@usefragments/core 1.0.0

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

@@ -0,0 +1,120 @@
+/**
+ * `tailwind/arbitrary-spacing` — flags arbitrary Tailwind spacing utilities
+ * that cannot be proven to sit on the configured spacing scale.
+ */
+
+import type { FactIndex, TailwindClassFact } from "../facts/index.js";
+
+import { makeFinding } from "./finding.js";
+import type { Finding, FindingReplaceClassTokenFix } from "./types.js";
+import {
+  matchesScale,
+  normalizeLengthForScale,
+  parseLengthValue,
+  readUsageNode,
+} from "./utils.js";
+
+export const RULE_ID = "tailwind/arbitrary-spacing";
+export const RULE_VERSION = "1";
+
+const SPACING_UTILITY_TO_PROPERTY: ReadonlyMap<string, string> = new Map([
+  ["m", "margin"],
+  ["mt", "margin"],
+  ["mr", "margin"],
+  ["mb", "margin"],
+  ["ml", "margin"],
+  ["ms", "margin"],
+  ["me", "margin"],
+  ["mx", "margin"],
+  ["my", "margin"],
+  ["p", "padding"],
+  ["pt", "padding"],
+  ["pr", "padding"],
+  ["pb", "padding"],
+  ["pl", "padding"],
+  ["ps", "padding"],
+  ["pe", "padding"],
+  ["px", "padding"],
+  ["py", "padding"],
+  ["gap", "gap"],
+  ["gap-x", "gap"],
+  ["gap-y", "gap"],
+  ["space-x", "gap"],
+  ["space-y", "gap"],
+] as const);
+
+export function ruleTailwindArbitrarySpacing(ix: FactIndex): Finding[] {
+  const findings: Finding[] = [];
+
+  for (const klass of ix.byKind("tailwind_class")) {
+    if (klass.value.kind !== "arbitrary") continue;
+
+    const property = SPACING_UTILITY_TO_PROPERTY.get(klass.utility);
+    if (!property) continue;
+
+    const policy = ix.policy.propertyScale(property);
+    if (!policy) continue;
+    const scale = ix.policy.scale(policy.scale);
+    if (!scale) continue;
+    const allowed = ix.policy.scaleValues(policy.scale).map((v) => v.value);
+    if (allowed.length === 0) continue;
+
+    const parsed = parseLengthValue(klass.value.raw);
+    const normalized = parsed ? normalizeLengthForScale(parsed, scale) : null;
+    if (normalized && matchesScale(normalized.value, allowed)) continue;
+
+    const node = readUsageNode(ix, klass.nodeId);
+    const evidenceIds = node
+      ? [node.id, klass.id, policy.id, scale.id]
+      : [klass.id, policy.id, scale.id];
+
+    const fix = buildFix(klass);
+
+    findings.push(
+      makeFinding({
+        ruleId: RULE_ID,
+        ruleVersion: RULE_VERSION,
+        severity: policy.severity,
+        message: `\`${klass.raw}\` is an arbitrary spacing value not on the project's spacing scale.`,
+        location: klass.location,
+        evidence: ix.evidence(evidenceIds),
+        fingerprintIdentity: {
+          source: "tailwind_class",
+          file: klass.file,
+          nodeId: klass.nodeId,
+          originPath: klass.originPath,
+          raw: klass.raw,
+          utility: klass.utility,
+          value: klass.value.raw,
+        },
+        fix,
+        attributes: {
+          rawClass: klass.raw,
+          rawValue: klass.value.raw,
+          utility: klass.utility,
+          property,
+          scale: scale.name,
+          allowed,
+          normalizedValue: normalized?.value,
+          normalizedUnit: normalized ? scale.unit : undefined,
+          assumedRootFontSizePx: normalized?.assumedRootFontSizePx,
+          assumedEmBasePx: normalized?.assumedEmBasePx,
+          source: "tailwind",
+        },
+      }),
+    );
+  }
+
+  return findings;
+}
+
+function buildFix(klass: TailwindClassFact): FindingReplaceClassTokenFix {
+  return {
+    kind: "replaceClassToken",
+    title: `Review ${klass.raw}`,
+    from: klass.raw,
+    to: null,
+    utility: klass.utility,
+    deterministic: false,
+  };
+}

package/src/rules/tailwind-forbidden-palette.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  compileGlobalGovernanceFacts,
+  FactIndex,
+  makeTailwindClassFact,
+  makeTailwindTokenResolvedFact,
+  makeUsageNodeFact,
+  ruleTailwindForbiddenPalette,
+  runRules,
+} from "../index.js";
+
+const FILE = "src/app.tsx";
+const LOC = { file: FILE, line: 1, column: 7 };
+
+function indexWithPolicy(): FactIndex {
+  const ix = new FactIndex();
+  ix.addMany(
+    compileGlobalGovernanceFacts({
+      tailwind: {
+        palette: {
+          deny: ["red-*"],
+        },
+      },
+    })
+  );
+  return ix;
+}
+
+function addResolvedClass(
+  ix: FactIndex,
+  raw = "bg-red-500",
+  token = "red-500",
+  source: "default" | "theme-css" = "default"
+): void {
+  const node = makeUsageNodeFact({
+    file: FILE,
+    nodePath: "0",
+    element: "div",
+    location: LOC,
+  });
+  ix.add(node);
+  ix.add(
+    makeTailwindClassFact({
+      file: FILE,
+      nodeId: node.id,
+      raw,
+      originPath: `attribute#0/class#${raw}`,
+      prefix: null,
+      modifiers: [],
+      important: false,
+      negative: false,
+      utility: "bg",
+      value: { kind: "token", token },
+      location: LOC,
+    })
+  );
+  ix.add(
+    makeTailwindTokenResolvedFact({
+      utility: "bg",
+      token,
+      resolved: { kind: "color", value: "#ef4444", source },
+    })
+  );
+}
+
+describe("tailwind/forbidden-palette", () => {
+  it("flags denied palette tokens — ACCEPTANCE §5.28", () => {
+    const ix = indexWithPolicy();
+    addResolvedClass(ix);
+
+    const findings = ruleTailwindForbiddenPalette(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({
+      ruleId: "tailwind/forbidden-palette",
+      severity: "moderate",
+      message:
+        "`bg-red-500` uses the `red-500` palette token, which is forbidden by policy `deny: red-*`.",
+      attributes: {
+        utility: "bg",
+        token: "red-500",
+        matchedPattern: "red-*",
+        source: "default",
+      },
+    });
+  });
+
+  it("is registered in runRules", () => {
+    const ix = indexWithPolicy();
+    addResolvedClass(ix);
+
+    expect(runRules(ix).map((f) => f.ruleId)).toContain("tailwind/forbidden-palette");
+  });
+
+  it("allows project-defined theme tokens even when their names do not match the stock allowlist", () => {
+    const ix = indexWithPolicy();
+    addResolvedClass(ix, "bg-danger", "danger", "theme-css");
+
+    expect(ruleTailwindForbiddenPalette(ix)).toHaveLength(0);
+  });
+
+  it("never flags universal color keywords (bg-white/text-black/border-transparent) — BUG 6", () => {
+    // An allow-list policy that white/black would otherwise violate.
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        tailwind: { palette: { allow: ["brand-*", "neutral-*"] } },
+      })
+    );
+    for (const token of ["white", "black", "transparent", "current"]) {
+      addResolvedClass(ix, `bg-${token}`, token, "default");
+    }
+
+    expect(ruleTailwindForbiddenPalette(ix)).toHaveLength(0);
+  });
+});

package/src/rules/tailwind-forbidden-palette.ts

@@ -0,0 +1,107 @@
+/**
+ * `tailwind/forbidden-palette` — enforces Tailwind palette allow/deny policy
+ * against resolved token-form color utilities.
+ */
+
+import type { FactIndex, TailwindClassFact } from "../facts/index.js";
+
+import { makeFinding } from "./finding.js";
+import type { Finding, FindingReplaceClassTokenFix } from "./types.js";
+import {
+  indexResolvedTailwindTokens,
+  matchPattern,
+  resolvedForClass,
+  TAILWIND_COLOR_UTILITIES,
+  UNIVERSAL_TAILWIND_COLOR_TOKENS,
+} from "./tailwind-rule-utils.js";
+import { readUsageNode } from "./utils.js";
+
+export const RULE_ID = "tailwind/forbidden-palette";
+export const RULE_VERSION = "1";
+
+export function ruleTailwindForbiddenPalette(ix: FactIndex): Finding[] {
+  const deny = ix.policy.tailwindPaletteDeny();
+  const allow = ix.policy.tailwindPaletteAllow();
+  if (!deny && !allow) return [];
+
+  const resolvedByKey = indexResolvedTailwindTokens(ix);
+  const findings: Finding[] = [];
+
+  for (const klass of ix.byKind("tailwind_class")) {
+    if (klass.value.kind !== "token") continue;
+    const token = klass.value.token;
+    if (!TAILWIND_COLOR_UTILITIES.has(klass.utility)) continue;
+    if (UNIVERSAL_TAILWIND_COLOR_TOKENS.has(token)) continue;
+
+    const resolved = resolvedForClass(resolvedByKey, klass);
+    if (!resolved || resolved.resolved.kind !== "color") continue;
+    if (resolved.resolved.source === "theme-css") continue;
+
+    const deniedPattern = deny ? matchPattern(token, deny.patterns) : null;
+    const allowedPattern = allow ? matchPattern(token, allow.patterns) : null;
+    const allowViolation = allow && !allowedPattern;
+    if (!deniedPattern && !allowViolation) continue;
+
+    const policy = deniedPattern ? deny! : allow!;
+    const matchedPattern = deniedPattern ?? allowedPattern ?? null;
+    const node = readUsageNode(ix, klass.nodeId);
+    const evidenceIds = node
+      ? [node.id, klass.id, resolved.id, policy.id]
+      : [klass.id, resolved.id, policy.id];
+
+    findings.push(
+      makeFinding({
+        ruleId: RULE_ID,
+        ruleVersion: RULE_VERSION,
+        severity: policy.severity,
+        message: messageFor(klass, token, deniedPattern, allow?.patterns ?? []),
+        location: klass.location,
+        evidence: ix.evidence(evidenceIds),
+        fingerprintIdentity: {
+          source: "tailwind_class",
+          file: klass.file,
+          nodeId: klass.nodeId,
+          originPath: klass.originPath,
+          raw: klass.raw,
+          utility: klass.utility,
+          token,
+          matchedPattern,
+        },
+        fix: buildFix(klass),
+        attributes: {
+          rawClass: klass.raw,
+          utility: klass.utility,
+          token,
+          matchedPattern,
+          allowedPatterns: allow?.patterns,
+          source: resolved.resolved.source,
+        },
+      })
+    );
+  }
+
+  return findings;
+}
+
+function messageFor(
+  klass: TailwindClassFact,
+  token: string,
+  deniedPattern: string | null,
+  allowedPatterns: readonly string[]
+): string {
+  if (deniedPattern) {
+    return `\`${klass.raw}\` uses the \`${token}\` palette token, which is forbidden by policy \`deny: ${deniedPattern}\`.`;
+  }
+  return `\`${klass.raw}\` uses the \`${token}\` palette token, which is outside the allowed Tailwind palette patterns [${allowedPatterns.join(", ")}].`;
+}
+
+function buildFix(klass: TailwindClassFact): FindingReplaceClassTokenFix {
+  return {
+    kind: "replaceClassToken",
+    title: `Review ${klass.raw}`,
+    from: klass.raw,
+    to: null,
+    utility: klass.utility,
+    deterministic: false,
+  };
+}

package/src/rules/tailwind-off-scale-spacing-token.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  compileGlobalGovernanceFacts,
+  FactIndex,
+  g,
+  makeTailwindClassFact,
+  makeTailwindTokenResolvedFact,
+  makeUsageNodeFact,
+  ruleTailwindOffScaleSpacingToken,
+  runRules,
+} from "../index.js";
+
+const FILE = "src/app.tsx";
+const LOC = { file: FILE, line: 1, column: 7 };
+
+function indexWithScale(): FactIndex {
+  const ix = new FactIndex();
+  ix.addMany(
+    compileGlobalGovernanceFacts({
+      scales: {
+        space: g.scale.px([0, 4, 8, 16, 32]),
+      },
+      styles: [
+        g.styles.rawSpacing().mustMatchScale("space", {
+          appliesTo: ["padding"],
+          severity: "warn",
+        }),
+      ],
+    })
+  );
+  return ix;
+}
+
+function addResolvedSpacing(ix: FactIndex, raw = "p-3", token = "3", value = "0.75rem"): void {
+  const node = makeUsageNodeFact({
+    file: FILE,
+    nodePath: "0",
+    element: "div",
+    location: LOC,
+  });
+  ix.add(node);
+  ix.add(
+    makeTailwindClassFact({
+      file: FILE,
+      nodeId: node.id,
+      raw,
+      originPath: `attribute#0/class#${raw}`,
+      prefix: null,
+      modifiers: [],
+      important: false,
+      negative: false,
+      utility: "p",
+      value: { kind: "token", token },
+      location: LOC,
+    })
+  );
+  ix.add(
+    makeTailwindTokenResolvedFact({
+      utility: "p",
+      token,
+      resolved: { kind: "length", value, source: "theme-css" },
+    })
+  );
+}
+
+describe("tailwind/off-scale-spacing-token", () => {
+  it("flags spacing tokens whose resolved value misses the scale — ACCEPTANCE §5.29", () => {
+    const ix = indexWithScale();
+    addResolvedSpacing(ix);
+
+    const findings = ruleTailwindOffScaleSpacingToken(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({
+      ruleId: "tailwind/off-scale-spacing-token",
+      severity: "moderate",
+      message:
+        "`p-3` resolves to 12px, which is not on the project's spacing scale [0, 4, 8, 16, 32].",
+      attributes: {
+        utility: "p",
+        token: "3",
+        resolvedPx: 12,
+      },
+    });
+  });
+
+  it("allows resolved spacing tokens on the scale", () => {
+    const ix = indexWithScale();
+    addResolvedSpacing(ix, "p-4", "4", "1rem");
+
+    expect(ruleTailwindOffScaleSpacingToken(ix)).toHaveLength(0);
+  });
+
+  it("is registered in runRules", () => {
+    const ix = indexWithScale();
+    addResolvedSpacing(ix);
+
+    expect(runRules(ix).map((f) => f.ruleId)).toContain("tailwind/off-scale-spacing-token");
+  });
+});

package/src/rules/tailwind-off-scale-spacing-token.ts

@@ -0,0 +1,108 @@
+/**
+ * `tailwind/off-scale-spacing-token` — checks resolved Tailwind spacing
+ * tokens against the same project spacing scale used for CSS declarations.
+ */
+
+import type { FactIndex } from "../facts/index.js";
+
+import { makeFinding } from "./finding.js";
+import type { Finding, FindingReplaceClassTokenFix } from "./types.js";
+import {
+  indexResolvedTailwindTokens,
+  resolvedForClass,
+  TAILWIND_SPACING_UTILITY_TO_PROPERTY,
+} from "./tailwind-rule-utils.js";
+import {
+  matchesScale,
+  normalizeLengthForScale,
+  parseLengthValue,
+  readUsageNode,
+} from "./utils.js";
+
+export const RULE_ID = "tailwind/off-scale-spacing-token";
+export const RULE_VERSION = "1";
+
+export function ruleTailwindOffScaleSpacingToken(ix: FactIndex): Finding[] {
+  const resolvedByKey = indexResolvedTailwindTokens(ix);
+  const findings: Finding[] = [];
+
+  for (const klass of ix.byKind("tailwind_class")) {
+    if (klass.value.kind !== "token") continue;
+    const property = TAILWIND_SPACING_UTILITY_TO_PROPERTY.get(klass.utility);
+    if (!property) continue;
+
+    const policy = ix.policy.propertyScale(property);
+    if (!policy) continue;
+    const scale = ix.policy.scale(policy.scale);
+    if (!scale) continue;
+    const allowed = ix.policy.scaleValues(policy.scale).map((v) => v.value);
+    if (allowed.length === 0) continue;
+
+    const resolved = resolvedForClass(resolvedByKey, klass);
+    if (!resolved || resolved.resolved.kind !== "length") continue;
+
+    const parsed = parseLengthValue(resolved.resolved.value);
+    if (!parsed) continue;
+    const normalized = normalizeLengthForScale(parsed, scale);
+    if (!normalized) continue;
+    const signedValue = klass.negative ? -normalized.value : normalized.value;
+    if (matchesScale(signedValue, allowed)) continue;
+
+    const node = readUsageNode(ix, klass.nodeId);
+    const evidenceIds = node
+      ? [node.id, klass.id, resolved.id, policy.id, scale.id]
+      : [klass.id, resolved.id, policy.id, scale.id];
+
+    findings.push(
+      makeFinding({
+        ruleId: RULE_ID,
+        ruleVersion: RULE_VERSION,
+        severity: policy.severity,
+        message: `\`${klass.raw}\` resolves to ${formatResolvedValue(signedValue, scale.unit)}, which is not on the project's spacing scale [${allowed.join(", ")}].`,
+        location: klass.location,
+        evidence: ix.evidence(evidenceIds),
+        fingerprintIdentity: {
+          source: "tailwind_class",
+          file: klass.file,
+          nodeId: klass.nodeId,
+          originPath: klass.originPath,
+          raw: klass.raw,
+          utility: klass.utility,
+          token: klass.value.token,
+          resolvedValue: signedValue,
+          scale: scale.name,
+        },
+        fix: buildFix(klass.raw, klass.utility),
+        attributes: {
+          rawClass: klass.raw,
+          utility: klass.utility,
+          token: klass.value.token,
+          property,
+          scale: scale.name,
+          allowed,
+          resolvedValue: resolved.resolved.value,
+          resolvedPx: scale.unit === "px" ? signedValue : undefined,
+          resolvedUnit: scale.unit,
+          source: resolved.resolved.source,
+        },
+      })
+    );
+  }
+
+  return findings;
+}
+
+function formatResolvedValue(value: number, unit: string): string {
+  return unit === "px" ? `${value}px` : `${value}${unit}`;
+}
+
+function buildFix(raw: string, utility: string): FindingReplaceClassTokenFix {
+  return {
+    kind: "replaceClassToken",
+    title: `Review ${raw}`,
+    from: raw,
+    to: null,
+    utility,
+    deterministic: false,
+  };
+}

package/src/rules/tailwind-raw-color-via-token.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  compileGlobalGovernanceFacts,
+  FactIndex,
+  makeTailwindClassFact,
+  makeTailwindTokenResolvedFact,
+  makeUsageNodeFact,
+  ruleTailwindRawColorViaToken,
+  runRules,
+} from "../index.js";
+
+const FILE = "src/app.tsx";
+const LOC = { file: FILE, line: 1, column: 7 };
+
+function indexWithAllowPolicy(): FactIndex {
+  const ix = new FactIndex();
+  ix.addMany(
+    compileGlobalGovernanceFacts({
+      tailwind: {
+        palette: {
+          allow: ["brand-*"],
+        },
+      },
+    })
+  );
+  return ix;
+}
+
+function addResolvedColor(
+  ix: FactIndex,
+  raw = "bg-red-500",
+  token = "red-500",
+  source: "default" | "theme-css" = "default"
+): void {
+  const node = makeUsageNodeFact({
+    file: FILE,
+    nodePath: "0",
+    element: "div",
+    location: LOC,
+  });
+  ix.add(node);
+  ix.add(
+    makeTailwindClassFact({
+      file: FILE,
+      nodeId: node.id,
+      raw,
+      originPath: `attribute#0/class#${raw}`,
+      prefix: null,
+      modifiers: [],
+      important: false,
+      negative: false,
+      utility: "bg",
+      value: { kind: "token", token },
+      location: LOC,
+    })
+  );
+  ix.add(
+    makeTailwindTokenResolvedFact({
+      utility: "bg",
+      token,
+      resolved: { kind: "color", value: "#ef4444", source },
+    })
+  );
+}
+
+describe("tailwind/raw-color-via-token", () => {
+  it("flags default color tokens outside the allowed palette — ACCEPTANCE §5.30", () => {
+    const ix = indexWithAllowPolicy();
+    addResolvedColor(ix);
+
+    const findings = ruleTailwindRawColorViaToken(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({
+      ruleId: "tailwind/raw-color-via-token",
+      severity: "moderate",
+      message:
+        "`bg-red-500` resolves to raw color `#ef4444` (Tailwind default). Project policy requires `brand-*` palette tokens.",
+      attributes: {
+        utility: "bg",
+        token: "red-500",
+        resolvedValue: "#ef4444",
+        source: "default",
+      },
+    });
+  });
+
+  it("allows tokens matching the palette allow list", () => {
+    const ix = indexWithAllowPolicy();
+    addResolvedColor(ix, "bg-brand-500", "brand-500");
+
+    expect(ruleTailwindRawColorViaToken(ix)).toHaveLength(0);
+  });
+
+  it("allows project-defined theme tokens outside the stock palette names", () => {
+    const ix = indexWithAllowPolicy();
+    addResolvedColor(ix, "bg-danger", "danger", "theme-css");
+
+    expect(ruleTailwindRawColorViaToken(ix)).toHaveLength(0);
+  });
+
+  it("is registered in runRules", () => {
+    const ix = indexWithAllowPolicy();
+    addResolvedColor(ix);
+
+    expect(runRules(ix).map((f) => f.ruleId)).toContain("tailwind/raw-color-via-token");
+  });
+});