@usefragments/core 1.0.0

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

@@ -0,0 +1,357 @@
+/**
+ * `styles/no-raw-dimensions` — fires when a length-bearing CSS declaration or
+ * JSX inline style uses a raw dimension literal (`16px`, `1rem`, …) on a
+ * property covered by the global `style.rawDimensions.forbid` policy.
+ *
+ * Suggestion strength is tiered, mirroring `styles/no-raw-spacing`:
+ *
+ * - **exact token match** — the raw value EXACTLY equals a tenant dimension
+ *   token of the same unit (units are never cross-converted — matching `1rem`
+ *   to a `16px` token would assume a root font size we cannot guarantee). Emits
+ *   a value-preserving, deterministic `var(--token)` fix.
+ * - **off-scale single value** — `border-radius: 10px` when the tenant has no
+ *   `10px` token. Names the NEAREST token of the same unit via `suggestedToken`
+ *   and the message, but attaches NO fix — snapping changes the rendered value,
+ *   so it must stay a suggestion the author confirms, never an auto-rewrite.
+ *   Same-unit only: a `px` value never snaps to a `rem` token, keeping the
+ *   suggestion free of an assumed root-font-size.
+ * - **no nearby token** (or a multi-value shorthand off-scale) — flagged with no
+ *   fix and no suggestion, leaving the choice to the author.
+ *
+ * Nearest snapping adds NO new findings and changes NO rendered values: an
+ * off-scale dimension already fires under this policy; the snap only enriches
+ * that finding with a `suggestedToken` hint.
+ *
+ * The policy is intentionally opt-in (no preset enables it): a plain
+ * `fragments govern scan` never flags raw dimensions. Only callers that supply
+ * a `style.rawDimensions.forbid` record (e.g. the conform tool) activate it.
+ */
+
+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";
+
+export const RULE_ID = "styles/no-raw-dimensions";
+export const RULE_VERSION = "1";
+
+interface DimensionFixMatch {
+  tokens: TokenDefinitionFact[];
+  fixValue: string;
+  suggestedToken: string;
+}
+
+/**
+ * How a raw dimension resolves against the tenant's tokens:
+ * - `exact`   — value-preserving token swap (deterministic, auto-applicable fix)
+ * - `nearest` — closest same-unit token, surfaced as a `suggestedToken` hint with
+ *   NO fix object: snapping changes the rendered value, and the conform engine
+ *   auto-applies any token-backed `replaceStyleValue` fix, so attaching one would
+ *   silently rewrite the value. The suggestion rides on the message + attribute.
+ * - `raw`     — flagged, but no token to suggest (no fix)
+ */
+type DimensionResolution =
+  | { kind: "exact"; tokens: TokenDefinitionFact[]; fixValue: string; suggestedToken: string }
+  | { kind: "nearest"; token: TokenDefinitionFact; suggestedToken: string }
+  | { kind: "raw" };
+
+export function ruleStylesNoRawDimensions(ix: FactIndex): Finding[] {
+  const policy = ix.policy.rawDimensionPolicy();
+  if (!policy) return [];
+
+  const appliesTo = new Set(policy.appliesTo);
+  const spacingTokens = ix.tokens.byCategory("spacing");
+  const radiusTokens = ix.tokens.byCategory("radius");
+  const preferLabel = policy.prefer === "token" ? "design token" : "CSS variable";
+  const findings: Finding[] = [];
+
+  for (const decl of ix.byKind("style_declaration")) {
+    const property = toKebabCase(decl.property);
+    if (!appliesTo.has(property)) continue;
+
+    const tokens = tokensForProperty(property, spacingTokens, radiusTokens);
+    const resolution = resolveDimension(decl.value, tokens);
+    if (!resolution) continue;
+    const tokenIds = resolutionTokenIds(resolution);
+    const evidenceIds = tokenIds.length ? [decl.id, policy.id, ...tokenIds] : [decl.id, policy.id];
+
+    findings.push(
+      makeFinding({
+        ruleId: RULE_ID,
+        ruleVersion: RULE_VERSION,
+        severity: policy.severity,
+        message: dimensionMessage(decl.value, decl.property, preferLabel, resolution, false),
+        location: decl.location,
+        evidence: ix.evidence(evidenceIds),
+        fingerprintIdentity: {
+          source: "style_declaration",
+          file: decl.file,
+          selector: decl.selector,
+          declarationPath: decl.declarationPath,
+          property: decl.property,
+          value: decl.value,
+        },
+        fix: dimensionFix(decl.property, resolution),
+        attributes: {
+          property: decl.property,
+          rawValue: decl.value,
+          source: "css",
+          suggestedToken: resolutionSuggestedToken(resolution),
+        },
+      })
+    );
+  }
+
+  const componentByNode = indexComponentByNodeId(ix);
+  for (const inline of ix.byKind("usage_inline_style")) {
+    if (inline.valueKind === "css-variable") continue;
+    const property = toKebabCase(inline.property);
+    if (!appliesTo.has(property)) continue;
+
+    const node = readUsageNode(ix, inline.nodeId);
+    if (!node) continue;
+
+    const componentEvidenceId = componentByNode.get(node.id)?.id;
+    const tokens = tokensForProperty(property, spacingTokens, radiusTokens);
+    const resolution = resolveDimension(inline.value, tokens);
+    if (!resolution) continue;
+    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;
+
+    findings.push(
+      makeFinding({
+        ruleId: RULE_ID,
+        ruleVersion: RULE_VERSION,
+        severity: policy.severity,
+        message: dimensionMessage(inline.value, inline.property, preferLabel, resolution, true),
+        location: node.location,
+        evidence: ix.evidence(evidenceIds),
+        fingerprintIdentity: {
+          source: "usage_inline_style",
+          file: node.file,
+          nodePath: node.nodePath,
+          element: node.element,
+          property: inline.property,
+          value: inline.value,
+        },
+        fix: dimensionFix(inline.property, resolution),
+        attributes: {
+          property: inline.property,
+          rawValue: inline.value,
+          source: "jsx",
+          suggestedToken: resolutionSuggestedToken(resolution),
+        },
+      })
+    );
+  }
+
+  return findings;
+}
+
+/** Normalize a JSX camelCase style key (`paddingTop`) to CSS kebab (`padding-top`). */
+function toKebabCase(property: string): string {
+  return property.replace(/([A-Z])/g, "-$1").toLowerCase();
+}
+
+function tokensForProperty(
+  property: string,
+  spacingTokens: readonly TokenDefinitionFact[],
+  radiusTokens: readonly TokenDefinitionFact[]
+): readonly TokenDefinitionFact[] {
+  return property.includes("radius") ? radiusTokens : spacingTokens;
+}
+
+/**
+ * Resolve a raw dimension against the candidate tokens, preferring an exact
+ * (value-preserving) match, then a nearest same-unit snap, then no token.
+ * Returns `null` when the value is neither a token match nor a raw dimension —
+ * i.e. nothing to flag.
+ */
+function resolveDimension(
+  raw: string,
+  tokens: readonly TokenDefinitionFact[]
+): DimensionResolution | null {
+  const exact = findDimensionFixMatch(raw, tokens);
+  if (exact) {
+    return {
+      kind: "exact",
+      tokens: exact.tokens,
+      fixValue: exact.fixValue,
+      suggestedToken: exact.suggestedToken,
+    };
+  }
+  if (!isRawDimensionValue(raw)) return null;
+
+  const nearest = findNearestDimensionToken(raw, tokens);
+  if (nearest) return { kind: "nearest", ...nearest };
+  return { kind: "raw" };
+}
+
+function resolutionTokenIds(resolution: DimensionResolution): FactId[] {
+  if (resolution.kind === "exact") return resolution.tokens.map((token) => token.id);
+  if (resolution.kind === "nearest") return [resolution.token.id];
+  return [];
+}
+
+function resolutionSuggestedToken(resolution: DimensionResolution): string | undefined {
+  if (resolution.kind === "exact") return resolution.suggestedToken;
+  if (resolution.kind === "nearest") return resolution.suggestedToken;
+  return undefined;
+}
+
+function dimensionMessage(
+  rawValue: string,
+  property: string,
+  preferLabel: string,
+  resolution: DimensionResolution,
+  inline: boolean
+): string {
+  const where = inline ? `inline \`${property}\`` : `\`${property}\``;
+  if (resolution.kind === "nearest") {
+    return `Raw dimension ${rawValue} on ${where}. Closest token is \`${resolution.suggestedToken}\` (${resolution.token.value}); use a ${preferLabel} instead.`;
+  }
+  return `Raw dimension ${rawValue} on ${where}. Use a ${preferLabel} instead.`;
+}
+
+function dimensionFix(
+  property: string,
+  resolution: DimensionResolution
+): FindingReplaceStyleValueFix | undefined {
+  if (resolution.kind === "exact") {
+    return {
+      kind: "replaceStyleValue",
+      title: `Replace ${property} with ${resolution.fixValue}`,
+      property,
+      value: resolution.fixValue,
+      deterministic: true,
+    };
+  }
+  // `nearest` deliberately emits NO fix — a value-changing snap must stay a
+  // suggestion (see DimensionResolution); only the exact, value-preserving swap
+  // is safe to auto-apply.
+  return undefined;
+}
+
+/**
+ * Find a dimension token whose value matches the raw literal exactly, compared
+ * in canonical px. No fuzzy/nearest matching — only value-preserving swaps earn
+ * an exact match.
+ */
+function findDimensionMatch(
+  raw: string,
+  tokens: readonly TokenDefinitionFact[]
+): TokenDefinitionFact | null {
+  const target = normalizeDimension(raw);
+  if (target === null) return null;
+  for (const token of tokens) {
+    if (normalizeDimension(token.value) === target) return token;
+  }
+  return null;
+}
+
+function findDimensionFixMatch(
+  raw: string,
+  tokens: readonly TokenDefinitionFact[]
+): DimensionFixMatch | null {
+  const single = findDimensionMatch(raw, tokens);
+  if (single) {
+    return {
+      tokens: [single],
+      fixValue: tokenVar(single),
+      suggestedToken: single.name,
+    };
+  }
+
+  const parts = raw.trim().split(/\s+/);
+  if (parts.length < 2 || parts.length > 4) return null;
+
+  const matches: TokenDefinitionFact[] = [];
+  for (const part of parts) {
+    const match = findDimensionMatch(part, tokens);
+    if (!match) return null;
+    matches.push(match);
+  }
+
+  return {
+    tokens: matches,
+    fixValue: matches.map(tokenVar).join(" "),
+    suggestedToken: matches.map((token) => token.name).join(" "),
+  };
+}
+
+/**
+ * For an off-scale SINGLE dimension value, find the nearest token of the SAME
+ * unit. Same-unit only keeps the suggestion value-safe: matching a `px` value
+ * to a `rem` token would assume a root font size we cannot guarantee. A non-zero
+ * value never snaps to a `0` token (that silently removes the dimension), and a
+ * multi-value shorthand returns null (no single nearest target).
+ */
+function findNearestDimensionToken(
+  raw: string,
+  tokens: readonly TokenDefinitionFact[]
+): { token: TokenDefinitionFact; suggestedToken: string } | null {
+  const parsed = parseLengthValue(raw);
+  if (!parsed) return null;
+  const rawUnit = parsed.unit ?? "px";
+
+  let best: { token: TokenDefinitionFact; value: number } | null = null;
+  for (const token of tokens) {
+    const tokenLength = parseLengthValue(token.value);
+    if (!tokenLength) continue;
+    const tokenUnit = tokenLength.unit ?? "px";
+    if (tokenUnit !== rawUnit) continue;
+    if (tokenLength.value === parsed.value) continue; // exact handled elsewhere
+    if (tokenLength.value === 0 && parsed.value !== 0) continue; // never snap to 0
+    if (best === null) {
+      best = { token, value: tokenLength.value };
+      continue;
+    }
+    const delta = Math.abs(parsed.value - tokenLength.value);
+    const bestDelta = Math.abs(parsed.value - best.value);
+    // Ties break toward the smaller token value, then first-seen, for stability.
+    if (delta < bestDelta || (delta === bestDelta && tokenLength.value < best.value)) {
+      best = { token, value: tokenLength.value };
+    }
+  }
+
+  if (!best) return null;
+  return {
+    token: best.token,
+    suggestedToken: best.token.name,
+  };
+}
+
+function isRawDimensionValue(raw: string): boolean {
+  if (normalizeDimension(raw) !== null) return true;
+  const parts = raw.trim().split(/\s+/);
+  return (
+    parts.length >= 2 &&
+    parts.length <= 4 &&
+    parts.every((part) => normalizeDimension(part) !== null)
+  );
+}
+
+/**
+ * Canonical match key `${amount}${unit}` (unitless treated as px, for React
+ * inline numerics and `0`). Units are intentionally NOT cross-converted:
+ * matching `1rem` to a `16px` token would assume a 16px root font size we
+ * cannot guarantee, so a unit mismatch never matches. This keeps every emitted
+ * fix value-preserving.
+ */
+function normalizeDimension(value: string): string | null {
+  const parsed = parseLengthValue(value);
+  if (!parsed) return null;
+  return `${parsed.value}${parsed.unit ?? "px"}`;
+}
+
+function tokenVar(token: TokenDefinitionFact): string {
+  if (token.name.startsWith("$")) return token.name;
+  const cssVarName = token.name.startsWith("--")
+    ? token.name
+    : `--${token.name.replace(/\./g, "-")}`;
+  return `var(${cssVarName})`;
+}

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

@@ -0,0 +1,236 @@
+/**
+ * `styles/no-raw-spacing` — fires when a length-bearing CSS declaration or
+ * JSX inline style on a scaled property uses a raw spacing literal instead of
+ * a design token.
+ *
+ * The rule needs both a `style.property.scale` policy (which property is
+ * scaled, and which scale name backs it) and a matching set of `scale_value`
+ * facts (the allowed numbers). If either is missing the rule is silent for
+ * that property.
+ *
+ * Two violation shapes, mirroring `styles/no-raw-color`:
+ *
+ * - **off the scale** — `padding: 13px` on a [0,4,8,12,16] scale. Flagged; the
+ *   suggested fix snaps to the nearest scale value (as the matching token when
+ *   one exists, else the raw grid value). Because snapping *changes* the
+ *   rendered value, the fix is a suggestion (non-deterministic) — never applied
+ *   silently.
+ * - **on the scale but a raw literal that equals a token** — `padding: 16px`
+ *   where `--space-md` is `16px`. Flagged; the fix swaps in `var(--space-md)`.
+ *   This is value-preserving, so it is a deterministic, auto-applicable fix.
+ *   (Only fires when a matching spacing token exists — a pure-grid value with no
+ *   named token, like `0`, stays silent.)
+ *
+ * `padding: var(--space-3)` → silent (token reference). `padding: 1.5rem` on a
+ * px scale → normalized through the configured root font size before matching.
+ */
+
+import type {
+  FactId,
+  FactIndex,
+  ScaleFact,
+  StyleDeclarationFact,
+  UsageComponentFact,
+  UsageInlineStyleFact,
+} from "../facts/index.js";
+
+import { makeFinding } from "./finding.js";
+import {
+  buildSpacingTokenLookup,
+  resolveSpacingValue,
+  type CheckedSpacingValue,
+  type SpacingTokenLookup,
+} from "./spacing-resolution.js";
+import type { Finding } from "./types.js";
+import { indexComponentByNodeId, readUsageNode } from "./utils.js";
+
+export const RULE_ID = "styles/no-raw-spacing";
+export const RULE_VERSION = "1";
+
+export function ruleStylesNoRawSpacing(ix: FactIndex): Finding[] {
+  const findings: Finding[] = [];
+
+  // Token lookups are scale-relative (token values normalize to the scale's
+  // unit), so cache one per scale name to avoid rebuilding per declaration.
+  const lookupCache = new Map<string, SpacingTokenLookup>();
+  const lookupFor = (scale: ScaleFact): SpacingTokenLookup => {
+    let lookup = lookupCache.get(scale.name);
+    if (!lookup) {
+      lookup = buildSpacingTokenLookup(ix.tokens.byCategory("spacing"), scale);
+      lookupCache.set(scale.name, lookup);
+    }
+    return lookup;
+  };
+
+  for (const decl of ix.byKind("style_declaration")) {
+    const finding = checkDeclaration(ix, decl, lookupFor);
+    if (finding) findings.push(finding);
+  }
+
+  const componentByNode = indexComponentByNodeId(ix);
+  for (const inline of ix.byKind("usage_inline_style")) {
+    const finding = checkInlineStyle(ix, inline, componentByNode, lookupFor);
+    if (finding) findings.push(finding);
+  }
+
+  return findings;
+}
+
+/**
+ * Inline style property names arrive camelCase (`marginTop`); the policy keys
+ * spacing scales by CSS property (`margin-top`). Normalize so longhand inline
+ * props resolve their scale the same way the CSS file path does.
+ */
+function cssPropertyName(property: string): string {
+  return property.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+function checkDeclaration(
+  ix: FactIndex,
+  decl: StyleDeclarationFact,
+  lookupFor: (scale: ScaleFact) => SpacingTokenLookup
+): Finding | null {
+  const policy = ix.policy.propertyScale(decl.property);
+  if (!policy) return null;
+  const scale = ix.policy.scale(policy.scale);
+  if (!scale) return null;
+  const allowed = ix.policy.scaleValues(policy.scale).map((v) => v.value);
+  if (allowed.length === 0) return null;
+
+  const checked = resolveSpacingValue({
+    raw: decl.value,
+    allowed,
+    scale,
+    tokens: lookupFor(scale),
+  });
+  if (!checked) return null;
+
+  return makeFinding({
+    ruleId: RULE_ID,
+    ruleVersion: RULE_VERSION,
+    severity: policy.severity,
+    message: spacingMessage(decl.property, decl.value, allowed, scale.unit, checked),
+    location: decl.location,
+    evidence: ix.evidence([decl.id, policy.id, scale.id]),
+    fingerprintIdentity: {
+      source: "style_declaration",
+      file: decl.file,
+      selector: decl.selector,
+      declarationPath: decl.declarationPath,
+      property: decl.property,
+      value: decl.value,
+    },
+    fix: buildSpacingFix(decl.property, checked),
+    attributes: {
+      property: decl.property,
+      rawValue: decl.value,
+      scale: scale.name,
+      allowed,
+      suggestedValue: checked.suggestedValue,
+      matchedToken: checked.matchedToken,
+      suggestedToken: checked.suggestedToken,
+      reason: checked.reason,
+      normalizedValue: checked.normalizedValue,
+      normalizedUnit: scale.unit,
+      assumedRootFontSizePx: checked.assumedRootFontSizePx,
+      assumedEmBasePx: checked.assumedEmBasePx,
+      source: "css",
+    },
+  });
+}
+
+function checkInlineStyle(
+  ix: FactIndex,
+  inline: UsageInlineStyleFact,
+  componentByNode: Map<FactId, UsageComponentFact>,
+  lookupFor: (scale: ScaleFact) => SpacingTokenLookup
+): Finding | null {
+  const policy = ix.policy.propertyScale(cssPropertyName(inline.property));
+  if (!policy) return null;
+  const scale = ix.policy.scale(policy.scale);
+  if (!scale) return null;
+  const allowed = ix.policy.scaleValues(policy.scale).map((v) => v.value);
+  if (allowed.length === 0) return null;
+
+  if (inline.valueKind === "css-variable") return null;
+
+  const checked = resolveSpacingValue({
+    raw: inline.value,
+    allowed,
+    scale,
+    tokens: lookupFor(scale),
+    bareNumberFix: inline.valueKind === "number",
+  });
+  if (!checked) return null;
+
+  const node = readUsageNode(ix, inline.nodeId);
+  if (!node) return null;
+
+  const componentEvidenceId = componentByNode.get(node.id)?.id;
+  const evidenceIds = componentEvidenceId
+    ? [node.id, componentEvidenceId, inline.id, policy.id, scale.id]
+    : [node.id, inline.id, policy.id, scale.id];
+
+  return makeFinding({
+    ruleId: RULE_ID,
+    ruleVersion: RULE_VERSION,
+    severity: policy.severity,
+    message: spacingMessage(inline.property, inline.value, allowed, scale.unit, checked),
+    location: node.location,
+    evidence: ix.evidence(evidenceIds),
+    fingerprintIdentity: {
+      source: "usage_inline_style",
+      file: node.file,
+      nodePath: node.nodePath,
+      element: node.element,
+      property: inline.property,
+      value: inline.value,
+    },
+    fix: buildSpacingFix(inline.property, checked),
+    attributes: {
+      property: inline.property,
+      rawValue: inline.value,
+      scale: scale.name,
+      allowed,
+      suggestedValue: checked.suggestedValue,
+      matchedToken: checked.matchedToken,
+      suggestedToken: checked.suggestedToken,
+      reason: checked.reason,
+      normalizedValue: checked.normalizedValue,
+      normalizedUnit: scale.unit,
+      assumedRootFontSizePx: checked.assumedRootFontSizePx,
+      assumedEmBasePx: checked.assumedEmBasePx,
+      source: "jsx",
+    },
+  });
+}
+
+function buildSpacingFix(property: string, checked: CheckedSpacingValue) {
+  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,
+  };
+}
+
+function spacingMessage(
+  property: string,
+  value: string,
+  allowed: number[],
+  unit: "px" | "rem",
+  checked: CheckedSpacingValue
+): string {
+  if (checked.reason === "token-equivalent" && checked.matchedToken) {
+    return `\`${property}: ${value}\` is a raw literal that matches token \`${checked.matchedToken}\`. Reference the token instead.`;
+  }
+  const sample = allowed
+    .slice()
+    .sort((a, b) => a - b)
+    .slice(0, 6);
+  const suffix = `${sample.join(unit + ", ")}${unit}`;
+  const ellipsis = allowed.length > sample.length ? ", …" : "";
+  return `\`${property}: ${value}\` is not on the spacing scale. Allowed: ${suffix}${ellipsis}.`;
+}