@webjsdev/server 0.8.63 → 0.8.64

package/src/check/rules-components.js

@@ -0,0 +1,275 @@
+/**
+ * Component-authoring rules: registration, reactive-property declaration, and
+ * the SSR-safety of a component body.
+ *
+ * Lifted verbatim out of checkConventions, which held all twenty rules inline
+ * in one 900-line function. Each rule keeps its original comment header, its
+ * logic, and its position in the run order.
+ */
+import {
+  extractWebComponentClassBodies, matchClosingBrace, parsePropEntries,
+} from '../js-scan.js';
+import {
+  isComponentFile, arrayPropUsesObject, findFieldInitializers, methodBodyOf,
+  findBrowserMemberUses,
+} from './helpers.js';
+
+/**
+ * @typedef {import('./rules.js').Violation} Violation
+ * @typedef {{ abs: string, rel: string, content: string, scan: string }} ScannedFile
+ */
+
+
+/**
+ * Rule: `components-have-register`.
+ *
+ * @param {ScannedFile[]} files  every JS/TS file in the app, raw and redacted
+ * @param {Violation[]} violations  accumulator the rule pushes onto
+ * @returns {void}
+ */
+export function checkComponentsHaveRegister(files, violations) {
+  // --- Rule: components-have-register ---
+  {
+    for (const { rel, scan } of files) {
+      if (!isComponentFile(rel)) continue;
+      // Use redacted source so a code-example string like
+      // `Foo.register('bar')` inside a tagged template literal does
+      // not falsely satisfy the rule for a sibling unregistered
+      // class. Real register() calls live at top level where the
+      // redactor leaves them alone.
+      if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
+      // Accept either registration pattern:
+      //   Counter.register('tag')                    (WebJs idiom)
+      //   customElements.define('tag', Counter)      (native)
+      if (/\b[A-Z][A-Za-z0-9_$]*\.register\s*\(\s*['"`]/.test(scan)) continue;
+      if (/\bcustomElements\.define\s*\(/.test(scan)) continue;
+      violations.push({
+        rule: 'components-have-register',
+        file: rel,
+        message: "Component extends WebComponent but is never registered. Call ClassName.register('tag-name') at the bottom of the file.",
+        fix: "Add `ClassName.register('tag-name')` after the class definition",
+      });
+    }
+  }
+}
+
+/**
+ * Rule: `no-static-properties`.
+ *
+ * @param {ScannedFile[]} files  every JS/TS file in the app, raw and redacted
+ * @param {Violation[]} violations  accumulator the rule pushes onto
+ * @returns {void}
+ */
+export function checkNoStaticProperties(files, violations) {
+  // --- Rule: no-static-properties ---
+  // A hand-written `static properties = { … }` in a WebComponent class body is
+  // no longer supported: reactive properties are declared via the
+  // `extends WebComponent({ … })` factory (the runtime throws on a direct
+  // `static properties`). Flag it statically so the editor catches it before
+  // the page 500s.
+  {
+    for (const { rel, scan } of files) {
+      // Use redacted source so fixture-style strings like
+      // `class X extends WebComponent { static properties = {…} }` inside
+      // template literals don't trip the rule. Real declarations live at
+      // top-level code where the redactor leaves them alone.
+      if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
+      for (const { body } of extractWebComponentClassBodies(scan)) {
+        if (!/static\s+properties\s*=\s*\{/.test(body)) continue;
+        violations.push({
+          rule: 'no-static-properties',
+          file: rel,
+          message:
+            '`static properties = { … }` is no longer supported; declare reactive properties via the `extends WebComponent({ … })` factory instead.',
+          fix: 'Move the properties into the factory call: `class X extends WebComponent({ count: Number })`. Use `prop(Number, { reflect: true })` for options and set defaults in the constructor after super(). Delete the `static properties` block and any `declare` fields for those props.',
+        });
+      }
+    }
+  }
+}
+
+/**
+ * Rule: `reactive-props-no-class-field`.
+ *
+ * @param {ScannedFile[]} files  every JS/TS file in the app, raw and redacted
+ * @param {Violation[]} violations  accumulator the rule pushes onto
+ * @returns {void}
+ */
+export function checkReactivePropsNoClassField(files, violations) {
+  // --- Rule: reactive-props-no-class-field ---
+  // A reactive property declared via the factory must not also carry a plain
+  // class-field declaration (initializer OR type-only): under modern class-field
+  // semantics (including `erasableSyntaxOnly: true`) every class-field declaration
+  // compiles to Object.defineProperty after super() and clobbers the framework's
+  // reactive accessor (silent broken re-renders). Catches `count = 0`,
+  // `count: number = 0`, `count!: number`, and `count?: number`.
+  {
+    for (const { rel, scan } of files) {
+      if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
+      for (const { body, factoryProps } of extractWebComponentClassBodies(scan)) {
+        if (factoryProps.size === 0) continue;
+        for (const bad of findFieldInitializers(body, factoryProps)) {
+          violations.push({
+            rule: 'reactive-props-no-class-field',
+            file: rel,
+            message: `Reactive prop \`${bad}\` uses a class-field declaration (initializer or type-only); this clobbers the framework's reactive accessor under modern class-field semantics.`,
+            fix: `Delete the class-field declaration and set the default by assigning \`this.${bad} = <value>\` inside \`constructor()\` after \`super()\`.`,
+          });
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Rule: `array-prop-uses-array-type`.
+ *
+ * @param {ScannedFile[]} files  every JS/TS file in the app, raw and redacted
+ * @param {Violation[]} violations  accumulator the rule pushes onto
+ * @returns {void}
+ */
+export function checkArrayPropUsesArrayType(files, violations) {
+  // --- Rule: array-prop-uses-array-type ---
+  // An array-typed reactive prop declared via the factory should pass the
+  // `Array` runtime constructor, not `Object`. Both share one converter
+  // (JSON encode/decode), so `Object` does not crash, but it misstates the
+  // prop contract and diverges from the documented built-in set. Fires only
+  // when the factory generic is itself an array type AND the constructor is
+  // `Object`; a bare `foo: Object` (no generic to prove array-ness) is left
+  // alone to avoid false positives. Uses the redacted `scan`, so a
+  // `prop<X[]>(Object)` shown inside an html`` example string never fires.
+  {
+    for (const { rel, scan } of files) {
+      if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
+      for (const { factoryArg } of extractWebComponentClassBodies(scan)) {
+        const objStart = factoryArg.indexOf('{');
+        if (objStart === -1) continue;
+        const objEnd = matchClosingBrace(factoryArg, objStart + 1);
+        if (objEnd === -1) continue;
+        const objContent = factoryArg.slice(objStart + 1, objEnd);
+        for (const { key, value } of parsePropEntries(objContent)) {
+          if (!arrayPropUsesObject(value)) continue;
+          violations.push({
+            rule: 'array-prop-uses-array-type',
+            file: rel,
+            message: `Array-typed reactive prop \`${key}\` is declared with the \`Object\` constructor (\`prop<…[]>(Object)\`); use \`Array\` so the runtime converter matches the declared shape.`,
+            fix: `Change the constructor to \`Array\`: \`${key}: prop<…[]>(Array)\`. Object and Array share one converter so behaviour is unchanged, but \`Array\` states the prop's shape correctly.`,
+          });
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Rule: `no-browser-globals-in-render`.
+ *
+ * @param {ScannedFile[]} files  every JS/TS file in the app, raw and redacted
+ * @param {Violation[]} violations  accumulator the rule pushes onto
+ * @returns {void}
+ */
+export function checkNoBrowserGlobalsInRender(files, violations) {
+  // --- Rule: no-browser-globals-in-render ---
+  // The SSR pipeline runs the constructor (`new Cls()`), willUpdate, and
+  // render() on the server element shim (attribute methods backed, but no real
+  // DOM). A genuinely browser-only global or an unshimmed HTMLElement member on
+  // `this` touched in any of those throws at SSR time. Those belong in
+  // connectedCallback / post-render hooks, which SSR never calls. willUpdate is
+  // scanned because it now runs at SSR (issue #217).
+  {
+    for (const { rel, scan } of files) {
+      if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
+      for (const { body } of extractWebComponentClassBodies(scan)) {
+        for (const method of ['constructor', 'willUpdate', 'render']) {
+          const code = methodBodyOf(body, method);
+          if (!code) continue;
+          for (const { member, kind } of findBrowserMemberUses(code)) {
+            violations.push({
+              rule: 'no-browser-globals-in-render',
+              file: rel,
+              message: `\`${member}\` (${kind}) is used in ${method}(), which runs during SSR where it is not available, so it throws and the component fails to server-render.`,
+              fix: `Move browser-only work to connectedCallback() or a lifecycle hook (firstUpdated/updated), which SSR never calls. Seed first-paint defaults in the constructor only from server-known inputs (attributes / props), then refine in connectedCallback by writing to a signal.`,
+            });
+          }
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Rule: `no-shadowed-native-member`.
+ *
+ * @param {ScannedFile[]} files  every JS/TS file in the app, raw and redacted
+ * @param {Violation[]} violations  accumulator the rule pushes onto
+ * @returns {void}
+ */
+export function checkNoShadowedNativeMember(files, violations) {
+  // --- Rule: no-shadowed-native-member ---
+  // A WebComponent method named after a native DOM mutation method WebJs
+  // instruments on every light-DOM host for the slot API (#1021) is SHADOWED at
+  // runtime (the native/instrumented method wins), so the component method never
+  // runs, while TypeScript stays green (a shorter override is assignable). Rename
+  // the handler. The lifecycle hooks are meant to be overridden, so only the DOM
+  // mutation members are reserved.
+  {
+    const NATIVE_MEMBERS = [
+      'append', 'prepend', 'before', 'after', 'replaceWith', 'replaceChildren', 'remove',
+      'appendChild', 'insertBefore', 'removeChild', 'replaceChild',
+    ];
+    for (const { rel, scan } of files) {
+      if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
+      for (const { body } of extractWebComponentClassBodies(scan)) {
+        // The slot interception installs only on LIGHT-DOM hosts (the shadow
+        // branch keeps the true native methods), so a shadow component's method
+        // is never shadowed. Skip the whole class.
+        if (/static\s+shadow\s*=\s*true/.test(body)) continue;
+        // Brace-depth map over the (already string/comment-masked) class body,
+        // so only TOP-LEVEL class members flag: a same-named object-literal
+        // shorthand or function expression nested inside a method body is a
+        // different object's property and shadows nothing.
+        const depth = new Int32Array(body.length);
+        {
+          let d = 0;
+          for (let i = 0; i < body.length; i++) {
+            if (body[i] === '{') { depth[i] = d; d++; }
+            else if (body[i] === '}') { d--; depth[i] = d; }
+            else depth[i] = d;
+          }
+        }
+        for (const name of NATIVE_MEMBERS) {
+          // Two shadowed-definition shapes, both instance-level: the method /
+          // accessor form (`remove() {`, `get remove() {`), and the class-field
+          // FUNCTION form (`remove = () => {}` / `= function () {}`), which the
+          // connect-time interception install overwrites just the same. A
+          // `static` member lives on the constructor and shadows nothing.
+          const methodRe = new RegExp(
+            `(?:^|[\\s;}])((?:static\\s+)?)(?:async\\s+)?(?:get\\s+|set\\s+)?(${name})\\s*\\([^)]*\\)\\s*(?::[^{]*)?\\{`,
+            'g',
+          );
+          const fieldRe = new RegExp(
+            `(?:^|[\\s;}])((?:static\\s+)?)(${name})\\s*=\\s*(?:async\\s*)?(?:function\\b|\\([^)]*\\)\\s*(?::[^=]*)?=>|[\\w$]+\\s*=>)`,
+            'g',
+          );
+          let flagged = false;
+          for (const re of [methodRe, fieldRe]) {
+            let m;
+            while (!flagged && (m = re.exec(body)) !== null) {
+              if (m[1]) continue;                       // static: not shadowed
+              const nameIdx = m.index + m[0].indexOf(m[2]);
+              if (depth[nameIdx] !== 0) continue;       // nested: another object's property
+              flagged = true;
+              violations.push({
+                rule: 'no-shadowed-native-member',
+                file: rel,
+                message: `Component member \`${name}\` shadows the native DOM method WebJs instruments for the slot API, so it silently never runs (the native method wins) and TypeScript does not catch it.`,
+                fix: `Rename the member to a non-native name (e.g. \`${name}Row()\` / \`${name}Item()\`) and update its call sites.`,
+              });
+            }
+            if (flagged) break;
+          }
+        }
+      }
+    }
+  }
+}

package/src/check/rules-imports.js

@@ -0,0 +1,166 @@
+/**
+ * Import-graph rules: what a browser-bound module may reach, whether a local
+ * specifier resolves, and whether a bound form action can answer a POST.
+ *
+ * Lifted verbatim out of checkConventions, which held all twenty rules inline
+ * in one 900-line function. Each rule keeps its original comment header, its
+ * logic, and its position in the run order.
+ */
+import { relative } from 'node:path';
+import {
+  redactStringsAndTemplates, redactToPlaceholders, classifyActionHole,
+} from '../js-scan.js';
+import { resolveImport } from '../module-graph.js';
+import {
+  hasUseServerDirective, enumerableExports, importedLocalNames, importedValueNames,
+} from './helpers.js';
+
+/**
+ * @typedef {import('./rules.js').Violation} Violation
+ * @typedef {{ abs: string, rel: string, content: string, scan: string }} ScannedFile
+ */
+
+/**
+ * Rule: `no-missing-local-import`.
+ *
+ * @param {string} appDir  absolute path to the app root
+ * @param {ScannedFile[]} files  every JS/TS file in the app, raw and redacted
+ * @param {Violation[]} violations  accumulator the rule pushes onto
+ * @returns {void}
+ */
+export function checkNoMissingLocalImport(appDir, files, violations) {
+  // --- Rule: no-missing-local-import ---
+  // A named value import of a symbol an app-internal module does not export is a
+  // runtime crash (the binding is undefined) that the elision-based checks miss,
+  // so `check` can stay green while `typecheck` is red (a dropped schema table
+  // orphaning a gallery module is the motivating dogfood case). Conservative by
+  // construction: only app-internal specifiers resolving to a known app file,
+  // only named value imports, and only when the target's exports are fully
+  // enumerable (see enumerableExports / importedValueNames).
+  {
+    // Fully-blanked view (blankStrings=true): string AND template AND comment
+    // bodies blank to spaces, position-preserving. The default `scan` keeps
+    // plain-string bodies VERBATIM (so callers can read `register('tag')`),
+    // which would let an `import`/`export` inside a string be matched, so use
+    // the fully-blanked view for both the export map and the import scan. The
+    // real specifier is read back from `content` at the same (length-preserved)
+    // offset.
+    const maskedByAbs = new Map();
+    for (const f of files) maskedByAbs.set(f.abs, redactStringsAndTemplates(f.content, true));
+    const exportsByAbs = new Map();
+    for (const f of files) exportsByAbs.set(f.abs, enumerableExports(maskedByAbs.get(f.abs)));
+    // `import\s+` excludes `import.meta` and a dynamic `import(`. The clause is
+    // `[^'";]*?` so it cannot swallow a side-effect `import '...'` (its quote) or
+    // bridge across a `;` into the next statement's `from`.
+    const reImport = /\bimport\s+([^'";]*?)\bfrom\s*(['"])/g;
+    for (const { abs, rel, content } of files) {
+      const masked = maskedByAbs.get(abs);
+      reImport.lastIndex = 0;
+      let m;
+      while ((m = reImport.exec(masked))) {
+        const quote = m[2];
+        const specStart = reImport.lastIndex;           // just past the opening quote
+        const specEnd = content.indexOf(quote, specStart);
+        if (specEnd < 0) continue;
+        const spec = content.slice(specStart, specEnd);
+        if (!/^(?:\.|#)/.test(spec)) continue; // app-internal only (relative or #alias)
+        const names = importedValueNames(m[1]);
+        if (!names || names.length === 0) continue;
+        const target = resolveImport(spec, abs, appDir);
+        const exp = exportsByAbs.get(target);
+        if (exp == null) continue; // not an app file, or exports not enumerable
+        for (const name of names) {
+          if (exp.has(name)) continue;
+          violations.push({
+            rule: 'no-missing-local-import',
+            file: rel,
+            message: `Imports \`${name}\` from \`${spec}\`, but that module does not export \`${name}\`. The binding is undefined at runtime and crashes on first use (often a renamed or removed export, e.g. a dropped schema table).`,
+            fix: `Add \`${name}\` to \`${spec}\`, correct the imported name, or remove the import.`,
+          });
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Rule: `form-action-not-a-get-action`.
+ *
+ * @param {string} appDir  absolute path to the app root
+ * @param {ScannedFile[]} files  every JS/TS file in the app, raw and redacted
+ * @param {Violation[]} violations  accumulator the rule pushes onto
+ * @returns {void}
+ */
+export function checkFormActionNotAGetAction(appDir, files, violations) {
+  // --- Rule: form-action-not-a-get-action (#1155) ---
+  // `<form action=${fn}>` binds a server action to a POST submission. An action
+  // declaring `method = 'GET'` cannot serve one: it is CSRF-exempt and takes its
+  // args in the url, so the dispatcher answers 405. Catch it at edit time.
+  {
+    // A `'use server'` file's declared method, or absent when it declares none.
+    const methodByAbs = new Map();
+    for (const f of files) {
+      if (!/\.server\.m?[jt]s$/.test(f.rel)) continue;
+      if (!hasUseServerDirective(f.content)) continue;
+      const m = /\bexport\s+const\s+method\s*(?::[^=]*)?=\s*['"`]([A-Za-z]+)['"`]/.exec(f.scan);
+      if (m) methodByAbs.set(f.abs, m[1].toUpperCase());
+    }
+    if (methodByAbs.size) {
+      const reImport = /\bimport\s+([^'";]*?)\bfrom\s*(['"])/g;
+      for (const { abs, rel, content } of files) {
+        // PLACEHOLDER redaction, not either mask, and the choice is forced.
+        // The default mask blanks a tagged template outright, so a real
+        // `html`<form action=${fn}>`` disappears and the rule could never fire;
+        // the fully-blanked mask does the same. Placeholder mode keeps `${...}`
+        // holes as REAL code while turning each literal BODY into one opaque
+        // `__STR_n__` token, so a live binding is readable and a `<form
+        // action=${x}>` shown as text inside a docs sample is a single token
+        // with no hole in it. That distinction is the whole carve-out: the
+        // framework's own website renders this exact shape as a code sample.
+        const { redacted, literals } = redactToPlaceholders(content);
+        // Both binding shapes count the same here: `action=` on a `<form>`
+        // (#1155) and `formaction=` on a `<button>` / `<input>` submitter
+        // (#1207) each put the named action behind a form submission, and a
+        // GET-declared action cannot serve either. `classifyActionHole` owns
+        // the tag-and-attribute pairing (js-scan.js).
+        const bound = new Set();
+        for (const m of redacted.matchAll(/__STR_(\d+)__\$\{\s*([A-Za-z_$][\w$]*)\s*\}/g)) {
+          if (!classifyActionHole(literals[Number(m[1])] || '')) continue;
+          bound.add(m[2]);
+        }
+        if (!bound.size) continue;
+        reImport.lastIndex = 0;
+        let im;
+        while ((im = reImport.exec(redacted))) {
+          // The specifier is a placeholder token in this view, so read the real
+          // one back out of `literals`.
+          const tok = /__STR_(\d+)__/.exec(redacted.slice(reImport.lastIndex, reImport.lastIndex + 24));
+          if (!tok) continue;
+          const spec = literals[Number(tok[1])] || '';
+          if (!/^(?:\.|#)/.test(spec)) continue;
+          const names = importedLocalNames(im[1]);
+          if (!names.length) continue;
+          const target = resolveImport(spec, abs, appDir);
+          // ONLY a GET is contradictory, and the rule must say exactly what the
+          // dispatcher does or it is a false positive. A browser form always
+          // submits as a POST, and the dispatcher runs a PUT / PATCH / DELETE
+          // action on that POST: the declared verb governs the RPC transport,
+          // not whether the function can serve a form. A GET is different in
+          // kind (CSRF-exempt, args in the url, no body), which is why it is
+          // the one the dispatcher answers with a 405.
+          const method = target ? methodByAbs.get(target) : undefined;
+          if (method !== 'GET') continue;
+          for (const { local, imported } of names) {
+            if (!bound.has(local)) continue;
+            violations.push({
+              rule: 'form-action-not-a-get-action',
+              file: rel,
+              message: `Binds \`${imported}\` to a form, but \`${spec}\` declares \`method = 'GET'\`. A GET action rides its arguments in the url and skips the CSRF check, so it cannot answer a form POST; the submission is a 405.`,
+              fix: `Drop the \`method\` export from \`${spec}\` (an action with no method is a POST, which is what a form submits), or bind an action that takes a POST.`,
+            });
+          }
+        }
+      }
+    }
+  }
+}

package/src/check/rules-registry.js

@@ -0,0 +1,128 @@
+/**
+ * Custom-element registry rules: tag-name validity and uniqueness across the app.
+ *
+ * Lifted verbatim out of checkConventions, which held all twenty rules inline
+ * in one 900-line function. Each rule keeps its original comment header, its
+ * logic, and its position in the run order.
+ */
+import { join } from 'node:path';
+import {
+  isComponentFile,
+} from './helpers.js';
+import {
+  gitIgnoredSet,
+} from './runner-support.js';
+
+/**
+ * @typedef {import('./rules.js').Violation} Violation
+ * @typedef {{ abs: string, rel: string, content: string, scan: string }} ScannedFile
+ */
+
+
+/**
+ * Rule: `tag-name-has-hyphen`.
+ *
+ * @param {ScannedFile[]} files  every JS/TS file in the app, raw and redacted
+ * @param {Violation[]} violations  accumulator the rule pushes onto
+ * @returns {void}
+ */
+export function checkTagNameHasHyphen(files, violations) {
+  // --- Rule: tag-name-has-hyphen ---
+  {
+    for (const { rel, scan } of files) {
+      if (!isComponentFile(rel)) continue;
+      // Use redacted source. A `register('tag')` call inside a
+      // TAGGED template literal (docs-page code example) is blanked.
+      // Calls at top level keep their structure AND their string
+      // argument. Quote style can be ', ", or ` (untagged backtick
+      // literals survive the redactor, like single/double-quote
+      // strings).
+      const patterns = [
+        // Class.register('tag') / register("tag") / register(`tag`)
+        /\b[A-Z][A-Za-z0-9_$]*\.register\s*\(\s*(['"`])([^'"`]+)\1/g,
+        // customElements.define('tag', Class) and quote variants
+        /\bcustomElements\.define\s*\(\s*(['"`])([^'"`]+)\1/g,
+      ];
+      for (const re of patterns) {
+        let match;
+        while ((match = re.exec(scan)) !== null) {
+          const tagName = match[2];
+          if (!tagName.includes('-')) {
+            violations.push({
+              rule: 'tag-name-has-hyphen',
+              file: rel,
+              message: `Custom element tag "${tagName}" must contain a hyphen`,
+              fix: `Rename to a hyphenated tag name, e.g. "app-${tagName}" or "${tagName}-element"`,
+            });
+          }
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Rule: `no-duplicate-tag`.
+ *
+ * @param {string} appDir  absolute path to the app root
+ * @param {ScannedFile[]} files  every JS/TS file in the app, raw and redacted
+ * @param {Violation[]} violations  accumulator the rule pushes onto
+ * @returns {Promise<void>}
+ */
+export async function checkNoDuplicateTag(appDir, files, violations) {
+  // --- Rule: no-duplicate-tag ---
+  // Two registrations of the SAME tag string anywhere in the app resolve
+  // inconsistently at runtime (SSR last-wins, browser first-wins), so flag
+  // every colliding site naming the others. Scans EVERY source file, not just
+  // components/, because a duplicate is a runtime hazard regardless of where
+  // the register/define call lives (a page, a lib, a module can register a
+  // tag too); this keeps the rule in lockstep with the editor's 9004
+  // diagnostic, which is likewise project-wide. Reuses the same
+  // register/define extraction as tag-name-has-hyphen, over the redacted
+  // source so a tag in a docs-page tagged-template example does not count.
+  // Only hyphenated tags are considered (a non-hyphenated tag is already
+  // flagged by tag-name-has-hyphen / invariant 3), matching the 9004 filter.
+  {
+    // Generated / gitignored files (e.g. a `webjs ui add`-regenerated
+    // `components/` dir) are not committed source the rule should police;
+    // counting them would flag a collision between a hand-written component
+    // and its generated copy. Skip anything git reports as ignored.
+    // Best-effort: a non-git project (or absent git) scans everything.
+    const ignored = await gitIgnoredSet(appDir, files.map((f) => f.rel));
+    /** @type {Map<string, string[]>} tag -> rel files that register it (with repeats) */
+    const tagSites = new Map();
+    const patterns = [
+      /\b[A-Z][A-Za-z0-9_$]*\.register\s*\(\s*(['"`])([^'"`]+)\1/g,
+      /\bcustomElements\.define\s*\(\s*(['"`])([^'"`]+)\1/g,
+    ];
+    for (const { scan, rel } of files) {
+      if (ignored.has(rel)) continue;
+      for (const re of patterns) {
+        let match;
+        while ((match = re.exec(scan)) !== null) {
+          const tagName = match[2];
+          if (!tagName.includes('-')) continue;
+          const arr = tagSites.get(tagName) || [];
+          arr.push(rel);
+          tagSites.set(tagName, arr);
+        }
+      }
+    }
+    for (const [tagName, sites] of tagSites) {
+      if (sites.length < 2) continue;
+      // Report once per DISTINCT file, naming the others.
+      for (const file of new Set(sites)) {
+        const others = [...new Set(sites)].filter((f) => f !== file);
+        const where = others.length
+          ? `also registered in ${others.join(', ')}`
+          : 'registered more than once in this file';
+        violations.push({
+          rule: 'no-duplicate-tag',
+          file,
+          message: `Custom element tag "${tagName}" is registered more than once (${where}). A tag must be registered exactly once; the runtime resolves a duplicate inconsistently (SSR keeps the last registration, the browser keeps the first).`,
+          fix: `Rename one registration so each "${tagName}" is unique, e.g. "${tagName}-2".`,
+        });
+      }
+    }
+  }
+}