@usefragments/core 1.0.0

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

@@ -0,0 +1,82 @@
+/**
+ * `tailwind/raw-color-via-token` — flags Tailwind color tokens that resolve
+ * to literal colors when policy requires named palette families.
+ */
+
+import type { FactIndex } from "../facts/index.js";
+
+import { makeFinding } from "./finding.js";
+import type { Finding } from "./types.js";
+import {
+  indexResolvedTailwindTokens,
+  matchPattern,
+  resolvedForClass,
+  TAILWIND_COLOR_UTILITIES,
+  UNIVERSAL_TAILWIND_COLOR_TOKENS,
+} from "./tailwind-rule-utils.js";
+import { detectRawColor, readUsageNode } from "./utils.js";
+
+export const RULE_ID = "tailwind/raw-color-via-token";
+export const RULE_VERSION = "1";
+
+export function ruleTailwindRawColorViaToken(ix: FactIndex): Finding[] {
+  const allow = ix.policy.tailwindPaletteAllow();
+  if (!allow || allow.patterns.length === 0) return [];
+
+  const resolvedByKey = indexResolvedTailwindTokens(ix);
+  const findings: Finding[] = [];
+
+  for (const klass of ix.byKind("tailwind_class")) {
+    if (klass.value.kind !== "token") continue;
+    if (!TAILWIND_COLOR_UTILITIES.has(klass.utility)) continue;
+    if (UNIVERSAL_TAILWIND_COLOR_TOKENS.has(klass.value.token)) continue;
+    if (matchPattern(klass.value.token, allow.patterns)) continue;
+
+    const resolved = resolvedForClass(resolvedByKey, klass);
+    if (!resolved || resolved.resolved.kind !== "color") continue;
+    if (resolved.resolved.source === "theme-css") continue;
+
+    const color = detectRawColor(resolved.resolved.value);
+    if (!color) continue;
+
+    const node = readUsageNode(ix, klass.nodeId);
+    const evidenceIds = node
+      ? [node.id, klass.id, resolved.id, allow.id]
+      : [klass.id, resolved.id, allow.id];
+
+    findings.push(
+      makeFinding({
+        ruleId: RULE_ID,
+        ruleVersion: RULE_VERSION,
+        severity: allow.severity,
+        message: `\`${klass.raw}\` resolves to raw color \`${color}\` (${sourceLabel(resolved.resolved.source)}). Project policy requires \`${allow.patterns.join("`, `")}\` palette tokens.`,
+        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: color,
+        },
+        attributes: {
+          rawClass: klass.raw,
+          utility: klass.utility,
+          token: klass.value.token,
+          resolvedValue: color,
+          source: resolved.resolved.source,
+          allowedPatterns: allow.patterns,
+        },
+      })
+    );
+  }
+
+  return findings;
+}
+
+function sourceLabel(source: "theme-css" | "default"): string {
+  return source === "default" ? "Tailwind default" : source;
+}

package/src/rules/tailwind-rule-utils.ts

@@ -0,0 +1,106 @@
+import type { FactIndex, TailwindClassFact, TailwindTokenResolvedFact } from "../facts/index.js";
+
+export const TAILWIND_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",
+]);
+
+/**
+ * Tailwind color *keywords* that are not palette families and carry no
+ * satisfiable "use a named family" remedy. `bg-white`, `text-black`,
+ * `border-transparent`, `ring-current`, `divide-inherit` are stock utilities a
+ * project ships with regardless of its configured palette, so the palette
+ * allow/deny policy must never flag them (doing so produces an unfixable
+ * warning and double-reports against `raw-color-via-token`).
+ */
+export const UNIVERSAL_TAILWIND_COLOR_TOKENS = new Set([
+  "white",
+  "black",
+  "transparent",
+  "current",
+  "inherit",
+  "none",
+]);
+
+export const TAILWIND_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 indexResolvedTailwindTokens(
+  ix: FactIndex
+): Map<string, TailwindTokenResolvedFact> {
+  const out = new Map<string, TailwindTokenResolvedFact>();
+  for (const fact of ix.byKind("tailwind_token_resolved")) {
+    out.set(resolvedKey(fact.utility, fact.token), fact);
+  }
+  return out;
+}
+
+export function resolvedForClass(
+  resolvedByKey: ReadonlyMap<string, TailwindTokenResolvedFact>,
+  klass: TailwindClassFact
+): TailwindTokenResolvedFact | undefined {
+  if (klass.value.kind !== "token") return undefined;
+  return resolvedByKey.get(resolvedKey(klass.utility, klass.value.token));
+}
+
+export function resolvedKey(utility: string, token: string): string {
+  return `${utility}\0${token}`;
+}
+
+export function matchPattern(value: string, patterns: readonly string[]): string | null {
+  for (const pattern of patterns) {
+    if (matchesTokenGlob(value, pattern)) return pattern;
+  }
+  return null;
+}
+
+function matchesTokenGlob(value: string, pattern: string): boolean {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  return new RegExp(`^${escaped}$`).test(value);
+}

package/src/rules/tailwind-unknown-class.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  compileGlobalGovernanceFacts,
+  FactIndex,
+  makeTailwindClassFact,
+  makeTailwindTokenResolvedFact,
+  makeUsageNodeFact,
+  ruleTailwindUnknownClass,
+  runRules,
+} from "../index.js";
+
+const FILE = "src/app.tsx";
+const LOC = { file: FILE, line: 1, column: 7 };
+
+function indexWithStrictMode(enabled = true): FactIndex {
+  const ix = new FactIndex();
+  ix.addMany(
+    compileGlobalGovernanceFacts({
+      rules: enabled ? { "tailwind/unknown-class": true } : {},
+    })
+  );
+  return ix;
+}
+
+function addUnknownResolvedClass(ix: FactIndex): void {
+  const node = makeUsageNodeFact({
+    file: FILE,
+    nodePath: "0",
+    element: "div",
+    location: LOC,
+  });
+  ix.add(node);
+  ix.add(
+    makeTailwindClassFact({
+      file: FILE,
+      nodeId: node.id,
+      raw: "bg-totally-made-up",
+      originPath: "attribute#0/class#0",
+      prefix: null,
+      modifiers: [],
+      important: false,
+      negative: false,
+      utility: "bg",
+      value: { kind: "token", token: "totally-made-up" },
+      location: LOC,
+    })
+  );
+  ix.add(
+    makeTailwindTokenResolvedFact({
+      utility: "bg",
+      token: "totally-made-up",
+      resolved: { kind: "unknown", source: "unknown" },
+    })
+  );
+}
+
+describe("tailwind/unknown-class", () => {
+  it("flags unresolved tokens when strict mode is enabled — ACCEPTANCE §5.31", () => {
+    const ix = indexWithStrictMode(true);
+    addUnknownResolvedClass(ix);
+
+    const findings = ruleTailwindUnknownClass(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({
+      ruleId: "tailwind/unknown-class",
+      severity: "minor",
+      message: "`bg-totally-made-up` did not resolve to any known palette token.",
+      attributes: {
+        utility: "bg",
+        token: "totally-made-up",
+        reason: "resolution-miss",
+      },
+    });
+  });
+
+  it("is silent by default — ACCEPTANCE §5.31", () => {
+    const ix = indexWithStrictMode(false);
+    addUnknownResolvedClass(ix);
+
+    expect(ruleTailwindUnknownClass(ix)).toHaveLength(0);
+  });
+
+  it("flags parser failures separately", () => {
+    const ix = indexWithStrictMode(true);
+    const node = makeUsageNodeFact({
+      file: FILE,
+      nodePath: "0",
+      element: "div",
+      location: LOC,
+    });
+    ix.add(node);
+    ix.add(
+      makeTailwindClassFact({
+        file: FILE,
+        nodeId: node.id,
+        raw: "totally-made-up",
+        originPath: "attribute#0/class#0",
+        prefix: null,
+        modifiers: [],
+        important: false,
+        negative: false,
+        utility: "unknown",
+        value: { kind: "none" },
+        location: LOC,
+      })
+    );
+
+    expect(ruleTailwindUnknownClass(ix)[0]?.attributes).toMatchObject({
+      reason: "parse-failure",
+    });
+  });
+
+  it("does not flag box-shadow size utilities as unresolved colors", () => {
+    const ix = indexWithStrictMode(true);
+    const node = makeUsageNodeFact({
+      file: FILE,
+      nodePath: "0",
+      element: "div",
+      location: LOC,
+    });
+    ix.add(node);
+    // `shadow` is in TAILWIND_COLOR_UTILITIES, but `shadow-lg` is a box-shadow
+    // size, not a color — it must not be reported as a resolution miss.
+    ix.add(
+      makeTailwindClassFact({
+        file: FILE,
+        nodeId: node.id,
+        raw: "shadow-lg",
+        originPath: "attribute#0/class#0",
+        prefix: null,
+        modifiers: [],
+        important: false,
+        negative: false,
+        utility: "shadow",
+        value: { kind: "token", token: "lg" },
+        location: LOC,
+      })
+    );
+    ix.add(
+      makeTailwindTokenResolvedFact({
+        utility: "shadow",
+        token: "lg",
+        resolved: { kind: "unknown", source: "unknown" },
+      })
+    );
+
+    expect(ruleTailwindUnknownClass(ix)).toHaveLength(0);
+  });
+
+  it("is registered in runRules but stays policy-gated", () => {
+    const ix = indexWithStrictMode(true);
+    addUnknownResolvedClass(ix);
+
+    expect(runRules(ix).map((f) => f.ruleId)).toContain("tailwind/unknown-class");
+  });
+});

package/src/rules/tailwind-unknown-class.ts

@@ -0,0 +1,121 @@
+/**
+ * `tailwind/unknown-class` — opt-in strict-mode diagnostics for classes that
+ * either fail parser utility recognition or fail token resolution.
+ */
+
+import type { FactIndex } from "../facts/index.js";
+
+import { makeFinding } from "./finding.js";
+import type { Finding } from "./types.js";
+import {
+  indexResolvedTailwindTokens,
+  resolvedForClass,
+  TAILWIND_COLOR_UTILITIES,
+} from "./tailwind-rule-utils.js";
+import { readUsageNode } from "./utils.js";
+
+export const RULE_ID = "tailwind/unknown-class";
+export const RULE_VERSION = "1";
+
+/** Color keywords valid in any palette — never a "did not resolve" miss. */
+const UNIVERSAL_COLOR_KEYWORDS = new Set([
+  "white",
+  "black",
+  "transparent",
+  "current",
+  "currentcolor",
+  "inherit",
+  "none",
+]);
+
+export function ruleTailwindUnknownClass(ix: FactIndex): Finding[] {
+  const policy = ix.policy.tailwindUnknownClassEnabled();
+  if (!policy) return [];
+
+  const resolvedByKey = indexResolvedTailwindTokens(ix);
+  const findings: Finding[] = [];
+
+  for (const klass of ix.byKind("tailwind_class")) {
+    if (klass.utility === "unknown") {
+      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}\` could not be parsed as a known Tailwind utility.`,
+          location: klass.location,
+          evidence: ix.evidence(evidenceIds),
+          fingerprintIdentity: {
+            source: "tailwind_class",
+            file: klass.file,
+            nodeId: klass.nodeId,
+            originPath: klass.originPath,
+            raw: klass.raw,
+            reason: "parse-failure",
+          },
+          attributes: {
+            rawClass: klass.raw,
+            utility: klass.utility,
+            reason: "parse-failure",
+          },
+        })
+      );
+      continue;
+    }
+
+    if (klass.value.kind !== "token") continue;
+
+    // The resolution-miss diagnostic is about PALETTE tokens only. Don't flag
+    // non-color utilities (font-medium, items-center, border-2 width), bare
+    // numeric tokens (sizes/widths, not colors), or universal color keywords
+    // (white/black/transparent) as "did not resolve to a palette token".
+    if (!TAILWIND_COLOR_UTILITIES.has(klass.utility)) continue;
+    // `shadow` is dual-purpose: `shadow-{size}` (sm/lg/xl/...) is box-shadow,
+    // not a color. The resolution-miss check can't distinguish a size keyword
+    // from a misspelled color, so it would flag every `shadow-lg`. Skip it —
+    // shadow *color* misuse is rare and not worth the false positives.
+    if (klass.utility === "shadow") continue;
+    const token = klass.value.token;
+    if (/^\d/.test(token)) continue;
+    if (UNIVERSAL_COLOR_KEYWORDS.has(token.toLowerCase())) continue;
+
+    const resolved = resolvedForClass(resolvedByKey, klass);
+    if (!resolved || resolved.resolved.kind !== "unknown") continue;
+
+    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: `\`${klass.raw}\` did not resolve to any known palette token.`,
+        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,
+          reason: "resolution-miss",
+        },
+        attributes: {
+          rawClass: klass.raw,
+          utility: klass.utility,
+          token: klass.value.token,
+          reason: "resolution-miss",
+        },
+      })
+    );
+  }
+
+  return findings;
+}

package/src/rules/taxonomy.test.ts

@@ -0,0 +1,238 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  compareByVocabularyRank,
+  compileGlobalGovernanceFacts,
+  contractTierRuleIds,
+  customerDefaultRuleStates,
+  FactIndex,
+  FRAGMENTS_INTERNAL_RULE_IDS,
+  fragmentsPresetRuleStates,
+  isContractTierRule,
+  makeContractTokenFact,
+  makeStyleCssVarsMustBeDefinedFact,
+  makeStyleDeclarationFact,
+  makeUsageNodeFact,
+  makeUsageTextChildFact,
+  RULE_TIER,
+  RULES,
+  runRules,
+  tierFor,
+} from "../index.js";
+import type { Fact } from "../index.js";
+
+/**
+ * Brief 02 — rule taxonomy. ACCEPTANCE §1–§3.
+ *
+ * The customer default preset enables only Tier A (contract vocabulary), which
+ * is inert until a contract is authored; Tier B (generic hygiene) is off and the
+ * Fragments-internal `tokens/require-dual-fallback` is excluded entirely. The
+ * full `fragments` preset keeps every rule for Fragments' own dogfooding.
+ */
+
+// --- fixtures --------------------------------------------------------------
+
+/** Raw-value declarations — the shape that floods the dashboard today. */
+function rawValueFixture(): Fact[] {
+  const file = "src/Widget.module.scss";
+  return [
+    makeStyleDeclarationFact({
+      file,
+      selector: ".a",
+      declarationPath: "0",
+      property: "color",
+      value: "#3b82f6",
+      location: { file, line: 1, column: 2 },
+    }),
+    makeStyleDeclarationFact({
+      file,
+      selector: ".a",
+      declarationPath: "1",
+      property: "padding",
+      value: "13px",
+      location: { file, line: 2, column: 2 },
+    }),
+    makeStyleDeclarationFact({
+      file,
+      selector: ".a",
+      declarationPath: "2",
+      property: "background",
+      // a CSS token var with no SCSS fallback — the dual-fallback shape
+      value: "var(--fui-surface-secondary)",
+      location: { file, line: 3, column: 2 },
+    }),
+  ];
+}
+
+function index(facts: Fact[]): FactIndex {
+  const ix = new FactIndex();
+  ix.addMany(facts);
+  return ix;
+}
+
+// --- taxonomy SSOT coverage ------------------------------------------------
+
+describe("rule taxonomy SSOT", () => {
+  it("classifies every rule in RULES, with no stray ids", () => {
+    const ruleIds = RULES.map((rule) => rule.id).sort();
+    const tieredIds = Object.keys(RULE_TIER).sort();
+    expect(tieredIds).toEqual(ruleIds);
+  });
+
+  it("treats exactly the two-choice-contract rules as Tier A", () => {
+    expect(contractTierRuleIds().sort()).toEqual([
+      "components/prefer-library",
+      "tokens/css-vars-must-be-defined",
+    ]);
+  });
+
+  it("fails safe to hygiene for unknown rule ids", () => {
+    expect(tierFor("some/unknown-rule")).toBe("hygiene");
+    expect(isContractTierRule("some/unknown-rule")).toBe(false);
+  });
+});
+
+// --- §1 — customer + no contract → zero findings ---------------------------
+
+describe("§1 customer default, no contract", () => {
+  it("produces zero findings over a raw-value fixture (not the flood)", () => {
+    const ix = index([
+      ...compileGlobalGovernanceFacts({ rules: customerDefaultRuleStates() }),
+      ...rawValueFixture(),
+    ]);
+
+    const findings = runRules(ix);
+    expect(findings).toHaveLength(0);
+  });
+
+  it("contrast: the same fixture DOES flood under the full fragments preset", () => {
+    // The customer default's 0 is the taxonomy doing its job, not an empty
+    // fixture: the config-gated dual-fallback rule fires under `fragments` on the
+    // exact same facts, and is precisely what the customer default drops.
+    const fragments = index([
+      ...compileGlobalGovernanceFacts({ rules: fragmentsPresetRuleStates() }),
+      ...rawValueFixture(),
+    ]);
+    expect(runRules(fragments).some((f) => f.ruleId === "tokens/require-dual-fallback")).toBe(true);
+  });
+});
+
+// --- §2 — require-dual-fallback absent from the customer preset ------------
+
+describe("§2 tokens/require-dual-fallback is Fragments-internal", () => {
+  const file = "src/Card.module.scss";
+  const decl = makeStyleDeclarationFact({
+    file,
+    selector: ".c",
+    declarationPath: "0",
+    property: "color",
+    value: "var(--fui-surface-secondary)",
+    location: { file, line: 1, column: 0 },
+  });
+
+  it("is excluded from the customer default entirely", () => {
+    expect(FRAGMENTS_INTERNAL_RULE_IDS.has("tokens/require-dual-fallback")).toBe(true);
+    expect(customerDefaultRuleStates()).not.toHaveProperty("tokens/require-dual-fallback");
+  });
+
+  it("customer preset = 0, fragments preset = 1", () => {
+    const customer = index([
+      ...compileGlobalGovernanceFacts({ rules: customerDefaultRuleStates() }),
+      decl,
+    ]);
+    expect(runRules(customer)).toHaveLength(0);
+
+    const fragments = index([
+      ...compileGlobalGovernanceFacts({ rules: fragmentsPresetRuleStates() }),
+      decl,
+    ]);
+    const fragmentsFindings = runRules(fragments);
+    expect(fragmentsFindings).toHaveLength(1);
+    expect(fragmentsFindings[0].ruleId).toBe("tokens/require-dual-fallback");
+  });
+});
+
+// --- §3 — contract authored → exactly the Tier-A drift, vocabulary-first ---
+
+describe("§3 contract authored", () => {
+  // A contract: canonical Button declared (npm source) + a token source file
+  // declaring --color-accent. An agent writes a raw <button> and references an
+  // off-contract var(--color-brand).
+  function contractIndex(): FactIndex {
+    const file = "src/app.tsx";
+    const scss = "src/app.module.scss";
+    return index([
+      ...compileGlobalGovernanceFacts({
+        rules: customerDefaultRuleStates(),
+        canonicalSources: [{ kind: "npm", specifier: "@acme/ui", include: ["Button"] }],
+      }),
+      // token half of the contract (activation fact + vocabulary)
+      makeStyleCssVarsMustBeDefinedFact({ severity: "warn" }),
+      makeContractTokenFact({ name: "--color-accent" }),
+      // the agent's drift: a raw <button>
+      makeUsageNodeFact({
+        file,
+        nodePath: "0:0",
+        element: "button",
+        interactive: true,
+        location: { file, line: 10, column: 4 },
+      }),
+      // ...and an off-contract token reference (shares the --color- family)
+      makeStyleDeclarationFact({
+        file: scss,
+        selector: ".cta",
+        declarationPath: "0",
+        property: "background",
+        value: "var(--color-brand)",
+        location: { file: scss, line: 3, column: 2 },
+      }),
+      // ...plus a raw hex that Tier B would flag — proves hygiene stays silent
+      makeStyleDeclarationFact({
+        file: scss,
+        selector: ".cta",
+        declarationPath: "1",
+        property: "color",
+        value: "#3b82f6",
+        location: { file: scss, line: 4, column: 2 },
+      }),
+    ]);
+  }
+
+  // the raw <button> needs a child so it is not treated as icon-only
+  function withButtonText(ix: FactIndex): FactIndex {
+    const node = ix.byKind("usage_node").find((n) => n.element === "button");
+    if (node) ix.add(makeUsageTextChildFact({ nodeId: node.id, text: "Save", index: 0 }));
+    return ix;
+  }
+
+  it("yields exactly the two Tier-A findings, no hygiene", () => {
+    const findings = runRules(withButtonText(contractIndex()));
+    const ruleIds = findings.map((f) => f.ruleId);
+
+    expect(new Set(ruleIds)).toEqual(
+      new Set(["components/prefer-library", "tokens/css-vars-must-be-defined"])
+    );
+    expect(findings).toHaveLength(2);
+    // every headline finding is contract vocabulary — no raw-color/hygiene leak
+    expect(ruleIds.every(isContractTierRule)).toBe(true);
+  });
+
+  it("ranks canonical-component bypass first (vocabulary-first), with a directed fix", () => {
+    const findings = runRules(withButtonText(contractIndex()));
+    const ranked = findings.map((f) => f.ruleId).sort(compareByVocabularyRank);
+    expect(ranked).toEqual(["components/prefer-library", "tokens/css-vars-must-be-defined"]);
+
+    const canonical = findings.find((f) => f.ruleId === "components/prefer-library");
+    // "Replace your raw <button> with your <Button>" — a directed, deterministic fix.
+    expect(canonical?.fix).toMatchObject({
+      kind: "replaceComponent",
+      from: "button",
+      to: "Button",
+      deterministic: true,
+    });
+    expect(canonical?.attributes).toMatchObject({
+      rawValue: "button",
+      suggestedComponent: "Button",
+    });
+  });
+});