@bongos/core 1.19.360 → 1.19.362

package/src/module-api.js

@@ -1150,8 +1150,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.358 with no explicit bump. run 32877754251. (task 1002620)
 //   1.19.360 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.359 with no explicit bump. run 32881040669. (task 1002620)
+//   1.19.361 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.360 with no explicit bump. run 32883230235. (task 1002620)
+//   1.19.362 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.361 with no explicit bump. run 32886106098. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.360'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.362'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

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`);
+});

package/tests/hall_page_gate_map.mjs

@@ -68,10 +68,11 @@ const ORACLE = {
   '/builders/scouting': 'requireProjectCuratePage',
 
   // Metic+ since R16 (goal 1000069): the Government page is three rooms —
-  // Constitution · Board Room · Ranks & Permissions — and only the third is the
-  // archon admin surface, whose DATA routes all still gate on government.manage
-  // individually. The shell follows the widest legitimate audience; the board
-  // reads carry the vote atom, the manage tab seals itself for non-archons.
+  // Permissions · Board Room · Constitution (reordered, task 1003269) — and only
+  // the Permissions room is the archon admin surface, whose DATA routes all still
+  // gate on government.manage individually. The shell follows the widest
+  // legitimate audience; the board reads carry the vote atom, and the manage
+  // tab seals itself for non-archons.
   '/builders/government': 'requireGovernmentPage',
 
   // Deliberately UNGATED — the landing card, the rank ladder, the reward