cursedbelt 3.0.1 → 4.0.0

package/scripts/generateAreaStyles.ts

@@ -0,0 +1,253 @@
+#!/usr/bin/env bun
+/**
+ * Generate `src/styles-areas/*.css` — cursedbelt's utilities, PRECOMPILED PER AREA,
+ * so a consuming app pays for the components it renders instead of for the union.
+ *
+ * ── The number this exists to move ──────────────────────────────────────────
+ * `cursedbelt/styles.css` and the `styles-static.css` + `styles-utilities.css`
+ * pair emit the same union — the 135,470 B of `src/styles-utilities.css`,
+ * measured, whichever route an app takes — because `@source` cannot be aimed at
+ * anything finer than a directory and `VirtualList`/`VirtualCardGrid` live at the root of `src/react`.
+ * Five apps ship that union today; the heaviest of them draws a 3D orbit scene, a
+ * map frame, a lightbox and two lazy document viewers, and none of them renders
+ * more than a fraction of the design system.
+ *
+ * `scripts/styleAreas.ts` is the map and owns the WHY. This file is the compiler:
+ * one stylesheet per area, each holding the candidates in that area's import
+ * closure MINUS the ones `core` (and whatever the area declares in `needs`)
+ * already ships, so importing core plus five areas duplicates nothing. A consumer's stylesheet becomes:
+ *
+ *   @import "tailwindcss";
+ *   @import "cursedbelt/styles-static.css";
+ *   @import "cursedbelt/styles-areas/core.css";
+ *   @import "cursedbelt/styles-areas/data-table.css";   ← only what it renders
+ *   @import "cursedbelt/theme.css";
+ *
+ * and it scans nothing of this package's source tree, exactly as the
+ * `styles-utilities.css` route already arranged.
+ *
+ * ── What it is worth, measured on the fixture app ───────────────────────────
+ * `demo/fixtures/lean-app` is a real consumer built out of this package's own
+ * deep subpaths: a releases console with stat tiles, a chart, a sortable table
+ * and a virtualized log. Compiled both ways (tailwindcss 4.3.3, unminified, in
+ * this repo, both counts including the app's own utilities and the theme):
+ *
+ *   styles-static.css + styles-utilities.css        (the union)   169,517 B
+ *   styles-static.css + core + charts + data-table
+ *                     + stats + virtual                           119,432 B   −29.5%
+ *
+ * Of that, the cursedbelt half falls from 142,119 B to 92,034 B — a 35% cut, and
+ * the fixture is not a minimal app: it declares five of the 43 areas. `core`
+ * alone is 66,700 B against the 135,470 B union artifact, so the floor for an app
+ * that renders only primitives is roughly half of what every app ships today.
+ *
+ * 🔴 The saving is bounded by how coarse `core` is, NOT by this mechanism. An area
+ * can be one file — `scripts/styleAreas.ts` scans a file LIST, so nothing here has
+ * a directory's granularity in it — and splitting `core` further is a table edit
+ * with a regenerate, not a redesign.
+ *
+ * `src/fixtureAppCss.spec.ts` is what holds that number down — a baseline that
+ * fails when the emitted CSS for the fixture GROWS, which is the check nothing in
+ * this package had while three, then four, then five apps paid for the union.
+ *
+ * ── The trap, and why nothing here is allowed to be hand-written ────────────
+ * Every failure this mechanism can have is SILENT in the same way the
+ * `styles-utilities.css` split was: a missing area, a stale artifact and a
+ * collapsed scan all produce CSS that is smaller, and smaller is what the whole
+ * exercise was asked for. So the area map is CLOSURE-derived rather than listed
+ * (an area cannot be missing what its own components import),
+ * `coverageFault()` fails on a module no area reaches, and
+ * `src/stylesAreas.spec.ts` proves core-plus-every-area emits the union rule for
+ * rule before any of it is allowed to ship.
+ *
+ * Usage:
+ *   bun run styles:areas            # write src/styles-areas/*.css
+ *   bun run styles:areas --check    # exit 1 if any is stale, write nothing
+ */
+import { REPO_ROOT, STATIC_STYLESHEET, readStylesheets } from './generateStaticStyles';
+import { UTILITY_INPUT, compileStylesheet } from './generateUtilityStyles';
+import {
+	AREA_DIR,
+	AREAS,
+	type Area,
+	CORE,
+	areaClosures,
+	candidatesIn,
+	coverageFault,
+	transitiveNeeds,
+} from './styleAreas';
+
+export { AREA_DIR, AREAS, CORE };
+
+/** The stylesheet an area is written to, relative to the repo root. */
+export const areaFile = (name: string): string => `${AREA_DIR}/${name}.css`;
+
+/** The export subpath a consumer imports it by. */
+export const areaSubpath = (name: string): string => `./${AREA_DIR.replace(/^src\//, '')}/${name}.css`;
+
+/**
+ * A floor on `core`'s scan, for the same reason `generateUtilityStyles.ts` has
+ * one: a collapsed scan compiles and writes an EMPTY stylesheet, and every app
+ * that imported it renders unstyled with nothing red anywhere. 5,170 candidates
+ * today; a tripwire, not a ratchet.
+ */
+export const MIN_CORE_CANDIDATES = 1_000;
+
+const banner = (area: Area, candidates: number, subtracted: boolean): string => {
+	const needs = transitiveNeeds(area.name);
+	const imports = [CORE, ...needs, ...(subtracted ? [area.name] : [])]
+		.filter((n, i, all) => all.indexOf(n) === i)
+		.map((n) => ` *   @import "cursedbelt/styles-areas/${n}.css";`)
+		.join('\n');
+	return `/*
+ * cursedbelt — the \`${area.name}\` area. GENERATED BUILD ARTIFACT. Never hand-edit.
+ *
+ * ${area.why}.
+ *
+ * ${
+		subtracted
+			? `Every Tailwind utility the modules in this area's import closure use, MINUS the\n * ones ${[CORE, ...needs].map((n) => `\`styles-areas/${n}.css\``).join(' and ')} already ship${needs.length > 0 ? '' : 's'}. 🔴 Import ALL of these, in\n * this order — this file alone is incomplete:`
+			: 'Every Tailwind utility the primitives and their plumbing use. Import it first,\n * before any other area:'
+	}
+ *
+ *   @import "tailwindcss";
+ *   @import "cursedbelt/styles-static.css";
+${imports}
+ *   @import "cursedbelt/theme.css";
+ *
+ * An app that imports every area gets exactly what \`cursedbelt/styles-utilities.css\`
+ * emits — proved rule by rule in src/stylesAreas.spec.ts, which is also what fails
+ * when this file is stale. ${candidates} candidate(s) scanned.
+ *
+ * Written by scripts/generateAreaStyles.ts (\`bun run styles:areas\`), which
+ * \`bun run build\` runs. The map of what is in which area, and why the areas are
+ * import closures rather than a hand-written list, is scripts/styleAreas.ts.
+ */
+`;
+};
+
+export interface BuiltArea {
+	readonly name: string;
+	readonly css: string;
+	/** Candidates this stylesheet was compiled from, after core was subtracted. */
+	readonly candidates: string[];
+	/** Every module in the area's closure, repo-relative — what the spec reports on. */
+	readonly modules: string[];
+}
+
+/**
+ * Compile every area.
+ *
+ * Refuses to run against a stale `styles-static.css` for the same reason
+ * `generateUtilityStyles.ts` does: these are compiled against it through
+ * `@reference`, so a stale one bakes in the wrong tokens with nothing to show for
+ * it in the output.
+ */
+export const buildAreaStyles = async (): Promise<BuiltArea[]> => {
+	const { expected, onDisk } = await readStylesheets();
+	if (onDisk !== expected) {
+		throw new Error(
+			`${STATIC_STYLESHEET} is ${onDisk === null ? 'missing' : 'stale'}, and these artifacts are compiled\n` +
+				`against it (\`@reference\`), so they would bake in the wrong tokens. Run:\n` +
+				`  cd ${REPO_ROOT} && bun run styles:static`,
+		);
+	}
+	const { closures } = await areaClosures();
+	const fault = coverageFault(closures);
+	if (fault) throw new Error(fault);
+
+	const coreClosure = closures.get(CORE) as Set<string>;
+	const coreCandidates = await candidatesIn(coreClosure);
+	if (coreCandidates.size < MIN_CORE_CANDIDATES) {
+		throw new Error(
+			`the scan of \`${CORE}\` found ${coreCandidates.size} candidates (floor ${MIN_CORE_CANDIDATES}).\n` +
+				'That is a collapsed scan, not a small core — the stylesheet it would write emits an\n' +
+				'empty utility layer and every consuming app renders UNSTYLED.',
+		);
+	}
+
+	// Every area's raw candidate set first: `needs` subtracts one area from another,
+	// so no area can be compiled until all of them have been scanned.
+	const raw = new Map<string, Set<string>>([[CORE, coreCandidates]]);
+	for (const area of AREAS) {
+		if (area.name === CORE) continue;
+		raw.set(area.name, await candidatesIn(closures.get(area.name) as Set<string>));
+	}
+
+	const built: BuiltArea[] = [];
+	for (const area of AREAS) {
+		const closure = closures.get(area.name) as Set<string>;
+		const needs = transitiveNeeds(area.name);
+		const subtract =
+			area.name === CORE
+				? new Set<string>()
+				: new Set([...coreCandidates, ...needs.flatMap((n) => [...(raw.get(n) as Set<string>)])]);
+		const only = [...(raw.get(area.name) as Set<string>)].filter((c) => !subtract.has(c)).sort();
+		// 🔴 A fresh compile per area. The object `compile()` returns ACCUMULATES the
+		// candidates it has been built with, so reusing one would make every area after
+		// the first a superset of the ones before it — and each file would still look
+		// plausible on its own. Found by measuring; the symptom was areas growing
+		// monotonically in the order they were compiled.
+		const compiled = await compileStylesheet(UTILITY_INPUT);
+		built.push({
+			name: area.name,
+			css: `${banner(area, only.length, area.name !== CORE)}${compiled.build(only)}`,
+			candidates: only,
+			modules: [...closure].map((f) => f.replace(`${REPO_ROOT}/`, '')).sort(),
+		});
+	}
+	return built;
+};
+
+/** What each area's stylesheet should contain, and what is on disk right now. */
+export const readAreaStyles = async (): Promise<Array<BuiltArea & { onDisk: string | null }>> => {
+	const built = await buildAreaStyles();
+	return Promise.all(
+		built.map(async (area) => {
+			const target = Bun.file(`${REPO_ROOT}/${areaFile(area.name)}`);
+			return { ...area, onDisk: (await target.exists()) ? await target.text() : null };
+		}),
+	);
+};
+
+/** Area stylesheets on disk that `AREAS` no longer names — a renamed area leaves one behind. */
+export const strayAreaFiles = (): string[] => {
+	const known = new Set(AREAS.map((a) => `${a.name}.css`));
+	return [...new Bun.Glob('*.css').scanSync({ cwd: `${REPO_ROOT}/${AREA_DIR}`, onlyFiles: true })]
+		.filter((f) => !known.has(f))
+		.sort();
+};
+
+if (import.meta.main) {
+	const areas = await readAreaStyles();
+	const stale = areas.filter((a) => a.onDisk !== a.css);
+	const stray = strayAreaFiles();
+	if (process.argv.includes('--check')) {
+		if (stale.length === 0 && stray.length === 0) {
+			console.log(`✅ ${AREA_DIR}/ is current (${areas.length} areas).`);
+			process.exit(0);
+		}
+		console.error(
+			`❌ ${AREA_DIR}/ is out of date:\n` +
+				stale.map((a) => `     ${a.onDisk === null ? 'missing' : 'stale'}  ${areaFile(a.name)}`).join('\n') +
+				stray.map((f) => `\n     no longer an area  ${AREA_DIR}/${f}`).join('') +
+				`\n   Run:\n     cd ${REPO_ROOT} && bun run styles:areas`,
+		);
+		process.exit(1);
+	}
+	for (const area of stale) await Bun.write(`${REPO_ROOT}/${areaFile(area.name)}`, area.css);
+	const total = areas.reduce((sum, a) => sum + a.css.length, 0);
+	console.log(
+		stale.length === 0
+			? `✅ ${AREA_DIR}/ already current — ${areas.length} areas, ${total.toLocaleString()} B in total.`
+			: `✅ wrote ${stale.length} of ${areas.length} area stylesheet(s) into ${AREA_DIR}/ ` +
+					`(${total.toLocaleString()} B in total; core is ${areas[0]?.css.length.toLocaleString()} B).`,
+	);
+	if (stray.length > 0) {
+		console.error(
+			`\n❌ ${AREA_DIR}/ still holds ${stray.length} stylesheet(s) no area names — delete them:\n  ` +
+				stray.map((f) => `${REPO_ROOT}/${AREA_DIR}/${f}`).join('\n  '),
+		);
+		process.exit(1);
+	}
+}

package/scripts/guardrailsEnforce.spec.ts

@@ -45,6 +45,68 @@ describe('no-raw-action-button', () => {
   });
 });
 
+// Filed 2026-09-15 after three false positives in three repos, all one defect: the tag
+// walker stopped at the first `>` it saw, including one written in the PROSE of a comment
+// inside the attribute list — which made every attribute below that point invisible, opt-out
+// comment included. The third sighting was the fix for the second: a comment explaining this
+// bug, containing a literal `>`, reproduced it.
+describe('opening-tag extraction (comment-aware)', () => {
+  test('a prose "<select>" in a comment does not hide the opt-out below it', () => {
+    const source = `<button
+      // A radio-like list rather than a <select>, so the row is the control.
+      // guardrails-ignore no-raw-action-button: presentational row in a radio-like list
+      type="button"
+    >Move here</button>`;
+    expect(check('no-raw-action-button', source)).toHaveLength(0);
+  });
+
+  test('a prose angle bracket does not hide a role="radio" below it', () => {
+    const source = `<button
+      /* A radio-like list rather than a <select>. */
+      role="radio"
+      aria-checked={selected}
+    >Move here</button>`;
+    expect(check('no-raw-action-button', source)).toHaveLength(0);
+  });
+
+  test('an arrow-function attribute still does not end the tag', () => {
+    const source = `<button
+      onClick={() => setOpen(true)}
+      // guardrails-ignore no-raw-action-button: virtual gamepad key, a real button for AT
+      type="button"
+    >A</button>`;
+    expect(check('no-raw-action-button', source)).toHaveLength(0);
+    // …and the walker still finds the end of that tag, rather than running on.
+    expect(check('no-raw-action-button', '<button onClick={() => save()}>Save</button>')).toHaveLength(1);
+  });
+
+  test('a "//" inside an attribute string is a URL, not a comment', () => {
+    const source = '<button data-href="https://example.com/x">Go</button><button role="tab">Tab</button>';
+    expect(check('no-raw-action-button', source)).toHaveLength(1);
+  });
+
+  test('a comment does not extend one tag over the NEXT element\'s ignore', () => {
+    const source = `<button
+      // A radio-like list rather than a <select>.
+      type="button"
+    >One</button>
+    <button
+      // guardrails-ignore no-raw-action-button: presentational row
+      type="button"
+    >Two</button>`;
+    expect(check('no-raw-action-button', source)).toHaveLength(1);
+  });
+
+  test('the same defect on <input>: prose above the opt-out', () => {
+    const source = `<input
+      // A raw input rather than a <select>-backed Field — the native file picker.
+      // guardrails-ignore no-raw-inputs: native file picker, no Field equivalent
+      type="file"
+    />`;
+    expect(check('no-raw-inputs', source)).toHaveLength(0);
+  });
+});
+
 describe('no-raw-overflow', () => {
   test('flags inline style overflow: auto', () => {
     expect(check('no-raw-overflow', '<div style={{ overflow: "auto" }} />')).toHaveLength(1);

package/scripts/guardrailsEnforce.ts

@@ -147,7 +147,7 @@
 // run, so these stay few and visible. A malformed/unrecognized-category directive is
 // ignored (its violations still fire) and a warning is printed.
 
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { type Dirent, existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, extname, join, relative } from "node:path";
 
 const IGNORE_DIR_NAMES = new Set(["node_modules", "dist", "dist-deploy", ".git", "build", "coverage"]);
@@ -179,7 +179,15 @@ interface Rule {
 }
 
 export function walk(dir: string, out: string[] = []): string[] {
-	let entries: ReturnType<typeof readdirSync>;
+	// 🔴 `Dirent[]`, never `ReturnType<typeof readdirSync>`. `readdirSync` is OVERLOADED, and
+	// `ReturnType` of an overloaded function is the LAST overload — which @types/node 24 made
+	// `Dirent<NonSharedBuffer>[]` when `Dirent` became generic, while the call below returns
+	// the string-encoding overload's `Dirent<string>[]`. The annotation was always a guess at
+	// an overload set somebody else maintains; a release reordered it and the guess became
+	// five compile errors that every consumer of `cursedbelt/guardrails` inherited (task 172).
+	// Bare `Dirent` is `Dirent<string>` under >=24's default type argument and is the plain
+	// non-generic class before that, so this spelling is correct on both.
+	let entries: Dirent[];
 	try {
 		entries = readdirSync(dir, { withFileTypes: true });
 	} catch {
@@ -201,13 +209,69 @@ export function walk(dir: string, out: string[] = []): string[] {
 	return out;
 }
 
+/** Index just past the string/template literal opening at `start`. Quoted attribute values
+ *  are skipped so a `//` inside one reads as the URL it is (`src="https://…"`) rather than
+ *  as the start of a comment. `'`/`"` stop at a newline — an unterminated quote must not
+ *  swallow the rest of the file; a backtick may span lines and nests `${…}`. */
+function skipQuoted(source: string, start: number): number {
+	const quote = source[start];
+	let i = start + 1;
+	if (quote !== "`") {
+		while (i < source.length && source[i] !== quote && source[i] !== "\n") {
+			i += source[i] === "\\" ? 2 : 1;
+		}
+		return Math.min(i + 1, source.length);
+	}
+	let depth = 0;
+	while (i < source.length) {
+		if (source[i] === "\\") {
+			i += 2;
+			continue;
+		}
+		if (depth === 0 && source[i] === "`") return i + 1;
+		if (source.slice(i, i + 2) === "${") {
+			depth++;
+			i += 2;
+			continue;
+		}
+		if (depth > 0 && source[i] === "}") depth--;
+		i++;
+	}
+	return i;
+}
+
 /** Slice from a `<button` (or similar) match to the end of its opening tag, tolerating
- *  `{...}` JS expressions in attribute values that may themselves contain `>`. */
+ *  `{...}` JS expressions in attribute values that may themselves contain `>`
+ *  (`onClick={() => …}`, which works because that `>` sits inside braces).
+ *
+ *  JSX permits line and block comments INSIDE an attribute list, and a comment is prose —
+ *  so it may contain an angle bracket ("a radio-like list rather than a `<select>`").
+ *  Those are skipped the same way `blankComments` skips them, because a `>` written in prose
+ *  used to end the tag here and make every attribute below it invisible — the
+ *  `guardrails-ignore` opt-out included. `blankComments` cannot simply be run first: the
+ *  opt-out checks read this slice and must see the ORIGINAL comment text (see the
+ *  no-raw-action-button check below), so the skip only suppresses TERMINATION; the comment
+ *  stays in what is returned. */
 function extractOpeningTag(source: string, startIndex: number): string {
 	let i = startIndex;
 	let braceDepth = 0;
 	while (i < source.length) {
+		const two = source.slice(i, i + 2);
+		if (two === "//") {
+			const end = source.indexOf("\n", i);
+			i = end === -1 ? source.length : end;
+			continue;
+		}
+		if (two === "/*") {
+			const end = source.indexOf("*/", i + 2);
+			i = end === -1 ? source.length : end + 2;
+			continue;
+		}
 		const ch = source[i];
+		if (ch === '"' || ch === "'" || ch === "`") {
+			i = skipQuoted(source, i);
+			continue;
+		}
 		if (ch === "{") braceDepth++;
 		else if (ch === "}") braceDepth--;
 		else if (ch === ">" && braceDepth <= 0) {