@bongos/core 1.21.174 → 1.21.176

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

@@ -1,540 +1,7 @@
 #!/usr/bin/env node
+// scripts/gds/gen-repo-map.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/gen-repo-map.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 '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 any checkout 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
-//   node scripts/gds/gen-repo-map.js --whole-only  # WRITE docs/repo-map.md only; never touch the
-//                                                  # tracked nested blocks (what a SPARSE
-//                                                  # checkout must use — task 1002962)
-// docs/repo-map.md is GITIGNORED + regenerated at deploy 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');
-const { sameContent } = require('./gen-freshness'); // eol-insensitive freshness (CRLF checkouts)
-
-// 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.
-// scripts/gds dropped (task 1003548): its block had grown to ~40k chars — 76% of a file every builder
-// session loads when it touches claim/ship. docs/repo-map.md still carries the full index.
-const NESTED_DIRS = ['src/bongos', 'src/bongos/routes'];
-
-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 (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');
-  // WRITE-side bucket selection, the sibling of the --check-* flags above (task
-  // 1002962). --whole-only regenerates the GITIGNORED docs/repo-map.md and leaves
-  // the TRACKED nested blocks alone.
-  //
-  // WHY a caller ever needs this: a SPARSE checkout materializes only part of the
-  // tree. The block ordering is `b.refs - a.refs || name`, and `refs` counts
-  // references across the VISIBLE corpus — so a checkout with 7 of 20 modules
-  // computes different counts and emits a legitimately different block. Written
-  // into a tracked file that dirties the working tree, and the NEXT `git pull`
-  // aborts with "local changes would be overwritten" — a silent, permanent sync
-  // deadlock (one checkout sat 257 commits behind for three days). A sparse
-  // checkout CONSUMES these blocks; they arrive correct with the pull, generated
-  // by CI from the whole tree. Only a full checkout may produce them.
-  const wholeOnly = process.argv.includes('--whole-only');
-  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 (!sameContent(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).
-  //     Skipped entirely under --whole-only — see the flag's rationale above.
-  for (const dir of (wholeOnly ? [] : 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 (!sameContent(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 };
+require('../bongos/forwarder.js').forward(module, 'gen-repo-map.js');