@bongos/core 1.17.0

package/tests/lifecycle_breakdown_view.mjs

@@ -0,0 +1,236 @@
+// tests/lifecycle_breakdown_view.mjs
+//
+// Coverage for V3.R23 / #243: version_lifecycle_breakdown must count ONLY
+// LEAF TASKS, the same way version_progress does. Pre-fix, the view was
+// defined in migration 012 with FILTER clauses that referenced t.status only —
+// it had no `NOT EXISTS (SELECT 1 FROM tasks c WHERE c.parent_task_id = t.id)`
+// guard. The result: a parent task with N shipped children inflated
+// shipped_count by N+1 (the parent itself + each child).
+//
+// Migration 034 replaces the view with the leaf predicate. This test proves
+// two properties:
+//
+//   1. The migration text itself contains the leaf predicate in EVERY
+//      per-state FILTER clause. (Static SQL assertion — protects against a
+//      future hand-edit dropping the guard from one state and not another.)
+//   2. The view's filter semantics, simulated in JS over a fixture of
+//      parent + 2 children, produces single counts — not double counts —
+//      AND the OLD pre-fix predicate on the SAME fixture would have
+//      double-counted. The "would have" half is the load-bearing proof that
+//      the migration actually changed behaviour, not just SQL text.
+//
+// No live DB. The view's predicate is pure (status + title + leaf-ness), so
+// reproducing it in JS gives high-fidelity coverage without spinning Postgres.
+//
+// Run:  node tests/lifecycle_breakdown_view.mjs
+
+import { strict as assert } from 'node:assert';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, '..');
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try {
+    await fn();
+    console.log(`  ok  ${name}`);
+    passed++;
+  } catch (err) {
+    console.error(`  FAIL ${name}`);
+    console.error('    ', err.message);
+    failed++;
+  }
+}
+
+// --- helpers -----------------------------------------------------------------
+
+// Mirrors the view's WHERE / FILTER predicate. Given the full tasks array
+// (so we can check children) and a candidate task t, decide whether it
+// counts toward the per-state breakdown.
+function leafPredicate(t, allTasks) {
+  if (!t) return false;
+  if (typeof t.title === 'string' && t.title.startsWith('__smoke__')) return false;
+  const hasChildren = allTasks.some((c) => c.parent_task_id === t.id);
+  return !hasChildren;
+}
+
+// Old pre-fix predicate (migration 012): per-state filter only on status +
+// __smoke__ title. NO leaf guard. We reproduce it so the test can demonstrate
+// the bug the migration fixes.
+function oldPredicate(t /*, allTasks */) {
+  if (!t) return false;
+  if (typeof t.title === 'string' && t.title.startsWith('__smoke__')) return false;
+  return true;
+}
+
+// Compute the per-state breakdown the way the NEW view does — leaf-only.
+function breakdownNew(tasks) {
+  const out = { completed_count: 0, confirmed_count: 0, shipped_count: 0 };
+  for (const t of tasks) {
+    if (!leafPredicate(t, tasks)) continue;
+    if (t.status === 'completed') out.completed_count++;
+    else if (t.status === 'confirmed') out.confirmed_count++;
+    else if (t.status === 'shipped') out.shipped_count++;
+  }
+  return out;
+}
+
+// Compute the per-state breakdown the way the OLD (buggy) view did — every row.
+function breakdownOld(tasks) {
+  const out = { completed_count: 0, confirmed_count: 0, shipped_count: 0 };
+  for (const t of tasks) {
+    if (!oldPredicate(t, tasks)) continue;
+    if (t.status === 'completed') out.completed_count++;
+    else if (t.status === 'confirmed') out.confirmed_count++;
+    else if (t.status === 'shipped') out.shipped_count++;
+  }
+  return out;
+}
+
+// --- tests -------------------------------------------------------------------
+
+await (async () => {
+  console.log('migration 034: view SQL text');
+
+  const migrationPath = join(repoRoot, 'migrations', '034_lifecycle_breakdown_leaf_only.sql');
+  const migrationSql = readFileSync(migrationPath, 'utf8');
+
+  await test('migration 034 defines version_lifecycle_breakdown', () => {
+    assert.ok(
+      /CREATE VIEW version_lifecycle_breakdown/i.test(migrationSql),
+      'migration 034 must (re)create version_lifecycle_breakdown'
+    );
+    assert.ok(
+      /DROP VIEW IF EXISTS version_lifecycle_breakdown/i.test(migrationSql),
+      'migration 034 must DROP the old view first (column-list safety)'
+    );
+  });
+
+  await test('each per-state FILTER clause carries the leaf predicate', () => {
+    // Split on "count(*) FILTER" — each chunk after the first should be
+    // a single FILTER clause body, and each must include the leaf guard.
+    // Match the predicate flexibly w.r.t. whitespace.
+    const leafGuard = /NOT\s+EXISTS\s*\(\s*SELECT\s+1\s+FROM\s+tasks\s+c\s+WHERE\s+c\.parent_task_id\s*=\s*t\.id\s*\)/i;
+
+    const filterChunks = migrationSql.split(/count\(\*\)\s+FILTER/i).slice(1);
+    assert.equal(
+      filterChunks.length, 3,
+      `expected 3 per-state FILTER clauses (completed / confirmed / shipped); found ${filterChunks.length}`
+    );
+
+    for (const [idx, chunk] of filterChunks.entries()) {
+      // Bound each chunk to its own closing paren-region — take up to the
+      // first ") AS <name>_count" so we don't pull the predicate from a
+      // neighbouring clause.
+      const body = chunk.split(/\)\s+AS\s+\w+_count/i)[0];
+      assert.ok(
+        leafGuard.test(body),
+        `FILTER clause #${idx + 1} must contain the leaf guard NOT EXISTS (...). body was: ${body.slice(0, 200)}…`
+      );
+    }
+  });
+
+  await test('migration 034 bumps the migration counter and registers itself', () => {
+    assert.ok(
+      /UPDATE\s+migration_counter\s+SET\s+next_number\s*=\s*GREATEST\(next_number,\s*35\)/i.test(migrationSql),
+      'migration must bump migration_counter.next_number to >= 35'
+    );
+    assert.ok(
+      /INSERT\s+INTO\s+schema_migrations\s*\(\s*version\s*\)\s*VALUES\s*\(\s*'034_lifecycle_breakdown_leaf_only'/i.test(migrationSql),
+      "migration must INSERT INTO schema_migrations the '034_lifecycle_breakdown_leaf_only' row"
+    );
+  });
+
+  console.log('view semantics: leaf-only rollup');
+
+  // Fixture: a parent task with 2 shipped children, both inside one version.
+  // The bug being fixed: pre-fix rollup reports shipped_count = 3 (parent +
+  // each child). Post-fix it reports shipped_count = 2 (children only).
+  const parentChildrenAllShipped = [
+    { id: 1, version_id: 'GDS-V3', parent_task_id: null, status: 'shipped', title: 'Parent' },
+    { id: 2, version_id: 'GDS-V3', parent_task_id: 1,    status: 'shipped', title: 'Child A' },
+    { id: 3, version_id: 'GDS-V3', parent_task_id: 1,    status: 'shipped', title: 'Child B' },
+  ];
+
+  await test('NEW view: parent + 2 shipped children → shipped_count = 2 (leaves only)', () => {
+    const got = breakdownNew(parentChildrenAllShipped);
+    assert.deepEqual(got, { completed_count: 0, confirmed_count: 0, shipped_count: 2 });
+  });
+
+  await test('OLD view (regression baseline): same fixture WOULD have reported shipped_count = 3', () => {
+    const got = breakdownOld(parentChildrenAllShipped);
+    assert.deepEqual(got, { completed_count: 0, confirmed_count: 0, shipped_count: 3 },
+      'the pre-fix predicate must over-count by 1 (the parent row); if it doesn\'t, the test no longer proves the fix matters');
+  });
+
+  await test('mixed lifecycle states: leaf-only rollup is honest per-state', () => {
+    const tasks = [
+      // Parent with mixed-state children → only children count.
+      { id: 10, version_id: 'GDS-V3', parent_task_id: null, status: 'shipped',   title: 'Parent X' },
+      { id: 11, version_id: 'GDS-V3', parent_task_id: 10,   status: 'completed', title: 'X child 1' },
+      { id: 12, version_id: 'GDS-V3', parent_task_id: 10,   status: 'confirmed', title: 'X child 2' },
+      { id: 13, version_id: 'GDS-V3', parent_task_id: 10,   status: 'shipped',   title: 'X child 3' },
+      // Standalone leaf shipped.
+      { id: 20, version_id: 'GDS-V3', parent_task_id: null, status: 'shipped', title: 'Solo Y' },
+      // Standalone leaf in confirmed.
+      { id: 21, version_id: 'GDS-V3', parent_task_id: null, status: 'confirmed', title: 'Solo Z' },
+    ];
+    // Leaves: 11 (completed), 12 (confirmed), 13 (shipped), 20 (shipped), 21 (confirmed).
+    // → completed=1, confirmed=2, shipped=2
+    assert.deepEqual(
+      breakdownNew(tasks),
+      { completed_count: 1, confirmed_count: 2, shipped_count: 2 }
+    );
+  });
+
+  await test('__smoke__ rows are excluded (matches view FILTER)', () => {
+    const tasks = [
+      { id: 30, version_id: 'GDS-V3', parent_task_id: null, status: 'shipped', title: 'Real leaf' },
+      { id: 31, version_id: 'GDS-V3', parent_task_id: null, status: 'shipped', title: '__smoke__ excluded' },
+    ];
+    assert.deepEqual(
+      breakdownNew(tasks),
+      { completed_count: 0, confirmed_count: 0, shipped_count: 1 }
+    );
+  });
+
+  await test('a parent with NO children IS itself a leaf — gets counted', () => {
+    // Edge case worth pinning: in this schema "parent" is purely a function
+    // of OTHER rows pointing at this one via parent_task_id. A row that
+    // happens to be parent_task_id=null AND has no children is still a leaf.
+    const tasks = [
+      { id: 40, version_id: 'GDS-V3', parent_task_id: null, status: 'shipped', title: 'Childless top-level' },
+    ];
+    assert.deepEqual(
+      breakdownNew(tasks),
+      { completed_count: 0, confirmed_count: 0, shipped_count: 1 }
+    );
+  });
+
+  await test('predicate parity: leaf clause matches the one version_progress uses (migration 017)', () => {
+    // Cross-check against the live version_progress definition so the two
+    // views stay aligned. If someone evolves version_progress's leaf guard
+    // (different operator, different table alias) we want this test to FAIL
+    // loudly until the lifecycle view is updated in lockstep.
+    const progressMigration = readFileSync(
+      join(repoRoot, 'migrations', '017_version_progress_exclude_abandoned.sql'),
+      'utf8'
+    );
+    const leafGuard = /NOT\s+EXISTS\s*\(\s*SELECT\s+1\s+FROM\s+tasks\s+c\s+WHERE\s+c\.parent_task_id\s*=\s*t\.id\s*\)/i;
+    assert.ok(
+      leafGuard.test(progressMigration),
+      'version_progress (migration 017) must use the same leaf guard — if this fails, the two views have diverged and migration 034 should be re-aligned'
+    );
+    assert.ok(
+      leafGuard.test(migrationSql),
+      'version_lifecycle_breakdown (migration 034) must use the same leaf guard'
+    );
+  });
+
+  console.log(`\n${passed} passed, ${failed} failed`);
+  if (failed > 0) process.exit(1);
+})();

package/tests/linkify_refs.mjs

@@ -0,0 +1,264 @@
+// tests/linkify_refs.mjs
+//
+// #604 — the doc-linkifier classifier. The whole value of the rewrite is that
+// it is CONSERVATIVE: a wrong rewrite (pointing a "#NNN" at the wrong thing)
+// just recreates the Xenos's complaint, so these tests pin down exactly which
+// refs are rewritten and which are deliberately left bare.
+//
+// Pure function — no API, no filesystem. validIds is a fixed Set.
+//
+// Run:  node tests/linkify_refs.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { linkifyText, RESOLVER_BASE, RESOLVER_BASE_IDEA, RESOLVER_BASE_BLOCKER, discoverDocs } =
+  require('../scripts/gds/linkify-refs.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+const IDS = new Set([12, 30, 170, 197, 227, 308, 475]);
+const link = (n) => `[#${n}](${RESOLVER_BASE}${n})`;
+const run = (s, ids = IDS) => linkifyText(s, ids).text;
+
+t('a bare task ref is linkified', () => {
+  assert.equal(run('shipped in #475 today'), `shipped in ${link(475)} today`);
+});
+
+t('a parenthesized task ref is linkified (these are task refs here, not PRs)', () => {
+  assert.equal(run('R01-followup (#308, 2026-05-13)'), `R01-followup (${link(308)}, 2026-05-13)`);
+});
+
+t('an explicit "task #NNN" ref is linkified', () => {
+  assert.equal(run('via task #197 we'), `via task ${link(197)} we`);
+});
+
+t('a number that is NOT a known task is left bare', () => {
+  assert.equal(run('see PR #999 for the merge'), 'see PR #999 for the merge');
+});
+
+t('a markdown HEADING ANCHOR is never touched (would break the TOC)', () => {
+  const s = '[Session Update Protocol](#12-session-update-protocol)';
+  assert.equal(run(s), s);
+});
+
+t('a link TARGET like ](#227) is left alone', () => {
+  const s = 'see [the section](#227)';
+  assert.equal(run(s), s);
+});
+
+t('a ref INSIDE markdown link text is not linkified (would nest links)', () => {
+  // mid-text, not right after '[': the bug that shipped [task [#415](r)](url)
+  assert.equal(run('see [task #170](https://x.com) for detail'),
+    'see [task #170](https://x.com) for detail');
+  assert.equal(run('[V3.R13 / #197](../CLAUDE.md) ref', new Set([197])),
+    '[V3.R13 / #197](../CLAUDE.md) ref');
+});
+
+t('already-linked refs are not double-wrapped (idempotent)', () => {
+  const once = run('shipped in #475 today');
+  assert.equal(run(once), once);
+});
+
+t('idea-context refs are NEUTRALIZED (code span) — never task-linked, never bare-404', () => {
+  assert.equal(run('GDS-V4 (idea_inbox #30) will'), 'GDS-V4 (idea_inbox `#30`) will');
+  assert.equal(run('captured as idea #30 last week'), 'captured as idea `#30` last week');
+});
+
+t('an entity ref is neutralized even when the number is NOT a known task id', () => {
+  // "idea #170" was the original Xenos complaint: left bare it autolinks to a
+  // dead github.com issue. Entity context decides; the task-id set does not.
+  assert.equal(run('filed idea #222 yesterday', new Set([1])), 'filed idea `#222` yesterday');
+});
+
+t('blocker-context refs are neutralized — blocker ids share the integer space', () => {
+  assert.equal(run('a blocker #170 needs Lars', new Set([170])), 'a blocker `#170` needs Lars');
+});
+
+t('report/learning/claim/builder entity refs are neutralized too', () => {
+  assert.equal(run('captured learning #53 today', new Set([53])), 'captured learning `#53` today');
+  assert.equal(run('filed as security_reports #2', new Set([2])), 'filed as security_reports `#2`');
+  assert.equal(run('builder #3 was reset', new Set([3])), 'builder `#3` was reset');
+});
+
+t('a session ORDINAL ("Planning Session #1") is not a task ref', () => {
+  assert.equal(run('via Planning Session #1 today', new Set([1])), 'via Planning Session `#1` today');
+});
+
+t('a PR number ("PR #475") is left bare even when it collides with a task id — GitHub autolinks it CORRECTLY', () => {
+  assert.equal(run('merged in PR #475', new Set([475])), 'merged in PR #475');
+});
+
+t('entity classification carries across a comma list ("blockers #1, #2")', () => {
+  // Both are blocker ids — neither should become a task link…
+  assert.equal(run('blockers #1, #2 remain', new Set([1, 2])), 'blockers `#1`, `#2` remain');
+});
+
+t('entity classification carries across a RANGE ("reports #2–#11")', () => {
+  assert.equal(run('reports #2–#11 filed', new Set([2, 11])), 'reports `#2`–`#11` filed');
+});
+
+t('…but a genuine task list ("Tasks #1, #2") still linkifies BOTH', () => {
+  assert.equal(run('Tasks #1, #2 shipped', new Set([1, 2])), `Tasks ${link(1)}, ${link(2)} shipped`);
+});
+
+t('mixed line: "Tasks #1, #2 + blockers #1, #2" links the task half, neutralizes the blocker half', () => {
+  const out = run('Tasks #1, #2 + blockers #1, #2', new Set([1, 2]));
+  assert.equal(out, `Tasks ${link(1)}, ${link(2)} + blockers \`#1\`, \`#2\``);
+});
+
+t('entity context does not over-extend past non-glue text', () => {
+  // "idea #30, then task #197" — idea neutralized, but the comma+word gap
+  // breaks inheritance so the real task ref still linkifies.
+  assert.equal(run('idea #30, then task #197 ran', new Set([30, 197])),
+    `idea \`#30\`, then task ${link(197)} ran`);
+});
+
+t('neutralization is idempotent — a `#30` code span is never re-wrapped', () => {
+  const once = run('captured as idea #30 last week');
+  assert.equal(run(once), once);
+});
+
+t('a PAST mis-linkification in entity context is unwrapped to a code span', () => {
+  // An earlier linkifier run wrongly sent "learning #53" to the task resolver.
+  assert.equal(run(`captured learning ${link(53)} today`, new Set([53])),
+    'captured learning `#53` today');
+});
+
+t('a PAST mis-linkification of a PR ref is unwrapped back to BARE (autolink is correct there)', () => {
+  assert.equal(run(`merged in PR ${link(475)}`, new Set([475])), 'merged in PR #475');
+});
+
+t('a RANGE of past mis-linkifications unwraps on both ends', () => {
+  assert.equal(run(`security_reports ${link(2)}–${link(11)} filed`, new Set([2, 11])),
+    'security_reports `#2`–`#11` filed');
+});
+
+t('a CORRECT task resolver link is never unwrapped', () => {
+  const s = `shipped in ${link(475)} today`;
+  assert.equal(run(s), s);
+});
+
+t('inline code spans are not transformed', () => {
+  const s = 'the `#197` marker stays code';
+  assert.equal(run(s), s);
+});
+
+t('fenced code blocks are not transformed', () => {
+  const s = ['before #475', '```', 'code #475 here', '```', 'after #475'].join('\n');
+  const out = run(s).split('\n');
+  assert.equal(out[0], `before ${link(475)}`);
+  assert.equal(out[2], 'code #475 here'); // inside fence — untouched
+  assert.equal(out[4], `after ${link(475)}`);
+});
+
+t('multiple refs on one line all linkify', () => {
+  assert.equal(run('Phase 1 #197, Phase 2 #227.'), `Phase 1 ${link(197)}, Phase 2 ${link(227)}.`);
+});
+
+t('a slugged ref like #170foo is treated as not-bare and skipped', () => {
+  assert.equal(run('#170foo'), '#170foo');
+});
+
+t('stats report linkified + skip reasons', () => {
+  const stats = { linkified: 0, skipped: {} };
+  linkifyText('#475 and #999 and idea #30 and [x](#12-y)', IDS, stats);
+  assert.equal(stats.linkified, 1, 'only #475 should linkify');
+  assert.ok(stats.skipped['not-a-task'] >= 1, 'a non-task was skipped');
+});
+
+// ========================================================================
+// #629 — idea/blocker refs LINK to their resolvers when the id validates.
+// `ids` is now {tasks, ideas, blockers}; the existing tests above pass a bare
+// task Set (empty idea/blocker sets), so those refs still NEUTRALIZE — the new
+// behavior only kicks in when the matching id set contains the number.
+// ========================================================================
+
+const ilink = (n) => `[#${n}](${RESOLVER_BASE_IDEA}${n})`;
+const blink = (n) => `[#${n}](${RESOLVER_BASE_BLOCKER}${n})`;
+const runIds = (s, ids) => linkifyText(s, ids).text;
+
+t('a bare idea ref LINKS to the idea resolver when the id is a known idea', () => {
+  assert.equal(runIds('GDS-V4 (idea_inbox #30) will', { tasks: new Set(), ideas: new Set([30]), blockers: new Set() }),
+    `GDS-V4 (idea_inbox ${ilink(30)}) will`);
+  assert.equal(runIds('captured as idea #173 last week', { ideas: new Set([173]) }),
+    `captured as idea ${ilink(173)} last week`);
+});
+
+t('a bare blocker ref LINKS to the blocker resolver when the id is a known blocker', () => {
+  assert.equal(runIds('a blocker #10 needs Lars', { blockers: new Set([10]) }),
+    `a blocker ${blink(10)} needs Lars`);
+});
+
+t('an idea ref whose id is NOT a known idea is still NEUTRALIZED (no wrong link, no 404)', () => {
+  assert.equal(runIds('filed idea #222 yesterday', { ideas: new Set([1]) }), 'filed idea `#222` yesterday');
+});
+
+t('a task id and an idea id that collide resolve to DIFFERENT resolvers by context', () => {
+  const ids = { tasks: new Set([170]), ideas: new Set([170]), blockers: new Set() };
+  assert.equal(runIds('task #170 vs idea #170', ids), `task ${link(170)} vs idea ${ilink(170)}`);
+});
+
+t('idea/blocker classification carries across a list → BOTH link', () => {
+  assert.equal(runIds('blockers #1, #2 remain', { blockers: new Set([1, 2]) }),
+    `blockers ${blink(1)}, ${blink(2)} remain`);
+  assert.equal(runIds('ideas #30 and #173', { ideas: new Set([30, 173]) }),
+    `ideas ${ilink(30)} and ${ilink(173)}`);
+});
+
+t('Phase 2: a PRIOR idea/blocker neutralization `#N` is UPGRADED to a resolver link', () => {
+  assert.equal(runIds('see idea_inbox `#160` here', { ideas: new Set([160]) }),
+    `see idea_inbox ${ilink(160)} here`);
+  assert.equal(runIds('blocker `#7` is open', { blockers: new Set([7]) }),
+    `blocker ${blink(7)} is open`);
+});
+
+t('Phase 2 upgrade carries across a list of code spans ("blockers `#1`, `#2`")', () => {
+  assert.equal(runIds('blockers `#1`, `#2` remain', { blockers: new Set([1, 2]) }),
+    `blockers ${blink(1)}, ${blink(2)} remain`);
+});
+
+t('Phase 2 does NOT upgrade an other-entity code span (no resolver for learnings)', () => {
+  assert.equal(runIds('captured learning `#53` today', { ideas: new Set([53]), blockers: new Set([53]) }),
+    'captured learning `#53` today');
+});
+
+t('Phase 2 does NOT touch a legit code span with no idea/blocker context', () => {
+  // "the `#197` marker" — even if 197 is a known idea, there is no idea noun
+  // before it, so it stays a literal code span.
+  assert.equal(runIds('the `#197` marker stays code', { ideas: new Set([197]) }),
+    'the `#197` marker stays code');
+});
+
+t('idea/blocker linking is idempotent (link, then link again = no change)', () => {
+  const ids = { ideas: new Set([30]), blockers: new Set([7]) };
+  const once = runIds('idea #30 and blocker #7', ids);
+  assert.equal(once, `idea ${ilink(30)} and blocker ${blink(7)}`);
+  assert.equal(runIds(once, ids), once);
+  // and a freshly-upgraded code span is stable on a second pass too
+  const up = runIds('idea_inbox `#30`', ids);
+  assert.equal(runIds(up, ids), up);
+});
+
+t('a known idea link is never unwrapped by the past-mislink pass', () => {
+  const ids = { ideas: new Set([30]) };
+  const s = `idea ${ilink(30)} shipped`;
+  assert.equal(runIds(s, ids), s);
+});
+
+t('discoverDocs finds CLAUDE.md + session logs, only .md, skips the generated ideas file', () => {
+  const docs = discoverDocs();
+  assert.ok(docs.includes('CLAUDE.md'), 'includes CLAUDE.md');
+  assert.ok(docs.some((d) => d.startsWith('docs/session-logs/')), 'includes session logs');
+  assert.ok(docs.every((d) => d.endsWith('.md')), 'only markdown files');
+  assert.ok(!docs.includes('generative-ideas.md'), 'excludes the generated ideas file');
+});
+
+console.log(`\nlinkify_refs: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/live_channel.mjs

@@ -0,0 +1,128 @@
+// tests/live_channel.mjs
+//
+// Unit smoke for the GDS live-update relay (#569 / ADR 0030).
+//
+// Verifies the in-process fan-out logic in src/bongos/live-channel.js WITHOUT a
+// real Postgres — a fake pg.Client is injected via _setClientFactory. This is
+// the transport-agnostic layer: in production the hall's SSE endpoint
+// (src/bongos/routes/live.js) subscribes here and writes each nudge to connected
+// EventSource clients. (Before R55 / ADR 0069 the subscriber was the Colyseus
+// BuildersHallRoom; this relay is unchanged either way.)
+//   1. First subscriber lazily opens ONE LISTEN connection (connect + LISTEN).
+//   2. A NOTIFY on the 'gds_live' channel reaches every subscriber, parsed.
+//   3. A NOTIFY on some OTHER channel is ignored.
+//   4. Malformed JSON payload → subscriber gets null (no throw).
+//   5. One throwing subscriber doesn't starve the others.
+//   6. A second subscriber REUSES the same connection (factory called once).
+//   7. Connection closes only when the LAST subscriber leaves.
+//
+// Run:  node tests/live_channel.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { EventEmitter } from 'node:events';
+
+const require = createRequire(import.meta.url);
+const live = require('../src/bongos/live-channel.js');
+
+const tick = () => new Promise((r) => setTimeout(r, 10));
+
+// A fake pg.Client: records calls, lets the test emit notifications.
+let factoryCalls = 0;
+let lastClient = null;
+function fakeFactory() {
+  factoryCalls += 1;
+  const c = new EventEmitter();
+  c.queries = [];
+  c.ended = false;
+  c.connect = async () => {};
+  c.query = async (sql) => { c.queries.push(sql); };
+  c.end = async () => { c.ended = true; };
+  lastClient = c;
+  return c;
+}
+
+live._setClientFactory(fakeFactory);
+
+// --- 1 + 2 + 6: lazy connect, delivery, single connection -----------------
+const got1 = [];
+const got2 = [];
+const unsub1 = live.subscribe((p) => got1.push(p));
+await tick();
+
+assert.equal(factoryCalls, 1, 'first subscriber opens exactly one client');
+assert.ok(lastClient, 'a client was created');
+assert.ok(
+  lastClient.queries.some((q) => /LISTEN\s+gds_live/i.test(q)),
+  'client issued LISTEN gds_live',
+);
+assert.deepEqual(live._state(), { subscribers: 1, connected: true });
+
+const unsub2 = live.subscribe((p) => got2.push(p));
+await tick();
+assert.equal(factoryCalls, 1, 'second subscriber REUSES the connection');
+assert.equal(live._state().subscribers, 2);
+
+// Deliver a well-formed notification.
+lastClient.emit('notification', { channel: 'gds_live', payload: '{"table":"tasks","op":"UPDATE"}' });
+assert.deepEqual(got1.at(-1), { table: 'tasks', op: 'UPDATE' }, 'subscriber 1 got parsed payload');
+assert.deepEqual(got2.at(-1), { table: 'tasks', op: 'UPDATE' }, 'subscriber 2 got parsed payload');
+
+// --- 3: other channel ignored ---------------------------------------------
+const before = got1.length;
+lastClient.emit('notification', { channel: 'something_else', payload: '{"x":1}' });
+assert.equal(got1.length, before, 'notification on another channel is ignored');
+
+// --- 4: malformed JSON → null, no throw ------------------------------------
+lastClient.emit('notification', { channel: 'gds_live', payload: 'not json{' });
+assert.equal(got1.at(-1), null, 'malformed payload delivered as null');
+
+// --- 5: a throwing subscriber must not starve the others -------------------
+const got3 = [];
+const unsub3 = live.subscribe(() => { throw new Error('boom'); });
+const got4 = [];
+const unsub4 = live.subscribe((p) => got4.push(p));
+await tick();
+lastClient.emit('notification', { channel: 'gds_live', payload: '{"table":"builders","op":"INSERT"}' });
+assert.deepEqual(got4.at(-1), { table: 'builders', op: 'INSERT' }, 'good subscriber still gets payload despite a throwing peer');
+
+// --- 7: connection closes only after the LAST subscriber leaves ------------
+unsub1();
+unsub2();
+unsub3();
+assert.equal(lastClient.ended, false, 'still connected while one subscriber remains');
+assert.equal(live._state().connected, true);
+unsub4();
+assert.equal(lastClient.ended, true, 'connection closed after the last subscriber left');
+assert.deepEqual(live._state(), { subscribers: 0, connected: false });
+
+// --- 8: a dropped LISTEN connection reconnects while a subscriber remains ---
+// #983: shrink the reconnect backoff via the test-only seam so this exercises
+// the reconnect path WITHOUT a multi-second real-time wait (was a hard
+// `setTimeout(2300)`, the slowest assertion in the suite).
+live._setReconnectDelay(10);
+const startCalls = factoryCalls;
+const got5 = [];
+const unsub5 = live.subscribe((p) => got5.push(p));
+await tick();
+assert.equal(factoryCalls, startCalls + 1, 'resubscribe opens a fresh client');
+const firstClient = lastClient;
+
+// Simulate the LISTEN connection dropping mid-flight.
+firstClient.emit('error', new Error('connection terminated unexpectedly'));
+assert.equal(live._state().connected, false, 'connection torn down on error');
+
+// scheduleReconnect waits ~10ms (test backoff), then reconnects because a
+// subscriber remains. Poll briefly instead of a fixed long sleep.
+for (let i = 0; i < 50 && factoryCalls < startCalls + 2; i++) await tick();
+assert.equal(factoryCalls, startCalls + 2, 'reconnected with a new client after the backoff');
+assert.equal(live._state().connected, true, 'live again after reconnect');
+
+// Nudges flow over the reconnected client.
+lastClient.emit('notification', { channel: 'gds_live', payload: '{"table":"claims","op":"DELETE"}' });
+assert.deepEqual(got5.at(-1), { table: 'claims', op: 'DELETE' }, 'nudges resume after reconnect');
+
+unsub5();
+assert.equal(live._state().connected, false, 'closed after the final unsubscribe');
+
+console.log('live_channel: all assertions passed');