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 { 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 &&
        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 && 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 usage.source === source.specifier || usage.source.startsWith(`${source.specifier}/`);
    }
    if (source.kind === "registry") {
      if (!source.importPath) return false;
      return usage.source === source.importPath || usage.source.startsWith(`${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);
}