// The generator, proved on a throwaway root holding copies of real `errors.ts` files and of the // real error-code pages — never the committed ones. Every refusal leaves every file as found, // because a registration without its row is the gap this exists to close. import { afterAll, describe, expect, setDefaultTimeout, test } from 'bun:test'; // why: Bun has no mkdtemp/rm of its own; a unique directory per run keeps test workers apart. import { mkdir } from 'node:fs/promises'; import { planPageEdits } from './lib/error-code-page-edit'; import { codeRows, errorCodePageFiles, ownerOfPage, ownerPage } from './lib/error-code-pages'; import { codeRowFor, registerIn } from './lib/error-code-plan'; import { snapshotReader } from './lib/planned-writes'; import { REPO_SCAN_TIMEOUT_MS } from './lib/run'; // Reads the real tree or spawns real processes, so it runs on the repo-scan backstop. setDefaultTimeout(REPO_SCAN_TIMEOUT_MS); afterAll(removeFixtureRoots); import { ScriptError } from './lib/script-error'; import { newErrorCode, STATUS_BACKLOG, statusTableFor, WIKI_PAGE } from './new-error-code'; import { fixtureRoot, ROOT, read, refusal, removeFixtureRoots, transpiles, } from './new-error-code.fixtures'; describe('a new code, registered and documented in one edit', () => { test('money: into the codes array AND the titles table, a row on its page, the index', async () => { const dir = await fixtureRoot(); const result = await newErrorCode(dir, [ 'X_MONEY_ROUNDING_LOST', '--package', 'money', '--title', "a conversion that can't keep its minor units", '--fix', "call convert(amount, rate, { rounding: 'half-even' })", '--cause', 'a rate with more | decimals than the currency', '--status', '422', ]); expect(result.written).toEqual([ 'packages/money/src/errors.ts', ownerPage('money'), WIKI_PAGE, statusTableFor('money'), ]); const errors = await read(dir, 'packages/money/src/errors.ts'); expect(errors).toContain(" 'X_MONEY_ROUNDING_LOST',\n] as const;"); expect(errors).toContain( " X_MONEY_ROUNDING_LOST: 'a conversion that can\\'t keep its minor units',\n};", ); expect(transpiles(errors)).toBe(true); const page = await read(dir, ownerPage('money')); const codes = codeRows(page).map((row) => row.codes[0] ?? ''); // Present, and at its place in code order: the rows either side sort below and above it. const at = codes.indexOf('X_MONEY_ROUNDING_LOST'); expect(at).toBeGreaterThan(0); expect((codes[at - 1] ?? '') < 'X_MONEY_ROUNDING_LOST').toBe(true); expect((codes[at + 1] ?? 'X_~') > 'X_MONEY_ROUNDING_LOST').toBe(true); expect(page).toContain('more \\| decimals'); // …and the index lists it, so no second command is needed for the gate to stay green. expect(await read(dir, WIKI_PAGE)).toContain( '| X_MONEY_ROUNDING_LOST | [money](Error-Codes-money) |', ); }); test('the row goes in the CODE table, never the notes table further down', async () => { // Scraping's page carries a retry-override table (`| Set | Codes | Effect |`) in its notes. const dir = await fixtureRoot(); const before = await read(dir, ownerPage('scraping')); const input = { code: 'X_SCRAPE_ZZ_PROBE', pkg: 'scraping', title: 't', cause: 'c', fix: 'f' }; const [page] = await planPageEdits({ root: dir, read: snapshotReader(dir, new Map()), input, owner: 'scraping', }); const lines = (page?.text ?? '').split('\n'); const at = lines.indexOf(codeRowFor(input)); expect(at).toBeGreaterThan(0); expect(lines.indexOf('| Set | Codes | Effect |')).toBeGreaterThan(at); expect(lines[at - 1]).toStartWith('| `X_SCRAPE_'); expect(page?.text.replace(`${codeRowFor(input)}\n`, '')).toBe(before); }); test("an owner's first code opens its page, linked from the regenerated index", async () => { const dir = await fixtureRoot(); const input = { code: 'X_FRESH_PROBE', pkg: 'fresh', title: 't', cause: 'c', fix: 'f' }; const [page, index] = await planPageEdits({ root: dir, read: snapshotReader(dir, new Map()), input, owner: 'fresh', }); expect(page?.path).toBe('wiki/Error-Codes-fresh.md'); expect(page?.text).toStartWith('# Error codes: `@ultimat3/fresh`'); expect(codeRows(page?.text ?? '').map((row) => row.codes)).toEqual([['X_FRESH_PROBE']]); expect(index?.text).toContain( '| `@ultimat3/fresh` | [Error-Codes-fresh](Error-Codes-fresh) | 1 |', ); }); test('seo: a literal registerErrorCodes({ … }) gets a { title } entry', async () => { const dir = await fixtureRoot(); await newErrorCode(dir, [ 'X_SEO_ALT_MISSING', '--package', 'seo', '--title', 'an image with no alt text', '--cause', 'what usually makes it happen', '--fix', 'add alt to the the cause names', '--off-socket', ]); const errors = await read(dir, 'packages/seo/src/errors.ts'); expect(errors).toContain(" X_SEO_ALT_MISSING: { title: 'an image with no alt text' },\n});"); expect(transpiles(errors)).toBe(true); }); }); describe('a registry kept as frozen declarations, not titles', () => { // `@ultimat3/schema` is tier 0 and cannot call `registerErrorCodes()`, so its codes are DATA core // reads: `Object.freeze({ X_A: { title } })` in `error-codes.ts`. The planner refused that shape, // so the one package with it had a second, hand-written way to add a code. const withSchema = async (): Promise => { const dir = await fixtureRoot(); await mkdir(`${dir}/packages/schema/src`, { recursive: true }); await Bun.write( `${dir}/packages/schema/src/error-codes.ts`, Bun.file(`${ROOT}/packages/schema/src/error-codes.ts`), ); return dir; }; const args = (title: string): string[] => [ 'X_SCHEMA_PROBE', '--package', 'schema', '--title', title, '--cause', 'what usually makes it happen', '--fix', 'edit the schema the cause names', '--off-socket', ]; test('schema: the declaration joins the frozen object, the row and the pin land with it', async () => { const dir = await withSchema(); await newErrorCode(dir, args('a probe')); const codes = await read(dir, 'packages/schema/src/error-codes.ts'); expect(codes).toContain(" X_SCHEMA_PROBE: { title: 'a probe' },\n });"); expect(transpiles(codes)).toBe(true); expect(await read(dir, ownerPage('schema'))).toContain('| `X_SCHEMA_PROBE` | a probe |'); // The pin joins schema's OFF_SOCKET group — never schema's UNDECIDED group. Opening a group a // package lacks is `new-error-code-status.test.ts`'s `time` case. const backlog = await read(dir, STATUS_BACKLOG); const offSocket = backlog.slice(backlog.indexOf('export const OFF_SOCKET')); // Read off the group, never a copy of the real row: the row grows with every schema code, and // Biome writes it on one line or one code per line depending on its width. const group = offSocket.slice(0, offSocket.indexOf('\n};\n')); expect(group).toMatch(/\n {2}schema: \[[^\]]*'X_SCHEMA_PROBE',?\s*\],\n/); }); test('a title past 100 columns wraps the way Biome writes the entry', async () => { const dir = await withSchema(); const title = 'a probe whose title is long enough that the one-line entry would not fit the column'; await newErrorCode(dir, args(title)); expect(await read(dir, 'packages/schema/src/error-codes.ts')).toContain( ` X_SCHEMA_PROBE: {\n title: '${title}',\n },\n });`, ); }); }); describe('a package whose titles are not in the first file the planner looks at', () => { // `@ultimat3/core` keeps its REGISTRY in `error-codes.ts` and its titles in // `core-error-codes.ts`, closed by `} as const;`. The planner stopped at the registry and // refused the package every other package depends on (plan 101, slice 01). test('core: the title lands in core-error-codes.ts, inside the literal', async () => { const dir = await fixtureRoot(); await mkdir(`${dir}/packages/core/src`, { recursive: true }); for (const file of ['error-codes.ts', 'core-error-codes.ts', 'errors.ts']) { await Bun.write( `${dir}/packages/core/src/${file}`, Bun.file(`${ROOT}/packages/core/src/${file}`), ); } const registry = await read(dir, 'packages/core/src/error-codes.ts'); const result = await newErrorCode(dir, [ 'X_CORE_PROBE_ONLY', '--package', 'core', '--title', 'a probe', '--cause', 'what usually makes it happen', '--fix', 'x doctor --json', '--off-socket', ]); expect(result.written).toEqual([ 'packages/core/src/core-error-codes.ts', ownerPage('core'), WIKI_PAGE, STATUS_BACKLOG, ]); const titles = await read(dir, 'packages/core/src/core-error-codes.ts'); expect(titles).toContain(" X_CORE_PROBE_ONLY: 'a probe',\n} as const;"); expect(transpiles(titles)).toBe(true); // The registry it could not add to is left exactly as found. expect(await read(dir, 'packages/core/src/error-codes.ts')).toBe(registry); expect(await read(dir, ownerPage('core'))).toContain('| `X_CORE_PROBE_ONLY` | a probe |'); }); // `@ultimat3/entity` keeps its registry in `entity-error.ts` — split from `errors.ts` so a // browser module can raise a code without importing `@ultimat3/db` (plan 101, slice 03). test('entity: the code joins the owned array and the titles in entity-error.ts', async () => { const dir = await fixtureRoot(); await mkdir(`${dir}/packages/entity/src`, { recursive: true }); for (const file of ['entity-error.ts', 'errors.ts']) { await Bun.write( `${dir}/packages/entity/src/${file}`, Bun.file(`${ROOT}/packages/entity/src/${file}`), ); } const result = await newErrorCode(dir, [ 'X_ENTITY_PROBE_ONLY', '--package', 'entity', '--title', 'a probe', '--cause', 'what usually makes it happen', '--fix', 'x doctor --json', '--status', '500', ]); expect(result.written).toEqual([ 'packages/entity/src/entity-error.ts', ownerPage('entity'), WIKI_PAGE, statusTableFor('entity'), ]); const errors = await read(dir, 'packages/entity/src/entity-error.ts'); expect(errors).toContain(" 'X_ENTITY_PROBE_ONLY',\n] as const;"); expect(errors).toContain(" X_ENTITY_PROBE_ONLY: 'a probe',\n};"); expect(transpiles(errors)).toBe(true); }); test('a code any candidate file already names is refused, not added to the next one', async () => { const dir = await fixtureRoot(); await mkdir(`${dir}/packages/core/src`, { recursive: true }); await Bun.write( `${dir}/packages/core/src/error-codes.ts`, "export const registry = new Map([['X_CORE_TAKEN', 't']]);\n", ); await Bun.write( `${dir}/packages/core/src/core-error-codes.ts`, "const CORE_CODE_TITLES = {\n X_A: 'a',\n} as const;\n", ); const argv = [ 'X_CORE_TAKEN', '--package', 'core', '--title', 't', '--cause', 'what usually makes it happen', '--fix', 'f', '--off-socket', ]; expect(await refusal(newErrorCode(dir, argv))).toBe('X_NEW_ERROR_CODE_EXISTS'); expect(await read(dir, 'packages/core/src/core-error-codes.ts')).not.toContain('X_CORE_TAKEN'); }); }); describe('the wiki fix cell reads like its neighbours', () => { // `--fix 'x db gen'` landed on the page as bare text between rows whose commands are in // backticks (W-DB, plan 101): a command a reader copies is code, and the page says so. const cellOf = (fix: string): string => { const row = codeRowFor({ code: 'X_CORE_PROBE', pkg: 'core', title: 't', cause: 'c', fix }); return row.split(' | ').at(-1)?.replace(/ \|$/, '') ?? ''; }; test('a bare command is written in backticks', () => { expect(cellOf('x db gen')).toBe('`x db gen`'); expect(cellOf('x jobs list --name --state running --json')).toBe( '`x jobs list --name --state running --json`', ); }); test('a trailing shell comment stays prose, after the command', () => { expect(cellOf('x secrets show --json # confirms the key id in force')).toBe( '`x secrets show --json` — confirms the key id in force', ); }); test('a fix the author already formatted is left exactly as written', () => { expect(cellOf('`x secrets init`, or export `ULTIMATE_SECRETS_KEY`')).toBe( '`x secrets init`, or export `ULTIMATE_SECRETS_KEY`', ); }); test('a pipe inside the command is still escaped for the table', () => { expect(cellOf('printf %s "$T" | x secrets set NAME')).toBe( '`printf %s "$T" \\| x secrets set NAME`', ); }); }); describe('a codes array with a sentence per entry', () => { // `@ultimat3/cli`'s owned-codes array carries a comment per code; read as "no array", the // planner wrote the title alone and the package no longer typechecked. test('the code joins the array as well as the titles', () => { const source = [ 'export const X_OWNED_ERROR_CODES = [', " 'X_A',", ' // why the next one exists', " 'X_B',", '] as const;', 'export const X_TITLES: Readonly> = {', " X_A: 'a',", " X_B: 'b',", '};', ].join('\n'); const out = registerIn(source, 'packages/x/src/error-codes.ts', { code: 'X_C', pkg: 'x', title: 'c', cause: 'c', fix: 'x doctor --json', }); expect(out).toContain(" 'X_C',\n] as const;"); expect(out).toContain(" X_C: 'c',"); }); }); describe('the cause cell is its own sentence, never the title again', () => { const base = ['X_MONEY_PROBE', '--package', 'money', '--title', 'a probe', '--fix', 'f']; test('no --cause is refused before anything is written', async () => { const dir = await fixtureRoot(); const before = await read(dir, ownerPage('money')); expect(await refusal(newErrorCode(dir, [...base, '--status', '400']))).toBe( 'X_NEW_ERROR_CODE_INVALID', ); expect(await read(dir, ownerPage('money'))).toBe(before); }); test('a --cause that repeats the title is refused — the row would say one thing twice', async () => { const dir = await fixtureRoot(); const argv = [...base, '--cause', ' A probe ', '--status', '400']; expect(await refusal(newErrorCode(dir, argv))).toBe('X_NEW_ERROR_CODE_INVALID'); }); test('the row carries title, cause and fix in their own cells', async () => { const dir = await fixtureRoot(); await newErrorCode(dir, [...base, '--cause', 'what usually causes it', '--status', '400']); const row = (await read(dir, ownerPage('money'))) .split('\n') .find((line) => line.startsWith('| `X_MONEY_PROBE`')); expect(row).toBe('| `X_MONEY_PROBE` | a probe | what usually causes it | `f` |'); }); }); describe('the real tree', () => { /** Every owner a page exists for, but the repo scripts: the packages that register codes. */ const packages = async (): Promise => (await errorCodePageFiles(ROOT)).flatMap((path) => { const owner = ownerOfPage(path); return owner === undefined || owner === 'scripts' ? [] : [owner]; }); test('every owner page names a package directory of this repository', async () => { const owners = await packages(); expect(owners.length).toBeGreaterThan(20); for (const pkg of owners) expect(await Bun.file(`${ROOT}/packages/${pkg}/package.json`).exists()).toBe(true); }); test('most real packages are in a shape it can add to — the rest are refused, never guessed', async () => { const shapes: Record = {}; for (const pkg of await packages()) { // A package that split its titles out (`ai`, `cli`, `jobs`) is probed where the planner writes. const split = Bun.file(`${ROOT}/packages/${pkg}/src/error-codes.ts`); const file = (await split.exists()) ? split : Bun.file(`${ROOT}/packages/${pkg}/src/errors.ts`); if (!(await file.exists())) continue; try { const out = registerIn(await file.text(), pkg, { code: 'X_PROBE_ONLY', pkg, title: 't', cause: 'c', fix: 'f', }); // Accepted means VALID: a plan that corrupts the file is worse than a refusal. shapes[pkg] = transpiles(out) ? 'ok' : 'crash'; } catch (error) { shapes[pkg] = error instanceof ScriptError ? error.code : 'crash'; } } expect(Object.values(shapes)).not.toContain('crash'); expect(Object.values(shapes).filter((shape) => shape === 'ok').length).toBeGreaterThan(20); expect(shapes['money']).toBe('ok'); expect(shapes['seo']).toBe('ok'); // A titles table beside a BORROWED codes array: the borrowed list is not where a new code goes. expect(shapes['query']).toBe('ok'); }); });