@usefragments/core 1.0.0 → 1.3.0

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

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  compileGlobalGovernanceFacts,
+  FactIndex,
+  makeContractTokenFact,
+  makeStyleCssVarsMustBeDefinedFact,
+  makeStyleDeclarationFact,
+  makeTokenDefinitionFact,
+} from "../../index.js";
+import { ruleTokensCssVarsMustBeDefined } from "../tokens-css-vars-must-be-defined.js";
+import { ruleTokensRequireDualFallback } from "../tokens-require-dual-fallback.js";
+
+function declaration(value: string) {
+  return makeStyleDeclarationFact({
+    file: "src/app.scss",
+    selector: ".app",
+    declarationPath: "0",
+    property: "padding",
+    value,
+    location: { file: "src/app.scss", line: 1, column: 0 },
+  });
+}
+
+function index(...facts: Parameters<FactIndex["addMany"]>[0][]): FactIndex {
+  const ix = new FactIndex();
+  ix.addMany(
+    compileGlobalGovernanceFacts({
+      rules: { "tokens/require-dual-fallback": { enabled: true, severity: "error" } },
+    })
+  );
+  for (const group of facts) ix.addMany(group);
+  return ix;
+}
+
+describe("tokens/require-dual-fallback trust floor", () => {
+  it("stays silent for an unregistered token and never invents its Sass symbol (§1)", () => {
+    const ix = index([
+      makeStyleCssVarsMustBeDefinedFact({ severity: "warn" }),
+      makeContractTokenFact({ name: "--fui-space-2" }),
+      declaration("var(--fui-space-9)"),
+    ]);
+
+    expect(ruleTokensRequireDualFallback(ix)).toEqual([]);
+    const undefinedFindings = ruleTokensCssVarsMustBeDefined(ix);
+    expect(undefinedFindings).toHaveLength(1);
+    expect(JSON.stringify(undefinedFindings)).not.toContain("$fui-space-9");
+  });
+
+  it("emits a deterministic fix only for a registered Sass variable and rescans clean (§2)", () => {
+    const token = makeTokenDefinitionFact({
+      name: "$fui-space-2",
+      value: "8px",
+      category: "spacing",
+      referenceFormat: "scss-var",
+    });
+    const ix = index([token, declaration("var(--fui-space-2)")]);
+
+    expect(ruleTokensRequireDualFallback(ix)).toMatchObject([
+      {
+        fix: {
+          kind: "replaceStyleValue",
+          value: "var(--fui-space-2, $fui-space-2)",
+          deterministic: true,
+        },
+      },
+    ]);
+
+    const rescanned = index([token, declaration("var(--fui-space-2, $fui-space-2)")]);
+    expect(ruleTokensRequireDualFallback(rescanned)).toEqual([]);
+  });
+
+  it("keeps the finding but emits no fix for a CSS-only token (§2)", () => {
+    const ix = index([
+      makeTokenDefinitionFact({
+        name: "--fui-color-accent",
+        value: "#2563eb",
+        category: "color",
+        referenceFormat: "css-var",
+      }),
+      declaration("var(--fui-color-accent)"),
+    ]);
+
+    const findings = ruleTokensRequireDualFallback(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].fix).toBeUndefined();
+    expect(findings[0].message).toContain("No matching SCSS variable was found");
+    expect(JSON.stringify(findings[0])).not.toContain("$fui-color-accent)");
+  });
+});

package/src/rules/components-prefer-library.ts

@@ -24,6 +24,8 @@ export const RULE_VERSION = "1";
 
 interface CanonicalMappingOption {
   name: string;
+  /** Internal conform-boundary assertion; only the conform policy builder sets it. */
+  conformStatus?: "confirmed";
   canonical?: string;
   htmlEquivalent?: string;
   /**
@@ -268,7 +270,8 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
     if (node.element.includes(".")) continue;
     const props = propsByNode.get(node.id) ?? [];
     const textChildren = textByNode.get(node.id) ?? [];
-    const imported = importsByFileAndLocal.get(node.file)?.get(node.element);
+    const importsForFile = importsByFileAndLocal.get(node.file);
+    const imported = importsForFile?.get(node.element);
     const nodeInputType =
       node.element === "input" ? readStaticStringProp(props, "type") : undefined;
     const mapped = findMapping(node, nodeInputType, mappings);
@@ -281,6 +284,7 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
       const suggestedComponent = mapped.name;
       const suggestedImport = importPath ?? "the canonical library";
       const propMapping = mapped.propMapping ?? [];
+      const propCompatibility = assessMappedPropCompatibility(props, propMapping);
       const roleMatch = isRoleMatch(node, mapped);
       const precisionTier: RawHtmlPrecisionTier = roleMatch ? "role-reimpl" : "exact-html";
 
@@ -290,6 +294,12 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
         !ownedImportsEqual(imported.source, importPath) &&
         node.element === suggestedComponent
       ) {
+        // A same-name package import is not proof that the package implements
+        // our canonical primitive. For example, TanStack Router's `Link` and a
+        // design-system `Link` share a local JSX name but have different
+        // contracts. Only an unaliased local import is a useful guided
+        // candidate; package migrations need an explicit import policy.
+        if (!isLocalExactComponentImportRedirectCandidate(imported, suggestedComponent)) continue;
         const key = `${imported.file}\0${imported.local}\0${imported.source}\0${importPath}`;
         if (seenImportFixes.has(key)) continue;
         seenImportFixes.add(key);
@@ -297,8 +307,8 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
           makeFinding({
             ruleId: RULE_ID,
             ruleVersion: RULE_VERSION,
-            severity: policy.severity ?? "warn",
-            message: `<${node.element}> should import from ${importPath}.`,
+            severity: capAdvisorySeverity(policy.severity),
+            message: `<${node.element}> may need to import from ${importPath}; verify that the local component contract is compatible first.`,
             location: imported.location,
             evidence: ix.evidence([node.id, imported.id, policy.id]),
             fingerprintIdentity: {
@@ -312,7 +322,7 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
               title: `Replace import path with "${importPath}"`,
               from: imported.source,
               to: importPath,
-              deterministic: true,
+              deterministic: false,
             },
             attributes: {
               rawValue: imported.source,
@@ -320,6 +330,8 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
               suggestedImport: importPath,
               canonical: mapped.canonical,
               confidence: mapped.confidence,
+              advisory: true,
+              contractProof: "missing",
             },
           })
         );
@@ -363,7 +375,11 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
                   title: `Replace <${node.element}> with <${suggestedComponent}>`,
                   from: node.element,
                   to: suggestedComponent,
-                  deterministic: true,
+                  // The fact IR cannot prove that it observed every JSX
+                  // attribute shape (notably dynamic inline styles). The
+                  // conform AST preflight may promote this guided fix only
+                  // after it proves the complete prop surface directly.
+                  deterministic: false,
                 },
               }
             : {}),
@@ -374,8 +390,14 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
             canonical: mapped.canonical,
             confidence: mapped.confidence,
             propMapping,
+            propCompatibility: propCompatibility.complete ? "observed-complete" : "incomplete",
+            ...(mapped.conformStatus === "confirmed" ? { canonicalMappingConfirmed: true } : {}),
+            ...(propCompatibility.unprovenProps.length > 0
+              ? { unprovenProps: propCompatibility.unprovenProps }
+              : {}),
             precisionTier,
             ...(roleMatch ? { matchedRole: node.role } : {}),
+            ...(isRawHtmlAdvisoryTier(precisionTier) ? { advisory: true } : {}),
           },
         })
       );
@@ -387,7 +409,8 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
     // canonical component name is very likely a hand-rolled reimplementation
     // (`<div className={styles.card}>` for a Card). class-name↔component is a
     // naming-intent signal, not structural proof — so this is advisory, capped at
-    // warn, carries no auto-fix, and never blocks a write (see emit-gate).
+    // warn, carries no auto-fix, and never blocks a write (see emit-gate). DOG-03
+    // backlog: deterministic canonical-shell signatures may promote proven matches.
     if (
       (node.element === "div" || node.element === "span") &&
       node.role === undefined &&
@@ -432,6 +455,57 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
     const suggestion = findSuggestionSource(suggestedComponent, sources);
     if (!suggestion) continue;
     if (!builtIn && !shouldSuggest(node, imported)) continue;
+
+    // An exact component-name match is either already canonical (handled near
+    // the top of the loop), a safely redirectable local component import, or an
+    // unrelated component that happens to share a name. Never report a
+    // replaceComponent X -> X no-op, and never infer that one package's `Link`
+    // is interchangeable with another package's `Link`.
+    if (node.element === suggestedComponent) {
+      const importPath = canonicalImportPath(suggestion);
+      if (
+        !imported ||
+        !importPath ||
+        !isLocalExactComponentImportRedirectCandidate(imported, suggestedComponent)
+      ) {
+        continue;
+      }
+      const key = `${imported.file}\0${imported.local}\0${imported.source}\0${importPath}`;
+      if (seenImportFixes.has(key)) continue;
+      seenImportFixes.add(key);
+      findings.push(
+        makeFinding({
+          ruleId: RULE_ID,
+          ruleVersion: RULE_VERSION,
+          severity: capAdvisorySeverity(policy.severity),
+          message: `<${node.element}> may need to import from ${importPath}; verify that the local component contract is compatible first.`,
+          location: imported.location,
+          evidence: ix.evidence([node.id, imported.id, policy.id]),
+          fingerprintIdentity: {
+            file: imported.file,
+            local: imported.local,
+            from: imported.source,
+            to: importPath,
+          },
+          fix: {
+            kind: "replaceImport",
+            title: `Replace import path with "${importPath}"`,
+            from: imported.source,
+            to: importPath,
+            deterministic: false,
+          },
+          attributes: {
+            rawValue: imported.source,
+            suggestedComponent,
+            suggestedImport: importPath,
+            suggestedImportSourceKind: suggestion.kind,
+            advisory: true,
+            contractProof: "missing",
+          },
+        })
+      );
+      continue;
+    }
     // Directory canonical sources are typically derived without an `include`
     // filter (cloud pushes `{ kind: "directory", path }` for every component
     // folder), so `sourceIncludesComponent` matches EVERY name. Without the same
@@ -495,7 +569,10 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
                 title: `Replace ${rawElement} with <${suggestedComponent}>`,
                 from: node.element,
                 to: suggestedComponent,
-                deterministic: true,
+                // A canonical source proves that the target exists, not that
+                // this native element's complete prop contract is compatible.
+                // Only explicit canonical mappings carry that proof.
+                deterministic: false,
               },
             }
           : {}),
@@ -505,6 +582,7 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
           suggestedImport,
           suggestedImportSourceKind: suggestion.kind,
           precisionTier,
+          propCompatibility: "unknown",
           ...(builtIn?.matchedRole ? { matchedRole: builtIn.matchedRole } : {}),
           ...(builtIn?.inputType ? { matchedInputType: builtIn.inputType } : {}),
           ...(isRawHtmlAdvisoryTier(precisionTier) ? { advisory: true } : {}),
@@ -689,6 +767,79 @@ function shouldSuggest(node: UsageNodeFact, imported: UsageImportFact | undefine
   return imported !== undefined;
 }
 
+interface PropCompatibilityAssessment {
+  complete: boolean;
+  unprovenProps: string[];
+}
+
+/**
+ * Prove that every observed prop can survive the component replacement.
+ *
+ * An explicit pass-through (`rawProp === canonicalProp`) is proof too. Spreads,
+ * missing entries, and value translations that cannot be applied exactly stay
+ * unresolved: the canonical mapping proves the target component, but it does
+ * not imply that the target forwards the native element's entire prop surface.
+ */
+function assessMappedPropCompatibility(
+  props: readonly UsagePropResolvedFact[],
+  mappings: ReadonlyArray<NonNullable<CanonicalMappingOption["propMapping"]>[number]>
+): PropCompatibilityAssessment {
+  const byRawProp = new Map(mappings.map((mapping) => [mapping.rawProp, mapping]));
+  const unprovenProps = props.flatMap((prop) => {
+    if (prop.resolution === "spread") return [prop.prop];
+    const mapping = byRawProp.get(prop.prop);
+    if (!mapping || !mappingCanPreserveProp(mapping, prop)) return [prop.prop];
+    return [];
+  });
+  return { complete: unprovenProps.length === 0, unprovenProps };
+}
+
+function mappingCanPreserveProp(
+  mapping: NonNullable<CanonicalMappingOption["propMapping"]>[number],
+  prop: UsagePropResolvedFact
+): boolean {
+  const renames = mapping.rawProp !== mapping.canonicalProp;
+  const valueMap = mapping.valueMap;
+  const translatesValue = valueMap !== undefined && Object.keys(valueMap).length > 0;
+
+  // The conform editor can only rename simple JSX identifiers. A pass-through
+  // needs no edit and can therefore retain valid JSX names such as aria-label.
+  if (renames && (!isIdentifier(mapping.rawProp) || !isIdentifier(mapping.canonicalProp))) {
+    return false;
+  }
+  if (!translatesValue) return true;
+  if (!isIdentifier(mapping.rawProp)) return false;
+  return (
+    prop.resolution === "static" &&
+    typeof prop.value === "string" &&
+    Object.prototype.hasOwnProperty.call(valueMap, prop.value)
+  );
+}
+
+function isLocalExactComponentImportRedirectCandidate(
+  usage: UsageImportFact,
+  componentName: string
+): boolean {
+  return isUnaliasedNamedImport(usage, componentName) && isProjectLocalImportSource(usage.source);
+}
+
+function isUnaliasedNamedImport(usage: UsageImportFact, componentName: string): boolean {
+  return isSimpleComponentBinding(usage, componentName) && usage.imported === componentName;
+}
+
+function isSimpleComponentBinding(usage: UsageImportFact, componentName: string): boolean {
+  return usage.namespace !== true && usage.local === componentName;
+}
+
+function isProjectLocalImportSource(source: string): boolean {
+  return (
+    source.startsWith(".") ||
+    source.startsWith("/") ||
+    source.startsWith("@/") ||
+    source.startsWith("~/")
+  );
+}
+
 /**
  * Case-INSENSITIVE equality for the `htmlEquivalent` ↔ raw-tag comparison.
  * Raw HTML tag names are case-insensitive, but a catalog/author can store a
@@ -734,6 +885,7 @@ function isCanonicalMappingOption(value: unknown): value is CanonicalMappingOpti
   if (record.htmlType !== undefined && typeof record.htmlType !== "string") return false;
   if (record.importPath !== undefined && typeof record.importPath !== "string") return false;
   if (record.confidence !== undefined && typeof record.confidence !== "number") return false;
+  if (record.conformStatus !== undefined && record.conformStatus !== "confirmed") return false;
   if (
     record.declaredHtmlEquivalent !== undefined &&
     typeof record.declaredHtmlEquivalent !== "boolean"
@@ -910,6 +1062,12 @@ function sourceLabel(source: CanonicalSource): string {
   return source.path;
 }
 
+function canonicalImportPath(source: CanonicalSource): string | undefined {
+  if (source.kind === "npm") return source.specifier;
+  if (source.kind === "registry") return source.importPath;
+  return undefined;
+}
+
 function isCanonicalSourceImplementationFile(
   file: string,
   sources: readonly CanonicalSource[]

package/src/rules/emit-gate.test.ts

@@ -35,8 +35,46 @@ describe("isDenyEligible", () => {
     expect(isDenyEligible(warn, true)).toBe(true);
   });
 
-  it("does not deny an explicitly non-deterministic (heuristic) fix", () => {
-    const heuristic = { ...base, fix: { deterministic: false } } as unknown as Finding;
+  it.each(["none", "runtime_advisory", "provenance_bound"] as const)(
+    "never gates or denies %s evidence",
+    (evidenceGrade) => {
+      const lowEvidence = { ...base, evidenceGrade } as unknown as Finding;
+      expect(isDenyEligible(lowEvidence, false)).toBe(false);
+    }
+  );
+
+  it.each(["source_backed", "receipt_backed"] as const)(
+    "allows %s evidence to reach the remaining deny checks",
+    (evidenceGrade) => {
+      const proven = { ...base, evidenceGrade } as unknown as Finding;
+      expect(isDenyEligible(proven, false)).toBe(true);
+    }
+  );
+
+  it("does not deny an explicitly non-deterministic token heuristic", () => {
+    const heuristic = {
+      ...base,
+      ruleId: "styles/no-raw-color",
+      fix: { deterministic: false },
+    } as unknown as Finding;
     expect(isDenyEligible(heuristic, false)).toBe(false);
   });
+
+  it("denies an exact canonical-component violation while withholding its generic fix", () => {
+    const exactComponent = {
+      ...base,
+      fix: { deterministic: false },
+      attributes: { precisionTier: "exact-html", propCompatibility: "observed-complete" },
+    } as unknown as Finding;
+    expect(isDenyEligible(exactComponent, false)).toBe(true);
+  });
+
+  it("keeps a component replacement advisory when observed props are not proven compatible", () => {
+    const incompleteComponent = {
+      ...base,
+      fix: { deterministic: false },
+      attributes: { precisionTier: "exact-html", propCompatibility: "incomplete" },
+    } as unknown as Finding;
+    expect(isDenyEligible(incompleteComponent, false)).toBe(false);
+  });
 });

package/src/rules/emit-gate.ts

@@ -10,6 +10,7 @@
  * `fix` shape — no Node APIs, no config off disk, no clock. The CLI hook
  * re-exports `isDenyEligible` from here.
  */
+import { canBlock } from "../evidence.js";
 import { severityLevel } from "../severity.js";
 import type { Finding } from "./types.js";
 
@@ -30,16 +31,18 @@ export const BLOCKING_RULE_ALLOWLIST: ReadonlySet<string> = new Set([
 ]);
 
 /**
- * Mirrors `scanWithFacts`'s own CI exit logic: a finding gates CI when it is
- * error-severity, or warn-severity under `ci.failOnWarnings`. Gating on exactly
- * this set is what makes a local/emit deny imply a CI failure.
+ * A finding gates CI only when its evidence is source-backed or stronger, it is
+ * not explicitly advisory, and its severity is configured to gate. Missing
+ * grades are treated as source-backed for compatibility with older reports.
  */
 export function gatesCi(finding: Finding, failOnWarnings: boolean): boolean {
+  if (!canBlock(finding.evidenceGrade ?? "source_backed")) return false;
+  if (finding.attributes?.advisory === true) return false;
   const level = severityLevel(finding.severity);
   return level === "error" || (failOnWarnings && level === "warn");
 }
 
-/** A finding may deny iff it is allowlisted, gates CI, and is not a flagged-heuristic fix. */
+/** A finding may deny iff it is allowlisted, gates CI, and is not heuristic. */
 export function isDenyEligible(finding: Finding, failOnWarnings: boolean): boolean {
   if (!BLOCKING_RULE_ALLOWLIST.has(finding.ruleId)) return false;
   // Advisory findings — the low-confidence precision tiers a rule flags with
@@ -50,11 +53,19 @@ export function isDenyEligible(finding: Finding, failOnWarnings: boolean): boole
   // confident" principle as the non-deterministic-fix guard below.
   if (finding.attributes?.advisory === true) return false;
   if (!gatesCi(finding, failOnWarnings)) return false;
-  // An explicitly non-deterministic fix is the engine's own "low confidence /
-  // ambiguous" signal (e.g. several tokens share a value, or a heuristic swap).
-  // Those stay advisory — only deny when the engine is confident. A finding with
-  // no fix at all (e.g. a raw color with no matching token) still gates CI, so it
-  // remains deny-eligible.
-  if (finding.fix?.deterministic === false) return false;
+  // Most explicitly non-deterministic fixes are the engine's own low-confidence
+  // signal (for example, several tokens share a value). A prefer-library
+  // finding may still be an exact policy violation, but hard-denying it is only
+  // DX-safe when the configured mapping proves that every observed prop can be
+  // preserved. The conform AST preflight independently checks the source and
+  // binding before any edit is applied.
+  if (finding.fix?.deterministic === false) {
+    if (
+      finding.ruleId !== "components/prefer-library" ||
+      finding.attributes?.propCompatibility !== "observed-complete"
+    ) {
+      return false;
+    }
+  }
   return true;
 }

package/src/rules/finding.ts

@@ -15,6 +15,7 @@ import { canonicalJson, hash64Hex } from "../facts/ids.js";
 import { byRuleId } from "../codes/index.js";
 import { normalizeFinding, normalizeSeverity } from "../schemas/index.js";
 import type { Severity } from "../schemas/index.js";
+import type { EvidenceGrade } from "../evidence.js";
 
 import type { Finding, FindingFix } from "./types.js";
 
@@ -25,6 +26,7 @@ export interface MakeFindingInput {
   message: string;
   location: FactLocation;
   evidence: FactEvidence[];
+  evidenceGrade?: EvidenceGrade;
   fingerprintIdentity: Record<string, unknown>;
   fix?: FindingFix;
   attributes?: Record<string, unknown>;
@@ -48,6 +50,7 @@ export function makeFinding(input: MakeFindingInput): Finding {
     fingerprint,
     location: input.location,
     evidence: input.evidence,
+    evidenceGrade: input.evidenceGrade ?? "source_backed",
     fix: input.fix,
     attributes: input.attributes,
   });

package/src/rules/fix-availability.ts

@@ -0,0 +1,33 @@
+/**
+ * Whether each implemented rule can emit a fix on at least one finding.
+ *
+ * Rule-backed FUI registry entries derive their `fixAvailable` value from this
+ * map. A parity test keeps the keys in lock-step with `RULES`, so capability is
+ * declared once instead of being repeated in rule and code registries.
+ */
+export const RULE_FIX_AVAILABLE = {
+  "components/unknown-prop": false,
+  "components/forbidden-prop-value": true,
+  "props/invalid-value": true,
+  "imports/preferred-path": true,
+  "components/preferred-component": true,
+  "components/prefer-library": true,
+  "styles/no-raw-color": true,
+  "styles/no-raw-dimensions": true,
+  "styles/no-raw-spacing": true,
+  "styles/no-raw-typography": true,
+  "tailwind/arbitrary-color": false,
+  "tailwind/arbitrary-spacing": true,
+  "tailwind/forbidden-palette": true,
+  "tailwind/off-scale-spacing-token": true,
+  "tailwind/raw-color-via-token": false,
+  "tailwind/unknown-class": false,
+  "tokens/require-dual-fallback": true,
+  "tokens/css-vars-must-be-defined": false,
+  "theme/no-theme-coupled-literal": false,
+  "a11y/required-accessible-name": false,
+  "composition/cardinality": false,
+  "composition/co-occurrence": false,
+} as const satisfies Readonly<Record<string, boolean>>;
+
+export type RuleWithFixAvailability = keyof typeof RULE_FIX_AVAILABLE;