@usefragments/core 1.7.0 → 1.8.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",
@@ -357,8 +358,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();
+  });
+});