@usefragments/core 1.2.0 → 1.4.0

package/dist/index.js

@@ -109,7 +109,7 @@ import {
   ownedImportsEqual,
   resolveComponentGovernance,
   scaleGovernanceRecordSchema
-} from "./chunk-DBVTSUMT.js";
+} from "./chunk-CBSNXFOD.js";
 import {
   AGENT_FORMAT_SCHEMA_VERSION,
   agentErrorEnvelopeSchema,
@@ -134,7 +134,7 @@ import {
   suppressionDirectiveSchema,
   validatorResultSchema,
   violationSchema
-} from "./chunk-BQQTMGLA.js";
+} from "./chunk-57QDBEHQ.js";
 import {
   OWNED_PACKAGE_IDENTITY_EPOCH,
   OWNED_PACKAGE_IDENTITY_SOURCE_SHA256,
@@ -185,6 +185,8 @@ var BRAND = {
   legacyConfigFile: "segments.config.ts",
   /** CLI command name (e.g., "fragments") */
   cliCommand: "fragments",
+  /** Full user-facing CLI invocation for copy printed to end users (e.g., "npx @usefragments/cli") */
+  cliInvocation: "npx @usefragments/cli",
   /** Directory for storing fragments, registry, and cache */
   dataDir: ".fragments",
   /** Components subdirectory within .fragments/ */
@@ -238,6 +240,18 @@ var DEFAULTS = {
   port: 6006
 };
 
+// src/evidence.ts
+var EVIDENCE_ORDER = [
+  "none",
+  "runtime_advisory",
+  "provenance_bound",
+  "source_backed",
+  "receipt_backed"
+];
+function canBlock(grade) {
+  return EVIDENCE_ORDER.indexOf(grade) >= EVIDENCE_ORDER.indexOf("source_backed");
+}
+
 // src/conform-prove.ts
 var PROVE_MAX_PASSES = 8;
 var PROVE_DEFAULT_MAX_PASSES = 4;
@@ -386,6 +400,7 @@ async function proveCompliant(input, callbacks, options = {}) {
 
 // src/agent-format.ts
 function buildAgentFormat(input) {
+  const zeroRulesLoaded = input.integrity.rulesLoaded === 0;
   const integrityFailed = !input.integrity.healthy || input.integrity.inert;
   const score = integrityFailed ? 0 : scoreFindings(input.findings);
   const visibleFindings = uniqueFindings(input.findings).slice(0, input.maxFindings ?? 50);
@@ -398,15 +413,14 @@ function buildAgentFormat(input) {
     severity: finding.severity,
     level: severityLevel(finding.severity),
     message: finding.message,
+    evidenceGrade: finding.evidenceGrade,
     evidence: input.includeEvidence ? finding.evidence : [],
     plan: planForFinding(finding)
   }));
   const hasErrors = input.findings.some((finding) => severityLevel(finding.severity) === "error");
-  return {
+  const shared = {
     schemaVersion: AGENT_FORMAT_SCHEMA_VERSION,
-    passed: !integrityFailed && (input.passed ?? true) && !hasErrors,
-    score,
-    summary: integrityFailed ? `failed with score ${score}; ${input.integrity.reasons.join("; ") || "governance integrity is unhealthy"}` : agentSummary(input.findings.length, input.filesScanned, score),
+    summary: zeroRulesLoaded ? "indeterminate; zero_rules_loaded" : integrityFailed ? `failed with score ${score}; ${input.integrity.reasons.join("; ") || "governance integrity is unhealthy"}` : agentSummary(input.findings.length, input.filesScanned, score),
     integrity: input.integrity,
     fix_first: agentFindings.filter((finding) => finding.plan.confidence >= 0.8),
     remaining: agentFindings.filter((finding) => finding.plan.confidence < 0.8),
@@ -428,7 +442,23 @@ function buildAgentFormat(input) {
         ...suppression.expiresOn ? { expiresOn: suppression.expiresOn } : {},
         scope: "line"
       }))
-    } : {}
+    } : {},
+    ...input.provenance ? { provenance: input.provenance } : {},
+    ...input.verdict ? { verdict: input.verdict } : {}
+  };
+  if (zeroRulesLoaded) {
+    return {
+      ...shared,
+      integrity: { ...input.integrity, rulesLoaded: 0 },
+      passed: false,
+      status: "indeterminate",
+      reasons: ["zero_rules_loaded"]
+    };
+  }
+  return {
+    ...shared,
+    passed: !integrityFailed && (input.passed ?? true) && !hasErrors,
+    score
   };
 }
 function uniqueFindings(findings) {
@@ -1651,16 +1681,20 @@ var tokenSourceSchema = z4.object({
 var tokenConfigSchema = z4.object({
   include: repoRelativePathsSchema.optional(),
   sources: z4.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: z4.array(z4.string().min(1)).optional(),
   exclude: z4.array(repoRelativePathSchema).optional(),
   themeSelectors: z4.record(z4.string()).optional(),
   enabled: z4.boolean().optional(),
   format: z4.enum(["auto", "css", "scss", "dtcg", "tailwind"]).optional(),
   namespace: z4.string().min(1).optional()
 }).passthrough().superRefine((tokens, ctx) => {
-  if (!tokens.include?.length && !tokens.sources?.length) {
+  if (!tokens.include?.length && !tokens.sources?.length && !tokens.packages?.length) {
     ctx.addIssue({
       code: z4.ZodIssueCode.custom,
-      message: "Add tokens.include or tokens.sources",
+      message: "Add tokens.include, tokens.sources, or tokens.packages",
       path: ["sources"]
     });
   }
@@ -2903,30 +2937,41 @@ function inferTokenGroup(name) {
       return category;
   }
 }
+var TOKEN_GROUP_COMMENT_MAPPINGS = {
+  "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"
+};
+function looksLikeCleanHeading(text) {
+  if (!/^[a-z0-9][a-z0-9 -]*$/.test(text)) return false;
+  const wordCount = text.split(/\s+/).filter(Boolean).length;
+  return wordCount > 0 && wordCount <= 3;
+}
 function normalizeTokenGroupComment(comment) {
   const text = comment.trim().replace(/^\/\/\s*/, "").replace(/^\/\*+\s*/, "").replace(/\s*\*+\/$/, "").trim().toLowerCase();
-  const mappings = {
-    "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];
+  }
+  if (!looksLikeCleanHeading(text)) {
+    return null;
+  }
+  return text.replace(/\s+/g, "-");
 }
 
 // src/tokens/scss.ts
@@ -2993,7 +3038,7 @@ function parseScssTokens(content, filePath = "tokens.scss") {
   const tokens = [];
   const seenNames = /* @__PURE__ */ new Set();
   let currentCategory = "other";
-  let hasCommentCategories = false;
+  let currentCategoryIsCurated = false;
   const scssVars = parseScssVariables(content);
   const varDeclRegex = /^\s*(--[\w-]+)\s*:\s*(.+?)\s*;/;
   const sectionCommentRegex = /^\s*\/\/\s+([A-Z].+)$/;
@@ -3003,7 +3048,9 @@ function parseScssTokens(content, filePath = "tokens.scss") {
       const normalized = normalizeTokenGroupComment(commentMatch[0]);
       if (normalized) {
         currentCategory = normalized;
-        hasCommentCategories = true;
+        currentCategoryIsCurated = true;
+      } else {
+        currentCategoryIsCurated = false;
       }
       continue;
     }
@@ -3019,7 +3066,7 @@ function parseScssTokens(content, filePath = "tokens.scss") {
       tokens.push({
         name,
         value: cleanValue || void 0,
-        category: hasCommentCategories ? currentCategory : inferTokenGroup(name),
+        category: currentCategoryIsCurated ? currentCategory : inferTokenGroup(name),
         description
       });
     }
@@ -3030,7 +3077,7 @@ function parseScssTokens(content, filePath = "tokens.scss") {
     tokens.push({
       name,
       value,
-      category: hasCommentCategories ? currentCategory : inferTokenGroup(name)
+      category: currentCategoryIsCurated ? currentCategory : inferTokenGroup(name)
     });
   }
   const cssVarValues = /* @__PURE__ */ new Map();
@@ -3326,19 +3373,35 @@ function parsedOutputToDesignTokens(output, filePath) {
   return tokens;
 }
 function scssOutputToDesignTokens(output, filePath) {
-  const names = /* @__PURE__ */ new Set();
-  const tokens = [];
+  const tokensByName = /* @__PURE__ */ new Map();
   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: /* @__PURE__ */ 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
+    ])
+  );
 }
-function designTokenFromParsed(name, parsed, filePath) {
+function designTokenFromParsed(name, parsed, filePath, referenceFormat, sourceNames) {
   return {
     name,
     rawValue: parsed.value ?? "",
@@ -3351,6 +3414,8 @@ function designTokenFromParsed(name, parsed, filePath) {
     level: 1,
     referenceChain: [],
     sourceFile: filePath,
+    referenceFormat,
+    ...sourceNames?.length ? { sourceNames } : {},
     theme: "default",
     selector: ":root",
     description: parsed.description
@@ -4289,12 +4354,37 @@ function makeFinding(input) {
     fingerprint,
     location: input.location,
     evidence: input.evidence,
+    evidenceGrade: input.evidenceGrade ?? "source_backed",
     fix: input.fix,
     attributes: input.attributes
   });
 }
 
 // src/rules/utils.ts
+function emitFix(fix, proof, ix) {
+  const reasons = [];
+  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 !== void 0 && !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("; ") } : {}
+  };
+}
+function tokenSymbolsInText(value) {
+  return [...new Set(value.match(/\$[A-Za-z0-9_-]+|--[A-Za-z0-9_-]+/g) ?? [])];
+}
 function indexPropsByNodeId(ix) {
   const out = /* @__PURE__ */ new Map();
   for (const fact of ix.byKind("usage_prop_resolved")) {
@@ -4373,13 +4463,6 @@ function readUsageNode(ix, id) {
   const fact = ix.get(id);
   return fact && fact.kind === "usage_node" ? fact : void 0;
 }
-function cssVariableNames(tokens) {
-  const names = /* @__PURE__ */ new Set();
-  for (const token of tokens) {
-    names.add(token.name.startsWith("--") ? token.name : `--${token.name}`);
-  }
-  return names;
-}
 function contractPrefixFamilies(names) {
   const families = /* @__PURE__ */ new Set();
   for (const name of names) {
@@ -4993,11 +5076,13 @@ function ruleComponentsPreferLibrary(ix) {
   const textByNode = indexTextChildrenByNodeId(ix);
   const classTokensByNode = indexClassTokensByNode(ix);
   const reimplTargets = canonicalReimplTargets(sources, mappings);
+  const canonicalDirectoryResolvedNodes = indexCanonicalDirectoryResolvedNodes(ix, sources);
   const findings = [];
   const seenImportFixes = /* @__PURE__ */ new Set();
   for (const node of ix.byKind("usage_node")) {
     if (isCanonicalSourceImplementationFile(node.file, sources)) continue;
     if (node.element.includes(".")) continue;
+    if (canonicalDirectoryResolvedNodes.has(node.id)) continue;
     const props = propsByNode.get(node.id) ?? [];
     const textChildren = textByNode.get(node.id) ?? [];
     const importsForFile = importsByFileAndLocal.get(node.file);
@@ -5523,7 +5608,27 @@ function sourceLabel(source) {
 function canonicalImportPath(source) {
   if (source.kind === "npm") return source.specifier;
   if (source.kind === "registry") return source.importPath;
-  return void 0;
+  return source.include?.length ? source.path : void 0;
+}
+function indexCanonicalDirectoryResolvedNodes(ix, sources) {
+  const out = /* @__PURE__ */ new Set();
+  const directoryPaths = sources.filter(
+    (source) => source.kind === "directory"
+  ).map((source) => normalizePath(source.path));
+  if (directoryPaths.length === 0) return out;
+  for (const fact of ix.byKind("usage_component")) {
+    const module = componentIdModule(fact.componentId);
+    if (module === void 0) continue;
+    const normalizedModule = normalizePath(module);
+    if (directoryPaths.some((path) => isPathInSource(normalizedModule, path))) {
+      out.add(fact.nodeId);
+    }
+  }
+  return out;
+}
+function componentIdModule(componentId2) {
+  const hash = componentId2.indexOf("#");
+  return hash > 0 ? componentId2.slice(0, hash) : void 0;
 }
 function isCanonicalSourceImplementationFile(file, sources) {
   const normalizedFile = normalizePath(file);
@@ -6164,12 +6269,14 @@ function ruleStylesNoRawColor(ix) {
   const colorTokens = ix.tokens.byCategory("color");
   const preferLabel = policy.prefer === "token" ? "design token" : "CSS variable";
   const findings = [];
+  const advisorySeverity = policy.severity === "error" ? "warn" : policy.severity;
   for (const decl of ix.byKind("style_declaration")) {
     if (decl.property.startsWith("--") && decl.declaredTokenSource === true) continue;
     const color = detectRawColor(decl.value);
     if (!color) continue;
     if (isExemptColor(color, policy.except)) continue;
     const resolution = resolveColorToken(decl.property, color, colorTokens);
+    const fixEmission = resolution?.kind === "exact" ? buildTokenFix(decl.property, decl.value, color, resolution, ix) : void 0;
     const evidenceIds = resolution ? [decl.id, policy.id, resolution.token.id] : [decl.id, policy.id];
     findings.push(
       makeFinding({
@@ -6187,20 +6294,52 @@ function ruleStylesNoRawColor(ix) {
           property: decl.property,
           value: color
         },
-        fix: resolution?.kind === "exact" ? buildTokenFix(decl.property, decl.value, color, resolution) : void 0,
+        fix: fixEmission?.fix,
         attributes: {
           property: decl.property,
           rawValue: decl.value,
           color,
           source: "css",
           suggestedToken: resolution?.token.name,
-          ...resolution ? { tokenMatch: resolution.kind } : {}
+          ...resolution ? { tokenMatch: resolution.kind } : {},
+          ...fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}
         }
       })
     );
   }
   const componentByNode = indexComponentByNodeId(ix);
   for (const inline of ix.byKind("usage_inline_style")) {
+    if (inline.valueKind === "dynamic-raw") {
+      const node2 = readUsageNode(ix, inline.nodeId);
+      if (!node2) continue;
+      const componentEvidenceId2 = componentByNode.get(node2.id)?.id;
+      const evidenceIds2 = componentEvidenceId2 ? [node2.id, componentEvidenceId2, inline.id, policy.id] : [node2.id, inline.id, policy.id];
+      findings.push(
+        makeFinding({
+          ruleId: RULE_ID8,
+          ruleVersion: RULE_VERSION9,
+          severity: advisorySeverity,
+          message: `Runtime-constructed raw color \`${inline.value}\` on inline \`${inline.property}\`. Use a ${preferLabel} instead.`,
+          location: node2.location,
+          evidence: ix.evidence(evidenceIds2),
+          fingerprintIdentity: {
+            source: "usage_inline_style_dynamic",
+            file: node2.file,
+            nodePath: node2.nodePath,
+            element: node2.element,
+            property: inline.property,
+            value: inline.value
+          },
+          attributes: {
+            property: inline.property,
+            rawValue: inline.value,
+            source: "jsx",
+            dynamic: true
+          }
+        })
+      );
+      continue;
+    }
     if (inline.valueKind === "css-variable") continue;
     const color = detectRawColor(inline.value);
     if (!color) continue;
@@ -6209,6 +6348,7 @@ function ruleStylesNoRawColor(ix) {
     if (!node) continue;
     const componentEvidenceId = componentByNode.get(node.id)?.id;
     const resolution = resolveColorToken(inline.property, color, colorTokens);
+    const fixEmission = resolution?.kind === "exact" ? buildTokenFix(inline.property, inline.value, color, resolution, ix) : void 0;
     const baseEvidence = componentEvidenceId ? [node.id, componentEvidenceId, inline.id, policy.id] : [node.id, inline.id, policy.id];
     const evidenceIds = resolution ? [...baseEvidence, resolution.token.id] : baseEvidence;
     findings.push(
@@ -6227,20 +6367,81 @@ function ruleStylesNoRawColor(ix) {
           property: inline.property,
           value: color
         },
-        fix: resolution?.kind === "exact" ? buildTokenFix(inline.property, inline.value, color, resolution) : void 0,
+        fix: fixEmission?.fix,
         attributes: {
           property: inline.property,
           rawValue: inline.value,
           color,
           source: "jsx",
           suggestedToken: resolution?.token.name,
-          ...resolution ? { tokenMatch: resolution.kind } : {}
+          ...resolution ? { tokenMatch: resolution.kind } : {},
+          ...fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}
+        }
+      })
+    );
+  }
+  for (const prop of ix.byKind("usage_prop_resolved")) {
+    if (prop.resolution !== "static") continue;
+    if (typeof prop.value !== "string") continue;
+    if (!SVG_PAINT_ATTRS.has(prop.prop)) continue;
+    const color = detectRawColor(prop.value);
+    if (!color) continue;
+    if (isExemptColor(color, policy.except)) continue;
+    const node = readUsageNode(ix, prop.nodeId);
+    if (!node) continue;
+    const componentEvidenceId = componentByNode.get(node.id)?.id;
+    const cssProperty = SVG_PAINT_CSS_PROPERTY[prop.prop] ?? prop.prop;
+    const resolution = resolveColorToken(cssProperty, color, colorTokens);
+    const fixEmission = resolution?.kind === "exact" ? buildTokenFix(cssProperty, prop.value, color, resolution, ix) : void 0;
+    const baseEvidence = componentEvidenceId ? [node.id, componentEvidenceId, prop.id, policy.id] : [node.id, prop.id, policy.id];
+    const evidenceIds = resolution ? [...baseEvidence, resolution.token.id] : baseEvidence;
+    findings.push(
+      makeFinding({
+        ruleId: RULE_ID8,
+        ruleVersion: RULE_VERSION9,
+        severity: advisorySeverity,
+        message: colorMessage(color, `\`${prop.prop}\``, resolution, preferLabel),
+        location: prop.location ?? node.location,
+        evidence: ix.evidence(evidenceIds),
+        fingerprintIdentity: {
+          source: "usage_prop_resolved",
+          file: node.file,
+          nodePath: node.nodePath,
+          element: node.element,
+          property: prop.prop,
+          value: color
+        },
+        fix: fixEmission?.fix,
+        attributes: {
+          property: prop.prop,
+          rawValue: prop.value,
+          color,
+          source: "jsx",
+          suggestedToken: resolution?.token.name,
+          ...resolution ? { tokenMatch: resolution.kind } : {},
+          ...fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}
         }
       })
     );
   }
   return findings;
 }
+var SVG_PAINT_ATTRS = /* @__PURE__ */ new Set([
+  "fill",
+  "stroke",
+  "color",
+  "stop-color",
+  "stopColor",
+  "flood-color",
+  "floodColor",
+  "lighting-color",
+  "lightingColor"
+]);
+var SVG_PAINT_CSS_PROPERTY = {
+  stopColor: "stop-color",
+  floodColor: "flood-color",
+  lightingColor: "lighting-color"
+};
 function resolveColorToken(property, raw, tokens) {
   const exact = findTokenMatch(property, raw, tokens);
   if (exact) return { kind: "exact", token: exact.token, ambiguous: exact.ambiguous };
@@ -6318,21 +6519,24 @@ function normalizeColor2(value) {
   }
   return lower;
 }
-function buildTokenFix(property, rawValue, rawColor, match) {
+function buildTokenFix(property, rawValue, rawColor, match, ix) {
   const reference = tokenReference(match.token.name);
   const value = replaceRawColor(rawValue, rawColor, reference);
-  return {
-    kind: "replaceStyleValue",
-    title: `Replace ${property} with ${value}`,
-    property,
-    value,
-    // Apply automatically only when the swap is unambiguous AND the reference
-    // resolves verbatim. An ambiguous match (several tokens share the value,
-    // none role-matching) or a token that can't be referenced from CSS (a Sass
-    // *map* member, or a DTCG JSON token with no emitted custom property) is a
-    // suggestion — applying it would cross roles or write non-compiling code.
-    deterministic: !match.ambiguous && isApplicableTokenReference(match.token.referenceFormat)
-  };
+  return emitFix(
+    {
+      kind: "replaceStyleValue",
+      title: `Replace ${property} with ${value}`,
+      property,
+      value,
+      deterministic: true
+    },
+    {
+      symbols: [match.token.name],
+      editKind: "replaceStyleValue",
+      valuePreserving: !match.ambiguous
+    },
+    ix
+  );
 }
 function replaceRawColor(rawValue, rawColor, replacement) {
   if (rawValue === rawColor) return replacement;
@@ -6363,6 +6567,7 @@ function ruleStylesNoRawDimensions(ix) {
     if (!resolution) continue;
     const tokenIds = resolutionTokenIds(resolution);
     const evidenceIds = tokenIds.length ? [decl.id, policy.id, ...tokenIds] : [decl.id, policy.id];
+    const fixEmission = dimensionFix(decl.property, resolution, ix);
     findings.push(
       makeFinding({
         ruleId: RULE_ID9,
@@ -6379,12 +6584,13 @@ function ruleStylesNoRawDimensions(ix) {
           property: decl.property,
           value: decl.value
         },
-        fix: dimensionFix(decl.property, resolution),
+        fix: fixEmission?.fix,
         attributes: {
           property: decl.property,
           rawValue: decl.value,
           source: "css",
-          suggestedToken: resolutionSuggestedToken(resolution)
+          suggestedToken: resolutionSuggestedToken(resolution),
+          ...fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}
         }
       })
     );
@@ -6403,6 +6609,7 @@ function ruleStylesNoRawDimensions(ix) {
     const baseEvidence = componentEvidenceId ? [node.id, componentEvidenceId, inline.id, policy.id] : [node.id, inline.id, policy.id];
     const tokenIds = resolutionTokenIds(resolution);
     const evidenceIds = tokenIds.length ? [...baseEvidence, ...tokenIds] : baseEvidence;
+    const fixEmission = dimensionFix(inline.property, resolution, ix);
     findings.push(
       makeFinding({
         ruleId: RULE_ID9,
@@ -6419,12 +6626,13 @@ function ruleStylesNoRawDimensions(ix) {
           property: inline.property,
           value: inline.value
         },
-        fix: dimensionFix(inline.property, resolution),
+        fix: fixEmission?.fix,
         attributes: {
           property: inline.property,
           rawValue: inline.value,
           source: "jsx",
-          suggestedToken: resolutionSuggestedToken(resolution)
+          suggestedToken: resolutionSuggestedToken(resolution),
+          ...fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}
         }
       })
     );
@@ -6469,15 +6677,23 @@ function dimensionMessage(rawValue, property, preferLabel, resolution, inline) {
   }
   return `Raw dimension ${rawValue} on ${where}. Use a ${preferLabel} instead.`;
 }
-function dimensionFix(property, resolution) {
+function dimensionFix(property, resolution, ix) {
   if (resolution.kind === "exact") {
-    return {
-      kind: "replaceStyleValue",
-      title: `Replace ${property} with ${resolution.fixValue}`,
-      property,
-      value: resolution.fixValue,
-      deterministic: true
-    };
+    return emitFix(
+      {
+        kind: "replaceStyleValue",
+        title: `Replace ${property} with ${resolution.fixValue}`,
+        property,
+        value: resolution.fixValue,
+        deterministic: true
+      },
+      {
+        symbols: resolution.tokens.map((token) => token.name),
+        editKind: "replaceStyleValue",
+        valuePreserving: true
+      },
+      ix
+    );
   }
   return void 0;
 }
@@ -6578,7 +6794,7 @@ function resolveSpacingValue(input) {
   let anyOffScale = false;
   let canFixAll = true;
   let reliableSuggestion = true;
-  let allApplicableValuePreserving = true;
+  let allValuePreserving = true;
   for (const part of parts) {
     const normalized = normalizeLengthForScale(part.parsed, input.scale);
     if (normalized === null) return null;
@@ -6592,8 +6808,7 @@ function resolveSpacingValue(input) {
       }
       anyViolation = true;
       const reference = tokenReference(exactToken.name);
-      const applicable = isApplicableTokenReference(exactToken.referenceFormat) && normalized.deterministicFix;
-      if (!applicable) allApplicableValuePreserving = false;
+      if (!normalized.deterministicFix) allValuePreserving = false;
       suggestedParts.push(reference);
       if (!firstViolation) {
         firstViolation = {
@@ -6601,7 +6816,7 @@ function resolveSpacingValue(input) {
           suggestedValue: reference,
           suggestedToken: exactToken.name,
           fixEmittable: true,
-          deterministicFix: applicable,
+          deterministicFix: normalized.deterministicFix,
           reason: "token-equivalent",
           matchedToken: exactToken.name,
           assumedRootFontSizePx: normalized.assumedRootFontSizePx,
@@ -6612,7 +6827,7 @@ function resolveSpacingValue(input) {
     }
     anyViolation = true;
     anyOffScale = true;
-    allApplicableValuePreserving = false;
+    allValuePreserving = false;
     const nearest = nearestSignedScaleValue(normalized.value, input.allowed);
     const snapsToZero = nearest === 0 && normalized.value !== 0;
     let suggestedPart;
@@ -6645,7 +6860,7 @@ function resolveSpacingValue(input) {
   const joined = suggestedParts.join(" ");
   const changes = joined !== input.raw.trim().replace(/\s+/g, " ");
   const fixEmittable = canFixAll && reliableSuggestion && changes;
-  const deterministic = fixEmittable && !anyOffScale && allApplicableValuePreserving;
+  const deterministic = fixEmittable && !anyOffScale && allValuePreserving;
   return {
     ...firstViolation,
     reason: anyOffScale ? "off-scale" : "token-equivalent",
@@ -6709,6 +6924,7 @@ function checkDeclaration(ix, decl, lookupFor) {
     tokens: lookupFor(scale)
   });
   if (!checked) return null;
+  const fixEmission = buildSpacingFix(decl.property, checked, ix);
   return makeFinding({
     ruleId: RULE_ID10,
     ruleVersion: RULE_VERSION11,
@@ -6724,7 +6940,7 @@ function checkDeclaration(ix, decl, lookupFor) {
       property: decl.property,
       value: decl.value
     },
-    fix: buildSpacingFix(decl.property, checked),
+    fix: fixEmission?.fix,
     attributes: {
       property: decl.property,
       rawValue: decl.value,
@@ -6738,7 +6954,8 @@ function checkDeclaration(ix, decl, lookupFor) {
       normalizedUnit: scale.unit,
       assumedRootFontSizePx: checked.assumedRootFontSizePx,
       assumedEmBasePx: checked.assumedEmBasePx,
-      source: "css"
+      source: "css",
+      ...fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}
     }
   });
 }
@@ -6758,6 +6975,7 @@ function checkInlineStyle(ix, inline, componentByNode, lookupFor) {
     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;
   const componentEvidenceId = componentByNode.get(node.id)?.id;
@@ -6777,7 +6995,7 @@ function checkInlineStyle(ix, inline, componentByNode, lookupFor) {
       property: inline.property,
       value: inline.value
     },
-    fix: buildSpacingFix(inline.property, checked),
+    fix: fixEmission?.fix,
     attributes: {
       property: inline.property,
       rawValue: inline.value,
@@ -6791,19 +7009,28 @@ function checkInlineStyle(ix, inline, componentByNode, lookupFor) {
       normalizedUnit: scale.unit,
       assumedRootFontSizePx: checked.assumedRootFontSizePx,
       assumedEmBasePx: checked.assumedEmBasePx,
-      source: "jsx"
+      source: "jsx",
+      ...fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}
     }
   });
 }
-function buildSpacingFix(property, checked) {
+function buildSpacingFix(property, checked, ix) {
   if (!checked.fixEmittable || checked.suggestedValue === void 0) return void 0;
-  return {
-    kind: "replaceStyleValue",
-    title: `Replace ${property} with ${checked.suggestedValue}`,
-    property,
-    value: checked.suggestedValue,
-    deterministic: checked.deterministicFix
-  };
+  return emitFix(
+    {
+      kind: "replaceStyleValue",
+      title: `Replace ${property} with ${checked.suggestedValue}`,
+      property,
+      value: checked.suggestedValue,
+      deterministic: true
+    },
+    {
+      symbols: tokenSymbolsInText(checked.suggestedValue),
+      editKind: "replaceStyleValue",
+      valuePreserving: checked.deterministicFix
+    },
+    ix
+  );
 }
 function spacingMessage(property, value, allowed, unit, checked) {
   if (checked.reason === "token-equivalent" && checked.matchedToken) {
@@ -6832,6 +7059,7 @@ function ruleStylesNoRawTypography(ix) {
     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_ID11,
@@ -6848,7 +7076,7 @@ function ruleStylesNoRawTypography(ix) {
           property: decl.property,
           value: decl.value
         },
-        fix: buildFix(decl.property, checked),
+        fix: fixEmission?.fix,
         attributes: {
           property: decl.property,
           rawValue: decl.value,
@@ -6856,7 +7084,8 @@ function ruleStylesNoRawTypography(ix) {
           allowed,
           suggestedValue: checked.suggestedValue,
           matchedToken: checked.matchedToken,
-          source: "css"
+          source: "css",
+          ...fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}
         }
       })
     );
@@ -6865,8 +7094,15 @@ function ruleStylesNoRawTypography(ix) {
   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;
@@ -6887,7 +7123,7 @@ function ruleStylesNoRawTypography(ix) {
           property: inline.property,
           value: inline.value
         },
-        fix: buildFix(inline.property, checked),
+        fix: fixEmission?.fix,
         attributes: {
           property: inline.property,
           rawValue: inline.value,
@@ -6895,7 +7131,8 @@ function ruleStylesNoRawTypography(ix) {
           allowed,
           suggestedValue: checked.suggestedValue,
           matchedToken: checked.matchedToken,
-          source: "jsx"
+          source: "jsx",
+          ...fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}
         }
       })
     );
@@ -6925,11 +7162,10 @@ function checkFontSize(raw, allowed, scale, tokens, bareNumberFix = false) {
   const exactToken = tokens.get(magnitude);
   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
     };
@@ -6947,15 +7183,23 @@ function checkFontSize(raw, allowed, scale, tokens, bareNumberFix = false) {
     reason: "off-scale"
   };
 }
-function buildFix(property, checked) {
+function buildFix(property, checked, ix) {
   if (!checked.fixEmittable || checked.suggestedValue === void 0) return void 0;
-  return {
-    kind: "replaceStyleValue",
-    title: `Replace ${property} with ${checked.suggestedValue}`,
-    property,
-    value: checked.suggestedValue,
-    deterministic: checked.deterministicFix
-  };
+  return emitFix(
+    {
+      kind: "replaceStyleValue",
+      title: `Replace ${property} with ${checked.suggestedValue}`,
+      property,
+      value: checked.suggestedValue,
+      deterministic: true
+    },
+    {
+      symbols: tokenSymbolsInText(checked.suggestedValue),
+      editKind: "replaceStyleValue",
+      valuePreserving: checked.deterministicFix
+    },
+    ix
+  );
 }
 function typographyMessage(property, value, allowed, unit, checked) {
   if (checked.reason === "token-equivalent" && checked.matchedToken) {
@@ -7629,7 +7873,7 @@ var SASS_FILE = /\.(scss|sass)$/i;
 function ruleTokensRequireDualFallback(ix) {
   const policy = ix.policy.ruleConfig(RULE_ID19);
   if (!policy?.enabled) return [];
-  const knownTokenVars = cssVariableNames(ix.tokens.list());
+  const tokensByCssVariable = indexTokensByCssVariable(ix.tokens.list());
   const findings = [];
   for (const decl of ix.byKind("style_declaration")) {
     if (!SASS_FILE.test(decl.file)) continue;
@@ -7639,19 +7883,35 @@ function ruleTokensRequireDualFallback(ix) {
       const tokenName = match[1];
       const hasFallback = match[2] !== void 0;
       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})`) : void 0;
+      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
+      ) : void 0;
       findings.push(
         makeFinding({
           ruleId: RULE_ID19,
           ruleVersion: RULE_VERSION20,
           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,
@@ -7659,18 +7919,13 @@ function ruleTokensRequireDualFallback(ix) {
             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"
           }
         })
@@ -7679,6 +7934,17 @@ function ruleTokensRequireDualFallback(ix) {
   }
   return findings;
 }
+function indexTokensByCssVariable(tokens) {
+  const indexed = /* @__PURE__ */ new Map();
+  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;
+}
 
 // src/rules/tokens-css-vars-must-be-defined.ts
 var RULE_ID20 = "tokens/css-vars-must-be-defined";
@@ -7770,6 +8036,8 @@ var BLOCKING_RULE_ALLOWLIST = /* @__PURE__ */ new Set([
   // imported component bypasses its canonical
 ]);
 function gatesCi(finding, failOnWarnings) {
+  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";
 }
@@ -8500,6 +8768,7 @@ export {
   DEFAULTS,
   DEFAULT_ENHANCED_STYLE_PROPERTIES,
   DEFAULT_STYLE_PROPERTIES,
+  EVIDENCE_ORDER,
   EXPLAIN_URL_BASE,
   FRAGMENTS_INTERNAL_RULE_IDS,
   FactIndex,
@@ -8551,6 +8820,7 @@ export {
   byCode,
   byRuleId,
   calculateDeltaE,
+  canBlock,
   canonicalJson,
   canonicalPreimage,
   canonicalizeOwnedComponentId,