@bongos/core 1.21.174 → 1.21.176

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

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+// scripts/bongos/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 is required LAZILY, inside the one rule that uses it —
+// 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 pointer stub (task 1003537), written wholesale by gen-api-docs.js.
+// The spec, the reference and the six typed-client files that used to sit in this set
+// are no longer committed (task 1004866: gitignored, rebuilt from the routes), so git
+// never hands them to this driver and they have no rule here.
+const API_DOC_FILES = new Set([
+  'docs/routes-permissions.md',
+]);
+
+// 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 API set above is spread in whole — the stub is generated end to end,
+// so it takes 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,
+]);
+
+// 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 pointer stub (task 1003537): gen-api-docs.js writes it wholesale,
+  // so like docs/repo-map.md below it ignores all three merge sides and rebuilds.
+  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 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 };