feat(analyze/html/vue): add useVueVForKey (#8587)

<!--
  IMPORTANT!!
  If you generated this PR with the help of any AI assistance, please disclose it in the PR.
  https://github.com/biomejs/biome/blob/main/CONTRIBUTING.md#ai-assistance-notice
-->

<!--
	Thanks for submitting a Pull Request! We appreciate you spending the time to work on these changes.
	Please provide enough information so that others can review your PR.
	Once created, your PR will be automatically labeled according to changed files.
	Learn more about contributing: https://github.com/biomejs/biome/blob/main/CONTRIBUTING.md
-->

## Summary

<!-- Explain the **motivation** for making this change. What existing problem does the pull request solve?-->
This adds useVueVForKey, a port of https://eslint.vuejs.org/rules/require-v-for-key.html

The first draft was written by AI, but I effectively rewrote the whole thing myself.

<!-- Link any relevant issues if necessary or include a transcript of any Discord discussion. -->

<!-- If you create a user-facing change, please write a changeset: https://github.com/biomejs/biome/blob/main/CONTRIBUTING.md#writing-a-changeset (your changeset is often a good starting point for this summary as well) -->

## Test Plan

<!-- What demonstrates that your implementation is correct? -->
snapshots

## Docs

<!-- If you're submitting a new rule or action (or an option for them), the documentation is part of the code. Make sure rules and actions have example usages, and that all options are documented. -->

<!-- For other features, please submit a documentation PR to the `next` branch of our website: https://github.com/biomejs/website/. Link the PR here once it's ready. -->

Author: dyc3

.changeset/add-v-for-key-rule.md

@@ -0,0 +1,17 @@
+---
+"@biomejs/biome": patch
+---
+
+Added the rule [`useVueVForKey`](https://biomejs.dev/linter/rules/use-vue-v-for-key/), which enforces that any element using `v-for` also specifies a `key`.
+
+**Invalid**
+
+```vue
+<li v-for="item in items">{{ item }}</li>
+```
+
+**Valid**
+
+```vue
+<li v-for="item in items" :key="item.id">{{ item }}</li>
+```

crates/biome_configuration/src/analyzer/linter/rules.rs

@@ -10,6 +10,7 @@ pub mod no_vue_v_if_with_v_for;
 pub mod use_vue_consistent_v_bind_style;
 pub mod use_vue_consistent_v_on_style;
 pub mod use_vue_hyphenated_attributes;
+pub mod use_vue_v_for_key;
 pub mod use_vue_valid_template_root;
 pub mod use_vue_valid_v_bind;
 pub mod use_vue_valid_v_cloak;
@@ -21,4 +22,4 @@ pub mod use_vue_valid_v_on;
 pub mod use_vue_valid_v_once;
 pub mod use_vue_valid_v_pre;
 pub mod use_vue_valid_v_text;
-declare_lint_group! { pub Nursery { name : "nursery" , rules : [self :: no_ambiguous_anchor_text :: NoAmbiguousAnchorText , self :: no_script_url :: NoScriptUrl , self :: no_sync_scripts :: NoSyncScripts , self :: no_vue_v_if_with_v_for :: NoVueVIfWithVFor , self :: use_vue_consistent_v_bind_style :: UseVueConsistentVBindStyle , self :: use_vue_consistent_v_on_style :: UseVueConsistentVOnStyle , self :: use_vue_hyphenated_attributes :: UseVueHyphenatedAttributes , self :: use_vue_valid_template_root :: UseVueValidTemplateRoot , self :: use_vue_valid_v_bind :: UseVueValidVBind , self :: use_vue_valid_v_cloak :: UseVueValidVCloak , self :: use_vue_valid_v_else :: UseVueValidVElse , self :: use_vue_valid_v_else_if :: UseVueValidVElseIf , self :: use_vue_valid_v_html :: UseVueValidVHtml , self :: use_vue_valid_v_if :: UseVueValidVIf , self :: use_vue_valid_v_on :: UseVueValidVOn , self :: use_vue_valid_v_once :: UseVueValidVOnce , self :: use_vue_valid_v_pre :: UseVueValidVPre , self :: use_vue_valid_v_text :: UseVueValidVText ,] } }
+declare_lint_group! { pub Nursery { name : "nursery" , rules : [self :: no_ambiguous_anchor_text :: NoAmbiguousAnchorText , self :: no_script_url :: NoScriptUrl , self :: no_sync_scripts :: NoSyncScripts , self :: no_vue_v_if_with_v_for :: NoVueVIfWithVFor , self :: use_vue_consistent_v_bind_style :: UseVueConsistentVBindStyle , self :: use_vue_consistent_v_on_style :: UseVueConsistentVOnStyle , self :: use_vue_hyphenated_attributes :: UseVueHyphenatedAttributes , self :: use_vue_v_for_key :: UseVueVForKey , self :: use_vue_valid_template_root :: UseVueValidTemplateRoot , self :: use_vue_valid_v_bind :: UseVueValidVBind , self :: use_vue_valid_v_cloak :: UseVueValidVCloak , self :: use_vue_valid_v_else :: UseVueValidVElse , self :: use_vue_valid_v_else_if :: UseVueValidVElseIf , self :: use_vue_valid_v_html :: UseVueValidVHtml , self :: use_vue_valid_v_if :: UseVueValidVIf , self :: use_vue_valid_v_on :: UseVueValidVOn , self :: use_vue_valid_v_once :: UseVueValidVOnce , self :: use_vue_valid_v_pre :: UseVueValidVPre , self :: use_vue_valid_v_text :: UseVueValidVText ,] } }

crates/biome_diagnostics_categories/src/categories.rs

@@ -0,0 +1,121 @@
+use biome_analyze::{
+    Ast, Rule, RuleDiagnostic, RuleDomain, RuleSource, context::RuleContext, declare_lint_rule,
+};
+use biome_console::markup;
+use biome_html_syntax::{AnyVueDirective, HtmlAttributeList, VueDirectiveArgument};
+use biome_rowan::{AstNode, AstNodeList, TextRange};
+use biome_rule_options::use_vue_v_for_key::UseVueVForKeyOptions;
+
+declare_lint_rule! {
+    /// Enforce that elements using `v-for` also specify a unique `key`.
+    ///
+    /// When rendering lists with `v-for`, Vue relies on a `key` to track elements efficiently.
+    /// The `key` can be provided via longhand `v-bind:key` or shorthand `:key`. If you need to
+    /// animate the entrance/exit of an item in a list, the key should be a unique identifier for
+    /// each item in the list, and not the index of the item.
+    ///
+    /// For more information, see the Vue documentation on [list rendering](https://vuejs.org/guide/essentials/list#maintaining-state-with-key).
+    ///
+    /// ## Examples
+    ///
+    /// ### Invalid
+    ///
+    /// ```vue,expect_diagnostic
+    /// <li v-for="item in items">{{ item }}</li>
+    /// ```
+    ///
+    /// ### Valid
+    ///
+    /// ```vue
+    /// <li v-for="item in items" :key="item.id">{{ item }}</li>
+    /// ```
+    ///
+    /// ```vue
+    /// <li v-for="item in items" v-bind:key="item.id">{{ item }}</li>
+    /// ```
+    ///
+    pub UseVueVForKey {
+        version: "next",
+        name: "useVueVForKey",
+        language: "html",
+        recommended: true,
+        domains: &[RuleDomain::Vue],
+        sources: &[RuleSource::EslintVueJs("require-v-for-key").same()],
+    }
+}
+
+impl Rule for UseVueVForKey {
+    type Query = Ast<HtmlAttributeList>;
+    type State = TextRange;
+    type Signals = Option<Self::State>;
+    type Options = UseVueVForKeyOptions;
+
+    fn run(ctx: &RuleContext<Self>) -> Option<Self::State> {
+        let attrs = ctx.query();
+        let mut has_v_for = None;
+        let mut has_key = false;
+        for attr in attrs.iter() {
+            if let Some(dir_any) = attr.as_any_vue_directive() {
+                match dir_any {
+                    AnyVueDirective::VueDirective(dir) => {
+                        if dir.name_token().is_ok_and(|t| t.text_trimmed() == "v-for") {
+                            has_v_for = Some(dir.range());
+                        }
+                        if dir.name_token().is_ok_and(|t| t.text_trimmed() == "v-bind")
+                            && let Some(arg) = dir.arg()
+                            && is_v_bind_key_argument(&arg)
+                        {
+                            has_key = true;
+                        }
+                    }
+                    AnyVueDirective::VueVBindShorthandDirective(sh) => {
+                        if let Ok(arg) = sh.arg()
+                            && is_v_bind_key_argument(&arg)
+                        {
+                            has_key = true;
+                        }
+                    }
+                    _ => {}
+                }
+                if has_v_for.is_some() && has_key {
+                    // early exit if both found
+                    return None;
+                }
+            }
+        }
+        if let (Some(v_for_range), false) = (has_v_for, has_key) {
+            return Some(v_for_range);
+        }
+        None
+    }
+
+    fn diagnostic(_ctx: &RuleContext<Self>, state: &Self::State) -> Option<RuleDiagnostic> {
+        Some(
+            RuleDiagnostic::new(
+                rule_category!(),
+                state,
+                markup! {
+                    "This element is using "<Emphasis>"v-for"</Emphasis>", but the "<Emphasis>"key"</Emphasis>" attribute is missing."
+                },
+            )
+            .note(markup! {
+                "Using a unique key with "<Emphasis>"v-for"</Emphasis>" helps Vue optimize rendering and track elements efficiently. Failing to provide a key can result in unexpected behavior during updates. "<Hyperlink href="https://vuejs.org/guide/essentials/list#maintaining-state-with-key">"See the Vue docs for more info"</Hyperlink>"."
+            })
+            .note(markup! {
+                "Provide the key using "<Emphasis>":key=\"value\""</Emphasis>", and have the value be a unique value from the items you are iterating over. For example: `<li v-for=\"item in items\" :key=\"item.id\">{{ item }}</li>`"
+            }),
+        )
+    }
+}
+
+fn is_v_bind_key_argument(arg: &VueDirectiveArgument) -> bool {
+    let Ok(arg) = arg.arg() else {
+        return false;
+    };
+    let Some(static_arg) = arg.as_vue_static_argument() else {
+        return false;
+    };
+    static_arg
+        .name_token()
+        .is_ok_and(|name| name.text() == "key")
+}

crates/biome_html_analyze/src/lint/nursery.rs

@@ -0,0 +1,10 @@
+<!-- should generate diagnostics -->
+<ul>
+  <li v-for="item in items">{{ item }}</li>
+</ul>
+
+<div class="wrapper" v-for="(item, i) in items" data-id="foo"></div>
+
+<template v-for="item in items">
+  <li>{{ item }}</li>
+</template>

crates/biome_html_analyze/src/lint/nursery/use_vue_v_for_key.rs

@@ -0,0 +1,82 @@
+---
+source: crates/biome_html_analyze/tests/spec_tests.rs
+expression: invalid.vue
+---
+# Input
+```html
+<!-- should generate diagnostics -->
+<ul>
+  <li v-for="item in items">{{ item }}</li>
+</ul>
+
+<div class="wrapper" v-for="(item, i) in items" data-id="foo"></div>
+
+<template v-for="item in items">
+  <li>{{ item }}</li>
+</template>
+
+```
+
+# Diagnostics
+```
+invalid.vue:3:7 lint/nursery/useVueVForKey ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  i This element is using v-for, but the key attribute is missing.
+  
+    1 │ <!-- should generate diagnostics -->
+    2 │ <ul>
+  > 3 │   <li v-for="item in items">{{ item }}</li>
+      │       ^^^^^^^^^^^^^^^^^^^^^
+    4 │ </ul>
+    5 │ 
+  
+  i Using a unique key with v-for helps Vue optimize rendering and track elements efficiently. Failing to provide a key can result in unexpected behavior during updates. See the Vue docs for more info.
+  
+  i Provide the key using :key="value", and have the value be a unique value from the items you are iterating over. For example: `<li v-for="item in items" :key="item.id">{{ item }}</li>`
+  
+  i This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
+  
+
+```
+
+```
+invalid.vue:6:22 lint/nursery/useVueVForKey ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  i This element is using v-for, but the key attribute is missing.
+  
+    4 │ </ul>
+    5 │ 
+  > 6 │ <div class="wrapper" v-for="(item, i) in items" data-id="foo"></div>
+      │                      ^^^^^^^^^^^^^^^^^^^^^^^^^^
+    7 │ 
+    8 │ <template v-for="item in items">
+  
+  i Using a unique key with v-for helps Vue optimize rendering and track elements efficiently. Failing to provide a key can result in unexpected behavior during updates. See the Vue docs for more info.
+  
+  i Provide the key using :key="value", and have the value be a unique value from the items you are iterating over. For example: `<li v-for="item in items" :key="item.id">{{ item }}</li>`
+  
+  i This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
+  
+
+```
+
+```
+invalid.vue:8:11 lint/nursery/useVueVForKey ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  i This element is using v-for, but the key attribute is missing.
+  
+     6 │ <div class="wrapper" v-for="(item, i) in items" data-id="foo"></div>
+     7 │ 
+   > 8 │ <template v-for="item in items">
+       │           ^^^^^^^^^^^^^^^^^^^^^
+     9 │   <li>{{ item }}</li>
+    10 │ </template>
+  
+  i Using a unique key with v-for helps Vue optimize rendering and track elements efficiently. Failing to provide a key can result in unexpected behavior during updates. See the Vue docs for more info.
+  
+  i Provide the key using :key="value", and have the value be a unique value from the items you are iterating over. For example: `<li v-for="item in items" :key="item.id">{{ item }}</li>`
+  
+  i This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
+  
+
+```

crates/biome_html_analyze/tests/specs/nursery/useVueVForKey/invalid.vue

@@ -0,0 +1,10 @@
+<!-- should not generate diagnostics -->
+<ul>
+  <li v-for="item in items" :key="item.id">{{ item }}</li>
+</ul>
+
+<ul>
+  <li v-for="item in items" v-bind:key="item.id">{{ item }}</li>
+</ul>
+
+<div v-for="(item, i) in items" :key="i"></div>

crates/biome_html_analyze/tests/specs/nursery/useVueVForKey/invalid.vue.snap

@@ -0,0 +1,18 @@
+---
+source: crates/biome_html_analyze/tests/spec_tests.rs
+expression: valid.vue
+---
+# Input
+```html
+<!-- should not generate diagnostics -->
+<ul>
+  <li v-for="item in items" :key="item.id">{{ item }}</li>
+</ul>
+
+<ul>
+  <li v-for="item in items" v-bind:key="item.id">{{ item }}</li>
+</ul>
+
+<div v-for="(item, i) in items" :key="i"></div>
+
+```

crates/biome_html_analyze/tests/specs/nursery/useVueVForKey/valid.vue

@@ -404,6 +404,7 @@ pub mod use_vue_consistent_v_on_style;
 pub mod use_vue_define_macros_order;
 pub mod use_vue_hyphenated_attributes;
 pub mod use_vue_multi_word_component_names;
+pub mod use_vue_v_for_key;
 pub mod use_vue_valid_template_root;
 pub mod use_vue_valid_v_bind;
 pub mod use_vue_valid_v_cloak;