@bongos/core 1.21.180 → 1.21.181

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/bongos/package-core.js",
-  "core_version": "1.21.180",
-  "core_contract": "1.21.180",
-  "source_commit": "36dc85d6b63259779e000aebdf3dc1e0138792b0",
+  "core_version": "1.21.181",
+  "core_contract": "1.21.181",
+  "source_commit": "677ee2b818cf829dddd5434301b158be3408fbd5",
   "source_ref": "HEAD",
-  "built_at": "2026-10-26T00:58:50.603Z",
+  "built_at": "2026-10-26T01:16:25.738Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 616,
     "agent_docs_stubbed": 29,
-    "functional_verbatim": 3538,
+    "functional_verbatim": 3539,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 4184,
-  "tree_sha256": "fbe7e2684882ff2e854978d9a494f9058adeb5f62571e3e020009f9074f48249",
+  "file_count": 4185,
+  "tree_sha256": "e69b48d53a056c99114f3c5904e69828363e91f5f0df70b7b599e61e8e299d1d",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2937,7 +2937,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "82235d195b8ec1dae8f427ce3b500af7abcb84d3c265702ef66589f86abccc64"
+      "sha256": "4835f21d9d6cf7eaa82821e1bb5eb4c79493267300ef852ad1ca1c05b4a41e65"
     },
     {
       "path": "docs/modules-contract.md",
@@ -10827,12 +10827,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "ee9b6a44618660fc762c163d437234d8113af7f3d58e135a833ba5b1bc24fc2b"
+      "sha256": "4d3ecd3d1a0b7e6602da53e83e88c204ab82a45ca83ae3d24979746970f15ac9"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "d1b93e086b2f09ccba18efa17327c3ca20cec70c4b1e6f305ded43643fce1f26"
+      "sha256": "2a01fd05d918fc38ad18d1cc6305681129b6115a4eab33f7d1fa4d34b8da2e44"
     },
     {
       "path": "public-docs/index.html",
@@ -10852,7 +10852,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "6863c7358f68a6456d7be9d06d184442c3f3af03e8a27dab308913962649b751"
+      "sha256": "2a6e6fa89b09fd51aa8fae09c92eec30b6d0823dcdf3eaeda63826e7269a46ea"
     },
     {
       "path": "scripts/bongos/CLAUDE.md",
@@ -12052,7 +12052,7 @@
     {
       "path": "scripts/bongos/repo-metrics.js",
       "mode": "0000644",
-      "sha256": "c1ee7d69e2ef949ecec2ff7f602c9876a835fb9853585e21aea4c2d215c9aa1f"
+      "sha256": "15dee800bf6fc5aca8a9d332854825b1d0081f2269ccdf69c2b5d3e1010009cb"
     },
     {
       "path": "scripts/bongos/retired-core-skills.json",
@@ -14677,7 +14677,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "391a575b2a36039085561dfa8e1b76080d46a678f59dcde76ebb6e1c6a829945"
+      "sha256": "c48862d3a5d62afff6c50b8de356b68ec2ef4f22ced0c0caa36a99d5f135747a"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -19604,6 +19604,11 @@
       "mode": "0000644",
       "sha256": "5c964c162b87f2e73f6dc3343b1c4be886b7d3e0d29c01d51280dc790fc218e7"
     },
+    {
+      "path": "tests/repo_metrics_dead_exports.mjs",
+      "mode": "0000644",
+      "sha256": "f98a3d9635557d050f428c5ad3258ff1ef7652bf0f4fba87830cc09481b76e9b"
+    },
     {
       "path": "tests/reward_gate.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -3197,5 +3197,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.21.178 with no explicit bump. run 40250732318. (task 1002620)
   1.21.180 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.21.179 with no explicit bump. run 40251859318. (task 1002620)
+  1.21.181 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.180 with no explicit bump. run 40253320267. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.180",
+  "version": "1.21.181",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.21.180",
+      "version": "1.21.181",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.180",
+  "version": "1.21.181",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -10356,5 +10356,11 @@
       "id": "1004875",
       "text": "The unused-code check now covers modules/, the largest part of the codebase, and fails the build when someone adds a dead file or an unused export there. Five dead exports were removed along the way."
     }
+  ],
+  "1.21.181": [
+    {
+      "id": "1004892",
+      "text": "The repo health dashboard's dead-code number now counts the same way the CI check does, so it no longer jumps by about 1,800 false alarms from modules/."
+    }
   ]
 }

package/scripts/bongos/repo-metrics.js

@@ -37,6 +37,7 @@ const { execSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
 const { hasFlag } = require('./cli-lib');
+const { countKnipFindings } = require('./fitness-ratchets');
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 const TOP_N_LARGEST = 15;
@@ -151,36 +152,44 @@ function scanDeadCode() {
     return { dead_exports: null, dead_files: null, knip_status: 'unparseable' };
   }
 
-  // knip v6 JSON shape: { issues: [{ file, files (bool: whole file unused),
-  // exports:[...], types:[...], ... }] }. A top-level `files` array exists in
-  // some reporter modes; handle both. dead_exports sums unused exports+types
-  // across issues; dead_files counts issues whose whole file is unused.
-  let deadFiles = null;
+  const scored = scoreKnipReport(report);
+  if (!scored) return { dead_exports: null, dead_files: null, knip_status: 'unexpected_shape' };
+  return { ...scored, knip_status: 'ok' };
+}
+
+// knip JSON -> { dead_exports, dead_files }, or null on a shape we cannot read.
+//
+// dead_exports goes through the CI ratchet's own scorer, countKnipFindings, fed only
+// the exports/types findings (task 1004892). Counting knip's raw list instead put
+// ~1,800 exports under modules/ on the dashboard that ARE used: knip does not credit
+// a CommonJS namespace use (`lib.x`), and modules/ is written that way. The scorer's
+// name filter drops those, so this number and the ratchet's agree. `opts` passes
+// through to the scorer (a test injects `wordIndex`).
+//
+// COST: the scorer builds its word index once per call (codeWordIndex walks the
+// repo's .js/.mjs/.cjs/.html/.sh text) — measured ~2.3 s on this repo, beside a knip
+// run that already takes far longer. It is deliberately NOT fed from
+// gatherFileSizes()'s reads: that list is git-tracked .js/.mjs only, while the
+// ratchet's index also reads .cjs/.html/.sh and skips docs/ — a different file set
+// gives a different count, and matching CI's number is the whole point.
+function scoreKnipReport(report, opts = {}) {
+  if (!report || typeof report !== 'object') return null;
+  const hasIssues = Array.isArray(report.issues);
+  if (!hasIssues && !Array.isArray(report.files)) return null;
   let deadExports = null;
-  try {
-    if (Array.isArray(report.issues)) {
-      deadExports = report.issues.reduce((acc, issue) => {
-        const ex = Array.isArray(issue.exports) ? issue.exports.length : 0;
-        const ty = Array.isArray(issue.types) ? issue.types.length : 0;
-        return acc + ex + ty;
-      }, 0);
-      deadFiles = report.issues.reduce(
-        // knip 6 gives an ARRAY here ([{ name }]), not a bool (task 1004875).
-        (acc, issue) => acc + (issue.files === true || (Array.isArray(issue.files) && issue.files.length) ? 1 : 0),
-        0
-      );
-    }
-    // Some reporter modes additionally surface a flat unused-file list.
-    if (Array.isArray(report.files)) {
-      deadFiles = (deadFiles ?? 0) + report.files.length;
-    }
-    if (deadExports == null && deadFiles == null) {
-      return { dead_exports: null, dead_files: null, knip_status: 'unexpected_shape' };
-    }
-  } catch (_) {
-    return { dead_exports: null, dead_files: null, knip_status: 'unexpected_shape' };
+  let deadFiles = null;
+  if (hasIssues) {
+    const exportsOnly = report.issues.map((issue) => ({ file: issue.file, exports: issue.exports, types: issue.types }));
+    deadExports = countKnipFindings({ issues: exportsOnly }, opts);
+    deadFiles = report.issues.reduce(
+      // knip 6 gives an ARRAY here ([{ name }]), not a bool (task 1004875).
+      (acc, issue) => acc + (issue.files === true || (Array.isArray(issue.files) && issue.files.length) ? 1 : 0),
+      0
+    );
   }
-  return { dead_exports: deadExports, dead_files: deadFiles, knip_status: 'ok' };
+  // Some reporter modes additionally surface a flat unused-file list.
+  if (Array.isArray(report.files)) deadFiles = (deadFiles ?? 0) + report.files.length;
+  return { dead_exports: deadExports, dead_files: deadFiles };
 }
 
 // ---------- branch hygiene ----------
@@ -287,7 +296,7 @@ async function upsertSnapshot(pool, snap) {
 
 // ---------- main ----------
 
-(async () => {
+async function main() {
   const args = process.argv.slice(2);
   const asJson = hasFlag('--json', args);
   const noWrite = hasFlag('--no-write', args);
@@ -360,7 +369,15 @@ async function upsertSnapshot(pool, snap) {
   }
 
   process.exit(0);
-})().catch((err) => {
-  console.error('fatal:', err);
-  process.exit(1);
-});
+}
+
+module.exports = { scoreKnipReport };
+
+// CLI only when run directly, so a test can require this file without it
+// scanning the repo or writing to the DB (task 1004892).
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('fatal:', err);
+    process.exit(1);
+  });
+}

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.180'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.181'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/repo_metrics_dead_exports.mjs

@@ -0,0 +1,57 @@
+// tests/repo_metrics_dead_exports.mjs — repo-metrics scores dead exports the way the
+// CI knip ratchet does (task 1004892).
+//
+// Once knip scanned modules/ (task 1004875), repo-metrics' raw export count jumped by
+// ~1,800: knip does not credit a CommonJS namespace use (`lib.x`), and modules/ is
+// written that way. The ratchet's scorer (countKnipFindings) filters those by name;
+// repo-metrics must use the same scorer, so the dashboard number matches CI's.
+// Hermetic: synthetic knip JSON and an injected word index, no knip run.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+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 rm = require(path.join(ROOT, 'scripts/bongos/repo-metrics.js'));
+const fr = require(path.join(ROOT, 'scripts/bongos/fitness-ratchets.js'));
+
+const issue = (file, extra) => ({ file, files: [], exports: [], types: [], dependencies: [], unlisted: [], ...extra });
+
+test('a modules/ export used through a namespace elsewhere is not a dead export', () => {
+  const wordIndex = new Map([
+    ['usedViaNamespace', true], // spelled in 2+ files
+    ['onlyHere', 'modules/x/lib.js'], // spelled only in its own file
+  ]);
+  const report = {
+    issues: [
+      issue('modules/x/lib.js', {
+        exports: [{ name: 'usedViaNamespace' }, { name: 'onlyHere' }],
+        types: [{ name: 'neverSpelled' }],
+      }),
+      issue('src/y.js', { exports: [{ name: 'usedViaNamespace' }] }), // outside modules/: knip's verdict stands
+    ],
+  };
+  const scored = rm.scoreKnipReport(report, { wordIndex });
+  assert.equal(scored.dead_exports, 3); // onlyHere + neverSpelled + the src/ one
+  // ...and that is exactly the ratchet scorer's count for the same export/type findings.
+  assert.equal(scored.dead_exports, fr.countKnipFindings(report, { wordIndex }));
+});
+
+test('non-export findings (deps, unlisted) do not leak into dead_exports; dead files still count', () => {
+  const report = {
+    issues: [
+      issue('src/a.js', { files: [{ name: 'src/a.js' }], dependencies: [{ name: 'left-pad' }], exports: [{ name: 'x' }] }),
+      issue('src/b.js', { unlisted: [{ name: 'chalk' }] }),
+    ],
+  };
+  const scored = rm.scoreKnipReport(report, { wordIndex: new Map() });
+  assert.equal(scored.dead_exports, 1);
+  assert.equal(scored.dead_files, 1);
+});
+
+test('a report with no issues list is an unexpected shape (null), not zero', () => {
+  assert.equal(rm.scoreKnipReport({}, { wordIndex: new Map() }), null);
+  assert.equal(rm.scoreKnipReport(null, { wordIndex: new Map() }), null);
+});