#!/usr/bin/env bun // Enforce, as a gate rule, that `wiki/Error-Codes.md`'s "never ships to an app" parenthesis is // complete in both directions: every code it names has a table row on one of the error-code pages // (`wiki/Error-Codes-scripts.md`, for a script's own), and every code `scripts/` declares is named // in it. // // The gap this closes: nothing read that parenthesis. `checkErrorCodeDocs` is satisfied by ANY // `X_FOO` in a backtick anywhere on the page — `documentedCodes` is one regex over the whole file — // so being named INSIDE the parenthesis counts as being documented, and `X_LOCKFILE_STALE`, // `X_RELEASE_VERSION_UNSTATED` and eighteen others have no row at all. From the other side, // `checkErrorCodeRegistry` exempts gate codes by SCANNING `scripts/` (`hostOwnedCodes` in // scripts/verify.ts), never by reading the list — so the list is a hand-copy of a derived set with // no check on it, which is the same shape `gate-steps.ts` and `release-facts.ts` exist for. Four // `X_REGISTRY_*` codes are missing from it today, and the sentence around it says every code above // `## Reserved codes` resolves through `x errors explain` except the ones it names. // // bun run scripts/gate-codes.ts [--json] // The LEAF module, never the `@ultimat3/cli` barrel: the barrel links every package in the tree, so // one half-written module anywhere crashed this guard with a bare SyntaxError (DX ledger #10). import { collectDeclaredCodes } from '../packages/cli/src/error-contract'; import { renderFixShellArg } from '../packages/core/src/error-render'; import { GATE_CODE_NO_ROW, GATE_CODE_UNLISTED } from './gate-codes-backlog'; import { parseScriptArgs } from './lib/args'; import { ERROR_CODE_INDEX, ownerPage, readErrorCodePages } from './lib/error-code-pages'; import type { Finding } from './lib/log'; import { report } from './lib/log'; import { repoRoot } from './lib/run'; const SCRIPT = 'gate-codes'; /** The page the never-ships list is on: the index. The rows are on the owner pages. */ export const ERROR_REFERENCE = ERROR_CODE_INDEX; /** Where a script code's row goes. */ const SCRIPTS_PAGE = ownerPage('scripts'); export const BACKLOG_FILE = 'scripts/gate-codes-backlog.ts'; /** * Where the parenthesis starts. Matched on the prose that introduces it rather than on a line * number, because the page is edited far more often than this rule is. */ export const NEVER_SHIPS_LEAD = "this repository's own gate scripts ("; /** * The codes the parenthesis names, `X_ROADMAP_*`-style wildcards included. Read from the lead to * the first `)` after it: the sentence continues past that bracket ("never ship, so no package may * own them"), and swallowing the rest of the page would make every code on it "listed". */ export function neverShipsList(markdown: string): ReadonlySet { const start = markdown.indexOf(NEVER_SHIPS_LEAD); if (start === -1) return new Set(); const from = start + NEVER_SHIPS_LEAD.length; const close = markdown.indexOf(')', from); const span = markdown.slice(from, close === -1 ? from : close); return new Set([...span.matchAll(/`(X_[A-Z0-9_]*\*?)`/g)].map((match) => match[1] as string)); } /** * A code with a real row. Anchored on `| \`X_…\` |` as the FIRST cell, so a code merely mentioned * inside another row's cause or fix does not count as having one of its own — which is exactly the * hole `documentedCodes`' whole-file regex leaves open. */ export const tableRows = (markdown: string): ReadonlySet => new Set( [...markdown.matchAll(/^\|\s*`(X_[A-Z0-9_]+)`\s*\|/gm)].map((match) => match[1] as string), ); export type GateCodeGapKind = 'no-row' | 'unlisted' | 'pinned'; export interface GateCodeGap { readonly kind: GateCodeGapKind; readonly code: string; } export interface GateCodeInput { /** Every `X_*` code declared under `scripts/`, from `collectDeclaredCodes`. */ readonly declared: readonly string[]; /** The index's text: the never-ships list. */ readonly page: string; /** Every error-code page's text, the index included: a row on any of them is a row. */ readonly pages: readonly string[]; readonly noRowPins: readonly string[]; readonly unlistedPins: readonly string[]; } /** A wildcard entry covers a family: `X_ROADMAP_*` stands for every code it prefixes. */ const covers = (listed: ReadonlySet, code: string): boolean => listed.has(code) || [...listed].some((entry) => entry.endsWith('*') && code.startsWith(entry.slice(0, -1))); export function checkGateCodes(input: GateCodeInput): readonly GateCodeGap[] { const listed = neverShipsList(input.page); const rows = new Set(input.pages.flatMap((page) => [...tableRows(page)])); const gaps: GateCodeGap[] = []; // Every code the list stands for: the names it spells, AND each declared code a wildcard covers. // The row check read only the first until 2026-10, so `X_ROADMAP_*` listed a whole family and // excused every member of it from having a row — a covered code was documented by an asterisk. const named = [...listed].filter((code) => !code.endsWith('*')); const family = input.declared.filter((code) => !listed.has(code) && covers(listed, code)); const noRow = [...new Set([...named, ...family])].filter((code) => !rows.has(code)); for (const code of noRow) { if (input.noRowPins.includes(code)) continue; gaps.push({ kind: 'no-row', code }); } const unlisted = input.declared.filter((code) => !covers(listed, code)); for (const code of unlisted) { if (input.unlistedPins.includes(code)) continue; gaps.push({ kind: 'unlisted', code }); } // A pin nobody removes is a pin nobody reads — the ratchet only ratchets if it shrinks on its own. for (const code of input.noRowPins) { if (!noRow.includes(code)) gaps.push({ kind: 'pinned', code }); } for (const code of input.unlistedPins) { if (!unlisted.includes(code)) gaps.push({ kind: 'pinned', code }); } return gaps.sort((a, b) => a.code.localeCompare(b.code)); } const FINDINGS: Readonly Finding>> = Object.assign( Object.create(null), { 'no-row': (code) => ({ code: 'X_GATE_CODE_UNDOCUMENTED', cause: `${ERROR_REFERENCE} names ${code} in the never-ships list and no error-code page gives it a table row, so an agent handed ${code} finds the name and no cause and no fix`, fix: `grep -n '^| \`X_' ${SCRIPTS_PAGE} # add a \`| \`${code}\` | … |\` row there at its place in code order, then: bun run scripts/error-code-pages.ts --write — or drop ${code} from the never-ships list in ${ERROR_REFERENCE}`, at: ERROR_REFERENCE, }), unlisted: (code) => ({ code: 'X_GATE_CODE_UNDOCUMENTED', cause: `${code} is declared under scripts/ and ${ERROR_REFERENCE}'s never-ships list omits it, so that page promises "x errors explain ${code}" answers and it does not`, fix: `grep -n 'never ship' ${ERROR_REFERENCE} # add \`${code}\` to that never-ships parenthesis`, at: ERROR_REFERENCE, }), pinned: (code) => ({ code: 'X_GATE_CODE_BACKLOG_STALE', cause: `${code} is pinned in ${BACKLOG_FILE} and ${ERROR_REFERENCE} is no longer wrong about it`, fix: `grep -n ${renderFixShellArg(code, '')} ${BACKLOG_FILE} # delete '${code}' there`, at: BACKLOG_FILE, }), } satisfies Record Finding>, ); export const gateCodeFinding = (gap: GateCodeGap): Finding => FINDINGS[gap.kind](gap.code); /** Every `X_*` code this repo's own gate scripts declare — the set the parenthesis restates. */ export const scriptDeclaredCodes = async (root: string): Promise => (await collectDeclaredCodes(root)) .filter((site) => site.at.startsWith('scripts/')) .map((site) => site.code); export async function gateCodeGaps(root: string): Promise { const pages = await readErrorCodePages(root); return checkGateCodes({ declared: await scriptDeclaredCodes(root), page: pages.find((one) => one.path === ERROR_REFERENCE)?.text ?? '', pages: pages.map((one) => one.text), noRowPins: GATE_CODE_NO_ROW, unlistedPins: GATE_CODE_UNLISTED, }); } /** Every finding this rule contributes, for a caller that folds it into a gate step. */ export const gateCodeFindings = async (root: string): Promise => (await gateCodeGaps(root)).map(gateCodeFinding); if (import.meta.main) { const args = parseScriptArgs(Bun.argv.slice(2)); const pins = GATE_CODE_NO_ROW.length + GATE_CODE_UNLISTED.length; const findings = await gateCodeFindings(repoRoot()); report( { ok: findings.length === 0, script: SCRIPT, summary: findings.length === 0 ? `${ERROR_REFERENCE}'s never-ships list is complete in both directions, ${pins} code(s) pinned` : `${findings.length} finding(s): ${ERROR_REFERENCE}'s never-ships list is incomplete`, findings, data: { pinned: pins }, }, args.json, ); }