@bongos/core 1.19.359 → 1.19.361

package/tests/closeness.mjs

@@ -0,0 +1,324 @@
+// tests/closeness.mjs — closeness is a weighted blend that can explain itself
+// (task 1003174 / C04, goal 1000075; criterion collab-closeness-consented,
+// ADR 0187 §2).
+//
+// The criterion names three testable things, and the owner attached two of them
+// as conditions of taking the blend at all rather than as follow-ups:
+//   1. the weights are inspectable DATA;
+//   2. the surface can state the contributing signals for a given pair;
+//   3. a hidden builder appears in no graph.
+//
+// The scorer is pure, so 1 and 2 are driven with real inputs rather than asserted
+// over source. 3 is a consent property of the read, and is driven through the
+// real applyConsent gate with stub readers — including the failure modes, which
+// are the ones that actually matter.
+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 closeness = require(path.join(ROOT, 'modules', 'lifecycle', 'closeness.js'));
+const WEIGHTS = require(path.join(ROOT, 'modules', 'lifecycle', 'closeness-weights.json'));
+const read = (...p) => fs.readFileSync(path.join(ROOT, ...p), 'utf8');
+
+const SRC = read('modules', 'lifecycle', 'closeness.js');
+const ROUTES = read('modules', 'lifecycle', 'routes', 'closeness.js');
+
+// ── 1. THE WEIGHTS ARE DATA ─────────────────────────────────────────────────
+
+test('THE CONDITION: the weights live in a data file, not in the scorer', () => {
+  // "The weights are DATA, not constants buried in a function, so they can be
+  // reviewed and changed without a code archaeology dig." A numeric weight
+  // literal in the scorer would be exactly the dig.
+  const code = SRC.replace(/^\s*\/\/.*$/gm, '');
+  assert.match(code, /require\('\.\/closeness-weights\.json'\)/);
+  for (const s of WEIGHTS.signals) {
+    assert.ok(!new RegExp(`['"\`]${s.key}['"\`]\\s*:\\s*0?\\.\\d`).test(code),
+      `${s.key}'s weight must not be written into the scorer`);
+  }
+});
+
+test('every signal declares the four things a reviewer needs', () => {
+  // A weight with no label, no description and no saturation is not reviewable —
+  // it is a magic number that happens to live in a .json file.
+  for (const s of WEIGHTS.signals) {
+    assert.ok(s.key && s.label && s.description, `${s.key} is described in words`);
+    assert.equal(typeof s.weight, 'number', `${s.key} has a numeric weight`);
+    assert.ok(s.saturation > 0, `${s.key} declares what "full" means`);
+    assert.equal(typeof s.available, 'boolean', `${s.key} declares whether it can be measured`);
+  }
+});
+
+test('the declared weights sum to 1 across ALL signals', () => {
+  const total = WEIGHTS.signals.reduce((n, s) => n + s.weight, 0);
+  assert.ok(Math.abs(total - 1) < 1e-9, `weights sum to ${total}, not 1`);
+});
+
+test('the route serves the model VERBATIM rather than restating it', () => {
+  // An audit surface that paraphrases the model can drift from it, which makes
+  // it worse than nothing.
+  assert.match(ROUTES, /weights: closeness\.weightsModel\(\)/);
+});
+
+// ── 2. THE SCORE CAN EXPLAIN ITSELF ─────────────────────────────────────────
+
+test('THE CONDITION: every score carries a per-signal breakdown', () => {
+  // "Why am I close to them MUST be answerable on any surface that shows
+  // closeness." The breakdown is that answer, and it must account for the whole
+  // number: the contributions sum to the score.
+  const s = closeness.scoreCloseness({ co_claim: 2, co_build_session: 1, shipped_together_goal: 3 });
+  assert.ok(s.score > 0);
+  assert.equal(s.breakdown.length, closeness.availableSignals().length);
+  const summed = s.breakdown.reduce((n, r) => n + r.contribution, 0);
+  assert.ok(Math.abs(summed - s.score) < 1e-3, `breakdown sums to ${summed}, score is ${s.score}`);
+});
+
+test('a breakdown row shows the arithmetic, not just a verdict', () => {
+  const s = closeness.scoreCloseness({ co_claim: 2 });
+  const row = s.breakdown.find((r) => r.key === 'co_claim');
+  assert.equal(row.count, 2, 'the raw count');
+  assert.ok(row.saturation > 0, 'what it was measured against');
+  assert.ok(row.effective_weight > 0, 'the weight actually applied');
+  assert.ok(row.contribution > 0, 'and what it added');
+  assert.ok(row.description.length > 20, 'in words, too');
+});
+
+test('the explanation travels WITH the score, not behind a second call', () => {
+  // A separate endpoint is how a number ends up on a page with nothing to point
+  // at, because a caller may simply not make the second call.
+  assert.match(SRC, /why: \{ breakdown: scored\.breakdown, excluded: scored\.excluded, in_words: explainInWords\(scored\) \}/);
+  assert.ok(!/\/closeness\/[^\s'"]*why/.test(ROUTES), 'there is no separate why endpoint');
+});
+
+test('a signal saturates — no single runaway count can dominate', () => {
+  const sat = WEIGHTS.signals.find((s) => s.key === 'co_claim').saturation;
+  const atFull = closeness.scoreCloseness({ co_claim: sat });
+  const wayOver = closeness.scoreCloseness({ co_claim: sat * 100 });
+  assert.equal(atFull.score, wayOver.score, 'past saturation the signal stops growing');
+  assert.equal(wayOver.breakdown.find((r) => r.key === 'co_claim').value, 1);
+});
+
+test('no measurable history scores zero and SAYS so', () => {
+  const s = closeness.scoreCloseness({});
+  assert.equal(s.score, 0);
+  assert.match(closeness.explainInWords(s), /Nothing measurable has happened/);
+});
+
+test('the words name the strongest signal first', () => {
+  const s = closeness.scoreCloseness({ co_claim: 1, shipped_together_goal: 3 });
+  const words = closeness.explainInWords(s);
+  const strongest = s.breakdown.slice().sort((a, b) => b.contribution - a.contribution)[0];
+  assert.ok(words.toLowerCase().indexOf(strongest.label.toLowerCase()) >= 0);
+  assert.match(words, /^Mostly /);
+});
+
+// ── AN UNAVAILABLE SIGNAL IS NOT A ZERO ─────────────────────────────────────
+
+test('THE HONESTY RULE: an unmeasurable signal is excluded, not scored as zero', () => {
+  // comms_mention cannot be measured until C06 mirrors chat in. Scoring it zero
+  // would depress every pair identically AND make the explanation say "you never
+  // talk" — which is not what is true. What is true is that nothing can see it.
+  const unavailable = closeness.unavailableSignals();
+  assert.ok(unavailable.length > 0, 'this test is about a real case, not a hypothetical');
+  const s = closeness.scoreCloseness({ co_claim: 99, co_build_session: 99, shipped_together_goal: 99 });
+  assert.ok(Math.abs(s.score - 1) < 1e-9,
+    `every AVAILABLE signal at full must reach 1.0, got ${s.score} — an excluded signal is holding weight`);
+});
+
+test('the excluded signals are NAMED, with the reason, in every payload', () => {
+  const s = closeness.scoreCloseness({ co_claim: 1 });
+  assert.ok(s.excluded.length > 0);
+  for (const e of s.excluded) {
+    assert.equal(e.reason, 'not_measurable_yet');
+    assert.match(e.explanation, /NOT counted as zero/);
+    assert.ok(e.declared_weight > 0, 'and what it would have been worth');
+  }
+  assert.match(closeness.explainInWords(s), /Not counted:/);
+});
+
+test('the unavailable signal points at the task that unblocks it', () => {
+  const comms = WEIGHTS.signals.find((s) => s.key === 'comms_mention');
+  assert.equal(comms.available, false);
+  assert.match(comms.blocked_by, /1003176/);
+});
+
+test('effective weights always sum to 1 over the available subset', () => {
+  const s = closeness.scoreCloseness({});
+  const summed = s.breakdown.reduce((n, r) => n + r.effective_weight, 0);
+  assert.ok(Math.abs(summed - 1) < 1e-3, `effective weights sum to ${summed}`);
+});
+
+// ── 3. CONSENT: a hidden builder appears in NO graph ────────────────────────
+
+const entries = () => [
+  { builder_id: '10', score: 0.9 },
+  { builder_id: '20', score: 0.5 },
+  { builder_id: '30', score: 0.1 },
+];
+
+test('THE CONSENT RULE: a hidden builder is removed from the graph', () => {
+  return closeness.applyConsent(entries(), async () => new Set(['20']))
+    .then((out) => assert.deepEqual(out.map((e) => e.builder_id), ['10', '30']));
+});
+
+test('FAIL CLOSED: a consent read that THROWS empties the graph', async () => {
+  // An unreadable consent state is not permission. This is the direction that
+  // matters: the opposite default would serve a hidden builder on any hiccup.
+  const out = await closeness.applyConsent(entries(), async () => { throw new Error('hub down'); });
+  assert.deepEqual(out, []);
+});
+
+test('FAIL CLOSED: a consent read returning null empties the graph too', async () => {
+  // null is not "nobody is hidden".
+  const out = await closeness.applyConsent(entries(), async () => null);
+  assert.deepEqual(out, []);
+});
+
+test('no consent reader at all leaves the graph intact — that is not a hole', async () => {
+  // Where the hub module is off there is no hub-level hide flag to honour,
+  // because nobody on that instance has been offered the switch. Suppressing
+  // everyone would not be consent, it would be an outage.
+  const out = await closeness.applyConsent(entries(), null);
+  assert.equal(out.length, 3);
+});
+
+test('consent is ONE gate the reads pass through, not a filter at each call site', () => {
+  // C05 (task 1003175) is "consent is the read path, not a filter bolted on
+  // after" — it needs a single structural place, and this is it.
+  assert.equal((SRC.match(/await applyConsent\(/g) || []).length, 1,
+    'exactly one call site applies consent');
+  assert.match(SRC, /entries = await applyConsent\(entries, hiddenIdsFor\);/);
+});
+
+test('a suppressed builder\'s identity is never even read', () => {
+  // hydrate() runs AFTER applyConsent, so a hidden builder\'s name and avatar are
+  // not fetched at all — not fetched and then dropped.
+  const fn = SRC.slice(SRC.indexOf('async function closenessFor'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.ok(body.indexOf('applyConsent') < body.indexOf('return hydrate'),
+    'consent is applied before hydration');
+});
+
+test('the pair read cannot be used to detect that someone hid themselves', () => {
+  // "No measurable closeness" and "consent says no" MUST be indistinguishable —
+  // a caller able to tell them apart has found the hide flag through a side door.
+  const fn = SRC.slice(SRC.indexOf('async function closenessBetween'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  // Scope to the MISS BRANCH — everything after the hit returns. The signature
+  // above it legitimately names hiddenIdsFor, and asserting over the whole
+  // function flagged the parameter as if it were a leak.
+  const miss = body.slice(body.indexOf('if (found) return found;')).replace(/^\s*\/\/.*$/gm, '');
+  assert.ok(!/hidden|consent/i.test(miss), 'the miss branch does not name consent');
+  // ONE answer, and it is the same one a pair with no shared history gets.
+  assert.equal((miss.match(/return\s+null;/g) || []).length, 1);
+});
+
+test('the hub consent read distinguishes HIDDEN from never-federated', () => {
+  // getPublicProfileExtras returns null for a hidden account AND for an absent
+  // one. For a rollup those are the same; for a consent gate they are opposites,
+  // and conflating them would empty the graph on a fresh instance and call it
+  // consent. hiddenGithubIds asks the one question it needs.
+  const pi = read('modules', 'platform-identity', 'platform-identity.js');
+  const fn = pi.slice(pi.indexOf('async function hiddenGithubIds'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.match(body, /hide_stats = true/);
+  assert.ok(!/profile_state/.test(body), 'an unfederated builder has not opted out of anything');
+});
+
+// ── the graph is own-scoped ─────────────────────────────────────────────────
+
+test("you read your OWN graph, never someone else's", () => {
+  // Another builder's graph exposes who THEY are close to — a fact about third
+  // parties they did not consent to share.
+  assert.match(ROUTES, /closeness\.closenessFor\(req\.builder\.id/);
+  assert.ok(!/closenessFor\(\s*(req\.params|otherId)/.test(ROUTES));
+});
+
+test('the pair read is always relative to the CALLER', () => {
+  assert.match(ROUTES, /closenessBetween\(req\.builder\.id, otherId/);
+});
+
+test('a builder is never close to themselves', () => {
+  return closeness.closenessBetween(5, 5, {}).then((r) => assert.equal(r, null));
+});
+
+// ── bounds + registration ───────────────────────────────────────────────────
+
+test('reads are bounded', () => {
+  assert.equal(closeness.capRows(0), closeness.MAX_ROWS);
+  assert.equal(closeness.capRows(closeness.MAX_ROWS + 1), closeness.MAX_ROWS);
+  assert.equal(closeness.capRows(10), 10);
+});
+
+test('signals are counted over a trailing window, not all of history', () => {
+  // A collaboration from two years ago is history, not closeness.
+  assert.ok(closeness.WINDOW_DAYS > 0);
+  for (const q of ['coClaimCounts', 'coSessionCounts', 'shippedTogetherCounts']) {
+    const fn = SRC.slice(SRC.indexOf(`async function ${q}`));
+    assert.match(fn.slice(0, 1400), /now\(\) - \(\$2 \|\| ' days'\)::interval/, `${q} is windowed`);
+  }
+});
+
+test('the route is registered in the module manifest', () => {
+  const manifest = JSON.parse(read('modules', 'lifecycle', 'module.json'));
+  assert.ok(manifest.contributes.routes.includes('closeness'));
+});
+
+test('lifecycle reads the hide flag through the PORT, never the hub table', () => {
+  // ADR 0083: a module must not read another module's table.
+  assert.match(ROUTES, /resolveOptional\('platform-identity\.hub'\)/);
+  for (const src of [SRC, ROUTES]) {
+    assert.ok(!/platform_identity_accounts/.test(src), 'no cross-module table read');
+  }
+});
+
+// ── the pair read costs a pair (grader round 2, task 1003174) ───────────────
+
+test('THE PAIR READ IS NARROWED AT THE DATABASE, not filtered in memory', () => {
+  // Round 1 called the graph read and then find()-ed the one row it wanted —
+  // three self-joins and a hydrate over up to a hundred builders to answer a
+  // question about one, on a likely per-profile-view route. Both the quality and
+  // the efficiency worker flagged it independently.
+  const fn = SRC.slice(SRC.indexOf('async function closenessBetween'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.match(body, /closenessFor\(builderId, \{ limit: 1, hiddenIdsFor, otherId \}/,
+    'the pair id is pushed into the read, not applied after it');
+});
+
+test('and there is still exactly ONE definition of each signal', () => {
+  // The fix could have been a second set of pair-shaped queries. Two hand-written
+  // definitions of "what a co-claim is" drift, and the one that drifts is the one
+  // nobody reads — so otherId is a PARAMETER on the same query instead.
+  for (const q of ['coClaimCounts', 'coSessionCounts', 'shippedTogetherCounts']) {
+    assert.equal((SRC.match(new RegExp(`async function ${q}\\b`, 'g')) || []).length, 1,
+      `${q} is defined once`);
+    const fn = SRC.slice(SRC.indexOf(`async function ${q}`));
+    assert.match(fn.slice(0, 1500), /\$3::bigint IS NULL OR/,
+      `${q} narrows by parameter, and null means the whole graph`);
+  }
+});
+
+test('the index gap the grader raised is ANSWERED, not left open', () => {
+  // Round 2 could not confirm within budget whether the join columns were
+  // indexed. Checked: tasks.goal_id had NO index, and claims.builder_id /
+  // tasks.shipped_by were indexed only PARTIALLY, by predicates closeness does
+  // not satisfy (open claims / needs_rebase).
+  //
+  // The fix is NOT in this diff, and deliberately so: it was written here first
+  // as a lifecycle_ migration and the fitness check red-carded it, correctly —
+  // a module migration may only touch its own namespaced tables (ADR 0083 §5)
+  // and these are core tables. That makes it a core_ migration, which needs a
+  // reserved number and human eyes. Filed as task 1003268 with the SQL.
+  //
+  // This test pins the REFERENCE so the finding cannot be quietly dropped: if
+  // someone lands the indexes and deletes the note, they should delete this too.
+  assert.match(SRC, /task 1003268/,
+    'the closeness source cites the follow-up that carries the indexes');
+  const files = fs.readdirSync(path.join(ROOT, 'modules', 'lifecycle', 'migrations'));
+  assert.ok(!files.some((f) => /closeness/i.test(f)),
+    'and no module migration tries to index a core table again');
+});

package/tests/doc_comment_coverage.mjs

@@ -0,0 +1,87 @@
+// tests/doc_comment_coverage.mjs — the ADR 0095 doc-comment nudge detects real
+// gaps, stays advisory, and survives CRLF (task 1001654).
+//
+// Three things are pinned here, each a way this check could quietly become useless:
+//   1. It must stay ADVISORY. The ADR says a doc-comment gate must not block a ship
+//      without owner sign-off, because a blocking gate buys filler prose. A future
+//      edit that flips hardFail should fail this test and force that decision.
+//   2. It must be CRLF-safe. The sibling scanner docs-entropy.js finds ZERO
+//      markdown headings on a Windows checkout because its regex breaks on a
+//      trailing \r; this check reads source files the same way and must not
+//      repeat it.
+//   3. An empty enumeration is a scan defect, not a clean pass (the task 1002526
+//      lesson: a lint that scans nothing reports success forever).
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { checkDocCommentCoverage, scanHeaders, leadingComment, wordCount, MIN_WORDS } =
+  require(path.join(ROOT, 'scripts', 'gds', 'doc-comment-coverage.js'));
+
+const FILES = {
+  'src/no-header.js': "const x = require('y');\nmodule.exports = x;\n",
+  'src/code-first.js': 'const a = 1;\n// a comment AFTER code is not a header\n',
+  'src/thin.js': '// config.js — config.\nconst a = 1;\n',
+  'src/good.js': '// src/good.js — does the thing.\n//\n// WHY. It exists because the other thing could not do it safely.\nconst a = 1;\n',
+  'src/prologue.js': "#!/usr/bin/env node\n'use strict';\n// src/prologue.js — a real header stating what this does and why it exists.\nconst a = 1;\n",
+  'src/block.js': '/*\n * src/block.js — a block-comment header that explains what this file does\n * and the reason it exists at all.\n */\nconst a = 1;\n',
+};
+const read = (rel) => FILES[rel];
+
+test('a file with no leading comment is reported missing', () => {
+  const { missing } = scanHeaders(Object.keys(FILES), read);
+  assert.ok(missing.includes('src/no-header.js'));
+});
+
+test('a comment that follows code is NOT a header', () => {
+  // Otherwise any stray inline note anywhere in the file would count as coverage.
+  assert.equal(leadingComment(FILES['src/code-first.js']), '');
+  const { missing } = scanHeaders(Object.keys(FILES), read);
+  assert.ok(missing.includes('src/code-first.js'));
+});
+
+test('a header that only restates the filename is flagged thin, not missing', () => {
+  const { thin, missing } = scanHeaders(Object.keys(FILES), read);
+  assert.ok(!missing.includes('src/thin.js'));
+  assert.ok(thin.some((t) => t.file === 'src/thin.js' && t.words < MIN_WORDS));
+});
+
+test('a shebang + use-strict prologue may precede the header', () => {
+  const { missing, thin } = scanHeaders(['src/prologue.js'], read);
+  assert.deepEqual(missing, [], 'a CLI opening with #! still has a header');
+  assert.deepEqual(thin, []);
+});
+
+test('block-comment headers count too', () => {
+  const { missing, thin } = scanHeaders(['src/block.js'], read);
+  assert.deepEqual(missing, []);
+  assert.deepEqual(thin, []);
+});
+
+test('CRLF files are parsed identically to LF — the docs-entropy trap', () => {
+  // docs-entropy.js finds zero headings on a CRLF checkout because `.` does not
+  // match \r and `$` (no /m) only matches end-of-input. Reading source the same
+  // naive way would make this check report full coverage on Windows regardless of
+  // the truth, so LF and CRLF must agree exactly.
+  const lf = '// src/x.js — states what this file does and the reason it exists.\nconst a = 1;\n';
+  const crlf = lf.replace(/\n/g, '\r\n');
+  assert.equal(wordCount(leadingComment(crlf)), wordCount(leadingComment(lf)));
+  assert.ok(wordCount(leadingComment(crlf)) >= MIN_WORDS, 'a real CRLF header must not read as thin');
+});
+
+test('the check is ADVISORY — it never fails the build (ADR 0095)', () => {
+  const r = checkDocCommentCoverage();
+  assert.equal(r.hardFail, false, 'promoting this to blocking needs owner sign-off + its own ADR');
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.violations, [], 'findings surface as warnings, never violations');
+});
+
+test('the live repo scan actually reads files (never a silent empty scan)', () => {
+  const r = checkDocCommentCoverage();
+  const scanned = Number(/^(\d+)\/(\d+)/.exec(r.note)?.[2] ?? 0);
+  assert.ok(scanned > 100, `expected hundreds of scanned files, got ${scanned} — an empty scan proves nothing`);
+});