@bongos/core 1.21.174 → 1.21.176

package/scripts/gds/git-merge-regen.js

@@ -1,292 +1,7 @@
 #!/usr/bin/env node
-// scripts/gds/git-merge-regen.js — auto-heal merge conflicts in GENERATED files
-// (task 1243; the prevention for the task 1234 / PR #167 stall).
-//
-// docs/repo-map.md is a 100%-generated index (ADR 0063); the nested CLAUDE.md docs
-// (NESTED_DIRS) carry a generated symbol-skeleton BLOCK between markers. Two
-// parallel branches regenerate them differently, so they CONFLICT on every merge
-// with main — and a `merge=union`/`ours` attribute can't fix it because the
-// committed file must equal the MERGED code or CI's `repo_map --check` fails STALE.
-// The only correct resolution is to REGENERATE from the merged tree. This module is
-// both:
-//   • a git merge driver (registered by install-git-hooks.js, declared in
-//     .gitattributes) — invoked as `git-merge-regen.js %O %A %B %P` during any
-//     `git merge` (manual, /merge-mode, ship's pre-stage); and
-//   • a library (regenerateResolved / resolveInWorktree) reused by ship.js's
-//     mergeMainIntoBranch self-heal so the heal runs even where the driver isn't
-//     installed per-clone.
-//
-// THE DRIVER ONLY FIRES ON A CONFLICT. A merge that lands CLEAN still leaves the
-// generated docs describing the pre-merge tree — new symbols, a new session log and a
-// new skill all arrive without conflicting. Three things close that: ship.js (at ship
-// time), the server's conflict-resolve.js step 7b (for a PR it resolves), and
-// `.husky/post-merge` (task 1001431) for the bare local `git merge` / `git pull` that
-// neither of those covers.
-//
-// SAFETY: it regenerates the GENERATED content and 3-way-merges the hand-written
-// parts of nested docs; it succeeds ONLY if no conflict markers remain. A genuine
-// hand-written conflict falls through to a normal git conflict — it never invents a
-// resolution or clobbers a real edit.
-//
-// ⚠ THE DRIVER'S OUTPUT IS PROVISIONAL FOR ANY TREE-SCANNING ARTIFACT (task 1003546).
-// Every rule below that rebuilds by SCANNING THE WORKING TREE — copy-inventory.js's
-// registry pair, gen-repo-map's map + nested blocks, gen-file-map's sections — is
-// invoked BY git, DURING the merge, when that tree is still the PRE-merge (ours)
-// tree. So the driver writes an artifact describing the branch, git completes the
-// merge underneath it, and the merge lands CLEAN (exit 0, no unmerged paths, no
-// markers) carrying content that matches neither side nor the merged tree. Measured:
-// two branches each shifting lines in one scanned UI file merge clean and the merge
-// commit's docs/copy-registry.json is byte-identical to ours, silently dropping the
-// other side's line numbers (PR #536 / task 1003544).
-// It is still worth running — it clears the markers so the merge completes at all —
-// but it is NOT the authority. Whoever OWNS the merge must regenerate afterwards, on
-// the final tree, and commit the drift: the server does it in conflict-resolve.js
-// step 7b, and a post-merge `resolveInWorktree` call (ship-preflight-steps.js) is
-// correct for the same reason — by then git has written every cleanly-merged path.
-// Do NOT add a rule here and assume the merge is thereby correct; a line-numbered or
-// aggregate-carrying artifact cannot be resolved from the three merge sides at all.
-
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-const { spawnSync } = require('node:child_process');
-const G = require('./gen-repo-map');
-const FM = require('./gen-file-map');
-const SI = require('./gen-session-index');
-const CI = require('./copy-inventory');
-// gen-api-docs / gen-api-client are required LAZILY, inside the two rules that use them —
-// deliberately NOT here (task 1003537). gen-api-docs pulls src/bongos/routes/_helpers.js
-// for its LIMITS caps, and ship.js requires this module, so an eager require put a server
-// route file into the boot of every `bongos` subcommand. tests/module_api_lazy.mjs catches
-// exactly that. require() is cached, so the merge path pays the load once and the CLI
-// path never pays it at all.
-
-const REPO_ROOT = path.resolve(__dirname, '..', '..');
-
-// The generated API contract (task 1003537). gen-api-docs.js writes all three of these
-// wholesale from a scan of the route files, so one build() call answers whichever of
-// them git hands us.
-const API_DOC_FILES = new Set([
-  'docs/api/openapi.json',
-  'docs/api-reference.md',
-  'docs/routes-permissions.md',
-]);
-
-// The generated client (task 1003537), written wholesale from the spec by
-// gen-api-client.js. These six names mirror the keys of its build().files; the
-// lockstep is asserted in tests/git_merge_regen.mjs rather than derived here, because
-// deriving it would mean running the generator at require time. NOTE what is absent:
-// clients/bongos-client/examples/hello-world.mjs is hand-written and must stay out of
-// this set, or the driver would force a conflict on a file git can merge by itself.
-const API_CLIENT_DIR = 'clients/bongos-client';
-const API_CLIENT_FILES = new Set([
-  'index.mjs',
-  'index.cjs',
-  'bongos-client.global.js',
-  'index.d.ts',
-  'package.json',
-  'README.md',
-].map((n) => `${API_CLIENT_DIR}/${n}`));
-
-// The files this driver knows how to regenerate. docs/repo-map.md and
-// docs/session-log-index.md are whole-file; each NESTED_DIRS CLAUDE.md is
-// hand-written prose with one generated block; docs/file-map.md is hand-written
-// prose with TWO generated section blocks (ADR 0066). (task 1385: session-log-index
-// joined so a confirmed PR that only conflicts on it self-heals like the rest.)
-// docs/copy-inventory.md + docs/copy-registry.json (task 1003543) are the copy
-// registry's own pair — like repo-map.md, `copy-inventory.js` writes them
-// wholesale from a tree scan with nothing hand-authored in either, so any two
-// branches that both touch hall/status/landing copy regenerate them differently
-// and conflict on ordinary text; they join the whole-file group for the same
-// reason session-log-index.md did.
-// task 1001431: the ROOT CLAUDE.md joined too. It is mostly hand-written, but §13 carries
-// the bounded BEGIN/END GENERATED SESSION-LOG SNIPPET block (ADR 0062 §8) — so two sessions
-// that each add a session-log file regenerate that block differently and ALWAYS conflict
-// there, and nothing healed it: the driver did not know the file, and `merge=union` would be
-// wrong for prose. Same shape as docs/file-map.md (3-way-merge the prose, re-render the block).
-// task 1003537: the two API sets above are spread in whole — every one of those nine files
-// is generated end to end, so they take the docs/repo-map.md path (ignore all three merge
-// sides, rebuild). They are named up there rather than inline here because the rules below
-// test set membership, and tests/git_merge_regen.mjs cross-checks them against .gitattributes.
-const REGENERABLE = new Set([
-  'CLAUDE.md',
-  'docs/repo-map.md',
-  'docs/file-map.md',
-  'docs/session-log-index.md',
-  'docs/copy-inventory.md',
-  'docs/copy-registry.json',
-  // task 1004775: merged per page (page-reader.js mergeReadingDocs), see the rule below.
-  'docs/page-readings.json',
-  ...G.NESTED_DIRS.map((d) => `${d}/CLAUDE.md`),
-  ...API_DOC_FILES,
-  ...API_CLIENT_FILES,
-]);
-
-// A line that begins with a git conflict marker. If any survives our resolution,
-// the conflict is in hand-written content and we must NOT auto-resolve.
-const MARKER_RE = /^(<{7}|={7}|>{7})/m;
-
-function hasMarkers(s) {
-  return MARKER_RE.test(s);
-}
-
-// 3-way merge three content strings via `git merge-file` (writes conflict markers
-// where ours/theirs truly diverge). Returns the merged text (markers and all).
-function threeWayMerge(base, ours, theirs) {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-merge-'));
-  try {
-    const o = path.join(dir, 'ours');
-    const b = path.join(dir, 'base');
-    const t = path.join(dir, 'theirs');
-    fs.writeFileSync(o, ours);
-    fs.writeFileSync(b, base);
-    fs.writeFileSync(t, theirs);
-    // `git merge-file -p OURS BASE THEIRS` → merged result to stdout. Exit code is
-    // the conflict count (>0) or <0 on error; we want the body either way, so read
-    // stdout regardless of status.
-    const r = spawnSync('git', ['merge-file', '-p', o, b, t], { encoding: 'utf8' });
-    return typeof r.stdout === 'string' ? r.stdout : ours;
-  } finally {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
-}
-
-// Produce the resolved content for one generated file from its three merge inputs.
-// Returns { content, ok }: ok=false means a real (hand-written) conflict remains —
-// the caller must leave it for a human.
-function regenerateResolved(relpath, { base = '', ours = '', theirs = '' } = {}) {
-  if (!REGENERABLE.has(relpath)) return { content: null, ok: false };
-
-  // docs/session-log-index.md is fully generated from the session-log files
-  // (gen-session-index.js, ADR 0062 §8) — like docs/repo-map.md it ignores all
-  // three merge sides and rebuilds from the merged tree. Handled before
-  // buildModel() since it needs none of the code-symbol model.
-  if (relpath === 'docs/session-log-index.md') {
-    return { content: SI.renderIndex(SI.collectEntries()), ok: true };
-  }
-
-  // docs/copy-registry.json / docs/copy-inventory.md: both artifacts of one scan
-  // (copy-inventory.js), fully generated — ignore all three sides, rebuild from
-  // the merged tree. Reuse buildRegistry() rather than shelling out to write() so
-  // this stays in-process like the repo-map/session-index heals above.
-  if (relpath === 'docs/copy-registry.json') {
-    return { content: `${JSON.stringify(CI.buildRegistry(), null, 2)}\n`, ok: true };
-  }
-  // docs/page-readings.json (task 1004775): one entry per page, and a re-read needs a
-  // browser no merge has. Two approved page-tweak rounds re-read DIFFERENT pages and
-  // both rewrite the top counts line, so every pair conflicted and the second round
-  // stranded for a person. Merge it per page from the three sides and recompute the
-  // counts (page-reader.js mergeReadingDocs). Unlike the scans above it reads the
-  // merge sides, not the tree, so it is not provisional; a page BOTH sides re-read
-  // differently is a real conflict and stays one.
-  if (relpath === 'docs/page-readings.json') {
-    const PR = require('./page-reader');
-    const m = PR.mergeReadingDocs({ base, ours, theirs });
-    return m.ok ? { content: m.content, ok: true } : { content: null, ok: false };
-  }
-  if (relpath === 'docs/copy-inventory.md') {
-    return { content: CI.renderReport(CI.buildRegistry()), ok: true };
-  }
-
-  // The generated API contract (task 1003537): gen-api-docs.js writes openapi.json,
-  // api-reference.md and routes-permissions.md wholesale from a scan of the route files
-  // — nothing hand-authored in any of them — so like docs/repo-map.md below they ignore
-  // all three merge sides and rebuild. One build() yields all three; take the one asked
-  // for. This is the rule that ends the task-1002334 stall, where four merge → reship
-  // cycles each lost the race to a fresh textual conflict in exactly these files.
-  if (API_DOC_FILES.has(relpath)) {
-    const AD = require('./gen-api-docs'); // lazy — see the require block up top
-    const f = AD.build().files.find((x) => x.rel === relpath);
-    return { content: f.content, ok: true };
-  }
-
-  // The generated client (task 1003537): gen-api-client.js renders all six files from
-  // the spec, so it heals the same way. Hand it a FRESHLY BUILT spec instead of letting
-  // build() read docs/api/openapi.json off disk — mid-merge that file is very often the
-  // one git has just written conflict markers into, and JSON.parse would throw on them
-  // (an uncaught throw here exits non-zero, which git reads as "unresolved", so the
-  // failure would be a silent fallback to a textual conflict on the very files this
-  // rule exists to heal). Rebuilding also keeps the client consistent with the
-  // api-reference.md the same merge is healing.
-  if (API_CLIENT_FILES.has(relpath)) {
-    const AD = require('./gen-api-docs');   // lazy — see the require block up top
-    const AC = require('./gen-api-client'); // lazy — same reason
-    const { files } = AC.build(AD.buildOpenapi(AD.extractModel()));
-    return { content: files[relpath.slice(API_CLIENT_DIR.length + 1)], ok: true };
-  }
-
-  // The ROOT CLAUDE.md (task 1001431): hand-written prose carrying ONE generated block, the
-  // §13 session-log snippet. 3-way-merge the prose, then re-render the snippet from the
-  // session-log files on disk. Must be handled BEFORE the nested-CLAUDE.md fallthrough below,
-  // which derives a directory by stripping `/CLAUDE.md` — for the root path that strips
-  // nothing and would ask gen-repo-map for a symbol block for a directory named "CLAUDE.md".
-  // It also needs none of the code-symbol model, so it sits with the other pre-buildModel rules.
-  //   Same provisionality caveat as the whole-file rules above: collectEntries() scans the
-  // working tree, which during a merge is still ours, so the block this writes describes our
-  // side. That is what makes the merge COMPLETE; the post-merge regeneration (conflict-resolve
-  // step 7b / ship-preflight-steps' resolveInWorktree) is what makes it CORRECT.
-  if (relpath === 'CLAUDE.md') {
-    const merged = threeWayMerge(base, ours, theirs);
-    const out = SI.injectSnippet(merged, SI.renderSnippet(SI.collectEntries()));
-    return { content: out, ok: !hasMarkers(out) };
-  }
-
-  const model = G.buildModel();
-
-  // docs/repo-map.md is fully generated — ignore all three sides, rebuild it.
-  if (relpath === 'docs/repo-map.md') {
-    return { content: G.renderRepoMap(model), ok: true };
-  }
-
-  // docs/file-map.md: hand-written prose with TWO generated section blocks (ADR 0066). 3-way-merge
-  // the prose, then overwrite each generated block with a fresh render from disk (the same dirs +
-  // notes sidecar gen-file-map reads). Two parallel branches that each add a skill conflict only in
-  // those blocks; regenerating from the merged tree is the one correct resolution.
-  if (relpath === 'docs/file-map.md') {
-    const merged = threeWayMerge(base, ours, theirs);
-    let out = merged;
-    for (const m of FM.buildModel()) out = FM.injectSection(out, m);
-    return { content: out, ok: !hasMarkers(out) };
-  }
-
-  // Nested CLAUDE.md: 3-way-merge the hand-written prose, then overwrite the
-  // generated block with a fresh render from the merged code.
-  const dir = relpath.replace(/\/CLAUDE\.md$/, '');
-  const merged = threeWayMerge(base, ours, theirs);
-  const out = G.injectBlock(merged, G.renderNestedBlock(model, dir));
-  return { content: out, ok: !hasMarkers(out) };
-}
-
-// Reused by ship.js mergeMainIntoBranch: resolve a conflicted file straight from the
-// index stages (:1 base, :2 ours, :3 theirs) of an in-progress `git merge`, writing
-// the result into the working tree. Returns true iff fully resolved.
-function resolveInWorktree(relpath) {
-  if (!REGENERABLE.has(relpath)) return false;
-  const stage = (n) => {
-    const r = spawnSync('git', ['show', `:${n}:${relpath}`], { cwd: REPO_ROOT, encoding: 'utf8' });
-    return r.status === 0 && typeof r.stdout === 'string' ? r.stdout : '';
-  };
-  const { content, ok } = regenerateResolved(relpath, { base: stage(1), ours: stage(2), theirs: stage(3) });
-  if (content == null || !ok) return false;
-  fs.writeFileSync(path.join(REPO_ROOT, relpath), content);
-  return true;
-}
-
-// git merge-driver entrypoint: `git-merge-regen.js %O %A %B %P`. Writes the resolved
-// content into %A (git takes %A as the merge result) and exits 0; exits 1 to signal
-// an unresolved conflict (git then leaves the normal conflict for a human).
-function runDriver(argv) {
-  const [O, A, B, P] = argv;
-  if (!A || !P) {
-    process.stderr.write('git-merge-regen: usage as a merge driver: %O %A %B %P\n');
-    process.exit(1);
-  }
-  const read = (p) => { try { return fs.readFileSync(p, 'utf8'); } catch { return ''; } };
-  const { content, ok } = regenerateResolved(P, { base: read(O), ours: read(A), theirs: read(B) });
-  if (content != null) fs.writeFileSync(A, content);
-  process.exit(ok ? 0 : 1);
-}
-
-if (require.main === module) runDriver(process.argv.slice(2));
-
-module.exports = { REGENERABLE, MARKER_RE, hasMarkers, threeWayMerge, regenerateResolved, resolveInWorktree };
+// scripts/gds/git-merge-regen.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/git-merge-regen.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';
+require('../bongos/forwarder.js').forward(module, 'git-merge-regen.js');