@usefragments/core 1.0.0

package/src/rules/components-prefer-library.ts

@@ -0,0 +1,943 @@
+import type { CanonicalSource, GovernanceSeverity } from "../governance.js";
+import type {
+  FactIndex,
+  UsageImportFact,
+  UsageNodeFact,
+  UsagePropResolvedFact,
+  UsageTextChildFact,
+} from "../facts/index.js";
+import {
+  isEnforceableHtmlEquivalent,
+  isRawHtmlAdvisoryTier,
+  resolveCanonicalForAriaRole,
+  resolveCanonicalForRawHtml,
+  type RawHtmlPrecisionTier,
+} from "../raw-html-canonical.js";
+import { ownedImportMatchesRoot, ownedImportsEqual } from "../package-identity-match.js";
+
+import { makeFinding } from "./finding.js";
+import type { Finding } from "./types.js";
+import { indexPropsByNodeId, indexTextChildrenByNodeId } from "./utils.js";
+
+export const RULE_ID = "components/prefer-library";
+export const RULE_VERSION = "1";
+
+interface CanonicalMappingOption {
+  name: string;
+  canonical?: string;
+  htmlEquivalent?: string;
+  /**
+   * ARIA role of the canonical primitive this mapping points at (e.g. `status`
+   * for Toast, `alert` for Alert). Lets the rule key on element *semantics*
+   * rather than the raw tag name, so a bespoke `<div role="status">` re-impl is
+   * flagged structurally — not just literal tag/import matches.
+   */
+  ariaRole?: string;
+  /**
+   * Intrinsic input `type` of the canonical primitive this mapping points at
+   * (e.g. `checkbox` for Checkbox, `radio` for RadioGroup). Only meaningful when
+   * `htmlEquivalent === "input"`: it discriminates one raw `<input>` from
+   * another so a library can map `<input type="checkbox">` → Checkbox and
+   * `<input type="radio">` → RadioGroup independently. Unset → matches any
+   * `<input>` regardless of type (backward-compatible tag-level match).
+   */
+  htmlType?: string;
+  importPath?: string;
+  propMapping?: Array<{
+    rawProp: string;
+    canonicalProp: string;
+    valueMap?: Record<string, string>;
+  }>;
+  confidence?: number;
+  /**
+   * The `htmlEquivalent` was EXPLICITLY declared by the project (provenance:
+   * `localCanonical.resolves`), not inferred. Lets the enforceability gate fire
+   * a specific interactive tag (button/a) against any canonical NAME — the
+   * library-agnostic path — without re-opening the inferred-htmlEquivalent flood.
+   */
+  declaredHtmlEquivalent?: boolean;
+}
+
+function isExplicitTagDeclaration(mapping: CanonicalMappingOption): boolean {
+  return mapping.declaredHtmlEquivalent === true;
+}
+
+/** Advisory findings never exceed `warn`, whatever the project configured. */
+function capAdvisorySeverity(configured: GovernanceSeverity | undefined): GovernanceSeverity {
+  const base = configured ?? "warn";
+  return base === "error" ? "warn" : base;
+}
+
+/**
+ * Advisory-precision matches (role-reimpl, interactive-nonsemantic, html-advisory,
+ * icon-only) are lower-confidence and never carry a deterministic fix, so they must
+ * never hard-block a write or hard-fail CI. Cap their severity at `warn` even when a
+ * project raises `components/prefer-library` to `error` — only the confident
+ * exact-html / input-type tiers inherit the escalated severity. (The blocking hook's
+ * `isDenyEligible` also refuses to deny `attributes.advisory` findings; this keeps
+ * the CI severity honest to the same confidence line.)
+ */
+function severityForTier(
+  configured: GovernanceSeverity | undefined,
+  tier: RawHtmlPrecisionTier
+): GovernanceSeverity {
+  return isRawHtmlAdvisoryTier(tier) ? capAdvisorySeverity(configured) : (configured ?? "warn");
+}
+
+/**
+ * Generic structural / typography / primitive class names that routinely appear
+ * as plain layout classes even in fully-canonical codebases. Even when one equals
+ * a canonical component name (Box, Grid, Stack, List, Text…), a `<div class="box">`
+ * is almost never a hand-rolled component — so they are excluded from the
+ * className-reimplementation heuristic to keep it low-noise. Distinctive component
+ * names (card, badge, alert, dialog, tooltip, drawer, accordion, chip…) are NOT
+ * listed here, so they still flag.
+ */
+const GENERIC_CLASSNAME_DENYLIST: ReadonlySet<string> = new Set([
+  "box",
+  "grid",
+  "stack",
+  "row",
+  "col",
+  "cols",
+  "column",
+  "columns",
+  "flex",
+  "wrap",
+  "wrapper",
+  "container",
+  "content",
+  "inner",
+  "outer",
+  "main",
+  "root",
+  "layout",
+  "panel",
+  "group",
+  "area",
+  "block",
+  "section",
+  "item",
+  "items",
+  "entry",
+  "list",
+  "header",
+  "heading",
+  "footer",
+  "nav",
+  "navbar",
+  "bar",
+  "toolbar",
+  "sidebar",
+  "aside",
+  "body",
+  "cell",
+  "title",
+  "subtitle",
+  "label",
+  "caption",
+  "text",
+  "copy",
+  "icon",
+  "img",
+  "image",
+  "media",
+  "link",
+  "links",
+  "button",
+  "btn",
+  "input",
+  "field",
+  "fields",
+  "form",
+  "control",
+  "controls",
+  "menu",
+  "dropdown",
+  "table",
+  "page",
+  "view",
+  "screen",
+  "overlay",
+  "backdrop",
+  "spacer",
+  "divider",
+  "separator",
+  "line",
+  "dot",
+  "tabs",
+]);
+
+interface ReimplTarget {
+  name: string;
+  import?: string;
+}
+
+/** lowercased class token → the canonical component it likely reimplements. */
+function canonicalReimplTargets(
+  sources: readonly CanonicalSource[],
+  mappings: readonly CanonicalMappingOption[]
+): Map<string, ReimplTarget> {
+  const out = new Map<string, ReimplTarget>();
+  const add = (name: string | undefined, importPath: string | undefined) => {
+    if (!name || !isIdentifier(name)) return;
+    const key = name.toLowerCase();
+    if (GENERIC_CLASSNAME_DENYLIST.has(key) || out.has(key)) return;
+    out.set(key, { name, ...(importPath ? { import: importPath } : {}) });
+  };
+  for (const mapping of mappings) add(mapping.name, mapping.importPath);
+  for (const source of sources) {
+    const label = sourceLabel(source);
+    for (const name of source.include ?? []) add(name, label);
+  }
+  return out;
+}
+
+/** The CSS-module member of a `styles.card` / `styles["card"]` snippet, or null. */
+function classMemberFromSnippet(snippet: string): string | null {
+  const bracket = /\[\s*["'`]([A-Za-z0-9_-]+)["'`]\s*\]\s*$/.exec(snippet);
+  if (bracket) return bracket[1];
+  const dot = /\.([A-Za-z_$][\w$]*)\s*$/.exec(snippet);
+  return dot ? dot[1] : null;
+}
+
+/** Candidate class-name tokens per node: literal classes + resolvable module members. */
+function indexClassTokensByNode(ix: FactIndex): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  const push = (nodeId: string, token: string | null) => {
+    if (!token) return;
+    const list = out.get(nodeId);
+    if (list) list.push(token);
+    else out.set(nodeId, [token]);
+  };
+  for (const fact of ix.byKind("classname_literal")) {
+    for (const cls of fact.classes) push(fact.nodeId, cls);
+  }
+  for (const fact of ix.byKind("classname_dynamic")) {
+    // Only the `styles.card` identifier form yields a clean member name; clsx()/
+    // template/spread forms are too fuzzy to key a suggestion on.
+    if (fact.reason !== "identifier") continue;
+    push(fact.nodeId, classMemberFromSnippet(fact.snippet));
+  }
+  return out;
+}
+
+interface ClassNameReimplMatch {
+  canonical: string;
+  matchedClass: string;
+  import?: string;
+}
+
+function findClassNameReimpl(
+  node: UsageNodeFact,
+  classTokensByNode: Map<string, string[]>,
+  targets: Map<string, ReimplTarget>
+): ClassNameReimplMatch | null {
+  const tokens = classTokensByNode.get(node.id);
+  if (!tokens) return null;
+  for (const token of tokens) {
+    const target = targets.get(token.toLowerCase());
+    if (target) {
+      return {
+        canonical: target.name,
+        matchedClass: token,
+        ...(target.import ? { import: target.import } : {}),
+      };
+    }
+  }
+  return null;
+}
+
+export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
+  const policy = ix.policy.ruleConfig(RULE_ID);
+  if (!policy?.enabled) return [];
+  const sources = canonicalSourcesFromPolicy(policy.options?.canonicalSources);
+  const mappings = canonicalMappingsFromPolicy(policy.options?.canonicalMappings);
+  if (sources.length === 0 && mappings.length === 0) return [];
+
+  const importsByFileAndLocal = indexImportsByFileAndLocal(ix);
+  const propsByNode = indexPropsByNodeId(ix);
+  const textByNode = indexTextChildrenByNodeId(ix);
+  const classTokensByNode = indexClassTokensByNode(ix);
+  const reimplTargets = canonicalReimplTargets(sources, mappings);
+  const findings: Finding[] = [];
+  const seenImportFixes = new Set<string>();
+
+  for (const node of ix.byKind("usage_node")) {
+    if (isCanonicalSourceImplementationFile(node.file, sources)) continue;
+    if (node.element.includes(".")) continue;
+    const props = propsByNode.get(node.id) ?? [];
+    const textChildren = textByNode.get(node.id) ?? [];
+    const imported = importsByFileAndLocal.get(node.file)?.get(node.element);
+    const nodeInputType =
+      node.element === "input" ? readStaticStringProp(props, "type") : undefined;
+    const mapped = findMapping(node, nodeInputType, mappings);
+    if (mapped && imported && isMappedCanonicalImport(imported, mapped)) continue;
+    if (imported && isCanonicalImport(imported, node.element, sources)) continue;
+
+    if (mapped) {
+      if (!shouldSuggestMapped(node, nodeInputType, imported, mapped)) continue;
+      const importPath = mapped.importPath;
+      const suggestedComponent = mapped.name;
+      const suggestedImport = importPath ?? "the canonical library";
+      const propMapping = mapped.propMapping ?? [];
+      const roleMatch = isRoleMatch(node, mapped);
+      const precisionTier: RawHtmlPrecisionTier = roleMatch ? "role-reimpl" : "exact-html";
+
+      if (
+        imported &&
+        importPath &&
+        !ownedImportsEqual(imported.source, importPath) &&
+        node.element === suggestedComponent
+      ) {
+        const key = `${imported.file}\0${imported.local}\0${imported.source}\0${importPath}`;
+        if (seenImportFixes.has(key)) continue;
+        seenImportFixes.add(key);
+        findings.push(
+          makeFinding({
+            ruleId: RULE_ID,
+            ruleVersion: RULE_VERSION,
+            severity: policy.severity ?? "warn",
+            message: `<${node.element}> should import from ${importPath}.`,
+            location: imported.location,
+            evidence: ix.evidence([node.id, imported.id, policy.id]),
+            fingerprintIdentity: {
+              file: imported.file,
+              local: imported.local,
+              from: imported.source,
+              to: importPath,
+            },
+            fix: {
+              kind: "replaceImport",
+              title: `Replace import path with "${importPath}"`,
+              from: imported.source,
+              to: importPath,
+              deterministic: true,
+            },
+            attributes: {
+              rawValue: imported.source,
+              suggestedComponent,
+              suggestedImport: importPath,
+              canonical: mapped.canonical,
+              confidence: mapped.confidence,
+            },
+          })
+        );
+        continue;
+      }
+
+      // No-op guard: the element already IS the suggested canonical (any
+      // wrong-import-path fix was handled just above). "Replace <X> with <X>"
+      // is not drift — skip it. This kills the icon self-mappings
+      // (e.g. <GitBranch> → <GitBranch>) that floated up as noise.
+      if (node.element === suggestedComponent) continue;
+
+      findings.push(
+        makeFinding({
+          ruleId: RULE_ID,
+          ruleVersion: RULE_VERSION,
+          severity: severityForTier(policy.severity, precisionTier),
+          message:
+            node.element === "button"
+              ? `Bespoke <button> has a library equivalent. Swap to <${suggestedComponent}> from ${suggestedImport}.`
+              : roleMatch
+                ? `Custom <${node.element} role="${node.role}"> reimplements a primitive. Use <${suggestedComponent}> from ${suggestedImport}.`
+                : `Bespoke <${node.element}> should use <${suggestedComponent}> from ${suggestedImport}.`,
+          location: node.location,
+          evidence: ix.evidence(
+            imported ? [node.id, imported.id, policy.id] : [node.id, policy.id]
+          ),
+          fingerprintIdentity: {
+            file: node.file,
+            nodePath: node.nodePath,
+            element: node.element,
+            suggestedComponent,
+            suggestedImport,
+          },
+          ...(!isRawHtmlAdvisoryTier(precisionTier) &&
+          isIdentifier(node.element) &&
+          isIdentifier(suggestedComponent)
+            ? {
+                fix: {
+                  kind: "replaceComponent" as const,
+                  title: `Replace <${node.element}> with <${suggestedComponent}>`,
+                  from: node.element,
+                  to: suggestedComponent,
+                  deterministic: true,
+                },
+              }
+            : {}),
+          attributes: {
+            rawValue: node.element,
+            suggestedComponent,
+            suggestedImport,
+            canonical: mapped.canonical,
+            confidence: mapped.confidence,
+            propMapping,
+            precisionTier,
+            ...(roleMatch ? { matchedRole: node.role } : {}),
+          },
+        })
+      );
+      continue;
+    }
+
+    // #2 — className reimplementation heuristic (advisory-only). A plain
+    // <div>/<span> with no ARIA role and no handler whose class name matches a
+    // canonical component name is very likely a hand-rolled reimplementation
+    // (`<div className={styles.card}>` for a Card). class-name↔component is a
+    // naming-intent signal, not structural proof — so this is advisory, capped at
+    // warn, carries no auto-fix, and never blocks a write (see emit-gate).
+    if (
+      (node.element === "div" || node.element === "span") &&
+      node.role === undefined &&
+      node.interactive !== true &&
+      !hasEventHandler(props)
+    ) {
+      const reimpl = findClassNameReimpl(node, classTokensByNode, reimplTargets);
+      if (reimpl) {
+        const suggestedImport = reimpl.import ?? "the canonical library";
+        findings.push(
+          makeFinding({
+            ruleId: RULE_ID,
+            ruleVersion: RULE_VERSION,
+            severity: capAdvisorySeverity(policy.severity),
+            message: `<${node.element} class="${reimpl.matchedClass}"> looks like a hand-rolled <${reimpl.canonical}>. Use <${reimpl.canonical}> from ${suggestedImport} instead of restyling a <${node.element}>.`,
+            location: node.location,
+            evidence: ix.evidence([node.id, policy.id]),
+            fingerprintIdentity: {
+              file: node.file,
+              nodePath: node.nodePath,
+              element: node.element,
+              suggestedComponent: reimpl.canonical,
+              matchedClass: reimpl.matchedClass,
+            },
+            attributes: {
+              rawValue: node.element,
+              suggestedComponent: reimpl.canonical,
+              ...(reimpl.import ? { suggestedImport: reimpl.import } : {}),
+              precisionTier: "classname-reimpl",
+              matchedClass: reimpl.matchedClass,
+              advisory: true,
+            },
+          })
+        );
+        continue;
+      }
+    }
+
+    const builtIn = findBuiltInRawHtmlMatch(node, props, textChildren, nodeInputType);
+    const suggestedComponent =
+      builtIn?.canonical ?? (node.element === "button" ? "Button" : node.element);
+    const suggestion = findSuggestionSource(suggestedComponent, sources);
+    if (!suggestion) continue;
+    if (!builtIn && !shouldSuggest(node, imported)) continue;
+    // Directory canonical sources are typically derived without an `include`
+    // filter (cloud pushes `{ kind: "directory", path }` for every component
+    // folder), so `sourceIncludesComponent` matches EVERY name. Without the same
+    // guards #224 added to the mapped path, that turns every imported component
+    // — Phosphor icons included — into a no-op `<X> → <X>` finding, and lets a
+    // non-enforceable raw-tag match (`<button>` → a non-Button canonical) slip
+    // through. Hold the directory path to the semantic-only contract:
+    //   (i)   never a no-op (element already IS the suggestion),
+    //   (ii)  only raw lowercase HTML tags are targets (an already-capitalized
+    //         component is not a prefer-library candidate for a directory source),
+    //   (iii) only when the raw tag → canonical mapping is enforceable
+    //         (isEnforceableHtmlEquivalent) — so `<button>` → Button fires but a
+    //         disagreeing `<button>` → Chip does not.
+    // npm/registry sources are curated (specifier + usual include lists) and keep
+    // their import-redirect behavior, so this gate is directory-scoped only.
+    if (suggestion.kind === "directory") {
+      if (node.element === suggestedComponent) continue;
+      if (!builtIn) continue;
+      if (isIdentifier(node.element) && /^[A-Z]/.test(node.element)) continue;
+      if (
+        !isEnforceableHtmlEquivalent({
+          tag: node.element,
+          canonical: suggestedComponent,
+          inputType: nodeInputType,
+        })
+      ) {
+        continue;
+      }
+    }
+    const suggestedImport = sourceLabel(suggestion);
+    const precisionTier = builtIn?.tier ?? "exact-html";
+    const rawElement = formatRawElement(node, props);
+
+    findings.push(
+      makeFinding({
+        ruleId: RULE_ID,
+        ruleVersion: RULE_VERSION,
+        severity: severityForTier(policy.severity, precisionTier),
+        message: messageForBuiltInMatch({
+          node,
+          rawElement,
+          suggestedComponent,
+          suggestedImport,
+          precisionTier,
+        }),
+        location: node.location,
+        evidence: ix.evidence(imported ? [node.id, imported.id, policy.id] : [node.id, policy.id]),
+        fingerprintIdentity: {
+          file: node.file,
+          nodePath: node.nodePath,
+          element: node.element,
+          suggestedComponent,
+          suggestedImport,
+        },
+        ...(!isRawHtmlAdvisoryTier(precisionTier) &&
+        isIdentifier(node.element) &&
+        isIdentifier(suggestedComponent)
+          ? {
+              fix: {
+                kind: "replaceComponent" as const,
+                title: `Replace ${rawElement} with <${suggestedComponent}>`,
+                from: node.element,
+                to: suggestedComponent,
+                deterministic: true,
+              },
+            }
+          : {}),
+        attributes: {
+          rawValue: node.element,
+          suggestedComponent,
+          suggestedImport,
+          suggestedImportSourceKind: suggestion.kind,
+          precisionTier,
+          ...(builtIn?.matchedRole ? { matchedRole: builtIn.matchedRole } : {}),
+          ...(builtIn?.inputType ? { matchedInputType: builtIn.inputType } : {}),
+          ...(isRawHtmlAdvisoryTier(precisionTier) ? { advisory: true } : {}),
+        },
+      })
+    );
+  }
+
+  return findings;
+}
+
+interface BuiltInRawHtmlMatch {
+  canonical: string;
+  tier: RawHtmlPrecisionTier;
+  matchedRole?: string;
+  inputType?: string;
+}
+
+function findBuiltInRawHtmlMatch(
+  node: UsageNodeFact,
+  props: readonly UsagePropResolvedFact[],
+  textChildren: readonly UsageTextChildFact[],
+  inputType: string | undefined
+): BuiltInRawHtmlMatch | null {
+  if (isIconOnlyButton(node, props, textChildren)) {
+    return { canonical: "IconButton", tier: "icon-only" };
+  }
+
+  const rawMatch = resolveCanonicalForRawHtml(node.element, inputType);
+  if (rawMatch) {
+    return {
+      ...rawMatch,
+      ...(inputType ? { inputType } : {}),
+    };
+  }
+
+  if (node.role && isRoleReimplementationHost(node.element)) {
+    const roleMatch = resolveCanonicalForAriaRole(node.role);
+    if (roleMatch) {
+      return {
+        ...roleMatch,
+        matchedRole: node.role,
+      };
+    }
+  }
+
+  if (
+    (node.element === "div" || node.element === "span") &&
+    node.role === undefined &&
+    node.interactive === true &&
+    hasEventHandler(props)
+  ) {
+    return { canonical: "Button", tier: "interactive-nonsemantic" };
+  }
+
+  return null;
+}
+
+function isIconOnlyButton(
+  node: UsageNodeFact,
+  props: readonly UsagePropResolvedFact[],
+  textChildren: readonly UsageTextChildFact[]
+): boolean {
+  if (node.element !== "button") return false;
+  if (node.interactive !== true && !hasEventHandler(props)) return false;
+  if (!hasExplicitAriaName(props)) return false;
+  return !hasVisibleText(textChildren);
+}
+
+function isRoleReimplementationHost(element: string): boolean {
+  return element === "div" || element === "span" || element === "a";
+}
+
+function hasEventHandler(props: readonly UsagePropResolvedFact[]): boolean {
+  return props.some((prop) => /^on[A-Z]/.test(prop.prop));
+}
+
+function hasExplicitAriaName(props: readonly UsagePropResolvedFact[]): boolean {
+  return props.some(
+    (prop) =>
+      (prop.prop === "aria-label" || prop.prop === "aria-labelledby") &&
+      prop.resolution === "static" &&
+      typeof prop.value === "string" &&
+      prop.value.trim().length > 0
+  );
+}
+
+function hasVisibleText(textChildren: readonly UsageTextChildFact[]): boolean {
+  return textChildren.some((child) => child.text.trim().length > 0);
+}
+
+function readStaticStringProp(
+  props: readonly UsagePropResolvedFact[],
+  propName: string
+): string | undefined {
+  const prop = props.find((candidate) => candidate.prop === propName);
+  if (!prop || prop.resolution !== "static") return undefined;
+  return typeof prop.value === "string" ? prop.value : undefined;
+}
+
+function formatRawElement(node: UsageNodeFact, props: readonly UsagePropResolvedFact[]): string {
+  if (node.element === "input") {
+    const inputType = readStaticStringProp(props, "type");
+    if (inputType) return `<input type="${inputType}">`;
+  }
+  if (node.role) return `<${node.element} role="${node.role}">`;
+  return `<${node.element}>`;
+}
+
+function messageForBuiltInMatch({
+  node,
+  rawElement,
+  suggestedComponent,
+  suggestedImport,
+  precisionTier,
+}: {
+  node: UsageNodeFact;
+  rawElement: string;
+  suggestedComponent: string;
+  suggestedImport: string;
+  precisionTier: RawHtmlPrecisionTier;
+}) {
+  if (precisionTier === "icon-only") {
+    return `Icon-only ${rawElement} should use <${suggestedComponent}> from ${suggestedImport}.`;
+  }
+  if (precisionTier === "role-reimpl") {
+    return `Custom ${rawElement} reimplements a primitive. Use <${suggestedComponent}> from ${suggestedImport}.`;
+  }
+  if (precisionTier === "interactive-nonsemantic") {
+    return `Interactive <${node.element}> reimplements a Button. Use <${suggestedComponent}> from ${suggestedImport}.`;
+  }
+  if (node.element === "button") {
+    return `Bespoke <button> has a library equivalent. Swap to <Button> from ${suggestedImport}.`;
+  }
+  return `Bespoke ${rawElement} should use <${suggestedComponent}> from ${suggestedImport}.`;
+}
+
+function shouldSuggestMapped(
+  node: UsageNodeFact,
+  nodeInputType: string | undefined,
+  imported: UsageImportFact | undefined,
+  mapping: CanonicalMappingOption
+): boolean {
+  if (
+    sameHtmlTag(mapping.htmlEquivalent, node.element) &&
+    // Enforceability is checked against `mapping.name` — the component this rule
+    // actually EMITS as `suggestedComponent` — not `mapping.canonical`. For
+    // ambiguous/common tags (button, a) `isEnforceableHtmlEquivalent` requires
+    // agreement with the curated canonical, so a Chip whose `canonical: "Button"`
+    // but `name: "Chip"` no longer leaks `suggestedComponent: "Chip"` while the
+    // canonical reads "Button". `<button>` → Button (name === canonical) still
+    // fires; semantic tags (textarea → Textarea) are unaffected (always
+    // enforceable regardless of name).
+    isEnforceableHtmlEquivalent({
+      tag: node.element,
+      canonical: mapping.name,
+      inputType: nodeInputType,
+      explicit: isExplicitTagDeclaration(mapping),
+    })
+  ) {
+    return true;
+  }
+  if (node.role !== undefined && node.role === mapping.ariaRole) return true;
+  // Only a literal use of the component's own NAME (e.g. <Modal> for name
+  // "Modal") is a candidate here — resolved as an import-redirect / no-op by the
+  // caller. We deliberately do NOT match on `mapping.canonical` (the vocabulary
+  // id): when name === canonical this clause would be redundant (the htmlEquivalent
+  // / name paths already cover it), and when they diverge (name "Modal", canonical
+  // "Dialog") matching `<Dialog>` only ever produced a self-contradicting swap
+  // (rawValue === canonical, suggestion is the renamed wrapper) and let any common
+  // vocab id (Dialog/Tooltip/Card) hijack an unrelated third-party usage. Same
+  // divergence principle as the button→Chip fix (#229) — audit #1/#2.
+  if (node.element === mapping.name) {
+    return imported !== undefined;
+  }
+  return false;
+}
+
+function shouldSuggest(node: UsageNodeFact, imported: UsageImportFact | undefined): boolean {
+  if (node.element === "button") return true;
+  if (!/^[A-Z]/.test(node.element)) return false;
+  return imported !== undefined;
+}
+
+/**
+ * Case-INSENSITIVE equality for the `htmlEquivalent` ↔ raw-tag comparison.
+ * Raw HTML tag names are case-insensitive, but a catalog/author can store a
+ * mis-cased `htmlEquivalent` ("Button", "INPUT"). The enforceability gate
+ * already lowercases internally, but the OUTER comparison gated whether the
+ * gate ran at all — so a mis-cased equivalent silently made a valid mapping
+ * inert (audit #29). Component NAME matches stay case-sensitive; only the
+ * raw-tag side is normalized here.
+ */
+function sameHtmlTag(htmlEquivalent: string | undefined, element: string): boolean {
+  return htmlEquivalent !== undefined && htmlEquivalent.toLowerCase() === element.toLowerCase();
+}
+
+function indexImportsByFileAndLocal(ix: FactIndex): Map<string, Map<string, UsageImportFact>> {
+  const out = new Map<string, Map<string, UsageImportFact>>();
+  for (const usage of ix.byKind("usage_import")) {
+    const importsForFile = out.get(usage.file) ?? new Map<string, UsageImportFact>();
+    importsForFile.set(usage.local, usage);
+    out.set(usage.file, importsForFile);
+  }
+  return out;
+}
+
+function canonicalSourcesFromPolicy(value: unknown): CanonicalSource[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter(isCanonicalSource);
+}
+
+function canonicalMappingsFromPolicy(value: unknown): CanonicalMappingOption[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter(isCanonicalMappingOption);
+}
+
+function isCanonicalMappingOption(value: unknown): value is CanonicalMappingOption {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  if (typeof record.name !== "string" || !isIdentifier(record.name)) return false;
+  if (record.canonical !== undefined && typeof record.canonical !== "string") return false;
+  if (record.htmlEquivalent !== undefined && typeof record.htmlEquivalent !== "string") {
+    return false;
+  }
+  if (record.ariaRole !== undefined && typeof record.ariaRole !== "string") return false;
+  if (record.htmlType !== undefined && typeof record.htmlType !== "string") return false;
+  if (record.importPath !== undefined && typeof record.importPath !== "string") return false;
+  if (record.confidence !== undefined && typeof record.confidence !== "number") return false;
+  if (
+    record.declaredHtmlEquivalent !== undefined &&
+    typeof record.declaredHtmlEquivalent !== "boolean"
+  ) {
+    return false;
+  }
+  if (record.propMapping !== undefined) {
+    if (!Array.isArray(record.propMapping)) return false;
+    if (!record.propMapping.every(isPropMappingOption)) return false;
+  }
+  return true;
+}
+
+function isPropMappingOption(
+  value: unknown
+): value is NonNullable<CanonicalMappingOption["propMapping"]>[number] {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record.rawProp === "string" &&
+    typeof record.canonicalProp === "string" &&
+    (record.valueMap === undefined || isStringRecord(record.valueMap))
+  );
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  return Object.values(value as Record<string, unknown>).every(
+    (entry) => typeof entry === "string"
+  );
+}
+
+function isCanonicalSource(value: unknown): value is CanonicalSource {
+  if (!value || typeof value !== "object") return false;
+  const record = value as Record<string, unknown>;
+  if (!hasValidComponentList(record.include)) return false;
+  if (!hasValidComponentList(record.exclude)) return false;
+  if (record.implementationPath !== undefined && typeof record.implementationPath !== "string") {
+    return false;
+  }
+  if (record.kind === "npm") return typeof record.specifier === "string";
+  if (record.kind === "directory") return typeof record.path === "string";
+  if (record.kind === "registry") {
+    return typeof record.registryId === "string" && typeof record.installPath === "string";
+  }
+  return false;
+}
+
+function hasValidComponentList(value: unknown): boolean {
+  return (
+    value === undefined || (Array.isArray(value) && value.every((item) => typeof item === "string"))
+  );
+}
+
+function findMapping(
+  node: UsageNodeFact,
+  nodeInputType: string | undefined,
+  mappings: readonly CanonicalMappingOption[]
+): CanonicalMappingOption | undefined {
+  // A type-specific input mapping wins over a generic tag-level one, so a
+  // library mapping `<input type="checkbox">` → Checkbox is never shadowed by a
+  // catch-all `<input>` → TextField entry. Normalized to lower-case to mirror
+  // the resolved `type` prop value the extractor records.
+  if (node.element === "input" && nodeInputType) {
+    const typed = mappings.find(
+      (mapping) =>
+        sameHtmlTag(mapping.htmlEquivalent, "input") &&
+        mapping.htmlType !== undefined &&
+        mapping.htmlType.toLowerCase() === nodeInputType.toLowerCase()
+    );
+    if (typed) return typed;
+  }
+
+  return mappings.find((mapping) => {
+    if (
+      sameHtmlTag(mapping.htmlEquivalent, node.element) &&
+      // Match enforceability against the EMITTED `mapping.name` (see
+      // shouldSuggestMapped): for ambiguous tags this requires the suggested
+      // component to BE the tag's curated canonical, so a disagreeing
+      // `<button>` → Chip mapping never matches in the first place.
+      isEnforceableHtmlEquivalent({
+        tag: node.element,
+        canonical: mapping.name,
+        inputType: nodeInputType,
+        explicit: isExplicitTagDeclaration(mapping),
+      })
+    ) {
+      // A type-constrained mapping only matches the matching input type; an
+      // unconstrained one matches any element with that tag (back-compat).
+      // Gated so an inferred `div`/`span` primitive (or a `button` → specialized
+      // component) never blanket-flags every container — see
+      // isEnforceableHtmlEquivalent.
+      return mapping.htmlType === undefined || matchesInputType(mapping, nodeInputType);
+    }
+    if (mapping.name === node.element) return true;
+    // Deliberately NOT matching on `mapping.canonical` (the vocabulary id): see
+    // shouldSuggestMapped. Selecting a mapping purely because the element name
+    // equals a canonical vocab id (Dialog/Tooltip/Card…) produced divergent swaps
+    // and cross-mapping hijacking (audit #1/#2). A real name match (above), an
+    // enforceable htmlEquivalent (above), or an ARIA-role match (below) remain.
+    // Semantic match: a bespoke element whose declared ARIA role equals the
+    // canonical primitive's role (e.g. `<div role="status">` → Toast). Keyed on
+    // normalized `usage_node.role`, so it is framework-agnostic.
+    return node.role !== undefined && mapping.ariaRole === node.role;
+  });
+}
+
+function matchesInputType(
+  mapping: CanonicalMappingOption,
+  nodeInputType: string | undefined
+): boolean {
+  if (mapping.htmlType === undefined) return true;
+  if (nodeInputType === undefined) return false;
+  return mapping.htmlType.toLowerCase() === nodeInputType.toLowerCase();
+}
+
+/** True when `mapped` was selected for `node` purely on an ARIA-role match. */
+function isRoleMatch(node: UsageNodeFact, mapping: CanonicalMappingOption): boolean {
+  return (
+    node.role !== undefined &&
+    node.role === mapping.ariaRole &&
+    node.element !== mapping.htmlEquivalent &&
+    node.element !== mapping.name &&
+    node.element !== mapping.canonical
+  );
+}
+
+function isMappedCanonicalImport(usage: UsageImportFact, mapping: CanonicalMappingOption): boolean {
+  return Boolean(mapping.importPath && ownedImportsEqual(usage.source, mapping.importPath));
+}
+
+function isCanonicalImport(
+  usage: UsageImportFact,
+  componentName: string,
+  sources: readonly CanonicalSource[]
+): boolean {
+  return sources.some((source) => {
+    if (!sourceIncludesComponent(source, componentName)) return false;
+    if (source.exclude?.includes(componentName)) return false;
+    if (source.kind === "npm") {
+      return ownedImportMatchesRoot(usage.source, source.specifier);
+    }
+    if (source.kind === "registry") {
+      if (!source.importPath) return false;
+      return ownedImportMatchesRoot(usage.source, source.importPath);
+    }
+    return normalizePath(usage.source).startsWith(normalizePath(source.path));
+  });
+}
+
+function findSuggestionSource(
+  componentName: string,
+  sources: readonly CanonicalSource[]
+): CanonicalSource | undefined {
+  return sources.find(
+    (source) =>
+      sourceIncludesComponent(source, componentName) && !source.exclude?.includes(componentName)
+  );
+}
+
+function sourceIncludesComponent(source: CanonicalSource, componentName: string): boolean {
+  if (source.include) return source.include.includes(componentName);
+  // Package-like canonical sources must be backed by an explicit export
+  // inventory before they can suggest arbitrary component names. Without this,
+  // a bare `{ kind: "npm", specifier: "@acme/ui" }` treats every imported
+  // PascalCase symbol as canonical and emits self-referential/noisy swaps.
+  if (source.kind === "npm" || source.kind === "registry") return false;
+  return true;
+}
+
+function sourceLabel(source: CanonicalSource): string {
+  if (source.kind === "npm") return source.specifier;
+  if (source.kind === "registry") return source.importPath ?? source.installPath;
+  return source.path;
+}
+
+function isCanonicalSourceImplementationFile(
+  file: string,
+  sources: readonly CanonicalSource[]
+): boolean {
+  const normalizedFile = normalizePath(file);
+  return sources.some((source) => {
+    if (source.kind === "npm" && source.implementationPath) {
+      return isPathInSource(normalizedFile, source.implementationPath);
+    }
+    if (source.kind === "directory") {
+      return isPathInSource(normalizedFile, source.path);
+    }
+    if (source.kind === "registry") {
+      return isPathInSource(normalizedFile, source.installPath);
+    }
+    return false;
+  });
+}
+
+function isPathInSource(file: string, sourcePath: string): boolean {
+  const normalizedSource = normalizePath(sourcePath).replace(/\/$/, "");
+  return file === normalizedSource || file.startsWith(`${normalizedSource}/`);
+}
+
+function normalizePath(path: string): string {
+  return path.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+function isIdentifier(value: string): boolean {
+  return /^[A-Za-z_$][\w$]*$/.test(value);
+}