@usefragments/core 1.7.1 → 1.9.0

package/src/rules/rules.test.ts

@@ -37,6 +37,7 @@ import {
 } from "../index.js";
 import type { CanonicalBridgeV1, Fact, FactId } from "../index.js";
 import { RULE_VERSION as A11Y_REQUIRED_ACCESSIBLE_NAME_VERSION } from "./a11y-required-accessible-name.js";
+import { makeFinding } from "./finding.js";
 
 type ButtonProps = {
   variant?: "primary" | "secondary" | "ghost" | "link";
@@ -438,6 +439,78 @@ describe("preferred JSX imports and components", () => {
     });
   });
 
+  it("keeps preferred-path fingerprints stable across line drift", () => {
+    const findingsAtLine = (line: number) => {
+      const ix = new FactIndex();
+      ix.addMany(
+        compileGlobalGovernanceFacts({
+          jsx: [g.jsx.importPath().prefer("@legacy/ui", "@usefragments/ui", { severity: "error" })],
+        })
+      );
+      ix.add(
+        makeUsageImportFact({
+          file: "apps/checkout/page.tsx",
+          local: "Button",
+          imported: "Button",
+          source: "@legacy/ui",
+          location: { file: "apps/checkout/page.tsx", line, column: 0 },
+        })
+      );
+      return ruleJsxPreferredImportPath(ix);
+    };
+
+    const before = findingsAtLine(1);
+    const after = findingsAtLine(9);
+
+    expect(after[0].fingerprint).toBe(before[0].fingerprint);
+    // Byte-pinned hashes: the legacy value is what a released v1 CLI recorded
+    // for this exact tuple (hash64Hex(canonicalJson({ruleId, file, from, to,
+    // line, column}))). If previousFingerprintIdentity ever drifts from the
+    // true v1 formula, real baselines mass-invalidate — this literal is the
+    // tripwire.
+    expect(before[0].fingerprint).toBe("4deee0ff7bb1810b");
+    expect(before[0].previousFingerprint).toBe("c04344ad7a96b651");
+    // The grace-window legacy hash still tracks position, so a v1 baseline
+    // recorded at either line matches exactly one of the two runs.
+    expect(after[0].previousFingerprint).not.toBe(before[0].previousFingerprint);
+  });
+
+  it("distinguishes repeated same-identity imports by source-order occurrence", () => {
+    // Two imports of the same specifier under different local aliases share the
+    // fingerprint identity tuple (local never enters the hash) — the ordinal
+    // tells them apart. Byte-identical duplicates collapse at the fact layer.
+    const findingsFor = (locals: readonly string[]) => {
+      const ix = new FactIndex();
+      ix.addMany(
+        compileGlobalGovernanceFacts({
+          jsx: [g.jsx.importPath().prefer("@legacy/ui", "@usefragments/ui", { severity: "error" })],
+        })
+      );
+      locals.forEach((local, index) => {
+        ix.add(
+          makeUsageImportFact({
+            file: "apps/checkout/page.tsx",
+            local,
+            imported: "Button",
+            source: "@legacy/ui",
+            location: { file: "apps/checkout/page.tsx", line: index * 10 + 1, column: 0 },
+          })
+        );
+      });
+      return ruleJsxPreferredImportPath(ix);
+    };
+
+    const both = findingsFor(["Button", "AliasedButton"]);
+    expect(both).toHaveLength(2);
+    expect(both[0].fingerprint).not.toBe(both[1].fingerprint);
+
+    // Deleting the first occurrence promotes the survivor to its ordinal, so
+    // the remaining debt matches a fingerprint the baseline already accepts.
+    const survivor = findingsFor(["AliasedButton"]);
+    expect(survivor).toHaveLength(1);
+    expect(survivor[0].fingerprint).toBe(both[0].fingerprint);
+  });
+
   it("emits a deterministic component replacement for canonical component mappings", () => {
     const legacyButtonId = makeComponentId("@legacy/ui", "LegacyButton");
     const ix = new FactIndex();
@@ -4163,6 +4236,47 @@ describe("styles/no-raw-dimensions", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// makeFinding fingerprint contract
+// ---------------------------------------------------------------------------
+
+describe("makeFinding fingerprint contract", () => {
+  const base = {
+    ruleId: "styles/no-raw-color",
+    ruleVersion: "1",
+    severity: "serious" as const,
+    message: "Raw color",
+    location: { file: "src/App.tsx", line: 3, column: 1 },
+    evidence: [{ factId: "fact-1" as FactId, fact: { kind: "style_declaration" } }],
+  };
+
+  it("rejects position keys in fingerprintIdentity", () => {
+    expect(() =>
+      makeFinding({
+        ...base,
+        fingerprintIdentity: { file: "src/App.tsx", value: "#fff", line: 3, column: 1 },
+      })
+    ).toThrow(/position keys \(line, column\)/);
+  });
+
+  it("hashes a legacy identity into previousFingerprint when provided", () => {
+    const migrated = makeFinding({
+      ...base,
+      fingerprintIdentity: { file: "src/App.tsx", value: "#fff", occurrence: 0 },
+      previousFingerprintIdentity: { file: "src/App.tsx", value: "#fff", line: 3, column: 1 },
+    });
+    const plain = makeFinding({
+      ...base,
+      fingerprintIdentity: { file: "src/App.tsx", value: "#fff", occurrence: 0 },
+    });
+
+    expect(migrated.fingerprint).toBe(plain.fingerprint);
+    expect(migrated.previousFingerprint).toBeDefined();
+    expect(migrated.previousFingerprint).not.toBe(migrated.fingerprint);
+    expect(plain.previousFingerprint).toBeUndefined();
+  });
+});
+
 // Type witness so eslint/tsc don't trip on unused imports above.
 const _typeWitness: Fact[] = [];
 void _typeWitness;

package/src/rules/tokens-css-vars-must-be-defined.test.ts

@@ -7,7 +7,10 @@ import {
   makeStyleDeclarationFact,
 } from "../index.js";
 import type { Fact } from "../index.js";
-import { ruleTokensCssVarsMustBeDefined } from "./tokens-css-vars-must-be-defined.js";
+import {
+  contractTokenReferenceCensus,
+  ruleTokensCssVarsMustBeDefined,
+} from "./tokens-css-vars-must-be-defined.js";
 
 /**
  * ACCEPTANCE §4 (rule level) + §11 (regression lock).
@@ -242,3 +245,65 @@ describe("ruleTokensCssVarsMustBeDefined", () => {
     expect(reversed).toHaveLength(2);
   });
 });
+
+describe("contractTokenReferenceCensus", () => {
+  function declAt(line: number, value: string): Fact {
+    const file = "src/Card.module.scss";
+    return makeStyleDeclarationFact({
+      file,
+      selector: ".card",
+      declarationPath: `.card:${line}`,
+      property: "color",
+      value,
+      location: { file, line, column: 2 },
+    });
+  }
+
+  it("is unmeasured (undefined) while the rule is inert — no policy fact or no vocabulary", () => {
+    expect(
+      contractTokenReferenceCensus(index([...vocabulary(), declAt(1, "var(--fui-color-accent)")]))
+    ).toBeUndefined();
+    expect(
+      contractTokenReferenceCensus(index([POLICY, declAt(1, "var(--fui-color-accent)")]))
+    ).toBeUndefined();
+  });
+
+  it("counts distinct judged declaration sites — clean and drifting alike, foreign excluded", () => {
+    const census = contractTokenReferenceCensus(
+      index([
+        POLICY,
+        ...vocabulary(),
+        declAt(1, "var(--fui-color-accent)"), // clean, judged
+        declAt(2, "var(--fui-color-brand)"), // drift, judged
+        declAt(3, "var(--swiper-theme-color)"), // foreign, never judged
+        declAt(4, "#39594d"), // no reference at all
+      ])
+    );
+    expect(census).toEqual({ checkedSites: 2 });
+  });
+
+  it("counts a site once regardless of how many judged references it carries", () => {
+    const census = contractTokenReferenceCensus(
+      index([
+        POLICY,
+        ...vocabulary(),
+        declAt(1, "var(--fui-color-accent) var(--fui-space-2) var(--fui-color-brand)"),
+      ])
+    );
+    expect(census).toEqual({ checkedSites: 1 });
+  });
+
+  it("judges only the PRIMARY var() position, exactly like the rule (#17)", () => {
+    // The only primary reference is foreign; the in-contract token sits in
+    // fallback position and must not create a checked site the rule would
+    // never have judged.
+    const census = contractTokenReferenceCensus(
+      index([
+        POLICY,
+        ...vocabulary(),
+        declAt(1, "var(--swiper-theme-color, var(--fui-color-accent))"),
+      ])
+    );
+    expect(census).toEqual({ checkedSites: 0 });
+  });
+});

package/src/rules/tokens-css-vars-must-be-defined.ts

@@ -39,9 +39,22 @@ const CSS_VAR_REFERENCE = /var\(\s*(--[A-Za-z0-9_-]+)/gi;
  * for projects without a contract. Hardcoded values are handled by the unchanged
  * `styles/no-raw-color` rule; this rule only judges custom-property references.
  */
-export function ruleTokensCssVarsMustBeDefined(ix: FactIndex): Finding[] {
-  const policy = ix.policy.cssVarsMustBeDefined();
-  if (!policy) return [];
+interface ContractVocabularyContext {
+  vocabulary: ReadonlySet<string>;
+  prefixes: ReadonlySet<string>;
+  hasFlatTokens: boolean;
+  locallyDefinedCustomProperties: ReadonlySet<string>;
+}
+
+/**
+ * The judgment context the rule scans with, or `undefined` while the rule is
+ * inert (no `style.cssVars.mustBeDefined` policy fact, or no authored contract
+ * vocabulary). Shared with `contractTokenReferenceCensus` so the health
+ * metric's denominator and this rule's findings are computed over the same
+ * population, by the same shape gate.
+ */
+function contractVocabularyContext(ix: FactIndex): ContractVocabularyContext | undefined {
+  if (!ix.policy.cssVarsMustBeDefined()) return undefined;
 
   // The contract vocabulary travels on its OWN fact channel (contract_token),
   // injected by the CLI from the user's token source files — kept separate from
@@ -49,21 +62,47 @@ export function ruleTokensCssVarsMustBeDefined(ix: FactIndex): Finding[] {
   const vocabulary = new Set(ix.byKind("contract_token").map((token) => token.name));
   // The truly-unauthored case (no contract token facts) is the only hard return —
   // it preserves the §11 inert-without-contract regression lock.
-  if (vocabulary.size === 0) return [];
+  if (vocabulary.size === 0) return undefined;
 
   // A flat/single-segment vocabulary (`--accent`, `--bg`) yields no prefix family,
   // but the rule must STILL enforce it (#22/#25/#31/#36) — we no longer hard-return
   // on an empty family set. `hasFlatTokens` lets single-segment refs through the
   // shaped gate whenever the vocabulary itself declares single-segment tokens,
   // which also enforces the flat half of a mixed vocabulary symmetrically (#18).
-  const prefixes = contractPrefixFamilies(vocabulary);
-  const hasFlatTokens = [...vocabulary].some(isSingleSegmentVarName);
-  const locallyDefinedCustomProperties = new Set(
-    ix
-      .byKind("style_declaration")
-      .filter((decl) => decl.property.startsWith("--"))
-      .map((decl) => decl.property)
+  return {
+    vocabulary,
+    prefixes: contractPrefixFamilies(vocabulary),
+    hasFlatTokens: [...vocabulary].some(isSingleSegmentVarName),
+    locallyDefinedCustomProperties: new Set(
+      ix
+        .byKind("style_declaration")
+        .filter((decl) => decl.property.startsWith("--"))
+        .map((decl) => decl.property)
+    ),
+  };
+}
+
+/**
+ * Whether a primary-position `var()` reference is judged against the contract:
+ * either it IS a vocabulary token (clean) or it is shaped like one (drift).
+ * Foreign vendor custom properties (`--radix-*`, `--swiper-*`) are inspected
+ * but never judged, so they stay outside both counts.
+ */
+function isJudgedReference(tokenName: string, context: ContractVocabularyContext): boolean {
+  return (
+    context.vocabulary.has(tokenName) ||
+    sharesContractPrefix(tokenName, context.prefixes) ||
+    (context.hasFlatTokens && isSingleSegmentVarName(tokenName)) ||
+    context.locallyDefinedCustomProperties.has(tokenName)
   );
+}
+
+export function ruleTokensCssVarsMustBeDefined(ix: FactIndex): Finding[] {
+  const policy = ix.policy.cssVarsMustBeDefined();
+  if (!policy) return [];
+  const context = contractVocabularyContext(ix);
+  if (!context) return [];
+  const { vocabulary } = context;
 
   const findings: Finding[] = [];
 
@@ -83,11 +122,7 @@ export function ruleTokensCssVarsMustBeDefined(ix: FactIndex): Finding[] {
       CSS_VAR_REFERENCE.lastIndex = skipToCloseParen(decl.value, match.index + 3);
 
       if (vocabulary.has(tokenName)) continue;
-      const shaped =
-        sharesContractPrefix(tokenName, prefixes) ||
-        (hasFlatTokens && isSingleSegmentVarName(tokenName)) ||
-        locallyDefinedCustomProperties.has(tokenName);
-      if (!shaped) continue;
+      if (!isJudgedReference(tokenName, context)) continue;
       if (seen.has(tokenName)) continue;
       seen.add(tokenName);
 
@@ -136,6 +171,43 @@ function isSingleSegmentVarName(name: string): boolean {
   return name.indexOf("-", 2) === -1;
 }
 
+export interface ContractTokenReferenceCensus {
+  /**
+   * Distinct style-declaration sites (by file:line:column) carrying at least
+   * one contract-judged primary `var()` reference.
+   */
+  checkedSites: number;
+}
+
+/**
+ * The checked-site denominator for the `contract-site-health` metric's
+ * token-reference population: how many style-declaration sites this rule
+ * actually judged against the contract vocabulary. `undefined` while the rule
+ * is inert — an unmeasured population, never a measured zero. Walks the same
+ * `style_declaration` facts with the same primary-position `var()` scan and
+ * shape gate as the rule itself, so a site can violate iff it was counted.
+ */
+export function contractTokenReferenceCensus(
+  ix: FactIndex
+): ContractTokenReferenceCensus | undefined {
+  const context = contractVocabularyContext(ix);
+  if (!context) return undefined;
+
+  const checked = new Set<string>();
+  for (const decl of ix.byKind("style_declaration")) {
+    CSS_VAR_REFERENCE.lastIndex = 0;
+    let match: RegExpExecArray | null;
+    while ((match = CSS_VAR_REFERENCE.exec(decl.value)) !== null) {
+      const tokenName = match[1];
+      CSS_VAR_REFERENCE.lastIndex = skipToCloseParen(decl.value, match.index + 3);
+      if (!isJudgedReference(tokenName, context)) continue;
+      checked.add(`${decl.location.file}:${decl.location.line}:${decl.location.column}`);
+      break;
+    }
+  }
+  return { checkedSites: checked.size };
+}
+
 /**
  * Index just past the `)` that closes the open paren AT `openParenIndex`
  * (a balanced-paren scan, so a nested fallback `var(--a, var(--b))` is skipped as

package/src/schemas/index.ts

@@ -9,6 +9,7 @@ import {
 } from "../severity.js";
 import type { LegacySeverityLevel, Severity } from "../severity.js";
 import type { EvidenceGrade } from "../evidence.js";
+import { byRuleId } from "../codes/index.js";
 
 const evidenceGradeSchema: z.ZodType<EvidenceGrade> = z.enum([
   "none",
@@ -115,6 +116,12 @@ export const findingSchema = z.object({
   helpUrl: z.string().url().optional(),
   message: z.string(),
   fingerprint: z.string(),
+  /**
+   * Fingerprint this finding carried before a fingerprint-identity migration.
+   * Emitted only by migrated rules during the grace window so baseline
+   * records keyed on the legacy hash keep matching instead of churning.
+   */
+  previousFingerprint: z.string().optional(),
   location: factLocationSchema,
   evidence: z.array(factEvidenceSchema).min(1),
   evidenceGrade: evidenceGradeSchema.optional(),
@@ -357,8 +364,11 @@ export function normalizeSeverity(severity: Severity | LegacySeverityLevel): Sev
 export function normalizeFinding(
   input: Omit<Finding, "level"> & { level?: Finding["level"] }
 ): Finding {
+  const code = input.code === undefined ? byRuleId.get(input.ruleId) : undefined;
   return {
     ...input,
+    code: input.code ?? code?.code,
+    helpUrl: input.helpUrl ?? code?.explainUrl,
     evidenceGrade: input.evidenceGrade ?? "source_backed",
     level: input.level ?? severityLevel(input.severity),
   };

package/src/schemas/normalize-finding.test.ts

@@ -0,0 +1,50 @@
+/**
+ * `normalizeFinding` — FUI code attachment for findings that skip the rules
+ * engine's builder.
+ *
+ * The engine's suppression system findings (unused/expired/malformed
+ * suppression, missing expiry) are normalized here rather than through
+ * `rules/finding.ts`, and field report #3 (C16) caught the consequence: the
+ * human summary printed FUI9002 while `--format json` emitted
+ * `code: undefined`, so no JSON consumer could map the finding to rule
+ * metadata. The normalizer now resolves the registered code itself; an
+ * explicitly provided code always wins.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { normalizeFinding } from "./index.js";
+
+const base = {
+  ruleVersion: "typestyle-suppressions:v1",
+  severity: "serious",
+  message: "Suppression has expired for FUI2005.",
+  fingerprint: "0000000000000000",
+  location: { file: "src/App.tsx", line: 3, column: 1 },
+  evidence: [],
+} as const;
+
+describe("normalizeFinding", () => {
+  it("attaches the registered FUI code and explain URL for a registered ruleId", () => {
+    const finding = normalizeFinding({ ...base, ruleId: "expired-suppression" });
+    expect(finding.code).toBe("FUI9002");
+    expect(finding.helpUrl).toBe("https://usefragments.com/errors/FUI9002");
+  });
+
+  it("keeps an explicitly provided code and helpUrl", () => {
+    const finding = normalizeFinding({
+      ...base,
+      ruleId: "expired-suppression",
+      code: "FUI0000",
+      helpUrl: "https://example.com/FUI0000",
+    });
+    expect(finding.code).toBe("FUI0000");
+    expect(finding.helpUrl).toBe("https://example.com/FUI0000");
+  });
+
+  it("leaves code undefined for an unregistered ruleId", () => {
+    const finding = normalizeFinding({ ...base, ruleId: "not-a-registered-rule" });
+    expect(finding.code).toBeUndefined();
+    expect(finding.helpUrl).toBeUndefined();
+  });
+});