@bongos/core 1.17.0

package/scripts/gds/gen-repo-map.js

@@ -0,0 +1,519 @@
+#!/usr/bin/env node
+'use strict';
+// gen-repo-map.js — Path B (ADR 0062 §9 / ADR 0063, task 1224).
+//
+// A committed, CI-regenerated SYMBOL SKELETON for this instance's codebase:
+//   (1) docs/repo-map.md — an "altitude map" so an agent can navigate without reading every
+//       file: top symbols ranked by reference frequency (à la Aider's repo map) + per-directory
+//       exported signatures.
+//   (2) refreshes the FACTUAL half of the nested per-module CLAUDE.md docs (ADR 0061) — a
+//       generated, delimited block of the directory's exported signatures, so the hand-written
+//       interpretive prose stays put while the file list / signatures can't silently drift.
+//
+// Zero-dependency on purpose: the codebase is CommonJS JS, and a portable-core capability must
+// regenerate in CI and on every dev box with no native build / no node-gyp / no WASM grammar to
+// fetch (the whole point of Paths B+C is keeping every instance navigable cheaply). A line+regex
+// extractor is accurate enough for an *advisory* navigation aid (it is not a compiler input). A
+// richer tree-sitter/WASM backend can slot in behind extractFile() later for polyglot instances
+// (ADR 0063 Alternatives).
+//
+// Deterministic: no timestamps, stable sort — so `--check` is a clean idempotent CI gate.
+//
+// Usage:
+//   node scripts/gds/gen-repo-map.js            # regenerate docs/repo-map.md + nested-doc blocks
+//   node scripts/gds/gen-repo-map.js --check       # write nothing; exit 2 if EITHER bucket would change
+//   node scripts/gds/gen-repo-map.js --check-block # exit 2 only if a TRACKED nested block would change (the CI gate)
+//   node scripts/gds/gen-repo-map.js --check-whole # exit 2 only if docs/repo-map.md would change
+// docs/repo-map.md is GITIGNORED + regenerated at deploy/box-fetch since ADR 0110 (task 1926);
+// only the nested-doc symbol blocks stay tracked, so CI gates the block bucket, not the whole file.
+//   node scripts/gds/gen-repo-map.js --json       # print the extracted model as JSON (debug)
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveCoreRoot, resolveInstanceRoot } = require('../../src/instance-config'); // ADR 0108 §1: configurable-root
+// task 2013: reuse docs-entropy's link/staleness detectors (single source) to
+// build the doc link-graph + staleness flags. Requiring it is side-effect-free
+// (its CLI body is require.main-guarded).
+const docsEntropy = require('./docs-entropy');
+
+// ADR 0108 §Consequences #4 (configurable-root W6 / task 1886) — the generator scans TWO trees.
+// CORE code + the core-owned nested docs live under the core PACKAGE (resolveCoreRoot); the
+// instance's .claude/hooks are materialized under the host REPO (resolveInstanceRoot); modules
+// ship from BOTH. Today both resolve to the same checkout, so the scan is byte-identical; once the
+// core installs from node_modules they diverge and the map covers the right trees. A NEW hardcoded
+// `path.resolve(__dirname,'..','..')` reintroduces the bug.
+const CORE_ROOT = resolveCoreRoot();
+const INSTANCE_ROOT = resolveInstanceRoot();
+const REPO_ROOT = CORE_ROOT; // alias for the purely-core scan/write sites; instance/module sites route explicitly
+const MODULE_ROOTS = [...new Set([CORE_ROOT, INSTANCE_ROOT])];
+
+// Source roots scanned for both symbol extraction AND reference counting, grouped by which root
+// each resolves against. The build-system core (server-side JS) — the Cloud Bongos decoupling
+// target. Extend here to map more of an instance.
+const CORE_SCAN_ROOTS = ['server.js', 'src', 'scripts'];
+const INSTANCE_SCAN_ROOTS = ['.claude/hooks'];
+const MODULE_SCAN_ROOT = 'modules';
+const SCAN_ROOTS = [...CORE_SCAN_ROOTS, ...INSTANCE_SCAN_ROOTS, MODULE_SCAN_ROOT]; // combined list, for the scope header
+
+// Directories whose nested CLAUDE.md gets a generated symbol-skeleton block (must already exist —
+// they are authored in Path A / ADR 0061; this only refreshes the factual half). All CORE dirs.
+const NESTED_DIRS = ['src/bongos', 'src/bongos/routes', 'scripts/gds'];
+
+const EXCLUDE_DIR = new Set(['node_modules', '.git', 'tests', 'test', 'vendor']);
+const TOP_GLOBAL = 50;      // global "most-referenced" table cap
+const PER_FILE = 10;        // exported symbols listed per file
+const SIG_MAX = 90;         // signature truncation
+
+const BEGIN = '<!-- BEGIN GENERATED REPO-MAP (scripts/gds/gen-repo-map.js — do not hand-edit) -->';
+const END = '<!-- END GENERATED REPO-MAP -->';
+
+// Generic per-file local-helper / boilerplate names. They dominate a raw token tally (every script
+// has a `main`, a `log`, an `err`) but say nothing about cross-file centrality, so they are noise
+// for an altitude map. CommonJS reachability means real cross-file centrality ⟺ being exported, so
+// the global ranking is exported-only; this list trims the few generic names that still leak in.
+const NOISE = new Set([
+  'main', 'run', 'log', 'err', 'warn', 'fail', 'ok', 'info', 'debug', 'usage', 'help', 'sleep',
+  'noop', 'status', 'client', 'pool', 'res', 'req', 'next', 'data', 'result', 'val', 'value',
+  'fn', 'cb', 'msg', 'out', 'ret', 'args', 'opts', 'options', 'ctx', 'app', 'router', 'init',
+]);
+const isNoise = (name) => NOISE.has(name) || name.length <= 2;
+
+// macOS Finder / iCloud Drive sync-conflict copies are named "<base> 2.js",
+// "<base> 3.js", … (a space + digits before the extension). They are untracked,
+// stale duplicates that must NEVER enter the symbol skeleton: left in, they
+// double-count a module's symbols and bump file/symbol totals, so a ship from an
+// iCloud-synced checkout bakes phantom entries into the committed repo-map — and
+// CI's `repo_map --check` (run on a clean checkout that has no such copies) then
+// flags it STALE and fails the required `unit` gate. Skip them at the walk so the
+// generator is deterministic regardless of the working tree's sync artifacts
+// (task 1236; first hit on PR #165, the task 1233 ship).
+const CONFLICT_COPY_RE = / \d+\.js$/;
+const isConflictCopy = (name) => CONFLICT_COPY_RE.test(name);
+
+// Choose the symbols to surface for one file: exported public surface (ranked by reference
+// frequency); for an entry-point script with no exports, its declared fns/classes in source order.
+function pickForFile(f) {
+  const exAll = f.symbols.filter((s) => s.exported);
+  const ex = exAll.filter((s) => !isNoise(s.name));
+  if (ex.length) {
+    const list = [...ex].sort((a, b) => b.refs - a.refs || a.name.localeCompare(b.name));
+    return { list: list.slice(0, PER_FILE), pool: exAll.length };
+  }
+  const decl = f.symbols.filter((s) => (s.kind === 'fn' || s.kind === 'class') && !isNoise(s.name));
+  return { list: decl.slice(0, PER_FILE), pool: decl.length };
+}
+
+// ---- file walk -------------------------------------------------------------
+
+function walk(absRoot, out) {
+  let st;
+  try { st = fs.statSync(absRoot); } catch { return; }
+  if (st.isFile()) {
+    const base = path.basename(absRoot);
+    if (absRoot.endsWith('.js') && !isConflictCopy(base)) out.push(absRoot);
+    return;
+  }
+  if (!st.isDirectory()) return;
+  for (const ent of fs.readdirSync(absRoot, { withFileTypes: true })) {
+    if (ent.isDirectory()) {
+      if (EXCLUDE_DIR.has(ent.name)) continue;
+      walk(path.join(absRoot, ent.name), out);
+    } else if (ent.isFile() && ent.name.endsWith('.js') && !isConflictCopy(ent.name)) {
+      out.push(path.join(absRoot, ent.name));
+    }
+  }
+}
+
+// repo-relative POSIX path for an abs file under EITHER root (core package or instance repo).
+const relOf = (abs) => {
+  for (const base of [CORE_ROOT, INSTANCE_ROOT]) {
+    const r = path.relative(base, abs);
+    if (r && !r.startsWith('..') && !path.isAbsolute(r)) return r.split(path.sep).join('/');
+  }
+  return path.relative(CORE_ROOT, abs).split(path.sep).join('/');
+};
+
+function collectFiles() {
+  const files = [];
+  for (const root of CORE_SCAN_ROOTS) walk(path.join(CORE_ROOT, root), files);
+  for (const root of INSTANCE_SCAN_ROOTS) walk(path.join(INSTANCE_ROOT, root), files);
+  for (const r of MODULE_ROOTS) walk(path.join(r, MODULE_SCAN_ROOT), files); // modules ship from both roots
+  // stable, de-duped BY repo-relative path (a shared checkout would otherwise list a module twice)
+  const seen = new Set();
+  const uniq = [];
+  for (const abs of [...new Set(files)].sort()) {
+    const r = relOf(abs);
+    if (seen.has(r)) continue;
+    seen.add(r);
+    uniq.push(abs);
+  }
+  return uniq;
+}
+
+// ---- symbol extraction (col-0 declarations + exports) ----------------------
+
+const RE_FUNC = /^(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(([^)]*)\)?/;
+const RE_CLASS = /^class\s+([A-Za-z_$][\w$]*)/;
+// const NAME = (a,b) => | function(a,b) | async (a,b) => | require(...) | value | {…}
+const RE_DECL = /^(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(.*)$/;
+
+function rhsKindAndSig(rhs) {
+  let m;
+  if ((m = rhs.match(/^async\s+function\s*\(([^)]*)\)?/)) || (m = rhs.match(/^function\s*\(([^)]*)\)?/))) {
+    return { kind: 'fn', sig: m[1] };
+  }
+  if ((m = rhs.match(/^async\s*\(([^)]*)\)?\s*=>/)) || (m = rhs.match(/^\(([^)]*)\)?\s*=>/))) {
+    return { kind: 'fn', sig: m[1] };
+  }
+  if ((m = rhs.match(/^async\s+([A-Za-z_$][\w$]*)\s*=>/)) || (m = rhs.match(/^([A-Za-z_$][\w$]*)\s*=>/))) {
+    return { kind: 'fn', sig: m[1] };
+  }
+  if (/^require\(/.test(rhs)) return { kind: 'import', sig: '' };
+  if (/^\{/.test(rhs)) return { kind: 'obj', sig: '' };
+  if (/^(?:new\s+)?[A-Za-z_$][\w$.]*\s*\(/.test(rhs)) return { kind: 'val', sig: '' };
+  return { kind: 'const', sig: '' };
+}
+
+function parseExports(src) {
+  const exported = new Set();
+  let m;
+  // module.exports.NAME = / exports.NAME =
+  const reDot = /(?:module\.)?exports\.([A-Za-z_$][\w$]*)\s*=/g;
+  while ((m = reDot.exec(src))) exported.add(m[1]);
+  // module.exports = { a, b: x, c }   (also handles multi-line object)
+  const reObj = /module\.exports\s*=\s*\{([\s\S]*?)\}/g;
+  while ((m = reObj.exec(src))) {
+    for (const part of m[1].split(',')) {
+      const key = part.split(':')[0].trim().replace(/^\.\.\./, '').trim();
+      if (/^[A-Za-z_$][\w$]*$/.test(key)) exported.add(key);
+    }
+  }
+  // module.exports = NAME
+  const reSingle = /module\.exports\s*=\s*([A-Za-z_$][\w$]*)\s*;/g;
+  while ((m = reSingle.exec(src))) exported.add(m[1]);
+  return exported;
+}
+
+function extractFile(abs) {
+  const src = fs.readFileSync(abs, 'utf8');
+  const lines = src.split('\n');
+  const exported = parseExports(src);
+  const symbols = [];
+  for (const raw of lines) {
+    // col-0 declarations only — commented-out / nested code is indented or comment-led
+    if (/^[\s/*]/.test(raw)) continue;
+    let m;
+    if ((m = raw.match(RE_FUNC))) {
+      symbols.push({ name: m[1], kind: 'fn', sig: (m[2] || '').trim() });
+    } else if ((m = raw.match(RE_CLASS))) {
+      symbols.push({ name: m[1], kind: 'class', sig: '' });
+    } else if ((m = raw.match(RE_DECL))) {
+      const { kind, sig } = rhsKindAndSig(m[2].trim());
+      if (kind === 'import') continue; // requires aren't navigation symbols
+      symbols.push({ name: m[1], kind, sig: (sig || '').trim() });
+    }
+  }
+  // de-dupe by name (keep first), tag exported
+  const seen = new Set();
+  const uniq = [];
+  for (const s of symbols) {
+    if (seen.has(s.name)) continue;
+    seen.add(s.name);
+    uniq.push({ ...s, exported: exported.has(s.name) });
+  }
+  return uniq;
+}
+
+// ---- reference frequency (token tally across the whole corpus) -------------
+
+function buildRefCounts(files) {
+  const counts = new Map();
+  const reId = /[A-Za-z_$][\w$]*/g;
+  for (const abs of files) {
+    const src = fs.readFileSync(abs, 'utf8');
+    let m;
+    while ((m = reId.exec(src))) {
+      const id = m[0];
+      counts.set(id, (counts.get(id) || 0) + 1);
+    }
+  }
+  return counts;
+}
+
+// ---- model -----------------------------------------------------------------
+
+function buildModel() {
+  const files = collectFiles();
+  const refs = buildRefCounts(files);
+  const byFile = []; // {rel, symbols:[{name,kind,sig,exported,refs}]}
+  const allSyms = [];
+  for (const abs of files) {
+    const rel = relOf(abs); // root-aware: a module file may live under the instance repo post-split
+    const syms = extractFile(abs).map((s) => ({ ...s, refs: refs.get(s.name) || 0, file: rel }));
+    byFile.push({ rel, symbols: syms });
+    allSyms.push(...syms);
+  }
+  return { files, byFile, allSyms };
+}
+
+function fmtSig(s) {
+  if (s.kind === 'fn') {
+    let sig = s.sig || '';
+    if (sig.length > SIG_MAX) sig = sig.slice(0, SIG_MAX) + '…';
+    return `${s.name}(${sig})`;
+  }
+  if (s.kind === 'class') return `class ${s.name}`;
+  return s.name;
+}
+
+// ---- rendering: docs/repo-map.md -------------------------------------------
+
+function renderRepoMap(model) {
+  const L = [];
+  L.push('# Repo map — generated symbol skeleton');
+  L.push('');
+  L.push('> **AUTO-GENERATED — do not hand-edit.** Regenerate with `node scripts/gds/gen-repo-map.js` (runs on deploy, like `gen-diagrams.js`). Path B of the 2026-06-18 context-cliff plan — a portable-core altitude map ([ADR 0062](adr/0062-medusa-instance-model-decoupling.md) §9 · [ADR 0063](adr/0063-generated-repo-map-symbol-skeleton.md)). Complements the lexical recall layer ([ADR 0060](adr/0060-gds-retrieval-layer.md)), which indexes *prose*; this indexes *code*.');
+  L.push('>');
+  L.push(`> **Scope:** \`${SCAN_ROOTS.join('`, `')}\` — ${model.files.length} JS files, ${model.allSyms.length} top-level symbols. (Tests + \`node_modules\` + vendored libs excluded.) Symbols ranked by reference frequency across the scanned corpus.`);
+  L.push('');
+
+  // Global top-N: exported surface (cross-file reachable in CommonJS), minus generic noise.
+  const top = model.allSyms
+    .filter((s) => s.exported && !isNoise(s.name))
+    .sort((a, b) => b.refs - a.refs || a.name.localeCompare(b.name) || a.file.localeCompare(b.file))
+    .slice(0, TOP_GLOBAL);
+  L.push(`## Top ${TOP_GLOBAL} exported symbols by reference frequency`);
+  L.push('');
+  L.push('| symbol | kind | file | refs |');
+  L.push('|---|---|---|---|');
+  for (const s of top) L.push(`| \`${fmtSig(s)}\` | ${s.kind} | \`${s.file}\` | ${s.refs} |`);
+  L.push('');
+
+  // Per-directory exported signatures
+  L.push('## By directory — exported signatures');
+  L.push('');
+  const dirs = new Map();
+  for (const f of model.byFile) {
+    const dir = f.rel.includes('/') ? f.rel.slice(0, f.rel.lastIndexOf('/')) : '.';
+    if (!dirs.has(dir)) dirs.set(dir, []);
+    dirs.get(dir).push(f);
+  }
+  for (const dir of [...dirs.keys()].sort()) {
+    const fileEntries = dirs.get(dir).sort((a, b) => a.rel.localeCompare(b.rel));
+    const rendered = [];
+    for (const f of fileEntries) {
+      const { list, pool } = pickForFile(f);
+      if (!list.length) continue;
+      const base = f.rel.slice(f.rel.lastIndexOf('/') + 1);
+      const more = pool - list.length;
+      rendered.push(`- \`${base}\` — ${list.map((s) => '`' + fmtSig(s) + '`').join(', ')}${more > 0 ? ` _(+${more} more)_` : ''}`);
+    }
+    if (!rendered.length) continue;
+    L.push(`### \`${dir}/\``);
+    L.push('');
+    L.push(...rendered);
+    L.push('');
+  }
+
+  // task 2013 — the DOCUMENTATION map: a link-graph for the key navigational docs
+  // (bullet 193: "click architecture.md → see the docs it links to") + STALENESS
+  // FLAGS (docs whose internal links/anchors docs-entropy can't resolve). This is
+  // the anti-drift mechanism that replaces the manual "remember to update the
+  // detail files" session-end chores (bullets 223/224/226): the flag surfaces
+  // mechanically what needs a touch-up, so it isn't left to memory.
+  L.push(...renderDocMapLines());
+
+  return L.join('\n').replace(/\n+$/, '') + '\n';
+}
+
+// The curated set of top navigational docs whose outbound doc-links are worth
+// graphing (the whole 399-file graph would be noise). An agent lands on one of
+// these and can see, without opening it, which docs it points at.
+const KEY_DOCS = [
+  'CLAUDE.md',
+  'docs/architecture.md',
+  'docs/project-context.md',
+  'docs/file-map.md',
+  'docs/branding-contract.md',
+  'docs/api-reference.md',
+  'docs/adr/README.md',
+  'docs/canonical-permissions.md',
+];
+
+// Resolve a markdown link href (relative to the doc it appears in) to a
+// repo-relative .md path, or null if it isn't an internal .md target.
+function resolveDocLink(fromRel, href) {
+  const noAnchor = String(href).split('#')[0];
+  if (!noAnchor || !/\.md$/i.test(noAnchor)) return null;
+  const fromDir = fromRel.includes('/') ? fromRel.slice(0, fromRel.lastIndexOf('/')) : '.';
+  const resolved = path.posix.normalize(path.posix.join(fromDir, noAnchor));
+  return resolved.startsWith('..') ? null : resolved;
+}
+
+function renderDocMapLines() {
+  const L = [];
+  let files;
+  try { files = docsEntropy.collectMarkdownFiles(); } catch { return L; }
+  const fileSet = new Set(files);
+
+  L.push('');
+  L.push('## Documentation map — link-graph + staleness (task 2013)');
+  L.push('');
+  L.push('> Generated from the same detectors as `docs-entropy.js`. The link-graph lets an agent see a key doc\'s outbound doc-links without opening it; the staleness flags surface docs whose internal links/anchors no longer resolve — the anti-drift signal that replaces the manual "remember to update the detail files" chore.');
+  L.push('');
+
+  // Link-graph for the curated key docs.
+  L.push('### Key-doc link-graph');
+  L.push('');
+  L.push('| doc | links to |');
+  L.push('|---|---|');
+  for (const doc of KEY_DOCS) {
+    if (!fileSet.has(doc)) continue;
+    let parsed;
+    try { parsed = docsEntropy.parseFile(path.join(INSTANCE_ROOT, doc)); } catch { parsed = null; }
+    if (!parsed) { try { parsed = docsEntropy.parseFile(path.join(CORE_ROOT, doc)); } catch { parsed = null; } }
+    const targets = new Set();
+    for (const lk of (parsed && parsed.links) || []) {
+      const t = resolveDocLink(doc, lk.href);
+      if (t && t !== doc && fileSet.has(t)) targets.add(t);
+    }
+    const list = [...targets].sort();
+    const shown = list.slice(0, 12).map((t) => `\`${t}\``).join(', ');
+    const more = list.length > 12 ? ` _(+${list.length - 12} more)_` : '';
+    L.push(`| \`${doc}\` | ${list.length ? shown + more : '—'} |`);
+  }
+  L.push('');
+
+  // Staleness flags: docs with unresolved internal links/anchors.
+  let findings = [];
+  try { findings = docsEntropy.scanStaleLinks(files) || []; } catch { findings = []; }
+  const byFile = new Map();
+  for (const f of findings) {
+    if (!byFile.has(f.file)) byFile.set(f.file, []);
+    byFile.get(f.file).push(f);
+  }
+  L.push('### Docs needing a touch-up (staleness flags)');
+  L.push('');
+  if (byFile.size === 0) {
+    L.push('_None — every tracked doc\'s internal links + anchors resolve._');
+  } else {
+    L.push(`${byFile.size} doc(s) carry an unresolved internal link or anchor (top 25 by count):`);
+    L.push('');
+    L.push('| doc | unresolved links |');
+    L.push('|---|---|');
+    const rows = [...byFile.entries()].sort((a, b) => b[1].length - a[1].length).slice(0, 25);
+    for (const [file, fs2] of rows) L.push(`| \`${file}\` | ${fs2.length} |`);
+  }
+  L.push('');
+  return L;
+}
+
+// ---- rendering: nested-doc generated block ---------------------------------
+
+function renderNestedBlock(model, dir) {
+  const prefix = dir.endsWith('/') ? dir : dir + '/';
+  const here = model.byFile
+    .filter((f) => {
+      const d = f.rel.includes('/') ? f.rel.slice(0, f.rel.lastIndexOf('/')) : '.';
+      return d === dir; // non-recursive: files directly in this dir
+    })
+    .sort((a, b) => a.rel.localeCompare(b.rel));
+  const L = [];
+  L.push(BEGIN);
+  L.push(`**Symbol skeleton (generated from the code — do not hand-edit; refresh: \`node scripts/gds/gen-repo-map.js\`).** Exported signatures, most-referenced first. The interpretive notes above are hand-written; this factual list is regenerated on deploy so it can't drift ([ADR 0063](${path.relative(path.join(REPO_ROOT, dir), path.join(REPO_ROOT, 'docs/adr/0063-generated-repo-map-symbol-skeleton.md')).split(path.sep).join('/')})).`);
+  L.push('');
+  for (const f of here) {
+    const { list, pool } = pickForFile(f);
+    if (!list.length) continue;
+    const base = f.rel.slice(prefix.length);
+    const more = pool - list.length;
+    L.push(`- \`${base}\` — ${list.map((s) => '`' + fmtSig(s) + '`').join(', ')}${more > 0 ? ` _(+${more} more)_` : ''}`);
+  }
+  L.push(END);
+  return L.join('\n');
+}
+
+function injectBlock(existing, block) {
+  const b = existing.indexOf(BEGIN);
+  const e = existing.indexOf(END);
+  if (b !== -1 && e !== -1 && e > b) {
+    return existing.slice(0, b) + block + existing.slice(e + END.length);
+  }
+  // insert before "**See also.**" if present, else append
+  const anchor = existing.indexOf('**See also.**');
+  if (anchor !== -1) {
+    return existing.slice(0, anchor) + block + '\n\n' + existing.slice(anchor);
+  }
+  return existing.replace(/\n*$/, '') + '\n\n' + block + '\n';
+}
+
+// ---- main ------------------------------------------------------------------
+
+function main() {
+  // Two artifact BUCKETS, gated separately since ADR 0110 (task 1926):
+  //   • 'whole' — docs/repo-map.md, which is now GITIGNORED and regenerated at
+  //     deploy / box-source-fetch (the gen-atlas.js model), so it carries no
+  //     committed copy and two parallel branches can never collide on it.
+  //   • 'block' — the generated symbol BLOCK inside each nested CLAUDE.md, which
+  //     stays hand-written prose + a tracked block, so it MUST stay fresh in git.
+  // `--check`       → both buckets (back-compat; a full local sanity check).
+  // `--check-block` → block bucket only (the HARD per-PR CI gate in fitness.js).
+  // `--check-whole` → whole-file bucket only (used by nothing hard; deploy owns it).
+  const checkAll = process.argv.includes('--check');
+  const checkWhole = process.argv.includes('--check-whole');
+  const checkBlock = process.argv.includes('--check-block');
+  const model = buildModel();
+
+  if (process.argv.includes('--json')) {
+    process.stdout.write(JSON.stringify(model, null, 2) + '\n');
+    return;
+  }
+
+  const writes = [];
+  // 1) docs/repo-map.md (whole-file; gitignored since ADR 0110 — a `write` here on a
+  //    fresh checkout just means "absent, would be created", which is expected)
+  const mapPath = path.join(REPO_ROOT, 'docs', 'repo-map.md');
+  const mapNext = renderRepoMap(model);
+  const mapCur = fs.existsSync(mapPath) ? fs.readFileSync(mapPath, 'utf8') : '';
+  if (mapCur !== mapNext) writes.push({ full: mapPath, content: mapNext, rel: 'docs/repo-map.md', bucket: 'whole' });
+
+  // 2) nested CLAUDE.md generated blocks (tracked; the HARD-gated bucket)
+  for (const dir of NESTED_DIRS) {
+    const docPath = path.join(REPO_ROOT, dir, 'CLAUDE.md');
+    if (!fs.existsSync(docPath)) {
+      console.error(`gen-repo-map: WARN nested doc missing, skipping: ${dir}/CLAUDE.md`);
+      continue;
+    }
+    const cur = fs.readFileSync(docPath, 'utf8');
+    const next = injectBlock(cur, renderNestedBlock(model, dir));
+    if (cur !== next) writes.push({ full: docPath, content: next, rel: `${dir}/CLAUDE.md`, bucket: 'block' });
+  }
+
+  if (checkAll || checkWhole || checkBlock) {
+    const wantBlock = checkAll || checkBlock;
+    const wantWhole = checkAll || checkWhole;
+    const stale = writes.filter((w) => (w.bucket === 'block' && wantBlock) || (w.bucket === 'whole' && wantWhole));
+    if (stale.length) {
+      console.error(`gen-repo-map ${checkBlock ? '--check-block' : checkWhole ? '--check-whole' : '--check'}: STALE — would update ${stale.map((w) => w.rel).join(', ')}`);
+      console.error('  run: node scripts/gds/gen-repo-map.js  (and commit any TRACKED files it changes)');
+      process.exit(2);
+    }
+    console.log(`gen-repo-map ${checkBlock ? '--check-block' : checkWhole ? '--check-whole' : '--check'}: up to date.`);
+    return;
+  }
+
+  if (!writes.length) {
+    console.log('gen-repo-map: repo map already current — no changes.');
+    return;
+  }
+  for (const w of writes) fs.writeFileSync(w.full, w.content);
+  console.log(`gen-repo-map: wrote ${writes.length} file(s): ${writes.map((w) => w.rel).join(', ')}`);
+}
+
+if (require.main === module) main();
+
+// Exported so the git merge driver / ship self-heal (scripts/gds/git-merge-regen.js,
+// task 1243) can regenerate a generated file's content from the MERGED working-tree
+// code WITHOUT shelling out or re-parsing stdout. The require.main guard above keeps
+// `require('./gen-repo-map')` side-effect-free (it no longer runs main()).
+module.exports = { BEGIN, END, NESTED_DIRS, buildModel, renderRepoMap, renderNestedBlock, injectBlock };