@usefragments/core 1.0.0 → 1.3.0

package/src/rules/rules.test.ts

@@ -1509,9 +1509,10 @@ describe("tokens/require-dual-fallback", () => {
     );
     ix.addMany([
       makeTokenDefinitionFact({
-        name: "--fui-color-brand",
+        name: "$fui-color-brand",
         value: "#123456",
         category: "color",
+        referenceFormat: "scss-var",
       }),
       makeStyleDeclarationFact({
         file: "src/button.scss",
@@ -1775,7 +1776,7 @@ describe("components/prefer-library", () => {
     expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
   });
 
-  it("flags imported bespoke components when package canonical sources include the exported component", () => {
+  it("keeps same-name local import redirects advisory without a verified source contract", () => {
     const ix = new FactIndex();
     ix.addMany(
       compileGlobalGovernanceFacts({
@@ -1812,13 +1813,57 @@ describe("components/prefer-library", () => {
     expect(findings[0]).toMatchObject({
       ruleId: "components/prefer-library",
       code: "FUI1004",
+      fix: {
+        kind: "replaceImport",
+        from: "../components/Card",
+        to: "@acme/ui",
+        deterministic: false,
+      },
       attributes: {
         suggestedComponent: "Card",
         suggestedImport: "@acme/ui",
+        advisory: true,
+        contractProof: "missing",
       },
     });
   });
 
+  it("does not mistake TanStack Router Link for the canonical Link by name alone", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        rules: {
+          "components/prefer-library": {
+            enabled: true,
+            severity: "error",
+            options: {
+              canonicalSources: [{ kind: "npm", specifier: "@acme/ui", include: ["Link"] }],
+            },
+          },
+        },
+      })
+    );
+    ix.add(
+      makeUsageNodeFact({
+        file: "src/app.tsx",
+        nodePath: "0:0",
+        element: "Link",
+        location: { file: "src/app.tsx", line: 5, column: 4 },
+      })
+    );
+    ix.add(
+      makeUsageImportFact({
+        file: "src/app.tsx",
+        local: "Link",
+        imported: "Link",
+        source: "@tanstack/react-router",
+        location: { file: "src/app.tsx", line: 1, column: 0 },
+      })
+    );
+
+    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
+  });
+
   it("recognizes a current import through legacy npm source and mapping spellings", () => {
     const ix = new FactIndex();
     ix.addMany(
@@ -2159,7 +2204,7 @@ describe("components/prefer-library", () => {
     expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
   });
 
-  it("attaches a deterministic component fix from confirmed canonical mappings", () => {
+  it("keeps a complete mapped replacement guided until the conform AST preflight", () => {
     const ix = new FactIndex();
     ix.addMany(
       compileGlobalGovernanceFacts({
@@ -2183,6 +2228,15 @@ describe("components/prefer-library", () => {
         },
       })
     );
+    ix.add(
+      makeUsageImportFact({
+        file: "src/app.tsx",
+        local: "Button",
+        imported: "Button",
+        source: "@acme/ui",
+        location: { file: "src/app.tsx", line: 1, column: 0 },
+      })
+    );
     ix.add(
       makeUsageNodeFact({
         file: "src/app.tsx",
@@ -2200,14 +2254,102 @@ describe("components/prefer-library", () => {
         kind: "replaceComponent",
         from: "button",
         to: "Button",
-        deterministic: true,
+        deterministic: false,
       },
       attributes: {
         suggestedComponent: "Button",
         suggestedImport: "@acme/ui",
         propMapping: [{ rawProp: "className", canonicalProp: "variant" }],
+        propCompatibility: "observed-complete",
       },
     });
+    expect(findings[0].attributes).not.toHaveProperty("canonicalMappingConfirmed");
+  });
+
+  it("withholds a native-element fix when a native-only prop has no confirmed mapping", () => {
+    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",
+                },
+              ],
+            },
+          },
+        },
+      })
+    );
+    ix.add(
+      makeUsageImportFact({
+        file: "src/app.tsx",
+        local: "Button",
+        imported: "Button",
+        source: "@acme/ui",
+        location: { file: "src/app.tsx", line: 1, column: 0 },
+      })
+    );
+    addRawNode(ix, {
+      element: "button",
+      nodePath: "0:0",
+      props: [{ prop: "formAction", value: "/save" }],
+    });
+
+    const findings = ruleComponentsPreferLibrary(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({
+      fix: { kind: "replaceComponent", deterministic: false },
+      attributes: {
+        propCompatibility: "incomplete",
+        unprovenProps: ["formAction"],
+      },
+    });
+  });
+
+  it("keeps replacement metadata but marks it non-deterministic when its import is absent", () => {
+    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",
+                },
+              ],
+            },
+          },
+        },
+      })
+    );
+    addRawNode(ix, { element: "button", nodePath: "0:0", text: "Save" });
+
+    const findings = ruleComponentsPreferLibrary(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].attributes).toMatchObject({
+      suggestedComponent: "Button",
+      suggestedImport: "@acme/ui",
+    });
+    expect(findings[0].fix).toMatchObject({
+      kind: "replaceComponent",
+      from: "button",
+      to: "Button",
+      deterministic: false,
+    });
   });
 
   it("does not flag generic <div>/<span> from an inferred component primitive (anti-flood)", () => {
@@ -2561,29 +2703,38 @@ describe("components/prefer-library", () => {
       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)", () => {
+    it("STILL fires the legit local name-based import redirect (<Modal> → 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"
+        "../Modal"
       );
       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", () => {
+    it("STILL fires for a local import when name === canonical (<Dialog> for name 'Dialog')", () => {
       const findings = importedFindings(
         [{ name: "Dialog", canonical: "Dialog", importPath: "@acme/ui" }],
         "Dialog",
-        "react-aria"
+        "../Dialog"
       );
       expect(findings).toHaveLength(1);
       expect(findings[0].attributes?.suggestedComponent).toBe("Dialog");
     });
+
+    it("does not redirect a package-owned same-name Link without an explicit import policy", () => {
+      const findings = importedFindings(
+        [{ name: "Link", canonical: "Link", importPath: "@acme/ui" }],
+        "Link",
+        "@tanstack/react-router"
+      );
+      expect(findings).toHaveLength(0);
+    });
   });
 
   describe("directory canonical source (unfiltered include — dogfood shape)", () => {
@@ -2672,7 +2823,7 @@ describe("components/prefer-library", () => {
       expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
     });
 
-    it("flags raw <button> → Button when Button is a declared directory canonical", () => {
+    it("flags raw <button> → Button without advertising it as deterministic when Button is not imported", () => {
       const ix = new FactIndex();
       ix.addMany(
         compileGlobalGovernanceFacts({
@@ -2704,18 +2855,18 @@ describe("components/prefer-library", () => {
       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",
         },
       });
+      expect(findings[0].fix).toMatchObject({
+        kind: "replaceComponent",
+        from: "button",
+        to: "Button",
+        deterministic: false,
+      });
     });
 
     it("flags a raw element by canonical vocab id when display name diverges (Modal → Dialog)", () => {
@@ -2825,7 +2976,9 @@ describe("components/prefer-library", () => {
 
     const findings = ruleComponentsPreferLibrary(ix);
 
-    // type-specific mappings win over the generic tag-level one; text falls back
+    // Type-specific mappings win over the generic tag-level one; text falls
+    // back. No canonical bindings exist in this fixture, so suggestions remain
+    // useful but are not advertised as deterministic edits.
     expect(findings.map((finding) => finding.attributes?.suggestedComponent)).toEqual([
       "Checkbox",
       "RadioGroup",
@@ -2836,7 +2989,7 @@ describe("components/prefer-library", () => {
       "RadioGroup",
       "TextField",
     ]);
-    expect(findings.every((finding) => finding.fix?.deterministic === true)).toBe(true);
+    expect(findings.every((finding) => finding.fix?.deterministic === false)).toBe(true);
   });
 
   it("does not let a type-constrained mapping match a different or untyped input", () => {
@@ -2872,7 +3025,7 @@ describe("components/prefer-library", () => {
     expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
   });
 
-  it("attaches a deterministic import fix for canonical components from the wrong path", () => {
+  it("keeps a same-name local import redirect advisory without source-contract proof", () => {
     const ix = new FactIndex();
     ix.addMany(
       compileGlobalGovernanceFacts({
@@ -2918,9 +3071,10 @@ describe("components/prefer-library", () => {
         kind: "replaceImport",
         from: "../Button",
         to: "@acme/ui",
-        deterministic: true,
+        deterministic: false,
       },
       location: { line: 1, column: 0 },
+      attributes: { advisory: true, contractProof: "missing" },
     });
   });
 
@@ -2967,13 +3121,14 @@ describe("components/prefer-library", () => {
         suggestedComponent: "Alert",
         matchedRole: "status",
         confidence: 0.9,
+        advisory: true,
       },
     });
     // Role matches are advisory: no deterministic tag→component rewrite.
     expect(findings[0].fix).toBeUndefined();
   });
 
-  it("flags input type primitives config-free with deterministic fixes", () => {
+  it("flags input type primitives config-free without unsafe missing-import fixes", () => {
     const ix = preferLibraryIndex();
     addRawNode(ix, {
       element: "input",
@@ -3003,7 +3158,7 @@ describe("components/prefer-library", () => {
       "input-type",
       "input-type",
     ]);
-    expect(findings.map((finding) => finding.fix?.deterministic)).toEqual([true, true, true]);
+    expect(findings.every((finding) => finding.fix?.deterministic === false)).toBe(true);
   });
 
   it("does not infer generic text inputs as deterministic primitives", () => {
@@ -3093,7 +3248,7 @@ describe("components/prefer-library", () => {
       kind: "replaceComponent",
       from: "button",
       to: "Button",
-      deterministic: true,
+      deterministic: false,
     });
   });
 
@@ -3139,13 +3294,13 @@ describe("components/prefer-library", () => {
       kind: "replaceComponent",
       from: "button",
       to: "Button",
-      deterministic: true,
+      deterministic: false,
     });
     expect(findings[2].fix).toMatchObject({
       kind: "replaceComponent",
       from: "button",
       to: "Button",
-      deterministic: true,
+      deterministic: false,
     });
   });
 
@@ -3430,6 +3585,7 @@ describe("styles/no-raw-typography (BUG 10)", () => {
     );
     const findings = ruleStylesNoRawTypography(ix);
     expect(findings).toHaveLength(1);
+    expect(findings[0].code).toBe("FUI2016");
     expect(findings[0].fix).toMatchObject({
       value: "var(--font-size-md)",
       deterministic: true,

package/src/rules/spacing-resolution.ts

@@ -1,7 +1,6 @@
 import type { TokenDefinitionFact } from "../facts/index.js";
 
 import {
-  isApplicableTokenReference,
   matchesScale,
   nearestSignedScaleValue,
   normalizeLengthForScale,
@@ -75,7 +74,7 @@ export function resolveSpacingValue(input: {
   let reliableSuggestion = true;
   // Deterministic only when every violating part is a value-preserving,
   // verbatim-resolvable token swap.
-  let allApplicableValuePreserving = true;
+  let allValuePreserving = true;
 
   for (const part of parts) {
     const normalized = normalizeLengthForScale(part.parsed, input.scale);
@@ -93,9 +92,7 @@ export function resolveSpacingValue(input: {
       // On-grid literal that equals a token: value-preserving swap.
       anyViolation = true;
       const reference = tokenReference(exactToken.name);
-      const applicable =
-        isApplicableTokenReference(exactToken.referenceFormat) && normalized.deterministicFix;
-      if (!applicable) allApplicableValuePreserving = false;
+      if (!normalized.deterministicFix) allValuePreserving = false;
       suggestedParts.push(reference);
       if (!firstViolation) {
         firstViolation = {
@@ -103,7 +100,7 @@ export function resolveSpacingValue(input: {
           suggestedValue: reference,
           suggestedToken: exactToken.name,
           fixEmittable: true,
-          deterministicFix: applicable,
+          deterministicFix: normalized.deterministicFix,
           reason: "token-equivalent",
           matchedToken: exactToken.name,
           assumedRootFontSizePx: normalized.assumedRootFontSizePx,
@@ -117,7 +114,7 @@ export function resolveSpacingValue(input: {
     // one exists. Snapping changes rendered value, so this is not deterministic.
     anyViolation = true;
     anyOffScale = true;
-    allApplicableValuePreserving = false;
+    allValuePreserving = false;
 
     const nearest = nearestSignedScaleValue(normalized.value, input.allowed);
     const snapsToZero = nearest === 0 && normalized.value !== 0;
@@ -158,7 +155,7 @@ export function resolveSpacingValue(input: {
   const joined = suggestedParts.join(" ");
   const changes = joined !== input.raw.trim().replace(/\s+/g, " ");
   const fixEmittable = canFixAll && reliableSuggestion && changes;
-  const deterministic = fixEmittable && !anyOffScale && allApplicableValuePreserving;
+  const deterministic = fixEmittable && !anyOffScale && allValuePreserving;
 
   return {
     ...firstViolation,

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

@@ -18,11 +18,12 @@ import { makeFinding } from "./finding.js";
 import type { Finding, FindingReplaceStyleValueFix } from "./types.js";
 import {
   detectRawColor,
+  emitFix,
   indexComponentByNodeId,
-  isApplicableTokenReference,
   isExemptColor,
   readUsageNode,
   tokenReference,
+  type FixEmission,
 } from "./utils.js";
 
 export const RULE_ID = "styles/no-raw-color";
@@ -43,6 +44,10 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
     if (isExemptColor(color, policy.except)) continue;
 
     const resolution = resolveColorToken(decl.property, color, colorTokens);
+    const fixEmission =
+      resolution?.kind === "exact"
+        ? buildTokenFix(decl.property, decl.value, color, resolution, ix)
+        : undefined;
     const evidenceIds = resolution
       ? [decl.id, policy.id, resolution.token.id]
       : [decl.id, policy.id];
@@ -63,10 +68,7 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
           property: decl.property,
           value: color,
         },
-        fix:
-          resolution?.kind === "exact"
-            ? buildTokenFix(decl.property, decl.value, color, resolution)
-            : undefined,
+        fix: fixEmission?.fix,
         attributes: {
           property: decl.property,
           rawValue: decl.value,
@@ -74,6 +76,7 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
           source: "css",
           suggestedToken: resolution?.token.name,
           ...(resolution ? { tokenMatch: resolution.kind } : {}),
+          ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
         },
       })
     );
@@ -91,6 +94,10 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
 
     const componentEvidenceId = componentByNode.get(node.id)?.id;
     const resolution = resolveColorToken(inline.property, color, colorTokens);
+    const fixEmission =
+      resolution?.kind === "exact"
+        ? buildTokenFix(inline.property, inline.value, color, resolution, ix)
+        : undefined;
     const baseEvidence = componentEvidenceId
       ? [node.id, componentEvidenceId, inline.id, policy.id]
       : [node.id, inline.id, policy.id];
@@ -112,10 +119,7 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
           property: inline.property,
           value: color,
         },
-        fix:
-          resolution?.kind === "exact"
-            ? buildTokenFix(inline.property, inline.value, color, resolution)
-            : undefined,
+        fix: fixEmission?.fix,
         attributes: {
           property: inline.property,
           rawValue: inline.value,
@@ -123,6 +127,7 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
           source: "jsx",
           suggestedToken: resolution?.token.name,
           ...(resolution ? { tokenMatch: resolution.kind } : {}),
+          ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
         },
       })
     );
@@ -298,22 +303,26 @@ function buildTokenFix(
   property: string,
   rawValue: string,
   rawColor: string,
-  match: TokenMatch
-): FindingReplaceStyleValueFix {
+  match: TokenMatch,
+  ix: FactIndex
+): FixEmission<FindingReplaceStyleValueFix> {
   const reference = tokenReference(match.token.name);
   const value = replaceRawColor(rawValue, rawColor, reference);
-  return {
-    kind: "replaceStyleValue",
-    title: `Replace ${property} with ${value}`,
-    property,
-    value,
-    // Apply automatically only when the swap is unambiguous AND the reference
-    // resolves verbatim. An ambiguous match (several tokens share the value,
-    // none role-matching) or a token that can't be referenced from CSS (a Sass
-    // *map* member, or a DTCG JSON token with no emitted custom property) is a
-    // suggestion — applying it would cross roles or write non-compiling code.
-    deterministic: !match.ambiguous && isApplicableTokenReference(match.token.referenceFormat),
-  };
+  return emitFix(
+    {
+      kind: "replaceStyleValue",
+      title: `Replace ${property} with ${value}`,
+      property,
+      value,
+      deterministic: true,
+    },
+    {
+      symbols: [match.token.name],
+      editKind: "replaceStyleValue",
+      valuePreserving: !match.ambiguous,
+    },
+    ix
+  );
 }
 
 function replaceRawColor(rawValue: string, rawColor: string, replacement: string): string {

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

@@ -31,7 +31,13 @@ import type { FactId, FactIndex, TokenDefinitionFact } from "../facts/index.js";
 
 import { makeFinding } from "./finding.js";
 import type { Finding, FindingReplaceStyleValueFix } from "./types.js";
-import { indexComponentByNodeId, parseLengthValue, readUsageNode } from "./utils.js";
+import {
+  emitFix,
+  indexComponentByNodeId,
+  parseLengthValue,
+  readUsageNode,
+  type FixEmission,
+} from "./utils.js";
 
 export const RULE_ID = "styles/no-raw-dimensions";
 export const RULE_VERSION = "1";
@@ -75,6 +81,7 @@ 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);
 
     findings.push(
       makeFinding({
@@ -92,12 +99,13 @@ export function ruleStylesNoRawDimensions(ix: FactIndex): Finding[] {
           property: decl.property,
           value: decl.value,
         },
-        fix: dimensionFix(decl.property, resolution),
+        fix: fixEmission?.fix,
         attributes: {
           property: decl.property,
           rawValue: decl.value,
           source: "css",
           suggestedToken: resolutionSuggestedToken(resolution),
+          ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
         },
       })
     );
@@ -121,6 +129,7 @@ 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);
 
     findings.push(
       makeFinding({
@@ -138,12 +147,13 @@ export function ruleStylesNoRawDimensions(ix: FactIndex): Finding[] {
           property: inline.property,
           value: inline.value,
         },
-        fix: dimensionFix(inline.property, resolution),
+        fix: fixEmission?.fix,
         attributes: {
           property: inline.property,
           rawValue: inline.value,
           source: "jsx",
           suggestedToken: resolutionSuggestedToken(resolution),
+          ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
         },
       })
     );
@@ -219,16 +229,25 @@ function dimensionMessage(
 
 function dimensionFix(
   property: string,
-  resolution: DimensionResolution
-): FindingReplaceStyleValueFix | undefined {
+  resolution: DimensionResolution,
+  ix: FactIndex
+): FixEmission<FindingReplaceStyleValueFix> | undefined {
   if (resolution.kind === "exact") {
-    return {
-      kind: "replaceStyleValue",
-      title: `Replace ${property} with ${resolution.fixValue}`,
-      property,
-      value: resolution.fixValue,
-      deterministic: true,
-    };
+    return emitFix(
+      {
+        kind: "replaceStyleValue",
+        title: `Replace ${property} with ${resolution.fixValue}`,
+        property,
+        value: resolution.fixValue,
+        deterministic: true,
+      },
+      {
+        symbols: resolution.tokens.map((token) => token.name),
+        editKind: "replaceStyleValue",
+        valuePreserving: true,
+      },
+      ix
+    );
   }
   // `nearest` deliberately emits NO fix — a value-changing snap must stay a
   // suggestion (see DimensionResolution); only the exact, value-preserving swap