@bongos/core 1.19.325 → 1.19.327

package/tests/help_requests.mjs

@@ -0,0 +1,263 @@
+// tests/help_requests.mjs — "I am stuck": a help request names who it needs
+// (task 1003171 / C01, goal 1000075, criterion collab-ask-for-help).
+//
+// The premise the whole goal rests on: the person you need is often NOT another
+// one of you. So a request addresses a CRAFT or one specific person — and the
+// interesting cases are the refusals, because a request addressed to everyone is
+// a broadcast and one addressed to nobody cannot be routed at all.
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const help = require(path.join(ROOT, 'modules', 'lifecycle', 'help-requests.js'));
+const read = (...p) => fs.readFileSync(path.join(ROOT, ...p), 'utf8');
+const reasons = (input) => help.validateHelpRequest(input).errors.map((e) => e.reason);
+
+// ---- the addressee rules --------------------------------------------------
+test('a craft request is valid', () => {
+  assert.deepEqual(reasons({ needs_craft: 'artist', what_is_stuck: 'is this readable?' }), []);
+});
+
+test('a person request is valid', () => {
+  assert.deepEqual(reasons({ needs_builder_id: 42, what_is_stuck: 'stuck on the migration' }), []);
+});
+
+test('addressed to NOBODY is refused', () => {
+  // Unroutable: there is no one to notify.
+  assert.ok(reasons({ what_is_stuck: 'help' }).includes('no_addressee'));
+});
+
+test('addressed to BOTH is refused, not resolved', () => {
+  // Picking one would send the request somewhere the asker did not choose.
+  assert.ok(reasons({ needs_craft: 'artist', needs_builder_id: 7, what_is_stuck: 'help' })
+    .includes('two_addressees'));
+});
+
+test('an unknown craft is refused', () => {
+  assert.ok(reasons({ needs_craft: 'wizard', what_is_stuck: 'help' }).includes('unknown_craft'));
+});
+
+test('the crafts are ADR 0174\'s three', () => {
+  assert.deepEqual(help.helpCrafts().sort(), ['artist', 'builder', 'ideator']);
+});
+
+test('THE VOCABULARY SEAM: builder maps to the discipline spelled engineer', () => {
+  // builders.preferred_disciplines spells this craft 'engineer'. If C02 re-derives
+  // the mapping instead of consuming disciplineForCraft, the two spellings drift
+  // and a builder silently matches nothing.
+  assert.equal(help.disciplineForCraft('builder'), 'engineer');
+  assert.equal(help.disciplineForCraft('artist'), 'artist');
+  assert.equal(help.disciplineForCraft('ideator'), 'ideator');
+  assert.equal(help.disciplineForCraft('wizard'), null);
+});
+
+// ---- what is stuck --------------------------------------------------------
+test('what_is_stuck is required and must carry content', () => {
+  for (const v of [undefined, '', '   ', '\n\t ']) {
+    assert.ok(reasons({ needs_craft: 'artist', what_is_stuck: v }).includes('required'),
+      `${JSON.stringify(v)} is not a description of being stuck`);
+  }
+});
+
+test('an over-long description is refused rather than truncated', () => {
+  const long = 'x'.repeat(help.MAX_STUCK + 1);
+  assert.ok(reasons({ needs_craft: 'artist', what_is_stuck: long }).includes('too_long'));
+});
+
+// ---- context --------------------------------------------------------------
+test('a request may name a task OR a goal, never both', () => {
+  assert.deepEqual(reasons({ needs_craft: 'artist', what_is_stuck: 'x', task_id: 1 }), []);
+  assert.deepEqual(reasons({ needs_craft: 'artist', what_is_stuck: 'x', goal_id: 1 }), []);
+  assert.ok(reasons({ needs_craft: 'artist', what_is_stuck: 'x', task_id: 1, goal_id: 2 })
+    .includes('two_contexts'), 'two contexts means two answers to "what is this about"');
+});
+
+test('context is optional', () => {
+  assert.deepEqual(reasons({ needs_craft: 'ideator', what_is_stuck: 'a shape question' }), []);
+});
+
+// ---- the schema keeps the same promises -----------------------------------
+test('the CHECK constraints mirror the validator, so neither is the only guard', () => {
+  // The validator exists so a refusal names the field; the constraints are the
+  // authority. Both must exist or one of the two promises is unkept.
+  const sql = read('modules', 'lifecycle', 'migrations', 'lifecycle_004_help_requests.sql');
+  assert.match(sql, /needs_craft IN \('artist', 'builder', 'ideator'\)/);
+  assert.match(sql, /\(needs_craft IS NOT NULL\) <> \(needs_builder_id IS NOT NULL\)/, 'exactly-one-addressee');
+  assert.match(sql, /NOT \(task_id IS NOT NULL AND goal_id IS NOT NULL\)/, 'at most one context');
+  assert.match(sql, /length\(btrim\(what_is_stuck\)\) > 0/, 'non-empty description');
+});
+
+test('the table is module-owned and lifecycle-namespaced', () => {
+  // A NEW table the module owns, unlike goals/tasks which are core tables it only
+  // queries — so fitness check 11 permits it (ADR 0083 §Decision #5).
+  const sql = read('modules', 'lifecycle', 'migrations', 'lifecycle_004_help_requests.sql');
+  assert.match(sql, /CREATE TABLE IF NOT EXISTS lifecycle_help_requests/);
+  assert.ok(!/ALTER TABLE (?!lifecycle_)/.test(sql), 'it alters no core table');
+});
+
+test('sub-speciality is deliberately NOT modelled yet', () => {
+  // The criterion says "and later on sub-speciality". Modelling it now would
+  // invent a taxonomy before anyone has asked a real question through this.
+  const sql = read('modules', 'lifecycle', 'migrations', 'lifecycle_004_help_requests.sql');
+  // Assert on the COLUMN LIST, not the file: the first version of this matched
+  // "speciality" anywhere outside a `--` comment and flagged the migration's own
+  // COMMENT ON TABLE, which says it is deliberately not modelled. Same
+  // over-broad-source-assertion reflex as learning 1000196.
+  const body = sql.slice(sql.indexOf('CREATE TABLE'), sql.indexOf(');'));
+  const columns = body.split('\n')
+    .map((l) => l.replace(/--.*$/, '').trim())
+    .filter((l) => l && !/^(CONSTRAINT|CHECK|\))/.test(l));
+  assert.ok(!columns.some((l) => /special/i.test(l)), `no speciality column: ${columns.filter((l) => /special/i.test(l))}`);
+});
+
+// ---- the read that makes a request answerable -----------------------------
+test('the addressed read excludes your own requests', () => {
+  // Answering your own request is not help.
+  const src = read('modules', 'lifecycle', 'help-requests.js');
+  const fn = src.slice(src.indexOf('async function listOpenForBuilder'));
+  assert.match(fn.slice(0, 700), /requested_by <> \$1/);
+  assert.match(fn.slice(0, 700), /status = 'open'/, 'and settled requests are history');
+});
+
+test('only the ASKER can settle their own request', () => {
+  const src = read('modules', 'lifecycle', 'help-requests.js');
+  const fn = src.slice(src.indexOf('async function setHelpRequestStatus'));
+  assert.match(fn.slice(0, 600), /requested_by = \$2/, 'ownership is in the WHERE, not in rank');
+  assert.match(fn.slice(0, 600), /status = 'open'/, 'and a settled request cannot be re-settled');
+});
+
+// ---- it stands alone ------------------------------------------------------
+test('C01 depends on nothing social — it must stay independently shippable', () => {
+  const src = read('modules', 'lifecycle', 'help-requests.js');
+  const routes = read('modules', 'lifecycle', 'routes', 'help-requests.js');
+  for (const forbidden of ['closeness', 'mingle', 'agora', 'Agora']) {
+    assert.ok(!new RegExp(`require\\([^)]*${forbidden}`, 'i').test(src + routes),
+      `must not depend on ${forbidden}`);
+  }
+});
+
+test('the route is registered in the module manifest', () => {
+  // A route file nothing mounts is a file, not a surface.
+  const manifest = JSON.parse(read('modules', 'lifecycle', 'module.json'));
+  assert.ok(manifest.contributes.routes.includes('help-requests'));
+});
+
+// ---- the four grader findings from the first pass -------------------------
+const needs = require(path.join(ROOT, 'modules', 'builder-settings', 'builder-needs.js'));
+
+test('THE BLOCKER: a request REACHES people, it is not merely stored', () => {
+  // The criterion is "...and it reaches the right craft". Storing is not reaching.
+  // The reach lands in the needs roster the hall card and the CLI nudge already
+  // render, rather than in a second notification system invented beside it.
+  const n = needs.helpRequestsNeed({ openHelpRequests: 2 });
+  assert.ok(n, 'a pending request produces a need');
+  assert.equal(n.state, 'action_needed', 'a person is waiting on a human answer');
+  assert.match(n.message, /2 people/);
+  assert.ok(n.action && n.action.href, 'and it says where to go');
+});
+
+test('no requests produces NO need, not a cheerful empty state', () => {
+  // An empty state is not an input the system needs from you.
+  for (const ctx of [{ openHelpRequests: 0 }, {}, { openHelpRequests: undefined }]) {
+    assert.equal(needs.helpRequestsNeed(ctx), null);
+  }
+});
+
+test('the need is registered, so every renderer picks it up', () => {
+  const roster = needs.computeNeeds({ openHelpRequests: 1, ownKeySet: true, rank: 'metic' });
+  assert.ok(roster.items.some((i) => i.id === 'help_requests'), 'it is in the roster');
+  assert.ok(roster.action_needed_count >= 1);
+});
+
+test('THE PRIVACY BUG: craft comes from the caller, never from the query', () => {
+  // The first version took ?craft= and validated it only against the enum, so any
+  // builder could read every request addressed to a craft they do not belong to
+  // by trying each value. The param may now only NARROW what the caller has.
+  const routes = read('modules', 'lifecycle', 'routes', 'help-requests.js');
+  assert.match(routes, /craftsForBuilder\(req\.builder\.id\)/, "the caller's own crafts are read");
+  const forMe = routes.slice(routes.indexOf("'GET /help-requests/for-me'"));
+  const body = forMe.slice(0, forMe.indexOf('errorCode'));
+  assert.match(body, /mine\.filter\(/, 'the query param only intersects');
+  assert.ok(!/listOpenForBuilder\(\{[^}]*craft: (want|req\.query)/.test(body),
+    'the raw query value never reaches the read');
+});
+
+test('a builder with no declared craft sees only requests addressed BY NAME', () => {
+  // Fail-closed: belonging to a craft is a claim about yourself the system must
+  // not assume on your behalf.
+  const src = read('modules', 'lifecycle', 'help-requests.js');
+  const fn = src.slice(src.indexOf('async function craftsForBuilder'));
+  assert.match(fn.slice(0, 500), /preferred_disciplines/);
+  assert.match(fn.slice(0, 500), /filter\(Boolean\)/, 'unmapped disciplines drop out');
+});
+
+test('the settle refusal no longer lets you enumerate ids', () => {
+  // The comment claimed one refusal for three cases; the code looked the row up
+  // and said which. Comment and code now agree.
+  const routes = read('modules', 'lifecycle', 'routes', 'help-requests.js');
+  const patch = routes.slice(routes.indexOf("'PATCH /help-requests/:id'"));
+  assert.ok(!/getHelpRequest/.test(patch), 'no existence lookup in the refusal path');
+  const reasons = patch.match(/reason: '[^']+'/g) || [];
+  assert.equal(reasons.length, 1, `exactly one refusal reason, got ${reasons}`);
+});
+
+test('both reads are capped', () => {
+  assert.equal(help.capRows(5), 5);
+  assert.equal(help.capRows(999999), help.MAX_ROWS, 'an absurd limit is capped');
+  for (const bad of [0, -1, null, 'x', 1.5]) {
+    assert.equal(help.capRows(bad), help.MAX_ROWS, `${bad} falls back to the cap`);
+  }
+});
+
+test('core reaches the count through the PORT, never by importing lifecycle', () => {
+  const me = read('src', 'bongos', 'routes', 'me.js');
+  assert.match(me, /openHelpRequestsFor/);
+  assert.ok(!/require\([^)]*modules\/lifecycle/.test(me), 'no module import in the kernel (ADR 0093)');
+  // The fail-open lives in the fan-out's IIFE now, not a standalone try/catch —
+  // the property is what matters, so assert the property.
+  const fan = me.slice(me.indexOf('] = await Promise.all(['));
+  const iife = fan.slice(fan.indexOf('openHelpRequestsFor') - 400, fan.indexOf('openHelpRequestsFor') + 300);
+  assert.match(iife, /catch \(_\) \{ return 0; \}/, 'fail-open: /me must not break on a collab read');
+});
+
+// ---- the second-pass grader findings --------------------------------------
+test('the /me read is IN the fan-out, not a serialized await before it', () => {
+  // /me is the session-open hot path; every other per-builder read is batched
+  // into one Promise.all to keep latency at one round-trip depth. The first
+  // version added ~2 serialized round trips in front of it (grader).
+  const me = read('src', 'bongos', 'routes', 'me.js');
+  const fanStart = me.indexOf('] = await Promise.all([');
+  const fanEnd = me.indexOf('\n    ]);', fanStart);
+  assert.ok(fanStart > 0 && fanEnd > fanStart);
+  const fan = me.slice(fanStart, fanEnd);
+  assert.match(fan, /openHelpRequestsFor/, 'the read is inside the fan-out');
+  assert.match(me.slice(0, fanStart).slice(-2000), /helpRequestCount,/, 'and destructured from it');
+  assert.ok(!/helpRequestCount = await /.test(me), 'no standalone await remains');
+});
+
+test('the count is ONE query, and its craft map is generated from the JS map', () => {
+  // Two sequential queries on a hot path is a cost every builder pays on every
+  // open. The SQL CASE is generated from DISCIPLINE_TO_CRAFT so the two spellings
+  // of 'engineer' cannot drift apart.
+  const sql = help.craftMapSql('d');
+  assert.match(sql, /WHEN 'engineer' THEN 'builder'/);
+  for (const craft of help.helpCrafts()) {
+    const disc = help.disciplineForCraft(craft);
+    assert.ok(sql.includes(`WHEN '${disc}' THEN '${craft}'`), `${disc}->${craft} is in the SQL map`);
+  }
+  const src = read('modules', 'lifecycle', 'help-requests.js');
+  const fn = src.slice(src.indexOf('async function countOpenForBuilder'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.equal((body.match(/activePool\.query/g) || []).length, 1, 'exactly one round trip');
+});
+
+test('a help request addressed to a non-existent builder is a named 400', () => {
+  const routes = read('modules', 'lifecycle', 'routes', 'help-requests.js');
+  assert.match(routes, /builderExists/);
+  assert.match(routes, /no_such_builder/, 'the refusal names the field, not an FK 500');
+});