@bongos/core 1.19.1042 → 1.19.1044

package/tests/npm_release_where.mjs

@@ -0,0 +1,323 @@
+// tests/npm_release_where.mjs — a task's own page says where its code is (task 1004301):
+// the npm-release module's one-task reading (readTaskWhere), its route, the browser widget
+// that draws the line, and the core seam that puts the widget on the task page without the
+// page naming the module.
+//
+// WHAT IS AT RISK. The line is read by the person who shipped the task, and the case the
+// task exists for is the ship that never landed: "done, but not merged" must be said for a
+// completed/confirmed task, never a version it is not in. Every other stage must be the
+// deploy page's own answer, the widget must write only into the slot the page gives it and
+// only for the task still on screen, and a failure must draw nothing rather than something
+// wrong.
+//
+// Run:  node tests/npm_release_where.mjs
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { npmTarball, npmPackument, fakeHttpsGet } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { readTaskWhere } = require('../modules/npm-release/work.js');
+const buildRouter = require('../modules/npm-release/routes/task-where.js');
+
+const ORIGIN = 'https://registry.npmjs.org';
+const PKG = '@bongos/core';
+const TIMES = {
+  '1.0.1': '2026-09-22T10:00:00.000Z',
+  '1.0.2': '2026-09-23T10:00:00.000Z',
+  '1.0.3': '2026-09-24T10:00:00.000Z',
+  '1.0.4': '2026-09-25T10:00:00.000Z',
+};
+const NOTES = {
+  '1.0.1': [{ id: '11', text: 'Released long ago.' }],
+  '1.0.2': [{ id: '12', text: 'Running here, not released.' }],
+  '1.0.3': [{ id: '13', text: 'Published, not running.' }, { text: 'A hand-landed change nobody numbered.' }],
+  '1.0.4': [],
+};
+const TASKS = {
+  11: { status: 'shipped', value_summary: 'x', at: '2026-09-21T12:00:00Z' },
+  12: { status: 'shipped', value_summary: 'x', at: '2026-09-22T12:00:00Z' },
+  13: { status: 'shipped', value_summary: 'x', at: '2026-09-23T12:00:00Z' },
+  14: { status: 'shipped', value_summary: 'A hand-landed change nobody numbered.', at: '2026-09-23T13:00:00Z' },
+  15: { status: 'shipped', value_summary: 'Merged after the last version.', at: '2026-09-25T12:00:00Z' },
+  16: { status: 'shipped', value_summary: 'A scope edit.', at: '2026-09-20T12:00:00Z' },
+  20: { status: 'confirmed', value_summary: 'Stranded.', at: '2026-09-25T12:00:00Z' },
+  21: { status: 'completed', value_summary: null, at: '2026-09-25T13:00:00Z' },
+  30: { status: 'active', value_summary: null, at: '2026-09-25T13:00:00Z' },
+};
+
+function fakePool() {
+  const queries = [];
+  return {
+    queries,
+    async query(sql, params) {
+      queries.push({ sql, params });
+      if (/FROM tasks WHERE id = \$1::bigint/.test(sql)) {
+        const t = TASKS[params[0]];
+        return { rows: t ? [{ id: params[0], ...t }] : [] };
+      }
+      throw new Error(`unexpected query: ${sql}`);
+    },
+  };
+}
+const freshStore = () => ({ packument: { at: 0, value: null, inflight: null }, notes: { version: null, at: 0, value: null, inflight: null } });
+
+function setup({ latest = '1.0.1', pkStatus = 200 } = {}) {
+  const versions = Object.keys(TIMES);
+  const newest = versions[versions.length - 1];
+  const fg = fakeHttpsGet({
+    [`${ORIGIN}/@bongos%2fcore`]: { status: pkStatus, body: pkStatus === 200 ? npmPackument({ versions, latest, times: TIMES }) : 'nope' },
+    [`${ORIGIN}/@bongos/core/-/core-${newest}.tgz`]: { body: npmTarball({ notes: NOTES }) },
+  });
+  const pool = fakePool();
+  const store = freshStore();
+  const read = (id, over = {}) => readTaskWhere({ pool, id, pkg: PKG, live: '1.0.2', get: fg.get, store, installedNotes: () => null, now: () => Date.parse('2026-09-26T13:00:00Z'), ...over });
+  return { read, pool, asked: fg.asked };
+}
+
+// ---- the reading ---------------------------------------------------------------------
+
+test('each shipped task gets the deploy page\'s own stage and the version that carries it', async () => {
+  const { read } = setup();
+  const pick = async (id) => { const w = await read(id); return [w.stage, w.version]; };
+  assert.deepEqual(await pick(11), ['released', '1.0.1']);
+  assert.deepEqual(await pick(12), ['live_unreleased', '1.0.2']);
+  assert.deepEqual(await pick(13), ['not_live', '1.0.3']);
+  assert.deepEqual(await pick(14), ['not_live', '1.0.3'], 'a hand-landed merge is matched on the ship summary');
+  assert.deepEqual(await pick(15), ['unversioned', null], 'merged after the newest version went out');
+  assert.deepEqual(await pick(16), ['no_version', null]);
+  const w = await read(12);
+  assert.equal(w.live, '1.0.2');
+  assert.equal(w.released, '1.0.1');
+  assert.equal(w.partial, false);
+  assert.equal(w.task_id, '12');
+});
+
+test('a task marked done whose code never merged says so — the case this line exists for', async () => {
+  const { read } = setup();
+  for (const id of [20, 21]) {
+    const w = await read(id);
+    assert.equal(w.stage, 'not_merged', String(id));
+    assert.equal(w.version, null);
+  }
+});
+
+test('a task not yet done has nothing to place, and costs no registry read', async () => {
+  const { read, asked } = setup();
+  const w = await read(30);
+  assert.deepEqual(w, { task_id: '30', package: PKG, status: 'active', stage: null });
+  assert.deepEqual(asked, [], 'no packument, no tarball');
+});
+
+test('an id that is not a task answers null; one that is not a number is never queried', async () => {
+  const { read, pool } = setup();
+  assert.equal(await read(999), null);
+  for (const bad of ['1; DROP', '', null, '12a', '1234567890123']) assert.equal(await read(bad), null, String(bad));
+  assert.equal(pool.queries.length, 1, 'only the real id reached the database');
+});
+
+test('a registry that does not answer is a partial reading, said so', async () => {
+  const { read } = setup({ pkStatus: 500 });
+  const w = await read(12);
+  assert.equal(w.partial, true);
+  assert.equal(w.stage, 'no_version', 'with no notes nothing can be placed in a version');
+});
+
+test('the offered flag follows the deploy page: published before this hall ran it, and already released', async () => {
+  const { read } = setup({ latest: '1.0.4' });
+  const w = await read(13);
+  assert.equal(w.stage, 'not_live');
+  assert.equal(w.offered, true);
+});
+
+// ---- the route -----------------------------------------------------------------------
+
+function layers(read) {
+  const router = buildRouter({ read });
+  const layer = router.stack.find((l) => l.route && l.route.path === '/npm-release/task/:id');
+  return layer.route.stack.map((s) => s.handle);
+}
+function call(handler, id) {
+  return new Promise((resolve) => {
+    const res = { code: 200, status(c) { this.code = c; return this; }, json(v) { resolve({ status: this.code, body: v }); } };
+    Promise.resolve(handler({ params: { id } }, res)).catch((e) => resolve({ status: 'threw', body: e }));
+  });
+}
+
+test('the route asks only for a signed-in builder — nothing on the line is not already public', () => {
+  const handles = layers(async () => ({}));
+  assert.equal(handles.length, 2, 'requireBuilder, then the handler');
+  const src = fs.readFileSync(path.join(ROOT, 'modules/npm-release/routes/task-where.js'), 'utf8');
+  assert.match(src, /'\/npm-release\/task\/:id',\s*\n\s*api\.requireBuilder,\s*\n\s*async/);
+  assert.doesNotMatch(src, /requirePermission|api\.requireRank\(/);
+});
+
+test('the route: 400 for a non-number, 404 for no task, 500 plainly on a failed read', async () => {
+  const h = (read) => layers(read)[1];
+  assert.deepEqual((await call(h(async () => ({ stage: 'released' })), '12')).body, { stage: 'released' });
+  assert.equal((await call(h(async () => { throw new Error('no'); }), 'x')).status, 400);
+  assert.equal((await call(h(async () => null), '12')).status, 404);
+  const failed = await call(h(async () => { throw new Error('pool gone'); }), '12');
+  assert.equal(failed.status, 500);
+  assert.equal(failed.body.error.code, 'task_where_failed');
+  assert.doesNotMatch(JSON.stringify(failed.body), /pool gone/, 'the internal message stays in the log');
+});
+
+// ---- the widget ----------------------------------------------------------------------
+
+const WIDGET_SRC = fs.readFileSync(path.join(ROOT, 'modules/npm-release/public/task-widget.js'), 'utf8');
+
+function bootWidget(answer, { shown = null } = {}) {
+  const slot = { _html: '', set innerHTML(v) { this._html = String(v); }, get innerHTML() { return this._html; } };
+  const listeners = {};
+  const asked = [];
+  const windowObj = {
+    OTBTaskShown: shown,
+    BongosClient: { createClient: () => ({ request: async (m, url) => { asked.push(url); return answer(url); } }) },
+  };
+  const documentObj = {
+    getElementById: (id) => (id === 'task-contrib' ? slot : null),
+    addEventListener: (ev, fn) => { (listeners[ev] ||= []).push(fn); },
+  };
+  const sandbox = { window: windowObj, document: documentObj, console, Map, Promise, encodeURIComponent, String };
+  vm.createContext(sandbox);
+  vm.runInContext(WIDGET_SRC, sandbox, { filename: 'task-widget.js' });
+  const announce = (detail) => { windowObj.OTBTaskShown = detail; for (const fn of listeners['otb:task-shown'] || []) fn({ detail }); };
+  const settle = async () => { for (let i = 0; i < 6; i++) await new Promise((r) => setTimeout(r, 0)); };
+  return { slot, asked, announce, settle, win: windowObj };
+}
+const ok = (data) => ({ status: 200, ok: true, data });
+
+test('each stage reads as one plain sentence under the rail', async () => {
+  const cases = [
+    [{ stage: 'released', version: '1.19.1036', live: '1.19.1040' }, /In <b>1\.19\.1036<\/b> · running here · released to other projects\./],
+    [{ stage: 'live_unreleased', version: '1.19.1040', live: '1.19.1040' }, /In <b>1\.19\.1040<\/b> · running here · not released to other projects yet\./],
+    [{ stage: 'not_live', version: '1.19.1041' }, /In <b>1\.19\.1041<\/b> · published, not running here yet\./],
+    [{ stage: 'not_live', version: '1.19.1041', offered: true }, /not running here yet · already offered to other projects\./],
+    [{ stage: 'unversioned' }, /Merged, waiting for the next published version\./],
+    [{ stage: 'no_version' }, /Shipped, though no published version lists it — usually a change that needed no code/],
+    [{ stage: 'not_merged' }, /<b>Done, but not merged\.<\/b> The ledger marks this task done, and its code is not on main yet/],
+  ];
+  for (const [w, re] of cases) {
+    const b = bootWidget(() => ok(w));
+    b.announce({ id: '12', status: w.stage === 'not_merged' ? 'confirmed' : 'shipped' });
+    await b.settle();
+    assert.match(b.slot.innerHTML, re, w.stage);
+  }
+});
+
+test('a partial reading is said; a version is escaped; an unknown stage draws nothing', async () => {
+  const partial = bootWidget(() => ok({ stage: 'no_version', partial: true }));
+  partial.announce({ id: '12', status: 'shipped' });
+  await partial.settle();
+  assert.match(partial.slot.innerHTML, /\(a partial reading: the registry or the release notes could not be read\)/);
+
+  const evil = bootWidget(() => ok({ stage: 'released', version: '<img src=x>' }));
+  evil.announce({ id: '12', status: 'shipped' });
+  await evil.settle();
+  assert.match(evil.slot.innerHTML, /In <b>&lt;img src=x&gt;<\/b>/);
+
+  const odd = bootWidget(() => ok({ stage: 'somewhere-else' }));
+  odd.announce({ id: '12', status: 'shipped' });
+  await odd.settle();
+  assert.equal(odd.slot.innerHTML, '');
+});
+
+test('work not yet done asks nothing; a failure draws nothing rather than something wrong', async () => {
+  const idle = bootWidget(() => ok({ stage: 'released' }));
+  idle.announce({ id: '12', status: 'active' });
+  await idle.settle();
+  assert.deepEqual(idle.asked, []);
+  assert.equal(idle.slot.innerHTML, '');
+
+  for (const answer of [() => ({ status: 403, ok: false, data: null }), () => ({ status: 404, ok: false, data: null }), () => { throw new Error('offline'); }]) {
+    const b = bootWidget(answer);
+    b.announce({ id: '12', status: 'shipped' });
+    await b.settle();
+    assert.equal(b.slot.innerHTML, '');
+  }
+});
+
+test('one read per task, however often the page re-renders — and never for a task no longer shown', async () => {
+  const b = bootWidget(() => ok({ stage: 'released', version: '1.0.1' }));
+  b.announce({ id: '12', status: 'shipped' });
+  b.announce({ id: '12', status: 'shipped' });
+  await b.settle();
+  assert.deepEqual(b.asked, ['/api/bongos/npm-release/task/12']);
+
+  // The page moved on to another task while the first read was in flight.
+  let release;
+  const slow = bootWidget(() => new Promise((r) => { release = () => r(ok({ stage: 'released', version: '9.9.9' })); }));
+  slow.announce({ id: '12', status: 'shipped' });
+  slow.win.OTBTaskShown = { id: '13', status: 'active' };
+  release();
+  await slow.settle();
+  assert.equal(slow.slot.innerHTML, '', 'task 12\'s line is not written onto task 13\'s page');
+});
+
+test('a widget that loads after the first announcement still draws the line', async () => {
+  const b = bootWidget(() => ok({ stage: 'released', version: '1.0.1' }), { shown: { id: '12', status: 'shipped' } });
+  await b.settle();
+  assert.match(b.slot.innerHTML, /In <b>1\.0\.1<\/b>/);
+});
+
+// ---- the seam that puts it on the page -----------------------------------------------
+
+test('the module declares the task page section and ships its widget; the seam guard counts it wired', () => {
+  const manifest = JSON.parse(fs.readFileSync(path.join(ROOT, 'modules/npm-release/module.json'), 'utf8'));
+  assert.deepEqual(manifest.contributes.uiSections, ['task-where']);
+  assert.ok(manifest.contributes.routes.includes('task-where'));
+  assert.ok(fs.existsSync(path.join(ROOT, 'modules/npm-release/public/task-widget.js')));
+  const guard = fs.readFileSync(path.join(ROOT, 'scripts/gds/seam-wiring-guard.js'), 'utf8');
+  assert.match(guard, /alternates: \(dir\) => \[path\.join\(dir, 'public', 'task-widget\.js'\)\]/);
+});
+
+test('the server injects task widgets just before task.js, and names no module doing it', () => {
+  const { injectModuleHallWidgets } = require('../src/bongos/serve-internal.js');
+  const page = '<body><script src="/builders/md-reader.js" defer></script><script src="/builders/task.js?v=abc" defer></script></body>';
+  const out = injectModuleHallWidgets(page, [{ key: 'npm-release', src: '/modules/npm-release/public/task-widget.js' }], 'task');
+  assert.ok(out.indexOf('/modules/npm-release/public/task-widget.js') < out.indexOf('/builders/task.js'), 'before the consumer, so its listener exists first');
+  assert.ok(out.indexOf('/builders/md-reader.js') < out.indexOf('task-widget.js'));
+  assert.match(out, /<script src="\/modules\/npm-release\/public\/task-widget\.js" defer><\/script>/);
+  assert.equal(injectModuleHallWidgets(page, [], 'task'), page, 'no module, no change');
+  const index = '<script src="/builders/builders.js?v=1"></script>';
+  assert.match(injectModuleHallWidgets(index, [{ key: 'x', src: '/m.js' }]), /^<script src="\/m\.js" defer><\/script><script src="\/builders\/builders\.js/, 'the index injection is unchanged');
+  const si = fs.readFileSync(path.join(ROOT, 'src/bongos/serve-internal.js'), 'utf8');
+  assert.match(si, /hallWidgetScripts\(\{ isEnabled: isModuleEnabled, file: 'task-widget\.js' \}\),\s*\n\s*'task',/);
+});
+
+// ---- the fixes the first grade asked for ---------------------------------------------
+
+test('the installed release notes are read from disk once per process, not once per view', async () => {
+  const realRead = fs.readFileSync;
+  let reads = 0;
+  fs.readFileSync = function (p, ...rest) {
+    if (String(p).endsWith('release-notes.json')) reads++;
+    return realRead.call(this, p, ...rest);
+  };
+  try {
+    const { pool } = setup();
+    const fg = fakeHttpsGet({ [`${ORIGIN}/@bongos%2fcore`]: { status: 500, body: 'down' } });
+    for (let i = 0; i < 3; i++) {
+      // No installedNotes: the module's own default, which is the path every task view takes.
+      await readTaskWhere({ pool, id: 12, pkg: PKG, live: '1.0.2', get: fg.get, store: freshStore() });
+    }
+  } finally { fs.readFileSync = realRead; }
+  assert.equal(reads, 1, 'three task views, one disk read');
+});
+
+test('the widget keeps only the last few readings', async () => {
+  const b = bootWidget((url) => ok({ stage: 'released', version: url.split('/').pop() }));
+  for (let i = 1; i <= 12; i++) b.announce({ id: String(i), status: 'shipped' });
+  await b.settle();
+  b.announce({ id: '12', status: 'shipped' });
+  b.announce({ id: '1', status: 'shipped' });
+  await b.settle();
+  assert.equal(b.asked.filter((u) => u.endsWith('/12')).length, 1, 'a recent task is served from the cache');
+  assert.equal(b.asked.filter((u) => u.endsWith('/1')).length, 2, 'an old one was evicted and is read again');
+});