oxlint-plugin-vue-sfc 0.1.0

package/rules/v-on-event-hyphenation.mjs

@@ -0,0 +1,88 @@
+import {
+    ELEMENT_COMPONENT,
+    NODE_ELEMENT,
+    PROP_DIRECTIVE,
+    parseSfc,
+    reportAtFileOffset,
+    walkTemplate,
+} from "../utils/vue-sfc.mjs";
+
+/**
+ * Replacement for `vue/v-on-event-hyphenation` (no native oxlint equivalent — oxc#15761).
+ *
+ * In-DOM templates lower-case attribute names, so `@myEvent` becomes `@myevent` and silently
+ * stops matching an `emit("myEvent")`. Hyphenated `@my-event` survives that normalization and
+ * Vue maps it back to the camelCase emit. Keeping one convention also stops the same event
+ * being listened to two ways in different files.
+ *
+ * Scope, deliberately narrow to avoid false positives:
+ * - COMPONENTS only (parser `tagType`, not a casing heuristic). Native DOM events are all
+ *   lowercase already, and a custom element's events are not Vue's to rename.
+ * - Static event names only. `@[dynamic]` cannot be checked without evaluating the expression.
+ * - `v-on="obj"` (argument-less) has no single name and is skipped.
+ *
+ * This is `warn` upstream in our config, and stays `warn`: it is a convention with a real
+ * failure mode rather than a guaranteed bug, since SFC templates are not DOM-parsed.
+ */
+
+/** camelCase / PascalCase detection: any uppercase letter in the event name. */
+const HAS_UPPER = /[A-Z]/;
+
+function hyphenate(name) {
+    return name.replace(/\B([A-Z])/g, "-$1").toLowerCase();
+}
+
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "enforce `v-on` event naming style on custom components 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;
+                }
+                walkTemplate(ast, (node) => {
+                    if (node.type !== NODE_ELEMENT || node.tagType !== ELEMENT_COMPONENT) {
+                        return;
+                    }
+                    for (const prop of node.props ?? []) {
+                        if (prop.type !== PROP_DIRECTIVE || prop.name !== "on") {
+                            continue;
+                        }
+                        const arg = prop.arg;
+                        // Argument-less `v-on="obj"`, or a dynamic `@[name]` — nothing static
+                        // to judge.
+                        if (!arg || arg.type !== 4 /* SIMPLE_EXPRESSION */ || arg.isStatic === false) {
+                            continue;
+                        }
+                        const name = arg.content;
+                        if (!HAS_UPPER.test(name)) {
+                            continue;
+                        }
+                        // Anchor on the whole directive so the column lands on the `@`/`v-on`,
+                        // matching eslint-plugin-vue (verified at exact column parity).
+                        reportAtFileOffset(
+                            context,
+                            entry,
+                            prop.loc.start.offset,
+                            prop.loc.end.offset,
+                            `Use \`@${hyphenate(name)}\` instead of \`@${name}\` on <${node.tag}>: in-DOM templates lower-case attribute names, so the camelCase form silently stops matching the emit.`,
+                        );
+                    }
+                });
+            },
+        };
+    },
+};

package/utils/js-scope.mjs

@@ -0,0 +1,172 @@
+/**
+ * Minimal lexical scope resolution for oxlint JS-plugin rules that work on the script AST.
+ *
+ * Why this exists: a name-only lookup is not good enough. The first cut of
+ * vue-no-ref-as-operand collected ref names globally and flagged every matching identifier,
+ * which produced 14 false positives on this repo — all the same shape:
+ *
+ *     const giveTicker = ref("");                        // module scope: a ref
+ *     ...
+ *     const giveTicker = parseMaybeArrayRouteParam(x);   // inner scope: NOT a ref
+ *     if (giveTicker && !receiveTicker) { … }            // was wrongly reported
+ *
+ * So resolution has to respect shadowing. This is a deliberately small implementation — it
+ * models block/function/catch/loop scopes and the declaration forms that appear in SFC scripts,
+ * not the full ECMAScript scope algorithm.
+ *
+ * Known simplifications, all chosen to fail toward FALSE NEGATIVES rather than false positives:
+ * - `var` is treated as block-scoped rather than function-scoped. A `var` ref declared inside a
+ *   block is therefore invisible outside it: missed reports, never wrong ones.
+ * - No hoisting. Declarations are visible from the point they are recorded onward within their
+ *   scope, which matches `const`/`let` semantics (a use before declaration is a TDZ error) and
+ *   under-reports for hoisted `var`/`function`.
+ * - Destructuring binds its names but never marks them as refs, since `const { a } = ref(…)` is
+ *   not a ref-valued binding.
+ */
+
+const SCOPE_NODES = new Set([
+    "Program",
+    "FunctionDeclaration",
+    "FunctionExpression",
+    "ArrowFunctionExpression",
+    "BlockStatement",
+    "StaticBlock",
+    "ForStatement",
+    "ForInStatement",
+    "ForOfStatement",
+    "CatchClause",
+    "ClassDeclaration",
+    "ClassExpression",
+]);
+
+/** Collect every name bound by a binding pattern into `sink`. */
+function collectPatternNames(pattern, sink) {
+    if (!pattern || typeof pattern !== "object") {
+        return;
+    }
+    switch (pattern.type) {
+        case "Identifier":
+            sink(pattern.name);
+            break;
+        case "ObjectPattern":
+            for (const property of pattern.properties ?? []) {
+                collectPatternNames(property.value ?? property.argument, sink);
+            }
+            break;
+        case "ArrayPattern":
+            for (const element of pattern.elements ?? []) {
+                collectPatternNames(element, sink);
+            }
+            break;
+        case "AssignmentPattern":
+            collectPatternNames(pattern.left, sink);
+            break;
+        case "RestElement":
+            collectPatternNames(pattern.argument, sink);
+            break;
+        default:
+            break;
+    }
+}
+
+/**
+ * Walk `program`, tracking lexical scopes, and report identifiers whose nearest binding
+ * satisfies `isTracked`.
+ *
+ * @param program the Program node from oxlint's `Program(node)` visitor
+ * @param isMarkedInit (init) => boolean — does this initializer make the binding "tracked"
+ *        (for vue-no-ref-as-operand: is it a `ref()`/`computed()`/… call)
+ * @param onNode (node, scopeLookup) => void — called for every AST node, with a
+ *        `scopeLookup(name)` that returns `true` when the nearest binding of `name` is tracked,
+ *        `false` when it is shadowed by an untracked one, and `undefined` when unbound.
+ */
+export function walkWithScopes(program, isMarkedInit, onNode) {
+    /** Stack of Map<name, boolean /* tracked *\/>, innermost last. */
+    const stack = [new Map()];
+
+    const lookup = (name) => {
+        for (let i = stack.length - 1; i >= 0; i -= 1) {
+            const scope = stack[i];
+            if (scope.has(name)) {
+                return scope.get(name);
+            }
+        }
+        return undefined;
+    };
+
+    const declare = (name, tracked) => {
+        stack[stack.length - 1].set(name, tracked);
+    };
+
+    /** Record the bindings a node introduces INTO THE CURRENT scope, before descending. */
+    const recordDeclarations = (node) => {
+        switch (node.type) {
+            case "VariableDeclarator": {
+                if (node.id?.type === "Identifier") {
+                    declare(node.id.name, Boolean(isMarkedInit(node.init)));
+                } else {
+                    collectPatternNames(node.id, (name) => declare(name, false));
+                }
+                break;
+            }
+            case "FunctionDeclaration":
+            case "ClassDeclaration":
+                if (node.id?.type === "Identifier") {
+                    declare(node.id.name, false);
+                }
+                break;
+            case "ImportDeclaration":
+                for (const specifier of node.specifiers ?? []) {
+                    if (specifier.local?.type === "Identifier") {
+                        declare(specifier.local.name, false);
+                    }
+                }
+                break;
+            default:
+                break;
+        }
+    };
+
+    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 opensScope = SCOPE_NODES.has(node.type);
+        if (opensScope) {
+            stack.push(new Map());
+            // Parameters and the catch binding belong to the scope the node opens.
+            for (const param of node.params ?? []) {
+                collectPatternNames(param, (name) => declare(name, false));
+            }
+            if (node.type === "CatchClause") {
+                collectPatternNames(node.param, (name) => declare(name, false));
+            }
+        }
+
+        recordDeclarations(node);
+        onNode(node, lookup);
+
+        for (const key of Object.keys(node)) {
+            if (key === "parent" || key === "loc" || key === "range") {
+                continue;
+            }
+            walk(node[key]);
+        }
+
+        if (opensScope) {
+            stack.pop();
+        }
+    };
+
+    walk(program);
+}

package/utils/vue-bindings.mjs

@@ -0,0 +1,154 @@
+/**
+ * Positioned extraction of the variables a Vue template DECLARES — `v-for` aliases and `v-slot`
+ * destructuring — shared by vue-no-unused-vars and vue-no-template-shadow.
+ *
+ * `utils/vue-sfc.mjs` already has `extractBindingNames`, but it returns names only and bails on
+ * any pattern containing `:` or `=`. Both rules here need the OFFSET of each binding (reports
+ * anchor on the identifier itself) and need to handle renames and defaults, so this is a
+ * separate, more capable extractor rather than a change to that one.
+ *
+ * It is a positioned scan, not a real pattern parse: identifiers in the alias text, minus those
+ * immediately followed by `:` (object-pattern KEYS, where the binding is the right-hand name).
+ * That covers `item`, `(item, i)`, `{ a, b }`, `[a, b]`, `{ a: renamed }` and `{ a = 1 }` —
+ * every shape in this codebase.
+ */
+
+const IDENTIFIER_RE = /[A-Za-z_$][\w$]*/g;
+/** Words that can appear in alias text but are never bindings. */
+const RESERVED = new Set(["in", "of", "true", "false", "null", "undefined"]);
+
+/**
+ * Identifiers bound by a `v-for` alias / `v-slot` pattern, with offsets inside `text`.
+ * @returns {{name: string, offset: number}[]}
+ */
+export function bindingsWithOffsets(text) {
+    const found = [];
+    IDENTIFIER_RE.lastIndex = 0;
+    let match = IDENTIFIER_RE.exec(text);
+    while (match !== null) {
+        const name = match[0];
+        const isKey = /^\s*:/.test(text.slice(match.index + name.length));
+        if (!isKey && !RESERVED.has(name)) {
+            found.push({ name, offset: match.index });
+        }
+        match = IDENTIFIER_RE.exec(text);
+    }
+    return found;
+}
+
+/** The left-hand alias portion of a `v-for` expression. Returns null if there is no `in`/`of`. */
+export function forAliasPart(content) {
+    const match = /\s+(?:in|of)\s+/.exec(content);
+    if (!match) {
+        return null;
+    }
+    return { text: content.slice(0, match.index), offset: 0 };
+}
+
+/**
+ * Split a `v-for` alias list into its positional groups, each with its offset in `text`.
+ * `(a, i)` -> two groups; `({ a }, i)` -> two, the first a destructuring pattern.
+ * Splits only on top-level commas, so nested `{}` / `[]` / `()` stay intact.
+ */
+export function positionalGroups(text) {
+    const trimmed = text.trim();
+    const lead = text.indexOf(trimmed);
+    const wrapped = trimmed.startsWith("(") && trimmed.endsWith(")");
+    const inner = wrapped ? trimmed.slice(1, -1) : trimmed;
+    const base = lead + (wrapped ? 1 : 0);
+
+    const groups = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < inner.length; i += 1) {
+        const ch = inner[i];
+        if (ch === "{" || ch === "[" || ch === "(") {
+            depth += 1;
+        } else if (ch === "}" || ch === "]" || ch === ")") {
+            depth -= 1;
+        } else if (ch === "," && depth === 0) {
+            groups.push({ text: inner.slice(start, i), offset: base + start });
+            start = i + 1;
+        }
+    }
+    groups.push({ text: inner.slice(start), offset: base + start });
+    return groups;
+}
+
+/**
+ * The alias text a directive declares, or null if it declares nothing.
+ * `v-for` yields its left-hand side; `v-slot` yields its whole expression.
+ */
+export function declaredAlias(prop) {
+    if (!prop.exp?.content) {
+        return null;
+    }
+    if (prop.name === "for") {
+        return forAliasPart(prop.exp.content);
+    }
+    if (prop.name === "slot") {
+        return { text: prop.exp.content, offset: 0 };
+    }
+    return null;
+}
+
+/**
+ * Top-level binding names declared by a `<script setup>` program — everything the template can
+ * reference. Used by vue-no-template-shadow to know what a template alias would shadow.
+ */
+export function scriptTopLevelNames(program) {
+    const names = new Set();
+    const addPattern = (pattern) => {
+        if (!pattern || typeof pattern !== "object") {
+            return;
+        }
+        switch (pattern.type) {
+            case "Identifier":
+                names.add(pattern.name);
+                break;
+            case "ObjectPattern":
+                for (const property of pattern.properties ?? []) {
+                    addPattern(property.value ?? property.argument);
+                }
+                break;
+            case "ArrayPattern":
+                for (const element of pattern.elements ?? []) {
+                    addPattern(element);
+                }
+                break;
+            case "AssignmentPattern":
+                addPattern(pattern.left);
+                break;
+            case "RestElement":
+                addPattern(pattern.argument);
+                break;
+            default:
+                break;
+        }
+    };
+    for (const statement of program?.body ?? []) {
+        switch (statement.type) {
+            case "VariableDeclaration":
+                for (const declarator of statement.declarations ?? []) {
+                    addPattern(declarator.id);
+                }
+                break;
+            case "FunctionDeclaration":
+            case "ClassDeclaration":
+                if (statement.id?.type === "Identifier") {
+                    names.add(statement.id.name);
+                }
+                break;
+            case "ImportDeclaration":
+                for (const specifier of statement.specifiers ?? []) {
+                    if (specifier.local?.type === "Identifier") {
+                        names.add(specifier.local.name);
+                    }
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    return names;
+}

package/utils/vue-sfc.mjs

@@ -0,0 +1,202 @@
+import fs from "node:fs";
+
+import { parse } from "@vue/compiler-sfc";
+
+/**
+ * Helpers for writing oxlint JS-plugin rules against the Vue TEMPLATE AST.
+ *
+ * oxlint parses only the script block of an SFC and gives JS-plugin rules a
+ * script-only view: `context.sourceCode.text` is the script content and
+ * line/column locations passed to `context.report()` are validated against the
+ * script's line count (template lines are rejected with a RangeError).
+ *
+ * Two empirically verified escape hatches make template rules possible anyway:
+ * 1. `fs.readFileSync(context.filename)` works inside the sidecar, so a rule
+ *    can parse the FULL SFC with @vue/compiler-sfc.
+ * 2. `context.report({ node: { range: [start, end] } })` accepts raw
+ *    script-relative byte offsets WITHOUT line validation and maps them to
+ *    file positions by adding the script block's offset. A template offset is
+ *    therefore reachable only as `fileOffset - scriptStartOffset` when that is
+ *    >= 0 — i.e. when <script> precedes <template>.
+ *
+ * THIS REPO IS ENTIRELY THE OPPOSITE: every SFC is template-first (verified:
+ * 1414 template-first, 0 script-first), so template offsets are always
+ * NEGATIVE. oxlint rejects negative ranges (and rejects line/column that fall
+ * outside the script block), so a template diagnostic CANNOT be rendered on
+ * its real template line — the code frame always falls back to the script
+ * block's first line (see reportAtFileOffset). This is an inherent limit of
+ * oxlint's script-only JS-plugin view of .vue files, not a bug we can fix
+ * here; we surface the true template line:column in the message text instead.
+ */
+
+// One parse per file per lint run, shared across rules (module state lives for
+// the lifetime of oxlint's JS-plugin sidecar process).
+const cache = new Map();
+
+export function parseSfc(filename) {
+    let entry = cache.get(filename);
+    if (!entry) {
+        const text = fs.readFileSync(filename, "utf8");
+        const { descriptor, errors } = parse(text, { filename });
+        entry = { text, descriptor, errors };
+        cache.set(filename, entry);
+    }
+    return entry;
+}
+
+/** Script block content start offset in the file (script setup preferred). */
+export function scriptStartOffset(descriptor) {
+    const block = descriptor.scriptSetup ?? descriptor.script;
+    return block ? block.loc.start.offset : 0;
+}
+
+/**
+ * Report a diagnostic at an absolute FILE offset range by translating it into
+ * the script-relative range oxlint expects. Template positions BEFORE the
+ * script block can't be represented as ranges (negative offsets) — the norm in
+ * this template-first repo — so those fall back to the script block's first
+ * line with the real template line:column PREPENDED to the message, so the
+ * editor's problem list and the CLI still point you at the right place even
+ * though the squiggle is stuck on the script block.
+ */
+export function reportAtFileOffset(context, entry, fileStart, fileEnd, message) {
+    const base = scriptStartOffset(entry.descriptor);
+    const start = fileStart - base;
+    if (start >= 0) {
+        context.report({
+            node: { type: "TemplateDiagnostic", range: [start, fileEnd - base] },
+            message,
+        });
+        return;
+    }
+    const before = entry.text.slice(0, fileStart);
+    const line = before.split("\n").length;
+    const column = fileStart - (before.lastIndexOf("\n") + 1) + 1;
+    context.report({
+        node: { type: "TemplateDiagnostic", range: [0, 1] },
+        message: `[template ${line}:${column}] ${message}`,
+    });
+}
+
+/** Depth-first walk over @vue/compiler-dom template AST element nodes. */
+export function walkTemplate(node, visit) {
+    if (!node) {
+        return;
+    }
+    visit(node);
+    if (Array.isArray(node.children)) {
+        for (const child of node.children) {
+            walkTemplate(child, visit);
+        }
+    }
+    // v-if/v-else chains parsed standalone keep branches as siblings, but walk
+    // branches too in case a transformed AST is ever passed in.
+    if (Array.isArray(node.branches)) {
+        for (const branch of node.branches) {
+            walkTemplate(branch, visit);
+        }
+    }
+}
+
+/** @vue/compiler-dom NodeTypes used by rules (avoid importing internals). */
+export const NODE_ELEMENT = 1;
+export const NODE_TEXT = 2;
+export const NODE_INTERPOLATION = 5;
+export const PROP_ATTRIBUTE = 6;
+export const PROP_DIRECTIVE = 7;
+/** @vue/compiler-dom ElementTypes.COMPONENT */
+export const ELEMENT_COMPONENT = 1;
+
+/**
+ * Visit every expression in the template: interpolations (directiveName null)
+ * and directive expressions (directiveName e.g. "model", "bind", "if").
+ */
+export function eachTemplateExpression(ast, visit) {
+    walkTemplate(ast, (node) => {
+        if (node.type === NODE_INTERPOLATION && node.content?.content) {
+            visit(node.content, null);
+        }
+        if (node.type === NODE_ELEMENT) {
+            for (const p of node.props ?? []) {
+                if (p.type === PROP_DIRECTIVE && p.exp?.content) {
+                    visit(p.exp, p.name);
+                }
+            }
+        }
+    });
+}
+
+export function findDirective(el, name) {
+    return el.props?.find((p) => p.type === PROP_DIRECTIVE && p.name === name);
+}
+
+export function findKeyProp(el) {
+    return el.props?.find(
+        (p) =>
+            (p.type === PROP_ATTRIBUTE && p.name === "key") ||
+            (p.type === PROP_DIRECTIVE &&
+                p.name === "bind" &&
+                p.arg?.type === 4 /* SIMPLE_EXPRESSION */ &&
+                p.arg.content === "key"),
+    );
+}
+
+/**
+ * Extract variable names bound by a v-for / v-slot expression ("item",
+ * "(item, index)", "{ row }"). Returns null for shapes with renames or
+ * defaults (`{ a: b }`, `{ a = 1 }`) — identifying which side is the binding
+ * needs a real parser, and a wrong guess produces false positives downstream.
+ */
+export function extractBindingNames(exprText) {
+    const left = exprText.split(/\s+(?:in|of)\s+/)[0] ?? exprText;
+    if (/[:=]/.test(left)) {
+        return null;
+    }
+    const names = [...left.matchAll(/[A-Za-z_$][\w$]*/g)].map((m) => m[0]);
+    return names.length ? names : null;
+}
+
+/**
+ * Collect every identifier bound by a JS destructuring pattern
+ * (`a`, `{ a, b }`, `[a, b]`, `a = 1`, `...rest`) into `into`. Script-side rules use
+ * this to know which names a declaration / parameter / catch clause introduces.
+ */
+export const collectPatternNames = (pattern, into) => {
+    if (!pattern) {
+        return;
+    }
+    switch (pattern.type) {
+        case "Identifier":
+            into.add(pattern.name);
+            break;
+        case "ObjectPattern":
+            for (const p of pattern.properties ?? []) {
+                collectPatternNames(p.value ?? p.argument, into);
+            }
+            break;
+        case "ArrayPattern":
+            for (const el of pattern.elements ?? []) {
+                collectPatternNames(el, into);
+            }
+            break;
+        case "AssignmentPattern":
+            collectPatternNames(pattern.left, into);
+            break;
+        case "RestElement":
+            collectPatternNames(pattern.argument, into);
+            break;
+        default:
+            break;
+    }
+};
+
+/** Set of static `v-on` event names (`@click`, `v-on:click`) on a template element. */
+export function eventNames(el) {
+    const names = new Set();
+    for (const p of el.props ?? []) {
+        if (p.type === PROP_DIRECTIVE && p.name === "on" && p.arg?.type === 4 /* SIMPLE */) {
+            names.add(p.arg.content);
+        }
+    }
+    return names;
+}