@usefragments/core 1.0.0

package/src/rules/rules.test.ts

@@ -0,0 +1,3636 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  asComponentId,
+  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("@usefragments/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", "@usefragments/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: "@usefragments/ui",
+      deterministic: true,
+    });
+    expect(findings[0].attributes).toMatchObject({
+      importPath: "@legacy/ui",
+      suggestedImport: "@usefragments/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,
+    });
+  });
+
+  it("matches legacy/current import policies once and fixes the actual source spelling", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        jsx: [
+          g.jsx.importPath().prefer("@usefragments/ui", "@acme/ui"),
+          g.jsx.importPath().prefer("@usefragments/ui", "@acme/ui"),
+        ],
+      })
+    );
+    ix.add(
+      makeUsageImportFact({
+        file: "src/app.tsx",
+        local: "Button",
+        imported: "Button",
+        source: "@usefragments/ui",
+        location: { file: "src/app.tsx", line: 1, column: 0 },
+      })
+    );
+
+    const findings = ruleJsxPreferredImportPath(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].fix).toMatchObject({
+      kind: "replaceImport",
+      from: "@usefragments/ui",
+      to: "@acme/ui",
+    });
+  });
+
+  it("does not emit an import rewrite between equivalent owned spellings", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        jsx: [g.jsx.importPath().prefer("@usefragments/ui", "@usefragments/ui")],
+      })
+    );
+    ix.add(
+      makeUsageImportFact({
+        file: "src/app.tsx",
+        local: "Button",
+        imported: "Button",
+        source: "@usefragments/ui",
+        location: { file: "src/app.tsx", line: 1, column: 0 },
+      })
+    );
+
+    expect(ruleJsxPreferredImportPath(ix)).toHaveLength(0);
+  });
+
+  it("matches preferred-component policy across component package epochs", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        jsx: [g.jsx.component().prefer("@usefragments/ui#LegacyButton", "@acme/ui#Button")],
+      })
+    );
+    const node = makeUsageNodeFact({
+      file: "src/app.tsx",
+      nodePath: "0:0",
+      element: "LegacyButton",
+      location: { file: "src/app.tsx", line: 4, column: 2 },
+    });
+    ix.add(node);
+    ix.add(
+      makeUsageComponentFact({
+        nodeId: node.id,
+        componentId: asComponentId("@usefragments/ui#LegacyButton"),
+      })
+    );
+
+    expect(ruleJsxPreferredComponent(ix)).toHaveLength(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 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("recognizes a current import through legacy npm source and mapping spellings", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        rules: {
+          "components/prefer-library": {
+            enabled: true,
+            severity: "warning",
+            options: {
+              canonicalSources: [
+                {
+                  kind: "npm",
+                  specifier: "@usefragments/ui",
+                  include: ["Card"],
+                },
+              ],
+              canonicalMappings: [
+                {
+                  name: "Card",
+                  canonical: "Card",
+                  importPath: "@usefragments/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: "@usefragments/ui",
+        location: { file: "src/app.tsx", line: 1, column: 0 },
+      })
+    );
+
+    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
+  });
+
+  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("recognizes a current import through a legacy registry importPath", () => {
+    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: "@usefragments/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: "@usefragments/ui/Card",
+        location: { file: "src/app.tsx", line: 1, column: 0 },
+      })
+    );
+
+    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
+  });
+
+  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: "@usefragments/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: "@usefragments/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: "@usefragments/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("@usefragments/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: "@usefragments/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: "@usefragments/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: "@usefragments/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: "@usefragments/ui",
+          },
+          {
+            name: "Button",
+            canonical: "Button",
+            htmlEquivalent: "button",
+            importPath: "@usefragments/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: "@usefragments/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: "@usefragments/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;