@bongos/core 1.18.3 → 1.18.18

package/tests/doctor_hooks.mjs

@@ -0,0 +1,141 @@
+// tests/doctor_hooks.mjs
+//
+// Unit tests for doctor's git-hooks verdict (task 1002524). The pure core
+// `classifyHooksState` decides whether an unset/dangling core.hooksPath is a
+// FAIL the builder must fix or an honest WARN about absent instance topology.
+//
+// The incident this locks down: on a portable-core checkout `.husky/` does not
+// exist (README "Secrets scanning" declares it instance topology), yet doctor
+// hard-failed with "set it to .husky" and then, once set, failed again with
+// "resolves to a non-existent path" — and repeated the SAME command. An
+// unbreakable red loop for anyone who followed the advice.
+//
+// The rule: never recommend a hooks dir that is not there, and never report a
+// missing ADR 0043 layer-1 gate as green. Absent .husky is a WARN that names
+// the enforcing layers; a hooksPath pointing at nothing is a real FAIL.
+//
+// Importing doctor.js must NOT run its checks (which shell out to git and hit
+// the network) — doctor.js guards its main IIFE behind `require.main === module`.
+// This test proves that holds.
+//
+// Run:  node tests/doctor_hooks.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const { classifyHooksState } = require('../scripts/gds/doctor.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try {
+    fn();
+    passed++;
+    console.log(`  ok  ${name}`);
+  } catch (err) {
+    failed++;
+    console.log(`  FAIL ${name}`);
+    console.log(`     ${err.message}`);
+  }
+}
+
+const ROOT = path.join(path.sep, 'repo');
+// exists() stub: give it the set of paths that are present. Built with
+// path.join so the separators match what the implementation produces on both
+// POSIX and Windows.
+const has = (...paths) => {
+  const set = new Set(paths);
+  return (p) => set.has(p);
+};
+const HUSKY = path.join(ROOT, '.husky');
+
+console.log('classifyHooksState');
+
+test('hooksPath set and the dir exists → ok', () => {
+  const r = classifyHooksState({ hooksPath: '.husky', worktreeRoot: ROOT, exists: has(HUSKY) });
+  assert.equal(r.status, 'ok');
+  assert.equal(r.resolved, HUSKY);
+});
+
+test('an absolute hooksPath that exists is honoured, not overridden', () => {
+  const r = classifyHooksState({
+    hooksPath: '/shared/hooks', worktreeRoot: ROOT, exists: has('/shared/hooks'),
+  });
+  assert.equal(r.status, 'ok');
+  assert.equal(r.resolved, '/shared/hooks');
+});
+
+// THE REGRESSION. Portable core: no .husky anywhere, hooksPath unset.
+test('unset hooksPath + no .husky → WARN, not fail (portable core)', () => {
+  const r = classifyHooksState({ hooksPath: '', worktreeRoot: ROOT, exists: has() });
+  assert.equal(r.status, 'warn', 'a core checkout must not be a hard fail');
+  assert.equal(r.code, 'no-hooks-dir');
+});
+
+test('the no-.husky warning never tells you to set hooksPath to .husky', () => {
+  const r = classifyHooksState({ hooksPath: '', worktreeRoot: ROOT, exists: has() });
+  assert.ok(
+    !/config\s+core\.hooksPath\s+\.husky/.test(r.message),
+    `must not recommend a dir that is not there — got: ${r.message}`
+  );
+});
+
+test('the no-.husky warning names the layers that DO enforce', () => {
+  const r = classifyHooksState({ hooksPath: '', worktreeRoot: ROOT, exists: has() });
+  assert.ok(/CI|audit/i.test(r.message), `must report honestly, got: ${r.message}`);
+});
+
+// Instance checkout: .husky is present but not switched on — a real, fixable gap.
+test('unset hooksPath + .husky present → fail (a real inactive gate)', () => {
+  const r = classifyHooksState({ hooksPath: '', worktreeRoot: ROOT, exists: has(HUSKY) });
+  assert.equal(r.status, 'fail');
+  assert.equal(r.code, 'inactive');
+});
+
+test('the inactive-gate fix points at the installer, which is itself guarded', () => {
+  const r = classifyHooksState({ hooksPath: '', worktreeRoot: ROOT, exists: has(HUSKY) });
+  assert.ok(/install-git-hooks/.test(r.message), `got: ${r.message}`);
+});
+
+// Dangling hooksPath — the second half of the old loop.
+test('hooksPath set but resolving nowhere → fail', () => {
+  const r = classifyHooksState({ hooksPath: '.husky', worktreeRoot: ROOT, exists: has() });
+  assert.equal(r.status, 'fail');
+  assert.equal(r.code, 'dangling');
+});
+
+test('a dangling hooksPath with no .husky advises UNSET, not the same failing command', () => {
+  const r = classifyHooksState({ hooksPath: '.husky', worktreeRoot: ROOT, exists: has() });
+  assert.ok(/--unset/.test(r.message), `must break the loop — got: ${r.message}`);
+  assert.ok(
+    !/config\s+core\.hooksPath\s+\.husky\s*$/.test(r.message.trim()),
+    'must not repeat the command that just failed'
+  );
+});
+
+test('a dangling hooksPath WITH .husky on disk advises the installer instead', () => {
+  // 'nope' resolves to ROOT/nope, which is absent — while .husky IS present.
+  const r = classifyHooksState({ hooksPath: 'nope', worktreeRoot: ROOT, exists: has(HUSKY) });
+  assert.equal(r.status, 'fail');
+  assert.equal(r.code, 'dangling');
+  assert.ok(/install-git-hooks/.test(r.message), `got: ${r.message}`);
+});
+
+test('every verdict carries a non-empty message', () => {
+  for (const c of [
+    { hooksPath: '', exists: has() },
+    { hooksPath: '', exists: has(HUSKY) },
+    { hooksPath: '.husky', exists: has() },
+    { hooksPath: '.husky', exists: has(HUSKY) },
+  ]) {
+    const r = classifyHooksState({ ...c, worktreeRoot: ROOT });
+    assert.ok(r.message && r.message.length > 0, `empty message for ${JSON.stringify(c)}`);
+    assert.ok(['ok', 'warn', 'fail'].includes(r.status), `bad status ${r.status}`);
+  }
+});
+
+console.log('');
+console.log(`${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/extract_json.mjs

@@ -0,0 +1,140 @@
+// tests/extract_json.mjs
+//
+// Unit test for grader-workers/extract-json.js (task 1001678) — the PURE, leaf
+// JSON extractor every grader worker delegates to when pulling a verdict object
+// out of raw LLM output. It is load-bearing for the quality gate: if extraction
+// returns null the worker reports parse_error and the panel retries, which is
+// the exact flake the balanced-brace scan was written to kill.
+//
+// Three strategies are tried in order (whole-string → ```json fence → balanced
+// brace scan), so the cases below are grouped by which one they exercise, plus
+// the two rules that decide between multiple candidates: objects only, and a
+// real SCORE key wins over an incidental prose object.
+//
+// Pure: no DB, no network, no filesystem, no live server.
+// Run: node tests/extract_json.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { extractJson, GRADE_SHAPE_KEYS } = require('../modules/grading/grader-workers/extract-json.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.message}`); }
+}
+
+test('non-string input is null, never a throw', () => {
+  // Workers hand this whatever the LLM layer produced — a timeout can make that
+  // undefined, so a non-string must degrade to null rather than crash the panel.
+  assert.equal(extractJson(42), null);
+  assert.equal(extractJson(null), null);
+  assert.equal(extractJson(undefined), null);
+  assert.equal(extractJson({ already: 'parsed' }), null);
+  assert.equal(extractJson(''), null);
+});
+
+test('strategy 1 — a clean JSON-only response parses whole', () => {
+  assert.deepEqual(extractJson('{"a":1}'), { a: 1 });
+  assert.deepEqual(extractJson('\n\n  {"a":1}  \n'), { a: 1 });
+  assert.deepEqual(extractJson('{"outer":{"inner":1}}'), { outer: { inner: 1 } });
+});
+
+test('only OBJECTS count — a valid array or scalar is not a verdict', () => {
+  // isObj rejects arrays/scalars, so valid-but-wrong-shaped JSON must not be
+  // mistaken for a grade. '[1,2,3]' contains no '{' at all, so every strategy
+  // misses and the result is null.
+  assert.equal(extractJson('[1,2,3]'), null);
+  assert.equal(extractJson('"hello"'), null);
+  // ...but an object later in the same string is still found.
+  assert.deepEqual(extractJson('[1,2] then {"a":1}'), { a: 1 });
+});
+
+test('strategy 2 — a fenced block wins over an earlier prose object', () => {
+  // The decoy matters: {"a":0} appears BEFORE the fence, so if the fenced branch
+  // were removed the brace scan would return the decoy instead. Without a decoy
+  // this case would pass either way and prove nothing about strategy 2.
+  assert.deepEqual(extractJson('Consider {"a":0} first.\n```json\n{"a":1}\n```'), { a: 1 });
+  assert.deepEqual(extractJson('Consider {"a":0} first.\n```\n{"a":1}\n```'), { a: 1 });
+});
+
+test('strategy 3 — prose around the object still extracts', () => {
+  assert.deepEqual(extractJson('Here is my grade:\n{"a":1}\nThanks!'), { a: 1 });
+  // The #465 flake: trailing prose carrying a stray unbalanced brace. The naive
+  // first-'{'-to-last-'}' slice this replaced would have swallowed the tail and
+  // returned a spurious parse_error.
+  assert.deepEqual(extractJson('{"a":1}\nNote: the } char is fine'), { a: 1 });
+});
+
+test('the brace scan is string- and escape-aware', () => {
+  // Both inputs are wrapped in prose ON PURPOSE. The bare object is valid JSON,
+  // so strategy 1 would return it whole and the scan under test would never run
+  // -- the assertion would then hold even with the scan's string handling gone.
+  // Prose forces strategy 3 to be the code path that produces the result.
+  //
+  // A '}' inside a string literal must not close the object early...
+  assert.deepEqual(
+    extractJson('Grade: {"note":"a } brace here","a":1} -- done'),
+    { note: 'a } brace here', a: 1 },
+  );
+  // ...and an escaped quote must not be read as the end of that string.
+  assert.deepEqual(
+    extractJson('Grade: {"note":"q \\" then } brace","a":1} -- done'),
+    { note: 'q " then } brace', a: 1 },
+  );
+});
+
+test('a "{" that only appears inside a string yields nothing', () => {
+  // Pins the real behaviour: no candidate, so null -- not a throw, not a partial
+  // parse. NB this does not prove the outer loop's string-skip is present: that
+  // skip avoids launching a doomed scan (a cost saving), and a scan launched
+  // from the mid-string brace finds no balanced object either. The observable
+  // result is null with or without it, so treat this as a null-safety pin.
+  assert.equal(extractJson('text "a { b" more'), null);
+});
+
+test('a real SCORE key beats an incidental prose object', () => {
+  // The tie-break that stops chatty output from winning: an earlier
+  // {"verdict":...} in prose must lose to the object carrying a grade key.
+  assert.deepEqual(
+    extractJson('I think {"verdict":"pass"} and the grade is {"functional_fidelity":9}'),
+    { functional_fidelity: 9 },
+  );
+  // Order-independent -- it prefers by shape, not by position.
+  assert.deepEqual(
+    extractJson('{"functional_fidelity":9} also {"verdict":"pass"}'),
+    { functional_fidelity: 9 },
+  );
+});
+
+test('with no grade-shaped candidate, the FIRST balanced object wins', () => {
+  assert.deepEqual(extractJson('{"a":1} and {"b":2}'), { a: 1 });
+});
+
+test('an invalid fence falls through to the brace scan', () => {
+  // Strategy 2 matches the fence but its body does not parse, so extraction
+  // must continue to strategy 3 rather than giving up at the fence.
+  assert.deepEqual(extractJson('```json\n{bad}\n```\n{"a":1}'), { a: 1 });
+});
+
+test('nothing parseable is null', () => {
+  assert.equal(extractJson('no json here at all'), null);
+  assert.equal(extractJson('{"a":'), null);
+});
+
+test('GRADE_SHAPE_KEYS is the exported score-key list', () => {
+  // Exported so workers and grader.js agree on what "grade-shaped" means; the
+  // preference test above depends on functional_fidelity being in this list.
+  assert.deepEqual(GRADE_SHAPE_KEYS, [
+    'functional_fidelity',
+    'code_quality',
+    'security_score',
+    'efficiency_score',
+  ]);
+});
+
+console.log(`\nextract-json (task 1001678) tests: ${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

package/tests/fitness.mjs

@@ -338,6 +338,68 @@ test('hall section registry check actually CATCHES a hardcoded <section class="s
   assert.deepEqual(otherSection, [], 'a non-widget <section> must not be flagged');
 });
 
+// --- hall Home zone budgets (task 2177) ---------------------------------------
+
+test('hall zone budgets: the live tree is within every declared budget', () => {
+  assert.deepEqual(fitness.checkHallZoneBudgets(), [], 'the live hall must be within budget');
+});
+
+test('hall zone budgets: ZONE_BUDGETS is parsed from builders.js, not copied here', () => {
+  const budgets = fitness.parseZoneBudgets("const ZONE_BUDGETS = { 'home-stats': 1, 'home-band': 2, 'home-main': 3 };");
+  assert.deepEqual(budgets, { 'home-stats': 1, 'home-band': 2, 'home-main': 3 });
+  // no literal → null, so the check can report "budgets are unenforced" rather
+  // than silently passing on a builders.js that no longer declares them.
+  assert.equal(fitness.parseZoneBudgets('const SOMETHING_ELSE = {};'), null);
+});
+
+test('hall zone budgets check actually CATCHES a breach (not a no-op)', () => {
+  const budgets = "const ZONE_BUDGETS = { 'home-stats': 1, 'home-main': 2 };";
+  // Stub fs: builders.js supplies the budgets, the widget files supply the counts.
+  const stub = (widgetFiles) => ({
+    readdirSync: () => Object.keys(widgetFiles),
+    readFileSync: (p) => (String(p).endsWith('builders.js')
+      ? budgets
+      : widgetFiles[Object.keys(widgetFiles).find((f) => String(p).endsWith(f))] ?? ''),
+  });
+
+  // within budget → clean
+  assert.deepEqual(
+    fitness.checkHallZoneBudgets(stub({
+      'a.js': "contributeHallWidget({ zone: 'home-main' })",
+      'b.js': "contributeHallWidget({ zone: 'home-main' })",
+    })),
+    [],
+    '2 home-main widgets against a budget of 2 must pass',
+  );
+
+  // one over → flagged, naming the zone, the count and the budget
+  const over = fitness.checkHallZoneBudgets(stub({
+    'a.js': "contributeHallWidget({ zone: 'home-main' })",
+    'b.js': "contributeHallWidget({ zone: 'home-main' })",
+    'c.js': "contributeHallWidget({ zone: 'home-main', summary: true })",
+  }));
+  assert.equal(over.length, 1, 'a 3rd home-main widget must be caught');
+  assert.match(over[0], /home-main.*3 registered.*budget is 2/s);
+
+  // a file that never calls contributeHallWidget is not counted (a `zone:` key
+  // in some unrelated object must not consume budget).
+  assert.deepEqual(
+    fitness.checkHallZoneBudgets(stub({
+      'a.js': "contributeHallWidget({ zone: 'home-main' })",
+      'unrelated.js': "const cfg = { zone: 'home-main' };",
+    })),
+    [],
+    'only real registrations count against the budget',
+  );
+
+  // builders.js without a parseable ZONE_BUDGETS → reported, never silently green
+  const unenforced = fitness.checkHallZoneBudgets({
+    readdirSync: () => [], readFileSync: () => 'const OTHER = 1;',
+  });
+  assert.equal(unenforced.length, 1);
+  assert.match(unenforced[0], /no longer declares a parseable ZONE_BUDGETS/);
+});
+
 // --- the demo proof module: BV1.R52 / task 1424 (ADR 0083) ----------------------
 // The net-new `modules/demo/` module is the live acceptance proof for the module
 // system. These tests lock in BOTH directions: the live demo module is clean, AND
@@ -433,3 +495,30 @@ test('write-route validation exemptions are the known dynamic-key prefs routes o
   const exempt = [...fitness.WRITE_VALIDATION_EXEMPT];
   assert.ok(exempt.length >= 1 && exempt.every((e) => e.startsWith('PATCH /me/')), 'exemptions are all /me/* prefs patches: ' + exempt.join(', '));
 });
+
+test('identity gate strips comments on CRLF checkouts too (task 1002428)', () => {
+  // Regression: stripCommentsForIdentity split on '\n', leaving a trailing '\r'
+  // on every line of a CRLF checkout. `.` does not match '\r', so the `.*$` in
+  // the line-comment pattern could never reach end-of-string and NO line comment
+  // was stripped — every rationale comment naming the old brand was scanned as
+  // if it were code. The gate's whole "comments never trip the scan" contract
+  // silently failed on Windows, and disagreed with Linux CI on the same tree.
+  // The pre-existing cases above are all LF-only, which is why this hid.
+  const { scanPromptIdentity } = fitness;
+  assert.equal(
+    scanPromptIdentity('x.js', '// see amazonprimea.com for context\r\nconst ok = 1;\r\n').length,
+    0,
+    'a CRLF full-line comment must be skipped'
+  );
+  assert.equal(
+    scanPromptIdentity('x.js', 'doThing(); // amazonprimea note\r\n').length,
+    0,
+    'a CRLF trailing comment must be skipped'
+  );
+  // ...and the strip must still not hide REAL code on CRLF (the gate keeps biting).
+  assert.equal(
+    scanPromptIdentity('x.js', 'const u = "https://amazonprimea.com/x";\r\n').length,
+    1,
+    'a CRLF code literal must still be caught'
+  );
+});

package/tests/gen_freshness.mjs

@@ -0,0 +1,96 @@
+// tests/gen_freshness.mjs — the doc generators' freshness comparison (task 1002445).
+//
+// Regression guard for a bug that made a HARD CI gate permanently red on Windows:
+// the generators render blocks with join('\n') (LF) but read the working copy with
+// readFileSync, which on a core.autocrlf=true checkout returns CRLF. The old
+// byte-wise `next !== cur` therefore reported STALE forever, and regenerating never
+// cleared it. A gate that cannot pass trains builders to ignore it AND hides real
+// drift behind the permanent failure.
+//
+// Two things must hold, and the second is what stops an over-broad "fix":
+//   1. line endings alone must NOT read as drift,
+//   2. a genuine content change must STILL read as drift.
+//
+// Pure file-read + require (no DB/network) — runs in the DB-free unit gate.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { sameContent, normalizeEol } = require(path.join(ROOT, 'scripts', 'gds', 'gen-freshness.js'));
+
+const LF = '# Title\n\n- one\n- two\n';
+const CRLF = '# Title\r\n\r\n- one\r\n- two\r\n';
+
+test('a CRLF working copy is not drift against an LF-rendered block', () => {
+  assert.equal(sameContent(CRLF, LF), true, 'this is the bug: LF vs CRLF must not read as STALE');
+  assert.equal(sameContent(LF, CRLF), true, 'and it is symmetric');
+  assert.equal(sameContent(CRLF, CRLF), true);
+  assert.equal(sameContent(LF, LF), true);
+});
+
+test('mixed line endings (an LF block spliced into a CRLF doc) are not drift', () => {
+  // Exactly what injectBlock/injectSection/injectSnippet produce on Windows.
+  const mixed = '# Title\r\n\r\n- one\n- two\r\n';
+  assert.equal(sameContent(mixed, LF), true);
+  assert.equal(sameContent(mixed, CRLF), true);
+});
+
+test('a REAL content change is still drift (the fix does not blind the gate)', () => {
+  assert.equal(sameContent(LF, '# Title\n\n- one\n- three\n'), false, 'changed list item');
+  assert.equal(sameContent(CRLF, '# Title\r\n\r\n- one\r\n- two\r\n- three\r\n'), false, 'added line');
+  assert.equal(sameContent(LF, ''), false, 'emptied file');
+  assert.equal(sameContent(LF, '# Title\n\n- one\n- two'), false, 'dropped trailing newline');
+  assert.equal(sameContent(LF, '# Title\n\n- one\n\n- two\n'), false, 'added blank line');
+});
+
+test('whitespace that is not a line ending is still content', () => {
+  assert.equal(sameContent('a\tb', 'a b'), false, 'tab vs space is a real difference');
+  assert.equal(sameContent('a \n', 'a\n'), false, 'trailing space is a real difference');
+  assert.equal(sameContent('\r', '\n'), false, 'a lone CR is not normalized — no generator emits it');
+});
+
+test('a missing file (null/undefined) reads as drift against real content', () => {
+  assert.equal(sameContent(null, LF), false, 'absent → must regenerate');
+  assert.equal(sameContent(undefined, LF), false);
+  assert.equal(normalizeEol(null), '', 'null normalizes to empty, not the string "null"');
+  assert.equal(normalizeEol(undefined), '');
+});
+
+// The guard that keeps the fix from rotting: every generator behind the
+// `generated artifacts fresh` gate must route its freshness comparison through
+// sameContent(). A reintroduced `cur !== next` on file bytes is the original bug.
+const GENERATORS = ['gen-repo-map.js', 'gen-session-index.js', 'gen-file-map.js', 'gen-api-docs.js'];
+
+test('every gated generator compares freshness through sameContent()', () => {
+  for (const g of GENERATORS) {
+    const src = fs.readFileSync(path.join(ROOT, 'scripts', 'gds', g), 'utf8');
+    assert.match(src, /require\('\.\/gen-freshness'\)/, `${g} must import the shared comparison`);
+    assert.match(src, /sameContent\(/, `${g} must use sameContent() for freshness`);
+  }
+});
+
+test('no gated generator byte-compares a file read against rendered content', () => {
+  // Catches the exact shape of the original bug: `cur !== next` / `next !== cur`
+  // (and the idx*/map* variants) directly on strings read from disk.
+  const BYTEWISE = /\b(cur|next|idxCur|idxNext|mapCur|mapNext)\s*!==\s*(cur|next|idxCur|idxNext|mapCur|mapNext)\b/;
+  for (const g of GENERATORS) {
+    const src = fs.readFileSync(path.join(ROOT, 'scripts', 'gds', g), 'utf8');
+    const offenders = src.split('\n')
+      .map((line, i) => ({ line: line.trim(), n: i + 1 }))
+      .filter(({ line }) => BYTEWISE.test(line));
+    assert.deepEqual(offenders, [], `${g} byte-compares generated content — use sameContent()`);
+  }
+});
+
+test('the byte-compare guard actually CATCHES the original bug shape', () => {
+  const BYTEWISE = /\b(cur|next|idxCur|idxNext|mapCur|mapNext)\s*!==\s*(cur|next|idxCur|idxNext|mapCur|mapNext)\b/;
+  assert.equal(BYTEWISE.test('if (next !== cur) writes.push({});'), true, 'the gen-file-map shape');
+  assert.equal(BYTEWISE.test('if (idxCur !== idxNext) writes.push({});'), true, 'the gen-session-index shape');
+  assert.equal(BYTEWISE.test('if (mapCur !== mapNext) writes.push({});'), true, 'the gen-repo-map shape');
+  assert.equal(BYTEWISE.test('if (!sameContent(next, cur)) writes.push({});'), false, 'the fixed shape passes');
+});