@usefragments/core 1.0.0

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

@@ -0,0 +1,237 @@
+/**
+ * `styles/no-raw-typography` — fires when a `font-size` declaration or JSX
+ * inline `fontSize` uses a raw length literal instead of a typography token.
+ *
+ * Consumes the `style.fontSize.mustMatchScale` policy (a `style_font_size_scale`
+ * fact) plus a backing scale. Without both it is silent — typography is only
+ * enforced once a project actually has a font-size scale (derived from its
+ * detected typography tokens). This closes the teach-vs-enforce gap where the
+ * agent context advertises typography tokens but nothing flags off-scale text.
+ *
+ * Behaviour mirrors `styles/no-raw-spacing`:
+ * - off the scale (`font-size: 13px` on [12,14,16]) → suggestion, never applied
+ *   silently (snapping changes rendered size);
+ * - on the scale but a raw literal equal to a token (`font-size: 16px` where
+ *   `--font-size-md` is `16px`) → deterministic, value-preserving token swap.
+ */
+
+import type {
+  FactId,
+  FactIndex,
+  ScaleFact,
+  StyleDeclarationFact,
+  TokenDefinitionFact,
+  UsageComponentFact,
+  UsageInlineStyleFact,
+} from "../facts/index.js";
+
+import { makeFinding } from "./finding.js";
+import type { Finding } from "./types.js";
+import {
+  indexComponentByNodeId,
+  isApplicableTokenReference,
+  matchesScale,
+  nearestSignedScaleValue,
+  normalizeLengthForScale,
+  parseLengthValue,
+  readUsageNode,
+  tokenReference,
+} from "./utils.js";
+
+export const RULE_ID = "styles/no-raw-typography";
+export const RULE_VERSION = "1";
+
+const FONT_SIZE_PROPERTIES = new Set(["font-size", "fontsize"]);
+
+export function ruleStylesNoRawTypography(ix: FactIndex): Finding[] {
+  const policy = ix.policy.fontSizeScale();
+  if (!policy) return [];
+  const scale = ix.policy.scale(policy.scale);
+  if (!scale) return [];
+  const allowed = ix.policy.scaleValues(policy.scale).map((v) => v.value);
+  if (allowed.length === 0) return [];
+
+  const tokens = buildTypographyTokenLookup(ix, scale);
+  const findings: Finding[] = [];
+
+  for (const decl of ix.byKind("style_declaration")) {
+    if (decl.property.toLowerCase() !== "font-size") continue;
+    const checked = checkFontSize(decl.value, allowed, scale, tokens);
+    if (!checked) continue;
+    findings.push(
+      makeFinding({
+        ruleId: RULE_ID,
+        ruleVersion: RULE_VERSION,
+        severity: policy.severity,
+        message: typographyMessage(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: buildFix(decl.property, checked),
+        attributes: {
+          property: decl.property,
+          rawValue: decl.value,
+          scale: scale.name,
+          allowed,
+          suggestedValue: checked.suggestedValue,
+          matchedToken: checked.matchedToken,
+          source: "css",
+        },
+      })
+    );
+  }
+
+  const componentByNode = indexComponentByNodeId(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");
+    if (!checked) continue;
+    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, scale.id]
+      : [node.id, inline.id, policy.id, scale.id];
+    findings.push(
+      makeFinding({
+        ruleId: RULE_ID,
+        ruleVersion: RULE_VERSION,
+        severity: policy.severity,
+        message: typographyMessage(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: buildFix(inline.property, checked),
+        attributes: {
+          property: inline.property,
+          rawValue: inline.value,
+          scale: scale.name,
+          allowed,
+          suggestedValue: checked.suggestedValue,
+          matchedToken: checked.matchedToken,
+          source: "jsx",
+        },
+      })
+    );
+  }
+
+  return findings;
+}
+
+function buildTypographyTokenLookup(
+  ix: FactIndex,
+  scale: ScaleFact
+): Map<number, TokenDefinitionFact> {
+  const out = new Map<number, TokenDefinitionFact>();
+  for (const token of ix.tokens.byCategory("typography")) {
+    const parsed = parseLengthValue(token.value);
+    if (!parsed || parsed.unit === null) continue;
+    const normalized = normalizeLengthForScale(parsed, scale);
+    if (normalized === null) continue;
+    const key = Math.abs(normalized.value);
+    if (!out.has(key)) out.set(key, token);
+  }
+  return out;
+}
+
+interface CheckedFontSize {
+  suggestedValue?: string;
+  fixEmittable: boolean;
+  deterministicFix: boolean;
+  reason: "off-scale" | "token-equivalent";
+  matchedToken?: string;
+}
+
+function checkFontSize(
+  raw: string,
+  allowed: number[],
+  scale: ScaleFact,
+  tokens: Map<number, TokenDefinitionFact>,
+  bareNumberFix = false
+): CheckedFontSize | null {
+  const trimmed = raw.trim();
+  if (!trimmed || /var\(|calc\(|clamp\(|min\(|max\(|,|\s/.test(trimmed)) return null;
+  const parsed = parseLengthValue(trimmed);
+  if (!parsed) return null;
+  const normalized = normalizeLengthForScale(parsed, scale);
+  if (normalized === null) return null;
+  const magnitude = Math.abs(normalized.value);
+  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,
+      reason: "token-equivalent",
+      matchedToken: exactToken.name,
+    };
+  }
+
+  const nearest = nearestSignedScaleValue(normalized.value, allowed);
+  if (nearest === null || (nearest === 0 && normalized.value !== 0)) {
+    return { fixEmittable: false, deterministicFix: false, reason: "off-scale" };
+  }
+  const nearestToken = tokens.get(Math.abs(nearest));
+  const suggestedValue = nearestToken
+    ? tokenReference(nearestToken.name)
+    : bareNumberFix
+      ? `${nearest}`
+      : `${nearest}${scale.unit}`;
+  // Off-scale snaps change rendered size → suggestion only; and an assumed
+  // root base makes the px guess unreliable, so attach no fix then.
+  return {
+    suggestedValue,
+    fixEmittable: normalized.deterministicFix,
+    deterministicFix: false,
+    reason: "off-scale",
+  };
+}
+
+function buildFix(property: string, checked: CheckedFontSize) {
+  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 typographyMessage(
+  property: string,
+  value: string,
+  allowed: number[],
+  unit: "px" | "rem",
+  checked: CheckedFontSize
+): 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 typography scale. Allowed: ${suffix}${ellipsis}.`;
+}

package/src/rules/tailwind-arbitrary-color.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  compileGlobalGovernanceFacts,
+  FactIndex,
+  g,
+  makeTailwindClassFact,
+  makeUsageNodeFact,
+  ruleTailwindArbitraryColor,
+  runRules,
+} from "../index.js";
+import type { TailwindValue } from "../index.js";
+
+const FILE = "components/card.tsx";
+
+function indexWithColorPolicy(): FactIndex {
+  const ix = new FactIndex();
+  ix.addMany(
+    compileGlobalGovernanceFacts({
+      styles: [
+        g.styles.rawColors().forbid({
+          except: ["transparent", "currentColor"],
+          prefer: "token",
+          severity: "warn",
+        }),
+      ],
+    }),
+  );
+  return ix;
+}
+
+function addClass(ix: FactIndex, input: {
+  raw: string;
+  utility: string;
+  value: TailwindValue;
+}) {
+  const node = makeUsageNodeFact({
+    file: FILE,
+    nodePath: "0:0",
+    element: "div",
+    location: { file: FILE, line: 4, column: 9 },
+  });
+  ix.add(node);
+  ix.add(
+    makeTailwindClassFact({
+      file: FILE,
+      nodeId: node.id,
+      raw: input.raw,
+      originPath: `attribute#0/class#${input.raw}`,
+      prefix: null,
+      modifiers: [],
+      important: false,
+      negative: false,
+      utility: input.utility,
+      value: input.value,
+      location: { file: FILE, line: 4, column: 18 },
+    }),
+  );
+}
+
+describe("tailwind/arbitrary-color", () => {
+  it("flags arbitrary hex colors — ACCEPTANCE §3.19", () => {
+    const ix = indexWithColorPolicy();
+    addClass(ix, {
+      raw: "bg-[#abc123]",
+      utility: "bg",
+      value: { kind: "arbitrary", raw: "#abc123" },
+    });
+
+    const findings = ruleTailwindArbitraryColor(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({
+      ruleId: "tailwind/arbitrary-color",
+      severity: "moderate",
+      attributes: {
+        rawClass: "bg-[#abc123]",
+        rawValue: "#abc123",
+        color: "#abc123",
+        utility: "bg",
+        source: "tailwind",
+      },
+    });
+    expect(findings[0].location).toMatchObject({ file: FILE, line: 4 });
+  });
+
+  it("flags arbitrary rgb() colors — ACCEPTANCE §3.20", () => {
+    const ix = indexWithColorPolicy();
+    addClass(ix, {
+      raw: "text-[rgb(10,20,30)]",
+      utility: "text",
+      value: { kind: "arbitrary", raw: "rgb(10,20,30)" },
+    });
+
+    const findings = ruleTailwindArbitraryColor(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].attributes).toMatchObject({
+      rawValue: "rgb(10,20,30)",
+      color: "rgb(10,20,30)",
+    });
+  });
+
+  it("does not fire for policy exemptions or non-color utilities", () => {
+    const ix = indexWithColorPolicy();
+    addClass(ix, {
+      raw: "bg-[transparent]",
+      utility: "bg",
+      value: { kind: "arbitrary", raw: "transparent" },
+    });
+    addClass(ix, {
+      raw: "m-[#abc123]",
+      utility: "m",
+      value: { kind: "arbitrary", raw: "#abc123" },
+    });
+
+    expect(ruleTailwindArbitraryColor(ix)).toHaveLength(0);
+  });
+
+  it("is registered in runRules", () => {
+    const ix = indexWithColorPolicy();
+    addClass(ix, {
+      raw: "fill-[#abc123]",
+      utility: "fill",
+      value: { kind: "arbitrary", raw: "#abc123" },
+    });
+
+    expect(runRules(ix).map((f) => f.ruleId)).toContain("tailwind/arbitrary-color");
+  });
+});

package/src/rules/tailwind-arbitrary-color.ts

@@ -0,0 +1,93 @@
+/**
+ * `tailwind/arbitrary-color` — flags color-bearing Tailwind utilities with
+ * arbitrary raw color values, e.g. `bg-[#abc123]` or
+ * `text-[rgb(10,20,30)]`.
+ */
+
+import type { FactIndex, TailwindClassFact } from "../facts/index.js";
+
+import { makeFinding } from "./finding.js";
+import type { Finding } from "./types.js";
+import { detectRawColor, isExemptColor, readUsageNode } from "./utils.js";
+
+export const RULE_ID = "tailwind/arbitrary-color";
+export const RULE_VERSION = "1";
+
+const COLOR_UTILITIES = new Set([
+  "accent",
+  "bg",
+  "border",
+  "border-b",
+  "border-e",
+  "border-l",
+  "border-r",
+  "border-s",
+  "border-t",
+  "border-x",
+  "border-y",
+  "caret",
+  "decoration",
+  "divide",
+  "fill",
+  "from",
+  "outline",
+  "placeholder",
+  "ring",
+  "ring-offset",
+  "shadow",
+  "stroke",
+  "text",
+  "to",
+  "via",
+]);
+
+export function ruleTailwindArbitraryColor(ix: FactIndex): Finding[] {
+  const policy = ix.policy.rawColorPolicy();
+  if (!policy) return [];
+
+  const findings: Finding[] = [];
+  for (const klass of ix.byKind("tailwind_class")) {
+    if (klass.value.kind !== "arbitrary") continue;
+    if (!COLOR_UTILITIES.has(klass.utility)) continue;
+
+    const color = detectRawColor(klass.value.raw);
+    if (!color) continue;
+    if (isExemptColor(color, policy.except)) continue;
+
+    const node = readUsageNode(ix, klass.nodeId);
+    const evidenceIds = node ? [node.id, klass.id, policy.id] : [klass.id, policy.id];
+
+    findings.push(
+      makeFinding({
+        ruleId: RULE_ID,
+        ruleVersion: RULE_VERSION,
+        severity: policy.severity,
+        message: `\`${klass.raw}\` uses arbitrary raw color ${color}. Use a ${policy.prefer === "token" ? "design token" : "CSS variable"} instead.`,
+        location: klass.location,
+        evidence: ix.evidence(evidenceIds),
+        fingerprintIdentity: fingerprintIdentity(klass, color),
+        attributes: {
+          rawClass: klass.raw,
+          rawValue: klass.value.raw,
+          color,
+          utility: klass.utility,
+          source: "tailwind",
+        },
+      }),
+    );
+  }
+
+  return findings;
+}
+
+function fingerprintIdentity(klass: TailwindClassFact, color: string): Record<string, unknown> {
+  return {
+    source: "tailwind_class",
+    file: klass.file,
+    nodeId: klass.nodeId,
+    originPath: klass.originPath,
+    raw: klass.raw,
+    utility: klass.utility,
+    value: color,
+  };
+}

package/src/rules/tailwind-arbitrary-spacing.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  compileGlobalGovernanceFacts,
+  FactIndex,
+  g,
+  makeTailwindClassFact,
+  makeUsageNodeFact,
+  ruleTailwindArbitrarySpacing,
+  runRules,
+} from "../index.js";
+import type { TailwindValue } from "../index.js";
+
+const FILE = "components/product/gallery.tsx";
+
+function indexWithSpacingPolicy(values = [0, 4, 8, 16, 32]): FactIndex {
+  const ix = new FactIndex();
+  ix.addMany(
+    compileGlobalGovernanceFacts({
+      scales: {
+        space: g.scale.px(values),
+      },
+      styles: [
+        g.styles.rawSpacing().mustMatchScale("space", {
+          appliesTo: ["margin", "padding", "gap"],
+          severity: "warn",
+        }),
+      ],
+    }),
+  );
+  return ix;
+}
+
+function addClass(ix: FactIndex, input: {
+  raw: string;
+  utility: string;
+  value: TailwindValue;
+  negative?: boolean;
+}) {
+  const node = makeUsageNodeFact({
+    file: FILE,
+    nodePath: "0:0",
+    element: "button",
+    location: { file: FILE, line: 12, column: 6 },
+  });
+  ix.add(node);
+  ix.add(
+    makeTailwindClassFact({
+      file: FILE,
+      nodeId: node.id,
+      raw: input.raw,
+      originPath: `attribute#0/class#${input.raw}`,
+      prefix: null,
+      modifiers: [],
+      important: false,
+      negative: input.negative ?? false,
+      utility: input.utility,
+      value: input.value,
+      location: { file: FILE, line: 12, column: 30 },
+    }),
+  );
+}
+
+describe("tailwind/arbitrary-spacing", () => {
+  it("flags arbitrary percent spacing — ACCEPTANCE §3.18", () => {
+    const ix = indexWithSpacingPolicy();
+    addClass(ix, {
+      raw: "m-[15%]",
+      utility: "m",
+      value: { kind: "arbitrary", raw: "15%" },
+    });
+
+    const findings = ruleTailwindArbitrarySpacing(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({
+      ruleId: "tailwind/arbitrary-spacing",
+      severity: "moderate",
+      message: "`m-[15%]` is an arbitrary spacing value not on the project's spacing scale.",
+      attributes: {
+        rawValue: "15%",
+        utility: "m",
+        property: "margin",
+        scale: "space",
+        source: "tailwind",
+      },
+    });
+    expect(findings[0].fix).toMatchObject({
+      kind: "replaceClassToken",
+      from: "m-[15%]",
+      to: null,
+      deterministic: false,
+    });
+  });
+
+  it("normalizes rem values before checking a px scale — ACCEPTANCE §3.21", () => {
+    const ix = indexWithSpacingPolicy([0, 4, 8, 16, 32]);
+    addClass(ix, {
+      raw: "p-[1rem]",
+      utility: "p",
+      value: { kind: "arbitrary", raw: "1rem" },
+    });
+    addClass(ix, {
+      raw: "p-[1.5rem]",
+      utility: "p",
+      value: { kind: "arbitrary", raw: "1.5rem" },
+    });
+
+    const findings = ruleTailwindArbitrarySpacing(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].attributes).toMatchObject({
+      rawClass: "p-[1.5rem]",
+      rawValue: "1.5rem",
+      normalizedValue: 24,
+      assumedRootFontSizePx: 16,
+    });
+    expect(findings[0].fix).toMatchObject({
+      kind: "replaceClassToken",
+      from: "p-[1.5rem]",
+      to: null,
+      deterministic: false,
+    });
+  });
+
+  it("does not flag positional arbitrary offsets — ACCEPTANCE §3.22", () => {
+    const ix = indexWithSpacingPolicy();
+    addClass(ix, {
+      raw: "top-[-1px]",
+      utility: "top",
+      value: { kind: "arbitrary", raw: "-1px" },
+    });
+
+    expect(ruleTailwindArbitrarySpacing(ix)).toHaveLength(0);
+  });
+
+  it("allows negative values whose magnitude is on the scale", () => {
+    const ix = indexWithSpacingPolicy();
+    addClass(ix, {
+      raw: "-mx-[4px]",
+      utility: "mx",
+      negative: true,
+      value: { kind: "arbitrary", raw: "4px" },
+    });
+
+    expect(ruleTailwindArbitrarySpacing(ix)).toHaveLength(0);
+  });
+
+  it("is registered in runRules", () => {
+    const ix = indexWithSpacingPolicy();
+    addClass(ix, {
+      raw: "gap-[13px]",
+      utility: "gap",
+      value: { kind: "arbitrary", raw: "13px" },
+    });
+
+    expect(runRules(ix).map((f) => f.ruleId)).toContain("tailwind/arbitrary-spacing");
+  });
+});