cursedbelt 4.5.0 → 4.7.0

package/scripts/publicSurface.ts

@@ -1,458 +0,0 @@
-#!/usr/bin/env bun
-/**
- * `bun scripts/publicSurface.ts [--prune]` — refuse a public surface that grows
- * without a recorded reason.
- *
- * ## What this exists for
- *
- * Measured 2026-09-13 across all 845 consumer files on this machine that mention
- * `cursedbelt`: `1.0.0` published **108 export subpaths and 3,359 exported
- * symbols**, of which every consumer together imported **406 — 12.1%**.
- * `cursedbelt/react` alone exposed 1,037 and 178 were used. Nothing objected at
- * any single step, because no single step was large; the owner's own account of
- * how it got there is *"worked on over many projects with tons of features
- * changing"*.
- *
- * 🔴 **This is NOT a dead-code check, and 12.1% is not a bug to delete.** Most of
- * that surface is alive: the `react` barrel re-exports components that live
- * imports keep mounted, and a design system is SUPPOSED to ship more than any one
- * app has adopted. Deleting everything safely deletable removed 4% of the package
- * (tasks 32/33). What was missing was not restraint, it was an INSTRUMENT — the
- * total was never measured anywhere, so growth was invisible at the only moment
- * anyone could have judged it. This file makes growth visible and deliberate; it
- * does not forbid it.
- *
- * Both rows below are a DATED RECORD, not a live claim — the live number is
- * `publicSurface.baseline`, checked against the tree every run, and it can only
- * go down from the second row:
- *
- *                                subpaths   symbols   dependencies   peers
- *     1.0.0, before tasks 32/33       108     4,167             47      51
- *     seeded 2026-09-13                85     3,808             44      47
- *
- * 🔴 Both rows were measured by THIS file, run against `c01b119` and against the
- * tree it was seeded from, so they are commensurable with each other and with
- * every future run. They are NOT the 3,359 in the task that asked for this file:
- * that number came from an independent walk of the same shape, and this one counts
- * 4,167 for the same tree. The gap is method, not surface — a `default` export,
- * a destructured `export const {a, b}`, and a bare `export * from 'cwip/layout'`
- * are each counted here and were not counted there. Which is the point of the
- * "What it counts, exactly" section below: two numbers that do not say what they
- * counted cannot be compared, and only one of them can be a ratchet.
- *
- * `subpaths` excludes the three stylesheet exports, which have no symbols; the
- * `exports` map has three more keys than the count above. The dependency columns
- * are the second half of the same failure and are asserted by
- * `src/declaredDepsAreImported.spec.ts` — see "The dependency half" below.
- *
- * This file is the reason that second row cannot quietly become the first one
- * again: **document the WHY; automate the WHETHER.** A paragraph in a doc asking
- * the next agent to think about whether a new subpath is needed is the failure
- * mode, not the fix.
- *
- * ## The ratchet
- *
- * `publicSurface.baseline` holds a COUNT PER SUBPATH, the same shape as
- * `tools/check-paths.baseline`, which is the mechanism this generation already
- * trusts. Four ways to fail, and the last two are what make it a ratchet rather
- * than a high-water mark:
- *
- *   1. a subpath in `exports` that the baseline does not list       → NEW SURFACE
- *   2. a listed subpath whose symbol count went UP                  → GREW
- *   3. a listed subpath whose count went DOWN, or that is gone      → run --prune
- *   4. an entry matching no subpath at all                          → run --prune
- *
- * (3) and (4) mean a deleted module cannot leave a stale allowance behind for the
- * next module to grow into. Inherited surface can only fall.
- *
- * `--prune` records the burn-down in one deliberate command and REFUSES to raise
- * anything, so a genuine new export is `--prune`-then-review rather than a number
- * edited by hand, and it shows up in the diff as surface.
- *
- * ## 🔴 What it counts, exactly — and what it does not
- *
- * A count is only worth having if it says what it counted; a count that silently
- * measures less than it claims is a guess wearing a measurement's clothes. This
- * walks, per export subpath in `package.json`, the TypeScript AST of the entry
- * module and every `export * from` beneath it, transitively, deduped by name:
- *
- *   · `export const/let/var/function/class/interface/type/enum/namespace`
- *   · `export { x }`, `export { x as y }`, `export type { x }`
- *   · `export * as ns from './m'`  (one symbol: `ns`)
- *   · `export default` / `export default function Foo` (one symbol: `default`)
- *   · `export * from './m'`        (transitive; cycles are visited once)
- *   · `export * from 'some-package'` — RESOLVED and walked, not skipped. There is
- *     one today (`src/core/layout/index.ts` re-exports `cwip/layout`) and a
- *     package's symbols re-exported under this package's name are this package's
- *     surface. If such a specifier ever resolves to something this cannot parse
- *     (a `.js` build with no types), the run FAILS rather than counting zero.
- *
- * Deliberately NOT counted, each because counting it would make the number lie:
- *
- *   · non-TS export targets — `./styles.css`, `./theme.css`, `./workspace.css`.
- *     A stylesheet has no symbols. They are reported as "asset export(s)" so they
- *     cannot vanish from the accounting.
- *   · anything not reachable from an `exports` subpath. Internal modules are not
- *     public surface. What `src/react/components/**` contains is not the measure;
- *     what the `./react` barrel re-exports is.
- *   · the two `bin` targets, `cc-verify` and `cc-promote`. 🔴 They ARE public
- *     surface — and they are NOT reachable through `exports`, which is exactly why
- *     an earlier reachability walk seeded from `exports` alone reported a shipped
- *     CLI as removable. A CLI's interface is its argv, not its export list, so
- *     counting its exported symbols would measure the wrong thing. Their SHAPE is
- *     already asserted by `src/publishShape.spec.ts` ("declares bin paths npm will
- *     actually keep"), and nothing here concludes anything is dead — this tool
- *     only ever compares `cursedbelt` to its own baseline.
- *
- * ## What this may NOT become
- *
- *   · Not a usage check. It must never try to know who imports `cursedbelt`; that
- *     is cross-repo, and a repo's gate proves that repo.
- *   · Not a ban on growth. New surface is one hand-added line plus a commit
- *     message that says why — a reviewable moment, not a wall.
- *   · Not a second guard. One check, one baseline, entry criteria in this header.
- *
- * ## The dependency half
- *
- * 47 hard dependencies is the number that decides what a consumer pays, and it is
- * surface by the same argument. It is NOT re-checked here, because it is already
- * checked once: `src/declaredDepsAreImported.spec.ts` fails on any `dependencies`
- * or `peerDependencies` entry that no file under `src/` or `scripts/` imports, and
- * `src/noPathDeps.spec.ts` fails on a `file:`/`link:`/`workspace:`/`portal:` range
- * in any dependency block. Two ratchets that disagree is the guard sprawl this
- * generation is trying to avoid, so this file points at them instead of repeating
- * them.
- *
- * 🔴 If you ever move that check here, keep the property that made it correct: it
- * scans EVERY file type, not just `.ts`. `tw-animate-css` is imported from
- * `src/styles.css` and a `.ts`-only scan calls it dead.
- *
- * Exit 1 on any failure, so it can sit in a verify chain. It sits in the suite
- * instead — `src/publicSurface.spec.ts` — so `bun run verify` needs no new script
- * and cannot be a script somebody forgot to chain.
- */
-import { dirname, join } from 'node:path';
-import ts from 'typescript';
-
-// Resolved from this file, never from `process.cwd()`: the suite imports it and
-// `bun test` can be started from anywhere.
-const ROOT = dirname(import.meta.dir);
-const BASELINE = join(ROOT, 'publicSurface.baseline');
-
-const DEFAULT_HEADER = [
-	'# Public surface of `cursedbelt`: one line per export subpath, `<exported symbols>  <subpath>`.',
-	'#',
-	'# A CEILING, not an amnesty. The check fails on a subpath NOT listed here, on a listed',
-	'# subpath that gained a symbol, and on an entry that no longer matches `package.json`',
-	'# exports — so a deleted module cannot leave a stale allowance behind. Surface can only fall.',
-	'#',
-	'# To record a deliberate change:  bun scripts/publicSurface.ts --prune',
-	'# It refuses to RAISE anything, so new surface is a reviewed diff, never a silent one.',
-	'#',
-	'# What a count includes, what it excludes and why, and the measurement this file is a',
-	'# ratchet against, are in the header of scripts/publicSurface.ts. Say nothing here that',
-	'# the entries below already say.',
-];
-
-export type Surface = {
-	/** subpath (as written in `exports`) → deduped exported symbol count */
-	counts: Map<string, number>;
-	/** subpaths skipped because they resolve to a non-TS asset (the three stylesheets) */
-	assets: string[];
-};
-
-const isRelative = (spec: string): boolean => spec.startsWith('./') || spec.startsWith('../');
-const isWalkable = (file: string): boolean => /\.(m|c)?tsx?$/.test(file);
-
-/** `./a/b` from `src/x/y.tsx` → the first of `src/a/b.ts(x)`, `src/a/b/index.ts(x)`, … that exists. */
-const resolveRelative = async (fromFile: string, spec: string): Promise<string | null> => {
-	const base = join(dirname(fromFile), spec);
-	// `./x.js` names `./x.ts` — the spelling Node ESM needs in the emitted file (task 269), which
-	// tsc copies verbatim from the source. Tried first so a `.js` never resolves to itself.
-	const ts = /\.js$/.test(base) ? [base.replace(/\.js$/, '.ts'), base.replace(/\.js$/, '.tsx')] : [];
-	const candidates = [...ts, `${base}.ts`, `${base}.tsx`, `${base}/index.ts`, `${base}/index.tsx`, base];
-	for (const c of candidates) {
-		if (await Bun.file(c).exists()) return c;
-	}
-	return null;
-};
-
-/**
- * A bare `export * from 'pkg'` — resolved through node resolution so its symbols
- * are counted rather than silently dropped. Throws when the package resolves to
- * something with no parseable types, because a zero there would be a lie.
- */
-const resolveBare = (fromFile: string, spec: string): string => {
-	let resolved: string;
-	try {
-		resolved = Bun.resolveSync(spec, dirname(fromFile));
-	} catch (cause) {
-		throw new Error(
-			`${fromFile}: \`export * from '${spec}'\` re-exports a package that does not resolve, so its ` +
-				'symbols cannot be counted. Install it, or name the symbols — do not let the count lie.',
-			{ cause },
-		);
-	}
-	if (!isWalkable(resolved)) {
-		throw new Error(
-			`${fromFile}: \`export * from '${spec}'\` resolves to ${resolved}, which this measurement cannot ` +
-				'parse. Point it at TypeScript, name the symbols, or teach scripts/publicSurface.ts to read ' +
-				'a declaration bundle — do not let the count lie.',
-		);
-	}
-	return resolved;
-};
-
-// One parse per file, shared across all 88 subpaths: the barrels overlap heavily
-// (every `./react/*` subpath re-parses a slice of what `./react` already walked).
-const parsed = new Map<string, ts.SourceFile>();
-const sourceOf = async (file: string): Promise<ts.SourceFile> => {
-	const hit = parsed.get(file);
-	if (hit !== undefined) return hit;
-	// 🔴 Bun.file, NOT node:fs — this package's test preload shares one process with
-	// specs that virtualize node:fs, so a readFileSync scan reads MOCK data and the
-	// measurement passes against files it never opened. Same trap as
-	// publishShape.spec.ts; see its header.
-	const source = ts.createSourceFile(file, await Bun.file(file).text(), ts.ScriptTarget.ES2022, true);
-	parsed.set(file, source);
-	return source;
-};
-
-/** Every name a binding pattern introduces — `export const { a, b: [c] } = …` is three. */
-const bindingNames = (name: ts.BindingName, out: Set<string>): void => {
-	if (ts.isIdentifier(name)) {
-		out.add(name.text);
-		return;
-	}
-	for (const el of name.elements) {
-		if (ts.isBindingElement(el)) bindingNames(el.name, out);
-	}
-};
-
-/** Deduped exported names of `file`, following `export * from` chains. */
-const exportedNames = async (file: string, seen = new Set<string>()): Promise<Set<string>> => {
-	const names = new Set<string>();
-	if (seen.has(file)) return names;
-	seen.add(file);
-
-	const source = await sourceOf(file);
-	const modifiersOf = (node: ts.Node): readonly ts.Modifier[] =>
-		ts.canHaveModifiers(node) ? (ts.getModifiers(node) ?? []) : [];
-
-	for (const st of source.statements) {
-		if (ts.isExportDeclaration(st)) {
-			if (st.exportClause && ts.isNamedExports(st.exportClause)) {
-				for (const el of st.exportClause.elements) names.add(el.name.text);
-			} else if (st.exportClause && ts.isNamespaceExport(st.exportClause)) {
-				names.add(st.exportClause.name.text);
-			} else {
-				const spec =
-					st.moduleSpecifier && ts.isStringLiteral(st.moduleSpecifier) ? st.moduleSpecifier.text : null;
-				if (spec === null) continue;
-				let target: string | null;
-				if (isRelative(spec)) {
-					target = await resolveRelative(file, spec);
-					if (target === null) throw new Error(`${file}: \`export * from '${spec}'\` resolves to nothing.`);
-				} else {
-					target = resolveBare(file, spec);
-				}
-				for (const n of await exportedNames(target, seen)) names.add(n);
-			}
-			continue;
-		}
-		if (ts.isExportAssignment(st)) {
-			names.add('default');
-			continue;
-		}
-		const modifiers = modifiersOf(st);
-		if (!modifiers.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) continue;
-		// `export default function Foo()` is imported as `default`, not as `Foo`.
-		if (modifiers.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword)) {
-			names.add('default');
-			continue;
-		}
-		if (ts.isVariableStatement(st)) {
-			for (const d of st.declarationList.declarations) bindingNames(d.name, names);
-		} else if (
-			(ts.isFunctionDeclaration(st) ||
-				ts.isClassDeclaration(st) ||
-				ts.isInterfaceDeclaration(st) ||
-				ts.isTypeAliasDeclaration(st) ||
-				ts.isEnumDeclaration(st) ||
-				ts.isModuleDeclaration(st)) &&
-			st.name !== undefined
-		) {
-			if (ts.isIdentifier(st.name) || ts.isStringLiteral(st.name)) names.add(st.name.text);
-		}
-	}
-	return names;
-};
-
-/** The `./src/**` or `./scripts/**` TypeScript file a subpath resolves to, or null when it is an asset. */
-const entryOf = (value: unknown): string | null => {
-	if (typeof value === 'string')
-		return (value.startsWith('./src/') || value.startsWith('./scripts/')) && isWalkable(value)
-			? join(ROOT, value.slice(2))
-			: null;
-	if (typeof value !== 'object' || value === null) return null;
-	// `bun` and `source` are the conditions that point at TypeScript; `types` and
-	// `import` point into `dist`, which is build output and may not exist. Reading
-	// the conditions in this order is what makes the measurement work on a clean
-	// checkout, before `bun run build` has ever run.
-	for (const key of ['bun', 'source', 'types', 'import', 'default']) {
-		if (key in (value as Record<string, unknown>)) {
-			const hit = entryOf((value as Record<string, unknown>)[key]);
-			if (hit !== null) return hit;
-		}
-	}
-	for (const v of Object.values(value as Record<string, unknown>)) {
-		const hit = entryOf(v);
-		if (hit !== null) return hit;
-	}
-	return null;
-};
-
-export const measureSurface = async (pkg: { exports: Record<string, unknown> }): Promise<Surface> => {
-	const counts = new Map<string, number>();
-	const assets: string[] = [];
-	for (const [subpath, value] of Object.entries(pkg.exports)) {
-		const entry = entryOf(value);
-		if (entry === null) {
-			assets.push(subpath);
-			continue;
-		}
-		counts.set(subpath, (await exportedNames(entry)).size);
-	}
-	return { counts, assets };
-};
-
-// ── the baseline ────────────────────────────────────────────────────────────────
-
-export type Baseline = { header: string[]; counts: Map<string, number> };
-
-export const parseBaseline = (text: string): Baseline => {
-	const header = text.split('\n').filter((l) => l.startsWith('#'));
-	const counts = new Map<string, number>();
-	for (const line of text.split('\n')) {
-		if (!line.trim() || line.startsWith('#')) continue;
-		const m = line.match(/^\s*(\d+)\s+(\S.*)$/);
-		if (m?.[2] !== undefined) counts.set(m[2].trim(), Number(m[1]));
-	}
-	return { header: header.length > 0 ? header : DEFAULT_HEADER, counts };
-};
-
-export const readBaseline = async (): Promise<Baseline> => {
-	const f = Bun.file(BASELINE);
-	return parseBaseline((await f.exists()) ? await f.text() : '');
-};
-
-export const formatBaseline = (header: string[], counts: Map<string, number>): string =>
-	`${[...header, ...[...counts.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([k, n]) => `${n}  ${k}`)].join(
-		'\n',
-	)}\n`;
-
-export type Failures = { grown: string[]; fresh: string[]; stale: string[] };
-
-export const compare = (surface: Surface, baseline: Baseline): Failures => {
-	const fresh: string[] = [];
-	const grown: string[] = [];
-	for (const [subpath, n] of surface.counts) {
-		const allowed = baseline.counts.get(subpath);
-		if (allowed === undefined) fresh.push(`${subpath}  — NEW subpath, ${n} exported symbol(s)`);
-		else if (n > allowed) grown.push(`${subpath}  — baseline allows ${allowed}, exports ${n} now`);
-	}
-	const stale = [...baseline.counts.entries()]
-		.filter(([subpath, n]) => (surface.counts.get(subpath) ?? 0) < n)
-		.map(([subpath, n]) =>
-			surface.counts.has(subpath)
-				? `${subpath}  — baseline says ${n}, exports ${surface.counts.get(subpath)}`
-				: `${subpath}  — baseline says ${n}, the subpath is gone`,
-		);
-	return { fresh, grown, stale };
-};
-
-export const run = async (): Promise<Failures & { surface: Surface; baseline: Baseline }> => {
-	const pkg = (await Bun.file(join(ROOT, 'package.json')).json()) as { exports: Record<string, unknown> };
-	const surface = await measureSurface(pkg);
-	const baseline = await readBaseline();
-	return { ...compare(surface, baseline), surface, baseline };
-};
-
-// ── CLI ─────────────────────────────────────────────────────────────────────────
-
-if (import.meta.main) {
-	const argv = process.argv.slice(2);
-	const prune = argv.includes('--prune');
-	const { fresh, grown, stale, surface, baseline } = await run();
-	const total = [...surface.counts.values()].reduce((a, b) => a + b, 0);
-
-	// `--seed` exists once, to record the surface the ratchet starts from. It REFUSES
-	// over an existing baseline, so re-seeding means deleting the file first — two
-	// visible steps and a whole-file diff, rather than one command that quietly
-	// re-baselines whatever grew.
-	if (argv.includes('--seed')) {
-		if (baseline.counts.size > 0) {
-			console.error(`publicSurface --seed refuses: ${BASELINE} already records ${baseline.counts.size} subpath(s).`);
-			console.error('Lower it with --prune. Raising it is a hand edit in a commit that says why.');
-			process.exit(1);
-		}
-		await Bun.write(BASELINE, formatBaseline(baseline.header, surface.counts));
-		console.log(`publicSurface: seeded ${surface.counts.size} subpath(s), ${total} exported symbol(s).`);
-		process.exit(0);
-	}
-
-	if (prune) {
-		// 🔴 It may only LOWER. Growth is the thing this file exists to make visible;
-		// a prune that could absorb it would be the disable switch.
-		if (fresh.length > 0 || grown.length > 0) {
-			console.error('publicSurface --prune refuses while the surface has GROWN — it may only lower the baseline.\n');
-			for (const v of [...fresh, ...grown]) console.error(`  ${v}`);
-			console.error(
-				'\nTo record deliberate new surface, add the line by hand and say in the commit message why the\npackage needs it — that is the reviewable moment this check exists to create.\n',
-			);
-			process.exit(1);
-		}
-		const lowered = new Map<string, number>();
-		for (const [subpath, n] of baseline.counts) {
-			const now = surface.counts.get(subpath);
-			if (now !== undefined) lowered.set(subpath, Math.min(n, now));
-		}
-		await Bun.write(BASELINE, formatBaseline(baseline.header, lowered));
-		console.log(
-			`publicSurface: baseline pruned to ${lowered.size} subpath(s), ` +
-				`${baseline.counts.size - lowered.size} removed, ${[...lowered.values()].reduce((a, b) => a + b, 0)} symbols.`,
-		);
-		process.exit(0);
-	}
-
-	let bad = false;
-	const report = (label: string, lines: string[], advice: string): void => {
-		if (lines.length === 0) return;
-		bad = true;
-		console.error(`\n${lines.length} ${label}:\n`);
-		for (const l of lines) console.error(`  ${l}`);
-		console.error(`\n${advice}\n`);
-	};
-	report(
-		'export subpath(s) the baseline does not know',
-		fresh,
-		'A new subpath is a permanent public promise. If it is genuinely wanted, add its line to\n' +
-			`${BASELINE} and say why in the commit message.`,
-	);
-	report(
-		'subpath(s) that gained exported symbols',
-		grown,
-		'A baseline entry is a ceiling. Raise it by hand, in a commit that says why.',
-	);
-	report(
-		'baseline entr(y|ies) that no longer match `exports`',
-		stale,
-		`Surface came off and the ratchet was not tightened. Run:\n  cd ${ROOT} && bun scripts/publicSurface.ts --prune`,
-	);
-	if (bad) process.exit(1);
-
-	console.log(
-		`publicSurface: ${surface.counts.size} subpath(s), ${total} exported symbol(s), ` +
-			`${surface.assets.length} asset export(s) — none grown.`,
-	);
-}