msd-core/scripts/gen-exit-code-registry.cjs

#!/usr/bin/env node
/**
 * gen-exit-code-registry.cjs — generates FOUR byte-identical/derived
 * artifacts from the declaration at gsd-core/bin/shared/exit-codes.json:
 *   - gsd-core/bin/lib/exit-code-registry.cjs   (tsc-adjacent build tree)
 *   - scripts/lib/exit-code-registry.cjs        (committed, for scripts/
 *     consumers that must work on an unbuilt clone — same reason
 *     scripts/lib/cli-exit.cjs exists alongside gsd-core/bin/lib/cli-exit.cjs;
 *     see scripts/gen-scripts-cli-exit.cjs).
 *   - src/exit-code-registry.d.cts               (the ambient type declaration
 *     tsc uses to typecheck src/cli-exit.cts's `require('./exit-code-registry.cjs')`
 *     against the shape the .cjs artifacts above actually export — generated
 *     from the SAME ENTRY_FIELD_TYPES table serializeRegistry() uses, so the
 *     two can never independently drift).
 *   - gsd-core/bin/shared/exit-codes.sh          (POSIX sh, safe under
 *     `set -u`: one `export EXIT_<NAME>=<code>` per entry, sourced by the
 *     bash scanners under scripts/ so a shell caller never re-invents a
 *     literal exit-code integer — ADR-3889 Phase 4, #3908).
 *
 * ADR-3889 ("One exit-code registry — 0 and 1 are free, everything else is
 * allocated") Phase 1 (#3905) built the single-output allocator; Phase 2
 * (#3906) added the second .cjs emission so scripts/ has its own committed
 * copy instead of reaching into gitignored build output; a follow-up closed
 * the review finding that the .d.cts was hand-maintained with no gate by
 * generating it here too; Phase 4 (#3908) added the shell fragment so the
 * three bash scanners can source symbolic names instead of hardcoding
 * integers.
 *
 * The two .cjs artifacts are byte-identical: serializeRegistry() only encodes
 * the DECLARATION path (for the banner comment), never the output path, so
 * one generated string is written to both locations unchanged. The .d.cts
 * and .sh artifacts are separate, smaller derivations but are generated and
 * --check-gated exactly the same way.
 *
 * Nothing in this script emits a registered exit code itself; wiring
 * consumers onto the registry is separate work.
 *
 * Usage:
 *   node scripts/gen-exit-code-registry.cjs                # same as --write
 *   node scripts/gen-exit-code-registry.cjs --write         # write all four artifacts
 *   node scripts/gen-exit-code-registry.cjs --check         # exit 1 if ANY committed artifact is stale
 *   node scripts/gen-exit-code-registry.cjs --declaration <path> --out <path> --scripts-out <path> --dts-out <path> --sh-out <path>   # override for tests
 *   node scripts/gen-exit-code-registry.cjs --json          # emit ONE JSON report on stdout instead of human prose
 */

'use strict';

const fs = require('node:fs');
const path = require('node:path');

const REPO_ROOT = path.resolve(__dirname, '..');
const DEFAULT_DECLARATION_PATH = path.join(REPO_ROOT, 'gsd-core', 'bin', 'shared', 'exit-codes.json');
const DEFAULT_OUTPUT_PATH = path.join(REPO_ROOT, 'gsd-core', 'bin', 'lib', 'exit-code-registry.cjs');
const DEFAULT_SCRIPTS_OUTPUT_PATH = path.join(REPO_ROOT, 'scripts', 'lib', 'exit-code-registry.cjs');
const DEFAULT_DTS_OUTPUT_PATH = path.join(REPO_ROOT, 'src', 'exit-code-registry.d.cts');
const DEFAULT_SH_OUTPUT_PATH = path.join(REPO_ROOT, 'gsd-core', 'bin', 'shared', 'exit-codes.sh');

/**
 * Single source of the entry field list (name -> TS type), in emission order.
 * serializeRegistry()'s per-entry object literal and serializeDts()'s
 * ExitCodeEntry interface are BOTH derived from this one table, so the two
 * artifacts cannot independently drift out of shape with each other — closing
 * the review finding that the ambient .d.cts was a hand-maintained guess at
 * what serializeRegistry() emits.
 */
const ENTRY_FIELD_TYPES = Object.freeze({
  code: 'number',
  name: 'string',
  meaning: 'string',
  owner: 'string',
  authorizedBy: 'string',
});

/** Frozen reason codes so tests assert on structure, not prose. */
const REASON = Object.freeze({
  OK: 'ok_generated_sync',
  DRIFTED: 'fail_generated_drifted',
  USAGE: 'fail_usage',
  MISSING_DECLARATION: 'fail_missing_declaration',
  MALFORMED_DECLARATION: 'fail_malformed_declaration',
  NOT_AN_ARRAY: 'fail_not_an_array',
  EMPTY_DECLARATION: 'fail_empty_declaration',
  INVALID_ENTRY: 'fail_invalid_entry',
  DUPLICATE_CODE: 'fail_duplicate_code',
  DUPLICATE_NAME: 'fail_duplicate_name',
  RESERVED_CODE: 'fail_reserved_code',
  FORBIDDEN_OWNER: 'fail_forbidden_owner',
  MISSING_ARTIFACT: 'fail_missing_artifact',
});

const USAGE_MESSAGE = [
  'Usage: node scripts/gen-exit-code-registry.cjs [--write|--check] [--declaration <path>] [--out <path>] [--scripts-out <path>] [--dts-out <path>] [--sh-out <path>] [--json]',
  '  (no flag)        same as --write',
  '  --write          write all four generated registry artifacts',
  '  --check          exit 1 if ANY committed artifact is stale',
  '  --declaration    override the declaration path (default: gsd-core/bin/shared/exit-codes.json)',
  '  --out            override the primary output artifact path (default: gsd-core/bin/lib/exit-code-registry.cjs)',
  '  --scripts-out    override the secondary output artifact path (default: scripts/lib/exit-code-registry.cjs)',
  '  --dts-out        override the ambient type declaration path (default: src/exit-code-registry.d.cts)',
  '  --sh-out         override the shell-sourceable fragment path (default: gsd-core/bin/shared/exit-codes.sh)',
  '  --json           emit ONE JSON report ({ok, reason, context, detail?}) on stdout instead of human-readable prose',
].join('\n');

/** SCREAMING_SNAKE_CASE: starts with a letter, only uppercase letters/digits/underscores. */
const NAME_RE = /^[A-Z][A-Z0-9_]*$/;

/** Fields every entry must carry as a non-empty, non-whitespace-only string. */
const REQUIRED_STRING_FIELDS = ['meaning', 'owner', 'authorizedBy'];

/**
 * Bands, per ADR-3889 §1:
 *   0, 1                 free (not allocatable here)
 *   2                     hook-adapter only
 *   3-13                  Node-reserved
 *   14-63, 79, 126+        outside every band
 *   64-78                 generic
 *   80-125                domain
 */
function isAllocatableCode(code) {
  if (code === 2) return true;
  if (code >= 64 && code <= 78) return true;
  if (code >= 80 && code <= 125) return true;
  return false;
}

/**
 * Label the non-allocatable band a rejected code falls into, per the same
 * range boundaries documented on isAllocatableCode/ADR-3889 §1. Only called
 * for codes that already failed isAllocatableCode, so 2 and 64-125 never
 * reach here.
 * @returns {string}
 */
function bandFor(code) {
  if (code === 0 || code === 1) return 'free';
  if (code >= 3 && code <= 13) return 'node-reserved';
  if (code >= 126) return 'shell-signal';
  return 'outside-every-band'; // 14-63, 79
}

/**
 * Validate a single declaration entry's shape and band membership.
 * @returns {{ok:true}|{ok:false,reason:string,message:string,context:object}}
 */
function validateEntry(entry, index) {
  if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
    return {
      ok: false,
      reason: REASON.INVALID_ENTRY,
      message: `entry[${index}] is not an object: ${JSON.stringify(entry)}`,
      context: { field: 'entry', index },
    };
  }

  const { code, name } = entry;
  if (!Number.isInteger(code) || code < 0) {
    return {
      ok: false,
      reason: REASON.INVALID_ENTRY,
      message: `entry[${index}].code must be a non-negative integer (no coercion), received ${JSON.stringify(code)}`,
      context: { field: 'code', index, code },
    };
  }

  if (typeof name !== 'string' || name.trim() === '' || !NAME_RE.test(name)) {
    return {
      ok: false,
      reason: REASON.INVALID_ENTRY,
      message: `entry[${index}].name must be a non-empty SCREAMING_SNAKE_CASE string, received ${JSON.stringify(name)}`,
      context: { field: 'name', index, code, name },
    };
  }

  for (const field of REQUIRED_STRING_FIELDS) {
    const value = entry[field];
    if (typeof value !== 'string' || value.trim() === '') {
      return {
        ok: false,
        reason: REASON.INVALID_ENTRY,
        message: `entry[${index}] (${name}).${field} must be a non-empty string, received ${JSON.stringify(value)}`,
        context: { field, index, code, name },
      };
    }
  }

  if (!isAllocatableCode(code)) {
    return {
      ok: false,
      reason: REASON.RESERVED_CODE,
      message: `entry[${index}] (${name}) declares code ${code}, which is outside every allocatable band ` +
        `(2 hook-adapter only; 64-78 generic; 80-125 domain) — see ADR-3889 §1`,
      context: { code, band: bandFor(code), index, name },
    };
  }

  if (code === 2 && entry.owner !== 'hook-adapter') {
    return {
      ok: false,
      reason: REASON.FORBIDDEN_OWNER,
      message: `entry[${index}] (${name}) declares code 2 with owner "${entry.owner}" — code 2 is reserved to ` +
        `the Claude Code hook protocol and may only be owned by "hook-adapter"`,
      context: { code, owner: entry.owner, requiredOwner: 'hook-adapter', index, name },
    };
  }

  return { ok: true };
}

/**
 * Validate the whole declaration: every entry individually, then the
 * cross-entry invariants (one number one meaning; one owner emits a given
 * code — but the SAME owner may legitimately own several distinct codes).
 * @returns {{ok:true}|{ok:false,reason:string,message:string,context:object}}
 */
function validateEntries(entries) {
  for (let i = 0; i < entries.length; i++) {
    const result = validateEntry(entries[i], i);
    if (!result.ok) return result;
  }

  const byCode = new Map();
  const byName = new Map();
  for (const entry of entries) {
    if (byCode.has(entry.code)) {
      const other = byCode.get(entry.code);
      return {
        ok: false,
        reason: REASON.DUPLICATE_CODE,
        message: `code ${entry.code} is declared twice: "${other.name}" and "${entry.name}"`,
        context: { code: entry.code, names: [other.name, entry.name] },
      };
    }
    byCode.set(entry.code, entry);

    if (byName.has(entry.name)) {
      const other = byName.get(entry.name);
      return {
        ok: false,
        reason: REASON.DUPLICATE_NAME,
        message: `name "${entry.name}" is declared twice: code ${other.code} and code ${entry.code}`,
        context: { name: entry.name, codes: [other.code, entry.code] },
      };
    }
    byName.set(entry.name, entry);
  }

  return { ok: true };
}

/**
 * Load and parse the declaration file.
 * @returns {{ok:true,entries:Array}|{ok:false,reason:string,message:string}}
 */
function loadDeclaration(declarationPath) {
  if (!fs.existsSync(declarationPath)) {
    return {
      ok: false,
      reason: REASON.MISSING_DECLARATION,
      message: `declaration not found at ${declarationPath}`,
      context: { path: declarationPath },
    };
  }

  let raw;
  try {
    raw = fs.readFileSync(declarationPath, 'utf8');
  } catch (err) {
    return {
      ok: false,
      reason: REASON.MISSING_DECLARATION,
      message: `could not read ${declarationPath}: ${err.message}`,
      context: { path: declarationPath },
    };
  }

  let parsed;
  try {
    parsed = JSON.parse(raw);
  } catch (err) {
    return {
      ok: false,
      reason: REASON.MALFORMED_DECLARATION,
      message: `${declarationPath} is not valid JSON: ${err.message}`,
      context: { path: declarationPath },
    };
  }

  if (!Array.isArray(parsed)) {
    return {
      ok: false,
      reason: REASON.NOT_AN_ARRAY,
      message: `${declarationPath} must be a JSON array, received ${parsed === null ? 'null' : typeof parsed}`,
      context: { path: declarationPath },
    };
  }

  if (parsed.length === 0) {
    return {
      ok: false,
      reason: REASON.EMPTY_DECLARATION,
      message: `${declarationPath} is an empty array — declare at least one exit code`,
      context: { path: declarationPath },
    };
  }

  return { ok: true, entries: parsed };
}

/**
 * Hand-serialize the generated registry module (string concatenation, like
 * gsd-core/bin/lib/capability-registry.cjs — no build step, no template
 * engine, so the emitted bytes are exactly what `--check` re-derives).
 */
function serializeRegistry(entries, declarationPath) {
  const relDeclaration = path.relative(REPO_ROOT, declarationPath).split(path.sep).join('/');
  const banner = [
    '\'use strict\';',
    '',
    '// GENERATED FILE — DO NOT EDIT BY HAND.',
    `// Source of truth: ${relDeclaration}. Regenerate with:`,
    '//   node scripts/gen-exit-code-registry.cjs --write',
    '// This exact content is emitted to TWO locations — gsd-core/bin/lib/exit-code-registry.cjs',
    '// and scripts/lib/exit-code-registry.cjs (the latter committed so scripts/',
    '// consumers work on an unbuilt clone) — both byte-compared by',
    '// `npm run lint:generated-sync` (#3905 ADR-3889 Phase 1; #3906 Phase 2 added the second copy).',
    '//',
    '// exitCodeFor(name) / nameForExitCode(code) are pure and total over this',
    '// closed table — each throws for anything not registered here.',
    '',
  ].join('\n');

  const entryFieldNames = Object.keys(ENTRY_FIELD_TYPES);
  const entryLiterals = entries.map((e) => {
    const fieldLines = entryFieldNames.map((field) => `    ${field}: ${JSON.stringify(e[field])},`).join('\n');
    return `  Object.freeze({\n${fieldLines}\n  })`;
  }).join(',\n');

  const body = [
    'const EXIT_CODES = Object.freeze([',
    entryLiterals,
    ']);',
    '',
    'const NAME_TO_CODE = new Map(EXIT_CODES.map((entry) => [entry.name, entry.code]));',
    'const CODE_TO_NAME = new Map(EXIT_CODES.map((entry) => [entry.code, entry.name]));',
    '',
    '/**',
    ' * Resolve the registered exit code for a symbolic name. Pure, total: throws',
    ' * for anything not an exact, registered, exact-case key — including',
    ' * non-strings, the empty string, untrimmed strings, wrong case, and',
    ' * prototype-chain names like `__proto__`/`constructor`/`toString` (a Map',
    ' * lookup never touches the prototype chain, so these are indistinguishable',
    ' * from any other unregistered name).',
    ' *',
    ' * @param {string} name',
    ' * @returns {number}',
    ' */',
    'function exitCodeFor(name) {',
    '  if (typeof name !== \'string\' || name.length === 0) {',
    '    throw new Error(`exitCodeFor: name must be a non-empty string, received ${JSON.stringify(name)}`);',
    '  }',
    '  if (!NAME_TO_CODE.has(name)) {',
    '    throw new Error(`exitCodeFor: unregistered exit code name: ${JSON.stringify(name)}`);',
    '  }',
    '  return NAME_TO_CODE.get(name);',
    '}',
    '',
    '/**',
    ' * Reverse of exitCodeFor: resolve the symbolic name for a registered exit',
    ' * code. Pure, total: throws for anything not an exact, registered code.',
    ' *',
    ' * @param {number} code',
    ' * @returns {string}',
    ' */',
    'function nameForExitCode(code) {',
    '  if (!CODE_TO_NAME.has(code)) {',
    '    throw new Error(`nameForExitCode: unregistered exit code: ${JSON.stringify(code)}`);',
    '  }',
    '  return CODE_TO_NAME.get(code);',
    '}',
    '',
    'module.exports = { EXIT_CODES, exitCodeFor, nameForExitCode };',
    '',
  ].join('\n');

  return banner + '\n' + body;
}

/**
 * Generate the ambient type declaration for the generated .cjs registry
 * artifacts. Derived from the SAME ENTRY_FIELD_TYPES table serializeRegistry()
 * iterates for its per-entry object literals, and from serializeRegistry()'s
 * own fixed `module.exports = { EXIT_CODES, exitCodeFor, nameForExitCode }`
 * shape — so this declaration cannot drift out of step with what the sibling
 * .cjs artifacts actually export without both call sites being edited
 * together. Structural only (no per-entry data): the type is the same
 * regardless of how many rows the declaration has.
 */
function serializeDts(declarationPath) {
  const relDeclaration = path.relative(REPO_ROOT, declarationPath).split(path.sep).join('/');
  const fieldLines = Object.entries(ENTRY_FIELD_TYPES)
    .map(([field, type]) => `  readonly ${field}: ${type};`)
    .join('\n');

  return [
    '// GENERATED FILE — DO NOT EDIT BY HAND.',
    `// Source of truth: ${relDeclaration} + the ENTRY_FIELD_TYPES table in`,
    '// scripts/gen-exit-code-registry.cjs. Regenerate with:',
    '//   node scripts/gen-exit-code-registry.cjs --write',
    '//',
    '// Ambient type declaration for exit-code-registry.cjs — a GENERATED,',
    '// committed artifact with no `.cts` source of its own (it is hand-serialized',
    '// from gsd-core/bin/shared/exit-codes.json by scripts/gen-exit-code-registry.cjs,',
    '// ADR-3889 §2, #3905/#3906), so tsc has nothing to compile for it. This file',
    "// exists purely so `src/cli-exit.cts`'s `require('./exit-code-registry.cjs')`",
    '// type-checks against the SAME shape the generated artifact actually exports',
    '// at runtime — mirroring the src/vendor/*.d.cts pattern already used for',
    '// other verbatim/generated JS this tree resolves types for without compiling.',
    '//',
    '// This declaration is generated from the same ENTRY_FIELD_TYPES table',
    "// serializeRegistry()'s per-entry object literals iterate, and is",
    '// byte-compared by `node scripts/gen-exit-code-registry.cjs --check`',
    '// (the same check that already covers the two sibling .cjs artifacts) so a',
    '// shape drift here fails the build instead of surfacing at a destructuring',
    '// call site.',
    '',
    'export interface ExitCodeEntry {',
    fieldLines,
    '}',
    '',
    'declare const exitCodeRegistry: {',
    '  readonly EXIT_CODES: readonly ExitCodeEntry[];',
    '  // Property-typed function signatures (`name: (args) => ret`), NOT method',
    '  // shorthand (`name(args): ret`) — the latter is a TS "method" and trips',
    '  // @typescript-eslint/unbound-method at every destructuring call site',
    '  // (`const { exitCodeFor } = ...`), since a method may implicitly use',
    '  // `this`. These are pure functions that never do, so they are typed as',
    '  // plain function-valued properties instead.',
    '  exitCodeFor: (name: string) => number;',
    '  nameForExitCode: (code: number) => string;',
    '};',
    '',
    'export = exitCodeRegistry;',
    '',
  ].join('\n');
}

/**
 * Generate the shell-sourceable fragment: one `export EXIT_<NAME>=<code>`
 * line per declared entry, POSIX sh, safe under `set -u` (a sourced file that
 * only ever ASSIGNS variables can never trip an unset-variable check,
 * regardless of what the caller's shell had in scope beforehand).
 *
 * Consumed by the bash scanners under scripts/ via `. gsd-core/bin/shared/
 * exit-codes.sh` (ADR-3889 Phase 4, #3908) so a shell caller resolves a
 * symbolic name instead of hardcoding a literal integer that can silently
 * drift from the registry.
 */
function serializeSh(entries, declarationPath) {
  const relDeclaration = path.relative(REPO_ROOT, declarationPath).split(path.sep).join('/');
  const banner = [
    '#!/bin/sh',
    '# GENERATED FILE — DO NOT EDIT BY HAND.',
    `# Source of truth: ${relDeclaration}. Regenerate with:`,
    '#   node scripts/gen-exit-code-registry.cjs --write',
    '#',
    '# One `export EXIT_<NAME>=<code>` per gsd-core/bin/shared/exit-codes.json',
    '# entry (ADR-3889 §2, #3905/#3906/#3908). POSIX sh, safe under `set -u`:',
    '# sourcing this file only ever ASSIGNS variables, never reads one, so it',
    '# cannot trip an unset-variable check regardless of the caller\'s existing',
    '# environment.',
    '#',
    '# Usage (from a scanner under scripts/):',
    '#   . "$(dirname "$0")/../gsd-core/bin/shared/exit-codes.sh"',
    '#   exit "$EXIT_UNAVAILABLE"',
    '',
  ].join('\n');

  const lines = entries.map((e) => `export EXIT_${e.name}=${e.code}`);

  return banner + lines.join('\n') + '\n';
}

/**
 * Load, validate, and serialize the declaration in one step.
 * @returns {{ok:true,content:string}|{ok:false,reason:string,message:string}}
 */
function buildRegistryContent(declarationPath) {
  const loaded = loadDeclaration(declarationPath);
  if (!loaded.ok) return loaded;

  const validated = validateEntries(loaded.entries);
  if (!validated.ok) return validated;

  return { ok: true, content: serializeRegistry(loaded.entries, declarationPath), entries: loaded.entries };
}

function printFail(result) {
  console.error(`FAIL gen-exit-code-registry: ${result.reason}`);
  console.error(`  ${result.message}`);
}

/**
 * Emit a failure outcome: structured JSON on stdout (and NO stderr prose)
 * when `json` is set, otherwise the legacy human-readable stderr report.
 * `context` carries the specifics (offending code/name/field/path) that the
 * `detail` prose currently embeds, so a `--json` consumer never needs to
 * parse prose to recover them — it defaults to `null` for reasons (USAGE,
 * DRIFTED, MISSING_ARTIFACT) that carry no structured specifics.
 * @param {{reason:string, message?:string, context?:object}} result
 * @param {boolean} json
 */
function emitFail(result, json) {
  if (json) {
    process.stdout.write(JSON.stringify({ ok: false, reason: result.reason, context: result.context ?? null, detail: result.message }) + '\n');
    return;
  }
  printFail(result);
}

/**
 * Emit a success outcome: structured JSON on stdout when `json` is set,
 * otherwise the legacy human-readable stdout line.
 * @param {string} reason
 * @param {string} humanMessage
 * @param {boolean} json
 */
function emitOk(reason, humanMessage, json) {
  if (json) {
    process.stdout.write(JSON.stringify({ ok: true, reason }) + '\n');
    return;
  }
  console.log(humanMessage);
}

function doWrite(declarationPath, outPath, scriptsOutPath, dtsPath, shPath, json) {
  const result = buildRegistryContent(declarationPath);
  if (!result.ok) {
    emitFail(result, json);
    return 1;
  }
  // The two .cjs artifacts are byte-identical copies of the same generated
  // content (serializeRegistry never encodes the output path), so the same
  // string is written to both locations unchanged.
  for (const target of [outPath, scriptsOutPath]) {
    fs.mkdirSync(path.dirname(target), { recursive: true });
    fs.writeFileSync(target, result.content, 'utf8');
  }
  const dtsContent = serializeDts(declarationPath);
  fs.mkdirSync(path.dirname(dtsPath), { recursive: true });
  fs.writeFileSync(dtsPath, dtsContent, 'utf8');
  const shContent = serializeSh(result.entries, declarationPath);
  fs.mkdirSync(path.dirname(shPath), { recursive: true });
  fs.writeFileSync(shPath, shContent, 'utf8');
  emitOk(
    REASON.OK,
    `ok gen-exit-code-registry: wrote ${outPath}\nok gen-exit-code-registry: wrote ${scriptsOutPath}\n`
    + `ok gen-exit-code-registry: wrote ${dtsPath}\nok gen-exit-code-registry: wrote ${shPath}`,
    json,
  );
  return 0;
}

/**
 * Verify one committed artifact against the freshly generated content.
 * @returns {{ok:true}|{ok:false,reason:string,message:string,context:object}}
 */
function checkOneArtifact(artifactLabel, artifactPath, content) {
  if (!fs.existsSync(artifactPath)) {
    return {
      ok: false,
      reason: REASON.MISSING_ARTIFACT,
      message: `${artifactPath} (${artifactLabel}) does not exist. Run:\n  node scripts/gen-exit-code-registry.cjs --write`,
      context: { artifact: artifactLabel, path: artifactPath },
    };
  }

  const committed = fs.readFileSync(artifactPath, 'utf8');
  if (committed !== content) {
    return {
      ok: false,
      reason: REASON.DRIFTED,
      message:
        `${artifactPath} (${artifactLabel}, ${committed.length} bytes) != freshly generated content (${content.length} bytes)\n\n`
        + 'Regenerate with:\n  node scripts/gen-exit-code-registry.cjs --write',
      context: { artifact: artifactLabel, path: artifactPath },
    };
  }

  return { ok: true };
}

/**
 * --check verifies ALL FOUR committed artifacts against the same freshly
 * generated content and fails naming which one drifted (or is missing) if
 * any does. Checked in a fixed order (primary, secondary, dts, sh) so a
 * single-artifact failure is always reported deterministically.
 */
function doCheck(declarationPath, outPath, scriptsOutPath, dtsPath, shPath, json) {
  const result = buildRegistryContent(declarationPath);
  if (!result.ok) {
    emitFail(result, json);
    return 1;
  }
  const dtsContent = serializeDts(declarationPath);
  const shContent = serializeSh(result.entries, declarationPath);

  const artifacts = [
    ['primary', outPath, result.content],
    ['secondary', scriptsOutPath, result.content],
    ['dts', dtsPath, dtsContent],
    ['sh', shPath, shContent],
  ];
  for (const [artifactLabel, artifactPath, content] of artifacts) {
    const checked = checkOneArtifact(artifactLabel, artifactPath, content);
    if (!checked.ok) {
      emitFail(checked, json);
      return 1;
    }
  }

  emitOk(
    REASON.OK,
    `ok gen-exit-code-registry: ${outPath} matches ${declarationPath}\n`
    + `ok gen-exit-code-registry: ${scriptsOutPath} matches ${declarationPath}\n`
    + `ok gen-exit-code-registry: ${dtsPath} matches ${declarationPath}\n`
    + `ok gen-exit-code-registry: ${shPath} matches ${declarationPath}`,
    json,
  );
  return 0;
}

/**
 * @returns {{mode:'write'|'check', declarationPath:?string, outPath:?string, scriptsOutPath:?string, dtsPath:?string, shPath:?string, json:boolean}}
 */
function parseArgs(argv) {
  let mode = null;
  let declarationPath = null;
  let outPath = null;
  let scriptsOutPath = null;
  let dtsPath = null;
  let shPath = null;
  let json = false;

  for (let i = 0; i < argv.length; i++) {
    const arg = argv[i];
    if (arg === '--write' || arg === '--check') {
      if (mode !== null) {
        throw new Error(`conflicting mode flags: --${mode} and ${arg}`);
      }
      mode = arg === '--write' ? 'write' : 'check';
    } else if (arg === '--json') {
      json = true;
    } else if (arg === '--declaration') {
      const value = argv[++i];
      if (value === undefined) throw new Error('--declaration requires a value');
      declarationPath = value;
    } else if (arg.startsWith('--declaration=')) {
      declarationPath = arg.slice('--declaration='.length);
    } else if (arg === '--out') {
      const value = argv[++i];
      if (value === undefined) throw new Error('--out requires a value');
      outPath = value;
    } else if (arg.startsWith('--out=')) {
      outPath = arg.slice('--out='.length);
    } else if (arg === '--scripts-out') {
      const value = argv[++i];
      if (value === undefined) throw new Error('--scripts-out requires a value');
      scriptsOutPath = value;
    } else if (arg.startsWith('--scripts-out=')) {
      scriptsOutPath = arg.slice('--scripts-out='.length);
    } else if (arg === '--dts-out') {
      const value = argv[++i];
      if (value === undefined) throw new Error('--dts-out requires a value');
      dtsPath = value;
    } else if (arg.startsWith('--dts-out=')) {
      dtsPath = arg.slice('--dts-out='.length);
    } else if (arg === '--sh-out') {
      const value = argv[++i];
      if (value === undefined) throw new Error('--sh-out requires a value');
      shPath = value;
    } else if (arg.startsWith('--sh-out=')) {
      shPath = arg.slice('--sh-out='.length);
    } else {
      throw new Error(`unrecognized argument: ${arg}`);
    }
  }

  return { mode: mode || 'write', declarationPath, outPath, scriptsOutPath, dtsPath, shPath, json };
}

function main() {
  // --json must be honored even on a parse failure (e.g. an unrecognized
  // flag alongside --json), so it is detected from the raw argv rather
  // than from parseArgs's return value, which may never be produced.
  const rawArgv = process.argv.slice(2);
  const jsonRequested = rawArgv.includes('--json');

  let args;
  try {
    args = parseArgs(rawArgv);
  } catch (err) {
    emitFail({ reason: REASON.USAGE, message: jsonRequested ? err.message : `${err.message}\n${USAGE_MESSAGE}` }, jsonRequested);
    return 1;
  }

  const declarationPath = args.declarationPath || DEFAULT_DECLARATION_PATH;
  const outPath = args.outPath || DEFAULT_OUTPUT_PATH;
  const scriptsOutPath = args.scriptsOutPath || DEFAULT_SCRIPTS_OUTPUT_PATH;
  const dtsPath = args.dtsPath || DEFAULT_DTS_OUTPUT_PATH;
  const shPath = args.shPath || DEFAULT_SH_OUTPUT_PATH;

  return args.mode === 'check'
    ? doCheck(declarationPath, outPath, scriptsOutPath, dtsPath, shPath, args.json)
    : doWrite(declarationPath, outPath, scriptsOutPath, dtsPath, shPath, args.json);
}

if (require.main === module) process.exitCode = main();

module.exports = {
  REASON,
  USAGE_MESSAGE,
  DEFAULT_DECLARATION_PATH,
  DEFAULT_OUTPUT_PATH,
  DEFAULT_SCRIPTS_OUTPUT_PATH,
  DEFAULT_DTS_OUTPUT_PATH,
  DEFAULT_SH_OUTPUT_PATH,
  ENTRY_FIELD_TYPES,
  isAllocatableCode,
  bandFor,
  validateEntry,
  validateEntries,
  loadDeclaration,
  serializeRegistry,
  serializeDts,
  serializeSh,
  buildRegistryContent,
  parseArgs,
  main,
};