@bongos/core 1.19.925 → 1.19.927

package/tests/idea_descent_surface.mjs

@@ -0,0 +1,458 @@
+// tests/idea_descent_surface.mjs
+//
+// task 1004094 (BV2.R10, goal 1000095, criterion `ideator-tag-survives-the-fork`)
+// — THE DESCENT SURFACE on /idea/:id. Spec docs/specs/bongos-v2-ideator-surface.md;
+// ADR 0312 (the edges), 0313 (removal proposed then confirmed), 0322 (the five
+// states).
+//
+// THE DONE-WHEN IS THE FIRST TEST, and it is the only one that matters on its
+// own: a person can trace a thing shipped months later back to the line that
+// caused it, THROUGH rewrites, splits and merges. So §1 renders a real
+// four-deep chain whose hops are a rewrite, two splits and a fold, and asserts
+// that the reader is handed every hop, the word for each edge, and a path back
+// to each task.
+//
+// TESTED AT THE RENDERED LAYER, not at the read behind it. That is the first of
+// the three findings this goal's work inherited from the abandoned task 1004054
+// (see modules/ideas/trail-descent.js): the prior attempt asserted on the
+// server-side builder alone, which is exactly how a renderer bug survived it.
+// Every case below boots the REAL modules/hall-ui/public/idea.js through
+// tests/helpers.mjs bootIdeaPage and reads the HTML a reader would get.
+//
+// THE THREE TRAPS THIS FILE EXISTS TO CATCH, each of which paints a page that
+// looks completely fine:
+//
+//   1. THE ROOTS GO MISSING. attachDescentToTrail deliberately EXCLUDES an
+//      idea's own root tasks from descent_tasks (repeating them would
+//      double-count the first hop for the payout). A renderer that draws only
+//      descent_tasks therefore loses the first thing the thought ever caused —
+//      the one hop every other surface already shows — and the rail still
+//      renders, just beginning in the middle of the story.
+//   2. UNREADABLE IS DRAWN AS ALIVE. `removed_tasks` is `{}` when nothing went
+//      out and `null` when the lifecycle facts could not be read at all. Those
+//      are different answers, and collapsing the second into the first promises
+//      a reader that every branch survived. Nothing errors when it does.
+//   3. THE EMPTY STATE IS A HEADING OVER NOTHING. A thought that caused nothing
+//      must render NO section, not an empty rail — the same judgement the page
+//      already makes about a quick idea's five-field skeleton.
+//
+// DB-free: no route, no pool, no browser. Run: node tests/idea_descent_surface.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { bootIdeaPage, settle } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed += 1; console.log(`ok   ${name}`); }
+  catch (err) { failed += 1; console.log(`FAIL ${name}\n     ${err && (err.message || JSON.stringify(err))}`); }
+}
+
+// ---------------------------------------------------------------------------
+// the fixture world
+// ---------------------------------------------------------------------------
+
+// One thought, one root, and a four-deep descent below it whose hops are the
+// three relations the done-when names by name — a rewrite, a split and a merge
+// — plus a fold that later WENT OUT and a cascade that has not landed yet. The
+// deepest hop lives in a LATER version, because the descent crosses version
+// boundaries deliberately (ADR 0312) and a surface that hides that is lying by
+// omission.
+const ROOT = { task_id: '9001', origin: 'promote', title: 'Env vars in project setup', status: 'shipped', goal_id: '600' };
+
+const DESCENT = [
+  { task_id: '9002', depth: 1, relation: 'rewrite', origin_task_id: '9001', title: 'Scope widened to secrets', status: 'shipped', version_id: 'BONGOS-V1', kind: 'feature' },
+  { task_id: '9003', depth: 2, relation: 'split', origin_task_id: '9001', title: 'The env var editor', status: 'shipped', version_id: 'BONGOS-V1', kind: 'feature' },
+  { task_id: '9004', depth: 2, relation: 'merge', origin_task_id: '9001', title: 'Encrypted secret storage', status: 'shipped', version_id: 'BONGOS-V2', kind: 'feature' },
+  { task_id: '9005', depth: 3, relation: 'fold', origin_task_id: '9001', title: 'The settings panel it lived in', status: 'shipped', version_id: 'BONGOS-V1', kind: 'refactor' },
+  { task_id: '9006', depth: 1, relation: 'cascade', origin_task_id: '9001', title: 'Import a .env file', status: 'backlog', version_id: 'BONGOS-V2', kind: 'feature' },
+];
+
+function anIdea(over = {}) {
+  return {
+    id: '1',
+    title: 'A place to put env vars',
+    body_md: 'The thought.',
+    grade: 'quick',
+    status: 'promoted',
+    kind: 'feature',
+    suggested_version: 'BONGOS-V1',
+    captured_by: '1',
+    captured_at: '2026-07-01T12:00:00.000Z',
+    promoted_to_task_id: '9001',
+    promoted_task_title: ROOT.title,
+    promoted_task_status: ROOT.status,
+    lineage_tasks: [ROOT],
+    descent_tasks: DESCENT,
+    removed_tasks: {},
+    size: { credits: 278, payments: 5, scale: 3, estimated: 0, historical: false },
+    state: { state: 'star', position: 'well', wellGoalId: '600', awaitingNod: false, brightness: 0.82, hasWork: true, attributable: true },
+    ...over,
+  };
+}
+
+async function renderIdea(over = {}) {
+  const page = bootIdeaPage({ idea: anIdea(over) });
+  await settle();
+  await settle();
+  await settle();
+  return page.html();
+}
+
+// The rows, in render order, each as { id, mark, meta }.
+function rowsOf(html) {
+  const out = [];
+  const re = /<li class="ig-desc__row" data-mark="([^"]+)" style="--d:(\d+)">([\s\S]*?)<\/li>/g;
+  let m;
+  while ((m = re.exec(html)) !== null) {
+    const body = m[3];
+    const id = (/<span class="ig-desc__id">(\d+)<\/span>/.exec(body) || [])[1];
+    const meta = (/<span class="ig-desc__meta">([\s\S]*?)<\/span>\s*$/.exec(body.split('ig-desc__meta')[1] ? body : body) || [])[0];
+    out.push({
+      id,
+      mark: m[1],
+      depth: Number(m[2]),
+      meta: (/<span class="ig-desc__meta">([\s\S]*?)<\/span>/.exec(body) || [])[1] || '',
+      title: (/<a class="ig-desc__title"[^>]*>([\s\S]*?)<\/a>/.exec(body) || [])[1] || '',
+      href: (/<a class="ig-desc__title" href="([^"]+)"/.exec(body) || [])[1] || '',
+    });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// §1 — the done-when
+// ---------------------------------------------------------------------------
+
+await test('§1 DONE-WHEN: a thing shipped later traces back through the rewrites, splits and merges', async () => {
+  const html = await renderIdea();
+  const rows = rowsOf(html);
+
+  // Every hop is there: the root plus all five descendants. Nothing is capped
+  // on this page — profile.js caps at three and links HERE for the rest, which
+  // is the only thing that makes that cap honest.
+  assert.equal(rows.length, 6, `expected the root + 5 descendants, got ${rows.length}`);
+  assert.deepEqual(rows.map((r) => r.id), ['9001', '9002', '9003', '9004', '9005', '9006']);
+
+  // The three relations the done-when names are each stated IN WORDS. A reader
+  // tracing 9005 back to the origin has to be able to see what kind of hop each
+  // step was, or the rail is a list of tasks rather than a story.
+  const meta = (id) => rows.find((r) => r.id === id).meta;
+  assert.match(meta('9002'), /rewritten/, 'the rewrite must say so');
+  assert.match(meta('9003'), /split off/, 'the split must say so');
+  assert.match(meta('9004'), /merged in/, 'the merge must say so');
+  assert.match(meta('9005'), /folded in/, 'the fold must say so');
+  assert.match(meta('9006'), /caused by/, 'the cascade must say so');
+
+  // And every hop is a door back to the work itself.
+  for (const r of rows) {
+    assert.equal(r.href, `/task/${r.id}`, `row ${r.id} must link to its task`);
+  }
+});
+
+await test('§1 the depth of a hop survives into the rail, so the shape is readable', async () => {
+  const rows = rowsOf(await renderIdea());
+  // The server counts hops FROM a root; the rail draws the root at 0, so every
+  // descendant sits one step deeper than the number the read carries.
+  assert.deepEqual(
+    rows.map((r) => [r.id, r.depth]),
+    [['9001', 0], ['9002', 2], ['9003', 3], ['9004', 3], ['9005', 4], ['9006', 2]],
+  );
+});
+
+await test('§1 a descendant in a LATER version says which one; one in the same version does not', async () => {
+  const rows = rowsOf(await renderIdea());
+  const meta = (id) => rows.find((r) => r.id === id).meta;
+  // 9004 and 9006 are BONGOS-V2 against an idea filed at BONGOS-V1.
+  assert.match(meta('9004'), /in BONGOS-V2/, 'a cross-version hop must name its version');
+  assert.match(meta('9006'), /in BONGOS-V2/);
+  // 9002 is in the idea's own version, so saying so would be noise on every row.
+  assert.doesNotMatch(meta('9002'), /in BONGOS-V1/, 'a same-version hop must not repeat the version');
+});
+
+// ---------------------------------------------------------------------------
+// §2 — the roots (trap 1)
+// ---------------------------------------------------------------------------
+
+await test('§2 TRAP: the ROOT is drawn, though the server leaves it out of descent_tasks', async () => {
+  const rows = rowsOf(await renderIdea());
+  const root = rows[0];
+  assert.equal(root.id, '9001', 'the first thing the thought caused must lead the rail');
+  assert.equal(root.depth, 0);
+  assert.match(root.meta, /became work/, 'a root has no relation — it became work');
+  assert.match(root.title, /Env vars in project setup/);
+});
+
+await test('§2 an idea that became MANY tasks shows every one of them as a root', async () => {
+  const rows = rowsOf(await renderIdea({
+    lineage_tasks: [
+      ROOT,
+      { task_id: '9010', origin: 'develop', title: 'The second thing it became', status: 'ready', goal_id: '600' },
+    ],
+  }));
+  const roots = rows.filter((r) => r.depth === 0).map((r) => r.id);
+  assert.deepEqual(roots, ['9001', '9010'], 'both lineage tasks are roots');
+});
+
+await test('§2 a promotion that predates the lineage table still shows its one root', async () => {
+  // lineage_tasks empty, promoted_to_task_id set — the only answer for an old
+  // promotion, and the reason the legacy column is still read.
+  const rows = rowsOf(await renderIdea({ lineage_tasks: [], descent_tasks: [] }));
+  assert.deepEqual(rows.map((r) => r.id), ['9001']);
+  assert.match(rows[0].meta, /became work/);
+});
+
+await test('§2 an idea carrying BOTH lineage and the legacy column does not list its root twice', async () => {
+  const rows = rowsOf(await renderIdea({ descent_tasks: [] }));
+  assert.deepEqual(rows.map((r) => r.id), ['9001'], 'lineage wins; the legacy column is not added on top');
+});
+
+// ---------------------------------------------------------------------------
+// §3 — the branches that went out (trap 2)
+// ---------------------------------------------------------------------------
+
+await test('§3 a CONFIRMED removal marks its row out, names the ship that did it, and is counted', async () => {
+  const html = await renderIdea({
+    removed_tasks: { 9005: { proposal_task_id: '9100', ship_task_id: '9101', paths: ['src/settings/panel.js'], decided_at: '2027-01-14T09:00:00.000Z' } },
+  });
+  const rows = rowsOf(html);
+  const gone = rows.find((r) => r.id === '9005');
+  assert.equal(gone.mark, 'out', 'a removed hop is marked out');
+  assert.match(gone.meta, /went out/);
+  assert.match(gone.meta, /task 9101/, 'the removal names the ship that did it');
+  assert.match(gone.meta, /href="\/task\/9101"/, 'and that ship is reachable');
+  // Every other hop is unaffected — removal is per-node, not per-thought.
+  assert.deepEqual(
+    rows.filter((r) => r.id !== '9005').map((r) => r.mark),
+    ['live', 'live', 'live', 'live', 'pending'],
+  );
+  assert.match(html, /<span class="ig-desc__n">1<\/span>\s*<span class="ig-desc__flabel">went out<\/span>/);
+});
+
+await test('§3 TRAP: `null` removal facts are NOT drawn as a descent that is wholly alive', async () => {
+  const html = await renderIdea({ removed_tasks: null });
+  const rows = rowsOf(html);
+  // Not one row may claim to be out, and none may claim to be alive either:
+  // "we could not look" is a third answer.
+  assert.equal(rows.filter((r) => r.mark === 'out').length, 0);
+  assert.doesNotMatch(html, /went out<\/span>/, 'no figure may state a removal count that was never read');
+  assert.match(html, /could not be read/, 'the page must SAY the liveness is unknown');
+});
+
+await test('§3 an empty `{}` means nothing went out — and says nothing, rather than saying it is unknown', async () => {
+  const html = await renderIdea({ removed_tasks: {} });
+  assert.doesNotMatch(html, /could not be read/, 'a readable, empty answer is not an unreadable one');
+  assert.doesNotMatch(html, /went out/, 'nothing went out, so nothing is said about it');
+  assert.equal(rowsOf(html).filter((r) => r.mark === 'out').length, 0);
+});
+
+// ---------------------------------------------------------------------------
+// §4 — the empty state (trap 3)
+// ---------------------------------------------------------------------------
+
+await test('§4 TRAP: a thought that caused NOTHING renders no section at all', async () => {
+  const html = await renderIdea({
+    status: 'open',
+    promoted_to_task_id: null,
+    promoted_task_title: null,
+    lineage_tasks: [],
+    descent_tasks: [],
+    size: null,
+    state: { state: 'protostar', position: 'open-space', wellGoalId: null, awaitingNod: false, brightness: 1, hasWork: false, attributable: true },
+  });
+  assert.doesNotMatch(html, /ig-desc/, 'no heading, no rail, no figures — the page says "still open" and stops');
+  // The page itself still renders: an absent descent must not blank the record.
+  assert.match(html, /rec-title/);
+});
+
+// ---------------------------------------------------------------------------
+// §5 — the numbers are the server's, and they never lie about what they are
+// ---------------------------------------------------------------------------
+
+await test('§5 size is printed verbatim and a HISTORICAL size says so', async () => {
+  const plain = await renderIdea();
+  assert.match(plain, /<span class="ig-desc__n">278<\/span>/);
+  assert.match(plain, /size — credits/);
+
+  // Spec decision 17: a backfilled size was computed from the descent an idea
+  // already had, not from payouts actually made. Anywhere the number is shown
+  // has to make that clear or it claims to be money that was never spent.
+  const hist = await renderIdea({ size: { credits: 278, payments: 0, scale: 3, estimated: 278, historical: true } });
+  assert.match(hist, /size — part historical/);
+});
+
+await test('§5 an idea with no size at all still draws its rail', async () => {
+  const html = await renderIdea({ size: null });
+  assert.doesNotMatch(html, /size — /, 'no size, no size figure');
+  assert.equal(rowsOf(html).length, 6, 'but every hop it caused is still drawn');
+});
+
+await test('§5 the count of things it caused is the rows actually drawn, roots included', async () => {
+  const html = await renderIdea();
+  assert.match(html, /<span class="ig-desc__n">6<\/span>\s*<span class="ig-desc__flabel">things it caused<\/span>/);
+});
+
+// ---------------------------------------------------------------------------
+// §6 — the vocabulary boundary (ADR 0322)
+// ---------------------------------------------------------------------------
+
+await test('§6 the page does NOT re-derive a five-object state per descendant', async () => {
+  const html = await renderIdea();
+  // The five objects are an IDEA's property, resolved once in
+  // modules/ideas/idea-state.js. A row here is a TASK and carries no object; if
+  // one of these words ever appears against a descent row, some renderer has
+  // started deciding a state a second time — which is the exact failure ADR 0322
+  // exists to prevent, and it would disagree with the sky on the first read.
+  const rail = /<ol class="ig-desc__list">([\s\S]*?)<\/ol>/.exec(html)[1];
+  for (const object of ['protostar', 'satellite', 'remnant', 'cold-body']) {
+    assert.doesNotMatch(rail, new RegExp(object, 'i'), `no descent row may be labelled a ${object}`);
+  }
+});
+
+await test('§6 an unknown relation is shown verbatim rather than dropped', async () => {
+  // A relation this page has not heard of is a real edge someone wrote. Dropping
+  // it would silently shorten the story; showing it unstyled does not.
+  const rows = rowsOf(await renderIdea({
+    descent_tasks: [{ task_id: '9007', depth: 1, relation: 'transmuted', origin_task_id: '9001', title: 'A hop from the future', status: 'shipped', version_id: 'BONGOS-V1' }],
+  }));
+  const hop = rows.find((r) => r.id === '9007');
+  assert.ok(hop, 'the row must still be drawn');
+  assert.match(hop.meta, /transmuted/);
+});
+
+// ---------------------------------------------------------------------------
+// §7 — it is a read of hostile data
+// ---------------------------------------------------------------------------
+
+await test('§7 a task title carrying markup reaches the page as TEXT, not as markup', async () => {
+  const html = await renderIdea({
+    descent_tasks: [{ task_id: '9008', depth: 1, relation: 'split', origin_task_id: '9001', title: '<img src=x onerror=alert(1)>', status: 'shipped', version_id: 'BONGOS-V1' }],
+  });
+  assert.doesNotMatch(html, /<img src=x/, 'the title must be escaped');
+  assert.match(html, /&lt;img src=x/);
+});
+
+await test('§7 a descent row with no title falls back to its id rather than rendering blank', async () => {
+  const rows = rowsOf(await renderIdea({
+    descent_tasks: [{ task_id: '9009', depth: 1, relation: 'split', origin_task_id: '9001', title: null, status: 'shipped' }],
+  }));
+  assert.match(rows.find((r) => r.id === '9009').title, /Task 9009/);
+});
+
+
+// ---------------------------------------------------------------------------
+// §8 — the read behind it
+//
+// The renderer above is only honest if the ROUTE hands it these fields, and the
+// route reads a different row from the one it used to. Both halves of that are
+// pinned here, DB-free, because both fail SILENTLY: a projection that stops
+// carrying `lineage_tasks` renders a thought with a descent as one with none,
+// and nothing errors.
+// ---------------------------------------------------------------------------
+
+const trail = require('../modules/ideas/trail.js');
+const trailRemoval = require('../modules/ideas/trail-removal.js');
+
+// A pool stand-in that records the SQL it was handed.
+function recordingPool(rows = []) {
+  const log = [];
+  return { log, query: async (text, params) => { log.push({ text, params }); return { rows }; } };
+}
+
+await test('§8 the detail read and the trail page read use the SAME projection', async () => {
+  // THE ANTI-DRIFT CLAIM, and it is invisible in review. The two reads differ
+  // only in their WHERE; if someone hand-copies the SELECT for one of them and
+  // later adds a column to the other, the detail page silently stops carrying
+  // a field the attachers read by name. Comparing the text is what makes the
+  // "spelled once" comment in trail.js a fact rather than an intention.
+  process.env.NODE_ENV = 'test';
+  const one = recordingPool([{ id: '1' }]);
+  await trail.getIdeaTrailRow('1', { pool: one });
+
+  const many = recordingPool([]);
+  await trail.listIdeaTrailForBuilder('95', { limit: 5 }, { pool: many });
+
+  const selectOf = (sql) => sql.slice(0, sql.indexOf('      WHERE'));
+  assert.ok(one.log.length === 1 && many.log.length === 1, 'one query each');
+  assert.equal(
+    selectOf(one.log[0].text),
+    selectOf(many.log[0].text),
+    'the detail read must select exactly what the trail read selects',
+  );
+  // And the thing the attachers actually need is in it.
+  assert.match(one.log[0].text, /lineage_tasks/);
+  assert.match(one.log[0].text, /promoted_task_goal_id/);
+  assert.match(one.log[0].text, /WHERE i\.id = \$1/);
+});
+
+await test('§8 getIdeaTrailRow answers null for an id that is not there', async () => {
+  process.env.NODE_ENV = 'test';
+  const p = recordingPool([]);
+  assert.equal(await trail.getIdeaTrailRow('404', { pool: p }), null);
+});
+
+// ---- the removal attacher -------------------------------------------------
+
+// A module-api stand-in is not available here, so the port is exercised through
+// the real resolveOptional by temporarily registering one. When that is not
+// possible the attacher's OWN contract is still the thing under test: what it
+// writes onto the row for each of the three answers.
+function withPort(port, fn) {
+  const api = require('../src/module-api');
+  const original = api.resolveOptional;
+  api.resolveOptional = (name) => (name === 'lifecycle.removals' ? port : original && original(name));
+  return fn().finally(() => { api.resolveOptional = original; });
+}
+
+await test('§8 attachRemovalToDescent keys BOTH the roots and the descent', async () => {
+  let asked = null;
+  const port = {
+    confirmedRemovalsForTasks: async (ids) => {
+      asked = [...ids].sort();
+      return new Map([['9005', { proposalTaskId: '9100', shipTaskId: '9101', paths: ['a.js'], decidedAt: 'x' }]]);
+    },
+  };
+  await withPort(port, async () => {
+    const idea = { id: '1', lineage_tasks: [{ task_id: '9001' }], descent_tasks: [{ task_id: '9005' }, { task_id: '9006' }] };
+    await trailRemoval.attachRemovalToDescent([idea]);
+    // The ROOT is asked about too. attachDescentToTrail leaves roots out of
+    // descent_tasks, and a root is the commonest thing to have been torn out —
+    // asking only about the descent would draw a dead origin as alive.
+    assert.deepEqual(asked, ['9001', '9005', '9006']);
+    assert.deepEqual(Object.keys(idea.removed_tasks), ['9005']);
+    assert.equal(idea.removed_tasks['9005'].ship_task_id, '9101');
+  });
+});
+
+await test('§8 nothing removed is `{}`; an unreadable port is `null` — never the same value', async () => {
+  await withPort({ confirmedRemovalsForTasks: async () => new Map() }, async () => {
+    const idea = { id: '1', lineage_tasks: [{ task_id: '9001' }], descent_tasks: [] };
+    await trailRemoval.attachRemovalToDescent([idea]);
+    assert.deepEqual(idea.removed_tasks, {}, 'readable and empty');
+  });
+  await withPort(null, async () => {
+    const idea = { id: '1', lineage_tasks: [{ task_id: '9001' }], descent_tasks: [] };
+    await trailRemoval.attachRemovalToDescent([idea]);
+    assert.equal(idea.removed_tasks, null, 'unreadable is null, and the renderer says so');
+  });
+});
+
+await test('§8 the whole page costs ONE port call, however many nodes it draws', async () => {
+  let calls = 0;
+  const port = { confirmedRemovalsForTasks: async () => { calls += 1; return new Map(); } };
+  await withPort(port, async () => {
+    const ideas = Array.from({ length: 12 }, (_, i) => ({
+      id: String(i + 1),
+      lineage_tasks: [{ task_id: String(8000 + i) }],
+      descent_tasks: Array.from({ length: 6 }, (__, j) => ({ task_id: String(9000 + i * 10 + j) })),
+    }));
+    await trailRemoval.attachRemovalToDescent(ideas);
+    assert.equal(calls, 1, 'one call for 12 ideas and 84 nodes, not one per idea');
+  });
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);