@usefragments/core 1.5.1 → 1.6.0

package/src/rules/rules.test.ts

@@ -17,6 +17,7 @@ import {
   makeUsageNodeFact,
   makeUsagePropResolvedFact,
   makeUsageTextChildFact,
+  projectSupersededImportPathPreferences,
   ruleA11yRequiredAccessibleName,
   ruleComponentsForbiddenPropValue,
   ruleComponentsPreferLibrary,
@@ -32,7 +33,7 @@ import {
   ruleTokensRequireDualFallback,
   runRules,
 } from "../index.js";
-import type { Fact, FactId } from "../index.js";
+import type { CanonicalBridgeV1, Fact, FactId } from "../index.js";
 
 type ButtonProps = {
   variant?: "primary" | "secondary" | "ghost" | "link";
@@ -625,6 +626,129 @@ describe("preferred JSX imports and components", () => {
     expect(ruleJsxPreferredImportPath(ix)).toHaveLength(0);
   });
 
+  // Report #2 B6 (brownfield-canonical brief 03): a confirmed bridge
+  // supersedes any non-bridge preference over the same underlying import —
+  // otherwise both emit with the same fingerprint and the hand rule flags the
+  // wrapper's own implementation file with a self-import fix.
+  describe("bridge supersession of non-bridge import preferences", () => {
+    const B6_BRIDGE: CanonicalBridgeV1 = {
+      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" },
+    };
+
+    it("emits only the bridge finding when a hand-authored record duplicates it", () => {
+      const ix = new FactIndex();
+      ix.addMany(
+        compileGlobalGovernanceFacts({
+          jsx: [g.jsx.importPath().prefer("@mui/material", "@/components", { imported: "Button" })],
+          canonicalBridges: [B6_BRIDGE],
+        })
+      );
+      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].attributes).toMatchObject({ canonicalBridge: true });
+    });
+
+    it("keeps the hand rule silent inside the wrapper implementation file", () => {
+      const ix = new FactIndex();
+      ix.addMany(
+        compileGlobalGovernanceFacts({
+          jsx: [g.jsx.importPath().prefer("@mui/material", "@/components", { imported: "Button" })],
+          canonicalBridges: [B6_BRIDGE],
+        })
+      );
+      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 },
+        })
+      );
+
+      expect(ruleJsxPreferredImportPath(ix)).toHaveLength(0);
+    });
+
+    it("leaves the hand rule firing on imports the bridge does not govern", () => {
+      const ix = new FactIndex();
+      ix.addMany(
+        compileGlobalGovernanceFacts({
+          jsx: [g.jsx.importPath().prefer("@mui/material", "@/components")],
+          canonicalBridges: [B6_BRIDGE],
+        })
+      );
+      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 },
+        })
+      );
+
+      const findings = ruleJsxPreferredImportPath(ix);
+      expect(findings).toHaveLength(1);
+      expect(findings[0].attributes).toMatchObject({ imported: "Stepper" });
+      expect(findings[0].attributes?.canonicalBridge).toBeUndefined();
+    });
+
+    it("names each superseded record through the compile-side projection", () => {
+      const superseded = projectSupersededImportPathPreferences({
+        jsx: [
+          g.jsx.importPath().prefer("@mui/material", "@/components", { imported: "Button" }),
+          g.jsx.importPath().prefer("@mui/material/Button", "@/components"),
+          g.jsx.importPath().prefer("@mui/material", "@/inputs", { imported: "TextField" }),
+          g.jsx.importPath().prefer("@legacy/ui", "@usefragments/ui"),
+        ],
+        canonicalBridges: [B6_BRIDGE],
+      });
+
+      expect(superseded).toEqual([
+        {
+          from: "@mui/material",
+          imported: "Button",
+          to: "@/components",
+          packageName: "@mui/material",
+          underlyingExportName: "Button",
+          localExportName: "Button",
+        },
+        {
+          from: "@mui/material/Button",
+          to: "@/components",
+          packageName: "@mui/material",
+          underlyingExportName: "Button",
+          localExportName: "Button",
+        },
+      ]);
+    });
+
+    it("projects nothing without bridges", () => {
+      expect(
+        projectSupersededImportPathPreferences({
+          jsx: [g.jsx.importPath().prefer("@mui/material", "@/components")],
+        })
+      ).toEqual([]);
+    });
+  });
+
   it("does not exempt sibling helpers, stories, barrels, or consumers", () => {
     const ix = new FactIndex();
     ix.addMany(

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

@@ -20,6 +20,7 @@ import type { Finding, FindingReplaceStyleValueFix } from "./types.js";
 import {
   detectRawColor,
   emitFix,
+  hoppedValue,
   indexComponentByNodeId,
   isExemptColor,
   readUsageNode,
@@ -51,8 +52,9 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
     if (isExemptColor(color, policy.except)) continue;
 
     const resolution = resolveColorToken(decl.property, color, colorTokens);
+    const hopped = hoppedValue(decl);
     const fixEmission =
-      resolution?.kind === "exact"
+      resolution?.kind === "exact" && !hopped
         ? buildTokenFix(decl.property, decl.value, color, resolution, ix)
         : undefined;
     const evidenceIds = resolution
@@ -64,7 +66,9 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
         ruleId: RULE_ID,
         ruleVersion: RULE_VERSION,
         severity: policy.severity,
-        message: colorMessage(color, `\`${decl.property}\``, resolution, preferLabel),
+        message:
+          colorMessage(color, `\`${decl.property}\``, resolution, preferLabel) +
+          (hopped?.suffix ?? ""),
         location: decl.location,
         evidence: ix.evidence(evidenceIds),
         fingerprintIdentity: {
@@ -84,6 +88,7 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
           suggestedToken: resolution?.token.name,
           ...(resolution ? { tokenMatch: resolution.kind } : {}),
           ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
+          ...(hopped?.attributes ?? {}),
         },
       })
     );
@@ -138,8 +143,9 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
 
     const componentEvidenceId = componentByNode.get(node.id)?.id;
     const resolution = resolveColorToken(inline.property, color, colorTokens);
+    const hopped = hoppedValue(inline);
     const fixEmission =
-      resolution?.kind === "exact"
+      resolution?.kind === "exact" && !hopped
         ? buildTokenFix(inline.property, inline.value, color, resolution, ix)
         : undefined;
     const baseEvidence = componentEvidenceId
@@ -152,7 +158,9 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
         ruleId: RULE_ID,
         ruleVersion: RULE_VERSION,
         severity: policy.severity,
-        message: colorMessage(color, `inline \`${inline.property}\``, resolution, preferLabel),
+        message:
+          colorMessage(color, `inline \`${inline.property}\``, resolution, preferLabel) +
+          (hopped?.suffix ?? ""),
         location: node.location,
         evidence: ix.evidence(evidenceIds),
         fingerprintIdentity: {
@@ -172,6 +180,7 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
           suggestedToken: resolution?.token.name,
           ...(resolution ? { tokenMatch: resolution.kind } : {}),
           ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
+          ...(hopped?.attributes ?? {}),
         },
       })
     );

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

@@ -34,6 +34,7 @@ import { localTokenCandidates } from "./token-candidates.js";
 import type { Finding, FindingReplaceStyleValueFix } from "./types.js";
 import {
   emitFix,
+  hoppedValue,
   indexComponentByNodeId,
   parseLengthValue,
   readUsageNode,
@@ -83,14 +84,17 @@ export function ruleStylesNoRawDimensions(ix: FactIndex): Finding[] {
     if (!resolution) continue;
     const tokenIds = resolutionTokenIds(resolution);
     const evidenceIds = tokenIds.length ? [decl.id, policy.id, ...tokenIds] : [decl.id, policy.id];
-    const fixEmission = dimensionFix(decl.property, resolution, ix);
+    const hopped = hoppedValue(decl);
+    const fixEmission = hopped ? undefined : dimensionFix(decl.property, resolution, ix);
 
     findings.push(
       makeFinding({
         ruleId: RULE_ID,
         ruleVersion: RULE_VERSION,
         severity: policy.severity,
-        message: dimensionMessage(decl.value, decl.property, preferLabel, resolution, false),
+        message:
+          dimensionMessage(decl.value, decl.property, preferLabel, resolution, false) +
+          (hopped?.suffix ?? ""),
         location: decl.location,
         evidence: ix.evidence(evidenceIds),
         fingerprintIdentity: {
@@ -108,6 +112,7 @@ export function ruleStylesNoRawDimensions(ix: FactIndex): Finding[] {
           source: "css",
           suggestedToken: resolutionSuggestedToken(resolution),
           ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
+          ...(hopped?.attributes ?? {}),
         },
       })
     );
@@ -131,14 +136,17 @@ export function ruleStylesNoRawDimensions(ix: FactIndex): Finding[] {
       : [node.id, inline.id, policy.id];
     const tokenIds = resolutionTokenIds(resolution);
     const evidenceIds = tokenIds.length ? [...baseEvidence, ...tokenIds] : baseEvidence;
-    const fixEmission = dimensionFix(inline.property, resolution, ix);
+    const hopped = hoppedValue(inline);
+    const fixEmission = hopped ? undefined : dimensionFix(inline.property, resolution, ix);
 
     findings.push(
       makeFinding({
         ruleId: RULE_ID,
         ruleVersion: RULE_VERSION,
         severity: policy.severity,
-        message: dimensionMessage(inline.value, inline.property, preferLabel, resolution, true),
+        message:
+          dimensionMessage(inline.value, inline.property, preferLabel, resolution, true) +
+          (hopped?.suffix ?? ""),
         location: node.location,
         evidence: ix.evidence(evidenceIds),
         fingerprintIdentity: {
@@ -156,6 +164,7 @@ export function ruleStylesNoRawDimensions(ix: FactIndex): Finding[] {
           source: "jsx",
           suggestedToken: resolutionSuggestedToken(resolution),
           ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
+          ...(hopped?.attributes ?? {}),
         },
       })
     );

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

@@ -45,6 +45,7 @@ import {
 import type { Finding } from "./types.js";
 import {
   emitFix,
+  hoppedValue,
   indexComponentByNodeId,
   readUsageNode,
   tokenSymbolsInText,
@@ -111,13 +112,15 @@ function checkDeclaration(
     tokens: lookupFor(scale),
   });
   if (!checked) return null;
-  const fixEmission = buildSpacingFix(decl.property, checked, ix);
+  const hopped = hoppedValue(decl);
+  const fixEmission = hopped ? undefined : buildSpacingFix(decl.property, checked, ix);
 
   return makeFinding({
     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) + (hopped?.suffix ?? ""),
     location: decl.location,
     evidence: ix.evidence([decl.id, policy.id, scale.id]),
     fingerprintIdentity: {
@@ -144,6 +147,7 @@ function checkDeclaration(
       assumedEmBasePx: checked.assumedEmBasePx,
       source: "css",
       ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
+      ...(hopped?.attributes ?? {}),
     },
   });
 }
@@ -171,7 +175,8 @@ function checkInlineStyle(
     bareNumberFix: inline.valueKind === "number",
   });
   if (!checked) return null;
-  const fixEmission = buildSpacingFix(inline.property, checked, ix);
+  const hopped = hoppedValue(inline);
+  const fixEmission = hopped ? undefined : buildSpacingFix(inline.property, checked, ix);
 
   const node = readUsageNode(ix, inline.nodeId);
   if (!node) return null;
@@ -185,7 +190,9 @@ 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) +
+      (hopped?.suffix ?? ""),
     location: node.location,
     evidence: ix.evidence(evidenceIds),
     fingerprintIdentity: {
@@ -212,6 +219,7 @@ function checkInlineStyle(
       assumedEmBasePx: checked.assumedEmBasePx,
       source: "jsx",
       ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
+      ...(hopped?.attributes ?? {}),
     },
   });
 }
@@ -245,7 +253,7 @@ function spacingMessage(
   property: string,
   value: string,
   allowed: number[],
-  unit: "px" | "rem",
+  scale: ScaleFact,
   checked: CheckedSpacingValue
 ): string {
   if (checked.reason === "token-equivalent" && checked.matchedToken) {
@@ -255,7 +263,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

@@ -31,6 +31,7 @@ import type { Finding } from "./types.js";
 import {
   indexComponentByNodeId,
   emitFix,
+  hoppedValue,
   matchesScale,
   nearestSignedScaleValue,
   normalizeLengthForScale,
@@ -61,13 +62,16 @@ export function ruleStylesNoRawTypography(ix: FactIndex): Finding[] {
     if (decl.property.toLowerCase() !== "font-size") continue;
     const checked = checkFontSize(decl.value, allowed, scale, tokens);
     if (!checked) continue;
-    const fixEmission = buildFix(decl.property, checked, ix);
+    const hopped = hoppedValue(decl);
+    const fixEmission = hopped ? undefined : buildFix(decl.property, checked, ix);
     findings.push(
       makeFinding({
         ruleId: RULE_ID,
         ruleVersion: RULE_VERSION,
         severity: policy.severity,
-        message: typographyMessage(decl.property, decl.value, allowed, scale.unit, checked),
+        message:
+          typographyMessage(decl.property, decl.value, allowed, scale.unit, checked) +
+          (hopped?.suffix ?? ""),
         location: decl.location,
         evidence: ix.evidence([decl.id, policy.id, scale.id]),
         fingerprintIdentity: {
@@ -88,6 +92,7 @@ export function ruleStylesNoRawTypography(ix: FactIndex): Finding[] {
           matchedToken: checked.matchedToken,
           source: "css",
           ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
+          ...(hopped?.attributes ?? {}),
         },
       })
     );
@@ -105,7 +110,8 @@ export function ruleStylesNoRawTypography(ix: FactIndex): Finding[] {
       inline.valueKind === "number"
     );
     if (!checked) continue;
-    const fixEmission = buildFix(inline.property, checked, ix);
+    const hopped = hoppedValue(inline);
+    const fixEmission = hopped ? undefined : buildFix(inline.property, checked, ix);
     const node = readUsageNode(ix, inline.nodeId);
     if (!node) continue;
     const componentEvidenceId = componentByNode.get(node.id)?.id;
@@ -117,7 +123,9 @@ export function ruleStylesNoRawTypography(ix: FactIndex): Finding[] {
         ruleId: RULE_ID,
         ruleVersion: RULE_VERSION,
         severity: policy.severity,
-        message: typographyMessage(inline.property, inline.value, allowed, scale.unit, checked),
+        message:
+          typographyMessage(inline.property, inline.value, allowed, scale.unit, checked) +
+          (hopped?.suffix ?? ""),
         location: node.location,
         evidence: ix.evidence(evidenceIds),
         fingerprintIdentity: {
@@ -138,6 +146,7 @@ export function ruleStylesNoRawTypography(ix: FactIndex): Finding[] {
           matchedToken: checked.matchedToken,
           source: "jsx",
           ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
+          ...(hopped?.attributes ?? {}),
         },
       })
     );

package/src/rules/utils.ts

@@ -232,6 +232,45 @@ export function readStyleDeclaration(ix: FactIndex, id: FactId): StyleDeclaratio
   return fact && fact.kind === "style_declaration" ? fact : undefined;
 }
 
+/** What a raw-value rule needs to report a value that arrived through a hop. */
+export interface HoppedValue {
+  /** Appended to the message so the use site names the declaration a reader
+   *  cannot see from the finding's own line. */
+  suffix: string;
+  /** Merged into the finding's attributes for JSON/SARIF consumers. */
+  attributes: {
+    valueFrom: "const-binding";
+    declaredAs: string;
+    declaredAt: string;
+  };
+}
+
+/**
+ * Shared reading of `valueFrom` provenance for the raw-value style rules
+ * (color, spacing, dimensions, typography). One helper so a const-resolved
+ * value reports identically everywhere instead of becoming a color special
+ * case.
+ *
+ * Callers must also drop their fix when this returns a value: the authored text
+ * at the finding's location is an identifier, so replacing "the value" there
+ * would rewrite code the user never wrote.
+ */
+export function hoppedValue(fact: {
+  valueFrom?: { kind: "const-binding"; name: string; location: { file: string; line: number } };
+}): HoppedValue | undefined {
+  const from = fact.valueFrom;
+  if (!from) return undefined;
+  const declaredAt = `${from.location.file}:${from.location.line}`;
+  return {
+    suffix: ` Value comes from \`${from.name}\`, declared at ${declaredAt}.`,
+    attributes: {
+      valueFrom: "const-binding",
+      declaredAs: from.name,
+      declaredAt,
+    },
+  };
+}
+
 /**
  * The set of CSS custom-property names a token vocabulary defines, normalized to
  * `--`-prefixed form. Shared by the token-vocabulary rules

package/src/types.ts

@@ -567,7 +567,10 @@ export interface TokenSourceConfig {
   /** Repo-root-relative token file or glob. */
   path: RepoRelativePath;
 
-  /** Explicit token format, or "auto" to infer from extension/content. */
+  /**
+   * Explicit token format, or "auto" to infer from extension/content. Use
+   * "auto" for statically analyzable TypeScript and JavaScript token modules.
+   */
   format?: TokenSourceFormat;
 }
 
@@ -578,7 +581,10 @@ export interface TokenConfig {
    */
   include?: string[];
 
-  /** Repo-root-relative token source files/globs for monorepos and Cloud setup. */
+  /**
+   * Repo-root-relative token source files/globs for monorepos and Cloud setup.
+   * Set each source to format "auto" for TypeScript or JavaScript token modules.
+   */
   sources?: TokenSourceConfig[];
 
   /**
@@ -613,7 +619,10 @@ export interface TokenConfig {
   /** Enable token comparison in style diffs (default: true) */
   enabled?: boolean;
 
-  /** Token source format detection ('auto' detects from file extension) */
+  /**
+   * Token source format detection. "auto" infers supported formats from the
+   * file extension, including statically analyzable TypeScript/JavaScript modules.
+   */
   format?: TokenSourceFormat;
 
   /** Vendor namespace for Fragments extensions in DTCG files (default: 'com.usefragments') */
@@ -813,12 +822,21 @@ export interface FragmentsConfig {
 
   /** Local component-identity decisions used when Cloud does not own the key. */
   identity?: {
+    /** Authored sanctions, rejections, and dismissals keyed by portable component identity. */
     decisions?: Array<{
       /** Portable component key (`file#exportName`). */
       component: string;
+
+      /** The identity disposition recorded for this component. */
       kind: "sanction" | "reject" | "dismiss";
+
+      /** Optional canonical target (`moduleSpecifier#exportName`) for sanctions. */
       canonicalTarget?: string;
+
+      /** Human-readable rationale stored with the decision. */
       reason?: string;
+
+      /** Stable external identifier used to reconcile an existing decision. */
       decisionId?: string;
     }>;
   };