oxlint-plugin-vue-sfc 0.1.0

package/rules/no-lone-template.mjs

@@ -0,0 +1,68 @@
+import {
+    NODE_ELEMENT,
+    PROP_DIRECTIVE,
+    parseSfc,
+    reportAtFileOffset,
+    walkTemplate,
+} from "../utils/vue-sfc.mjs";
+
+/**
+ * Replacement for `vue/no-lone-template` (no native oxlint equivalent — oxc#15761).
+ *
+ * `<template>` renders nothing itself; it exists to carry `v-if` / `v-for` / `v-slot` for a
+ * group of children. Without one of those it is a no-op wrapper — harmless at runtime, but
+ * it misleads the reader into thinking something is conditional or slotted, and it is usually
+ * the residue of deleting the directive that justified it.
+ *
+ * "Has a directive" is the test, not "has attributes": a static attribute on `<template>` is
+ * itself useless (that is vue-no-useless-template-attributes' job), so it does not rescue a
+ * lone template. Any directive counts — `v-if`, `v-for`, `v-slot`/`#name`, and also less
+ * common ones like `v-pre` — because each gives the element a reason to exist.
+ *
+ * The SFC's own `<template>` block is never flagged: `descriptor.template.ast` is a ROOT node
+ * (type 0), not an element, so the walk never sees it as a `<template>` element.
+ */
+
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "disallow unnecessary `<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;
+                }
+                walkTemplate(ast, (node) => {
+                    if (node.type !== NODE_ELEMENT || node.tag !== "template") {
+                        return;
+                    }
+                    const hasDirective = (node.props ?? []).some(
+                        (prop) => prop.type === PROP_DIRECTIVE,
+                    );
+                    if (hasDirective) {
+                        return;
+                    }
+                    reportAtFileOffset(
+                        context,
+                        entry,
+                        node.loc.start.offset,
+                        node.loc.end.offset,
+                        "`<template>` with no `v-if` / `v-for` / `v-slot` renders nothing and groups nothing. Remove the wrapper, or add the directive it was meant to carry.",
+                    );
+                });
+            },
+        };
+    },
+};

package/rules/no-mutating-props.mjs

@@ -0,0 +1,283 @@
+import {
+    NODE_ELEMENT,
+    NODE_INTERPOLATION,
+    PROP_DIRECTIVE,
+    parseSfc,
+    reportAtFileOffset,
+    walkTemplate,
+} from "../utils/vue-sfc.mjs";
+
+/**
+ * Replacement for `vue/no-mutating-props` (no native oxlint equivalent — oxc#15761).
+ *
+ * Props are the parent's state. Writing to one changes the child's copy until the parent next
+ * re-renders, at which point the value snaps back — so the bug shows up as a field that "won't
+ * stay changed", which is a miserable thing to debug. Vue warns at runtime for the direct case and
+ * says nothing at all for nested mutation (`props.obj.a = 1`).
+ *
+ * A CORRELATION rule covering BOTH halves: script assignments via the AST, and template mutations
+ * (`@click="props.x++"`, `v-model="props.x"`) via a lexical scan.
+ *
+ * Deliberately conservative, because a false positive on a prop read would be intolerable — the
+ * template side reports ONLY two unambiguous shapes:
+ * 1. `v-model` (or `v-model:arg`) whose expression is rooted at a prop. v-model IS an assignment,
+ *    so there is no ambiguity about intent.
+ * 2. An expression containing a prop root followed by an assignment or increment operator
+ *    (`=` not part of `==`/`===`/`!=`/`>=`/`<=`, or `++`/`--`/`+=`/`-=`/`*=`/`/=`/`%=`).
+ * Anything else — a read, a method call, a comparison — is never reported. String literals and
+ * comments are blanked before the scan so prose cannot trigger it.
+ *
+ * The script side is exact rather than lexical: it walks for `AssignmentExpression` and
+ * `UpdateExpression` whose target's ROOT object is the props variable or a destructured prop.
+ */
+
+const PROP_FACTORIES = new Set(["defineProps"]);
+const MUTATION_AFTER_ROOT = /^\s*(?:\.\s*[\w$]+|\[[^\]]*\])*\s*(?:\+\+|--|[+\-*/%]=|=(?!=))/;
+
+/** Blank string-literal and comment CONTENTS, preserving length so offsets stay valid. */
+function blankStringsAndComments(source) {
+    const out = [...source];
+    let quote = null;
+    let comment = 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 === "\\") {
+            out[i] = " ";
+            if (i + 1 < out.length) {
+                out[i + 1] = " ";
+            }
+            i += 1;
+            continue;
+        }
+        if (ch === quote) {
+            quote = null;
+            continue;
+        }
+        out[i] = " ";
+    }
+    return out.join("");
+}
+
+/** The props variable name and any destructured prop names. */
+function analyzeProps(program) {
+    let propsVar = null;
+    const destructured = new Set();
+    const isPropsCall = (node) => {
+        if (node?.type !== "CallExpression") {
+            return false;
+        }
+        if (node.callee?.type === "Identifier" && PROP_FACTORIES.has(node.callee.name)) {
+            return true;
+        }
+        // `withDefaults(defineProps<…>(), { … })`
+        return (
+            node.callee?.type === "Identifier" &&
+            node.callee.name === "withDefaults" &&
+            isPropsCall(node.arguments?.[0])
+        );
+    };
+    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 === "VariableDeclarator" && isPropsCall(node.init)) {
+            if (node.id?.type === "Identifier") {
+                propsVar = node.id.name;
+            } else if (node.id?.type === "ObjectPattern") {
+                for (const property of node.id.properties ?? []) {
+                    const target = property.value ?? property.argument;
+                    if (target?.type === "Identifier") {
+                        destructured.add(target.name);
+                    }
+                }
+            }
+        }
+        for (const key of Object.keys(node)) {
+            if (key === "parent" || key === "loc" || key === "range") {
+                continue;
+            }
+            walk(node[key]);
+        }
+    };
+    walk(program);
+    return { propsVar, destructured };
+}
+
+/** The root identifier of a member chain (`a.b.c` -> `a`), or null. */
+function rootIdentifier(node) {
+    let current = node;
+    while (current?.type === "MemberExpression") {
+        current = current.object;
+    }
+    return current?.type === "Identifier" ? current : null;
+}
+
+export default {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "disallow mutation of component props",
+            recommended: true,
+        },
+        schema: [],
+        messages: {
+            mutating:
+                "`{{name}}` is a prop, so it belongs to the parent. Writing to it is overwritten on the parent's next render — emit an event and let the parent own the change.",
+        },
+    },
+    create(context) {
+        if (!context.filename.endsWith(".vue")) {
+            return {};
+        }
+        return {
+            Program(program) {
+                const { propsVar, destructured } = analyzeProps(program);
+                if (!propsVar && !destructured.size) {
+                    return;
+                }
+                const isPropRoot = (name) =>
+                    (propsVar !== null && name === propsVar) || destructured.has(name);
+
+                // --- script side: exact AST walk --------------------------------------------
+                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;
+                    }
+                    const target =
+                        node.type === "AssignmentExpression"
+                            ? node.left
+                            : node.type === "UpdateExpression"
+                              ? node.argument
+                              : null;
+                    if (target) {
+                        const root = rootIdentifier(target);
+                        if (root && isPropRoot(root.name)) {
+                            context.report({
+                                node: root,
+                                messageId: "mutating",
+                                data: { name: root.name },
+                            });
+                        }
+                    }
+                    for (const key of Object.keys(node)) {
+                        if (key === "parent" || key === "loc" || key === "range") {
+                            continue;
+                        }
+                        walk(node[key]);
+                    }
+                };
+                walk(program);
+
+                // --- template side: conservative lexical scan -------------------------------
+                const entry = parseSfc(context.filename);
+                const ast = entry.descriptor.template?.ast;
+                if (!ast) {
+                    return;
+                }
+                const roots = [...(propsVar ? [propsVar] : []), ...destructured];
+                if (!roots.length) {
+                    return;
+                }
+                const rootPattern = new RegExp(
+                    `\\b(${roots.map((r) => r.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})\\b`,
+                    "g",
+                );
+
+                const report = (expression, offsetInExpression, name) => {
+                    const start = expression.loc.start.offset + offsetInExpression;
+                    reportAtFileOffset(
+                        context,
+                        entry,
+                        start,
+                        start + name.length,
+                        `\`${name}\` is a prop, so it belongs to the parent. Writing to it in the template is overwritten on the parent's next render — emit an event and let the parent own the change.`,
+                    );
+                };
+
+                const scan = (expression, alwaysMutation) => {
+                    if (!expression?.content) {
+                        return;
+                    }
+                    const text = blankStringsAndComments(expression.content);
+                    rootPattern.lastIndex = 0;
+                    let match = rootPattern.exec(text);
+                    while (match !== null) {
+                        const after = text.slice(match.index + match[1].length);
+                        if (alwaysMutation || MUTATION_AFTER_ROOT.test(after)) {
+                            report(expression, match.index, match[1]);
+                        }
+                        match = rootPattern.exec(text);
+                    }
+                };
+
+                walkTemplate(ast, (node) => {
+                    if (node.type === NODE_INTERPOLATION) {
+                        scan(node.content, false);
+                        return;
+                    }
+                    if (node.type !== NODE_ELEMENT) {
+                        return;
+                    }
+                    for (const prop of node.props ?? []) {
+                        if (prop.type !== PROP_DIRECTIVE) {
+                            continue;
+                        }
+                        // `v-model` IS an assignment, so its target is unambiguously mutated.
+                        scan(prop.exp, prop.name === "model");
+                    }
+                });
+            },
+        };
+    },
+};

package/rules/no-parsing-error.mjs

@@ -0,0 +1,51 @@
+import { parseSfc, reportAtFileOffset } from "../utils/vue-sfc.mjs";
+
+/**
+ * Replacement for `vue/no-parsing-error` (no native oxlint equivalent — oxc#15761).
+ *
+ * Uniquely cheap among the ported rules: we already run `@vue/compiler-sfc`'s parser to get
+ * the template AST, and it already collects every syntax error it recovered from. This rule
+ * is just surfacing `errors` instead of discarding them — no traversal, no heuristics.
+ *
+ * Why it earns its place rather than being redundant with the build: the compiler RECOVERS
+ * from these and carries on, so a malformed attribute or an unclosed tag can ship silently
+ * and only show up as markup that renders slightly wrong. Reporting at lint time makes it a
+ * gate instead of a surprise.
+ *
+ * Errors without a location are still reported, anchored at the start of the file rather
+ * than dropped — a parse error we cannot place is more important to surface, not less.
+ */
+
+export default {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "disallow parsing errors in `<template>`",
+            recommended: true,
+        },
+        schema: [],
+        messages: { m: "" },
+    },
+    create(context) {
+        if (!context.filename.endsWith(".vue")) {
+            return {};
+        }
+        return {
+            Program() {
+                const entry = parseSfc(context.filename);
+                for (const error of entry.errors ?? []) {
+                    const start = error.loc?.start?.offset ?? 0;
+                    const end = error.loc?.end?.offset ?? start + 1;
+                    const message = error.message ?? String(error);
+                    reportAtFileOffset(
+                        context,
+                        entry,
+                        start,
+                        end,
+                        `Vue template parsing error: ${message} The compiler recovers from this, so it can ship as subtly wrong markup rather than a build failure.`,
+                    );
+                }
+            },
+        };
+    },
+};

package/rules/no-raw-text.mjs

@@ -0,0 +1,99 @@
+import { NODE_ELEMENT, NODE_TEXT, parseSfc, reportAtFileOffset } from "../utils/vue-sfc.mjs";
+
+/**
+ * Replacement for `@intlify/vue-i18n/no-raw-text` (no native oxlint equivalent —
+ * oxlint has no i18n plugin). Flags user-facing literal text in the template that
+ * is not wrapped in an i18n call, so untranslated strings are caught in review
+ * instead of shipping. This repo collects missing keys for translators, so raw
+ * text in a template is almost always an oversight.
+ *
+ * Scope & false-positive guards (template-first repo, so the squiggle lands on the
+ * script block — the real template line:column is prepended to the message by
+ * reportAtFileOffset):
+ * - TEXT nodes only. Interpolations (`{{ $t('…') }}`) are never flagged; static
+ *   attributes (placeholder/title/…) are out of scope for now.
+ * - A text node is flagged only when it contains a 2+ letter word AND at least one
+ *   lowercase letter. That skips currency tickers / acronyms (BTC, USDT, OK), pure
+ *   numbers, symbols and punctuation — the dominant non-translatable noise — while
+ *   still catching real prose ("Buy", "items", "Confirm").
+ * - `ignoreTags` skips text inside non-translatable elements (style/script/pre/code).
+ * - `ignorePattern` (regex source) lets a project allowlist brand names etc.
+ */
+
+const DEFAULT_IGNORE_TAGS = ["style", "script", "pre", "code"];
+const HAS_WORD = /\p{L}{2,}/u;
+const HAS_LOWER = /\p{Ll}/u;
+
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "disallow untranslated raw text in Vue templates (use i18n)",
+            recommended: false,
+        },
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    ignorePattern: { type: "string" },
+                    ignoreTags: { type: "array", items: { type: "string" } },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: { m: "" },
+    },
+    create(context) {
+        if (!context.filename.endsWith(".vue")) {
+            return {};
+        }
+        const opts = context.options?.[0] ?? {};
+        const ignoreTags = new Set(opts.ignoreTags ?? DEFAULT_IGNORE_TAGS);
+        const ignoreRe = opts.ignorePattern ? new RegExp(opts.ignorePattern, "u") : null;
+        return {
+            Program() {
+                const entry = parseSfc(context.filename);
+                const ast = entry.descriptor.template?.ast;
+                if (!ast) {
+                    return;
+                }
+                const visit = (node) => {
+                    if (!node) {
+                        return;
+                    }
+                    // Skip the entire subtree of a non-translatable element, not just its
+                    // direct text children — text can be nested (`<pre><span>x</span></pre>`).
+                    if (node.type === NODE_ELEMENT && ignoreTags.has(node.tag)) {
+                        return;
+                    }
+                    if (node.type === NODE_TEXT) {
+                        const text = (node.content ?? "").trim();
+                        const flag =
+                            text &&
+                            HAS_WORD.test(text) &&
+                            HAS_LOWER.test(text) &&
+                            !(ignoreRe && ignoreRe.test(text));
+                        if (flag) {
+                            const snippet = text.length > 40 ? `${text.slice(0, 39)}…` : text;
+                            reportAtFileOffset(
+                                context,
+                                entry,
+                                node.loc.start.offset,
+                                node.loc.end.offset,
+                                `Raw template text "${snippet}" should be wrapped in an i18n translation ($t).`,
+                            );
+                        }
+                        return;
+                    }
+                    for (const child of node.children ?? []) {
+                        visit(child);
+                    }
+                    for (const branch of node.branches ?? []) {
+                        visit(branch);
+                    }
+                };
+                visit(ast);
+            },
+        };
+    },
+};

package/rules/no-ref-as-operand.mjs

@@ -0,0 +1,118 @@
+import { walkWithScopes } from "../utils/js-scope.mjs";
+
+/**
+ * Replacement for `vue/no-ref-as-operand` (no native oxlint equivalent — this one is on oxc's
+ * roadmap as script-based-and-feasible but had no PR as of oxlint 1.78; see OXLINT_MIGRATION.md).
+ *
+ * `const count = ref(0)` then `count + 1` operates on the ref OBJECT, not its value. There is no
+ * type error in plain JS and TypeScript often can't save you either (`Ref<number> + number`
+ * widens to `string` via valueOf/toString in some positions), so it ships as `"[object Object]1"`
+ * or `NaN`. The fix is always `.value`.
+ *
+ * Unlike the template rules in this plugin, this is a SCRIPT rule: oxlint hands JS plugins the
+ * real script AST, so there is no SFC self-parsing, no `reportAtFileOffset`, and positions are
+ * already correct — this rule does not depend on oxc#20501 at all.
+ *
+ * The reported contexts were derived EMPIRICALLY from eslint-plugin-vue, because the set is not
+ * what you would guess. Confirmed flagged: binary and logical operands (including `??`), unary
+ * arguments (`!`, `-`, `typeof`), a conditional's test, `if` test, `switch` discriminant,
+ * template-literal substitutions, and the right side of a COMPOUND assignment (`m += c`).
+ * Confirmed NOT flagged, and deliberately left alone:
+ * - `while (c)` and `for (;c;)` tests — surprising, but matching upstream matters more than
+ *   consistency, and being stricter than ESLint would break the parity guarantee.
+ * - plain assignment `m = c` — assigning the ref itself is a normal thing to do.
+ * - call arguments `fn(c)`, array/object literals `[c]` / `{ k: c }` — passing the ref around
+ *   is the idiomatic way to share reactivity.
+ * - `c.value` in any position.
+ *
+ * Ref detection resolves through LEXICAL SCOPE (utils/js-scope.mjs), not by name alone. That
+ * distinction is not academic: a name-only first cut produced 14 false positives on this repo,
+ * every one the same shape — a module-scope `const x = ref(…)` plus an inner-scope
+ * `const x = someCall(…)`, where the inner, non-ref binding was being reported. Shadowing has
+ * to be respected for this rule to be usable at all.
+ *
+ * Remaining limits, inherited from the scope helper and all failing toward false negatives:
+ * aliased/re-exported ref factories are not followed, `var` is treated as block-scoped, and
+ * there is no hoisting. See utils/js-scope.mjs.
+ */
+
+const REF_FACTORIES = new Set(["ref", "computed", "shallowRef", "customRef", "toRef"]);
+
+function isRefFactoryCall(init) {
+    return (
+        init?.type === "CallExpression" &&
+        init.callee?.type === "Identifier" &&
+        REF_FACTORIES.has(init.callee.name)
+    );
+}
+
+export default {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "require `.value` when using a `ref` as an operand",
+            recommended: true,
+        },
+        schema: [],
+        messages: {
+            refAsOperand:
+                "`{{name}}` is a ref, so this operates on the ref object rather than its value. Use `{{name}}.value`.",
+        },
+    },
+    create(context) {
+        return {
+            Program(program) {
+                const report = (candidate, lookup) => {
+                    if (candidate?.type !== "Identifier") {
+                        return;
+                    }
+                    // `true` only when the NEAREST binding is a ref; a shadowing non-ref
+                    // binding yields `false`, an unbound name `undefined`.
+                    if (lookup(candidate.name) !== true) {
+                        return;
+                    }
+                    context.report({
+                        node: candidate,
+                        messageId: "refAsOperand",
+                        data: { name: candidate.name },
+                    });
+                };
+
+                walkWithScopes(program, isRefFactoryCall, (node, lookup) => {
+                    switch (node.type) {
+                        case "BinaryExpression":
+                        case "LogicalExpression":
+                            report(node.left, lookup);
+                            report(node.right, lookup);
+                            break;
+                        case "UnaryExpression":
+                            report(node.argument, lookup);
+                            break;
+                        case "ConditionalExpression":
+                            report(node.test, lookup);
+                            break;
+                        case "IfStatement":
+                            report(node.test, lookup);
+                            break;
+                        case "SwitchStatement":
+                            report(node.discriminant, lookup);
+                            break;
+                        case "TemplateLiteral":
+                            for (const expression of node.expressions ?? []) {
+                                report(expression, lookup);
+                            }
+                            break;
+                        case "AssignmentExpression":
+                            // Compound only: `m += c` reads c's value, `m = c` stores the ref.
+                            if (node.operator !== "=") {
+                                report(node.right, lookup);
+                            }
+                            break;
+                        default:
+                            break;
+                    }
+                });
+            },
+        };
+    },
+};

package/rules/no-template-key.mjs

@@ -0,0 +1,65 @@
+import {
+    NODE_ELEMENT,
+    findDirective,
+    findKeyProp,
+    parseSfc,
+    reportAtFileOffset,
+    walkTemplate,
+} from "../utils/vue-sfc.mjs";
+
+/**
+ * Replacement for `vue/no-template-key` (no native oxlint equivalent — oxc#15761).
+ *
+ * `<template>` is not rendered, so a `key` on it has nothing to identify. Vue either
+ * ignores it or warns, and the developer's intent (keying the rendered children) is
+ * silently unmet.
+ *
+ * The one legitimate exception, and it is the common case in Vue 3: `<template v-for>`
+ * DOES take the key, precisely because the template stands in for each iteration. So
+ * this rule flags `key` on `<template>` only when the template carries no `v-for`.
+ * Flagging the v-for case would contradict vue-require-v-for-key, which requires it.
+ */
+
+export default {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "disallow `key` attribute on `<template>` without `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 || node.tag !== "template") {
+                        return;
+                    }
+                    const key = findKeyProp(node);
+                    // `<template v-for :key>` is the Vue 3 idiom and is required by
+                    // vue-require-v-for-key — never flag it.
+                    if (!key || findDirective(node, "for")) {
+                        return;
+                    }
+                    reportAtFileOffset(
+                        context,
+                        entry,
+                        key.loc.start.offset,
+                        key.loc.end.offset,
+                        "`<template>` is not rendered, so a `key` on it identifies nothing. Move the key to the rendered child element, or put `v-for` on this `<template>` if you meant to key the iteration.",
+                    );
+                });
+            },
+        };
+    },
+};