oxlint-plugin-vue-sfc 0.1.0

package/rules/require-v-for-key.mjs

@@ -0,0 +1,80 @@
+import {
+    NODE_ELEMENT,
+    findDirective,
+    findKeyProp,
+    parseSfc,
+    reportAtFileOffset,
+    walkTemplate,
+} from "../utils/vue-sfc.mjs";
+
+/**
+ * Replacement for `vue/require-v-for-key` (no native oxlint equivalent — oxlint's 46
+ * native vue rules are all script-side; every template-AST rule still lives in the
+ * ESLint fallback, see packages/eslint-config/libs/vue.mjs and oxc#15761).
+ *
+ * A `v-for` without a `key` makes Vue reuse DOM nodes by index, so component state
+ * (focus, input values, transition state) leaks across list items when the list is
+ * reordered or filtered. It is a correctness bug, not a style preference, which is
+ * why this ships as `error`.
+ *
+ * Vue 3 semantics, and the false-positive guards that matter here:
+ * - The key belongs on the element carrying `v-for`, INCLUDING `<template v-for>`.
+ * - For `<template v-for>` we also accept a key on every direct element child. That
+ *   is the Vue 2 idiom and still works in Vue 3, so flagging it would report working
+ *   code — and one false positive on a 1500-SFC codebase costs more trust than the
+ *   marginal rule strictness buys.
+ * - `findKeyProp` accepts both the static `key` attribute and `:key` / `v-bind:key`.
+ * - `<template v-for>` with no element children (text only) cannot carry a keyed
+ *   child, so it is judged on its own key alone.
+ */
+
+export default {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "require `v-bind:key` with `v-for` directives",
+            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 || !findDirective(node, "for")) {
+                        return;
+                    }
+                    if (findKeyProp(node)) {
+                        return;
+                    }
+                    // `<template v-for>`: a key on every direct element child is the Vue 2
+                    // idiom and still correct in Vue 3, so treat it as satisfied.
+                    if (node.tag === "template") {
+                        const elementChildren = (node.children ?? []).filter(
+                            (child) => child.type === NODE_ELEMENT,
+                        );
+                        if (elementChildren.length && elementChildren.every(findKeyProp)) {
+                            return;
+                        }
+                    }
+                    reportAtFileOffset(
+                        context,
+                        entry,
+                        node.loc.start.offset,
+                        node.loc.end.offset,
+                        `<${node.tag}> uses v-for without a :key. Vue reuses DOM nodes by index without one, so item state leaks when the list is reordered or filtered.`,
+                    );
+                });
+            },
+        };
+    },
+};

package/rules/require-valid-default-prop.mjs

@@ -0,0 +1,282 @@
+/**
+ * Replacement for `vue/require-valid-default-prop` (no native oxlint equivalent — oxc#15761).
+ *
+ * Two distinct bugs, both silent:
+ * 1. `{ type: Array, default: [] }` shares ONE array across every instance of the component.
+ *    Push to it in one place and it appears everywhere. Vue requires a factory (`default: () => []`)
+ *    precisely so each instance gets its own.
+ * 2. `{ type: String, default: 1 }` declares one type and defaults to another. Nothing complains
+ *    at runtime; the component just receives a number when nothing was passed.
+ *
+ * A SCRIPT rule — oxlint's own `Program(node)` AST, correct positions, no dependency on oxc#20501.
+ *
+ * Semantics confirmed against eslint-plugin-vue:
+ * - Array/Object defaults must be a factory function; `null` and `undefined` are accepted.
+ * - Primitives may ALSO use a factory (`{ type: String, default: () => "s" }` is accepted).
+ * - When the default IS a factory, its RETURNED expression is type-checked instead
+ *   (`{ type: Array, default: () => ({}) }` is reported).
+ * - A union `type: [String, Number]` is satisfied by a default matching ANY member.
+ * - A prop with no `type`, or no `default`, is never reported.
+ * - The report anchors on the default VALUE expression (or on the factory's returned expression).
+ *
+ * Deliberately conservative: any expression whose type cannot be determined statically — an
+ * identifier, a call, a conditional — is treated as UNKNOWN and never reported. A prop default
+ * pulled from a constant is extremely common and reporting it would be wrong, so this trades
+ * completeness for zero false positives.
+ */
+
+const NATIVE_TYPES = new Set([
+    "String",
+    "Number",
+    "Boolean",
+    "Array",
+    "Object",
+    "Function",
+    "Symbol",
+    "BigInt",
+    "Date",
+]);
+/** Types whose default MUST be produced by a factory, because the value would be shared. */
+const REFERENCE_TYPES = new Set(["Array", "Object"]);
+
+/** Declared prop types as a Set of native type names, or null when not statically known. */
+function declaredTypes(typeNode) {
+    if (!typeNode) {
+        return null;
+    }
+    if (typeNode.type === "Identifier" && NATIVE_TYPES.has(typeNode.name)) {
+        return new Set([typeNode.name]);
+    }
+    if (typeNode.type === "ArrayExpression") {
+        const names = new Set();
+        for (const element of typeNode.elements ?? []) {
+            if (element?.type === "Identifier" && NATIVE_TYPES.has(element.name)) {
+                names.add(element.name);
+            } else {
+                return null; // an unrecognised member makes the whole union unknown
+            }
+        }
+        return names.size ? names : null;
+    }
+    return null;
+}
+
+/**
+ * Strip `ParenthesizedExpression` wrappers. oxc-parser preserves them, so `() => ({})` has a
+ * parenthesized body — and upstream anchors its report on the INNER expression, not the paren.
+ */
+function unwrap(node) {
+    let current = node;
+    while (current?.type === "ParenthesizedExpression") {
+        current = current.expression;
+    }
+    return current;
+}
+
+/** The native type a value expression evaluates to, `"null"`, or null when unknown. */
+function inferType(input) {
+    const node = unwrap(input);
+    if (!node) {
+        return null;
+    }
+    switch (node.type) {
+        case "ArrayExpression":
+            return "Array";
+        case "ObjectExpression":
+            return "Object";
+        case "TemplateLiteral":
+            return "String";
+        case "ArrowFunctionExpression":
+        case "FunctionExpression":
+            return "Function";
+        case "Literal": {
+            if (node.value === null) {
+                return "null";
+            }
+            switch (typeof node.value) {
+                case "string":
+                    return "String";
+                case "number":
+                    return "Number";
+                case "boolean":
+                    return "Boolean";
+                default:
+                    return null;
+            }
+        }
+        case "UnaryExpression":
+            // `-1` is a number; `!x` a boolean. Only handle the unambiguous numeric case.
+            return node.operator === "-" || node.operator === "+"
+                ? inferType(node.argument)
+                : null;
+        case "Identifier":
+            return node.name === "undefined" ? "null" : null;
+        default:
+            return null;
+    }
+}
+
+/** The expression a concise/blocked arrow or function returns, or null when not determinable. */
+function factoryReturn(input) {
+    const node = unwrap(input);
+    if (node.type === "ArrowFunctionExpression" && node.body?.type !== "BlockStatement") {
+        return unwrap(node.body);
+    }
+    const body = node.body?.body;
+    if (!Array.isArray(body) || body.length !== 1 || body[0].type !== "ReturnStatement") {
+        return null;
+    }
+    return body[0].argument ? unwrap(body[0].argument) : null;
+}
+
+/** Every `defineProps({ … })` / `props: { … }` object in the program. */
+function findPropsObjects(program) {
+    const objects = [];
+    const walk = (node) => {
+        if (!node || typeof node !== "object") {
+            return;
+        }
+        if (Array.isArray(node)) {
+            for (const item of node) {
+                walk(item);
+            }
+            return;
+        }
+        if (typeof node.type !== "string") {
+            return;
+        }
+        if (
+            node.type === "CallExpression" &&
+            node.callee?.type === "Identifier" &&
+            node.callee.name === "defineProps" &&
+            node.arguments?.[0]?.type === "ObjectExpression"
+        ) {
+            objects.push(node.arguments[0]);
+        }
+        if (
+            node.type === "Property" &&
+            (node.key?.name ?? node.key?.value) === "props" &&
+            node.value?.type === "ObjectExpression"
+        ) {
+            objects.push(node.value);
+        }
+        for (const key of Object.keys(node)) {
+            if (key === "parent" || key === "loc" || key === "range") {
+                continue;
+            }
+            walk(node[key]);
+        }
+    };
+    walk(program);
+    return objects;
+}
+
+const ARTICLE_NAMES = {
+    String: "a string",
+    Number: "a number",
+    Boolean: "a boolean",
+    Array: "an array",
+    Object: "an object",
+    Function: "a function",
+};
+
+export default {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "enforce props default values to be valid",
+            recommended: true,
+        },
+        schema: [],
+        messages: {
+            mustBeFactory:
+                "The default for the `{{name}}` prop is shared across every instance of this component. Use a factory: `default: () => …`.",
+            typeMismatch:
+                "The default for the `{{name}}` prop should be {{expected}} to match its declared type.",
+        },
+    },
+    create(context) {
+        return {
+            Program(program) {
+                for (const propsObject of findPropsObjects(program)) {
+                    for (const prop of propsObject.properties ?? []) {
+                        const name = prop.key?.name ?? prop.key?.value;
+                        if (typeof name !== "string" || prop.value?.type !== "ObjectExpression") {
+                            continue;
+                        }
+                        let typeNode = null;
+                        let defaultNode = null;
+                        for (const entry of prop.value.properties ?? []) {
+                            const key = entry.key?.name ?? entry.key?.value;
+                            if (key === "type") {
+                                typeNode = entry.value;
+                            } else if (key === "default") {
+                                defaultNode = entry.value;
+                            }
+                        }
+                        const expected = declaredTypes(typeNode);
+                        if (!expected || !defaultNode) {
+                            continue;
+                        }
+
+                        defaultNode = unwrap(defaultNode);
+                        const defaultType = inferType(defaultNode);
+                        // `null` / `undefined` defaults are always accepted.
+                        if (defaultType === "null") {
+                            continue;
+                        }
+
+                        // A factory: check what it RETURNS instead, unless Function is declared.
+                        if (defaultType === "Function" && !expected.has("Function")) {
+                            const returned = factoryReturn(defaultNode);
+                            const returnedType = inferType(returned);
+                            if (!returned || !returnedType || returnedType === "null") {
+                                continue; // not statically determinable — stay quiet
+                            }
+                            if (!expected.has(returnedType)) {
+                                context.report({
+                                    node: returned,
+                                    messageId: "typeMismatch",
+                                    data: {
+                                        name,
+                                        expected: [...expected]
+                                            .map((t) => ARTICLE_NAMES[t] ?? t)
+                                            .join(" or "),
+                                    },
+                                });
+                            }
+                            continue;
+                        }
+
+                        // A bare reference-type default is shared between instances.
+                        const needsFactory = [...expected].some((t) => REFERENCE_TYPES.has(t));
+                        if (needsFactory && defaultType && REFERENCE_TYPES.has(defaultType)) {
+                            context.report({
+                                node: defaultNode,
+                                messageId: "mustBeFactory",
+                                data: { name },
+                            });
+                            continue;
+                        }
+
+                        if (!defaultType) {
+                            continue; // unknown — never report
+                        }
+                        if (!expected.has(defaultType)) {
+                            context.report({
+                                node: defaultNode,
+                                messageId: "typeMismatch",
+                                data: {
+                                    name,
+                                    expected: [...expected]
+                                        .map((t) => ARTICLE_NAMES[t] ?? t)
+                                        .join(" or "),
+                                },
+                            });
+                        }
+                    }
+                }
+            },
+        };
+    },
+};

package/rules/this-in-template.mjs

@@ -0,0 +1,141 @@
+import { eachTemplateExpression, parseSfc, reportAtFileOffset } from "../utils/vue-sfc.mjs";
+
+/**
+ * Replacement for `vue/this-in-template` (no native oxlint equivalent — oxc#15761).
+ *
+ * Template expressions are already evaluated against the component instance, so `{{ this.x }}`
+ * is at best redundant. In `<script setup>` it is worse than redundant: there is no `this`
+ * bound the way an Options API component has one, so `this.x` reads from the wrong object (or
+ * `undefined`) while looking correct. It is a common artefact of pasting Options API code.
+ *
+ * Detection strips string literals before testing, which matters more than it sounds: a naive
+ * `\bthis\b` scan flags `:title="'use this instead'"` — user-facing copy containing the word
+ * "this" is common, and a rule that reports prose gets turned off. Template literals are
+ * stripped too, but their `${...}` substitutions are KEPT, since real `this` can hide there.
+ *
+ * Reduced scope vs eslint-plugin-vue: this is a lexical scan, not an AST walk, so it cannot
+ * tell `this.x` from a `this` inside a nested arrow function that legitimately rebinds it.
+ * In a template expression that distinction is vanishingly rare, and the failure mode is a
+ * false positive on `@click="() => this.x"` — which is itself the pattern the rule targets.
+ * Documented rather than silently approximated; see OXLINT_MIGRATION.md.
+ */
+
+/**
+ * Blank out the CONTENTS of string literals AND comments, preserving length so offsets stay
+ * valid. Template-literal `${...}` substitutions are preserved (real `this` can live there).
+ *
+ * Comments are not a hypothetical: this repo has a `v-if` whose multi-line `/* … *\/` comment
+ * explains tab behaviour in prose containing the word "this". Scanning it produced the rule's
+ * only corpus hit, and it was entirely spurious.
+ */
+function stripStringContents(source) {
+    const out = [...source];
+    let quote = null;
+    let depth = 0;
+    let comment = null; // "line" | "block" | null
+    for (let i = 0; i < out.length; i += 1) {
+        const ch = out[i];
+        if (comment === "line") {
+            out[i] = " ";
+            continue;
+        }
+        if (comment === "block") {
+            if (ch === "*" && out[i + 1] === "/") {
+                out[i] = " ";
+                out[i + 1] = " ";
+                i += 1;
+                comment = null;
+                continue;
+            }
+            out[i] = " ";
+            continue;
+        }
+        if (quote === null) {
+            if (ch === "/" && out[i + 1] === "/") {
+                comment = "line";
+                out[i] = " ";
+                continue;
+            }
+            if (ch === "/" && out[i + 1] === "*") {
+                comment = "block";
+                out[i] = " ";
+                out[i + 1] = " ";
+                i += 1;
+                continue;
+            }
+            if (ch === "'" || ch === '"' || ch === "`") {
+                quote = ch;
+            }
+            continue;
+        }
+        if (ch === "\\") {
+            // Blank the escape pair so `\'` cannot be mistaken for a terminator.
+            out[i] = " ";
+            if (i + 1 < out.length) {
+                out[i + 1] = " ";
+            }
+            i += 1;
+            continue;
+        }
+        if (quote === "`" && ch === "$" && out[i + 1] === "{") {
+            depth += 1;
+            i += 1;
+            continue;
+        }
+        if (depth > 0) {
+            if (ch === "}") {
+                depth -= 1;
+            }
+            continue; // inside ${...}: keep it intact
+        }
+        if (ch === quote) {
+            quote = null;
+            continue;
+        }
+        out[i] = " ";
+    }
+    return out.join("");
+}
+
+const THIS_RE = /\bthis\b/;
+
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "disallow usage of `this` in template",
+            recommended: false,
+        },
+        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;
+                }
+                eachTemplateExpression(ast, (expression) => {
+                    const source = expression.content ?? "";
+                    const match = THIS_RE.exec(stripStringContents(source));
+                    if (!match) {
+                        return;
+                    }
+                    const start = expression.loc.start.offset + match.index;
+                    reportAtFileOffset(
+                        context,
+                        entry,
+                        start,
+                        start + 4,
+                        "`this` is unnecessary in a template expression — bindings are already resolved against the component. Under `<script setup>` it does not refer to the setup state at all.",
+                    );
+                });
+            },
+        };
+    },
+};

package/rules/use-v-on-exact.mjs

@@ -0,0 +1,112 @@
+import {
+    NODE_ELEMENT,
+    PROP_DIRECTIVE,
+    parseSfc,
+    reportAtFileOffset,
+    walkTemplate,
+} from "../utils/vue-sfc.mjs";
+
+/**
+ * Replacement for `vue/use-v-on-exact` (no native oxlint equivalent — oxc#15761).
+ *
+ * `@click="save"` fires on a plain click AND on ctrl-click, because without `.exact` a handler
+ * ignores extra system modifiers. So pairing it with `@click.ctrl="saveAs"` means ctrl-click runs
+ * BOTH handlers — you get a save and a save-as from one gesture. The bare handler needs `.exact`
+ * to opt out.
+ *
+ * Semantics derived empirically from eslint-plugin-vue (confirmed case by case):
+ * - Only "system" modifiers create the conflict: `ctrl`, `shift`, `alt`, `meta`. Others
+ *   (`prevent`, `stop`, `once`, key names like `enter`, mouse buttons) do not, so
+ *   `@click` + `@click.prevent` is NOT reported.
+ * - The report lands on the handler that has NO system modifiers and no `.exact` — the one that
+ *   needs changing — not on the modified sibling.
+ * - Two handlers that BOTH carry system modifiers (`@click.ctrl` + `@click.shift`) are fine:
+ *   neither swallows the other.
+ * - `@click.ctrl.exact` still triggers a report on a bare `@click` sibling: `.exact` on the
+ *   modified handler does not rescue the unmodified one.
+ * - Grouping is per element and per STATIC event name; a dynamic `@[evt]` is skipped since its
+ *   name is not knowable.
+ */
+
+const SYSTEM_MODIFIERS = new Set(["ctrl", "shift", "alt", "meta"]);
+
+function modifierNames(prop) {
+    return (prop.modifiers ?? []).map((modifier) =>
+        typeof modifier === "string" ? modifier : (modifier?.content ?? ""),
+    );
+}
+
+export default {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "enforce usage of `exact` modifier on `v-on`",
+            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;
+                    }
+                    /** event name -> handlers on this element */
+                    const byEvent = new Map();
+                    for (const prop of node.props ?? []) {
+                        if (prop.type !== PROP_DIRECTIVE || prop.name !== "on") {
+                            continue;
+                        }
+                        const arg = prop.arg;
+                        if (
+                            !arg ||
+                            arg.type !== 4 /* SIMPLE_EXPRESSION */ ||
+                            arg.isStatic === false
+                        ) {
+                            continue;
+                        }
+                        const modifiers = modifierNames(prop);
+                        const handler = {
+                            prop,
+                            hasSystem: modifiers.some((m) => SYSTEM_MODIFIERS.has(m)),
+                            isExact: modifiers.includes("exact"),
+                        };
+                        const bucket = byEvent.get(arg.content);
+                        if (bucket) {
+                            bucket.push(handler);
+                        } else {
+                            byEvent.set(arg.content, [handler]);
+                        }
+                    }
+                    for (const [event, handlers] of byEvent) {
+                        if (handlers.length < 2 || !handlers.some((h) => h.hasSystem)) {
+                            continue;
+                        }
+                        for (const handler of handlers) {
+                            if (handler.hasSystem || handler.isExact) {
+                                continue;
+                            }
+                            reportAtFileOffset(
+                                context,
+                                entry,
+                                handler.prop.loc.start.offset,
+                                handler.prop.loc.end.offset,
+                                `This \`@${event}\` also fires when the modifier keys of its sibling handlers are held, so one gesture runs both. Add \`.exact\` to restrict it to ${event} with no modifiers.`,
+                            );
+                        }
+                    }
+                });
+            },
+        };
+    },
+};