@bongos/core 1.19.1010 → 1.19.1012

package/tests/sky_read.mjs

@@ -0,0 +1,265 @@
+// tests/sky_read.mjs — GET /sky, the whole project sky in one read (task 1004230,
+// sky part 2 of 5; goal 1000095; ADR 0331, ADR 0227 §11).
+//
+// What this file pins is what the picture cannot show: that the wells and the
+// routes ARE the goal graph's (same read, not a copy); that a private goal stays
+// a well but loses every piece of prose, not only its title; that a task's
+// criterion link is the SAME link the version progress rollup computes, from the
+// same rows; that the payload is compact; that the cache is per viewer and
+// expires; and that identity comes from the authenticated request.
+//
+// DB-free: the pure shaper is run directly, the SQL against a recording fake
+// pool, the handler against stub collaborators (the goal_graph.mjs precedent).
+//
+// Run:  node tests/sky_read.mjs
+process.env.NODE_ENV = 'test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const skyLib = require(path.join(ROOT, 'modules/lifecycle/sky.js'));
+const { shapeSky, foldCriteria, skyRows, sky, skyCache, skyHandler } = skyLib;
+const { buildCriterionProgress } = require(path.join(ROOT, 'modules/lifecycle/done-when.js'));
+const { CUT_STATUSES, DONE_STATUSES } = require(path.join(ROOT, 'modules/lifecycle/task-status.js'));
+const manifest = JSON.parse(fs.readFileSync(path.join(ROOT, 'modules/lifecycle/module.json'), 'utf8'));
+const ROUTE_SRC = fs.readFileSync(path.join(ROOT, 'modules/lifecycle/routes/sky.js'), 'utf8');
+
+const { test, summary } = makeRunner();
+
+const CATS = new Map([['7', { id: 7, slug: 'security', label: 'Security' }]]);
+const g = (id, extra = {}) => ({ goal_id: String(id), title: `Goal ${id}`, status: 'open', version_id: 'V1', category_id: null, visible: true, task_total: 4, task_done: 1, ...extra });
+const e = (from, to, count = 1) => ({ from_goal_id: String(from), to_goal_id: String(to), count });
+const x = (id, extra = {}) => ({ goal_id: String(id), subtitle: `sub ${id}`, created_at: new Date('2026-09-01T00:00:00Z'), ...extra });
+// A flat (criterion, task) row in the shape both the rollup and the sky read.
+const cr = (id, goalId, taskId, taskStatus, extra = {}) => ({ id: String(id), goal_id: String(goalId), criterion_id: `slug-${id}`, criterion_md: `Criterion ${id}`, satisfied: false, sort_order: Number(id), task_id: taskId == null ? null : String(taskId), task_status: taskStatus ?? null, ...extra });
+const t = (id, goalId, extra = {}) => ({ id: String(id), goal_id: String(goalId), title: `Task ${id}`, status: 'ready', credits_reward: 30, created_on: '2026-09-02', idea_id: null, ...extra });
+
+// ---- shapeSky -------------------------------------------------------------------
+
+await test('the shape: wells carry their criteria and their compact tasks; edges are the graph\'s; counts add up', () => {
+  const out = shapeSky({
+    goals: [g(1), g(2)], edges: [e(1, 2, 3)], extras: [x(1), x(2)],
+    criteria: [cr(10, 1, 100, 'shipped'), cr(10, 1, 101, 'ready'), cr(11, 2, null)],
+    tasks: [t(100, 1, { status: 'shipped', idea_id: '555' }), t(101, 1), t(200, 2)],
+  });
+  assert.deepEqual(Object.keys(out), ['goals', 'edges', 'counts']);
+  assert.deepEqual(out.edges, [{ from: '1', to: '2', count: 3 }]);
+  assert.deepEqual(out.counts, { goals: 2, edges: 1, criteria: 2, tasks: 3 });
+  const w1 = out.goals[0];
+  assert.deepEqual(Object.keys(w1).sort(), ['category', 'created_at', 'criteria', 'goal_id', 'status', 'subtitle', 'task_done', 'task_total', 'tasks', 'title', 'version_id']);
+  assert.equal(w1.subtitle, 'sub 1');
+  assert.equal(w1.created_at, '2026-09-01T00:00:00.000Z');
+  assert.deepEqual(w1.criteria, [{ id: '10', criterion_id: 'slug-10', criterion_md: 'Criterion 10', satisfied: false, task_ids: ['100', '101'], pending_review: false }]);
+  assert.deepEqual(w1.tasks[0], { id: '100', title: 'Task 100', status: 'shipped', credits_reward: 30, created_on: '2026-09-02', idea_id: '555' });
+  assert.equal(w1.tasks[1].idea_id, null, 'a task not born of an idea carries null, not an empty string');
+  assert.deepEqual(out.goals[1].criteria[0].task_ids, [], 'a criterion with no linked task is an empty ring, not a missing one');
+});
+
+await test('nothing but the compact fields rides on a task — no description, no value summary, no notes', () => {
+  const out = shapeSky({ goals: [g(1)], extras: [x(1)], tasks: [t(1, 1, { description: 'long prose', value_summary: 'more prose', notes: 'and more' })] });
+  assert.deepEqual(Object.keys(out.goals[0].tasks[0]).sort(), ['created_on', 'credits_reward', 'id', 'idea_id', 'status', 'title']);
+});
+
+await test('a ring or a task under a goal that is not a well is dropped, not drawn to nowhere', () => {
+  const out = shapeSky({ goals: [g(1)], extras: [x(1)], criteria: [cr(10, 99, 5, 'ready')], tasks: [t(5, 99)] });
+  assert.deepEqual(out.counts, { goals: 1, edges: 0, criteria: 0, tasks: 0 });
+});
+
+await test('pending_review is derived the way the rollup derives it: every linked task terminal, at least one shipped, not yet satisfied', () => {
+  const out = shapeSky({
+    goals: [g(1)], extras: [x(1)],
+    criteria: [cr(10, 1, 1, 'shipped'), cr(10, 1, 2, 'abandoned'), cr(11, 1, 3, 'shipped'), cr(11, 1, 4, 'active'), cr(12, 1, 5, 'abandoned'), cr(13, 1, 6, 'shipped', { satisfied: true })],
+  });
+  const by = Object.fromEntries(out.goals[0].criteria.map((c) => [c.id, c]));
+  assert.equal(by['10'].pending_review, true, 'shipped + abandoned: abandoned is terminal, so nothing remains');
+  assert.equal(by['11'].pending_review, false, 'an active task still gates it');
+  assert.equal(by['12'].pending_review, true, 'all-abandoned DOES surface for review — the review flag is deliberately wider than auto-close (task 1002651, ADR 0183), and the sky must not narrow it');
+  assert.equal(by['13'].pending_review, false, 'already satisfied');
+  assert.equal(by['13'].satisfied, true);
+});
+
+await test('a PRIVATE goal the viewer cannot see stays a well with its counts, rings and tasks — but EVERY piece of prose is null, not only the title', () => {
+  const secret = { goal_id: '1', title: 'Secret roadmap', status: 'open', version_id: 'V1', category_id: 7, visible: false, task_total: 2, task_done: 0 };
+  const out = shapeSky({
+    goals: [secret, g(2)], edges: [e(2, 1)], extras: [x(1, { subtitle: 'the secret plan' }), x(2)],
+    criteria: [cr(10, 1, 100, 'ready', { criterion_md: 'secret criterion text' })],
+    tasks: [t(100, 1, { title: 'secret task title' })],
+  }, CATS);
+  const hidden = out.goals[0];
+  assert.equal(hidden.title, null);
+  assert.equal(hidden.subtitle, null);
+  assert.equal(hidden.category, null);
+  assert.equal(hidden.task_total, 2, 'counts are structure, not secrets (ADR 0112)');
+  assert.equal(hidden.criteria.length, 1, 'the ring is still drawn');
+  assert.equal(hidden.criteria[0].criterion_md, null, 'its text is not');
+  assert.deepEqual(hidden.criteria[0].task_ids, ['100'], 'the link survives — an id is not prose');
+  assert.equal(hidden.tasks[0].title, null);
+  assert.equal(hidden.tasks[0].status, 'ready');
+  assert.deepEqual(out.edges, [{ from: '2', to: '1', count: 1 }], 'and its routes still draw, or the structure would lie');
+  const json = JSON.stringify(out);
+  for (const leak of ['Secret roadmap', 'the secret plan', 'secret criterion text', 'secret task title', 'Security']) {
+    assert.equal(json.includes(leak), false, `"${leak}" is nowhere in the payload`);
+  }
+});
+
+await test('an empty corpus is a valid, empty sky', () => {
+  assert.deepEqual(shapeSky({}), { goals: [], edges: [], counts: { goals: 0, edges: 0, criteria: 0, tasks: 0 } });
+});
+
+// ---- the criterion→task link agrees with the progress rollup ------------------------
+
+await test('a task\'s criterion link is the SAME link the version progress rollup computes, from the same flat rows', () => {
+  // The rollup's rows carry cnum + task_title; the sky's carry goal_id + task_status.
+  // One set of rows, both projections, so the two folds see one truth.
+  const pairs = [[10, 1, 100, 'shipped'], [10, 1, 101, 'ready'], [11, 1, null, null], [12, 2, 200, 'active'], [12, 2, 201, 'shipped'], [12, 2, 202, 'abandoned']];
+  const rollupRows = pairs.map(([c, goal, task, status], i) => ({ cnum: c - 9, id: String(c), criterion_id: `slug-${c}`, criterion_md: `Criterion ${c}`, satisfied: false, goal_id: String(goal), task_id: task == null ? null : String(task), task_title: task == null ? null : `Task ${task}`, task_status: status }));
+  const skyRowsFlat = pairs.map(([c, goal, task, status]) => cr(c, goal, task, status));
+
+  const rollup = buildCriterionProgress('V1', rollupRows, 0, [{ id: '1', title: 'A', status: 'open' }, { id: '2', title: 'B', status: 'open' }]);
+  const folded = foldCriteria(skyRowsFlat);
+
+  const linkFromRollup = Object.fromEntries(rollup.criteria.map((c) => [c.id, c.tasks.map((tk) => String(tk.id))]));
+  const linkFromSky = Object.fromEntries(folded.map((c) => [c.id, c.task_ids]));
+  assert.deepEqual(linkFromSky, linkFromRollup);
+  // and the derived flag agrees too, criterion by criterion
+  const flagFromRollup = Object.fromEntries(rollup.criteria.map((c) => [c.id, c.pending_review]));
+  const flagFromSky = Object.fromEntries(folded.map((c) => [c.id, c.pending_review]));
+  assert.deepEqual(flagFromSky, flagFromRollup);
+  assert.equal(flagFromSky['12'], false, 'one active task keeps ring 12 open on both sides');
+});
+
+// ---- the SQL, against a recording pool -----------------------------------------------
+
+function fakePool({ goalRows = [], edgeRows = [], extraRows = [], criteriaRows = [], taskRows = [] } = {}) {
+  const calls = [];
+  return {
+    calls,
+    async query(sql, params) {
+      calls.push({ sql, params });
+      if (/FROM dependencies/.test(sql)) return { rows: edgeRows };
+      if (/FROM done_when_criteria/.test(sql)) return { rows: criteriaRows };
+      if (/subtitle/.test(sql)) return { rows: extraRows };
+      if (/FROM tasks t/.test(sql)) return { rows: taskRows };
+      return { rows: goalRows };
+    },
+  };
+}
+
+await test('the wells and the routes come from goal-graph.js\'s OWN read — the viewer, the Archon flag and the shared buckets ride as its bind parameters', async () => {
+  const pool = fakePool();
+  await skyRows({ versionId: 'V1', viewerId: 42, viewerIsArchon: true }, { pool });
+  const goalsQ = pool.calls.find((c) => /FROM goals g\s+JOIN tasks t/.test(c.sql));
+  assert.ok(goalsQ, 'the graph\'s goals query ran');
+  assert.deepEqual(goalsQ.params, ['V1', true, 42, CUT_STATUSES, DONE_STATUSES]);
+  assert.ok(pool.calls.some((c) => /FROM dependencies/.test(c.sql)), 'and its edges query');
+  assert.equal(pool.calls.length, 5, 'five queries, however many goals, criteria or tasks there are');
+  for (const { sql } of pool.calls) assert.equal(/\b42\b/.test(sql), false, 'no viewer id in any SQL text');
+});
+
+await test('the criterion→task join is read ONCE for every goal-bearing criterion — one query, flat rows, never per criterion or per version', async () => {
+  const pool = fakePool();
+  await skyRows({}, { pool });
+  const crit = pool.calls.filter((c) => /FROM done_when_criteria/.test(c.sql));
+  assert.equal(crit.length, 1);
+  assert.match(crit[0].sql, /LEFT JOIN task_criteria tc ON tc\.criterion_id = c\.id/);
+  assert.match(crit[0].sql, /c\.goal_id IS NOT NULL/);
+  assert.match(crit[0].sql, /LEFT JOIN tasks t\s+ON t\.id = tc\.task_id/, 'a criterion with no task still arrives (the rollup\'s LEFT JOIN)');
+});
+
+await test('the task query is compact by construction: no description, no value_summary, and the date is truncated in SQL', async () => {
+  const pool = fakePool();
+  await skyRows({}, { pool });
+  const tq = pool.calls.find((c) => /FROM tasks t\s+JOIN goals g/.test(c.sql));
+  const select = tq.sql.slice(tq.sql.indexOf('SELECT'), tq.sql.indexOf('FROM'));
+  assert.equal(/description|value_summary|notes|handoff/.test(select), false, select);
+  assert.match(select, /created_at::date/);
+  assert.match(select, /source_ref ~ '\^idea:\[0-9\]\+\$'/, 'the idea id comes from a strict source_ref match');
+});
+
+await test('a repeated ?version= (an array) binds as its first value on every query — never a driver-level 500', async () => {
+  const pool = fakePool();
+  await skyRows({ versionId: ['V1', 'V2'] }, { pool });
+  for (const { params } of pool.calls) assert.equal(params[0], 'V1');
+});
+
+await test('the payload is the shaped sky, categories included, from one fake read', async () => {
+  const pool = fakePool({
+    goalRows: [{ goal_id: '1', title: 'A', status: 'open', version_id: 'V1', category_id: 7, visible: true, task_total: 1, task_done: 0 }],
+    extraRows: [x(1)], criteriaRows: [cr(10, 1, 100, 'ready')], taskRows: [t(100, 1)],
+  });
+  const out = await sky({ viewerId: 1 }, { pool, categoryIndex: async () => CATS });
+  assert.equal(out.goals[0].category.label, 'Security');
+  assert.deepEqual(out.goals[0].criteria[0].task_ids, ['100']);
+  assert.equal(out.goals[0].tasks[0].title, 'Task 100');
+});
+
+// ---- the cache and the handler -------------------------------------------------------
+
+function run(handler, req) {
+  const res = { body: null, failed: null, headers: {}, set(k, v) { this.headers[k] = v; return this; }, json(b) { this.body = b; return this; }, fail(code, o) { this.failed = { code, o }; return this; } };
+  return handler(req, res).then(() => res);
+}
+
+await test('the handler reads identity from the authenticated request, never the query', async () => {
+  let seen = null;
+  const h = skyHandler({ read: async (o) => { seen = o; return { goals: [], edges: [], counts: {} }; }, log: { error() {} } });
+  const res = await run(h, { builder: { id: 7, rank: 'metic' }, query: { version: 'V2', viewerId: '999', viewerIsArchon: 'true' } });
+  assert.deepEqual(seen, { versionId: 'V2', viewerId: 7, viewerIsArchon: false });
+  assert.equal(res.body.cache.hit, false);
+  assert.equal(res.body.cache.ttl_seconds, 60);
+  assert.equal(res.headers['Cache-Control'], 'private, max-age=60', 'private — the payload is shaped for one viewer');
+});
+
+await test('the cache serves a second read within 60s without touching the database, says so, and expires after', async () => {
+  let now = 1_000_000;
+  let reads = 0;
+  const cache = skyCache({ now: () => now });
+  const h = skyHandler({ read: async () => { reads += 1; return { goals: [], edges: [], counts: {} }; }, log: { error() {} }, cache });
+  const req = { builder: { id: 7, rank: 'metic' }, query: {} };
+  const a = await run(h, req);
+  const b = await run(h, req);
+  assert.equal(reads, 1);
+  assert.equal(b.body.cache.hit, true);
+  assert.equal(b.body.cache.taken_at, a.body.cache.taken_at);
+  now += 61_000;
+  const c = await run(h, req);
+  assert.equal(reads, 2, 'expired — read again');
+  assert.equal(c.body.cache.hit, false);
+});
+
+await test('the cache is PER VIEWER — a payload shaped for one builder is never handed to another, and an Archon\'s never to a non-Archon', async () => {
+  const cache = skyCache({ now: () => 5 });
+  const seen = [];
+  const h = skyHandler({ read: async (o) => { seen.push(o); return { goals: [{ goal_id: '1', title: o.viewerIsArchon ? 'SEEN' : null }], edges: [], counts: {} }; }, log: { error() {} }, cache });
+  const archon = await run(h, { builder: { id: 1, rank: 'archon' }, query: {} });
+  const metic = await run(h, { builder: { id: 2, rank: 'metic' }, query: {} });
+  const other = await run(h, { builder: { id: 3, rank: 'metic' }, query: {} });
+  assert.equal(seen.length, 3, 'three viewers, three reads');
+  assert.equal(archon.body.goals[0].title, 'SEEN');
+  assert.equal(metic.body.goals[0].title, null);
+  assert.equal(other.body.cache.hit, false);
+  assert.notEqual(cache.key({ viewerId: 1, viewerIsArchon: true }), cache.key({ viewerId: 1, viewerIsArchon: false }));
+  assert.notEqual(cache.key({ viewerId: 2 }), cache.key({ viewerId: 2, versionId: 'V1' }), 'a version filter is its own entry');
+});
+
+await test('a failing read is a 500 with no internals in the body', async () => {
+  const h = skyHandler({ read: async () => { throw new Error('SELECT exploded at goals.secret_column'); }, log: { error() {} } });
+  const res = await run(h, { builder: { id: 7, rank: 'metic' }, query: {} });
+  assert.equal(res.failed.code, 'sky_failed');
+  assert.equal(res.failed.o.status, 500);
+  assert.equal(JSON.stringify(res.failed).includes('secret_column'), false);
+});
+
+// ---- the mount -----------------------------------------------------------------------
+
+await test('the route is contributed by the lifecycle manifest and gated to a signed-in builder', () => {
+  assert.ok(manifest.contributes.routes.includes('sky'), 'module.json contributes "sky"');
+  assert.match(ROUTE_SRC, /router\.get\('\/sky',\s*api\.requireBuilder,\s*sky\.skyHandler\(/);
+});
+
+summary();