@usefragments/core 1.0.0 → 1.3.0

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

@@ -42,7 +42,13 @@ import {
   type SpacingTokenLookup,
 } from "./spacing-resolution.js";
 import type { Finding } from "./types.js";
-import { indexComponentByNodeId, readUsageNode } from "./utils.js";
+import {
+  emitFix,
+  indexComponentByNodeId,
+  readUsageNode,
+  tokenSymbolsInText,
+  type FixEmission,
+} from "./utils.js";
 
 export const RULE_ID = "styles/no-raw-spacing";
 export const RULE_VERSION = "1";
@@ -104,6 +110,7 @@ function checkDeclaration(
     tokens: lookupFor(scale),
   });
   if (!checked) return null;
+  const fixEmission = buildSpacingFix(decl.property, checked, ix);
 
   return makeFinding({
     ruleId: RULE_ID,
@@ -120,7 +127,7 @@ function checkDeclaration(
       property: decl.property,
       value: decl.value,
     },
-    fix: buildSpacingFix(decl.property, checked),
+    fix: fixEmission?.fix,
     attributes: {
       property: decl.property,
       rawValue: decl.value,
@@ -135,6 +142,7 @@ function checkDeclaration(
       assumedRootFontSizePx: checked.assumedRootFontSizePx,
       assumedEmBasePx: checked.assumedEmBasePx,
       source: "css",
+      ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
     },
   });
 }
@@ -162,6 +170,7 @@ function checkInlineStyle(
     bareNumberFix: inline.valueKind === "number",
   });
   if (!checked) return null;
+  const fixEmission = buildSpacingFix(inline.property, checked, ix);
 
   const node = readUsageNode(ix, inline.nodeId);
   if (!node) return null;
@@ -186,7 +195,7 @@ function checkInlineStyle(
       property: inline.property,
       value: inline.value,
     },
-    fix: buildSpacingFix(inline.property, checked),
+    fix: fixEmission?.fix,
     attributes: {
       property: inline.property,
       rawValue: inline.value,
@@ -201,19 +210,32 @@ function checkInlineStyle(
       assumedRootFontSizePx: checked.assumedRootFontSizePx,
       assumedEmBasePx: checked.assumedEmBasePx,
       source: "jsx",
+      ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
     },
   });
 }
 
-function buildSpacingFix(property: string, checked: CheckedSpacingValue) {
+function buildSpacingFix(
+  property: string,
+  checked: CheckedSpacingValue,
+  ix: FactIndex
+): FixEmission | undefined {
   if (!checked.fixEmittable || checked.suggestedValue === undefined) return undefined;
-  return {
-    kind: "replaceStyleValue" as const,
-    title: `Replace ${property} with ${checked.suggestedValue}`,
-    property,
-    value: checked.suggestedValue,
-    deterministic: checked.deterministicFix,
-  };
+  return emitFix(
+    {
+      kind: "replaceStyleValue" as const,
+      title: `Replace ${property} with ${checked.suggestedValue}`,
+      property,
+      value: checked.suggestedValue,
+      deterministic: true,
+    },
+    {
+      symbols: tokenSymbolsInText(checked.suggestedValue),
+      editKind: "replaceStyleValue",
+      valuePreserving: checked.deterministicFix,
+    },
+    ix
+  );
 }
 
 function spacingMessage(

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

@@ -29,13 +29,15 @@ import { makeFinding } from "./finding.js";
 import type { Finding } from "./types.js";
 import {
   indexComponentByNodeId,
-  isApplicableTokenReference,
+  emitFix,
   matchesScale,
   nearestSignedScaleValue,
   normalizeLengthForScale,
   parseLengthValue,
   readUsageNode,
   tokenReference,
+  tokenSymbolsInText,
+  type FixEmission,
 } from "./utils.js";
 
 export const RULE_ID = "styles/no-raw-typography";
@@ -58,6 +60,7 @@ 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);
     findings.push(
       makeFinding({
         ruleId: RULE_ID,
@@ -74,7 +77,7 @@ export function ruleStylesNoRawTypography(ix: FactIndex): Finding[] {
           property: decl.property,
           value: decl.value,
         },
-        fix: buildFix(decl.property, checked),
+        fix: fixEmission?.fix,
         attributes: {
           property: decl.property,
           rawValue: decl.value,
@@ -83,6 +86,7 @@ export function ruleStylesNoRawTypography(ix: FactIndex): Finding[] {
           suggestedValue: checked.suggestedValue,
           matchedToken: checked.matchedToken,
           source: "css",
+          ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
         },
       })
     );
@@ -92,8 +96,15 @@ export function ruleStylesNoRawTypography(ix: FactIndex): Finding[] {
   for (const inline of ix.byKind("usage_inline_style")) {
     if (inline.valueKind === "css-variable") continue;
     if (!FONT_SIZE_PROPERTIES.has(inline.property.toLowerCase())) continue;
-    const checked = checkFontSize(inline.value, allowed, scale, tokens, inline.valueKind === "number");
+    const checked = checkFontSize(
+      inline.value,
+      allowed,
+      scale,
+      tokens,
+      inline.valueKind === "number"
+    );
     if (!checked) continue;
+    const fixEmission = buildFix(inline.property, checked, ix);
     const node = readUsageNode(ix, inline.nodeId);
     if (!node) continue;
     const componentEvidenceId = componentByNode.get(node.id)?.id;
@@ -116,7 +127,7 @@ export function ruleStylesNoRawTypography(ix: FactIndex): Finding[] {
           property: inline.property,
           value: inline.value,
         },
-        fix: buildFix(inline.property, checked),
+        fix: fixEmission?.fix,
         attributes: {
           property: inline.property,
           rawValue: inline.value,
@@ -125,6 +136,7 @@ export function ruleStylesNoRawTypography(ix: FactIndex): Finding[] {
           suggestedValue: checked.suggestedValue,
           matchedToken: checked.matchedToken,
           source: "jsx",
+          ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
         },
       })
     );
@@ -175,12 +187,10 @@ function checkFontSize(
 
   if (matchesScale(normalized.value, allowed)) {
     if (!exactToken) return null;
-    const applicable =
-      isApplicableTokenReference(exactToken.referenceFormat) && normalized.deterministicFix;
     return {
       suggestedValue: tokenReference(exactToken.name),
       fixEmittable: true,
-      deterministicFix: applicable,
+      deterministicFix: normalized.deterministicFix,
       reason: "token-equivalent",
       matchedToken: exactToken.name,
     };
@@ -206,15 +216,27 @@ function checkFontSize(
   };
 }
 
-function buildFix(property: string, checked: CheckedFontSize) {
+function buildFix(
+  property: string,
+  checked: CheckedFontSize,
+  ix: FactIndex
+): FixEmission | undefined {
   if (!checked.fixEmittable || checked.suggestedValue === undefined) return undefined;
-  return {
-    kind: "replaceStyleValue" as const,
-    title: `Replace ${property} with ${checked.suggestedValue}`,
-    property,
-    value: checked.suggestedValue,
-    deterministic: checked.deterministicFix,
-  };
+  return emitFix(
+    {
+      kind: "replaceStyleValue" as const,
+      title: `Replace ${property} with ${checked.suggestedValue}`,
+      property,
+      value: checked.suggestedValue,
+      deterministic: true,
+    },
+    {
+      symbols: tokenSymbolsInText(checked.suggestedValue),
+      editKind: "replaceStyleValue",
+      valuePreserving: checked.deterministicFix,
+    },
+    ix
+  );
 }
 
 function typographyMessage(

package/src/rules/taxonomy.test.ts

@@ -12,6 +12,7 @@ import {
   makeContractTokenFact,
   makeStyleCssVarsMustBeDefinedFact,
   makeStyleDeclarationFact,
+  makeTokenDefinitionFact,
   makeUsageNodeFact,
   makeUsageTextChildFact,
   RULE_TIER,
@@ -36,6 +37,7 @@ import type { Fact } from "../index.js";
 function rawValueFixture(): Fact[] {
   const file = "src/Widget.module.scss";
   return [
+    dualFallbackToken(),
     makeStyleDeclarationFact({
       file,
       selector: ".a",
@@ -64,6 +66,15 @@ function rawValueFixture(): Fact[] {
   ];
 }
 
+function dualFallbackToken(): Fact {
+  return makeTokenDefinitionFact({
+    name: "$fui-surface-secondary",
+    value: "#f1f5f9",
+    category: "color",
+    referenceFormat: "scss-var",
+  });
+}
+
 function index(facts: Fact[]): FactIndex {
   const ix = new FactIndex();
   ix.addMany(facts);
@@ -138,12 +149,14 @@ describe("§2 tokens/require-dual-fallback is Fragments-internal", () => {
   it("customer preset = 0, fragments preset = 1", () => {
     const customer = index([
       ...compileGlobalGovernanceFacts({ rules: customerDefaultRuleStates() }),
+      dualFallbackToken(),
       decl,
     ]);
     expect(runRules(customer)).toHaveLength(0);
 
     const fragments = index([
       ...compileGlobalGovernanceFacts({ rules: fragmentsPresetRuleStates() }),
+      dualFallbackToken(),
       decl,
     ]);
     const fragmentsFindings = runRules(fragments);
@@ -217,18 +230,21 @@ describe("§3 contract authored", () => {
     expect(ruleIds.every(isContractTierRule)).toBe(true);
   });
 
-  it("ranks canonical-component bypass first (vocabulary-first), with a directed fix", () => {
+  it("ranks canonical-component bypass first without claiming an unsafe missing-import fix", () => {
     const findings = runRules(withButtonText(contractIndex()));
     const ranked = findings.map((f) => f.ruleId).sort(compareByVocabularyRank);
     expect(ranked).toEqual(["components/prefer-library", "tokens/css-vars-must-be-defined"]);
 
     const canonical = findings.find((f) => f.ruleId === "components/prefer-library");
-    // "Replace your raw <button> with your <Button>" — a directed, deterministic fix.
+    // The direction is explicit, but this fixture has no Button binding. A
+    // generic source patcher cannot safely rename the element without also
+    // importing Button, so the replacement stays visible but is not advertised
+    // as deterministic.
     expect(canonical?.fix).toMatchObject({
       kind: "replaceComponent",
       from: "button",
       to: "Button",
-      deterministic: true,
+      deterministic: false,
     });
     expect(canonical?.attributes).toMatchObject({
       rawValue: "button",

package/src/rules/tiers.ts

@@ -27,7 +27,7 @@ export type RuleTier = "contract" | "hygiene";
  */
 export const RULE_TIER: Readonly<Record<string, RuleTier>> = {
   // ---- Tier A — contract vocabulary -------------------------------------
-  "components/prefer-library": "contract", // canonical-component bypass (FUI1001/1004)
+  "components/prefer-library": "contract", // canonical-component bypass (FUI1004)
   "tokens/css-vars-must-be-defined": "contract", // token drift (FUI2015)
 
   // ---- Tier B — generic hygiene -----------------------------------------

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

@@ -1,8 +1,8 @@
-import type { FactIndex } from "../facts/index.js";
+import type { FactIndex, TokenDefinitionFact } from "../facts/index.js";
 
 import { makeFinding } from "./finding.js";
 import type { Finding } from "./types.js";
-import { cssVariableNames } from "./utils.js";
+import { emitFix } from "./utils.js";
 
 export const RULE_ID = "tokens/require-dual-fallback";
 export const RULE_VERSION = "1";
@@ -22,7 +22,7 @@ export function ruleTokensRequireDualFallback(ix: FactIndex): Finding[] {
   const policy = ix.policy.ruleConfig(RULE_ID);
   if (!policy?.enabled) return [];
 
-  const knownTokenVars = cssVariableNames(ix.tokens.list());
+  const tokensByCssVariable = indexTokensByCssVariable(ix.tokens.list());
   const findings: Finding[] = [];
 
   for (const decl of ix.byKind("style_declaration")) {
@@ -33,21 +33,43 @@ export function ruleTokensRequireDualFallback(ix: FactIndex): Finding[] {
       const tokenName = match[1];
       const hasFallback = match[2] !== undefined;
       if (hasFallback) continue;
-      if (!knownTokenVars.has(tokenName) && !tokenName.startsWith("--fui-")) continue;
+      const token = tokensByCssVariable.get(tokenName);
+      if (!token) continue;
 
       const rawValue = match[0];
       const scssVar = tokenName.replace(/^--/, "$");
-      const replacement = `var(${tokenName}, ${scssVar})`;
-      const nextValue = decl.value.replace(rawValue, replacement);
+      const hasScssVariable = token.referenceFormat === "scss-var";
+      const nextValue = hasScssVariable
+        ? decl.value.replace(rawValue, `var(${tokenName}, ${scssVar})`)
+        : undefined;
+      const fixEmission = nextValue
+        ? emitFix(
+            {
+              kind: "replaceStyleValue",
+              title: `Add fallback for ${tokenName}`,
+              property: decl.property,
+              value: nextValue,
+              deterministic: true,
+            },
+            {
+              symbols: [tokenName, scssVar],
+              editKind: "replaceStyleValue",
+              valuePreserving: true,
+            },
+            ix
+          )
+        : undefined;
 
       findings.push(
         makeFinding({
           ruleId: RULE_ID,
           ruleVersion: RULE_VERSION,
           severity: policy.severity ?? "warn",
-          message: `var(${tokenName}) is missing an SCSS fallback. Use var(${tokenName}, ${scssVar}).`,
+          message: hasScssVariable
+            ? `var(${tokenName}) is missing an SCSS fallback. Use var(${tokenName}, ${scssVar}).`
+            : `var(${tokenName}) is missing a fallback. No matching SCSS variable was found in the token source; add a fallback manually or define ${scssVar}.`,
           location: decl.location,
-          evidence: ix.evidence([decl.id, policy.id]),
+          evidence: ix.evidence([decl.id, token.id, policy.id]),
           fingerprintIdentity: {
             file: decl.file,
             selector: decl.selector,
@@ -55,24 +77,39 @@ export function ruleTokensRequireDualFallback(ix: FactIndex): Finding[] {
             property: decl.property,
             tokenName,
           },
-          fix: {
-            kind: "replaceStyleValue",
-            title: `Add fallback for ${tokenName}`,
-            property: decl.property,
-            value: nextValue,
-            deterministic: true,
-          },
+          fix: fixEmission?.fix,
           attributes: {
             property: decl.property,
             rawValue: decl.value,
             tokenName,
-            suggestedValue: nextValue,
+            ...(nextValue ? { suggestedValue: nextValue } : {}),
+            ...(fixEmission?.downgradeReason
+              ? { downgradeReason: fixEmission.downgradeReason }
+              : {}),
             source: "css",
           },
-        }),
+        })
       );
     }
   }
 
   return findings;
 }
+
+function indexTokensByCssVariable(
+  tokens: readonly TokenDefinitionFact[]
+): Map<string, TokenDefinitionFact> {
+  const indexed = new Map<string, TokenDefinitionFact>();
+  for (const token of tokens) {
+    const cssVariable = token.name.startsWith("--")
+      ? token.name
+      : token.name.startsWith("$")
+        ? `--${token.name.slice(1)}`
+        : `--${token.name}`;
+    const existing = indexed.get(cssVariable);
+    if (!existing || token.referenceFormat === "scss-var") {
+      indexed.set(cssVariable, token);
+    }
+  }
+  return indexed;
+}

package/src/rules/utils.ts

@@ -18,6 +18,57 @@ import type {
   UsagePropResolvedFact,
   UsageTextChildFact,
 } from "../facts/index.js";
+import type { FindingFix } from "./types.js";
+
+export interface FixProof {
+  symbols: readonly string[];
+  editKind: FindingFix["kind"];
+  valuePreserving: boolean;
+}
+
+export interface FixEmission<F extends FindingFix = FindingFix> {
+  fix: F;
+  downgradeReason?: string;
+}
+
+/**
+ * Gate token-substitution fixes on explicit proof. Callers attach any returned
+ * downgradeReason to the finding attributes so machine consumers can explain
+ * why a suggestion was not auto-applicable.
+ */
+export function emitFix<F extends FindingFix>(
+  fix: F,
+  proof: FixProof,
+  ix: FactIndex
+): FixEmission<F> {
+  const reasons: string[] = [];
+  if (proof.editKind !== fix.kind) reasons.push("edit kind does not match proof");
+  if (!proof.valuePreserving) reasons.push("value-preservation proof missing");
+  if (proof.symbols.length === 0) reasons.push("token-symbol proof missing");
+
+  const missingSymbols = proof.symbols.filter((symbol) => !ix.tokens.symbolExists(symbol));
+  if (missingSymbols.length > 0) {
+    reasons.push(`absent token symbol: ${missingSymbols.join(", ")}`);
+  }
+
+  const inapplicableSymbols = proof.symbols.filter((symbol) => {
+    const definition = ix.tokens.definitionForSymbol(symbol);
+    return definition !== undefined && !isApplicableTokenReference(definition.referenceFormat);
+  });
+  if (inapplicableSymbols.length > 0) {
+    reasons.push(`token reference is not directly applicable: ${inapplicableSymbols.join(", ")}`);
+  }
+
+  return {
+    fix: { ...fix, deterministic: reasons.length === 0 },
+    ...(reasons.length > 0 ? { downgradeReason: reasons.join("; ") } : {}),
+  };
+}
+
+/** Extract authored token symbols from a replacement string, preserving order. */
+export function tokenSymbolsInText(value: string): string[] {
+  return [...new Set(value.match(/\$[A-Za-z0-9_-]+|--[A-Za-z0-9_-]+/g) ?? [])];
+}
 
 export interface LengthScale {
   unit: "px" | "rem";

package/src/schemas/index.ts

@@ -8,6 +8,15 @@ import {
   severitySchema,
 } from "../severity.js";
 import type { LegacySeverityLevel, Severity } from "../severity.js";
+import type { EvidenceGrade } from "../evidence.js";
+
+const evidenceGradeSchema: z.ZodType<EvidenceGrade> = z.enum([
+  "none",
+  "runtime_advisory",
+  "provenance_bound",
+  "source_backed",
+  "receipt_backed",
+]);
 
 export { legacySeverityLevelSchema, severityLevelSchema, severitySchema };
 export type { LegacySeverityLevel, Severity, SeverityLevel } from "../severity.js";
@@ -108,6 +117,7 @@ export const findingSchema = z.object({
   fingerprint: z.string(),
   location: factLocationSchema,
   evidence: z.array(factEvidenceSchema).min(1),
+  evidenceGrade: evidenceGradeSchema.optional(),
   fix: findingFixSchema.optional(),
   attributes: z.record(z.unknown()).optional(),
   /**
@@ -224,15 +234,51 @@ export const agentFindingSchema = z.object({
   severity: severitySchema,
   level: severityLevelSchema,
   message: z.string(),
+  evidenceGrade: evidenceGradeSchema.optional(),
   evidence: z.array(factEvidenceSchema),
   plan: agentPlanSchema,
 });
 
-export const agentFormatSchema = z.object({
-  schemaVersion: z.literal("typestyle.agent.v1"),
-  passed: z.boolean(),
-  score: z.number(),
+export const AGENT_FORMAT_SCHEMA_VERSION = "typestyle.agent.v2" as const;
+
+export const agentIntegritySchema = z.object({
+  rulesLoaded: z.number().int().nonnegative(),
+  status: z.enum(["healthy", "degraded", "inert"]),
+  healthy: z.boolean(),
+  inert: z.boolean(),
+  reasons: z.array(z.string()),
+});
+
+const agentRunProvenanceSchema = z.object({
+  runId: z.string().regex(/^run_[a-f0-9]{12}$/),
+  fcid: z.string().min(1),
+  baselineId: z.string().min(1).optional(),
+  scope: z.object({
+    method: z.enum([
+      "three-dot",
+      "tree-diff",
+      "status",
+      "fallback-full",
+      "explicit",
+      "full",
+    ]),
+    gitOk: z.boolean(),
+  }),
+  engineVersion: z.string().min(1),
+  scopeHash: z.string().regex(/^[a-f0-9]{64}$/),
+  inputFilesHash: z.string().regex(/^[a-f0-9]{64}$/),
+});
+
+const agentRunVerdictSchema = z.object({
+  exitCode: z.union([z.literal(0), z.literal(1)]),
+  reasons: z.array(z.string()),
+  gatingFindingCount: z.number().int().nonnegative(),
+});
+
+const agentFormatBaseSchema = z.object({
+  schemaVersion: z.literal(AGENT_FORMAT_SCHEMA_VERSION),
   summary: z.string(),
+  integrity: agentIntegritySchema,
   fix_first: z.array(agentFindingSchema),
   remaining: z.array(agentFindingSchema),
   suppression_template: z.object({
@@ -247,9 +293,64 @@ export const agentFormatSchema = z.object({
   }),
   findings: z.array(findingSchema).optional(),
   suppressions: z.array(suppressionDirectiveSchema).optional(),
+  provenance: agentRunProvenanceSchema.optional(),
+  verdict: agentRunVerdictSchema.optional(),
 });
+
+export const agentFormatSchema = z.union([
+  agentFormatBaseSchema.extend({
+    passed: z.boolean(),
+    score: z.number(),
+    status: z.never().optional(),
+    reasons: z.never().optional(),
+    integrity: agentIntegritySchema.extend({
+      rulesLoaded: z.number().int().positive(),
+    }),
+  }),
+  agentFormatBaseSchema.extend({
+    passed: z.literal(false),
+    score: z.never().optional(),
+    status: z.literal("indeterminate"),
+    reasons: z.tuple([z.literal("zero_rules_loaded")]),
+    integrity: agentIntegritySchema.extend({
+      rulesLoaded: z.literal(0),
+    }),
+  }),
+  // A finalized Run can explicitly allow inert governance. Preserve the
+  // indeterminate integrity truth while making `passed` match that Run's sole
+  // verdict; requiring Run pins prevents generic zero-rule envelopes from
+  // accidentally becoming green.
+  agentFormatBaseSchema.extend({
+    passed: z.literal(true),
+    score: z.never().optional(),
+    status: z.literal("indeterminate"),
+    reasons: z.tuple([z.literal("zero_rules_loaded")]),
+    integrity: agentIntegritySchema.extend({
+      rulesLoaded: z.literal(0),
+    }),
+    provenance: agentRunProvenanceSchema,
+    verdict: agentRunVerdictSchema.extend({ exitCode: z.literal(0) }),
+  }),
+]);
 export type AgentFormat = z.infer<typeof agentFormatSchema>;
 
+export const agentErrorEnvelopeSchema = z.object({
+  schemaVersion: z.literal(AGENT_FORMAT_SCHEMA_VERSION),
+  passed: z.literal(false),
+  error: z.object({
+    code: z.string().min(1),
+    message: z.string().min(1),
+  }),
+  provenance: agentRunProvenanceSchema.optional(),
+  verdict: agentRunVerdictSchema.optional(),
+  cloudReport: z.enum(["reported", "failed", "skipped"]).optional(),
+  notices: z.array(z.string()).optional(),
+});
+export type AgentErrorEnvelope = z.infer<typeof agentErrorEnvelopeSchema>;
+
+export const agentOutputSchema = z.union([agentFormatSchema, agentErrorEnvelopeSchema]);
+export type AgentOutput = z.infer<typeof agentOutputSchema>;
+
 export function normalizeSeverity(severity: Severity | LegacySeverityLevel): Severity {
   return severitySchema.safeParse(severity).success
     ? (severity as Severity)
@@ -261,6 +362,7 @@ export function normalizeFinding(
 ): Finding {
   return {
     ...input,
+    evidenceGrade: input.evidenceGrade ?? "source_backed",
     level: input.level ?? severityLevel(input.severity),
   };
 }

package/src/token-types.ts

@@ -59,6 +59,12 @@ export interface DesignToken {
   /** Source file where this token was defined */
   sourceFile: string;
 
+  /** Authored reference form, when the parser can prove it from the source. */
+  referenceFormat?: "css-var" | "scss-var" | "scss-map" | "dtcg";
+
+  /** Authored spellings preserved before normalization (for example `$x` and `--x`). */
+  sourceNames?: string[];
+
   /** Line number in source file */
   lineNumber?: number;
 

package/src/tokens/__tests__/source-names.test.ts

@@ -0,0 +1,42 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { FactIndex, makeTokenDefinitionFact } from "../../facts/index.js";
+import { parseDesignTokenContent } from "../design-token-parser.js";
+
+const tokenFile = fileURLToPath(
+  new URL("../../../../../libs/ui/src/tokens/_variables.scss", import.meta.url)
+);
+
+describe("SCSS source-name provenance", () => {
+  it("preserves both authored spellings through parser, facts, and rule-time lookup", () => {
+    const parsed = parseDesignTokenContent(readFileSync(tokenFile, "utf8"), {
+      filePath: tokenFile,
+    });
+    const token = parsed.tokens.find((candidate) => candidate.name === "--fui-space-2");
+
+    expect(token?.sourceNames).toEqual(expect.arrayContaining(["--fui-space-2", "$fui-space-2"]));
+
+    const ix = new FactIndex();
+    ix.addMany(
+      parsed.tokens.map((candidate) =>
+        makeTokenDefinitionFact({
+          name: candidate.name,
+          value: candidate.resolvedValue,
+          category: candidate.category === "spacing" ? "spacing" : "other",
+          referenceFormat: candidate.referenceFormat,
+          sourceNames: candidate.sourceNames,
+        })
+      )
+    );
+
+    expect(ix.tokens.symbolExists("$fui-space-2")).toBe(true);
+    expect(ix.tokens.symbolExists("--fui-space-2")).toBe(true);
+    expect(ix.tokens.symbolExists("$fui-space-99")).toBe(false);
+    expect(ix.tokens.definitionForSymbol("$fui-space-2")?.sourceNames).toEqual(
+      expect.arrayContaining(["--fui-space-2", "$fui-space-2"])
+    );
+  });
+});