oxlint-plugin-vue-sfc 0.1.0

package/rules/no-template-shadow.mjs

@@ -0,0 +1,108 @@
+import { NODE_ELEMENT, PROP_DIRECTIVE, parseSfc, reportAtFileOffset } from "../utils/vue-sfc.mjs";
+import {
+    bindingsWithOffsets,
+    declaredAlias,
+    scriptTopLevelNames,
+} from "../utils/vue-bindings.mjs";
+
+/**
+ * Replacement for `vue/no-template-shadow` (no native oxlint equivalent — oxc#15761).
+ *
+ * A `v-for` alias or `v-slot` binding that reuses a name already in scope hides the outer one for
+ * the whole subtree. `<ul v-for="row in rows"><li v-for="row in row.kids">` reads as if the inner
+ * loop iterates the outer row, and it does — once. After that every `row` in the subtree means
+ * the inner one, so a later reference to the outer row silently resolves to the wrong value.
+ * Renaming is free; debugging this is not.
+ *
+ * This is the plugin's first CORRELATION rule: it needs both halves of the SFC. The template side
+ * comes from `parseSfc` as usual, and the script side from oxlint's own `Program(node)` AST, whose
+ * top-level bindings are exactly what `<script setup>` exposes to the template. A template alias
+ * is reported when it collides with EITHER an enclosing template binding or a script binding —
+ * both confirmed against eslint-plugin-vue.
+ *
+ * Scoping detail that matters: only ANCESTOR template bindings shadow. Two sibling subtrees may
+ * each bind `item` without conflict, which is why this walks with an explicit scope stack rather
+ * than using the flat `walkTemplate` helper the other rules share.
+ */
+
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "disallow variable declarations from shadowing variables declared in the outer scope",
+            recommended: true,
+        },
+        schema: [],
+        messages: { m: "" },
+    },
+    create(context) {
+        if (!context.filename.endsWith(".vue")) {
+            return {};
+        }
+        return {
+            Program(program) {
+                const entry = parseSfc(context.filename);
+                const ast = entry.descriptor.template?.ast;
+                if (!ast) {
+                    return;
+                }
+                const scriptNames = scriptTopLevelNames(program);
+
+                /**
+                 * @param node current template node
+                 * @param outer Set of names visible from ancestors (template aliases only;
+                 *        script names are checked separately so they are never "shadowed away")
+                 */
+                const visit = (node, outer) => {
+                    if (!node) {
+                        return;
+                    }
+                    let scope = outer;
+                    if (node.type === NODE_ELEMENT) {
+                        const declared = [];
+                        for (const prop of node.props ?? []) {
+                            if (prop.type !== PROP_DIRECTIVE) {
+                                continue;
+                            }
+                            const alias = declaredAlias(prop);
+                            if (!alias) {
+                                continue;
+                            }
+                            for (const binding of bindingsWithOffsets(alias.text)) {
+                                const collides =
+                                    outer.has(binding.name) || scriptNames.has(binding.name);
+                                if (collides) {
+                                    const start =
+                                        prop.exp.loc.start.offset + alias.offset + binding.offset;
+                                    reportAtFileOffset(
+                                        context,
+                                        entry,
+                                        start,
+                                        start + binding.name.length,
+                                        `\`${binding.name}\` shadows a ${outer.has(binding.name) ? "variable declared by an enclosing template scope" : "binding from <script>"}. Every reference in this subtree resolves to the inner one — rename it.`,
+                                    );
+                                }
+                                declared.push(binding.name);
+                            }
+                        }
+                        if (declared.length) {
+                            scope = new Set(outer);
+                            for (const name of declared) {
+                                scope.add(name);
+                            }
+                        }
+                    }
+                    for (const child of node.children ?? []) {
+                        visit(child, scope);
+                    }
+                    // v-if chains keep branches off `children` in a transformed AST; harmless here.
+                    for (const branch of node.branches ?? []) {
+                        visit(branch, scope);
+                    }
+                };
+
+                visit(ast, new Set());
+            },
+        };
+    },
+};

package/rules/no-textarea-mustache.mjs

@@ -0,0 +1,63 @@
+import {
+    NODE_ELEMENT,
+    NODE_INTERPOLATION,
+    parseSfc,
+    reportAtFileOffset,
+    walkTemplate,
+} from "../utils/vue-sfc.mjs";
+
+/**
+ * Replacement for `vue/no-textarea-mustache` (no native oxlint equivalent — oxc#15761).
+ *
+ * `<textarea>{{ value }}</textarea>` does not work the way it reads. The interpolation
+ * sets the element's initial child text, but a textarea's displayed value comes from its
+ * `value` property, and Vue does not keep the two in sync — so the field stops updating
+ * as soon as `value` changes. `v-model` (or `:value`) is the working form.
+ *
+ * Scope: only interpolations that are DIRECT children of the `<textarea>`. A nested
+ * element cannot legally appear inside a textarea, so there is nothing deeper to check,
+ * and walking deeper would risk flagging malformed markup twice.
+ */
+
+export default {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "disallow mustaches in `<textarea>`",
+            recommended: true,
+        },
+        schema: [],
+        messages: { m: "" },
+    },
+    create(context) {
+        if (!context.filename.endsWith(".vue")) {
+            return {};
+        }
+        return {
+            Program() {
+                const entry = parseSfc(context.filename);
+                const ast = entry.descriptor.template?.ast;
+                if (!ast) {
+                    return;
+                }
+                walkTemplate(ast, (node) => {
+                    if (node.type !== NODE_ELEMENT || node.tag !== "textarea") {
+                        return;
+                    }
+                    for (const child of node.children ?? []) {
+                        if (child.type !== NODE_INTERPOLATION) {
+                            continue;
+                        }
+                        reportAtFileOffset(
+                            context,
+                            entry,
+                            child.loc.start.offset,
+                            child.loc.end.offset,
+                            "Interpolation inside `<textarea>` only sets the initial text and then stops tracking the value. Use `v-model` (or `:value`) instead.",
+                        );
+                    }
+                });
+            },
+        };
+    },
+};

package/rules/no-unused-components.mjs

@@ -0,0 +1,133 @@
+import { NODE_ELEMENT, PROP_DIRECTIVE, parseSfc, walkTemplate } from "../utils/vue-sfc.mjs";
+
+/**
+ * Replacement for `vue/no-unused-components` (no native oxlint equivalent — oxc#15761).
+ *
+ * IMPORTANT — this rule is currently INERT in this repo, by design of the upstream rule rather
+ * than by any choice here. `vue/no-unused-components` only inspects Options API registration
+ * (`export default { components: { … } }`); it says nothing about `<script setup>`, where an
+ * unused component import is caught by `@typescript-eslint/no-unused-vars` instead. This repo has
+ * **zero** SFCs with a `components:` block and **zero** non-`setup` `<script>` blocks, so upstream
+ * reports nothing here and neither does this port — verified both ways.
+ *
+ * It is ported anyway, rather than dropped, so the check does not silently disappear the moment
+ * someone adds an Options API component. That does mean its correctness rests on synthetic probes
+ * matched against eslint-plugin-vue, NOT on the 1581-SFC corpus — the corpus cannot exercise a
+ * rule whose trigger does not occur. Recorded in OXLINT_MIGRATION.md.
+ *
+ * Semantics confirmed against upstream:
+ * - Registration is matched case-insensitively across naming styles: `<used />` and `<used-two />`
+ *   satisfy `Used` and `UsedTwo`, because Vue resolves kebab-case to the PascalCase registration.
+ * - `ignoreWhenBindingPresent` defaults to true: if the template contains ANY
+ *   `<component :is="binding">`, the rule suppresses itself entirely, since the binding could
+ *   resolve to any registered component. A static `is="Foo"` does not suppress.
+ * - The report anchors on the registration property in the script, not on anything in the template.
+ */
+
+/** `UsedTwo` / `used-two` / `used_two` all normalize to `usedtwo`. */
+function normalizeName(name) {
+    return name.replace(/[-_]/g, "").toLowerCase();
+}
+
+/** The `components: { … }` object expression from an Options API default export, or null. */
+function findComponentsObject(program) {
+    let found = null;
+    const inspectObject = (object) => {
+        for (const property of object.properties ?? []) {
+            const key = property.key;
+            const name = key?.name ?? key?.value;
+            if (name === "components" && property.value?.type === "ObjectExpression") {
+                found = property.value;
+            }
+        }
+    };
+    for (const statement of program?.body ?? []) {
+        if (statement.type !== "ExportDefaultDeclaration") {
+            continue;
+        }
+        const declaration = statement.declaration;
+        if (declaration?.type === "ObjectExpression") {
+            inspectObject(declaration);
+        } else if (
+            declaration?.type === "CallExpression" &&
+            declaration.arguments?.[0]?.type === "ObjectExpression"
+        ) {
+            // `export default defineComponent({ … })`
+            inspectObject(declaration.arguments[0]);
+        }
+    }
+    return found;
+}
+
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "disallow registering components that are not used inside templates",
+            recommended: true,
+        },
+        schema: [],
+        messages: {
+            unusedComponent:
+                'The "{{name}}" component is registered but never used in the template. Remove the registration, or use the component.',
+        },
+    },
+    create(context) {
+        if (!context.filename.endsWith(".vue")) {
+            return {};
+        }
+        return {
+            Program(program) {
+                const componentsObject = findComponentsObject(program);
+                if (!componentsObject) {
+                    return;
+                }
+                const entry = parseSfc(context.filename);
+                const ast = entry.descriptor.template?.ast;
+                if (!ast) {
+                    return;
+                }
+
+                const usedTags = new Set();
+                let hasDynamicIs = false;
+                walkTemplate(ast, (node) => {
+                    if (node.type !== NODE_ELEMENT) {
+                        return;
+                    }
+                    usedTags.add(normalizeName(node.tag));
+                    if (node.tag !== "component") {
+                        return;
+                    }
+                    for (const prop of node.props ?? []) {
+                        const isBoundIs =
+                            prop.type === PROP_DIRECTIVE &&
+                            prop.name === "bind" &&
+                            prop.arg?.content === "is";
+                        if (isBoundIs) {
+                            hasDynamicIs = true;
+                        }
+                    }
+                });
+                // A dynamic `:is` could resolve to any registration, so upstream stays quiet.
+                if (hasDynamicIs) {
+                    return;
+                }
+
+                for (const property of componentsObject.properties ?? []) {
+                    const name = property.key?.name ?? property.key?.value;
+                    if (typeof name !== "string") {
+                        continue;
+                    }
+                    if (usedTags.has(normalizeName(name))) {
+                        continue;
+                    }
+                    context.report({
+                        node: property,
+                        messageId: "unusedComponent",
+                        data: { name },
+                    });
+                }
+            },
+        };
+    },
+};

package/rules/no-unused-vars.mjs

@@ -0,0 +1,167 @@
+import {
+    NODE_ELEMENT,
+    NODE_INTERPOLATION,
+    PROP_DIRECTIVE,
+    parseSfc,
+    reportAtFileOffset,
+    walkTemplate,
+} from "../utils/vue-sfc.mjs";
+import {
+    bindingsWithOffsets,
+    declaredAlias,
+    positionalGroups,
+} from "../utils/vue-bindings.mjs";
+
+/**
+ * Replacement for `vue/no-unused-vars` (no native oxlint equivalent — oxc#15761).
+ *
+ * Note this is the TEMPLATE rule, not `@typescript-eslint/no-unused-vars`: it flags variables
+ * introduced BY the template — `v-for` aliases and `v-slot` destructuring — that the template
+ * then never reads. An unused alias is usually a leftover from a refactor, and an unused slot
+ * prop often means the consumer is reading the wrong name and silently rendering nothing.
+ *
+ * Semantics confirmed against eslint-plugin-vue case by case:
+ * - `v-for="item in items"` with no use of `item` → reported, anchored on `item` itself.
+ * - `v-for` aliases are POSITIONAL — `(value, key, index)` — so upstream applies `after-used`
+ *   logic to them: an unused alias BEFORE a used one is unavoidable and is not reported.
+ *   `v-for="(_, index) in items"` with `index` used is therefore clean, while
+ *   `v-for="(item, i)"` with only `item` used does report `i`. Getting this wrong produced 5
+ *   false positives here, all of the `(_, index)` shape.
+ * - `v-slot`/`#name="{ a, b }"` destructuring is NOT positional, so every unused binding is
+ *   reported regardless of order (confirmed: `{ a, b }` with only `b` used reports `a`).
+ * - `_` is NOT exempt. eslint-plugin-vue has an `ignorePattern` option but its default ignores
+ *   nothing, and our ESLint config never set one — so `v-for="_ in items"` IS reported, and
+ *   adding an underscore escape hatch here would silently diverge.
+ * - A use anywhere in the element's subtree counts, including inside attributes (`:key="o.id"`)
+ *   and nested children.
+ *
+ * Binding extraction lives in utils/vue-bindings.mjs (shared with vue-no-template-shadow) and is
+ * a positioned scan rather than a full pattern parse. Usage detection here is a word-boundary
+ * scan over the subtree's expression sources, so a name that appears only inside a string
+ * literal counts as used. Both approximations fail toward FALSE NEGATIVES (a missed unused
+ * variable), never toward reporting a variable that is genuinely used.
+ */
+
+/** Concatenated expression sources inside `element`'s subtree, excluding `skip`. */
+function subtreeExpressionText(element, skip) {
+    const parts = [];
+    walkTemplate(element, (node) => {
+        if (node.type === NODE_INTERPOLATION && node.content?.content) {
+            parts.push(node.content.content);
+            return;
+        }
+        if (node.type !== NODE_ELEMENT) {
+            return;
+        }
+        for (const prop of node.props ?? []) {
+            if (prop.type !== PROP_DIRECTIVE) {
+                continue;
+            }
+            if (prop.exp?.content && prop.exp !== skip) {
+                parts.push(prop.exp.content);
+            }
+            // A dynamic argument (`:[key]`, `@[evt]`) reads a binding too.
+            if (prop.arg?.content && prop.arg.isStatic === false) {
+                parts.push(prop.arg.content);
+            }
+        }
+    });
+    return parts.join("\n");
+}
+
+function usesName(text, name) {
+    return new RegExp(`\\b${name}\\b`).test(text);
+}
+
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "disallow unused variable definitions of v-for directives or scope attributes",
+            recommended: true,
+        },
+        schema: [],
+        messages: { m: "" },
+    },
+    create(context) {
+        if (!context.filename.endsWith(".vue")) {
+            return {};
+        }
+        return {
+            Program() {
+                const entry = parseSfc(context.filename);
+                const ast = entry.descriptor.template?.ast;
+                if (!ast) {
+                    return;
+                }
+                walkTemplate(ast, (node) => {
+                    if (node.type !== NODE_ELEMENT) {
+                        return;
+                    }
+                    for (const prop of node.props ?? []) {
+                        if (prop.type !== PROP_DIRECTIVE || !prop.exp?.content) {
+                            continue;
+                        }
+                        const alias = declaredAlias(prop);
+                        if (!alias) {
+                            continue;
+                        }
+                        const usage = subtreeExpressionText(node, prop.exp);
+                        // For `v-for`, the right-hand side is evaluated in the OUTER scope, so it
+                        // is not a use of the alias — but it lives in the same expression node,
+                        // which `skip` removed wholesale. Add it back so `v-for="a in a"` and
+                        // similar do not read as unused.
+                        const isFor = prop.name === "for";
+                        const rhs = isFor ? prop.exp.content.slice(alias.text.length) : "";
+                        const haystack = `${usage}\n${rhs}`;
+                        const report = (binding, groupOffset) => {
+                            const start =
+                                prop.exp.loc.start.offset +
+                                alias.offset +
+                                groupOffset +
+                                binding.offset;
+                            reportAtFileOffset(
+                                context,
+                                entry,
+                                start,
+                                start + binding.name.length,
+                                `\`${binding.name}\` is defined by this ${isFor ? "v-for" : "v-slot"} but never used in the template.`,
+                            );
+                        };
+
+                        if (!isFor) {
+                            // v-slot destructuring is not positional: report every unused name.
+                            for (const binding of bindingsWithOffsets(alias.text)) {
+                                if (!usesName(haystack, binding.name)) {
+                                    report(binding, 0);
+                                }
+                            }
+                            continue;
+                        }
+
+                        // v-for: positional, so apply `after-used` — only groups AFTER the last
+                        // group containing a used binding can be reported.
+                        const groups = positionalGroups(alias.text).map((group) => ({
+                            ...group,
+                            bindings: bindingsWithOffsets(group.text),
+                        }));
+                        let lastUsed = -1;
+                        groups.forEach((group, index) => {
+                            if (group.bindings.some((b) => usesName(haystack, b.name))) {
+                                lastUsed = index;
+                            }
+                        });
+                        for (let index = lastUsed + 1; index < groups.length; index += 1) {
+                            const group = groups[index];
+                            for (const binding of group.bindings) {
+                                if (!usesName(haystack, binding.name)) {
+                                    report(binding, group.offset);
+                                }
+                            }
+                        }
+                    }
+                });
+            },
+        };
+    },
+};

package/rules/no-use-v-if-with-v-for.mjs

@@ -0,0 +1,69 @@
+import {
+    NODE_ELEMENT,
+    findDirective,
+    parseSfc,
+    reportAtFileOffset,
+    walkTemplate,
+} from "../utils/vue-sfc.mjs";
+
+/**
+ * Replacement for `vue/no-use-v-if-with-v-for` (no native oxlint equivalent — oxc#15761).
+ *
+ * `v-if` and `v-for` on the SAME element: in Vue 3 `v-if` has the higher priority, so it is
+ * evaluated BEFORE the loop variable exists. `<li v-for="u in users" v-if="u.active">` does
+ * not filter the list — it throws or silently reads `undefined`, because `u` is not in scope
+ * when the condition runs. (Vue 2 had the opposite precedence, which is why this pattern
+ * survives in migrated code and reads as if it works.)
+ *
+ * The fix is either a computed filtered list, or moving `v-if` to a wrapping `<template>`.
+ *
+ * Reported unconditionally when both are present, matching eslint-plugin-vue's default
+ * (`allowUsingIterationVar: false`). The option that permits it exists for Vue 2 semantics;
+ * on Vue 3 the pattern is broken regardless of whether the condition touches the iteration
+ * variable, so there is nothing to allow.
+ */
+
+export default {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "disallow use of `v-if` on the same element as `v-for`",
+            recommended: true,
+        },
+        schema: [],
+        messages: { m: "" },
+    },
+    create(context) {
+        if (!context.filename.endsWith(".vue")) {
+            return {};
+        }
+        return {
+            Program() {
+                const entry = parseSfc(context.filename);
+                const ast = entry.descriptor.template?.ast;
+                if (!ast) {
+                    return;
+                }
+                walkTemplate(ast, (node) => {
+                    if (node.type !== NODE_ELEMENT) {
+                        return;
+                    }
+                    const vFor = findDirective(node, "for");
+                    const vIf = findDirective(node, "if");
+                    if (!vFor || !vIf) {
+                        return;
+                    }
+                    // Anchor on the `v-if` DIRECTIVE, not its expression: that is where
+                    // eslint-plugin-vue points (verified at exact column parity).
+                    reportAtFileOffset(
+                        context,
+                        entry,
+                        vIf.loc.start.offset,
+                        vIf.loc.end.offset,
+                        `\`v-if\` on the same element as \`v-for\` runs BEFORE the loop variable exists (v-if has higher priority in Vue 3), so this does not filter the list. Use a computed filtered list, or move the \`v-if\` to a wrapping <template>.`,
+                    );
+                });
+            },
+        };
+    },
+};

package/rules/no-useless-template-attributes.mjs

@@ -0,0 +1,98 @@
+import {
+    NODE_ELEMENT,
+    PROP_ATTRIBUTE,
+    PROP_DIRECTIVE,
+    parseSfc,
+    reportAtFileOffset,
+    walkTemplate,
+} from "../utils/vue-sfc.mjs";
+
+/**
+ * Replacement for `vue/no-useless-template-attributes` (no native oxlint equivalent — oxc#15761).
+ *
+ * `<template>` is not rendered, so most attributes on it go nowhere. `<template v-if="x"
+ * class="row">` looks like it styles the row; the class is silently dropped and the author is
+ * left debugging CSS that was never applied.
+ *
+ * The attributes that DO have meaning on a `<template>`:
+ * - the structural directives themselves: `v-if`, `v-else-if`, `v-else`, `v-for`, `v-slot`
+ *   (`#name`), and `v-pre`.
+ * - `key`, but only together with `v-for` — that is the Vue 3 iteration key, required by
+ *   vue-require-v-for-key. A `key` WITHOUT `v-for` is handled by vue-no-template-key, so it
+ *   is left alone here to avoid two rules reporting the same token.
+ *
+ * Everything else — static attributes, `v-bind`, `v-on`, `v-model`, `v-show` — is reported.
+ * A lone `<template>` with no directive at all is vue-no-lone-template's finding, not this
+ * rule's, so this rule only speaks when the template has at least one meaningful directive.
+ */
+
+const MEANINGFUL_DIRECTIVES = new Set(["if", "else-if", "else", "for", "slot", "pre"]);
+
+function isKeyProp(prop) {
+    if (prop.type === PROP_ATTRIBUTE) {
+        return prop.name === "key";
+    }
+    return (
+        prop.name === "bind" &&
+        prop.arg?.type === 4 /* SIMPLE_EXPRESSION */ &&
+        prop.arg.content === "key"
+    );
+}
+
+export default {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "disallow useless attribute on `<template>`",
+            recommended: true,
+        },
+        schema: [],
+        messages: { m: "" },
+    },
+    create(context) {
+        if (!context.filename.endsWith(".vue")) {
+            return {};
+        }
+        return {
+            Program() {
+                const entry = parseSfc(context.filename);
+                const ast = entry.descriptor.template?.ast;
+                if (!ast) {
+                    return;
+                }
+                walkTemplate(ast, (node) => {
+                    if (node.type !== NODE_ELEMENT || node.tag !== "template") {
+                        return;
+                    }
+                    const props = node.props ?? [];
+                    const structural = props.filter(
+                        (prop) =>
+                            prop.type === PROP_DIRECTIVE && MEANINGFUL_DIRECTIVES.has(prop.name),
+                    );
+                    // No structural directive at all → vue-no-lone-template's finding.
+                    if (!structural.length) {
+                        return;
+                    }
+                    for (const prop of props) {
+                        if (structural.includes(prop)) {
+                            continue;
+                        }
+                        // `key` is meaningful with v-for; without it, vue-no-template-key owns it.
+                        if (isKeyProp(prop)) {
+                            continue;
+                        }
+                        const label =
+                            prop.type === PROP_ATTRIBUTE ? prop.name : `v-${prop.name}`;
+                        reportAtFileOffset(
+                            context,
+                            entry,
+                            prop.loc.start.offset,
+                            prop.loc.end.offset,
+                            `\`${label}\` has no effect on \`<template>\` — the element is not rendered, so the attribute is silently dropped. Move it to the child element you meant to target.`,
+                        );
+                    }
+                });
+            },
+        };
+    },
+};