@bongos/core 1.19.358 → 1.19.359

package/tests/task_recommendations.mjs

@@ -0,0 +1,297 @@
+// tests/task_recommendations.mjs — passing a task RECOMMENDS it; it never
+// transfers the claim (task 1003173 / C03, goal 1000075; criterion
+// collab-pass-a-task, ADR 0187 §3).
+//
+// The criterion names four testable promises, and this file is organised around
+// them, because each one is a thing the code could plausibly have done instead:
+//   1. a pass creates a recommendation and never a claim;
+//   2. the recipient's claim is their own action;
+//   3. the recommendation and its author are readable afterwards;
+//   4. declining leaves no penalty on either party.
+//
+// Promises 1 and 4 are ABSENCE claims — "this code does not do X" — so they are
+// asserted against the source, which is the only place an absence is visible. A
+// behavioural test can show that a claim was not created on one path; it cannot
+// show that no path creates one.
+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 recs = require(path.join(ROOT, 'modules', 'lifecycle', 'task-recommendations.js'));
+const read = (...p) => fs.readFileSync(path.join(ROOT, ...p), 'utf8');
+
+const SRC = read('modules', 'lifecycle', 'task-recommendations.js');
+const ROUTES = read('modules', 'lifecycle', 'routes', 'recommendations.js');
+const SQL = read('modules', 'lifecycle', 'migrations', 'lifecycle_005_task_recommendations.sql');
+
+const SENDER = 7;
+const good = { task_id: 42, recommended_to: 9, reason: 'you shipped the last three hall surfaces' };
+const reasons = (input, sender = SENDER) => recs.validateRecommendation(input, sender).errors.map((e) => e.reason);
+
+// ── PROMISE 1: a pass creates a recommendation and NEVER a claim ────────────
+
+test('THE DECISION: nothing in this surface writes a claim', () => {
+  // The criterion exists because a pass that moved a claim would be a task
+  // quietly changing hands. Asserted as an absence over the whole surface: any
+  // INSERT/UPDATE against claims, from either file, is the thing forbidden.
+  for (const [name, src] of [['data layer', SRC], ['routes', ROUTES]]) {
+    assert.ok(!/\bINSERT\s+INTO\s+claims\b/i.test(src), `${name} must not insert a claim`);
+    assert.ok(!/\bUPDATE\s+claims\b/i.test(src), `${name} must not update a claim`);
+    assert.ok(!/\bDELETE\s+FROM\s+claims\b/i.test(src), `${name} must not delete a claim`);
+  }
+});
+
+test('and it does not reach the claim path indirectly either', () => {
+  // A require of the claim machinery would be the seam the decision refuses,
+  // even if today it went unused.
+  for (const [name, src] of [['data layer', SRC], ['routes', ROUTES]]) {
+    assert.ok(!/require\([^)]*claim/i.test(src), `${name} must not require the claim path`);
+    assert.ok(!/claimTask/.test(src), `${name} must not call claimTask`);
+  }
+});
+
+test('THE UNUSED SEAM: there is no transfer function, and no name promising one', () => {
+  // "Do NOT build a transfer path or a seam for one; the decision was
+  // recommend-only, and an unused seam is a cost." A function called transfer/
+  // reassign/handOff would read to the next author as an intention.
+  const exported = Object.keys(recs);
+  const suspect = exported.filter((k) => /transfer|reassign|handoff|hand_off|takeover/i.test(k));
+  assert.deepEqual(suspect, [], `no transfer-shaped export: ${suspect}`);
+});
+
+test('the schema has NO accepted status — accepting is claiming, which lives elsewhere', () => {
+  // A status saying "accepted" would be a second, weaker record of holding work,
+  // and would make this table look like the place claims come from.
+  assert.match(SQL, /status IN \('open', 'declined', 'withdrawn'\)/);
+  // Comments STRIPPED before asserting: both files DISCUSS why there is no
+  // accepted status, and matching the prose that explains the rule as a
+  // violation of it is the over-broad-source-assertion reflex of learning
+  // 1000196 — the same trap the sibling C01 test documents.
+  const sqlCode = SQL.replace(/^\s*--.*$/gm, '');
+  const routeCode = ROUTES.replace(/^\s*\/\/.*$/gm, '');
+  assert.ok(!/'accepted'/.test(sqlCode), 'no accepted status');
+  assert.ok(!/\baccept\b/i.test(routeCode), 'and no accept route');
+});
+
+test('the schema carries no transfer column', () => {
+  const body = SQL.slice(SQL.indexOf('CREATE TABLE'), SQL.indexOf('\n);'));
+  const columns = body.split('\n')
+    .map((l) => l.replace(/--.*$/, '').trim())
+    .filter((l) => l && !/^(CONSTRAINT|CHECK|\))/.test(l));
+  const suspect = columns.filter((l) => /transferred|claimed_by|assigned_to|accepted/i.test(l));
+  assert.deepEqual(suspect, [], `no transfer-shaped column: ${suspect}`);
+});
+
+// ── PROMISE 2: the recipient's claim is their own action ────────────────────
+
+test('the recipient read reports the TASK STATUS, not a claim grant', () => {
+  // What the recipient gets is enough to judge, and nothing that says they now
+  // hold it. Claimability stays the claim path's answer — duplicating that
+  // judgement here would be a second, staler copy of a rule that has an owner.
+  const fn = SRC.slice(SRC.indexOf('async function listForRecipient'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.match(body, /t\.status\s+AS task_status/, 'the task\'s own status is reported');
+  assert.ok(!/can_claim|claimable|is_claimable/i.test(body), 'and no claimability verdict is invented');
+});
+
+test('a recommendation to yourself is refused', () => {
+  // Not a recommendation. Checked against the AUTHENTICATED sender, never a
+  // client-supplied id — which is why validateRecommendation takes it as an
+  // argument rather than reading it out of the body.
+  assert.ok(reasons({ ...good, recommended_to: SENDER }).includes('cannot_recommend_to_self'));
+  assert.match(ROUTES, /validateRecommendation\(req\.body, req\.builder\.id\)/,
+    'the sender comes from the session');
+});
+
+test('the not-self rule is in the schema too, so neither guard is the only one', () => {
+  assert.match(SQL, /recommended_by <> recommended_to/);
+});
+
+// ── PROMISE 3: the recommendation and its author are readable afterwards ────
+
+test('THE LEDGER: the reason is required, not optional', () => {
+  // The criterion's own argument: an untraced recommendation is indistinguishable
+  // from a task quietly changing hands. A reason the sender must write is what
+  // makes this a record of a judgement rather than a nudge.
+  for (const v of [undefined, null, '', '   ', '\n\t ']) {
+    assert.ok(reasons({ ...good, reason: v }).includes('required'),
+      `${JSON.stringify(v)} is not a reason`);
+  }
+  assert.deepEqual(reasons(good), [], 'a real reason validates');
+});
+
+test('the reason is enforced in the schema and the route body as well', () => {
+  // Three guards that agree: the CHECK is the authority, the validator names the
+  // field, and the route schema refuses before either runs.
+  assert.match(SQL, /reason\s+text NOT NULL/);
+  assert.match(SQL, /length\(btrim\(reason\)\) > 0/);
+  assert.match(ROUTES, /reason: \{ required: true, type: 'string', minLength: 1/);
+});
+
+test('an over-long reason is refused rather than truncated', () => {
+  assert.ok(reasons({ ...good, reason: 'x'.repeat(recs.MAX_REASON + 1) }).includes('too_long'));
+});
+
+test('the per-task history reads EVERY status, so a declined pass stays on the record', () => {
+  // "Readable afterwards" is the point. A history filtered to open would erase
+  // exactly the case the ledger exists to document.
+  const fn = SRC.slice(SRC.indexOf('async function listForTask'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.match(body, /WHERE r\.task_id = \$1/);
+  assert.ok(!/status = 'open'/.test(body), 'the per-task history is not filtered to open');
+});
+
+test('the history names the AUTHOR, not just the recommendation', () => {
+  const fn = SRC.slice(SRC.indexOf('async function listForTask'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.match(body, /sender\.github_login/, 'who recommended it');
+  assert.match(body, /r\.reason/, 'and why');
+});
+
+test("the sender's own list is unfiltered by default", () => {
+  const fn = SRC.slice(SRC.indexOf('async function listFromSender'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.match(body, /\$2::text IS NULL OR r\.status = \$2/, 'status is an optional narrowing');
+});
+
+// ── PROMISE 4: declining leaves no penalty on either party ──────────────────
+
+test('THE NO-PENALTY RULE: declining touches nothing but its own row', () => {
+  // Asserted as an absence, because that is what "costs nothing" means. If a
+  // penalty ever appears for declining, it did not come from here.
+  const fn = SRC.slice(SRC.indexOf('async function declineRecommendation'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.match(body, /UPDATE lifecycle_task_recommendations/);
+  assert.ok(!/builders|credits|karma|credit_log|peer_votes/i.test(body),
+    'declining writes nothing about either person');
+});
+
+test('and no penalty machinery is reachable from this surface at all', () => {
+  for (const [name, src] of [['data layer', SRC], ['routes', ROUTES]]) {
+    const code = src.replace(/^\s*\/\/.*$/gm, '');   // comments may DISCUSS karma
+    for (const forbidden of ['karma', 'credit', 'penalt', 'cooldown', 'strike']) {
+      assert.ok(!new RegExp(forbidden, 'i').test(code),
+        `${name} must not reach ${forbidden} machinery`);
+    }
+  }
+});
+
+test('a decline is NOT final — the same task can be recommended again', () => {
+  // A permanent unique key would quietly make declining final, which is a cost.
+  // The uniqueness is partial, on open rows only.
+  assert.match(SQL, /CREATE UNIQUE INDEX[^;]*lifecycle_task_recommendations_open_uniq[^;]*WHERE status = 'open'/s);
+});
+
+test('a duplicate OPEN recommendation is a named conflict, not a 500', () => {
+  // The same judgement repeated. Not something the sender can fix by changing
+  // the body, so it is not a validation error.
+  assert.match(SRC, /ON CONFLICT DO NOTHING/);
+  assert.match(SRC, /reason: 'already_open'/);
+  assert.match(ROUTES, /recommendation_already_open', 409/);
+});
+
+// ── who may settle what ─────────────────────────────────────────────────────
+
+test('the RECIPIENT declines and the SENDER withdraws — each scoped in the WHERE', () => {
+  const dec = SRC.slice(SRC.indexOf('async function declineRecommendation'));
+  assert.match(dec.slice(0, 600), /recommended_to = \$2/, 'ownership is in the WHERE, not in rank');
+  const wd = SRC.slice(SRC.indexOf('async function withdrawRecommendation'));
+  assert.match(wd.slice(0, 600), /recommended_by = \$2/);
+  for (const fn of [dec, wd]) {
+    assert.match(fn.slice(0, 600), /status = 'open'/, 'a settled recommendation cannot be re-settled');
+  }
+});
+
+test('the settle refusal does not let you enumerate ids', () => {
+  // ONE refusal for absent / not-yours / already-settled. Looking the row up to
+  // say which would leak existence — the lesson help-requests learned from its
+  // own grader round (task 1003171).
+  const patch = ROUTES.slice(ROUTES.indexOf("'PATCH /task-recommendations/:id'"));
+  const body = patch.slice(0, patch.indexOf('errorCode'));
+  assert.match(body, /recommendation_not_settleable', 404/);
+  assert.ok(!/getRecommendation|SELECT/i.test(body), 'no lookup before the refusal');
+});
+
+// ── the shape the module contract requires ──────────────────────────────────
+
+test('the table is module-owned and lifecycle-namespaced', () => {
+  // A NEW table the module owns outright, unlike tasks/builders which are core
+  // tables it only references — so fitness check 11 permits it (ADR 0083 §5).
+  assert.match(SQL, /CREATE TABLE IF NOT EXISTS lifecycle_task_recommendations/);
+  assert.ok(!/ALTER TABLE (?!lifecycle_)/.test(SQL), 'it alters no core table');
+});
+
+test('the migration registers itself', () => {
+  assert.match(SQL, /INSERT INTO schema_migrations \(version\) VALUES \('lifecycle_005_task_recommendations'\)/);
+});
+
+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('recommendations'));
+});
+
+test('core reaches the count through the PORT, never by importing the module', () => {
+  // ADR 0093: core imports no module. /me needs the count for the needs roster,
+  // so the lifecycle port exposes it the same way it exposes the help-request one.
+  const lifecycle = read('modules', 'lifecycle', 'lifecycle.js');
+  assert.match(lifecycle, /openTaskRecommendationsFor:/);
+  const me = read('src', 'bongos', 'routes', 'me.js');
+  assert.match(me, /lifecycle\.openTaskRecommendationsFor/);
+  assert.ok(!/require\([^)]*task-recommendations/.test(me), 'core does not import the module');
+});
+
+// ── it reaches someone, rather than merely being stored ─────────────────────
+
+const needs = require(path.join(ROOT, 'modules', 'builder-settings', 'builder-needs.js'));
+
+test('a waiting recommendation produces a need, so it is surfaced and not just stored', () => {
+  // C01's grader round established the rule for its sibling: storing is not
+  // reaching. It lands in the needs roster the hall card and the CLI nudge
+  // already render, rather than in a second notification system beside it.
+  const n = needs.taskRecommendationsNeed({ openTaskRecommendations: 2 });
+  assert.ok(n, 'a pending recommendation produces a need');
+  assert.match(n.message, /2 tasks/);
+  assert.ok(n.action && n.action.href, 'and it says where to go');
+});
+
+test('the need says plainly that nothing has been assigned', () => {
+  // Wording that pressured the reader would BE the penalty the decision forbids.
+  const n = needs.taskRecommendationsNeed({ openTaskRecommendations: 1 });
+  assert.match(n.message, /Nothing has been assigned/);
+  assert.match(n.message, /declining costs nothing/);
+  assert.match(n.what, /suggestion, not an assignment/);
+});
+
+test('no recommendations produces NO need, not a cheerful empty state', () => {
+  for (const ctx of [{ openTaskRecommendations: 0 }, {}, { openTaskRecommendations: undefined }]) {
+    assert.equal(needs.taskRecommendationsNeed(ctx), null);
+  }
+});
+
+test('the need is registered, so every renderer picks it up', () => {
+  const roster = needs.computeNeeds({ openTaskRecommendations: 1, ownKeySet: true, rank: 'metic' });
+  assert.ok(roster.items.some((i) => i.id === 'task_recommendations'), 'it is in the roster');
+});
+
+// ── bounds ──────────────────────────────────────────────────────────────────
+
+test('reads are bounded, so an unsettled pile degrades the page and not the server', () => {
+  assert.equal(recs.capRows(0), recs.MAX_ROWS);
+  assert.equal(recs.capRows(-1), recs.MAX_ROWS);
+  assert.equal(recs.capRows(recs.MAX_ROWS + 1), recs.MAX_ROWS);
+  assert.equal(recs.capRows(1.5), recs.MAX_ROWS);
+  assert.equal(recs.capRows(25), 25);
+});
+
+test('task_id and recommended_to are required and must be positive ids', () => {
+  assert.ok(reasons({ reason: 'x' }).includes('required'));
+  assert.ok(reasons({ ...good, task_id: 0 }).includes('bad_task_id'));
+  assert.ok(reasons({ ...good, task_id: 1.5 }).includes('bad_task_id'));
+  assert.ok(reasons({ ...good, recommended_to: -3 }).includes('bad_builder_id'));
+});