@usefragments/core 1.2.0 → 1.4.0

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/schema.ts

@@ -244,6 +244,10 @@ const tokenConfigSchema = z
   .object({
     include: repoRelativePathsSchema.optional(),
     sources: z.array(tokenSourceSchema).min(1).optional(),
+    // Declared design-system packages whose shipped fragments.json token
+    // vocabulary seeds the known-token set (#7c). A packages-only tokens block
+    // is valid — see the superRefine below.
+    packages: z.array(z.string().min(1)).optional(),
     exclude: z.array(repoRelativePathSchema).optional(),
     themeSelectors: z.record(z.string()).optional(),
     enabled: z.boolean().optional(),
@@ -252,10 +256,10 @@ const tokenConfigSchema = z
   })
   .passthrough()
   .superRefine((tokens, ctx) => {
-    if (!tokens.include?.length && !tokens.sources?.length) {
+    if (!tokens.include?.length && !tokens.sources?.length && !tokens.packages?.length) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
-        message: "Add tokens.include or tokens.sources",
+        message: "Add tokens.include, tokens.sources, or tokens.packages",
         path: ["sources"],
       });
     }

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,6 +234,7 @@ export const agentFindingSchema = z.object({
   severity: severitySchema,
   level: severityLevelSchema,
   message: z.string(),
+  evidenceGrade: evidenceGradeSchema.optional(),
   evidence: z.array(factEvidenceSchema),
   plan: agentPlanSchema,
 });
@@ -238,10 +249,34 @@ export const agentIntegritySchema = z.object({
   reasons: z.array(z.string()),
 });
 
-export const agentFormatSchema = z.object({
+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),
-  passed: z.boolean(),
-  score: z.number(),
   summary: z.string(),
   integrity: agentIntegritySchema,
   fix_first: z.array(agentFindingSchema),
@@ -258,7 +293,45 @@ 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({
@@ -268,6 +341,10 @@ export const agentErrorEnvelopeSchema = 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>;
 
@@ -285,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;
 
@@ -187,6 +193,18 @@ export interface TokenConfig {
    */
   exclude?: string[];
 
+  /**
+   * npm package names whose SHIPPED `fragments.json` token vocabulary should seed
+   * the known-token set (e.g. `["@usefragments/ui"]`). This is a DECLARED-manifest
+   * ingest — the parser reads each package's published `fragments.json` (via its
+   * `<pkg>/fragments.json` export or its package.json `fragments` field) and
+   * merges the token NAMES into the vocabulary consumed by
+   * `tokens/css-vars-must-be-defined`, so a consumer using those `--fui-*` vars is
+   * not flagged as off-contract drift. node_modules SCSS is NEVER globbed — only
+   * the declared manifest is trusted, keeping the no-inference mandate intact.
+   */
+  packages?: string[];
+
   /**
    * Map CSS selectors to theme names
    * @example { ":root": "default", "[data-theme='dark']": "dark" }

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"])
+    );
+  });
+});

package/src/tokens/categories.ts

@@ -96,7 +96,48 @@ export function inferTokenGroup(name: string): string {
   }
 }
 
-export function normalizeTokenGroupComment(comment: string): string {
+/**
+ * Curated section-comment → category map. ONLY these headings (and short, clean
+ * uncurated headings) become token categories. A prose comment latched as a
+ * category is the #7d smell (`the-@supports-block-below-…` etc.), so anything
+ * that is not curated AND does not read like a heading returns `null`, letting
+ * the caller fall back to name-based `inferTokenGroup`.
+ */
+const TOKEN_GROUP_COMMENT_MAPPINGS: Record<string, string> = {
+  "base configuration": "base",
+  typography: "typography",
+  "spacing (micro)": "spacing",
+  spacing: "spacing",
+  "density padding": "spacing",
+  "border radius": "radius",
+  transitions: "transitions",
+  colors: "colors",
+  surfaces: "surfaces",
+  text: "text",
+  borders: "borders",
+  shadows: "shadows",
+  focus: "focus",
+  scrollbar: "scrollbar",
+  "component heights": "component-sizing",
+  "appshell layout": "layout",
+  codeblock: "code",
+  tooltip: "tooltip",
+  "hero/marketing gradient": "marketing",
+};
+
+/**
+ * A "clean heading" is alphanumerics + spaces + hyphens only (no punctuation,
+ * symbols, em/en dashes, parens, `@`, `/`, etc.) and at most three words. Prose
+ * comments — which carry punctuation and/or run long — fail this and are NOT
+ * treated as categories.
+ */
+function looksLikeCleanHeading(text: string): boolean {
+  if (!/^[a-z0-9][a-z0-9 -]*$/.test(text)) return false;
+  const wordCount = text.split(/\s+/).filter(Boolean).length;
+  return wordCount > 0 && wordCount <= 3;
+}
+
+export function normalizeTokenGroupComment(comment: string): string | null {
   const text = comment
     .trim()
     .replace(/^\/\/\s*/, "")
@@ -105,27 +146,16 @@ export function normalizeTokenGroupComment(comment: string): string {
     .trim()
     .toLowerCase();
 
-  const mappings: Record<string, string> = {
-    "base configuration": "base",
-    typography: "typography",
-    "spacing (micro)": "spacing",
-    spacing: "spacing",
-    "density padding": "spacing",
-    "border radius": "radius",
-    transitions: "transitions",
-    colors: "colors",
-    surfaces: "surfaces",
-    text: "text",
-    borders: "borders",
-    shadows: "shadows",
-    focus: "focus",
-    scrollbar: "scrollbar",
-    "component heights": "component-sizing",
-    "appshell layout": "layout",
-    codeblock: "code",
-    tooltip: "tooltip",
-    "hero/marketing gradient": "marketing",
-  };
-
-  return mappings[text] ?? text.replace(/\s+/g, "-");
+  if (text in TOKEN_GROUP_COMMENT_MAPPINGS) {
+    return TOKEN_GROUP_COMMENT_MAPPINGS[text];
+  }
+
+  // Uncurated: only accept short, clean headings as categories. Prose comments
+  // (punctuation/symbols or >3 words) return null so the token falls through to
+  // name-based inference instead of minting a garbage category slug (#7d).
+  if (!looksLikeCleanHeading(text)) {
+    return null;
+  }
+
+  return text.replace(/\s+/g, "-");
 }

package/src/tokens/design-token-parser.test.ts

@@ -67,15 +67,34 @@ describe("parseDesignTokenContent — DTCG/JSON format dispatch (#10)", () => {
 describe("parseDesignTokenContent — SCSS $-variable format dispatch (#32)", () => {
   it("parses SCSS $vars, normalizing $name to --name", () => {
     const content = "$fui-color-accent: #fff;\n$fui-space-2: 8px;";
-    const tokens = names(content, "tokens.scss");
-    expect(tokens).toContain("--fui-color-accent");
-    expect(tokens).toContain("--fui-space-2");
+    const tokens = parseDesignTokenContent(content, { filePath: "tokens.scss" }).tokens;
+    expect(tokens).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          name: "--fui-color-accent",
+          referenceFormat: "scss-var",
+        }),
+        expect.objectContaining({ name: "--fui-space-2", referenceFormat: "scss-var" }),
+      ])
+    );
   });
 
   it("dedupes a file declaring BOTH --fui-x and $fui-x to one --fui-x", () => {
     const content = ":root {\n  --fui-x: red;\n}\n$fui-x: red;";
-    const tokens = names(content, "tokens.scss");
-    expect(tokens.filter((n) => n === "--fui-x")).toHaveLength(1);
+    const tokens = parseDesignTokenContent(content, { filePath: "tokens.scss" }).tokens.filter(
+      (token) => token.name === "--fui-x"
+    );
+    expect(tokens).toHaveLength(1);
+    expect(tokens[0].referenceFormat).toBe("scss-var");
+  });
+
+  it("marks a CSS-only declaration in SCSS as css-var", () => {
+    const content = ":root {\n  --fui-color-accent: red;\n}";
+    const token = parseDesignTokenContent(content, { filePath: "tokens.scss" }).tokens.find(
+      (candidate) => candidate.name === "--fui-color-accent"
+    );
+
+    expect(token?.referenceFormat).toBe("css-var");
   });
 
   it("surfaces a NON-SILENT warning for a comment-only SCSS file (#32)", () => {

package/src/tokens/design-token-parser.ts

@@ -193,21 +193,51 @@ function parsedOutputToDesignTokens(output: TokenParseOutput, filePath: string):
  * and `$fui-x` yields one `--fui-x`.
  */
 function scssOutputToDesignTokens(output: TokenParseOutput, filePath: string): DesignToken[] {
-  const names = new Set<string>();
-  const tokens: DesignToken[] = [];
+  const tokensByName = new Map<
+    string,
+    {
+      parsed: ParsedToken;
+      referenceFormat: "css-var" | "scss-var";
+      sourceNames: Set<string>;
+    }
+  >();
   for (const cat of Object.values(output.categories)) {
     for (const t of cat) {
-      const cssName = t.name.startsWith("$") ? `--${t.name.slice(1)}` : t.name;
-      if (!cssName.startsWith("--") || names.has(cssName)) continue;
-      names.add(cssName);
-      tokens.push(designTokenFromParsed(cssName, t, filePath));
+      const isScssVariable = t.name.startsWith("$");
+      const cssName = isScssVariable ? `--${t.name.slice(1)}` : t.name;
+      if (!cssName.startsWith("--")) continue;
+
+      const existing = tokensByName.get(cssName);
+      if (!existing) {
+        tokensByName.set(cssName, {
+          parsed: t,
+          referenceFormat: isScssVariable ? "scss-var" : "css-var",
+          sourceNames: new Set([t.name]),
+        });
+      } else {
+        existing.sourceNames.add(t.name);
+        if (isScssVariable) {
+          existing.parsed = t;
+          existing.referenceFormat = "scss-var";
+        }
+      }
     }
   }
-  return tokens;
+  return [...tokensByName].map(([name, token]) =>
+    designTokenFromParsed(name, token.parsed, filePath, token.referenceFormat, [
+      ...token.sourceNames,
+    ])
+  );
 }
 
 /** Build a `DesignToken` from a sibling-parser `ParsedToken` under a CSS name. */
-function designTokenFromParsed(name: string, parsed: ParsedToken, filePath: string): DesignToken {
+function designTokenFromParsed(
+  name: string,
+  parsed: ParsedToken,
+  filePath: string,
+  referenceFormat?: DesignToken["referenceFormat"],
+  sourceNames?: string[]
+): DesignToken {
   return {
     name,
     rawValue: parsed.value ?? "",
@@ -220,6 +250,8 @@ function designTokenFromParsed(name: string, parsed: ParsedToken, filePath: stri
     level: 1,
     referenceChain: [],
     sourceFile: filePath,
+    referenceFormat,
+    ...(sourceNames?.length ? { sourceNames } : {}),
     theme: "default",
     selector: ":root",
     description: parsed.description,