Require key for conditionally rendered repeated components

docs/rules/index.md

@@ -276,6 +276,7 @@ For example:
 | [vue/sort-keys](./sort-keys.md) | enforce sort-keys in a manner that is compatible with order-in-components |  | :hammer: |
 | [vue/static-class-names-order](./static-class-names-order.md) | enforce static class names order | :wrench: | :hammer: |
 | [vue/v-for-delimiter-style](./v-for-delimiter-style.md) | enforce `v-for` directive's delimiter style | :wrench: | :lipstick: |
+| [vue/v-if-else-key](./v-if-else-key.md) | require key attribute for conditionally rendered repeated components | :wrench: | :warning: |
 | [vue/v-on-handler-style](./v-on-handler-style.md) | enforce writing style for handlers in `v-on` directives | :wrench: | :hammer: |
 | [vue/valid-define-options](./valid-define-options.md) | enforce valid `defineOptions` compiler macro |  | :warning: |
 

docs/rules/v-if-else-key.md

@@ -0,0 +1,49 @@
+---
+pageClass: rule-details
+sidebarDepth: 0
+title: vue/v-if-else-key
+description: require key attribute for conditionally rendered repeated components
+---
+# vue/v-if-else-key
+
+> require key attribute for conditionally rendered repeated components
+
+- :exclamation: <badge text="This rule has not been released yet." vertical="middle" type="error"> ***This rule has not been released yet.*** </badge>
+- :wrench: The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#fixing-problems) can automatically fix some of the problems reported by this rule.
+
+## :book: Rule Details
+
+This rule checks for components that are both repeated and conditionally rendered within the same scope. If such a component is found, the rule then checks for the presence of a 'key' directive. If the 'key' directive is missing, the rule issues a warning and offers a fix.
+
+This rule is not required in Vue 3, as the key is automatically assigned to the elements.
+
+<eslint-code-block fix :rules="{'vue/v-if-else-key': ['error']}">
+
+```vue
+<template>
+  <!-- ✓ GOOD -->
+  <my-component v-if="condition1" :key="one" />
+  <my-component v-else-if="condition2" :key="two" />
+  <my-component v-else :key="three" />
+
+  <!-- ✗ BAD -->
+  <my-component v-if="condition1" />
+  <my-component v-else-if="condition2" />
+  <my-component v-else />
+</template>
+```
+
+</eslint-code-block>
+
+## :wrench: Options
+
+Nothing.
+
+## :books: Further Reading
+
+- [Guide (for v2) - v-if without key](https://v2.vuejs.org/v2/style-guide/#v-if-v-else-if-v-else-without-key-use-with-caution)
+
+## :mag: Implementation
+
+- [Rule source](https://github.com/vuejs/eslint-plugin-vue/blob/master/lib/rules/v-if-else-key.js)
+- [Test source](https://github.com/vuejs/eslint-plugin-vue/blob/master/tests/lib/rules/v-if-else-key.js)

lib/index.js

@@ -215,6 +215,7 @@ module.exports = {
     'use-v-on-exact': require('./rules/use-v-on-exact'),
     'v-bind-style': require('./rules/v-bind-style'),
     'v-for-delimiter-style': require('./rules/v-for-delimiter-style'),
+    'v-if-else-key': require('./rules/v-if-else-key'),
     'v-on-event-hyphenation': require('./rules/v-on-event-hyphenation'),
     'v-on-function-call': require('./rules/v-on-function-call'),
     'v-on-handler-style': require('./rules/v-on-handler-style'),

lib/rules/v-if-else-key.js

@@ -0,0 +1,311 @@
+/**
+ * @author Felipe Melendez
+ * See LICENSE file in root directory for full license.
+ */
+'use strict'
+
+// =============================================================================
+// Requirements
+// =============================================================================
+
+const utils = require('../utils')
+const casing = require('../utils/casing')
+
+// =============================================================================
+// Constants and Variables
+// =============================================================================
+
+/**
+ * Map to store conditionally rendered components and their respective conditional directives.
+ *
+ * A conditional family is a group of components that are conditionally rendered using v-if, v-else-if, and v-else.
+ * This data structure helps track and manage the relation of such components with one another.
+ *
+ * This map links a parent node to its associated conditional family, representing
+ * the relationship between different parts of a Vue conditional rendering chain
+ * (v-if, v-else-if, v-else). Each entry in the map associates a parent node
+ * (representing the scope of the conditional family) with an object that tracks
+ * the nodes for each part of the conditional chain:
+ *
+ *  - 'if': Represents the node associated with the 'v-if' directive.
+ *  - 'elseIf': An array representing nodes associated with any 'v-else-if' directives.
+ *  - 'else': Represents the node associated with the 'v-else' directive.
+ *
+ * This structure helps in understanding the relationship between conditional directives
+ * within a given scope and aids in linting scenarios where these relationships matter.
+ *
+ * @type {Map<VElement, { if: VElement | null, elseIf: VElement[], else: VElement | null }>}
+ */
+const conditionalFamilies = new Map()
+
+// =============================================================================
+// Rule Helpers
+// =============================================================================
+
+/**
+ * Checks for the presence of a 'key' attribute in the given Vue component node. If the
+ * 'key' attribute is missing and the node is part of a conditional family (like v-if, v-else-if, or v-else),
+ * a report is generated. The fix proposed adds a unique key based on the component's name
+ * and count, following the format '${kebabCase(componentName)}-${componentCount}', e.g., 'some-component-2'.
+ *
+ * @param {VElement} node - The Vue component node to check for a 'key' attribute.
+ * @param {RuleContext} context - The rule's context object, used for reporting.
+ * @param {string} componentName - Name of the component.
+ * @param {string} uniqueKey - A unique key for the repeated component, used for the fix.
+ */
+const checkForKey = (node, context, componentName, uniqueKey) => {
+  if (node.parent && node.parent.type === 'VElement') {
+    const conditionalFamily = conditionalFamilies.get(node.parent)
+
+    if (
+      conditionalFamily &&
+      (utils.hasDirective(node, 'bind', 'key') ||
+        utils.hasAttribute(node, 'key') ||
+        !hasConditionalDirective(node) ||
+        !isConditionalFamilyComplete(conditionalFamily))
+    ) {
+      return
+    }
+
+    context.report({
+      node: node.startTag,
+      loc: node.startTag.loc,
+      messageId: 'requireKey',
+      data: {
+        componentName
+      },
+      fix(fixer) {
+        const afterComponentNamePosition =
+          node.startTag.range[0] + componentName.length + 1
+        return fixer.insertTextBeforeRange(
+          [afterComponentNamePosition, afterComponentNamePosition],
+          ` key='${uniqueKey}'`
+        )
+      }
+    })
+  }
+}
+
+/**
+ * Checks for the presence of conditional directives such as 'v-if', 'v-else-if', or 'v-else' in the
+ * given Vue component node.
+ *
+ * @param {VElement} node - The node to check for conditional directives.
+ * @returns {boolean} Returns true if a conditional directive is found in the node or its parents,
+ *   false otherwise.
+ */
+const hasConditionalDirective = (node) =>
+  utils.hasDirective(node, 'if') ||
+  utils.hasDirective(node, 'else-if') ||
+  utils.hasDirective(node, 'else')
+
+/**
+ * Checks whether a conditional family (comprising of 'if', 'else-if', and 'else' conditions) is complete.
+ * A conditional family is considered complete if:
+ * 1. An 'if' condition is present.
+ * 2. All elements of the family (if, else, else-if) share the same rawName.
+ * 3. There exists either an 'else' condition or at least one 'else-if' condition.
+ *
+ * @param {{ if: VElement | null, elseIf: VElement[], else: VElement | null }} family - The conditional family object with 'if', 'else-if', and 'else' properties.
+ * @returns {boolean} True if the conditional family is complete based on the above criteria, false otherwise.
+ */
+const isConditionalFamilyComplete = (family) => {
+  if (!family || !family.if) {
+    return false
+  }
+  const familyComponentName = family.if.rawName
+  if (family.else && family.else.rawName !== familyComponentName) {
+    return false
+  }
+  if (family.elseIf.some((node) => node.rawName !== familyComponentName)) {
+    return false
+  }
+  return Boolean(family.else || family.elseIf.length > 0)
+}
+
+// =============================================================================
+// Rule Definition
+// =============================================================================
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'require key attribute for conditionally rendered repeated components',
+      categories: null,
+      recommended: false,
+      url: 'https://eslint.vuejs.org/rules/v-if-else-key.html'
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      requireKey:
+        "Conditionally rendered repeated component '{{componentName}}' expected to have a 'key' attribute."
+    }
+  },
+  /**
+   * Creates and returns a rule object which checks usage of repeated components. If a component
+   * is used more than once, it checks for the presence of a key.
+   *
+   * @param {RuleContext} context - The context object.
+   * @returns {Object} A dictionary of functions to be called on traversal of the template body by
+   *   the eslint parser.
+   */
+  create(context) {
+    /**
+     * Array of Maps to keep track of components and their usage counts along with the first
+     * node instance. Each Map represents a different scope level, and maps a component name to
+     * an object containing the count and a reference to the first node.
+     */
+    /** @type {Map<string, { count: number; firstNode: any }>[]} */
+    const componentUsageStack = [new Map()]
+
+    /**
+     * Checks if a given node represents a custom component without any conditional directives.
+     *
+     * @param {VElement} node - The AST node to check.
+     * @returns {boolean} True if the node represents a custom component without any conditional directives, false otherwise.
+     */
+    const isCustomComponentWithoutCondition = (node) =>
+      node.type === 'VElement' &&
+      utils.isCustomComponent(node) &&
+      !hasConditionalDirective(node)
+
+    /** Set of built-in Vue components that are exempt from the rule. */
+    /** @type {Set<string>} */
+    const exemptTags = new Set(['component', 'slot', 'template'])
+
+    /** Set to keep track of nodes we've pushed to the stack. */
+    /** @type {Set<any>} */
+    const pushedNodes = new Set()
+
+    /**
+     * Creates and returns an object representing a conditional family.
+     *
+     * @returns {{ if: VElement | null, elseIf: VElement[], else: VElement | null }}
+     */
+    const createConditionalFamily = () => ({
+      if: null,
+      elseIf: [],
+      else: null
+    })
+
+    return utils.defineTemplateBodyVisitor(context, {
+      /**
+       * Callback to be executed when a Vue element is traversed. This function checks if the
+       * Vue element is a component, increments the usage count of the component in the
+       * current scope, and checks for the key directive if the component is repeated.
+       *
+       * @param {VElement} node - The traversed Vue element.
+       */
+      VElement(node) {
+        if (exemptTags.has(node.rawName)) {
+          return
+        }
+
+        const condition =
+          utils.getDirective(node, 'if') ||
+          utils.getDirective(node, 'else-if') ||
+          utils.getDirective(node, 'else')
+
+        if (condition) {
+          const conditionType = condition.key.name.name
+
+          if (node.parent && node.parent.type === 'VElement') {
+            let conditionalFamily = conditionalFamilies.get(node.parent)
+
+            if (
+              !conditionalFamily ||
+              (conditionalFamily.if &&
+                conditionalFamily.if.rawName !== node.rawName)
+            ) {
+              conditionalFamily = createConditionalFamily()
+              conditionalFamilies.set(node.parent, conditionalFamily)
+            }
+
+            switch (conditionType) {
+              case 'if': {
+                conditionalFamily.if = node
+                break
+              }
+              case 'else-if': {
+                conditionalFamily.elseIf.push(node)
+                break
+              }
+              case 'else': {
+                conditionalFamily.else = node
+                break
+              }
+            }
+          }
+        }
+
+        if (isCustomComponentWithoutCondition(node)) {
+          componentUsageStack.push(new Map())
+          return
+        }
+
+        if (!utils.isCustomComponent(node)) {
+          return
+        }
+
+        const componentName = node.rawName
+        const currentScope = componentUsageStack[componentUsageStack.length - 1]
+        const usageInfo = currentScope.get(componentName) || {
+          count: 0,
+          firstNode: null
+        }
+
+        if (hasConditionalDirective(node)) {
+          // Store the first node if this is the first occurrence
+          if (usageInfo.count === 0) {
+            usageInfo.firstNode = node
+          }
+
+          if (usageInfo.count > 0) {
+            const uniqueKey = `${casing.kebabCase(componentName)}-${
+              usageInfo.count + 1
+            }`
+            checkForKey(node, context, componentName, uniqueKey)
+
+            // If this is the second occurrence, also apply a fix to the first occurrence
+            if (usageInfo.count === 1) {
+              const uniqueKeyForFirstInstance = `${casing.kebabCase(
+                componentName
+              )}-1`
+              checkForKey(
+                usageInfo.firstNode,
+                context,
+                componentName,
+                uniqueKeyForFirstInstance
+              )
+            }
+          }
+          usageInfo.count += 1
+          currentScope.set(componentName, usageInfo)
+        }
+        componentUsageStack.push(new Map())
+        pushedNodes.add(node)
+      },
+
+      'VElement:exit'(node) {
+        if (exemptTags.has(node.rawName)) {
+          return
+        }
+        if (isCustomComponentWithoutCondition(node)) {
+          componentUsageStack.pop()
+          return
+        }
+        if (!utils.isCustomComponent(node)) {
+          return
+        }
+        if (pushedNodes.has(node)) {
+          componentUsageStack.pop()
+          pushedNodes.delete(node)
+        }
+      }
+    })
+  }
+}