import { describe, expect, it } from "vitest";

import {
  componentId as makeComponentId,
  defineFragment,
  FactIndex,
  compileComponentFacts,
  compileGlobalGovernanceFacts,
  g,
  makeClassNameDynamicFact,
  makeStyleDeclarationFact,
  makeTokenDefinitionFact,
  makeUsageComponentFact,
  makeUsageImportFact,
  makeUsageInlineStyleFact,
  makeUsageNodeFact,
  makeUsagePropResolvedFact,
  makeUsageTextChildFact,
  ruleA11yRequiredAccessibleName,
  ruleComponentsForbiddenPropValue,
  ruleComponentsPreferLibrary,
  ruleComponentsUnknownProp,
  ruleJsxPreferredComponent,
  ruleJsxPreferredImportPath,
  rulePropsInvalidValue,
  ruleStylesNoRawColor,
  ruleStylesNoRawDimensions,
  ruleStylesNoRawSpacing,
  ruleStylesNoRawTypography,
  ruleThemeNoThemeCoupledLiteral,
  ruleTokensRequireDualFallback,
  runRules,
} from "../index.js";
import type { Fact, FactId } from "../index.js";

type ButtonProps = {
  variant?: "primary" | "secondary" | "ghost" | "link";
  size?: "sm" | "md" | "lg";
  disabled?: boolean;
};

function Button(_props: ButtonProps) {
  return null;
}

const buttonId = makeComponentId("@fragments-sdk/ui", "Button");

function buildButtonFragment() {
  return defineFragment({
    component: Button,
    meta: {
      name: "Button",
      description: "Interactive element for user-triggered actions.",
      category: "forms",
    },
    guidance: {
      when: ["Submitting forms"],
      whenNot: ["Simple navigation without side effects"],
    },
    props: {
      variant: {
        type: "enum",
        values: ["primary", "secondary", "ghost", "link"],
        required: false,
      },
      size: { type: "enum", values: ["sm", "md", "lg"], required: false },
      disabled: { type: "boolean", required: false },
    },
    govern: (govern) => [
      govern.capability("dom.button"),
      govern.prop("variant").forbid("secondary", {
        when: { path: "apps/checkout/**" },
        because: "Checkout CTAs should stay visually dominant.",
        fix: { replaceWith: "primary" },
        severity: "error",
      }),
      govern.accessibility().requireName({
        because: "Buttons must announce their action.",
        severity: "error",
      }),
    ],
  });
}

function buildBaseConfigFacts() {
  return compileGlobalGovernanceFacts({
    scales: {
      space: g.scale.px([0, 4, 8, 12, 16, 20, 24, 32]),
    },
    styles: [
      g.styles.rawColors().forbid({
        except: ["transparent"],
        prefer: "token",
        severity: "error",
      }),
      g.styles.rawSpacing().mustMatchScale("space", {
        appliesTo: ["padding", "margin", "gap"],
        severity: "error",
      }),
    ],
    jsx: [g.jsx.unknownProps().forbid({ severity: "error" })],
  });
}

function emptyIndexWithGovernance(): FactIndex {
  const ix = new FactIndex();
  ix.addMany(buildBaseConfigFacts());
  ix.addMany(compileComponentFacts(buttonId, buildButtonFragment()));
  return ix;
}

function indexWithComponentUsageGovernance(): FactIndex {
  const ix = new FactIndex();
  ix.addMany(
    compileGlobalGovernanceFacts({
      rules: { "components/usage": { enabled: true, severity: "error" } },
    })
  );
  ix.addMany(compileComponentFacts(buttonId, buildButtonFragment()));
  return ix;
}

interface ButtonUsageInput {
  file: string;
  nodePath: string;
  line: number;
  column: number;
  props?: Array<{
    prop: string;
    resolution?: "static" | "dynamic" | "spread";
    value?: unknown;
  }>;
  inlineStyles?: Array<{
    property: string;
    valueKind: "static" | "number" | "css-variable";
    value: string;
  }>;
  text?: string;
}

function addButtonUsage(ix: FactIndex, input: ButtonUsageInput): { nodeId: FactId } {
  const node = makeUsageNodeFact({
    file: input.file,
    nodePath: input.nodePath,
    element: "Button",
    location: {
      file: input.file,
      line: input.line,
      column: input.column,
    },
  });
  ix.add(node);
  ix.add(makeUsageComponentFact({ nodeId: node.id, componentId: buttonId }));
  for (const prop of input.props ?? []) {
    ix.add(
      makeUsagePropResolvedFact({
        nodeId: node.id,
        prop: prop.prop,
        resolution: prop.resolution ?? "static",
        value: prop.value,
      })
    );
  }
  for (const inline of input.inlineStyles ?? []) {
    ix.add(
      makeUsageInlineStyleFact({
        nodeId: node.id,
        property: inline.property,
        valueKind: inline.valueKind,
        value: inline.value,
      })
    );
  }
  if (input.text !== undefined) {
    ix.add(makeUsageTextChildFact({ nodeId: node.id, text: input.text, index: 0 }));
  }
  return { nodeId: node.id };
}

// ---------------------------------------------------------------------------
// components/unknown-prop
// ---------------------------------------------------------------------------

describe("components/unknown-prop", () => {
  it("fires for an unknown prop with the prop's component location", () => {
    const ix = emptyIndexWithGovernance();
    addButtonUsage(ix, {
      file: "apps/marketing/page.tsx",
      nodePath: "0/0",
      line: 12,
      column: 4,
      props: [
        { prop: "variant", value: "primary" },
        { prop: "wibble", value: "yes" },
      ],
      text: "Continue",
    });

    const findings = ruleComponentsUnknownProp(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].ruleId).toBe("components/unknown-prop");
    expect(findings[0].severity).toBe("serious");
    expect(findings[0].location).toMatchObject({
      file: "apps/marketing/page.tsx",
      line: 12,
      column: 4,
    });
    expect(findings[0].attributes).toMatchObject({ prop: "wibble" });
    expect(findings[0].evidence.length).toBeGreaterThan(0);
  });

  it("does not fire for universal props (aria-*, data-*, on*, key/ref/className/style)", () => {
    const ix = emptyIndexWithGovernance();
    addButtonUsage(ix, {
      file: "apps/marketing/page.tsx",
      nodePath: "0",
      line: 1,
      column: 0,
      props: [
        { prop: "aria-label", value: "Save" },
        { prop: "data-testid", value: "save-btn" },
        { prop: "onClick", resolution: "dynamic" },
        { prop: "className", value: "x" },
        { prop: "style", resolution: "dynamic" },
        { prop: "key", value: "k" },
      ],
    });

    expect(ruleComponentsUnknownProp(ix)).toHaveLength(0);
  });

  it("does not fire when the global jsx.unknownProps policy is absent", () => {
    const ix = new FactIndex();
    ix.addMany(compileComponentFacts(buttonId, buildButtonFragment()));
    addButtonUsage(ix, {
      file: "apps/marketing/page.tsx",
      nodePath: "0",
      line: 1,
      column: 0,
      props: [{ prop: "wibble", value: "yes" }],
    });

    expect(ruleComponentsUnknownProp(ix)).toHaveLength(0);
  });
});

// ---------------------------------------------------------------------------
// components/forbidden-prop-value
// ---------------------------------------------------------------------------

describe("components/forbidden-prop-value", () => {
  it("fires only when the file matches the policy path glob", () => {
    const ix = emptyIndexWithGovernance();
    addButtonUsage(ix, {
      file: "apps/checkout/page.tsx",
      nodePath: "0/0",
      line: 42,
      column: 8,
      props: [{ prop: "variant", value: "secondary" }],
      text: "Continue",
    });
    addButtonUsage(ix, {
      file: "apps/marketing/home.tsx",
      nodePath: "0/0",
      line: 10,
      column: 4,
      props: [{ prop: "variant", value: "secondary" }],
      text: "Learn more",
    });

    const findings = ruleComponentsForbiddenPropValue(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].location.file).toBe("apps/checkout/page.tsx");
    expect(findings[0].severity).toBe("serious");
  });

  it("attaches a deterministic replacePropValue fix from policy.replaceWith", () => {
    const ix = emptyIndexWithGovernance();
    addButtonUsage(ix, {
      file: "apps/checkout/page.tsx",
      nodePath: "0/0",
      line: 42,
      column: 8,
      props: [{ prop: "variant", value: "secondary" }],
      text: "Continue",
    });

    const findings = ruleComponentsForbiddenPropValue(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].fix).toMatchObject({
      kind: "replacePropValue",
      prop: "variant",
      value: "primary",
      deterministic: true,
    });
  });

  it("does not fire for dynamic prop values", () => {
    const ix = emptyIndexWithGovernance();
    addButtonUsage(ix, {
      file: "apps/checkout/page.tsx",
      nodePath: "0/0",
      line: 1,
      column: 0,
      props: [{ prop: "variant", resolution: "dynamic" }],
    });

    expect(ruleComponentsForbiddenPropValue(ix)).toHaveLength(0);
  });
});

// ---------------------------------------------------------------------------
// props/invalid-value
// ---------------------------------------------------------------------------

describe("props/invalid-value", () => {
  it("fires for static enum values outside the component prop schema", () => {
    const ix = indexWithComponentUsageGovernance();
    addButtonUsage(ix, {
      file: "apps/marketing/page.tsx",
      nodePath: "0/0",
      line: 12,
      column: 4,
      props: [{ prop: "variant", value: "danger" }],
      text: "Delete workspace",
    });

    const findings = rulePropsInvalidValue(ix);

    expect(findings).toHaveLength(1);
    expect(findings[0]).toMatchObject({
      ruleId: "props/invalid-value",
      code: "FUI6002",
      severity: "serious",
      location: {
        file: "apps/marketing/page.tsx",
        line: 12,
        column: 4,
      },
      attributes: {
        componentId: buttonId,
        prop: "variant",
        rawValue: "danger",
        allowedValues: ["primary", "secondary", "ghost", "link"],
      },
    });
    expect(findings[0].fix).toBeUndefined();
    expect(findings[0].evidence.length).toBeGreaterThan(0);
  });

  it("skips dynamic, spread, unknown, and unconstrained props", () => {
    const ix = indexWithComponentUsageGovernance();
    addButtonUsage(ix, {
      file: "apps/marketing/page.tsx",
      nodePath: "0/0",
      line: 12,
      column: 4,
      props: [
        { prop: "variant", resolution: "dynamic" },
        { prop: "size", resolution: "spread", value: "xxl" },
        { prop: "wibble", value: "danger" },
        { prop: "disabled", value: "definitely" },
      ],
    });

    expect(rulePropsInvalidValue(ix)).toHaveLength(0);
  });

  it("does not fire unless the rule is enabled", () => {
    const ix = new FactIndex();
    ix.addMany(compileComponentFacts(buttonId, buildButtonFragment()));
    addButtonUsage(ix, {
      file: "apps/marketing/page.tsx",
      nodePath: "0/0",
      line: 12,
      column: 4,
      props: [{ prop: "variant", value: "danger" }],
    });

    expect(rulePropsInvalidValue(ix)).toHaveLength(0);
  });
});

// ---------------------------------------------------------------------------
// imports/preferred-path and components/preferred-component
// ---------------------------------------------------------------------------

describe("preferred JSX imports and components", () => {
  it("emits a deterministic import replacement for configured source mappings", () => {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        jsx: [
          g.jsx.importPath().prefer("@legacy/ui", "@fragments-sdk/ui", {
            severity: "error",
            because: "Use the canonical design-system package.",
          }),
        ],
      })
    );
    ix.add(
      makeUsageImportFact({
        file: "apps/checkout/page.tsx",
        local: "Button",
        imported: "Button",
        source: "@legacy/ui",
        location: { file: "apps/checkout/page.tsx", line: 1, column: 0 },
      })
    );

    const findings = ruleJsxPreferredImportPath(ix);

    expect(findings).toHaveLength(1);
    expect(findings[0].ruleId).toBe("imports/preferred-path");
    expect(findings[0].fix).toMatchObject({
      kind: "replaceImport",
      from: "@legacy/ui",
      to: "@fragments-sdk/ui",
      deterministic: true,
    });
    expect(findings[0].attributes).toMatchObject({
      importPath: "@legacy/ui",
      suggestedImport: "@fragments-sdk/ui",
    });
  });

  it("emits a deterministic component replacement for canonical component mappings", () => {
    const legacyButtonId = makeComponentId("@legacy/ui", "LegacyButton");
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        jsx: [
          g.jsx.component().prefer(legacyButtonId, buttonId, {
            severity: "warn",
            because: "Use the canonical Button component.",
          }),
        ],
      })
    );
    const node = makeUsageNodeFact({
      file: "apps/checkout/page.tsx",
      nodePath: "0/0",
      element: "LegacyButton",
      location: { file: "apps/checkout/page.tsx", line: 4, column: 9 },
    });
    ix.add(node);
    ix.add(makeUsageComponentFact({ nodeId: node.id, componentId: legacyButtonId }));

    const findings = ruleJsxPreferredComponent(ix);

    expect(findings).toHaveLength(1);
    expect(findings[0].ruleId).toBe("components/preferred-component");
    expect(findings[0].severity).toBe("moderate");
    expect(findings[0].fix).toMatchObject({
      kind: "replaceComponent",
      from: "LegacyButton",
      to: "Button",
      deterministic: true,
    });
  });
});

// ---------------------------------------------------------------------------
// styles/no-raw-color
// ---------------------------------------------------------------------------

describe("styles/no-raw-color", () => {
  it("fires for hex colors in inline JSX style", () => {
    const ix = emptyIndexWithGovernance();
    addButtonUsage(ix, {
      file: "apps/checkout/page.tsx",
      nodePath: "0/0",
      line: 42,
      column: 8,
      inlineStyles: [{ property: "color", valueKind: "static", value: "#2563eb" }],
      text: "x",
    });

    const findings = ruleStylesNoRawColor(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].attributes).toMatchObject({ source: "jsx", color: "#2563eb" });
  });

  it("fires for raw colors in SCSS declarations", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/Button.module.scss",
        selector: ".button",
        declarationPath: "0",
        property: "color",
        value: "#2563eb",
        location: {
          file: "libs/ui/Button.module.scss",
          line: 3,
          column: 2,
        },
      })
    );

    const findings = ruleStylesNoRawColor(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].attributes).toMatchObject({ source: "css", color: "#2563eb" });
    expect(findings[0].location.line).toBe(3);
  });

  it("only exempts raw custom property definitions inside declared token source files", () => {
    const tokenIx = emptyIndexWithGovernance();
    tokenIx.add(
      makeStyleDeclarationFact({
        file: "src/styles/tokens.css",
        selector: ":root",
        declarationPath: "0",
        property: "--fui-color-accent",
        value: "#39594d",
        declaredTokenSource: true,
        location: { file: "src/styles/tokens.css", line: 1, column: 0 },
      })
    );

    const productIx = emptyIndexWithGovernance();
    productIx.add(
      makeStyleDeclarationFact({
        file: "src/landing.scss",
        selector: ":root",
        declarationPath: "0",
        property: "--lp-accent",
        value: "#39594d",
        location: { file: "src/landing.scss", line: 1, column: 0 },
      })
    );

    expect(ruleStylesNoRawColor(tokenIx)).toHaveLength(0);
    expect(ruleStylesNoRawColor(productIx)).toHaveLength(1);
  });

  it("does not fire for var(--token) references", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".x",
        declarationPath: "0",
        property: "color",
        value: "var(--fui-color-accent, #ff0000)",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );
    addButtonUsage(ix, {
      file: "apps/x.tsx",
      nodePath: "0",
      line: 1,
      column: 0,
      inlineStyles: [
        { property: "color", valueKind: "css-variable", value: "var(--fui-color-accent)" },
      ],
      text: "x",
    });

    expect(ruleStylesNoRawColor(ix)).toHaveLength(0);
  });

  it("does not flag a hex inside a var() fallback within a shorthand", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".bordered",
        declarationPath: "0",
        property: "border",
        value: "1px solid var(--color-text, #1a1a1a)",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );

    // The hex is the var() fallback, not a raw color — flagging it would both be
    // a false positive and fight the dual-fallback rule that mandates it.
    expect(ruleStylesNoRawColor(ix)).toHaveLength(0);
  });

  it("does not fire for policy exemptions like 'transparent'", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".x",
        declarationPath: "0",
        property: "background",
        value: "transparent",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );

    expect(ruleStylesNoRawColor(ix)).toHaveLength(0);
  });

  it("fires for rgb() and hsl() function syntax", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".x",
        declarationPath: "0",
        property: "background",
        value: "rgb(0, 0, 0)",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".y",
        declarationPath: "0",
        property: "background",
        value: "hsl(220, 100%, 50%)",
        location: { file: "libs/ui/x.scss", line: 5, column: 0 },
      })
    );

    expect(ruleStylesNoRawColor(ix)).toHaveLength(2);
  });

  it("finds colors embedded in border and shadow shorthands", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".border",
        declarationPath: "0",
        property: "border",
        value: "1px solid #ccc",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".shadow",
        declarationPath: "1",
        property: "box-shadow",
        value: "0 1px 2px rgb(0, 0, 0)",
        location: { file: "libs/ui/x.scss", line: 2, column: 0 },
      })
    );

    const findings = ruleStylesNoRawColor(ix);
    expect(findings).toHaveLength(2);
    expect(findings.map((finding) => finding.attributes?.color)).toEqual(["#ccc", "rgb(0, 0, 0)"]);
  });
});

// ---------------------------------------------------------------------------
// styles/no-raw-spacing
// ---------------------------------------------------------------------------

describe("styles/no-raw-spacing", () => {
  it("fires for off-scale pixel values, silent for on-scale values", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".bad",
        declarationPath: "0",
        property: "padding",
        value: "13px",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".ok",
        declarationPath: "0",
        property: "padding",
        value: "12px",
        location: { file: "libs/ui/x.scss", line: 5, column: 0 },
      })
    );

    const findings = ruleStylesNoRawSpacing(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].attributes).toMatchObject({ rawValue: "13px" });
  });

  it("checks every value in spacing shorthands", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".bad",
        declarationPath: "0",
        property: "padding",
        value: "4px 10px",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".ok",
        declarationPath: "1",
        property: "padding",
        value: "4px 12px",
        location: { file: "libs/ui/x.scss", line: 2, column: 0 },
      })
    );

    const findings = ruleStylesNoRawSpacing(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].attributes).toMatchObject({
      rawValue: "4px 10px",
      suggestedValue: "4px 8px",
    });
  });

  it("treats inline numeric props as pixel values (padding: 13 → fires)", () => {
    const ix = emptyIndexWithGovernance();
    addButtonUsage(ix, {
      file: "apps/checkout/page.tsx",
      nodePath: "0/0",
      line: 42,
      column: 8,
      inlineStyles: [{ property: "padding", valueKind: "number", value: "13" }],
      text: "x",
    });

    const findings = ruleStylesNoRawSpacing(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].attributes).toMatchObject({ source: "jsx", rawValue: "13" });
  });

  it("normalizes rem values before checking a px spacing scale", () => {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        scales: {
          space: g.scale.px([0, 4, 8, 12, 16, 20, 24, 32, 80]),
        },
        styles: [
          g.styles.rawSpacing().mustMatchScale("space", {
            appliesTo: ["padding"],
            severity: "error",
          }),
        ],
      })
    );
    for (const [index, value] of [
      "0.25rem",
      "0.5rem",
      "1rem",
      "1.5rem",
      "2rem",
      "5rem",
    ].entries()) {
      ix.add(
        makeStyleDeclarationFact({
          file: "libs/ui/x.scss",
          selector: `.rem-${index}`,
          declarationPath: String(index),
          property: "padding",
          value,
          location: { file: "libs/ui/x.scss", line: index + 1, column: 0 },
        })
      );
    }

    expect(ruleStylesNoRawSpacing(ix)).toHaveLength(0);
  });

  it("normalizes em values for detection but does not autofix without an explicit em base", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".em",
        declarationPath: "0",
        property: "padding",
        value: "1.1em",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );

    const findings = ruleStylesNoRawSpacing(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].fix).toBeUndefined();
    expect(findings[0].attributes).toMatchObject({
      rawValue: "1.1em",
      normalizedValue: 17.6,
      assumedEmBasePx: 16,
      suggestedValue: "16px",
    });
  });

  it("emits a (non-deterministic) rem snap suggestion when the root font size is explicit", () => {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        scales: {
          space: {
            kind: "scale",
            unit: "px",
            values: [0, 14, 28],
            rootFontSizePx: 14,
          },
        },
        styles: [
          g.styles.rawSpacing().mustMatchScale("space", {
            appliesTo: ["padding"],
            severity: "error",
          }),
        ],
      })
    );
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".rem",
        declarationPath: "0",
        property: "padding",
        value: "1.1rem",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );

    const findings = ruleStylesNoRawSpacing(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].fix).toMatchObject({
      value: "14px",
      deterministic: false,
    });
    expect(findings[0].attributes).toMatchObject({
      suggestedValue: "14px",
    });
    expect(Number(findings[0].attributes?.normalizedValue)).toBeCloseTo(15.4);
  });

  it("does not fire for properties without a scale policy", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".x",
        declarationPath: "0",
        property: "border-radius",
        value: "13px",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );

    expect(ruleStylesNoRawSpacing(ix)).toHaveLength(0);
  });

  it("does not fire for var(--token) references", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".x",
        declarationPath: "0",
        property: "padding",
        value: "var(--fui-space-3)",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );

    expect(ruleStylesNoRawSpacing(ix)).toHaveLength(0);
  });

  it("allows negative values whose magnitude is on the configured scale", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".x",
        declarationPath: "0",
        property: "margin",
        value: "-4px",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );

    expect(ruleStylesNoRawSpacing(ix)).toHaveLength(0);
  });
});

// ---------------------------------------------------------------------------
// a11y/required-accessible-name
// ---------------------------------------------------------------------------

describe("a11y/required-accessible-name", () => {
  it("does not fire when there is a non-empty text child", () => {
    const ix = emptyIndexWithGovernance();
    addButtonUsage(ix, {
      file: "apps/x.tsx",
      nodePath: "0",
      line: 1,
      column: 0,
      text: "Continue",
    });

    expect(ruleA11yRequiredAccessibleName(ix)).toHaveLength(0);
  });

  it("does not fire with aria-label, aria-labelledby, or title", () => {
    const cases = [
      { prop: "aria-label", value: "Save" },
      { prop: "aria-labelledby", resolution: "dynamic" as const },
      { prop: "title", value: "Save" },
    ];
    for (const propInput of cases) {
      const ix = emptyIndexWithGovernance();
      addButtonUsage(ix, {
        file: "apps/x.tsx",
        nodePath: "0",
        line: 1,
        column: 0,
        props: [propInput],
      });
      expect(ruleA11yRequiredAccessibleName(ix)).toHaveLength(0);
    }
  });

  it("fires for an empty Button with no name source", () => {
    const ix = emptyIndexWithGovernance();
    addButtonUsage(ix, {
      file: "apps/x.tsx",
      nodePath: "0",
      line: 7,
      column: 4,
    });

    const findings = ruleA11yRequiredAccessibleName(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].location).toMatchObject({ line: 7, column: 4 });
  });

  it("does not fire for aria-hidden=true", () => {
    const ix = emptyIndexWithGovernance();
    addButtonUsage(ix, {
      file: "apps/x.tsx",
      nodePath: "0",
      line: 1,
      column: 0,
      props: [{ prop: "aria-hidden", value: true }],
    });

    expect(ruleA11yRequiredAccessibleName(ix)).toHaveLength(0);
  });
});

// ---------------------------------------------------------------------------
// Phase 5 vertical slice — runRules over the canonical fixture
// ---------------------------------------------------------------------------

describe("runRules — Phase 5 vertical slice", () => {
  it("produces three findings for the canonical checkout fixture", () => {
    const ix = emptyIndexWithGovernance();
    // Mirrors the brief's fixture:
    //   <Button variant="secondary" style={{ padding: 13, color: '#2563eb' }}>
    //     Continue
    //   </Button>
    addButtonUsage(ix, {
      file: "apps/checkout/page.tsx",
      nodePath: "0/0",
      line: 42,
      column: 8,
      props: [{ prop: "variant", value: "secondary" }],
      inlineStyles: [
        { property: "padding", valueKind: "number", value: "13" },
        { property: "color", valueKind: "static", value: "#2563eb" },
      ],
      text: "Continue",
    });

    const findings = runRules(ix);
    const ruleIds = findings.map((f) => f.ruleId).sort();
    expect(ruleIds).toEqual([
      "components/forbidden-prop-value",
      "styles/no-raw-color",
      "styles/no-raw-spacing",
    ]);
    for (const finding of findings) {
      expect(finding.evidence.length).toBeGreaterThan(0);
      expect(finding.fingerprint).toMatch(/^[0-9a-f]{16}$/);
    }
  });

  it("emits stable fingerprints across runs", () => {
    function buildIndex(): FactIndex {
      const ix = emptyIndexWithGovernance();
      addButtonUsage(ix, {
        file: "apps/checkout/page.tsx",
        nodePath: "0/0",
        line: 42,
        column: 8,
        props: [{ prop: "variant", value: "secondary" }],
        inlineStyles: [
          { property: "padding", valueKind: "number", value: "13" },
          { property: "color", valueKind: "static", value: "#2563eb" },
        ],
        text: "Continue",
      });
      return ix;
    }

    const a = runRules(buildIndex()).map((f) => f.fingerprint);
    const b = runRules(buildIndex()).map((f) => f.fingerprint);
    expect(b).toEqual(a);
  });

  it("emits the same fingerprint when the line number changes (fingerprint is content-addressed)", () => {
    function buildIndex(line: number): FactIndex {
      const ix = emptyIndexWithGovernance();
      addButtonUsage(ix, {
        file: "apps/checkout/page.tsx",
        nodePath: "0/0",
        line,
        column: 8,
        props: [{ prop: "variant", value: "secondary" }],
        text: "Continue",
      });
      return ix;
    }

    const baseline = runRules(buildIndex(42));
    const moved = runRules(buildIndex(99));
    expect(moved.map((f) => f.fingerprint)).toEqual(baseline.map((f) => f.fingerprint));
    expect(moved[0].location.line).toBe(99);
    expect(baseline[0].location.line).toBe(42);
  });

  it("every finding's evidence is non-empty and resolvable in the index", () => {
    const ix = emptyIndexWithGovernance();
    addButtonUsage(ix, {
      file: "apps/checkout/page.tsx",
      nodePath: "0/0",
      line: 1,
      column: 0,
      props: [{ prop: "variant", value: "secondary" }],
      inlineStyles: [{ property: "color", valueKind: "static", value: "#2563eb" }],
    });

    const findings = runRules(ix);
    expect(findings.length).toBeGreaterThan(0);
    for (const finding of findings) {
      expect(finding.evidence.length).toBeGreaterThan(0);
      for (const evidence of finding.evidence) {
        expect(ix.has(evidence.factId)).toBe(true);
      }
    }
  });
});

// ---------------------------------------------------------------------------
// Phase 6 — deterministic fix payloads on rules
// ---------------------------------------------------------------------------

describe("Phase 6 fix payloads", () => {
  it("styles/no-raw-spacing emits a nearest-scale replaceStyleValue fix for SCSS", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".bad",
        declarationPath: "0",
        property: "padding",
        value: "13px",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );

    const findings = ruleStylesNoRawSpacing(ix);
    expect(findings).toHaveLength(1);
    // Off-scale snaps change the rendered value, so the fix is a suggestion,
    // not a deterministic auto-apply (BUG 13 — no silent layout change).
    expect(findings[0].fix).toEqual({
      kind: "replaceStyleValue",
      title: "Replace padding with 12px",
      property: "padding",
      value: "12px",
      deterministic: false,
    });
    expect(findings[0].attributes).toMatchObject({ suggestedValue: "12px" });
  });

  it("styles/no-raw-spacing emits a bare-number fix for inline numeric props", () => {
    const ix = emptyIndexWithGovernance();
    addButtonUsage(ix, {
      file: "apps/checkout/page.tsx",
      nodePath: "0/0",
      line: 42,
      column: 8,
      inlineStyles: [{ property: "padding", valueKind: "number", value: "13" }],
      text: "x",
    });

    const findings = ruleStylesNoRawSpacing(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].fix).toEqual({
      kind: "replaceStyleValue",
      title: "Replace padding with 12",
      property: "padding",
      value: "12",
      deterministic: false,
    });
  });

  it("styles/no-raw-spacing flags but does NOT auto-snap a non-zero value to 0", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".tiny",
        declarationPath: "0",
        property: "padding",
        value: "2px",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );

    const findings = ruleStylesNoRawSpacing(ix);
    expect(findings).toHaveLength(1);
    // 2px's nearest scale value is 0 — snapping would silently remove the
    // padding, so no deterministic fix is offered.
    expect(findings[0].fix).toBeUndefined();
  });

  it("styles/no-raw-spacing snaps to the nearest allowed value (ties break low)", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".tie",
        declarationPath: "0",
        property: "margin",
        value: "10px",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );

    const findings = ruleStylesNoRawSpacing(ix);
    expect(findings).toHaveLength(1);
    // Scale is [0, 4, 8, 12, 16, 20, 24, 32]; 10 is equidistant from 8 and 12,
    // tie breaks low → 8px.
    expect(findings[0].fix).toMatchObject({ value: "8px" });
  });

  it("styles/no-raw-spacing preserves negative signs in nearest-scale fixes", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".tie",
        declarationPath: "0",
        property: "margin",
        value: "-10px",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );

    const findings = ruleStylesNoRawSpacing(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].fix).toMatchObject({ value: "-8px" });
    expect(findings[0].attributes).toMatchObject({ suggestedValue: "-8px" });
  });

  it("styles/no-raw-color emits a token-substitution fix when a color token matches", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeTokenDefinitionFact({
        name: "--fui-color-accent",
        value: "#2563eb",
        category: "color",
      })
    );
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".x",
        declarationPath: "0",
        property: "color",
        value: "#2563eb",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );

    const findings = ruleStylesNoRawColor(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].fix).toEqual({
      kind: "replaceStyleValue",
      title: "Replace color with var(--fui-color-accent)",
      property: "color",
      value: "var(--fui-color-accent)",
      deterministic: true,
    });
    expect(findings[0].attributes).toMatchObject({ suggestedToken: "--fui-color-accent" });
  });

  it("styles/no-raw-color prefers a role-matching token when several share a value", () => {
    const ix = emptyIndexWithGovernance();
    ix.addMany([
      makeTokenDefinitionFact({ name: "--color-bg", value: "#ffffff", category: "color" }),
      makeTokenDefinitionFact({ name: "--color-text", value: "#ffffff", category: "color" }),
    ]);
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".x",
        declarationPath: "0",
        property: "color",
        value: "#ffffff",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );

    const findings = ruleStylesNoRawColor(ix);
    expect(findings).toHaveLength(1);
    // Foreground property -> the text token, not the background token.
    expect(findings[0].fix).toMatchObject({ value: "var(--color-text)", deterministic: true });
  });

  it("styles/no-raw-color emits no fix when no token matches the raw color", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeTokenDefinitionFact({
        name: "--fui-color-accent",
        value: "#2563eb",
        category: "color",
      })
    );
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".x",
        declarationPath: "0",
        property: "color",
        value: "#ff00ff",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );

    const findings = ruleStylesNoRawColor(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].fix).toBeUndefined();
    expect(findings[0].attributes).toMatchObject({ suggestedToken: undefined });
  });

  it("styles/no-raw-color suggests the nearest token when no exact value matches", () => {
    const ix = emptyIndexWithGovernance();
    ix.addMany([
      makeTokenDefinitionFact({ name: "--fui-color-accent", value: "#2563eb", category: "color" }),
      makeTokenDefinitionFact({ name: "--fui-color-danger", value: "#dc2626", category: "color" }),
    ]);
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".x",
        declarationPath: "0",
        property: "color",
        value: "#2563f0", // one shade off the accent token
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );

    const findings = ruleStylesNoRawColor(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].message).toContain("Closest token is `--fui-color-accent` (#2563eb)");
    // A nearest match is a hint, never a fix — snapping changes the rendered color.
    expect(findings[0].fix).toBeUndefined();
    expect(findings[0].attributes).toMatchObject({
      suggestedToken: "--fui-color-accent",
      tokenMatch: "nearest",
    });
  });

  it("styles/no-raw-color suggests nothing when the nearest token is a different hue", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeTokenDefinitionFact({ name: "--fui-color-accent", value: "#2563eb", category: "color" })
    );
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".x",
        declarationPath: "0",
        property: "color",
        value: "#ff0000",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );

    const findings = ruleStylesNoRawColor(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].message).not.toContain("Closest token");
    expect(findings[0].attributes).toMatchObject({ suggestedToken: undefined });
  });

  it("styles/no-raw-color marks exact value matches with tokenMatch: exact", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeTokenDefinitionFact({ name: "--fui-color-accent", value: "#2563eb", category: "color" })
    );
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".x",
        declarationPath: "0",
        property: "color",
        value: "#2563eb",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );

    const findings = ruleStylesNoRawColor(ix);
    expect(findings[0].attributes).toMatchObject({ tokenMatch: "exact" });
  });

  it("styles/no-raw-color normalizes 3-digit hex when matching tokens", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeTokenDefinitionFact({
        name: "--fui-color-white",
        value: "#ffffff",
        category: "color",
      })
    );
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".x",
        declarationPath: "0",
        property: "background",
        value: "#FFF",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );

    const findings = ruleStylesNoRawColor(ix);
    expect(findings[0].fix).toMatchObject({ value: "var(--fui-color-white)" });
  });

  it("styles/no-raw-color preserves shorthand declarations when fixing embedded colors", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeTokenDefinitionFact({
        name: "--fui-color-accent",
        value: "#2563eb",
        category: "color",
      })
    );
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".x",
        declarationPath: "0",
        property: "border",
        value: "1px solid #2563eb",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );

    const findings = ruleStylesNoRawColor(ix);
    expect(findings[0].fix).toMatchObject({
      value: "1px solid var(--fui-color-accent)",
    });
  });

  it("styles/no-raw-color emits a fix for inline JSX colors when a token matches", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeTokenDefinitionFact({
        name: "--fui-color-accent",
        value: "#2563eb",
        category: "color",
      })
    );
    addButtonUsage(ix, {
      file: "apps/x.tsx",
      nodePath: "0",
      line: 1,
      column: 0,
      inlineStyles: [{ property: "color", valueKind: "static", value: "#2563eb" }],
      text: "x",
    });

    const findings = ruleStylesNoRawColor(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].fix).toEqual({
      kind: "replaceStyleValue",
      title: "Replace color with var(--fui-color-accent)",
      property: "color",
      value: "var(--fui-color-accent)",
      deterministic: true,
    });
  });

  it("token-match fix evidence resolves through the index (token fact is included)", () => {
    const ix = emptyIndexWithGovernance();
    ix.add(
      makeTokenDefinitionFact({
        name: "--fui-color-accent",
        value: "#2563eb",
        category: "color",
      })
    );
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector: ".x",
        declarationPath: "0",
        property: "color",
        value: "#2563eb",
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );

    const findings = ruleStylesNoRawColor(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].evidence.length).toBeGreaterThanOrEqual(3);
    for (const ev of findings[0].evidence) {
      expect(ix.has(ev.factId)).toBe(true);
    }
  });
});

describe("tokens/require-dual-fallback", () => {
  it("flags CSS token vars without SCSS fallbacks", () => {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        rules: {
          "tokens/require-dual-fallback": { enabled: true, severity: "error" },
        },
      })
    );
    ix.addMany([
      makeTokenDefinitionFact({
        name: "--fui-color-brand",
        value: "#123456",
        category: "color",
      }),
      makeStyleDeclarationFact({
        file: "src/button.scss",
        selector: ".button",
        declarationPath: "0",
        property: "color",
        value: "var(--fui-color-brand)",
        location: { file: "src/button.scss", line: 2, column: 2 },
      }),
    ]);

    const findings = ruleTokensRequireDualFallback(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0]).toMatchObject({
      ruleId: "tokens/require-dual-fallback",
      code: "FUI2003",
      severity: "serious",
      fix: {
        kind: "replaceStyleValue",
        value: "var(--fui-color-brand, $fui-color-brand)",
      },
    });
  });

  it("does NOT fire on plain .css/.module.css files (no Sass pipeline)", () => {
    for (const file of ["src/button.css", "src/button.module.css", "src/Button.tsx"]) {
      const ix = new FactIndex();
      ix.addMany(
        compileGlobalGovernanceFacts({
          rules: { "tokens/require-dual-fallback": { enabled: true, severity: "error" } },
        })
      );
      ix.addMany([
        makeTokenDefinitionFact({ name: "--fui-color-brand", value: "#123456", category: "color" }),
        makeStyleDeclarationFact({
          file,
          selector: ".button",
          declarationPath: "0",
          property: "color",
          value: "var(--fui-color-brand)",
          location: { file, line: 2, column: 2 },
        }),
      ]);
      expect(ruleTokensRequireDualFallback(ix), `should skip ${file}`).toHaveLength(0);
    }
  });
});

describe("theme/no-theme-coupled-literal", () => {
  it("flags theme-sensitive literal colors in custom shadows", () => {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        rules: {
          "theme/no-theme-coupled-literal": {
            enabled: true,
            severity: "warning",
          },
        },
      })
    );
    ix.add(
      makeStyleDeclarationFact({
        file: "src/card.scss",
        selector: ".card",
        declarationPath: "0",
        property: "box-shadow",
        value: "0 0 0 1px rgba(0, 0, 0, 0.16)",
        location: { file: "src/card.scss", line: 4, column: 2 },
      })
    );

    const findings = ruleThemeNoThemeCoupledLiteral(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0]).toMatchObject({
      ruleId: "theme/no-theme-coupled-literal",
      code: "FUI2014",
      attributes: {
        color: "rgba(0, 0, 0, 0.16)",
      },
    });
  });
});

describe("components/prefer-library", () => {
  function preferLibraryIndex() {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        rules: {
          "components/prefer-library": {
            enabled: true,
            severity: "warning",
            options: {
              canonicalSources: [
                {
                  kind: "npm",
                  specifier: "@acme/ui",
                  include: [
                    "Alert",
                    "Button",
                    "Checkbox",
                    "Collapsible",
                    "IconButton",
                    "NumberInput",
                    "Radio",
                    "Select",
                    "Table",
                  ],
                },
              ],
            },
          },
        },
      })
    );
    return ix;
  }

  function addRawNode(
    ix: FactIndex,
    input: {
      element: string;
      nodePath: string;
      role?: string;
      interactive?: boolean;
      props?: Array<{ prop: string; value?: unknown; resolution?: "static" | "dynamic" | "jsx" }>;
      text?: string;
    }
  ) {
    const node = makeUsageNodeFact({
      file: "src/app.tsx",
      nodePath: input.nodePath,
      element: input.element,
      role: input.role,
      interactive: input.interactive,
      location: { file: "src/app.tsx", line: 5, column: 4 },
    });
    ix.add(node);
    for (const prop of input.props ?? []) {
      ix.add(
        makeUsagePropResolvedFact({
          nodeId: node.id,
          prop: prop.prop,
          resolution: prop.resolution ?? "static",
          value: prop.value,
        })
      );
    }
    if (input.text !== undefined) {
      ix.add(makeUsageTextChildFact({ nodeId: node.id, text: input.text, index: 0 }));
    }
    return node;
  }

  it("caps advisory-tier severity at warn even when the rule is set to error (only confident tiers escalate)", () => {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        rules: {
          "components/prefer-library": {
            enabled: true,
            severity: "error",
            options: {
              canonicalSources: [
                { kind: "npm", specifier: "@acme/ui", include: ["Button", "Select"] },
              ],
            },
          },
        },
      })
    );
    addRawNode(ix, { element: "button", nodePath: "0:0", interactive: true, text: "Go" });
    addRawNode(ix, { element: "select", nodePath: "0:1" });

    const byRaw = Object.fromEntries(
      ruleComponentsPreferLibrary(ix).map((finding) => [finding.attributes?.rawValue, finding])
    );
    // Confident exact-html <button> → Button inherits the escalated error level…
    expect(byRaw.button?.level).toBe("error");
    expect(byRaw.button?.attributes?.advisory).toBeUndefined();
    // …but the advisory html-advisory <select> → Select is capped back to warn and
    // flagged advisory, so it can never hard-block or hard-fail CI.
    expect(byRaw.select?.level).toBe("warn");
    expect(byRaw.select?.attributes?.advisory).toBe(true);
  });

  it("advisory-flags a plain <div className={styles.alert}> as a hand-rolled primitive (reimplements-primitive)", () => {
    const ix = preferLibraryIndex();
    const alertDiv = addRawNode(ix, { element: "div", nodePath: "0:2" });
    ix.add(
      makeClassNameDynamicFact({
        file: "src/app.tsx",
        nodeId: alertDiv.id,
        attr: "className",
        reason: "identifier",
        snippet: "styles.alert",
        originPath: "0:2",
        location: { file: "src/app.tsx", line: 6, column: 4 },
      })
    );
    // `Table` is canonical, but `table` is a common layout class — the denylist
    // must keep it from flagging (the heuristic's low-noise guarantee).
    const tableDiv = addRawNode(ix, { element: "div", nodePath: "0:3" });
    ix.add(
      makeClassNameDynamicFact({
        file: "src/app.tsx",
        nodeId: tableDiv.id,
        attr: "className",
        reason: "identifier",
        snippet: "styles.table",
        originPath: "0:3",
        location: { file: "src/app.tsx", line: 7, column: 4 },
      })
    );

    const reimpls = ruleComponentsPreferLibrary(ix).filter(
      (finding) => finding.attributes?.precisionTier === "classname-reimpl"
    );
    expect(reimpls).toHaveLength(1);
    expect(reimpls[0].attributes?.suggestedComponent).toBe("Alert");
    expect(reimpls[0].attributes?.matchedClass).toBe("alert");
    expect(reimpls[0].attributes?.advisory).toBe(true);
    // Advisory: capped at warn (never a hard error/block) and no auto-fix.
    expect(reimpls[0].level).toBe("warn");
    expect(reimpls[0].fix).toBeUndefined();
  });

  it("does not flag imported bespoke components from bare package canonical sources without export inventory", () => {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        rules: {
          "components/prefer-library": {
            enabled: true,
            severity: "warning",
            options: {
              canonicalSources: [{ kind: "npm", specifier: "@acme/ui" }],
            },
          },
        },
      })
    );
    const node = makeUsageNodeFact({
      file: "src/app.tsx",
      nodePath: "0:0",
      element: "Card",
      location: { file: "src/app.tsx", line: 5, column: 4 },
    });
    ix.add(node);
    ix.add(
      makeUsageImportFact({
        file: "src/app.tsx",
        local: "Card",
        imported: "Card",
        source: "../components/Card",
        location: { file: "src/app.tsx", line: 1, column: 0 },
      })
    );

    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
  });

  it("flags imported bespoke components when package canonical sources include the exported component", () => {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        rules: {
          "components/prefer-library": {
            enabled: true,
            severity: "warning",
            options: {
              canonicalSources: [{ kind: "npm", specifier: "@acme/ui", include: ["Card"] }],
            },
          },
        },
      })
    );
    const node = makeUsageNodeFact({
      file: "src/app.tsx",
      nodePath: "0:0",
      element: "Card",
      location: { file: "src/app.tsx", line: 5, column: 4 },
    });
    ix.add(node);
    ix.add(
      makeUsageImportFact({
        file: "src/app.tsx",
        local: "Card",
        imported: "Card",
        source: "../components/Card",
        location: { file: "src/app.tsx", line: 1, column: 0 },
      })
    );

    const findings = ruleComponentsPreferLibrary(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0]).toMatchObject({
      ruleId: "components/prefer-library",
      code: "FUI1004",
      attributes: {
        suggestedComponent: "Card",
        suggestedImport: "@acme/ui",
      },
    });
  });

  it("does not flag bespoke components from bare registry canonical sources without export inventory", () => {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        rules: {
          "components/prefer-library": {
            enabled: true,
            severity: "warning",
            options: {
              canonicalSources: [
                {
                  kind: "registry",
                  registryId: "fragments-ui",
                  receiptPath: ".fragments/registry-lock.json",
                  installPath: "src/fragments/ui",
                  importPath: "@/fragments/ui",
                },
              ],
            },
          },
        },
      })
    );
    const node = makeUsageNodeFact({
      file: "src/app.tsx",
      nodePath: "0:0",
      element: "Card",
      location: { file: "src/app.tsx", line: 5, column: 4 },
    });
    ix.add(node);
    ix.add(
      makeUsageImportFact({
        file: "src/app.tsx",
        local: "Card",
        imported: "Card",
        source: "../components/Card",
        location: { file: "src/app.tsx", line: 1, column: 1 },
      })
    );

    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
  });

  it("flags bespoke components when registry canonical sources include the exported component", () => {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        rules: {
          "components/prefer-library": {
            enabled: true,
            severity: "warning",
            options: {
              canonicalSources: [
                {
                  kind: "registry",
                  registryId: "fragments-ui",
                  receiptPath: ".fragments/registry-lock.json",
                  installPath: "src/fragments/ui",
                  importPath: "@/fragments/ui",
                  include: ["Card"],
                },
              ],
            },
          },
        },
      })
    );
    const node = makeUsageNodeFact({
      file: "src/app.tsx",
      nodePath: "0:0",
      element: "Card",
      location: { file: "src/app.tsx", line: 5, column: 4 },
    });
    ix.add(node);
    ix.add(
      makeUsageImportFact({
        file: "src/app.tsx",
        local: "Card",
        imported: "Card",
        source: "../components/Card",
        location: { file: "src/app.tsx", line: 1, column: 1 },
      })
    );

    const findings = ruleComponentsPreferLibrary(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0]).toMatchObject({
      ruleId: "components/prefer-library",
      attributes: {
        suggestedComponent: "Card",
        suggestedImport: "@/fragments/ui",
        suggestedImportSourceKind: "registry",
      },
    });
  });

  it("respects canonical source include lists", () => {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        rules: {
          "components/prefer-library": {
            enabled: true,
            severity: "warning",
            options: {
              canonicalSources: [
                {
                  kind: "npm",
                  specifier: "@acme/ui",
                  include: ["Button"],
                },
              ],
            },
          },
        },
      })
    );
    addRawNode(ix, {
      element: "button",
      nodePath: "0:0",
      text: "Save",
      interactive: true,
    });
    const node = makeUsageNodeFact({
      file: "src/app.tsx",
      nodePath: "0:1",
      element: "MarketingCard",
      location: { file: "src/app.tsx", line: 8, column: 4 },
    });
    ix.add(node);
    ix.add(
      makeUsageImportFact({
        file: "src/app.tsx",
        local: "MarketingCard",
        imported: "MarketingCard",
        source: "../components/MarketingCard",
        location: { file: "src/app.tsx", line: 2, column: 0 },
      })
    );

    const findings = ruleComponentsPreferLibrary(ix);

    expect(findings).toHaveLength(1);
    expect(findings[0]).toMatchObject({
      ruleId: "components/prefer-library",
      attributes: {
        rawValue: "button",
        suggestedComponent: "Button",
        suggestedImport: "@acme/ui",
      },
    });
  });

  it("does not flag raw primitives inside a canonical source implementation", () => {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        rules: {
          "components/prefer-library": {
            enabled: true,
            severity: "warning",
            options: {
              canonicalSources: [
                {
                  kind: "npm",
                  specifier: "@fragments-sdk/ui",
                  implementationPath: "src/fragments/ui",
                  include: ["Button"],
                },
              ],
            },
          },
        },
      })
    );
    ix.add(
      makeUsageNodeFact({
        file: "src/fragments/ui/components/Button/index.tsx",
        nodePath: "0:0",
        element: "button",
        interactive: true,
        location: {
          file: "src/fragments/ui/components/Button/index.tsx",
          line: 5,
          column: 4,
        },
      })
    );

    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
  });

  it("matches canonical imports within the current file only", () => {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        rules: {
          "components/prefer-library": {
            enabled: true,
            severity: "warning",
            options: {
              canonicalSources: [
                {
                  kind: "npm",
                  specifier: "@fragments-sdk/ui",
                  implementationPath: "src/fragments/ui",
                  include: ["Table"],
                },
              ],
            },
          },
        },
      })
    );
    ix.add(
      makeUsageNodeFact({
        file: "src/page/settings.tsx",
        nodePath: "0:0",
        element: "Table",
        location: { file: "src/page/settings.tsx", line: 5, column: 4 },
      })
    );
    ix.add(
      makeUsageImportFact({
        file: "src/page/settings.tsx",
        local: "Table",
        imported: "Table",
        source: "@fragments-sdk/ui",
        location: { file: "src/page/settings.tsx", line: 1, column: 0 },
      })
    );
    ix.add(
      makeUsageImportFact({
        file: "src/fragments/ui/components/DataTable/index.tsx",
        local: "Table",
        imported: "Table",
        source: "../Table",
        location: {
          file: "src/fragments/ui/components/DataTable/index.tsx",
          line: 1,
          column: 0,
        },
      })
    );

    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
  });

  it("attaches a deterministic component fix from confirmed canonical mappings", () => {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        rules: {
          "components/prefer-library": {
            enabled: true,
            severity: "warning",
            options: {
              canonicalMappings: [
                {
                  name: "Button",
                  canonical: "Button",
                  htmlEquivalent: "button",
                  importPath: "@acme/ui",
                  propMapping: [{ rawProp: "className", canonicalProp: "variant" }],
                  confidence: 0.94,
                },
              ],
            },
          },
        },
      })
    );
    ix.add(
      makeUsageNodeFact({
        file: "src/app.tsx",
        nodePath: "0:0",
        element: "button",
        location: { file: "src/app.tsx", line: 5, column: 4 },
      })
    );

    const findings = ruleComponentsPreferLibrary(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0]).toMatchObject({
      ruleId: "components/prefer-library",
      fix: {
        kind: "replaceComponent",
        from: "button",
        to: "Button",
        deterministic: true,
      },
      attributes: {
        suggestedComponent: "Button",
        suggestedImport: "@acme/ui",
        propMapping: [{ rawProp: "className", canonicalProp: "variant" }],
      },
    });
  });

  it("does not flag generic <div>/<span> from an inferred component primitive (anti-flood)", () => {
    // A library component built on a <div> (Accordion) or <span> (Badge) must
    // NOT turn every container into a bespoke re-implementation of it. This was
    // the 10k-finding canonical-usage flood: div → Accordion, span → Badge.
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        rules: {
          "components/prefer-library": {
            enabled: true,
            severity: "warning",
            options: {
              canonicalMappings: [
                {
                  name: "Accordion",
                  canonical: "Accordion",
                  htmlEquivalent: "div",
                  importPath: "@acme/ui",
                },
                {
                  name: "Badge",
                  canonical: "Badge",
                  htmlEquivalent: "span",
                  importPath: "@acme/ui",
                },
              ],
            },
          },
        },
      })
    );
    addRawNode(ix, { element: "div", nodePath: "0:0" });
    addRawNode(ix, { element: "span", nodePath: "0:1" });

    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
  });

  it("suppresses <button> → specialized component but keeps <button> → Button (agreement)", () => {
    function findingsFor(mapping: Record<string, unknown>) {
      const ix = new FactIndex();
      ix.addMany(
        compileGlobalGovernanceFacts({
          rules: {
            "components/prefer-library": {
              enabled: true,
              severity: "warning",
              options: { canonicalMappings: [mapping] },
            },
          },
        })
      );
      addRawNode(ix, { element: "button", nodePath: "0:0", text: "Save", interactive: true });
      return ruleComponentsPreferLibrary(ix);
    }

    // <button> → Chip disagrees with the curated canonical (Button) → suppressed.
    expect(
      findingsFor({
        name: "Chip",
        canonical: "Chip",
        htmlEquivalent: "button",
        importPath: "@acme/ui",
      })
    ).toHaveLength(0);

    // <button> → Button agrees with the curated canonical → still fires.
    const buttonFindings = findingsFor({
      name: "Button",
      canonical: "Button",
      htmlEquivalent: "button",
      importPath: "@acme/ui",
    });
    expect(buttonFindings).toHaveLength(1);
    expect(buttonFindings[0].attributes?.suggestedComponent).toBe("Button");
  });

  describe("@fragments-sdk/ui-style mapped sources — canonical≠suggestion divergence", () => {
    // Live-prod leak (post-#224): a Chip component declares an inverted
    // per-component `htmlEquivalent: "button"` and ships `canonical: "Button"`
    // (the correct enforceable canonical) but `name: "Chip"`. The #224 guard
    // validated the `canonical` field (Button → enforceable → passes) while the
    // rule EMITTED `suggestedComponent = mapping.name` ("Chip"). Result: a raw
    // <button> produced canonical:"Button" + suggestedComponent:"Chip" —
    // the divergence that was ~68% of the dogfood's remaining FUI1004 findings.
    // The emitted suggestion must equal the tag's enforceable canonical.
    function mappedFindings(mappings: Array<Record<string, unknown>>, element: string) {
      const ix = new FactIndex();
      ix.addMany(
        compileGlobalGovernanceFacts({
          rules: {
            "components/prefer-library": {
              enabled: true,
              severity: "warning",
              options: {
                canonicalSources: [{ kind: "npm", specifier: "@fragments-sdk/ui" }],
                canonicalMappings: mappings,
              },
            },
          },
        })
      );
      addRawNode(ix, { element, nodePath: "0:0", text: "Save", interactive: true });
      return ruleComponentsPreferLibrary(ix);
    }

    it("never emits suggestedComponent:'Chip' when canonical:'Button' but name:'Chip' (divergence)", () => {
      // ADVERSARIAL: without the fix, isEnforceableHtmlEquivalent validates the
      // `canonical` (Button) and lets the divergent `name` (Chip) leak as
      // suggestedComponent (the live-prod symptom: canonical:"Button" +
      // suggestedComponent:"Chip"). With the fix, enforceability is checked
      // against the emitted `name` ("Chip" !== "Button") so the divergent Chip
      // mapping never matches; the bare <button> instead resolves to its curated
      // canonical (Button). Either way: ZERO button→Chip findings, and any
      // finding that DOES fire must be button→Button (suggestion === canonical).
      const findings = mappedFindings(
        [
          {
            name: "Chip",
            canonical: "Button",
            htmlEquivalent: "button",
            importPath: "@fragments-sdk/ui",
          },
        ],
        "button"
      );
      expect(findings.filter((f) => f.attributes?.suggestedComponent === "Chip")).toHaveLength(0);
      for (const finding of findings) {
        // Any finding that fires for a bare <button> must point at the curated
        // canonical (Button) — never the divergent Chip name. When the mapped
        // path emits the `canonical` attribute it must agree with the suggestion.
        expect(finding.attributes?.suggestedComponent).toBe("Button");
        if (finding.attributes?.canonical !== undefined) {
          expect(finding.attributes.canonical).toBe(finding.attributes.suggestedComponent);
        }
      }
    });

    it("still fires <button> → Button (suggestion === canonical)", () => {
      const findings = mappedFindings(
        [
          {
            name: "Button",
            canonical: "Button",
            htmlEquivalent: "button",
            importPath: "@fragments-sdk/ui",
          },
        ],
        "button"
      );
      expect(findings).toHaveLength(1);
      expect(findings[0].attributes?.suggestedComponent).toBe("Button");
      expect(findings[0].attributes?.canonical).toBe("Button");
    });

    it("Button wins even when a divergent Chip→button mapping coexists", () => {
      // Both a correct Button mapping and a divergent Chip mapping are present;
      // the divergent Chip must never be the emitted suggestion.
      const findings = mappedFindings(
        [
          {
            name: "Chip",
            canonical: "Button",
            htmlEquivalent: "button",
            importPath: "@fragments-sdk/ui",
          },
          {
            name: "Button",
            canonical: "Button",
            htmlEquivalent: "button",
            importPath: "@fragments-sdk/ui",
          },
        ],
        "button"
      );
      expect(findings.filter((f) => f.attributes?.suggestedComponent === "Chip")).toHaveLength(0);
      expect(findings.every((f) => f.attributes?.suggestedComponent === "Button")).toBe(true);
    });

    it("semantic mapped tags still fire (textarea/select/table → custom-named)", () => {
      // Semantic, low-frequency tags remain enforceable even with custom-named
      // components — the fix must NOT regress these.
      const cases: Array<[string, string]> = [
        ["textarea", "Textarea"],
        ["select", "Select"],
        ["table", "DataTable"],
      ];
      for (const [tag, name] of cases) {
        const findings = mappedFindings(
          [{ name, canonical: name, htmlEquivalent: tag, importPath: "@fragments-sdk/ui" }],
          tag
        );
        expect(findings).toHaveLength(1);
        expect(findings[0].attributes?.suggestedComponent).toBe(name);
      }
    });

    it("does not flag generic <div>/<span> mapped to a divergent component", () => {
      // div/span have no curated canonical → never enforceable, never emitted.
      expect(
        mappedFindings(
          [
            { name: "Accordion", canonical: "Accordion", htmlEquivalent: "div" },
            { name: "Badge", canonical: "Badge", htmlEquivalent: "span" },
          ],
          "div"
        )
      ).toHaveLength(0);
      expect(
        mappedFindings([{ name: "Badge", canonical: "Badge", htmlEquivalent: "span" }], "span")
      ).toHaveLength(0);
    });

    it("matches a mis-cased htmlEquivalent (case-insensitive raw-tag compare — audit #29)", () => {
      // A catalog/author can store `htmlEquivalent: "TEXTAREA"` while the raw tag
      // is `textarea`. The mapped path must still match (raw tags are
      // case-insensitive), so the finding carries the mapping's custom name
      // ("BigText") — not the built-in advisory fallback ("Textarea"). Before the
      // fix the case-sensitive `===` made the mapping inert.
      const findings = mappedFindings(
        [
          {
            name: "BigText",
            canonical: "BigText",
            htmlEquivalent: "TEXTAREA",
            importPath: "@fragments-sdk/ui",
          },
        ],
        "textarea"
      );
      expect(findings).toHaveLength(1);
      expect(findings[0].attributes?.suggestedComponent).toBe("BigText");
    });
  });

  it("does not emit a no-op finding when the element already is the canonical (icon self-map)", () => {
    // The element IS the canonical and there is no import-path fix to make:
    // "replace <GitBranch> with <GitBranch>" is not drift. These icon self-maps
    // were pure noise in the flood.
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        rules: {
          "components/prefer-library": {
            enabled: true,
            severity: "warning",
            options: {
              canonicalMappings: [{ name: "GitBranch", canonical: "GitBranch" }],
            },
          },
        },
      })
    );
    ix.add(
      makeUsageNodeFact({
        file: "src/app.tsx",
        nodePath: "0:0",
        element: "GitBranch",
        location: { file: "src/app.tsx", line: 5, column: 4 },
      })
    );
    ix.add(
      makeUsageImportFact({
        file: "src/app.tsx",
        local: "GitBranch",
        imported: "GitBranch",
        source: "@phosphor-icons/react",
        location: { file: "src/app.tsx", line: 1, column: 0 },
      })
    );

    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
  });

  describe("component-name divergence — element === canonical vocab id (audit #1/#2)", () => {
    // Engine audit (2026-06-23): a confirmed mapping carries name = the user's
    // component display name and canonical = the vocabulary id, so divergence
    // (name "Modal", canonical "Dialog") is the NORM. The old findMapping /
    // shouldSuggestMapped matched purely on `mapping.canonical === node.element`,
    // so a user writing <Dialog> (the canonical vocab id) got told to swap to the
    // renamed wrapper <Modal> — a self-contradicting finding (rawValue ===
    // canonical) that also fired on compliant usage, and let any common vocab id
    // (Tooltip/Card/Switch) hijack an unrelated third-party usage. The canonical
    // selector is removed; only a real NAME match, an enforceable htmlEquivalent,
    // or an ARIA-role match may drive a finding. React-agnostic: uses @acme/ui.
    function importedFindings(
      mappings: Array<Record<string, unknown>>,
      element: string,
      importSource: string,
      sources: Array<Record<string, unknown>> = [{ kind: "npm", specifier: "@acme/ui" }]
    ) {
      const ix = new FactIndex();
      ix.addMany(
        compileGlobalGovernanceFacts({
          rules: {
            "components/prefer-library": {
              enabled: true,
              severity: "warning",
              options: { canonicalSources: sources, canonicalMappings: mappings },
            },
          },
        })
      );
      ix.add(
        makeUsageNodeFact({
          file: "src/app.tsx",
          nodePath: "0:0",
          element,
          location: { file: "src/app.tsx", line: 5, column: 4 },
        })
      );
      ix.add(
        makeUsageImportFact({
          file: "src/app.tsx",
          local: element,
          imported: element,
          source: importSource,
          location: { file: "src/app.tsx", line: 1, column: 0 },
        })
      );
      return ruleComponentsPreferLibrary(ix);
    }

    it("does NOT suggest swapping <Dialog> → <Modal> when name 'Modal' diverges from canonical 'Dialog' (#1)", () => {
      // ADVERSARIAL: before the fix this emitted a "Dialog → Modal" swap with
      // attributes { rawValue:'Dialog', canonical:'Dialog', suggestedComponent:'Modal' }
      // — self-contradicting and firing even on the canonical primitive.
      const fromImportPath = importedFindings(
        [{ name: "Modal", canonical: "Dialog", importPath: "@acme/ui" }],
        "Dialog",
        "@acme/ui"
      );
      expect(fromImportPath).toHaveLength(0);
      const fromThirdParty = importedFindings(
        [{ name: "Modal", canonical: "Dialog" }],
        "Dialog",
        "react-aria"
      );
      expect(
        fromThirdParty.filter((f) => f.attributes?.suggestedComponent === "Modal")
      ).toHaveLength(0);
    });

    it("does NOT let a common vocab id (Tooltip) hijack an unrelated mapping named 'Hint' (#2)", () => {
      const findings = importedFindings(
        [{ name: "Hint", canonical: "Tooltip" }],
        "Tooltip",
        "@radix-ui/react-tooltip"
      );
      expect(findings.filter((f) => f.attributes?.suggestedComponent === "Hint")).toHaveLength(0);
    });

    it("STILL fires the legit name-based import-redirect (<Modal> from wrong path → import @acme/ui)", () => {
      // Regression guard: removing the canonical selector must not kill the
      // real name-match import-redirect. <Modal> (the component's own name)
      // imported from the wrong path is genuine drift.
      const findings = importedFindings(
        [{ name: "Modal", canonical: "Dialog", importPath: "@acme/ui" }],
        "Modal",
        "react-aria"
      );
      expect(findings).toHaveLength(1);
      expect(findings[0].fix?.kind).toBe("replaceImport");
      expect(findings[0].attributes?.suggestedComponent).toBe("Modal");
    });

    it("STILL fires when name === canonical (<Dialog> for name 'Dialog') from wrong path", () => {
      const findings = importedFindings(
        [{ name: "Dialog", canonical: "Dialog", importPath: "@acme/ui" }],
        "Dialog",
        "react-aria"
      );
      expect(findings).toHaveLength(1);
      expect(findings[0].attributes?.suggestedComponent).toBe("Dialog");
    });
  });

  describe("directory canonical source (unfiltered include — dogfood shape)", () => {
    // A DIRECTORY canonical source is derived without an `include` list, so it
    // claims every component name. Before the fix that turned every imported
    // component (Phosphor icons included) into a no-op `<X> → <X>` finding and
    // let a disagreeing raw-tag match through. The directory path must honor the
    // same #224 guards as the mapped path: no no-ops, raw lowercase HTML only,
    // enforceable-canonical only.
    function directoryIndex() {
      const ix = new FactIndex();
      ix.addMany(
        compileGlobalGovernanceFacts({
          rules: {
            "components/prefer-library": {
              enabled: true,
              severity: "warning",
              options: {
                canonicalSources: [{ kind: "directory", path: "src/fragments/ui/components" }],
              },
            },
          },
        })
      );
      return ix;
    }

    it("does not flag imported icon components (already-capitalized, no-op)", () => {
      const ix = directoryIndex();
      for (const [i, icon] of ["X", "House"].entries()) {
        ix.add(
          makeUsageNodeFact({
            file: "src/app.tsx",
            nodePath: `0:${i}`,
            element: icon,
            location: { file: "src/app.tsx", line: 5 + i, column: 4 },
          })
        );
        ix.add(
          makeUsageImportFact({
            file: "src/app.tsx",
            local: icon,
            imported: icon,
            source: "@phosphor-icons/react",
            location: { file: "src/app.tsx", line: 1 + i, column: 0 },
          })
        );
      }

      expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
    });

    it("does not flag <button> when the canonical disagrees (button → Chip)", () => {
      // A directory source cannot supply Chip as button's canonical: button's
      // curated canonical is Button. The non-enforceable match is suppressed.
      const ix = new FactIndex();
      ix.addMany(
        compileGlobalGovernanceFacts({
          rules: {
            "components/prefer-library": {
              enabled: true,
              severity: "warning",
              options: {
                // No Button in the directory, only Chip → button's builtIn
                // canonical (Button) is not in the source, so even before the
                // enforceability gate there is no Chip target for a <button>.
                canonicalSources: [
                  {
                    kind: "directory",
                    path: "src/fragments/ui/components",
                    include: ["Chip"],
                  },
                ],
              },
            },
          },
        })
      );
      addRawNode(ix, {
        element: "button",
        nodePath: "0:0",
        text: "Save",
        interactive: true,
      });

      expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
    });

    it("flags raw <button> → Button when Button is a declared directory canonical", () => {
      const ix = new FactIndex();
      ix.addMany(
        compileGlobalGovernanceFacts({
          rules: {
            "components/prefer-library": {
              enabled: true,
              severity: "warning",
              options: {
                canonicalSources: [
                  {
                    kind: "directory",
                    path: "src/fragments/ui/components",
                    include: ["Button"],
                  },
                ],
              },
            },
          },
        })
      );
      addRawNode(ix, {
        element: "button",
        nodePath: "0:0",
        text: "Save",
        interactive: true,
      });

      const findings = ruleComponentsPreferLibrary(ix);
      expect(findings).toHaveLength(1);
      expect(findings[0]).toMatchObject({
        ruleId: "components/prefer-library",
        fix: {
          kind: "replaceComponent",
          from: "button",
          to: "Button",
          deterministic: true,
        },
        attributes: {
          rawValue: "button",
          suggestedComponent: "Button",
          suggestedImportSourceKind: "directory",
        },
      });
    });

    it("flags a raw element by canonical vocab id when display name diverges (Modal → Dialog)", () => {
      // The emitter scopes a divergent confirmed mapping (a "Modal" component
      // whose canonical is "Dialog") to include BOTH names. The raw <dialog>
      // resolves to the canonical "Dialog", so the suggestion must still fire
      // even though the team's component is named "Modal".
      const ix = new FactIndex();
      ix.addMany(
        compileGlobalGovernanceFacts({
          rules: {
            "components/prefer-library": {
              enabled: true,
              severity: "warning",
              options: {
                canonicalSources: [
                  {
                    kind: "directory",
                    path: "src/overlays",
                    include: ["Dialog", "Modal"],
                  },
                ],
              },
            },
          },
        })
      );
      addRawNode(ix, {
        element: "dialog",
        nodePath: "0:0",
        text: "Confirm",
        interactive: true,
      });

      const findings = ruleComponentsPreferLibrary(ix);
      expect(findings).toHaveLength(1);
      expect(findings[0]).toMatchObject({
        ruleId: "components/prefer-library",
        attributes: {
          rawValue: "dialog",
          suggestedComponent: "Dialog",
          suggestedImportSourceKind: "directory",
        },
      });
    });

    it("does not flag generic <div>/<span> from a directory source (anti-flood)", () => {
      const ix = directoryIndex();
      addRawNode(ix, { element: "div", nodePath: "0:0" });
      addRawNode(ix, { element: "span", nodePath: "0:1" });

      expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
    });
  });

  it("discriminates raw <input> by type via htmlType mappings", () => {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        rules: {
          "components/prefer-library": {
            enabled: true,
            severity: "warning",
            options: {
              canonicalMappings: [
                {
                  name: "TextField",
                  canonical: "Input",
                  htmlEquivalent: "input",
                  importPath: "@acme/ui",
                },
                {
                  name: "Checkbox",
                  canonical: "Checkbox",
                  htmlEquivalent: "input",
                  htmlType: "checkbox",
                  importPath: "@acme/ui",
                },
                {
                  name: "RadioGroup",
                  canonical: "Radio",
                  htmlEquivalent: "input",
                  htmlType: "radio",
                  importPath: "@acme/ui",
                },
              ],
            },
          },
        },
      })
    );
    addRawNode(ix, {
      element: "input",
      nodePath: "0:0",
      props: [{ prop: "type", value: "checkbox" }],
    });
    addRawNode(ix, {
      element: "input",
      nodePath: "0:1",
      props: [{ prop: "type", value: "radio" }],
    });
    addRawNode(ix, {
      element: "input",
      nodePath: "0:2",
      props: [{ prop: "type", value: "text" }],
    });

    const findings = ruleComponentsPreferLibrary(ix);

    // type-specific mappings win over the generic tag-level one; text falls back
    expect(findings.map((finding) => finding.attributes?.suggestedComponent)).toEqual([
      "Checkbox",
      "RadioGroup",
      "TextField",
    ]);
    expect(findings.map((finding) => finding.fix?.to)).toEqual([
      "Checkbox",
      "RadioGroup",
      "TextField",
    ]);
    expect(findings.every((finding) => finding.fix?.deterministic === true)).toBe(true);
  });

  it("does not let a type-constrained mapping match a different or untyped input", () => {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        rules: {
          "components/prefer-library": {
            enabled: true,
            severity: "warning",
            options: {
              canonicalMappings: [
                {
                  name: "Checkbox",
                  canonical: "Checkbox",
                  htmlEquivalent: "input",
                  htmlType: "checkbox",
                  importPath: "@acme/ui",
                },
              ],
            },
          },
        },
      })
    );
    addRawNode(ix, {
      element: "input",
      nodePath: "0:0",
      props: [{ prop: "type", value: "text" }],
    });
    addRawNode(ix, { element: "input", nodePath: "0:1" });

    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
  });

  it("attaches a deterministic import fix for canonical components from the wrong path", () => {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        rules: {
          "components/prefer-library": {
            enabled: true,
            severity: "warning",
            options: {
              canonicalMappings: [
                {
                  name: "Button",
                  canonical: "Button",
                  importPath: "@acme/ui",
                },
              ],
            },
          },
        },
      })
    );
    ix.add(
      makeUsageNodeFact({
        file: "src/app.tsx",
        nodePath: "0:0",
        element: "Button",
        location: { file: "src/app.tsx", line: 5, column: 4 },
      })
    );
    ix.add(
      makeUsageImportFact({
        file: "src/app.tsx",
        local: "Button",
        imported: "Button",
        source: "../Button",
        location: { file: "src/app.tsx", line: 1, column: 0 },
      })
    );

    const findings = ruleComponentsPreferLibrary(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0]).toMatchObject({
      fix: {
        kind: "replaceImport",
        from: "../Button",
        to: "@acme/ui",
        deterministic: true,
      },
      location: { line: 1, column: 0 },
    });
  });

  it("flags a bespoke element by its ARIA role, advisory (no deterministic fix)", () => {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        rules: {
          "components/prefer-library": {
            enabled: true,
            severity: "warning",
            options: {
              canonicalMappings: [
                {
                  name: "Alert",
                  canonical: "Alert",
                  ariaRole: "status",
                  importPath: "@acme/ui",
                  confidence: 0.9,
                },
              ],
            },
          },
        },
      })
    );
    // A raw <div role="status"> — matches the canonical's role, not its tag.
    ix.add(
      makeUsageNodeFact({
        file: "src/app.tsx",
        nodePath: "0:0",
        element: "div",
        role: "status",
        location: { file: "src/app.tsx", line: 9, column: 2 },
      })
    );

    const findings = ruleComponentsPreferLibrary(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0]).toMatchObject({
      ruleId: "components/prefer-library",
      message: 'Custom <div role="status"> reimplements a primitive. Use <Alert> from @acme/ui.',
      attributes: {
        suggestedComponent: "Alert",
        matchedRole: "status",
        confidence: 0.9,
      },
    });
    // Role matches are advisory: no deterministic tag→component rewrite.
    expect(findings[0].fix).toBeUndefined();
  });

  it("flags input type primitives config-free with deterministic fixes", () => {
    const ix = preferLibraryIndex();
    addRawNode(ix, {
      element: "input",
      nodePath: "0:0",
      props: [{ prop: "type", value: "checkbox" }],
    });
    addRawNode(ix, {
      element: "input",
      nodePath: "0:1",
      props: [{ prop: "type", value: "radio" }],
    });
    addRawNode(ix, {
      element: "input",
      nodePath: "0:2",
      props: [{ prop: "type", value: "number" }],
    });

    const findings = ruleComponentsPreferLibrary(ix);

    expect(findings.map((finding) => finding.attributes?.suggestedComponent)).toEqual([
      "Checkbox",
      "Radio",
      "NumberInput",
    ]);
    expect(findings.map((finding) => finding.attributes?.precisionTier)).toEqual([
      "input-type",
      "input-type",
      "input-type",
    ]);
    expect(findings.map((finding) => finding.fix?.deterministic)).toEqual([true, true, true]);
  });

  it("does not infer generic text inputs as deterministic primitives", () => {
    const ix = preferLibraryIndex();
    addRawNode(ix, { element: "input", nodePath: "0:0" });
    addRawNode(ix, {
      element: "input",
      nodePath: "0:1",
      props: [{ prop: "type", value: "text" }],
    });
    addRawNode(ix, {
      element: "input",
      nodePath: "0:2",
      props: [{ prop: "type", value: "email" }],
    });

    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
  });

  it("flags compound native tags as advisory raw HTML suggestions", () => {
    const ix = preferLibraryIndex();
    addRawNode(ix, { element: "select", nodePath: "0:0" });
    addRawNode(ix, { element: "table", nodePath: "0:1" });
    addRawNode(ix, { element: "details", nodePath: "0:2" });

    const findings = ruleComponentsPreferLibrary(ix);

    expect(findings.map((finding) => finding.attributes?.suggestedComponent)).toEqual([
      "Select",
      "Table",
      "Collapsible",
    ]);
    expect(findings.every((finding) => finding.fix === undefined)).toBe(true);
    expect(findings.every((finding) => finding.attributes?.advisory === true)).toBe(true);
    expect(findings.every((finding) => finding.attributes?.precisionTier === "html-advisory")).toBe(
      true
    );
  });

  it("flags interactive non-semantic elements as advisory Button suggestions", () => {
    const ix = preferLibraryIndex();
    addRawNode(ix, {
      element: "div",
      nodePath: "0:0",
      interactive: true,
      props: [{ prop: "onClick", resolution: "jsx" }],
    });
    addRawNode(ix, {
      element: "span",
      nodePath: "0:1",
      interactive: true,
      props: [{ prop: "onPointerDown", resolution: "jsx" }],
    });

    const findings = ruleComponentsPreferLibrary(ix);

    expect(findings).toHaveLength(2);
    expect(findings.map((finding) => finding.attributes?.suggestedComponent)).toEqual([
      "Button",
      "Button",
    ]);
    expect(findings.every((finding) => finding.fix === undefined)).toBe(true);
    expect(findings.every((finding) => finding.attributes?.advisory === true)).toBe(true);
    expect(
      findings.every((finding) => finding.attributes?.precisionTier === "interactive-nonsemantic")
    ).toBe(true);
  });

  it("uses the built-in role table on non-semantic tags without double-firing native elements", () => {
    const ix = preferLibraryIndex();
    addRawNode(ix, { element: "div", nodePath: "0:0", role: "button" });
    addRawNode(ix, { element: "div", nodePath: "0:1", role: "checkbox" });
    addRawNode(ix, { element: "button", nodePath: "0:2", role: "button", text: "Save" });

    const findings = ruleComponentsPreferLibrary(ix);

    expect(findings.map((finding) => finding.attributes?.suggestedComponent)).toEqual([
      "Button",
      "Checkbox",
      "Button",
    ]);
    expect(findings[0].fix).toBeUndefined();
    expect(findings[1].fix).toBeUndefined();
    expect(findings[0].attributes?.precisionTier).toBe("role-reimpl");
    expect(findings[1].attributes?.precisionTier).toBe("role-reimpl");
    expect(findings[2].fix).toMatchObject({
      kind: "replaceComponent",
      from: "button",
      to: "Button",
      deterministic: true,
    });
  });

  it("suggests IconButton for icon-only buttons and Button when text is present", () => {
    const ix = preferLibraryIndex();
    addRawNode(ix, {
      element: "button",
      nodePath: "0:0",
      interactive: true,
      props: [
        { prop: "onClick", resolution: "jsx" },
        { prop: "aria-label", value: "Close" },
      ],
    });
    addRawNode(ix, {
      element: "button",
      nodePath: "0:1",
      interactive: true,
      props: [{ prop: "onClick", resolution: "jsx" }],
      text: "Save",
    });
    addRawNode(ix, {
      element: "button",
      nodePath: "0:2",
      interactive: true,
      props: [
        { prop: "onClick", resolution: "jsx" },
        { prop: "children", resolution: "jsx" },
      ],
    });

    const findings = ruleComponentsPreferLibrary(ix);

    expect(findings.map((finding) => finding.attributes?.suggestedComponent)).toEqual([
      "IconButton",
      "Button",
      "Button",
    ]);
    expect(findings[0].fix).toBeUndefined();
    expect(findings[0].attributes?.precisionTier).toBe("icon-only");
    expect(findings[0].attributes?.advisory).toBe(true);
    expect(findings[1].fix).toMatchObject({
      kind: "replaceComponent",
      from: "button",
      to: "Button",
      deterministic: true,
    });
    expect(findings[2].fix).toMatchObject({
      kind: "replaceComponent",
      from: "button",
      to: "Button",
      deterministic: true,
    });
  });

  it("does not spray findings across plain wrappers or unknown roles", () => {
    const ix = preferLibraryIndex();
    addRawNode(ix, { element: "div", nodePath: "0:0" });
    addRawNode(ix, { element: "div", nodePath: "0:1", role: "region" });
    addRawNode(ix, { element: "section", nodePath: "0:2" });

    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
  });

  it("does not flag a role-bearing element when no mapping declares that role", () => {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        rules: {
          "components/prefer-library": {
            enabled: true,
            severity: "warning",
            options: {
              canonicalMappings: [{ name: "Alert", canonical: "Alert", ariaRole: "alert" }],
            },
          },
        },
      })
    );
    ix.add(
      makeUsageNodeFact({
        file: "src/app.tsx",
        nodePath: "0:0",
        element: "div",
        role: "status",
        location: { file: "src/app.tsx", line: 9, column: 2 },
      })
    );

    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
  });
});

// ---------------------------------------------------------------------------
// Run-5 fixes: token-aware spacing / typography, color role, fixer safety
// ---------------------------------------------------------------------------

function spacingIndexWithTokens(
  tokens: Array<{ name: string; value: string; referenceFormat?: TokenRefFormat }>
): FactIndex {
  const ix = new FactIndex();
  ix.addMany(
    compileGlobalGovernanceFacts({
      scales: { space: g.scale.px([0, 4, 8, 12, 16, 24, 32]) },
      styles: [
        g.styles.rawSpacing().mustMatchScale("space", {
          appliesTo: ["padding", "margin", "margin-top", "gap"],
          severity: "warn",
        }),
      ],
    })
  );
  for (const token of tokens) {
    ix.add(
      makeTokenDefinitionFact({
        name: token.name,
        value: token.value,
        category: "spacing",
        referenceFormat: token.referenceFormat,
      })
    );
  }
  return ix;
}

type TokenRefFormat = "css-var" | "scss-var" | "scss-map" | "dtcg";

describe("styles/no-raw-spacing — token-aware (BUG 1/13/15)", () => {
  it("flags an on-scale raw literal that equals a token with a deterministic var() swap", () => {
    const ix = spacingIndexWithTokens([{ name: "--space-md", value: "16px" }]);
    ix.add(
      makeStyleDeclarationFact({
        file: "src/x.css",
        selector: ".a",
        declarationPath: "0",
        property: "padding",
        value: "16px",
        location: { file: "src/x.css", line: 1, column: 0 },
      })
    );
    const findings = ruleStylesNoRawSpacing(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].fix).toMatchObject({
      value: "var(--space-md)",
      deterministic: true,
    });
    expect(findings[0].attributes).toMatchObject({ matchedToken: "--space-md" });
  });

  it("suggests the nearest token for an off-scale value but does NOT auto-apply it", () => {
    const ix = spacingIndexWithTokens([{ name: "--space-md", value: "16px" }]);
    ix.add(
      makeStyleDeclarationFact({
        file: "src/x.css",
        selector: ".a",
        declarationPath: "0",
        property: "padding",
        value: "15px",
        location: { file: "src/x.css", line: 1, column: 0 },
      })
    );
    const findings = ruleStylesNoRawSpacing(ix);
    expect(findings).toHaveLength(1);
    // Nearest scale value is 16 → its token; value-changing so non-deterministic.
    expect(findings[0].fix).toMatchObject({
      value: "var(--space-md)",
      deterministic: false,
    });
  });

  it("keeps a Sass-map token swap as a suggestion (non-compiling if applied)", () => {
    const ix = spacingIndexWithTokens([
      { name: "$space-md", value: "16px", referenceFormat: "scss-map" },
    ]);
    ix.add(
      makeStyleDeclarationFact({
        file: "src/x.scss",
        selector: ".a",
        declarationPath: "0",
        property: "padding",
        value: "16px",
        location: { file: "src/x.scss", line: 1, column: 0 },
      })
    );
    const findings = ruleStylesNoRawSpacing(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].fix?.deterministic).toBe(false);
  });

  it("catches a camelCase longhand inline spacing prop (marginTop)", () => {
    const ix = spacingIndexWithTokens([]);
    const node = makeUsageNodeFact({
      file: "src/Hero.tsx",
      nodePath: "0",
      element: "div",
      location: { file: "src/Hero.tsx", line: 3, column: 2 },
    });
    ix.add(node);
    ix.add(
      makeUsageInlineStyleFact({
        nodeId: node.id,
        property: "marginTop",
        valueKind: "number",
        value: "13",
      })
    );
    const findings = ruleStylesNoRawSpacing(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].attributes).toMatchObject({ property: "marginTop" });
  });
});

describe("styles/no-raw-color — role correctness + fixer safety (BUG 4/3/11)", () => {
  function colorIndex(
    tokens: Array<{ name: string; value: string; referenceFormat?: TokenRefFormat }>
  ): FactIndex {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        styles: [g.styles.rawColors().forbid({ prefer: "token", severity: "warn" })],
      })
    );
    for (const token of tokens) {
      ix.add(
        makeTokenDefinitionFact({
          name: token.name,
          value: token.value,
          category: "color",
          referenceFormat: token.referenceFormat,
        })
      );
    }
    return ix;
  }

  it("does NOT deterministically swap white text for a lone background token", () => {
    const ix = colorIndex([{ name: "--color-bg", value: "#ffffff" }]);
    ix.add(
      makeStyleDeclarationFact({
        file: "src/x.css",
        selector: ".a",
        declarationPath: "0",
        property: "color",
        value: "#ffffff",
        location: { file: "src/x.css", line: 1, column: 0 },
      })
    );
    const findings = ruleStylesNoRawColor(ix);
    expect(findings).toHaveLength(1);
    // The only matching token is a *background* token — wrong role for `color:`.
    expect(findings[0].fix?.deterministic).toBe(false);
  });

  it("still deterministically swaps a role-neutral brand color used as text", () => {
    const ix = colorIndex([{ name: "--color-brand-500", value: "#3366ff" }]);
    ix.add(
      makeStyleDeclarationFact({
        file: "src/x.css",
        selector: ".a",
        declarationPath: "0",
        property: "color",
        value: "#3366ff",
        location: { file: "src/x.css", line: 1, column: 0 },
      })
    );
    const findings = ruleStylesNoRawColor(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].fix?.deterministic).toBe(true);
  });

  it("keeps a DTCG-JSON token swap as a suggestion (no CSS var emitted)", () => {
    const ix = colorIndex([{ name: "--color-brand", value: "#3366ff", referenceFormat: "dtcg" }]);
    ix.add(
      makeStyleDeclarationFact({
        file: "src/x.css",
        selector: ".a",
        declarationPath: "0",
        property: "color",
        value: "#3366ff",
        location: { file: "src/x.css", line: 1, column: 0 },
      })
    );
    const findings = ruleStylesNoRawColor(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].fix?.deterministic).toBe(false);
  });
});

describe("styles/no-raw-typography (BUG 10)", () => {
  function typeIndex(tokens: Array<{ name: string; value: string }>): FactIndex {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        scales: { typeSize: g.scale.px([12, 14, 16, 20, 24]) },
        styles: [g.styles.fontSize().mustMatchScale("typeSize", { severity: "warn" })],
      })
    );
    for (const token of tokens) {
      ix.add(
        makeTokenDefinitionFact({ name: token.name, value: token.value, category: "typography" })
      );
    }
    return ix;
  }

  it("flags an off-scale font-size as a suggestion", () => {
    const ix = typeIndex([{ name: "--font-size-md", value: "16px" }]);
    ix.add(
      makeStyleDeclarationFact({
        file: "src/x.css",
        selector: ".a",
        declarationPath: "0",
        property: "font-size",
        value: "13px",
        location: { file: "src/x.css", line: 1, column: 0 },
      })
    );
    const findings = ruleStylesNoRawTypography(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].fix?.deterministic).toBe(false);
  });

  it("deterministically swaps an on-scale font-size literal for its token", () => {
    const ix = typeIndex([{ name: "--font-size-md", value: "16px" }]);
    ix.add(
      makeStyleDeclarationFact({
        file: "src/x.css",
        selector: ".a",
        declarationPath: "0",
        property: "font-size",
        value: "16px",
        location: { file: "src/x.css", line: 1, column: 0 },
      })
    );
    const findings = ruleStylesNoRawTypography(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].fix).toMatchObject({
      value: "var(--font-size-md)",
      deterministic: true,
    });
  });

  it("is silent without a font-size scale policy", () => {
    const ix = new FactIndex();
    ix.add(
      makeStyleDeclarationFact({
        file: "src/x.css",
        selector: ".a",
        declarationPath: "0",
        property: "font-size",
        value: "13px",
        location: { file: "src/x.css", line: 1, column: 0 },
      })
    );
    expect(ruleStylesNoRawTypography(ix)).toHaveLength(0);
  });
});

// ---------------------------------------------------------------------------
// styles/no-raw-dimensions
// ---------------------------------------------------------------------------

describe("styles/no-raw-dimensions", () => {
  function indexWithDimensions(opts: {
    appliesTo: string[];
    radius?: Array<{ name: string; value: string }>;
    spacing?: Array<{ name: string; value: string }>;
  }): FactIndex {
    const ix = new FactIndex();
    ix.addMany(
      compileGlobalGovernanceFacts({
        styles: [
          {
            kind: "style.rawDimensions.forbid",
            appliesTo: opts.appliesTo,
            prefer: "token",
            severity: "error",
          },
        ],
      })
    );
    for (const token of opts.radius ?? []) {
      ix.add(
        makeTokenDefinitionFact({
          name: token.name,
          value: token.value,
          category: "radius",
          referenceFormat: "css-var",
        })
      );
    }
    for (const token of opts.spacing ?? []) {
      ix.add(
        makeTokenDefinitionFact({
          name: token.name,
          value: token.value,
          category: "spacing",
          referenceFormat: "css-var",
        })
      );
    }
    return ix;
  }

  function addDecl(ix: FactIndex, property: string, value: string, selector = ".x"): void {
    ix.add(
      makeStyleDeclarationFact({
        file: "libs/ui/x.scss",
        selector,
        declarationPath: "0",
        property,
        value,
        location: { file: "libs/ui/x.scss", line: 1, column: 0 },
      })
    );
  }

  it("is silent when no rawDimensions policy is configured", () => {
    const ix = new FactIndex();
    ix.add(makeTokenDefinitionFact({ name: "--radius-md", value: "8px", category: "radius" }));
    addDecl(ix, "border-radius", "10px");
    expect(ruleStylesNoRawDimensions(ix)).toHaveLength(0);
  });

  it("emits a deterministic var() fix on an exact token match", () => {
    const ix = indexWithDimensions({
      appliesTo: ["border-radius"],
      radius: [{ name: "--radius-md", value: "8px" }],
    });
    addDecl(ix, "border-radius", "8px");

    const findings = ruleStylesNoRawDimensions(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].fix).toMatchObject({
      kind: "replaceStyleValue",
      value: "var(--radius-md)",
      deterministic: true,
    });
    expect(findings[0].attributes).toMatchObject({ suggestedToken: "--radius-md" });
  });

  it("snaps an off-scale value to the nearest same-unit token as a suggestion", () => {
    const ix = indexWithDimensions({
      appliesTo: ["border-radius"],
      radius: [
        { name: "--radius-sm", value: "4px" },
        { name: "--radius-md", value: "8px" },
        { name: "--radius-lg", value: "16px" },
      ],
    });
    addDecl(ix, "border-radius", "10px");

    const findings = ruleStylesNoRawDimensions(ix);
    expect(findings).toHaveLength(1);
    // 10px is nearest to 8px (--radius-md). Snapping changes the rendered value,
    // so it is surfaced as a suggestion (token + message) with NO auto-fix —
    // otherwise the conform engine would silently rewrite the value.
    expect(findings[0].fix).toBeUndefined();
    expect(findings[0].attributes).toMatchObject({
      rawValue: "10px",
      suggestedToken: "--radius-md",
    });
    expect(findings[0].message).toContain("Closest token");
  });

  it("never snaps a non-zero value to a zero-valued token", () => {
    const ix = indexWithDimensions({
      appliesTo: ["border-radius"],
      radius: [
        { name: "--radius-none", value: "0" },
        { name: "--radius-md", value: "8px" },
        { name: "--radius-lg", value: "16px" },
      ],
    });
    addDecl(ix, "border-radius", "2px");

    const findings = ruleStylesNoRawDimensions(ix);
    expect(findings).toHaveLength(1);
    // 2px is numerically closest to 0, but collapsing to 0 silently removes the
    // radius — so it suggests the nearest *non-zero* token instead.
    expect(findings[0].fix).toBeUndefined();
    expect(findings[0].attributes).toMatchObject({ suggestedToken: "--radius-md" });
  });

  it("offers no token when the only candidates are a different unit", () => {
    const ix = indexWithDimensions({
      appliesTo: ["border-radius"],
      radius: [{ name: "--radius-md", value: "0.5rem" }],
    });
    addDecl(ix, "border-radius", "10px");

    const findings = ruleStylesNoRawDimensions(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].fix).toBeUndefined();
    expect(findings[0].attributes.suggestedToken).toBeUndefined();
  });

  it("flags an off-scale multi-value shorthand without a nearest suggestion", () => {
    const ix = indexWithDimensions({
      appliesTo: ["border-radius"],
      radius: [{ name: "--radius-md", value: "8px" }],
    });
    addDecl(ix, "border-radius", "10px 12px");

    const findings = ruleStylesNoRawDimensions(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].fix).toBeUndefined();
  });

  it("suggests the nearest token for off-scale JSX inline dimensions", () => {
    const ix = indexWithDimensions({
      appliesTo: ["border-radius"],
      radius: [
        { name: "--radius-md", value: "8px" },
        { name: "--radius-lg", value: "16px" },
      ],
    });
    addButtonUsage(ix, {
      file: "apps/checkout/page.tsx",
      nodePath: "0/0",
      line: 7,
      column: 2,
      inlineStyles: [{ property: "borderRadius", valueKind: "static", value: "9px" }],
      text: "x",
    });

    const findings = ruleStylesNoRawDimensions(ix);
    expect(findings).toHaveLength(1);
    expect(findings[0].attributes).toMatchObject({
      source: "jsx",
      rawValue: "9px",
      suggestedToken: "--radius-md",
    });
    expect(findings[0].fix).toBeUndefined();
  });
});

// Type witness so eslint/tsc don't trip on unused imports above.
const _typeWitness: Fact[] = [];
void _typeWitness;