cursedbelt 3.0.1 → 4.0.0

package/scripts/checkDistExports.ts

@@ -0,0 +1,67 @@
+#!/usr/bin/env bun
+/**
+ * Every `exports` target that points into `dist/` must EXIST in the build that just ran.
+ *
+ * ── Why this is a build step and not a spec ────────────────────────────────────────
+ * A missing target does not throw. Node and tsc walk the conditions in order and take the
+ * first one that matches an ACTIVE condition — but a `types` (or `import`) target whose
+ * file is absent makes the resolver fall through to the next condition, which for this
+ * package is `bun`/`source`/`default`: the raw `.ts`. So an export that stops being built
+ * silently reverts to the exact defect task 172 fixed — a consumer's `tsc` compiling our
+ * source again — and every test in this repo stays green while it happens.
+ *
+ * It has to run inside `build`, against `CURSEDBELT_DIST_DIR`, because `dist/` is the one
+ * thing no spec here may read: `build` runs BESIDE `test` and `e2e` in the verify graph
+ * (`src/verifyGraph.spec.ts` asserts no spec opens `dist/`), so a spec looking at it would
+ * be reading a directory another stage is in the middle of swapping.
+ *
+ * Declarations are checked the same as runtime files on purpose — a `.d.ts` that was not
+ * emitted is not a smaller problem than a `.js` that was not emitted; it is a quieter one.
+ */
+import path from "node:path";
+
+const root = path.resolve(import.meta.dir, "..");
+const outDir = process.env.CURSEDBELT_DIST_DIR || "dist";
+
+const pkg = (await Bun.file(path.join(root, "package.json")).json()) as {
+	exports: Record<string, string | Record<string, string>>;
+};
+
+/** `[subpath, condition, target]` for every export target inside `dist/`. */
+const distTargets: [string, string, string][] = [];
+for (const [subpath, entry] of Object.entries(pkg.exports)) {
+	const conditions = typeof entry === "string" ? { default: entry } : entry;
+	for (const [condition, target] of Object.entries(conditions)) {
+		if (typeof target === "string" && target.startsWith("./dist/")) {
+			distTargets.push([subpath, condition, target]);
+		}
+	}
+}
+
+// A manifest this script cannot read is a manifest it cannot check; passing silently on
+// zero targets would make the whole step decorative.
+if (distTargets.length === 0) {
+	console.error("🔴 no exports target resolves into dist/ — checkDistExports is checking nothing.");
+	process.exit(1);
+}
+
+const missing: string[] = [];
+for (const [subpath, condition, target] of distTargets) {
+	// `./dist/react/index.js` → `<outDir>/react/index.js`, so a staged build (dist.next)
+	// is checked where it actually is rather than where it will be after the swap.
+	const staged = path.join(root, outDir, target.slice("./dist/".length));
+	if (!(await Bun.file(staged).exists())) {
+		missing.push(`${subpath} [${condition}] → ${target}   (not emitted at ${outDir}/${target.slice(7)})`);
+	}
+}
+
+if (missing.length > 0) {
+	console.error(
+		`\n🔴 the build did not emit ${missing.length} file(s) package.json exports promise:\n  ${missing.join("\n  ")}\n\n` +
+			"A consumer does not get an error for these — the resolver falls through to the next\n" +
+			"condition, which is our raw `.ts`, and the consumer's tsc compiles our source instead.\n",
+	);
+	process.exit(1);
+}
+
+console.log(`✅ all ${distTargets.length} dist export target(s) present in ${outDir}`);

package/scripts/cssRules.ts

@@ -0,0 +1,125 @@
+/**
+ * Compare two compiled stylesheets by the RULES they emit, not by their bytes.
+ *
+ * Every split this package has made to its CSS — `styles-static.css`,
+ * `styles-utilities.css`, and now `styles-areas/*.css` — can fail in exactly one
+ * way that matters: the new route emits FEWER rules than the old one, so some
+ * component renders unstyled in the apps that adopted it. That failure is
+ * invisible to `tsc` (it is CSS), to Biome (nothing is wrong with the file), and
+ * to a byte count read in the only direction anybody reads it, because a smaller
+ * stylesheet is what the whole exercise was asked for.
+ *
+ * So the specs compare rule sets. These helpers were written inside
+ * `src/stylesUtilitiesMatches.spec.ts` and live here now because
+ * `src/stylesAreas.spec.ts` needs the same comparison against the same two
+ * normalisations — a second copy of a CSS flattener is a second copy that can
+ * drift from the assertions relying on it.
+ */
+
+/**
+ * Flatten a stylesheet into `at-rule ‖ … ‖ selector` → the set of declarations in
+ * that block, merging blocks that repeat (both routes emit `@keyframes spin`
+ * twice; a consumer's browser does not care, and neither should a comparison).
+ *
+ * A hand-rolled walk rather than a CSS parser because the only input is Tailwind's
+ * own output: well-formed, and the one construct that could confuse brace counting
+ * — a `{` inside a string or a comment — is skipped explicitly.
+ */
+export const flatten = (css: string): Map<string, Set<string>> => {
+	const out = new Map<string, Set<string>>();
+	const stack: string[] = [];
+	const open: string[][] = [[]];
+	let buf = '';
+	const push = (raw: string): void => {
+		const decl = raw.trim();
+		if (decl) open[open.length - 1]?.push(decl);
+	};
+	for (let i = 0; i < css.length; i++) {
+		const ch = css[i];
+		if (ch === '/' && css[i + 1] === '*') {
+			i = css.indexOf('*/', i) + 1;
+			continue;
+		}
+		if (ch === '"' || ch === "'") {
+			const end = css.indexOf(ch, i + 1);
+			buf += css.slice(i, end + 1);
+			i = end;
+			continue;
+		}
+		if (ch === '{') {
+			stack.push(buf.trim().replace(/\s+/g, ' '));
+			buf = '';
+			open.push([]);
+			continue;
+		}
+		if (ch === '}') {
+			push(buf);
+			buf = '';
+			const key = stack.join(' ‖ ');
+			const set = out.get(key) ?? new Set<string>();
+			for (const decl of open.pop() ?? []) set.add(decl);
+			out.set(key, set);
+			stack.pop();
+			continue;
+		}
+		// At depth 0 a `;` ends a statement at-rule (`@layer a, b;`, `@import …`),
+		// which carries no declarations and must not stick to the next selector.
+		if (ch === ';') {
+			if (stack.length) push(buf);
+			buf = '';
+			continue;
+		}
+		buf += ch;
+	}
+	return out;
+};
+
+/** `var(--x, <anything>)` → `var(--x)`, so a fallback reads as the same declaration. */
+export const dropFallbacks = (decl: string): string => decl.replace(/var\((\s*--[\w-]+)[^)]*\)/g, 'var($1)');
+
+export const CUSTOM_PROPERTY = /^(--[\w-]+)\s*:/;
+
+/** Every custom property a stylesheet actually reads through `var()`. */
+export const referenced = (css: string): Set<string> => {
+	const out = new Set<string>();
+	for (const m of css.matchAll(/var\(\s*(--[\w-]+)/g)) out.add(m[1] as string);
+	return out;
+};
+
+/** Every custom property a stylesheet declares, including `@property` registrations. */
+export const declared = (css: string): Set<string> => {
+	const out = new Set<string>();
+	for (const m of css.matchAll(/(?:^|[;{\s])(--[\w-]+)\s*:/g)) out.add(m[1] as string);
+	for (const m of css.matchAll(/@property\s+(--[\w-]+)/g)) out.add(m[1] as string);
+	return out;
+};
+
+/**
+ * Rules and declarations `before` emits that `after` does not — the whole point.
+ *
+ * `ignoreProperty` is how a caller excuses the `@theme inline` alias declarations
+ * that one route writes into `:root` and nothing ever reads; everything else is a
+ * real difference.
+ */
+export const lostRules = (
+	before: Map<string, Set<string>>,
+	after: Map<string, Set<string>>,
+	ignoreProperty: (prop: string) => boolean = () => false,
+): { rules: string[]; declarations: string[] } => {
+	const rules: string[] = [];
+	const declarations: string[] = [];
+	for (const [key, decls] of before) {
+		const mine = after.get(key);
+		if (!mine) {
+			rules.push(key);
+			continue;
+		}
+		const theirs = new Set([...mine].map(dropFallbacks));
+		for (const decl of decls) {
+			const prop = CUSTOM_PROPERTY.exec(decl)?.[1];
+			if (prop && ignoreProperty(prop)) continue;
+			if (!theirs.has(dropFallbacks(decl))) declarations.push(`${key} → ${decl}`);
+		}
+	}
+	return { rules, declarations };
+};

package/scripts/fixtureAppCss.ts

@@ -0,0 +1,344 @@
+#!/usr/bin/env bun
+/**
+ * `bun scripts/fixtureAppCss.ts [--prune]` — measure what a consuming app emits,
+ * and refuse to let it grow.
+ *
+ * ## What this exists for
+ *
+ * Three apps shipped the union of this design system before anyone counted it,
+ * then four, then five; the fifth arrived with a 173-line `@source` list that
+ * could not have worked and a 494 kB entry chunk. Every one of those numbers was
+ * measured from the CONSUMER side, in a repo that cannot change the thing causing
+ * it, and none of them was measured twice — so nothing here could tell whether the
+ * cost was going up or down.
+ *
+ * 🔴 The check has to live in the package, and it may not reach into `apps/*`:
+ * this generation's third rule is that a repo's gate proves that repo. So the
+ * package keeps its own consumer — `demo/fixtures/lean-app`, a small releases
+ * console built out of cursedbelt's public subpaths — compiles its stylesheet the
+ * way an app's bundler will, and records the byte count here.
+ *
+ * ## The two routes, and why both are compiled every run
+ *
+ *   UNION — `styles-static.css` + `styles-utilities.css`, which is what every app
+ *           ships today and what `@import "cursedbelt/styles.css"` is equivalent
+ *           to (measured at 54 bytes' difference; see generateUtilityStyles.ts).
+ *   AREAS — `styles-static.css` + the areas `demo/fixtures/lean-app/app.css`
+ *           declares, and no `@source` into this package at all.
+ *
+ * Both, not just the second, because a ratchet on one number cannot tell a real
+ * saving from a design system that shrank. The RATIO is the claim; the absolute
+ * area number is the ratchet.
+ *
+ * ## The ratchet
+ *
+ * `fixtureAppCss.baseline` records both counts. `--prune` lowers them and REFUSES
+ * to raise, the same bargain `publicSurface.baseline` makes: a real increase — a
+ * new primitive in `core`, a component the fixture started rendering — is a hand
+ * edit in a commit that says why, which is a reviewable moment rather than a
+ * number that drifts. `src/fixtureAppCss.spec.ts` is what runs it in the gate, and
+ * it asserts the "not unstyled" half too: a stylesheet can always be made smaller
+ * by emitting less than the app needs.
+ */
+import { Scanner } from '@tailwindcss/oxide';
+import { REPO_ROOT } from './generateStaticStyles';
+import { compileStylesheet } from './generateUtilityStyles';
+import { AREAS, CORE, REACT_DIR, areaClosures, buildGraph, transitiveNeeds } from './styleAreas';
+
+/** The named fixture app. One, deliberately: a second one is a second thing to keep honest. */
+export const FIXTURE = 'demo/fixtures/lean-app';
+export const FIXTURE_DIR = `${REPO_ROOT}/${FIXTURE}`;
+export const FIXTURE_CSS = `${FIXTURE_DIR}/app.css`;
+export const BASELINE = `${REPO_ROOT}/fixtureAppCss.baseline`;
+
+/** `@import "cursedbelt/styles-areas/<area>.css";` — the fixture's one knob. */
+const AREA_IMPORT = /@import\s+"cursedbelt\/styles-areas\/([a-z0-9-]+)\.css"/g;
+
+/** Areas the fixture's stylesheet declares, in the order it imports them. */
+export const declaredAreas = async (): Promise<string[]> => {
+	const css = await Bun.file(FIXTURE_CSS).text();
+	return [...css.matchAll(AREA_IMPORT)].map((m) => m[1] as string);
+};
+
+/** `from 'cursedbelt/<subpath>'` in the fixture's TSX, with the names it took. */
+export interface FixtureImport {
+	/** The export subpath, `.`-prefixed as `package.json` spells it (`./react/charts`). */
+	readonly subpath: string;
+	/** Named bindings, for a barrel import. Empty for a deep subpath. */
+	readonly names: string[];
+	readonly file: string;
+}
+
+const IMPORT_BLOCK = /import\s+(?:type\s+)?(?:\{([^}]*)\}|[\w*\s,]+)\s*from\s*'(cursedbelt(?:\/[^']*)?)'/g;
+
+export const fixtureImports = async (): Promise<FixtureImport[]> => {
+	const out: FixtureImport[] = [];
+	for (const rel of new Bun.Glob('**/*.tsx').scanSync({ cwd: FIXTURE_DIR, onlyFiles: true })) {
+		const text = await Bun.file(`${FIXTURE_DIR}/${rel}`).text();
+		for (const match of text.matchAll(IMPORT_BLOCK)) {
+			const names = (match[1] ?? '')
+				.split(',')
+				.map((n) => n.trim().replace(/^type\s+/, ''))
+				// `A as B` exports A; the local alias is the consumer's business.
+				.map((n) => (n.includes(' as ') ? (n.split(/\s+as\s+/)[0] as string) : n))
+				.filter(Boolean);
+			out.push({ subpath: (match[2] as string).replace(/^cursedbelt/, '.'), names, file: `${FIXTURE}/${rel}` });
+		}
+	}
+	return out;
+};
+
+/**
+ * `export { A, type B } from './x'` in the `react` barrel → exported name → module.
+ *
+ * Only the named form, on purpose. A fixture import the barrel re-exports with
+ * `export * from` cannot be attributed to one module by a reader either, and
+ * `resolveFixtureModules` fails naming it rather than guessing — an unattributed
+ * import is exactly the case where an app would silently under-declare its areas.
+ */
+const NAMED_REEXPORT = /export\s+(?:type\s+)?\{([^}]*)\}\s*from\s*'(\.[^']+)'/g;
+
+export const barrelMap = async (): Promise<Map<string, string>> => {
+	const text = await Bun.file(`${REACT_DIR}/index.ts`).text();
+	const out = new Map<string, string>();
+	for (const match of text.matchAll(NAMED_REEXPORT)) {
+		const target = match[2] as string;
+		for (const raw of (match[1] as string).split(',')) {
+			const name = raw.trim().replace(/^type\s+/, '');
+			const exported = name.includes(' as ') ? (name.split(/\s+as\s+/)[1] as string) : name;
+			if (exported) out.set(exported.trim(), target);
+		}
+	}
+	return out;
+};
+
+/** `./react/charts` → `<repo>/src/react/charts/index.ts`, through the export map's `source` condition. */
+const subpathSource = (subpath: string, exportsMap: Record<string, unknown>): string | null => {
+	const entry = exportsMap[subpath];
+	const target = typeof entry === 'string' ? entry : (entry as { source?: string } | undefined)?.source;
+	return typeof target === 'string' ? `${REPO_ROOT}/${target.replace(/^\.\//, '')}` : null;
+};
+
+export interface FixtureResolution {
+	/** Entry modules under `src/react` the fixture's imports land on. */
+	readonly entries: Map<string, FixtureImport>;
+	/** Imports nothing could attribute to a module — always a failure, never a skip. */
+	readonly unresolved: string[];
+}
+
+export const resolveFixtureModules = async (exportsMap: Record<string, unknown>): Promise<FixtureResolution> => {
+	const barrel = await barrelMap();
+	const entries = new Map<string, FixtureImport>();
+	const unresolved: string[] = [];
+	for (const imp of await fixtureImports()) {
+		const source = subpathSource(imp.subpath, exportsMap);
+		if (!source) {
+			unresolved.push(`${imp.file}: cursedbelt${imp.subpath.slice(1)} is not an export subpath`);
+			continue;
+		}
+		// The two barrels re-export the package; attribute each NAME instead, or the
+		// fixture would appear to use every module there is.
+		if (source === `${REACT_DIR}/index.ts`) {
+			for (const name of imp.names) {
+				const target = barrel.get(name);
+				if (!target) {
+					unresolved.push(
+						`${imp.file}: \`${name}\` is not re-exported by name from src/react/index.ts, so no area can be ` +
+							'attributed to it — import it from its own subpath instead',
+					);
+					continue;
+				}
+				const resolved = `${REACT_DIR}/${target.replace(/^\.\//, '')}`;
+				for (const ext of ['.ts', '.tsx', '/index.ts', '/index.tsx']) {
+					if (Bun.file(`${resolved}${ext}`).size > 0) {
+						entries.set(`${resolved}${ext}`, imp);
+						break;
+					}
+				}
+			}
+			continue;
+		}
+		entries.set(source, imp);
+	}
+	return { entries, unresolved };
+};
+
+/** Every module under `src/react` the fixture's imports actually reach. */
+export const fixtureClosure = async (exportsMap: Record<string, unknown>): Promise<{
+	modules: Set<string>;
+	resolution: FixtureResolution;
+}> => {
+	const graph = await buildGraph();
+	const resolution = await resolveFixtureModules(exportsMap);
+	const seen = new Set<string>();
+	const queue = [...resolution.entries.keys()];
+	while (queue.length > 0) {
+		const next = queue.pop() as string;
+		if (seen.has(next)) continue;
+		seen.add(next);
+		for (const dep of graph.get(next) ?? []) queue.push(dep);
+	}
+	return { modules: seen, resolution };
+};
+
+/**
+ * Modules the fixture reaches that no declared area covers.
+ *
+ * 🔴 This, not the byte count, is the assertion that stops the saving being fake.
+ * An app under-declares its areas by adding a component and forgetting the
+ * `@import` — and the symptom is a component with no classes, three repos away,
+ * on a screen nobody opened during review.
+ */
+export const uncoveredModules = async (
+	declared: readonly string[],
+	exportsMap: Record<string, unknown>,
+): Promise<string[]> => {
+	const { closures } = await areaClosures();
+	const covered = new Set<string>();
+	for (const name of [CORE, ...declared]) for (const file of closures.get(name) ?? []) covered.add(file);
+	const { modules } = await fixtureClosure(exportsMap);
+	const owners = (file: string): string[] =>
+		AREAS.filter((a) => closures.get(a.name)?.has(file)).map((a) => a.name);
+	return [...modules]
+		.filter((file) => !covered.has(file))
+		.sort()
+		.map((file) => `${file.replace(`${REPO_ROOT}/`, '')}  — covered by: ${owners(file).join(', ') || 'NO AREA'}`);
+};
+
+/** Declared areas whose `needs` the fixture's stylesheet does not also import. */
+export const missingNeeds = (declared: readonly string[]): string[] => {
+	const have = new Set(declared);
+	return declared
+		.flatMap((name) => transitiveNeeds(name).filter((need) => !have.has(need)).map((need) => `${name} needs ${need}`))
+		.sort();
+};
+
+// ── the two compiles ──────────────────────────────────────────────────────────
+
+/** Everything is resolved against `src/`, the way `styles.css`'s own `@import`s are. */
+const STYLES_BASE = `${REPO_ROOT}/src`;
+
+const buildCss = async (input: string): Promise<string> => {
+	const compiled = await compileStylesheet(input);
+	return compiled.build(new Scanner({ sources: compiled.sources }).scan());
+};
+
+/** The fixture's own classes, whichever route it takes. */
+const HEAD = `@import "tailwindcss" source(none);\n@source "${FIXTURE_DIR}";\n@import "./styles-static.css";\n`;
+const TAIL = '@import "./theme.css";\n';
+
+export const unionRouteCss = (): Promise<string> => buildCss(`${HEAD}@import "./styles-utilities.css";\n${TAIL}`);
+
+export const areaRouteCss = (declared: readonly string[]): Promise<string> =>
+	buildCss(`${HEAD}${declared.map((a) => `@import "./styles-areas/${a}.css";`).join('\n')}\n${TAIL}`);
+
+/**
+ * What the fixture NEEDS: its own classes plus the classes of exactly the
+ * cursedbelt modules it reaches, and nothing else. The area route must be a
+ * superset of this or it is an unstyled app wearing a small byte count.
+ */
+export const requiredCss = async (exportsMap: Record<string, unknown>): Promise<string> => {
+	const { modules } = await fixtureClosure(exportsMap);
+	const compiled = await compileStylesheet(`${HEAD}${TAIL}`);
+	const own = new Scanner({ sources: compiled.sources }).scan();
+	const contents = await Promise.all(
+		[...modules].sort().map(async (file) => ({
+			content: await Bun.file(file).text(),
+			extension: file.slice(file.lastIndexOf('.') + 1),
+		})),
+	);
+	const mine = new Scanner({}).scanFiles(contents);
+	return compiled.build([...new Set([...own, ...mine])].sort());
+};
+
+export { STYLES_BASE };
+
+// ── the baseline ──────────────────────────────────────────────────────────────
+
+export interface Baseline {
+	readonly header: string;
+	readonly counts: Map<string, number>;
+}
+
+export const ROUTES = ['union', 'areas'] as const;
+
+export const parseBaseline = (text: string): Baseline => {
+	const header: string[] = [];
+	const counts = new Map<string, number>();
+	for (const line of text.split('\n')) {
+		if (line.startsWith('#') || line.trim() === '') {
+			if (counts.size === 0) header.push(line);
+			continue;
+		}
+		const [bytes, route] = line.trim().split(/\s+/);
+		if (bytes && route) counts.set(route, Number(bytes));
+	}
+	return { header: header.join('\n'), counts };
+};
+
+export const formatBaseline = (header: string, counts: Map<string, number>): string =>
+	`${header}\n${ROUTES.map((r) => `${String(counts.get(r) ?? 0).padStart(9)}  ${r}`).join('\n')}\n`;
+
+export const readBaseline = async (): Promise<Baseline> => {
+	const file = Bun.file(BASELINE);
+	return (await file.exists()) ? parseBaseline(await file.text()) : { header: '', counts: new Map() };
+};
+
+export interface Measurement {
+	readonly declared: string[];
+	readonly union: number;
+	readonly areas: number;
+}
+
+export const measure = async (): Promise<Measurement> => {
+	const declared = await declaredAreas();
+	const [union, areas] = await Promise.all([unionRouteCss(), areaRouteCss(declared)]);
+	return { declared, union: union.length, areas: areas.length };
+};
+
+if (import.meta.main) {
+	const { declared, union, areas } = await measure();
+	const baseline = await readBaseline();
+	const now = new Map<string, number>([
+		['union', union],
+		['areas', areas],
+	]);
+	const saved = union - areas;
+	console.log(
+		`${FIXTURE} — ${declared.length} areas (${declared.join(', ')})\n` +
+			`  union route  ${union.toLocaleString().padStart(9)} B\n` +
+			`  area route   ${areas.toLocaleString().padStart(9)} B   (−${saved.toLocaleString()} B, ` +
+			`${((saved / union) * 100).toFixed(1)}% smaller)`,
+	);
+	if (process.argv.includes('--prune')) {
+		const next = new Map(baseline.counts);
+		let lowered = 0;
+		for (const route of ROUTES) {
+			const recorded = baseline.counts.get(route);
+			const measured = now.get(route) as number;
+			if (recorded === undefined || measured < recorded) {
+				next.set(route, measured);
+				lowered++;
+			}
+		}
+		if (lowered === 0) {
+			console.log('\nnothing to prune — the baseline already records the smaller number.');
+			process.exit(0);
+		}
+		await Bun.write(BASELINE, formatBaseline(baseline.header, next));
+		console.log(`\n✅ lowered ${lowered} baseline entry/entries in ${BASELINE}.`);
+		process.exit(0);
+	}
+	const grown = ROUTES.filter((r) => (now.get(r) as number) > (baseline.counts.get(r) ?? Number.POSITIVE_INFINITY));
+	if (grown.length > 0) {
+		console.error(
+			`\n❌ the fixture app's CSS GREW:\n` +
+				grown
+					.map((r) => `     ${r}: baseline allows ${baseline.counts.get(r)} B, it emits ${now.get(r)} B now`)
+					.join('\n') +
+				'\n   Raise the number by hand, in a commit that says why — `--prune` only lowers.',
+		);
+		process.exit(1);
+	}
+	process.exit(0);
+}