@usefragments/core 1.2.0 → 1.4.0

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

@@ -18,11 +18,12 @@ import { makeFinding } from "./finding.js";
 import type { Finding, FindingReplaceStyleValueFix } from "./types.js";
 import {
   detectRawColor,
+  emitFix,
   indexComponentByNodeId,
-  isApplicableTokenReference,
   isExemptColor,
   readUsageNode,
   tokenReference,
+  type FixEmission,
 } from "./utils.js";
 
 export const RULE_ID = "styles/no-raw-color";
@@ -36,6 +37,12 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
   const preferLabel = policy.prefer === "token" ? "design token" : "CSS variable";
   const findings: Finding[] = [];
 
+  // Newly-broadened detections (SVG paint attributes, runtime-constructed
+  // colors) ship advisory this release so CI gates do not harden on findings
+  // teams have not yet had a chance to triage. Existing passes keep the
+  // configured severity.
+  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);
@@ -43,6 +50,10 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
     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)
+        : undefined;
     const evidenceIds = resolution
       ? [decl.id, policy.id, resolution.token.id]
       : [decl.id, policy.id];
@@ -63,10 +74,7 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
           property: decl.property,
           value: color,
         },
-        fix:
-          resolution?.kind === "exact"
-            ? buildTokenFix(decl.property, decl.value, color, resolution)
-            : undefined,
+        fix: fixEmission?.fix,
         attributes: {
           property: decl.property,
           rawValue: decl.value,
@@ -74,6 +82,7 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
           source: "css",
           suggestedToken: resolution?.token.name,
           ...(resolution ? { tokenMatch: resolution.kind } : {}),
+          ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
         },
       })
     );
@@ -81,6 +90,43 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
 
   const componentByNode = indexComponentByNodeId(ix);
   for (const inline of ix.byKind("usage_inline_style")) {
+    // #11b — a runtime-constructed color (`` `#${red}` ``, `"rgb(" + r + …`).
+    // The extractor already proved the static fragments begin a color literal,
+    // so surface it detect-only: the value is partly runtime, so it never
+    // carries a deterministic fix and cannot resolve to a token.
+    if (inline.valueKind === "dynamic-raw") {
+      const node = readUsageNode(ix, inline.nodeId);
+      if (!node) continue;
+      const componentEvidenceId = componentByNode.get(node.id)?.id;
+      const evidenceIds = componentEvidenceId
+        ? [node.id, componentEvidenceId, inline.id, policy.id]
+        : [node.id, inline.id, policy.id];
+      findings.push(
+        makeFinding({
+          ruleId: RULE_ID,
+          ruleVersion: RULE_VERSION,
+          severity: advisorySeverity,
+          message: `Runtime-constructed raw color \`${inline.value}\` on inline \`${inline.property}\`. Use a ${preferLabel} instead.`,
+          location: node.location,
+          evidence: ix.evidence(evidenceIds),
+          fingerprintIdentity: {
+            source: "usage_inline_style_dynamic",
+            file: node.file,
+            nodePath: node.nodePath,
+            element: node.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;
@@ -91,6 +137,10 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
 
     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)
+        : undefined;
     const baseEvidence = componentEvidenceId
       ? [node.id, componentEvidenceId, inline.id, policy.id]
       : [node.id, inline.id, policy.id];
@@ -112,10 +162,7 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
           property: inline.property,
           value: color,
         },
-        fix:
-          resolution?.kind === "exact"
-            ? buildTokenFix(inline.property, inline.value, color, resolution)
-            : undefined,
+        fix: fixEmission?.fix,
         attributes: {
           property: inline.property,
           rawValue: inline.value,
@@ -123,6 +170,64 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
           source: "jsx",
           suggestedToken: resolution?.token.name,
           ...(resolution ? { tokenMatch: resolution.kind } : {}),
+          ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
+        },
+      })
+    );
+  }
+
+  // #9d — SVG presentation attributes carry color in JSX markup, not CSS, so
+  // they arrive as `usage_prop_resolved` facts the two passes above never read.
+  // Scan a fixed paint-attribute allowlist for static raw colors. Data-URI
+  // colors (hex inside an encoded `url("data:…")`) are intentionally left out.
+  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)
+        : undefined;
+    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_ID,
+        ruleVersion: RULE_VERSION,
+        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 } : {}),
         },
       })
     );
@@ -131,6 +236,31 @@ export function ruleStylesNoRawColor(ix: FactIndex): Finding[] {
   return findings;
 }
 
+/**
+ * SVG presentation attributes that carry a paint (color) value in JSX markup.
+ * Both the raw-SVG kebab spelling and React's camelCase normalization are
+ * listed so `stop-color` and `stopColor` both resolve.
+ */
+const SVG_PAINT_ATTRS = new Set([
+  "fill",
+  "stroke",
+  "color",
+  "stop-color",
+  "stopColor",
+  "flood-color",
+  "floodColor",
+  "lighting-color",
+  "lightingColor",
+]);
+
+/** Map camelCase paint attributes to their CSS property name so the token
+ *  role-resolver (`colorRoleForProperty`) reasons over a canonical spelling. */
+const SVG_PAINT_CSS_PROPERTY: Record<string, string> = {
+  stopColor: "stop-color",
+  floodColor: "flood-color",
+  lightingColor: "lighting-color",
+};
+
 interface TokenMatch {
   token: TokenDefinitionFact;
   /** True when several tokens share the value and none matches the property's
@@ -298,22 +428,26 @@ function buildTokenFix(
   property: string,
   rawValue: string,
   rawColor: string,
-  match: TokenMatch
-): FindingReplaceStyleValueFix {
+  match: TokenMatch,
+  ix: FactIndex
+): FixEmission<FindingReplaceStyleValueFix> {
   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: string, rawColor: string, replacement: string): string {

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

@@ -31,7 +31,13 @@ import type { FactId, FactIndex, TokenDefinitionFact } from "../facts/index.js";
 
 import { makeFinding } from "./finding.js";
 import type { Finding, FindingReplaceStyleValueFix } from "./types.js";
-import { indexComponentByNodeId, parseLengthValue, readUsageNode } from "./utils.js";
+import {
+  emitFix,
+  indexComponentByNodeId,
+  parseLengthValue,
+  readUsageNode,
+  type FixEmission,
+} from "./utils.js";
 
 export const RULE_ID = "styles/no-raw-dimensions";
 export const RULE_VERSION = "1";
@@ -75,6 +81,7 @@ export function ruleStylesNoRawDimensions(ix: FactIndex): Finding[] {
     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({
@@ -92,12 +99,13 @@ export function ruleStylesNoRawDimensions(ix: FactIndex): Finding[] {
           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),
+          ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
         },
       })
     );
@@ -121,6 +129,7 @@ export function ruleStylesNoRawDimensions(ix: FactIndex): Finding[] {
       : [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({
@@ -138,12 +147,13 @@ export function ruleStylesNoRawDimensions(ix: FactIndex): Finding[] {
           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),
+          ...(fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}),
         },
       })
     );
@@ -219,16 +229,25 @@ function dimensionMessage(
 
 function dimensionFix(
   property: string,
-  resolution: DimensionResolution
-): FindingReplaceStyleValueFix | undefined {
+  resolution: DimensionResolution,
+  ix: FactIndex
+): FixEmission<FindingReplaceStyleValueFix> | undefined {
   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
+    );
   }
   // `nearest` deliberately emits NO fix — a value-changing snap must stay a
   // suggestion (see DimensionResolution); only the exact, value-preserving swap

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);