cursedbelt 5.19.1 → 5.20.0

package/dist/scripts/guardrailsEnforce.d.ts

@@ -15,6 +15,8 @@ interface Rule {
     check: (filePath: string, source: string) => Violation[];
 }
 export declare function walk(dir: string, out?: string[]): string[];
+/** Set the stylesheets this scan resolves against; the belt's `theme.css` is always included. */
+export declare function setThemeCss(appCss: readonly string[]): void;
 export declare function setReimplementedNames(names: readonly string[]): void;
 export declare function setPositionedClasses(compounds: readonly (readonly string[])[]): void;
 export declare function positionedClassesFromCss(css: string): string[][];

package/dist/scripts/guardrailsEnforce.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guardrailsEnforce.d.ts","sourceRoot":"","sources":["../../scripts/guardrailsEnforce.ts"],"names":[],"mappings":";AAmNA,UAAU,SAAS;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB;;;sEAGkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,IAAI;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;CACzD;AAED,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CA6B9D;AA66BD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAEpE;AA4tBD,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,GAAG,IAAI,CAEpF;AAID,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,CAoBhE;AA8CD,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAsBtC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAAuC,CAAC;AAE5F,0EAA0E;AAC1E,eAAO,MAAM,SAAS,EAAE,SAAS,MAAM,EAAwE,CAAC;AAShH,eAAO,MAAM,uBAAuB,aAAkD,CAAC;AAGvF,MAAM,WAAW,SAAS;IACzB,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACb;AAED;2FAC2F;AAC3F,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CA0C3F;AAED,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAmGhC,wBAAgB,0BAA0B,CAAC,SAAS,GAAE,MAAwB,GAAG,MAAM,EAAE,CAyBxF"}
+{"version":3,"file":"guardrailsEnforce.d.ts","sourceRoot":"","sources":["../../scripts/guardrailsEnforce.ts"],"names":[],"mappings":";AAwNA,UAAU,SAAS;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB;;;sEAGkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,IAAI;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;CACzD;AAED,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CA6B9D;AAu5BD,iGAAiG;AACjG,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAE3D;AAmHD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAEpE;AA4tBD,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,GAAG,IAAI,CAEpF;AAID,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,CAoBhE;AA8CD,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAuBtC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAAuC,CAAC;AAE5F,0EAA0E;AAC1E,eAAO,MAAM,SAAS,EAAE,SAAS,MAAM,EAAwE,CAAC;AAShH,eAAO,MAAM,uBAAuB,aAAkD,CAAC;AAGvF,MAAM,WAAW,SAAS;IACzB,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACb;AAED;2FAC2F;AAC3F,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CA0C3F;AAED,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAmGhC,wBAAgB,0BAA0B,CAAC,SAAS,GAAE,MAAwB,GAAG,MAAM,EAAE,CAyBxF"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt",
-	"version": "5.19.1",
+	"version": "5.20.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The React design system of the cursedbelt split — components, styles, theme. cursedbelt-core below it; server tier in cursedbelt-server.",

package/scripts/guardrailsEnforce.spec.ts

@@ -16,6 +16,7 @@ import {
   RULES,
   setPositionedClasses,
   setReimplementedNames,
+  setThemeCss,
   walk,
 } from './guardrailsEnforce';
 
@@ -588,6 +589,57 @@ describe('no-tailwind-palette', () => {
   });
 });
 
+describe('theme-colours-resolve (task 2240)', () => {
+  const REGISTERS_PRIMARY = '@theme inline {\n  --color-primary: var(--primary);\n}\n';
+  afterEach(() => setThemeCss([]));
+
+  test('🔴 a colour the belt DEFINES but nothing registers is flagged — bg-primary drew nothing in flix', () => {
+    setThemeCss([]);
+    const found = check('theme-colours-resolve', '<span className="bg-primary/10 text-primary-foreground" />');
+    expect(found.map((v) => v.snippet.split(' — ')[0])).toEqual(['bg-primary/10', 'text-primary-foreground']);
+  });
+
+  test("the app's own @theme registering it makes it resolve", () => {
+    setThemeCss([REGISTERS_PRIMARY]);
+    expect(check('theme-colours-resolve', '<span className="bg-primary/10 border-primary/60" />')).toHaveLength(0);
+    expect(check('theme-colours-resolve', '<span className="text-primary-foreground" />')).toHaveLength(1);
+  });
+
+  test("an app's own custom property is checked the same way", () => {
+    setThemeCss([':root { --brand: #123456; }\n']);
+    expect(check('theme-colours-resolve', '<b className="text-brand" />')).toHaveLength(1);
+    setThemeCss([':root { --brand: #123456; }\n@theme {\n  --color-brand: var(--brand);\n}\n']);
+    expect(check('theme-colours-resolve', '<b className="text-brand" />')).toHaveLength(0);
+  });
+
+  test("Tailwind's own names, the registered tokens and a CSS file are not its business", () => {
+    setThemeCss([]);
+    expect(check('theme-colours-resolve', '<p className="text-sm border-2 bg-accent/15 text-accent-strong border-border" />')).toHaveLength(0);
+    expect(RULES['theme-colours-resolve'].check('a.css', '.x { border-radius: var(--radius); }')).toHaveLength(0);
+  });
+
+  test('takes the opt-out comment, and a comment is not a class', () => {
+    setThemeCss([]);
+    expect(check('theme-colours-resolve', '// guardrails-ignore theme-colours-resolve: an @apply target\n<i className="bg-primary" />')).toHaveLength(0);
+    expect(check('theme-colours-resolve', '// we used to write bg-primary here\n<i />')).toHaveLength(0);
+  });
+
+  test('🔴 end to end: an app registering the colour OUTSIDE its scanned root still resolves', async () => {
+    const rows = JSON.stringify(Object.fromEntries(APP_RULES.map((name) => [name, 0])));
+    const app = { 'scripts/baseline.json': rows, 'src/Badge.tsx': 'export const B = () => <span className="bg-primary" />;\n' };
+    await withFixture(app, async (dir) => {
+      const { code, report } = await runCli(dir, ['--all-app-rules', '--baseline', 'scripts/baseline.json', 'src']);
+      expect(report).toContain('bg-primary');
+      expect(code).toBe(1);
+    });
+    await withFixture({ ...app, 'styles/globals.css': REGISTERS_PRIMARY }, async (dir) => {
+      const { code, report } = await runCli(dir, ['--all-app-rules', '--baseline', 'scripts/baseline.json', 'src']);
+      expect(report).toContain('✓ theme-colours-resolve: 0 violation(s)');
+      expect(code).toBe(0);
+    });
+  });
+});
+
 describe('no-raw-title-attr', () => {
   test('flags title= on a DOM element', () => {
     expect(check('no-raw-title-attr', '<button title="Delete"><Trash /></button>')).toHaveLength(1);

package/scripts/guardrailsEnforce.ts

@@ -89,6 +89,11 @@
 //     `text-muted-foreground`), arbitrary token values (`bg-[var(--surface-2)]`) and
 //     `white`/`black`/`transparent`/`current` are not matched.
 //
+//   theme-colours-resolve — task 2240: a colour utility (`bg-primary`) must name a colour an
+//     `@theme` REGISTERS (`--color-primary`), not merely a custom property some stylesheet
+//     defines — otherwise Tailwind emits nothing and the element draws no colour. Resolved
+//     against the belt's `theme.css` plus every `.css` in the app package. See its block.
+//
 //   no-raw-title-attr — DESIGN.md §4 ("Help Context Disclosing"): no native `title=""`
 //     on a DOM element. It does not exist on a touch device, waits ~500ms, cannot be
 //     themed, and reads inconsistently to a screen reader. Use cursedbelt's `Tooltip`,
@@ -1116,6 +1121,102 @@ const noTailwindPalette: Rule = makeValueRule(
 	TAILWIND_PALETTE_RE,
 );
 
+// ── theme-colours-resolve (task 2240) ───────────────────────────────────────
+// A colour utility must name a colour Tailwind can GENERATE, not merely a CSS variable that
+// exists. `theme.css` defined `--primary` as an alias but registered no `--color-primary` in
+// its `@theme`, so `bg-primary` compiled to nothing: no error, the class is simply absent from
+// the built CSS. Measured in flix on 2026-09-28 — SearchInput's badge background read
+// `rgba(0, 0, 0, 0)` off Chromium — and four DataTable components carried the same classes.
+// `src/themeColorsResolve.spec.ts` holds the belt's own components to this since 5.19.1; this
+// rule is the same check for an app, whose classes resolve against its own stylesheet too.
+//
+// The rule: a colour prefix (`bg-`, `text-`, `border-`, …) plus a name some stylesheet DEFINES
+// as a custom property (`--primary: …`) must have `--color-<name>` (or `--<prefix>-<name>`)
+// REGISTERED in an `@theme` block. Defined and registered are both read from the belt's
+// `theme.css` plus every `.css` in the app package (`setThemeCss`, from `main()`), because an
+// app's `@theme` need not sit under the roots it scans — binary-server's is `styles/globals.css`.
+// A name no stylesheet defines (`text-sm`, `border-2`, `bg-slate-800`) is Tailwind's own and is
+// another rule's business. `.css` files are not scanned: `border-radius:` and `outline-offset:`
+// are properties, not utilities, and would read as `border-` + a defined `--radius`.
+const THEME_COLOUR_PREFIXES = [
+	"bg", "text", "border", "ring", "outline", "fill", "stroke", "from", "via", "to",
+	"divide", "decoration", "placeholder", "caret", "ring-offset",
+];
+const THEME_COLOUR_CLASS_RE = new RegExp(
+	`(?<![\\w-])(${THEME_COLOUR_PREFIXES.join("|")})-([a-z][a-z0-9-]*?)(?:/\\d+)?(?![\\w/-])`,
+	"g",
+);
+const BELT_THEME_CSS = join(import.meta.dir, "..", "src", "theme.css");
+
+interface ThemeIndex {
+	/** Every `--x` an `@theme` block registers — what Tailwind can make utilities from. */
+	registered: Set<string>;
+	/** Every custom property defined anywhere — the names a utility could be MISTAKEN for. */
+	defined: Set<string>;
+}
+
+/** Index `@theme` registrations and custom-property definitions across stylesheets. */
+function themeIndexFromCss(sources: readonly string[]): ThemeIndex {
+	const registered = new Set<string>();
+	const defined = new Set<string>();
+	for (const raw of sources) {
+		const css = raw.replace(/\/\*[\s\S]*?\*\//g, " ");
+		for (const block of css.matchAll(/@theme[^{]*\{([\s\S]*?)\n\}/g)) {
+			for (const m of (block[1] ?? "").matchAll(/--([a-z0-9-]+)\s*:/g)) registered.add(m[1] ?? "");
+		}
+		for (const m of css.matchAll(/--([a-z0-9-]+)\s*:/g)) defined.add(m[1] ?? "");
+	}
+	return { registered, defined };
+}
+
+/** The belt's own `theme.css` — the index a caller outside `main()` gets by default. */
+function beltThemeCss(): string[] {
+	try {
+		return [readFileSync(BELT_THEME_CSS, "utf8")];
+	} catch {
+		return [];
+	}
+}
+
+let THEME_INDEX: ThemeIndex | undefined;
+/** Set the stylesheets this scan resolves against; the belt's `theme.css` is always included. */
+export function setThemeCss(appCss: readonly string[]): void {
+	THEME_INDEX = themeIndexFromCss([...beltThemeCss(), ...appCss]);
+}
+
+/** The utilities in `source` that name a defined-but-unregistered colour, with their offsets. */
+function unresolvedThemeColours(source: string, index: ThemeIndex): { cls: string; at: number }[] {
+	const out: { cls: string; at: number }[] = [];
+	THEME_COLOUR_CLASS_RE.lastIndex = 0;
+	for (const m of source.matchAll(THEME_COLOUR_CLASS_RE)) {
+		const name = m[2] ?? "";
+		if (!index.defined.has(name)) continue;
+		if (index.registered.has(`color-${name}`) || index.registered.has(`${m[1]}-${name}`)) continue;
+		out.push({ cls: m[0], at: m.index ?? 0 });
+	}
+	return out;
+}
+
+const THEME_COLOURS_IGNORE_RE = /guardrails-ignore\s+theme-colours-resolve\s*:/;
+
+const themeColoursResolve: Rule = {
+	name: "theme-colours-resolve",
+	description:
+		"a colour utility (bg-primary, text-primary-foreground, …) names a CSS variable no @theme registers as --color-<name>, so Tailwind generates NOTHING for it and the element draws no colour. Register `--color-<name>: var(--<name>);` in the app's @theme, or use a colour the theme registers.",
+	check(filePath, source) {
+		if (extname(filePath) === ".css") return [];
+		THEME_INDEX ??= themeIndexFromCss(beltThemeCss());
+		const violations: Violation[] = [];
+		const lines = source.split("\n");
+		for (const { cls, at } of unresolvedThemeColours(blankComments(source), THEME_INDEX)) {
+			const line = lineOf(source, at);
+			if (THEME_COLOURS_IGNORE_RE.test(lines.slice(Math.max(0, line - 3), line).join("\n"))) continue;
+			violations.push({ file: filePath, line, snippet: `${cls} — ${lines[line - 1]?.trim() ?? ""}` });
+		}
+		return violations;
+	},
+};
+
 // ── no-raw-title-attr (DESIGN.md §4 "Help Context Disclosing") ──────────────
 // A native `title=""` is the cheapest possible tooltip and it is four separate
 // failures at once: it does not exist on a touch device (there is no hover), it
@@ -2013,6 +2114,7 @@ export const RULES: Record<string, Rule> = {
 	[noRawZindex.name]: noRawZindex,
 	[noRawDataTable.name]: noRawDataTable,
 	[noTailwindPalette.name]: noTailwindPalette,
+	[themeColoursResolve.name]: themeColoursResolve,
 	[noRawTitleAttr.name]: noRawTitleAttr,
 	[noLocalReimplementation.name]: noLocalReimplementation,
 	[microTypographyFloor.name]: microTypographyFloor,
@@ -2356,6 +2458,10 @@ function main() {
 	const sourcesByFile = new Map<string, string>();
 	for (const file of files) sourcesByFile.set(file, readFileSync(file, "utf8"));
 
+	// `theme-colours-resolve` resolves against every stylesheet in the package, not only the
+	// scanned roots — an app's `@theme` can live beside `src/` (binary-server's `styles/`).
+	setThemeCss(walk(".").filter((file) => extname(file) === ".css").map((file) => readFileSync(file, "utf8")));
+
 	// `no-raw-popover` sees a popup its app's stylesheet positions — see that rule.
 	setPositionedClasses(
 		[...sourcesByFile].filter(([file]) => extname(file) === ".css").flatMap(([, css]) => positionedClassesFromCss(css)),

package/src/themeColorsResolve.spec.ts

@@ -21,29 +21,18 @@
 import { describe, expect, test } from 'bun:test';
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
+import { RULES, setThemeCss } from '../scripts/guardrailsEnforce';
 
 const ROOT = join(import.meta.dir, 'react');
-const THEME = readFileSync(join(import.meta.dir, 'theme.css'), 'utf8');
 
-const themeBlocks = [...THEME.matchAll(/@theme[^{]*\{([\s\S]*?)\n\}/g)].map((m) => m[1] ?? '');
-/** Every `--x` the `@theme` blocks register — what Tailwind can make utilities from. */
-const REGISTERED = new Set(themeBlocks.flatMap((b) => [...b.matchAll(/--([a-z0-9-]+)\s*:/g)].map((m) => m[1] ?? '')));
-/** Every custom property the file defines anywhere — the names a utility could be MISTAKEN for. */
-const DEFINED = new Set([...THEME.matchAll(/--([a-z0-9-]+)\s*:/g)].map((m) => m[1] ?? ''));
-
-const PREFIXES = ['bg', 'text', 'border', 'ring', 'outline', 'fill', 'stroke', 'from', 'via', 'to', 'divide', 'decoration', 'placeholder', 'caret', 'ring-offset'];
-const CLASS = new RegExp(`(?<![\\w-])(${PREFIXES.join('|')})-([a-z][a-z0-9-]*?)(?:/\\d+)?(?![\\w/-])`, 'g');
-
-/** The utilities in `source` that name a defined-but-unregistered colour. */
-export function unresolvedColours(source: string): string[] {
-  const out: string[] = [];
-  for (const m of source.matchAll(CLASS)) {
-    const name = m[2] ?? '';
-    if (!DEFINED.has(name)) continue;
-    const ok = REGISTERED.has(`color-${name}`) || REGISTERED.has(`${m[1]}-${name}`);
-    if (!ok) out.push(m[0]);
-  }
-  return out;
+/**
+ * The utilities in `source` that name a defined-but-unregistered colour. One implementation:
+ * this is the guardrail rule `theme-colours-resolve`, which holds apps to the same check. With
+ * no app stylesheet it resolves against `theme.css` alone — exactly the belt's own situation.
+ */
+function unresolvedColours(source: string): string[] {
+  setThemeCss([]);
+  return RULES['theme-colours-resolve'].check('x.tsx', source).map((v) => v.snippet.split(' — ')[0] ?? '');
 }
 
 function files(dir: string): string[] {
@@ -56,8 +45,6 @@ function files(dir: string): string[] {
 
 describe('every colour utility the belt uses resolves to a registered theme colour', () => {
   test('the check sees the 2026-09-28 shape, and passes the canonical names', () => {
-    expect(REGISTERED.has('color-accent-solid')).toBe(true);
-    expect(DEFINED.has('primary')).toBe(true);
     expect(unresolvedColours("'border-primary/60 bg-primary/10 text-primary-foreground'")).toEqual([
       'border-primary/60',
       'bg-primary/10',