@usefragments/core 1.5.0 → 1.5.2

package/src/rules/rules.test.ts

@@ -509,6 +509,160 @@ describe("preferred JSX imports and components", () => {
     expect(ruleJsxPreferredImportPath(ix)).toHaveLength(0);
   });
 
+  it("governs a confirmed package-to-local bridge without offering an unsafe fix", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        severity: "error",
+        canonicalBridges: [
+          {
+            underlying: { packageName: "@mui/material", exportName: "Button" },
+            local: {
+              componentKey: "src/components/Button.tsx#Button",
+              moduleSpecifier: "@/components",
+              exportName: "Button",
+              implementationFiles: ["src/components/Button.tsx"],
+            },
+            decision: { state: "confirmed", source: "authored" },
+          },
+        ],
+      })
+    );
+    ix.add(
+      makeUsageImportFact({
+        file: "src/app/page.tsx",
+        local: "MuiButton",
+        imported: "Button",
+        source: "@mui/material",
+        location: { file: "src/app/page.tsx", line: 1, column: 0 },
+      })
+    );
+
+    const findings = ruleJsxPreferredImportPath(ix);
+
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({
+      ruleId: "imports/preferred-path",
+      severity: "serious",
+      attributes: {
+        canonicalBridge: true,
+        canonicalTarget: "src/components/Button.tsx#Button",
+        suggestedImport: "@/components",
+        suggestedComponent: "Button",
+      },
+    });
+    expect(findings[0].fix).toBeUndefined();
+  });
+
+  it("matches an exact mapped subpath default import", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        canonicalBridges: [
+          {
+            underlying: { packageName: "@mui/material", exportName: "Button" },
+            local: {
+              componentKey: "src/components/Button.tsx#Button",
+              moduleSpecifier: "@/components",
+              exportName: "Button",
+              implementationFiles: ["src/components/Button.tsx"],
+            },
+            decision: { state: "confirmed", source: "migration" },
+          },
+        ],
+      })
+    );
+    ix.add(
+      makeUsageImportFact({
+        file: "src/app/page.tsx",
+        local: "Button",
+        imported: "default",
+        source: "@mui/material/Button",
+        location: { file: "src/app/page.tsx", line: 1, column: 0 },
+      })
+    );
+
+    expect(ruleJsxPreferredImportPath(ix)).toHaveLength(1);
+  });
+
+  it("exempts only implementation files and leaves unmapped exports unaffected", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        canonicalBridges: [
+          {
+            underlying: { packageName: "@mui/material", exportName: "Button" },
+            local: {
+              componentKey: "src/components/Button.tsx#Button",
+              moduleSpecifier: "@/components",
+              exportName: "Button",
+              implementationFiles: ["src/components/Button.tsx"],
+            },
+            decision: { state: "confirmed", source: "authored" },
+          },
+        ],
+      })
+    );
+    ix.add(
+      makeUsageImportFact({
+        file: "./src/components/Button.tsx",
+        local: "MuiButton",
+        imported: "Button",
+        source: "@mui/material",
+        location: { file: "./src/components/Button.tsx", line: 1, column: 0 },
+      })
+    );
+    ix.add(
+      makeUsageImportFact({
+        file: "src/app/page.tsx",
+        local: "Stepper",
+        imported: "Stepper",
+        source: "@mui/material",
+        location: { file: "src/app/page.tsx", line: 1, column: 0 },
+      })
+    );
+
+    expect(ruleJsxPreferredImportPath(ix)).toHaveLength(0);
+  });
+
+  it("does not exempt sibling helpers, stories, barrels, or consumers", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        canonicalBridges: [
+          {
+            underlying: { packageName: "@mui/material", exportName: "Button" },
+            local: {
+              componentKey: "src/components/Button.tsx#Button",
+              moduleSpecifier: "@/components",
+              exportName: "Button",
+              implementationFiles: ["src/components/Button.tsx"],
+            },
+            decision: { state: "confirmed", source: "authored" },
+          },
+        ],
+      })
+    );
+    for (const file of [
+      "src/components/Button.helpers.tsx",
+      "src/components/Button.stories.tsx",
+      "src/components/index.ts",
+      "src/app/page.tsx",
+    ]) {
+      ix.add(
+        makeUsageImportFact({
+          file,
+          local: "Button",
+          imported: "Button",
+          source: "@mui/material",
+          location: { file, line: 1, column: 0 },
+        })
+      );
+    }
+
+    expect(ruleJsxPreferredImportPath(ix)).toHaveLength(4);
+  });
+
   it("matches preferred-component policy across component package epochs", () => {
     const ix = new FactIndex();
     ix.addMany(
@@ -1245,6 +1399,7 @@ describe("Phase 6 fix payloads", () => {
         name: "--fui-color-accent",
         value: "#2563eb",
         category: "color",
+        referenceFormat: "css-var",
       })
     );
     ix.add(
@@ -1273,8 +1428,18 @@ describe("Phase 6 fix payloads", () => {
   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" }),
+      makeTokenDefinitionFact({
+        name: "--color-bg",
+        value: "#ffffff",
+        category: "color",
+        referenceFormat: "css-var",
+      }),
+      makeTokenDefinitionFact({
+        name: "--color-text",
+        value: "#ffffff",
+        category: "color",
+        referenceFormat: "css-var",
+      }),
     ]);
     ix.add(
       makeStyleDeclarationFact({
@@ -1396,6 +1561,7 @@ describe("Phase 6 fix payloads", () => {
         name: "--fui-color-white",
         value: "#ffffff",
         category: "color",
+        referenceFormat: "css-var",
       })
     );
     ix.add(
@@ -1420,6 +1586,7 @@ describe("Phase 6 fix payloads", () => {
         name: "--fui-color-accent",
         value: "#2563eb",
         category: "color",
+        referenceFormat: "css-var",
       })
     );
     ix.add(
@@ -1446,6 +1613,7 @@ describe("Phase 6 fix payloads", () => {
         name: "--fui-color-accent",
         value: "#2563eb",
         category: "color",
+        referenceFormat: "css-var",
       })
     );
     addButtonUsage(ix, {
@@ -3367,14 +3535,15 @@ function spacingIndexWithTokens(
         name: token.name,
         value: token.value,
         category: "spacing",
-        referenceFormat: token.referenceFormat,
+        referenceFormat:
+          token.referenceFormat ?? (token.name.startsWith("$") ? "scss-var" : "css-var"),
       })
     );
   }
   return ix;
 }
 
-type TokenRefFormat = "css-var" | "scss-var" | "scss-map" | "dtcg";
+type TokenRefFormat = "css-var" | "scss-var" | "scss-map" | "dtcg" | "js-member";
 
 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", () => {
@@ -3438,6 +3607,27 @@ describe("styles/no-raw-spacing — token-aware (BUG 1/13/15)", () => {
     expect(findings[0].fix?.deterministic).toBe(false);
   });
 
+  it("keeps an exact Sass variable swap deterministic", () => {
+    const ix = spacingIndexWithTokens([
+      { name: "$space-md", value: "16px", referenceFormat: "scss-var" },
+    ]);
+    ix.add(
+      makeStyleDeclarationFact({
+        file: "src/x.scss",
+        selector: ".a",
+        declarationPath: "0",
+        property: "padding",
+        value: "16px",
+        location: { file: "src/x.scss", line: 1, column: 0 },
+      })
+    );
+
+    expect(ruleStylesNoRawSpacing(ix)[0]?.fix).toMatchObject({
+      value: "$space-md",
+      deterministic: true,
+    });
+  });
+
   it("catches a camelCase longhand inline spacing prop (marginTop)", () => {
     const ix = spacingIndexWithTokens([]);
     const node = makeUsageNodeFact({
@@ -3477,7 +3667,8 @@ describe("styles/no-raw-color — role correctness + fixer safety (BUG 4/3/11)",
           name: token.name,
           value: token.value,
           category: "color",
-          referenceFormat: token.referenceFormat,
+          referenceFormat:
+            token.referenceFormat ?? (token.name.startsWith("$") ? "scss-var" : "css-var"),
         })
       );
     }
@@ -3548,7 +3739,12 @@ describe("styles/no-raw-typography (BUG 10)", () => {
     );
     for (const token of tokens) {
       ix.add(
-        makeTokenDefinitionFact({ name: token.name, value: token.value, category: "typography" })
+        makeTokenDefinitionFact({
+          name: token.name,
+          value: token.value,
+          category: "typography",
+          referenceFormat: "css-var",
+        })
       );
     }
     return ix;

package/src/rules/spacing-resolution.ts

@@ -91,7 +91,7 @@ export function resolveSpacingValue(input: {
       }
       // On-grid literal that equals a token: value-preserving swap.
       anyViolation = true;
-      const reference = tokenReference(exactToken.name);
+      const reference = tokenReference(exactToken);
       if (!normalized.deterministicFix) allValuePreserving = false;
       suggestedParts.push(reference);
       if (!firstViolation) {
@@ -128,7 +128,7 @@ export function resolveSpacingValue(input: {
       const nearestToken = input.tokens.get(Math.abs(nearest));
       suggestedToken = nearestToken?.name;
       suggestedPart = nearestToken
-        ? tokenReference(nearestToken.name)
+        ? tokenReference(nearestToken)
         : input.bareNumberFix
           ? `${nearest}`
           : `${nearest}${input.scale.unit}`;

package/src/rules/styles-no-raw-color.test.ts

@@ -77,7 +77,12 @@ describe("styles/no-raw-color — #9d SVG paint attributes", () => {
   it("emits a deterministic token fix when stroke matches an accent token exactly", () => {
     const ix = indexWithColorPolicy();
     ix.add(
-      makeTokenDefinitionFact({ name: "--fui-color-accent", value: "#7c3aed", category: "color" })
+      makeTokenDefinitionFact({
+        name: "--fui-color-accent",
+        value: "#7c3aed",
+        category: "color",
+        referenceFormat: "css-var",
+      })
     );
     const nodeId = addNode(ix, "path");
     ix.add(

package/src/rules/styles-no-raw-color.ts

@@ -15,6 +15,7 @@ import type { FactIndex, TokenDefinitionFact } from "../facts/index.js";
 
 import { colorDistance, parseOpaqueColor } from "./color-math.js";
 import { makeFinding } from "./finding.js";
+import { localTokenCandidates } from "./token-candidates.js";
 import type { Finding, FindingReplaceStyleValueFix } from "./types.js";
 import {
   detectRawColor,
@@ -33,7 +34,7 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
   const policy = ix.policy.rawColorPolicy();
   if (!policy) return [];
 
-  const colorTokens = ix.tokens.byCategory("color");
+  const colorTokens = localTokenCandidates(ix, "color");
   const preferLabel = policy.prefer === "token" ? "design token" : "CSS variable";
   const findings: Finding[] = [];
 
@@ -431,7 +432,7 @@ function buildTokenFix(
   match: TokenMatch,
   ix: FactIndex
 ): FixEmission<FindingReplaceStyleValueFix> {
-  const reference = tokenReference(match.token.name);
+  const reference = tokenReference(match.token);
   const value = replaceRawColor(rawValue, rawColor, reference);
   return emitFix(
     {

package/src/rules/styles-no-raw-dimensions.ts

@@ -30,12 +30,14 @@
 import type { FactId, FactIndex, TokenDefinitionFact } from "../facts/index.js";
 
 import { makeFinding } from "./finding.js";
+import { localTokenCandidates } from "./token-candidates.js";
 import type { Finding, FindingReplaceStyleValueFix } from "./types.js";
 import {
   emitFix,
   indexComponentByNodeId,
   parseLengthValue,
   readUsageNode,
+  tokenReference,
   type FixEmission,
 } from "./utils.js";
 
@@ -67,8 +69,8 @@ export function ruleStylesNoRawDimensions(ix: FactIndex): Finding[] {
   if (!policy) return [];
 
   const appliesTo = new Set(policy.appliesTo);
-  const spacingTokens = ix.tokens.byCategory("spacing");
-  const radiusTokens = ix.tokens.byCategory("radius");
+  const spacingTokens = localTokenCandidates(ix, "spacing");
+  const radiusTokens = localTokenCandidates(ix, "radius");
   const preferLabel = policy.prefer === "token" ? "design token" : "CSS variable";
   const findings: Finding[] = [];
 
@@ -368,9 +370,5 @@ function normalizeDimension(value: string): string | null {
 }
 
 function tokenVar(token: TokenDefinitionFact): string {
-  if (token.name.startsWith("$")) return token.name;
-  const cssVarName = token.name.startsWith("--")
-    ? token.name
-    : `--${token.name.replace(/\./g, "-")}`;
-  return `var(${cssVarName})`;
+  return tokenReference(token);
 }

package/src/rules/styles-no-raw-spacing.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  compileGlobalGovernanceFacts,
+  FactIndex,
+  g,
+  makeStyleDeclarationFact,
+  ruleStylesNoRawSpacing,
+} from "../index.js";
+
+describe("styles/no-raw-spacing fork copy", () => {
+  it("names the active scale and its config lever without changing machine attributes", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        scales: {
+          space: g.scale.px([0, 4, 8, 12, 16, 20, 24]),
+        },
+        styles: [
+          g.styles.rawSpacing().mustMatchScale("space", {
+            appliesTo: ["margin-top"],
+            severity: "warn",
+          }),
+        ],
+      })
+    );
+    ix.add(
+      makeStyleDeclarationFact({
+        file: "src/Card.css",
+        selector: ".card",
+        declarationPath: "0",
+        property: "margin-top",
+        value: "10px",
+        location: { file: "src/Card.css", line: 2, column: 3 },
+      })
+    );
+
+    const [finding] = ruleStylesNoRawSpacing(ix);
+
+    expect(finding?.message).toContain("not on the `space` scale");
+    expect(finding?.message).toContain("Configure `govern.scales.space` to change it");
+    expect(finding?.attributes).toMatchObject({
+      scale: "space",
+      rawValue: "10px",
+      source: "css",
+    });
+  });
+});

package/src/rules/styles-no-raw-spacing.ts

@@ -35,6 +35,7 @@ import type {
 } from "../facts/index.js";
 
 import { makeFinding } from "./finding.js";
+import { localTokenCandidates } from "./token-candidates.js";
 import {
   buildSpacingTokenLookup,
   resolveSpacingValue,
@@ -62,7 +63,7 @@ export function ruleStylesNoRawSpacing(ix: FactIndex): Finding[] {
   const lookupFor = (scale: ScaleFact): SpacingTokenLookup => {
     let lookup = lookupCache.get(scale.name);
     if (!lookup) {
-      lookup = buildSpacingTokenLookup(ix.tokens.byCategory("spacing"), scale);
+      lookup = buildSpacingTokenLookup(localTokenCandidates(ix, "spacing"), scale);
       lookupCache.set(scale.name, lookup);
     }
     return lookup;
@@ -116,7 +117,7 @@ function checkDeclaration(
     ruleId: RULE_ID,
     ruleVersion: RULE_VERSION,
     severity: policy.severity,
-    message: spacingMessage(decl.property, decl.value, allowed, scale.unit, checked),
+    message: spacingMessage(decl.property, decl.value, allowed, scale, checked),
     location: decl.location,
     evidence: ix.evidence([decl.id, policy.id, scale.id]),
     fingerprintIdentity: {
@@ -184,7 +185,7 @@ function checkInlineStyle(
     ruleId: RULE_ID,
     ruleVersion: RULE_VERSION,
     severity: policy.severity,
-    message: spacingMessage(inline.property, inline.value, allowed, scale.unit, checked),
+    message: spacingMessage(inline.property, inline.value, allowed, scale, checked),
     location: node.location,
     evidence: ix.evidence(evidenceIds),
     fingerprintIdentity: {
@@ -230,7 +231,9 @@ function buildSpacingFix(
       deterministic: true,
     },
     {
-      symbols: tokenSymbolsInText(checked.suggestedValue),
+      symbols: checked.matchedToken
+        ? [checked.matchedToken]
+        : tokenSymbolsInText(checked.suggestedValue),
       editKind: "replaceStyleValue",
       valuePreserving: checked.deterministicFix,
     },
@@ -242,7 +245,7 @@ function spacingMessage(
   property: string,
   value: string,
   allowed: number[],
-  unit: "px" | "rem",
+  scale: ScaleFact,
   checked: CheckedSpacingValue
 ): string {
   if (checked.reason === "token-equivalent" && checked.matchedToken) {
@@ -252,7 +255,7 @@ function spacingMessage(
     .slice()
     .sort((a, b) => a - b)
     .slice(0, 6);
-  const suffix = `${sample.join(unit + ", ")}${unit}`;
+  const suffix = `${sample.join(scale.unit + ", ")}${scale.unit}`;
   const ellipsis = allowed.length > sample.length ? ", …" : "";
-  return `\`${property}: ${value}\` is not on the spacing scale. Allowed: ${suffix}${ellipsis}.`;
+  return `\`${property}: ${value}\` is not on the \`${scale.name}\` scale. Allowed: ${suffix}${ellipsis}. Configure \`govern.scales.${scale.name}\` to change it.`;
 }

package/src/rules/styles-no-raw-typography.ts

@@ -26,6 +26,7 @@ import type {
 } from "../facts/index.js";
 
 import { makeFinding } from "./finding.js";
+import { localTokenCandidates } from "./token-candidates.js";
 import type { Finding } from "./types.js";
 import {
   indexComponentByNodeId,
@@ -150,7 +151,7 @@ function buildTypographyTokenLookup(
   scale: ScaleFact
 ): Map<number, TokenDefinitionFact> {
   const out = new Map<number, TokenDefinitionFact>();
-  for (const token of ix.tokens.byCategory("typography")) {
+  for (const token of localTokenCandidates(ix, "typography")) {
     const parsed = parseLengthValue(token.value);
     if (!parsed || parsed.unit === null) continue;
     const normalized = normalizeLengthForScale(parsed, scale);
@@ -188,7 +189,7 @@ function checkFontSize(
   if (matchesScale(normalized.value, allowed)) {
     if (!exactToken) return null;
     return {
-      suggestedValue: tokenReference(exactToken.name),
+      suggestedValue: tokenReference(exactToken),
       fixEmittable: true,
       deterministicFix: normalized.deterministicFix,
       reason: "token-equivalent",
@@ -202,7 +203,7 @@ function checkFontSize(
   }
   const nearestToken = tokens.get(Math.abs(nearest));
   const suggestedValue = nearestToken
-    ? tokenReference(nearestToken.name)
+    ? tokenReference(nearestToken)
     : bareNumberFix
       ? `${nearest}`
       : `${nearest}${scale.unit}`;
@@ -231,7 +232,9 @@ function buildFix(
       deterministic: true,
     },
     {
-      symbols: tokenSymbolsInText(checked.suggestedValue),
+      symbols: checked.matchedToken
+        ? [checked.matchedToken]
+        : tokenSymbolsInText(checked.suggestedValue),
       editKind: "replaceStyleValue",
       valuePreserving: checked.deterministicFix,
     },

package/src/rules/taxonomy.test.ts

@@ -95,6 +95,7 @@ describe("rule taxonomy SSOT", () => {
       "components/prefer-library",
       "components/shadow-component",
       "tokens/css-vars-must-be-defined",
+      "tokens/upstream-drift",
     ]);
   });
 
@@ -102,6 +103,7 @@ describe("rule taxonomy SSOT", () => {
     expect(
       [
         "tokens/css-vars-must-be-defined",
+        "tokens/upstream-drift",
         "components/prefer-library",
         "components/shadow-component",
       ].sort(compareByVocabularyRank)
@@ -109,6 +111,7 @@ describe("rule taxonomy SSOT", () => {
       "components/shadow-component",
       "components/prefer-library",
       "tokens/css-vars-must-be-defined",
+      "tokens/upstream-drift",
     ]);
   });
 

package/src/rules/tiers.ts

@@ -30,6 +30,7 @@ export const RULE_TIER: Readonly<Record<string, RuleTier>> = {
   "components/shadow-component": "contract", // canonical-component identity drift
   "components/prefer-library": "contract", // canonical-component bypass (FUI1004)
   "tokens/css-vars-must-be-defined": "contract", // token drift (FUI2015)
+  "tokens/upstream-drift": "contract", // authored local/upstream value drift (FUI2017)
 
   // ---- Tier B — generic hygiene -----------------------------------------
   "components/unknown-prop": "hygiene",
@@ -99,6 +100,7 @@ const VOCABULARY_ORDER: readonly string[] = [
   "components/shadow-component",
   "components/prefer-library",
   "tokens/css-vars-must-be-defined",
+  "tokens/upstream-drift",
 ];
 
 /** Headline rank of a rule id (lower = higher in the vocabulary-first list). */

package/src/rules/token-candidates.ts

@@ -0,0 +1,36 @@
+import type { FactIndex, TokenDefinitionFact } from "../facts/index.js";
+import { normalizeColor } from "../tokens/color.js";
+
+/** Normalize token values using the same comparison contract as drift findings. */
+export function normalizedTokenValue(token: TokenDefinitionFact): string {
+  const value = token.value.trim();
+  return token.category === "color" ? normalizeColor(value) : value.replace(/\s+/g, " ");
+}
+
+/**
+ * Return local definitions that are safe to offer as replacement candidates.
+ * A local definition with one exact authored upstream counterpart is withheld
+ * while their values drift. Missing or ambiguous upstream input remains
+ * visible to drift diagnostics but is never guessed here.
+ */
+export function localTokenCandidates(
+  ix: FactIndex,
+  category?: TokenDefinitionFact["category"]
+): TokenDefinitionFact[] {
+  const all = ix.tokens.list();
+  const upstreamByName = new Map<string, TokenDefinitionFact[]>();
+  for (const token of all) {
+    if (token.role !== "upstream") continue;
+    const matches = upstreamByName.get(token.name) ?? [];
+    matches.push(token);
+    upstreamByName.set(token.name, matches);
+  }
+
+  return all.filter((token) => {
+    if (token.role === "upstream" || (category !== undefined && token.category !== category)) {
+      return false;
+    }
+    const matches = upstreamByName.get(token.upstreamName ?? token.name) ?? [];
+    return matches.length !== 1 || normalizedTokenValue(token) === normalizedTokenValue(matches[0]);
+  });
+}

package/src/rules/tokens-require-dual-fallback.ts

@@ -1,6 +1,7 @@
 import type { FactIndex, TokenDefinitionFact } from "../facts/index.js";
 
 import { makeFinding } from "./finding.js";
+import { localTokenCandidates } from "./token-candidates.js";
 import type { Finding } from "./types.js";
 import { emitFix } from "./utils.js";
 
@@ -22,7 +23,7 @@ export function ruleTokensRequireDualFallback(ix: FactIndex): Finding[] {
   const policy = ix.policy.ruleConfig(RULE_ID);
   if (!policy?.enabled) return [];
 
-  const tokensByCssVariable = indexTokensByCssVariable(ix.tokens.list());
+  const tokensByCssVariable = indexTokensByCssVariable(localTokenCandidates(ix));
   const findings: Finding[] = [];
 
   for (const decl of ix.byKind("style_declaration")) {