// The spaces procedure, from the command line. Reads the registry (test/space/registry.js), the decision-point // inventory (scripts/decision-points.mjs), the git manifest (test/space/git-manifest.json) and, for gate c, the // fail-site records of a suite run (PLY_FAILSITES=, written by test/space/failsite-hook.mjs). // // npm run spaces the hole report, every category, ranked by severity // npm run spaces -- --md regenerate SPACES.md // npm run spaces -- --ratchet lower test/space/ratchet.json to today's holes (never adds a hole; failsites // and claims need PLY_FAILSITES, else they keep their stored ids) // npm run spaces -- --ratchet --init --reason "" also add today's new holes to a stored category. With no // reason it exits 1, lists them and writes nothing; with one it prints the // `Ratchet-Change: test/space/ratchet.json: ` line the commit needs import { writeFileSync, existsSync } from 'node:fs'; import { join, isAbsolute } from 'node:path'; import { fileURLToPath } from 'node:url'; import { compute, readRecords, ratchet, RATCHET, ROOT, CATEGORIES, severityOfPoint, severityOfGit, spaceByName, isSite } from '../test/space/holes.js'; import { SPACES, SAMPLED } from '../test/space/registry.js'; const fmt = n => n.toLocaleString('en-US'); const esc = s => String(s).replace(/\|/g, '\\|').replace(/\n/g, '\\n').replace(/ [p.id, p])); const gitE = new Map(all.man.entries.map(e => [e.id, e])); const out = []; for (const id of all.holes.git) { const e = gitE.get(id); out.push({ sev: severityOfGit(e), cat: 'git', id, where: `git ${e.file}:${e.line} ${e.fn}()`, what: `${e.kind}: ${e.text}` }); } for (const id of all.holes.decisions) { const p = pts.get(id); out.push({ sev: severityOfPoint(p), cat: 'decisions', id, where: `${p.file} ${p.fn}()`, what: `${p.code}: ${p.what}` }); } for (const id of stored.failsites?.ids ?? []) { const p = pts.get(id); if (p) out.push({ sev: severityOfPoint(p), cat: 'failsites', id, where: `${p.file} ${p.fn}()`, what: `${p.code}: ${p.what}` }); } for (const id of stored.claims?.ids ?? []) out.push({ sev: 2, cat: 'claims', id, where: '', what: 'the registry names a merged space that does not reach this site' }); const kindRank = { git: 0, decisions: 1, failsites: 2, claims: 3 }; return out.sort((a, b) => a.sev - b.sev || kindRank[a.cat] - kindRank[b.cat] || a.id.localeCompare(b.id)); } export function coverage(all) { const tally = (ids, by) => { const t = { main: 0, pending: 0, excluded: 0, none: 0 }; for (const id of ids) { const r = by.get(id); if (!r) t.none++; else if ('excluded' in r) t.excluded++; else t[spaceByName.get(r.space).status === 'main' ? 'main' : 'pending']++; } return t; }; const kinds = by => { const k = { enumerated: 0, curated: 0, random: 0 }; for (const r of by.values()) if (r.space) k[spaceByName.get(r.space).kind]++; return k; }; return { decisions: tally(all.points.map(p => p.id), all.dec.by), git: tally(all.man.entries.map(e => e.id), all.git.by), decisionKinds: kinds(all.dec.by), gitKinds: kinds(all.git.by) }; } export function renderMd(all) { const st = ratchet().categories; const cov = coverage(all); const L = []; L.push('# Spaces', ''); L.push('', ''); L.push('Every decision ply makes, and every check git makes on the same input, belongs to a **space**: a list of axes, each a tagged union, whose product is explored cell by cell and judged by real git. Random fuzzing finds a bug; only enumeration says a bug class is gone (#52 could not tell broken from fixed by fuzzing; the enumerated #51 and #62 spaces found 412,008 and 3,598 wrong cells).', ''); L.push('The procedure is enforced, not remembered:', ''); L.push('- `scripts/decision-points.mjs` extracts every decision point from `src/` (each `fail(`/`failHere(` call, each call to a fail wrapper, each produced error code, each untyped `throw new Error`, each exported `parse*`/`decode*`/`classify*`/`decide*`).'); L.push(`- \`scripts/git-manifest.mjs\` extracts git ${all.man.git.tag}'s own checks (fsck msg ids, die/error/ng/reject strings of the protocol files, capabilities, request arguments, ref-name rules, fsck_tree modes) into \`test/space/git-manifest.json\`.`); L.push('- `test/space/registry.js` maps each one to the space and axis that covers it, or excludes it with a reason.'); L.push('- Gates (`test/space/registry.test.js`, `test/space/failsites.test.js`, in CI): **a** every decision point is registered; **b** every git check is covered or excluded; **c** every fail site is reached by a cell (stacks recorded at `plyError` by `test/space/failsite-hook.mjs` in node and by the plugin in `vitest.config.ts` under vitest: `src/` and the bundle are untouched), and every site the registry gives a space is reached by that space\'s runners when they ran. Reached is not judged: a test that triggers an error and asserts nothing reaches the site too, so the recorder also notes whether code outside `src/` read the error\'s `code`, and `failsites.test.js` prints the reached sites whose error nobody read (report only: that list has no ratchet baseline yet). A category with holes is in REPORT mode (holes printed; only a hole not in `test/space/ratchet.json` fails); at 0 it switches to ENFORCE. The ratchet only goes down: `npm run spaces -- --ratchet`.', ''); L.push('## Status', ''); L.push('| category | holes (ratchet) | mode |', '|---|---:|---|'); for (const c of CATEGORIES) L.push(`| ${c} | ${fmt(st[c].count)} | ${st[c].count === 0 ? 'ENFORCE' : 'REPORT'} |`); L.push(''); const sites = all.points.filter(isSite).length; L.push(`Decision points: **${fmt(all.points.length)}** (${fmt(sites)} fail sites, ${fmt(all.inv.producers.length)} produced codes, ${fmt(all.inv.untyped.length)} untyped throws, ${fmt(all.inv.exports.length)} exported parse/decode/classify/decide functions). Covered by a merged space ${fmt(cov.decisions.main)}, by a pending PR ${fmt(cov.decisions.pending)}, excluded ${fmt(cov.decisions.excluded)}, unregistered ${fmt(cov.decisions.none)}. Fail sites no cell reaches: ${fmt(st.failsites.count)} of ${fmt(sites)}. Of the registered points, ${fmt(cov.decisionKinds.enumerated)} are claimed by an enumerated space, ${fmt(cov.decisionKinds.random)} only by a random one and ${fmt(cov.decisionKinds.curated)} only by a curated list: a curated or random claim says a case exists, not that the class is gone.`, ''); L.push(`git ${all.man.git.tag} checks: **${fmt(all.man.entries.length)}** (${Object.entries(all.man.counts).map(([k, n]) => `${k} ${n}`).join(', ')}). Covered by a merged space ${fmt(cov.git.main)}, by a pending PR ${fmt(cov.git.pending)}, excluded ${fmt(cov.git.excluded)}, uncovered ${fmt(cov.git.none)}. Claimed by an enumerated space ${fmt(cov.gitKinds.enumerated)}, random ${fmt(cov.gitKinds.random)}, curated ${fmt(cov.gitKinds.curated)}.`, ''); if (SAMPLED.length) { L.push('Sampled fail sites (reached on some runs only; reported, never ratcheted):', ''); for (const x of SAMPLED) L.push(`- \`${esc(x.id)}\` (${x.runner}): ${esc(x.why)}`); L.push(''); } L.push('## Spaces', ''); L.push('| space | status | kind | axes | cells | observed / derived | oracle | decision points | git checks | run | OS |', '|---|---|---|---|---:|---|---|---:|---:|---|---|'); const countBy = by => { const m = new Map(); for (const r of by.values()) if (r.space) m.set(r.space, (m.get(r.space) ?? 0) + 1); return m; }; const dN = countBy(all.dec.by), gN = countBy(all.git.by); for (const s of SPACES) { const axes = s.axes.map(a => `${a.tag}${a.n ? `(${a.n})` : ''}`).join(' × '); const cells = typeof s.cells === 'number' ? fmt(s.cells) : esc(s.cells ?? '?'); const od = s.observed === undefined ? '—' : `${typeof s.observed === 'number' ? fmt(s.observed) : esc(s.observed)} / ${typeof s.derived === 'number' ? fmt(s.derived) : esc(s.derived ?? '—')}`; L.push(`| \`${s.name}\` | ${s.status === 'main' ? 'main' : `pending ${s.pending}`} | ${s.kind} | ${esc(axes)} | ${cells} | ${od} | ${esc(s.oracle)} | ${dN.get(s.name) ?? 0} | ${gN.get(s.name) ?? 0} | ${s.run}${s.runners?.length ? ` (${s.runners.map(r => `\`${r}\``).join(', ')})` : ''} | ${s.osDependent ? 'dependent¹' : '—'} |`); } L.push(''); L.push('¹ OS-dependent cells: expectations come from what the git server does on that run, fixtures keep refs in reftable (git ≥ 2.46, fix/43-bom 716cd77), and the Linux run in CI is the pass of record (the `linux` gate: every merged CI space\'s runners must have a Linux record; a macOS pass never counts).', ''); for (const s of SPACES.filter(x => x.osDependent)) L.push(`- \`${s.name}\`: ${esc(s.osDependent)}`); L.push(''); // decode sites: every bytes-to-string decode with its mode and what the registry says about it const decs = all.inv.decodes; L.push(`## Decode sites (${decs.length}: ${['lossless', 'strict', 'replacement'].map(m => `${m} ${decs.filter(d => d.mode === m).length}`).join(', ')})`, ''); L.push('git passes ref names, tree entry names, messages, idents and paths through as raw bytes. A **strict** decode (fatal TextDecoder, decodeURIComponent) refuses what git accepts; a **replacement** decode (the default TextDecoder) turns non-UTF-8 into U+FFFD and loses it. Either is a severity-1 hole unless the registry excludes it as display text or protocol keywords; the fix is a lossless decode and a space with a non-UTF-8 content axis.', ''); L.push('| where | mode | via | registry |', '|---|---|---|---|'); for (const d of decs) { const r = all.dec.by.get(d.id); const st = !r ? (d.mode === 'lossless' ? 'unregistered' : '**HOLE (data path)**') : 'excluded' in r ? `excluded: ${esc(r.excluded)}` : `\`${r.space}\` / ${r.axisTag}`; L.push(`| \`${d.file}\` ${d.fn}() | ${d.mode} | ${esc(d.via)} | ${st} |`); } L.push(''); const holes = rankedHoles(all, st); const SEV = { 1: 'Severity 1: checks on untrusted input (objects, packs, pkt-lines, reports, advertisements)', 2: 'Severity 2: decisions that claim an outcome (landed, rejected, conflict, ambiguous)', 3: 'Severity 3: the rest (caller input, limits, local I/O)' }; L.push(`## Holes (${fmt(holes.length)})`, ''); L.push('Ranked by severity, then category (`git`: a git check with no space; `decisions`: a ply decision point with no registry entry; `failsites`: a fail site no cell reaches; `claims`: a registry claim its space does not back). Fail-site and claim holes are the ratchet\'s, from the last recorded run.', ''); for (const sev of [1, 2, 3]) { const hs = holes.filter(h => h.sev === sev); L.push(`### ${SEV[sev]} (${fmt(hs.length)})`, ''); if (!hs.length) { L.push('None.', ''); continue; } L.push('| category | id | where | what |', '|---|---|---|---|'); for (const h of hs) L.push(`| ${h.cat} | \`${esc(h.id)}\` | ${esc(h.where)} | ${esc(h.what.slice(0, 120))} |`); L.push(''); } return `${L.join('\n')}\n`; } export function report(all) { const holes = rankedHoles(all, { failsites: { ids: all.holes.failsites ?? ratchet().categories.failsites.ids }, claims: { ids: all.holes.claims ?? ratchet().categories.claims.ids } }); const cov = coverage(all); console.log(`decision points ${all.points.length}: main ${cov.decisions.main}, pending ${cov.decisions.pending}, excluded ${cov.decisions.excluded}, unregistered ${cov.decisions.none}`); console.log(`git checks ${all.man.entries.length}: main ${cov.git.main}, pending ${cov.git.pending}, excluded ${cov.git.excluded}, uncovered ${cov.git.none}`); for (const c of CATEGORIES) console.log(`${c}: ${all.holes[c] === null ? '(no records; ratchet)' : ''} ${(all.holes[c] ?? ratchet().categories[c].ids).length}`); for (const sev of [1, 2, 3]) { const hs = holes.filter(h => h.sev === sev); console.log(`\n== severity ${sev}: ${hs.length}`); for (const h of hs) console.log(` [${h.cat}] ${h.id} ${h.where}`); } } if (process.argv[1] === fileURLToPath(import.meta.url)) { const dir = process.env.PLY_FAILSITES; const records = dir ? readRecords(isAbsolute(dir) ? dir : join(ROOT, dir)) : null; if (dir && !records) throw new Error(`no records under ${dir}`); const all = compute({ records }); if (process.argv.includes('--ratchet')) { const init = process.argv.includes('--init'); const at = process.argv.indexOf('--reason'); const reason = at < 0 ? '' : (process.argv[at + 1] ?? '').trim(); const old = existsSync(RATCHET) ? ratchet().categories : {}; const categories = {}; const added = []; for (const c of CATEGORIES) { const now = all.holes[c]; let ids; if (now === null) ids = old[c]?.ids ?? []; else if (!old[c]) ids = now; else { const keep = new Set(old[c].ids); ids = init ? now : now.filter(id => keep.has(id)); for (const id of ids) if (!keep.has(id)) added.push(`[${c}] ${id}`); } categories[c] = { count: ids.length, ids: [...ids].sort() }; } // A hole enters an existing category only with a stated reason, and the commit must repeat it: ci's // scripts/ratchet-guard.mjs compares ratchet.json with the base commit's and fails without the line. const line = `Ratchet-Change: test/space/ratchet.json: ${reason === '' ? '' : reason}`; if (added.length > 0 && reason === '') { console.error(`spaces: --ratchet --init would add ${added.length} hole(s) to test/space/ratchet.json; nothing written:\n${added.map(a => ` ${a}`).join('\n')}\nClose them, or rerun with --reason "" and put this line in the commit message:\n ${line}`); process.exit(1); } if (added.length > 0) console.log(`added ${added.length} hole(s):\n${added.map(a => ` ${a}`).join('\n')}\nthe commit message must carry the line:\n ${line}`); writeFileSync(RATCHET, `${JSON.stringify({ note: 'Holes per category (test/space/holes.js). Only ever lowered: npm run spaces -- --ratchet. A category at 0 is enforced.', categories }, null, 1)}\n`); for (const c of CATEGORIES) console.log(`${c}: ${categories[c].count}`); } if (process.argv.includes('--md')) writeFileSync(join(ROOT, 'SPACES.md'), renderMd(all)); if (!process.argv.includes('--ratchet') && !process.argv.includes('--md')) report(all); }