@bongos/core 1.17.0

package/scripts/gds/gen-atlas.js

@@ -0,0 +1,366 @@
+#!/usr/bin/env node
+'use strict';
+// gen-atlas.js — generate the Repo Atlas data file (modules/hall-ui/public/atlas.json)
+// straight from the code, for the Builders' Hall "Repo Atlas" page (idea #457,
+// ADR 0094). Two views share one data file: (the hall surface carved to
+// modules/hall-ui/public/ in BV1.R85.)
+//
+//   context  — how .md/context is organized: the always-loaded root CLAUDE.md vs
+//              the on-demand nested guides, the docs library, the DB as live
+//              state, the context-budget gauge, and broken-link drift.
+//   modules  — the TRUTH of the module system: the real modules carved into
+//              modules/<key>/ (clean boundary) vs the core blob (src/bongos, with
+//              db.js the big monolith) vs the planned-but-still-fused ghosts
+//              (the module-scope-map roster that has no modules/<key>/ dir yet).
+//
+// DESIGN INVARIANTS (ADR 0094):
+//   * Pure file-reads — NO network, NO GDS session. Runs headless on the droplet
+//     at deploy (the world-snapshot precedent, scripts/snapshots/render-world.mjs).
+//   * SERVER-SIDE regeneration: a step in scripts/deploy/deploy-prod.sh runs this
+//     on every deploy and writes atlas.json into the served dir. atlas.json is a
+//     build artifact (gitignored) — never committed, never hand-edited, so it
+//     can't drift. The page degrades gracefully when it's absent.
+//   * Two optional overlays (broken-link count, kernel-leak count) shell out to
+//     docs-entropy.js / fitness.js best-effort; if either fails the overlay is
+//     simply omitted and the map still generates.
+//
+// Usage:
+//   node scripts/gds/gen-atlas.js                 # write modules/hall-ui/public/atlas.json
+//   node scripts/gds/gen-atlas.js --out PATH      # write elsewhere
+//   node scripts/gds/gen-atlas.js --stdout        # print to stdout, write nothing
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { MODULE_GLOBS, MODULE_SCOPE_MAP } = require('../../src/bongos/module-scope-map');
+const { deriveProvenance } = require('../../src/module-loader/provenance');
+function ownProjectName() {
+  try { return require('../../src/branding').branding().identity.productName; } catch { return null; }
+}
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// Mirrors scripts/gds/fitness.js Check 2 (ADR 0061). Display-only gauge; if the
+// fitness ceilings move, this is a cosmetic drift in the budget bar, not a bug.
+const CLAUDE_MD_MAX_LINES = 300;
+const CLAUDE_MD_MAX_CHARS = 42000;
+
+// ---------------------------------------------------------------------------
+// small fs helpers (dependency-free; safe on the droplet)
+// ---------------------------------------------------------------------------
+function exists(rel) { try { fs.accessSync(path.join(REPO_ROOT, rel)); return true; } catch { return false; } }
+function readText(rel) { try { return fs.readFileSync(path.join(REPO_ROOT, rel), 'utf8'); } catch { return ''; } }
+function readJson(rel) { try { return JSON.parse(fs.readFileSync(path.join(REPO_ROOT, rel), 'utf8')); } catch { return null; } }
+
+function listDir(rel) {
+  try { return fs.readdirSync(path.join(REPO_ROOT, rel), { withFileTypes: true }); } catch { return []; }
+}
+function countMd(rel, { excludeReadme = true } = {}) {
+  return listDir(rel).filter((e) => e.isFile() && e.name.endsWith('.md') && !(excludeReadme && /^readme\.md$/i.test(e.name))).length;
+}
+
+// Recursively gather *.js under an absolute dir (skips node_modules/.git).
+function walkJs(absRoot, out = []) {
+  let st; try { st = fs.statSync(absRoot); } catch { return out; }
+  if (st.isFile()) { if (absRoot.endsWith('.js')) out.push(absRoot); return out; }
+  for (const ent of fs.readdirSync(absRoot, { withFileTypes: true })) {
+    if (ent.name === 'node_modules' || ent.name === '.git') continue;
+    walkJs(path.join(absRoot, ent.name), out);
+  }
+  return out;
+}
+// Lines of code + file count for a dir of .js (or a single file).
+function locOf(rel) {
+  const abs = path.join(REPO_ROOT, rel);
+  let files = [];
+  try { files = fs.statSync(abs).isDirectory() ? walkJs(abs) : (abs.endsWith('.js') ? [abs] : []); } catch { return { loc: 0, files: 0 }; }
+  let loc = 0;
+  for (const f of files) { try { loc += fs.readFileSync(f, 'utf8').split('\n').length; } catch { /* skip */ } }
+  return { loc, files: files.length };
+}
+function fmtLoc(n) { return n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n); }
+
+// Every CLAUDE.md in the tree (root + nested), relative to REPO_ROOT.
+function findClaudeMds(absDir = REPO_ROOT, out = []) {
+  for (const ent of fs.readdirSync(absDir, { withFileTypes: true })) {
+    if (ent.name === 'node_modules' || ent.name === '.git') continue;
+    const abs = path.join(absDir, ent.name);
+    if (ent.isDirectory()) findClaudeMds(abs, out);
+    else if (ent.name === 'CLAUDE.md') out.push(path.relative(REPO_ROOT, abs).split(path.sep).join('/'));
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// best-effort overlays (shell out; never fatal)
+// ---------------------------------------------------------------------------
+function runJson(scriptRel, args) {
+  try {
+    const out = execFileSync(process.execPath, [path.join(REPO_ROOT, scriptRel), ...args],
+      { cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 45000 });
+    return JSON.parse(out);
+  } catch (err) {
+    // fitness.js exits non-zero on a hard-fail but still prints JSON to stdout.
+    if (err && err.stdout) { try { return JSON.parse(err.stdout.toString()); } catch { /* fall through */ } }
+    return null;
+  }
+}
+function staleLinkCount() {
+  const r = runJson('scripts/gds/docs-entropy.js', ['--json']);
+  return r && Number.isFinite(r.stale_links) ? r.stale_links : null;
+}
+function kernelLeakCount() {
+  const r = runJson('scripts/gds/fitness.js', ['--json']);
+  if (!r) return null;
+  const checks = Array.isArray(r) ? r : (r.checks || []);
+  const leak = checks.find((c) => /kernel/i.test(c.name || '') && /domain/i.test(c.name || ''));
+  if (!leak) return null;
+  return (leak.warnings || []).length + (leak.violations || []).length;
+}
+
+// ---------------------------------------------------------------------------
+// module require-scan: does a module reach a sibling or deep core internal?
+// (the clean-vs-spaghetti signal — same rule as fitness.js moduleImportViolation)
+// ---------------------------------------------------------------------------
+const REQUIRE_RE = /require\(\s*['"](\.\.?\/[^'"]+)['"]\s*\)/g;
+const relOf = (abs) => path.relative(REPO_ROOT, abs).split(path.sep).join('/');
+function moduleBoundaryViolations(moduleKey) {
+  const dirAbs = path.join(REPO_ROOT, 'modules', moduleKey);
+  const violations = [];
+  for (const abs of walkJs(dirAbs)) {
+    for (const raw of fs.readFileSync(abs, 'utf8').split('\n')) {
+      const t = raw.trim();
+      if (t.startsWith('//') || t.startsWith('*') || t.startsWith('/*')) continue;
+      let m; REQUIRE_RE.lastIndex = 0;
+      while ((m = REQUIRE_RE.exec(raw))) {
+        const target = relOf(path.resolve(path.dirname(abs), m[1]));
+        const forms = [target, target + '.js', target.replace(/\/$/, '') + '/index.js'];
+        if (forms.includes('src/module-api.js')) continue;       // the doorway — allowed
+        const sib = /^modules\/([^/]+)(\/|$)/.exec(target);
+        if (sib) { if (sib[1] !== moduleKey) violations.push(`${relOf(abs)} → ${m[1]} (sibling ${sib[1]})`); continue; }
+        if (/^src\//.test(target)) violations.push(`${relOf(abs)} → ${m[1]} (deep core)`);
+      }
+    }
+  }
+  return violations;
+}
+
+// ===========================================================================
+// CONTEXT VIEW — how .md / context is organized
+// ===========================================================================
+function buildContextView() {
+  const claudeMds = findClaudeMds();
+  const nested = claudeMds.filter((f) => f !== 'CLAUDE.md').sort();
+
+  const rootText = readText('CLAUDE.md');
+  const rootLines = rootText ? rootText.split('\n').length : 0;
+  const rootChars = rootText.length;
+
+  const counts = {
+    adr: countMd('docs/adr'),
+    recipes: countMd('docs/recipes'),
+    audits: countMd('docs/audits'),
+    sessions: listDir('docs/session-logs').filter((e) => e.isFile() && e.name.endsWith('.md')).length,
+  };
+  const stale = staleLinkCount();
+
+  const nodes = [];
+  const edges = [];
+
+  nodes.push({
+    id: 'root', label: 'CLAUDE.md', sub: 'the index', kind: 'hub', group: 'always',
+    metric: `${rootLines} lines`,
+    badge: { t: `${rootLines} / ${CLAUDE_MD_MAX_LINES} lines`, k: rootLines > CLAUDE_MD_MAX_LINES ? 'danger' : 'warn' },
+    path: 'CLAUDE.md',
+    desc: `The one file loaded into the AI's memory at the START of every session — the index, not the encyclopedia. Because it is always loaded it has a hard size budget (${rootLines} of ${CLAUDE_MD_MAX_LINES} lines, ~${Math.round(rootChars / 4)} of ~${Math.round(CLAUDE_MD_MAX_CHARS / 4)} tokens), enforced automatically so it can't bloat.`,
+  });
+
+  // One island per nested CLAUDE.md (loads on demand). Real list from disk.
+  for (const rel of nested) {
+    const dir = rel.replace(/\/CLAUDE\.md$/, '');
+    nodes.push({
+      id: `nested:${dir}`, label: dir, sub: 'on-demand guide', kind: 'nested', group: 'ondemand',
+      path: rel,
+      desc: `A folder-level guide that loads ONLY when an agent works in ${dir}/. The agent never carries it otherwise — that's the whole trick of context management. ${nested.length} of these exist plus the root.`,
+    });
+    edges.push({ a: 'root', b: `nested:${dir}`, kind: 'gov' });
+  }
+
+  // Docs library clusters (real counts).
+  const docs = [
+    { id: 'docs:adr', label: 'Decisions', sub: `${counts.adr} ADRs`, path: 'docs/adr/', n: counts.adr,
+      desc: `Architecture Decision Records — one file per non-obvious choice, explaining WHY. ${counts.adr} of them; the most cross-linked corner of the repo.` },
+    { id: 'docs:recipes', label: 'Recipes', sub: `${counts.recipes} guides`, path: 'docs/recipes/', n: counts.recipes,
+      desc: `Multi-page operational how-tos (deploy, backup, merge). Read before doing similar work. ${counts.recipes} of them.` },
+    { id: 'docs:audits', label: 'Audits', sub: `${counts.audits} reviews`, path: 'docs/audits/', n: counts.audits,
+      desc: `First-principles "what to delete" reviews that feed next-version scope. ${counts.audits} of them.` },
+    { id: 'docs:sessions', label: 'Session logs', sub: `${counts.sessions} entries`, path: 'docs/session-logs/', n: counts.sessions,
+      desc: `One file per work session — the narrative history of what happened and why. ${counts.sessions} of them.` },
+  ];
+  for (const d of docs) {
+    const node = { id: d.id, label: d.label, sub: d.sub, kind: 'docs', group: 'library', path: d.path, desc: d.desc, metric: `${d.n} files` };
+    if (d.id === 'docs:adr' && Number.isFinite(stale) && stale > 0) {
+      node.badge = { t: `${stale} stale links`, k: 'danger' };
+      node.desc += ` Repo-wide there are ${stale} broken internal links today — the "drift" the whole context system fights. A live map makes it visible.`;
+    }
+    nodes.push(node);
+    edges.push({ a: 'root', b: d.id, kind: 'drill' });
+  }
+  if (Number.isFinite(stale) && stale > 0) edges.push({ a: 'docs:adr', b: 'docs:recipes', kind: 'drift' });
+
+  // The database — live state, never a file.
+  nodes.push({
+    id: 'db', label: 'The database', sub: 'live state', kind: 'db', group: 'live', path: 'Postgres — tasks · versions · costs',
+    badge: { t: "can't go stale", k: 'info' },
+    desc: 'Tasks, versions, costs, ranks — anything that CHANGES. Deliberately kept out of files so prose can never disagree with reality. A place context lives that is NOT a document.',
+  });
+  edges.push({ a: 'root', b: 'db', kind: 'live' });
+
+  // Self-generating context (the Atlas's own mechanism).
+  nodes.push({
+    id: 'generated', label: 'Auto-generated', sub: 'repo-map · index', kind: 'generated', group: 'live',
+    path: 'docs/repo-map.md · session-log-index.md', badge: { t: '⚙ self-updating', k: 'info' },
+    desc: "Some context writes itself on every deploy (the symbol map, the session index), marked do-not-edit so it can't drift. This is exactly the mechanism the Repo Atlas itself uses.",
+  });
+  edges.push({ a: 'root', b: 'generated', kind: 'gov' });
+
+  return {
+    blurb: 'How context is organized — and kept from rotting. The glowing island loads into the AI on EVERY session, so it stays tiny; the cool-blue islands load only when relevant; the paper islands are the reference library; the coral island is the database (live state, never a file).',
+    sub: `Generated from the repo on the last deploy. ${nested.length} on-demand guides · ${counts.adr} ADRs · ${counts.recipes} recipes · ${counts.sessions} session logs${Number.isFinite(stale) ? ` · ${stale} broken links` : ''}.`,
+    legend: [
+      { sw: 'sun', t: 'Loaded every session (keep tiny)' },
+      { sw: 'sky', t: 'On-demand (loads only when relevant)' },
+      { sw: 'paper', t: 'Reference library (docs)' },
+      { sw: 'coral', t: 'Live state — the database, never a file' },
+      { ln: 'danger', dash: true, t: 'Broken link (drift)' },
+    ],
+    nodes, edges,
+  };
+}
+
+// ===========================================================================
+// MODULE VIEW — the truth of the module system
+// ===========================================================================
+function buildModuleView() {
+  const nodes = [];
+  const edges = [];
+
+  // Core blob + its db.js monolith.
+  const core = locOf('src/bongos');
+  const db = locOf('src/bongos/db.js');
+  const leaks = kernelLeakCount();
+  const coreNode = {
+    id: 'core', label: 'src/bongos', sub: 'the core', kind: 'core', group: 'core',
+    loc: core.loc, files: core.files, metric: `${fmtLoc(core.loc)} lines`, path: 'src/bongos/',
+    desc: `The original monolith everything still hangs off — about ${fmtLoc(core.loc)} lines across ${core.files} files not yet split into modules. The one giant island: the honest picture of where the coupling still lives.`,
+  };
+  if (Number.isFinite(leaks) && leaks > 0) {
+    coreNode.badge = { t: `${leaks} kernel leaks`, k: 'warn' };
+    coreNode.desc += ` ${leaks} kernel→domain import leaks remain (tracked by the fitness ratchet).`;
+  }
+  nodes.push(coreNode);
+  nodes.push({
+    id: 'db', label: 'db.js', sub: `${fmtLoc(db.loc)} lines`, kind: 'db', group: 'core',
+    loc: db.loc, files: 1, metric: `${db.loc} lines`, path: 'src/bongos/db.js', badge: { t: 'the monolith', k: 'danger' },
+    desc: `A single ${db.loc}-line file nearly every part of the system reaches into for data. The dominant remaining tangle — the clearest "spaghetti" the map surfaces.`,
+  });
+  edges.push({ a: 'core', b: 'db', kind: 'monolith' });
+
+  // The roster to render = the scope-map roster (minus kernel, which IS the core)
+  // UNION any modules/<key>/ that actually exist on disk but aren't in the roster
+  // yet (e.g. character-anim) — so a real module can never be silently dropped.
+  const onDiskModules = listDir('modules').filter((e) => e.isDirectory()).map((e) => e.name);
+  const rosterKeys = Object.keys(MODULE_GLOBS).filter((k) => k !== 'kernel');
+  const allKeys = Array.from(new Set([...rosterKeys, ...onDiskModules]));
+  const ownName = ownProjectName();
+
+  let realCount = 0, ghostCount = 0, ownCount = 0, coreCount = 0;
+  for (const key of allKeys) {
+    const onDisk = onDiskModules.includes(key);
+    const scope = MODULE_SCOPE_MAP[key] || { globs: [], protected: false };
+
+    if (onDisk) {
+      realCount += 1;
+      const manifest = readJson(`modules/${key}/module.json`) || {};
+      const { loc, files } = locOf(`modules/${key}`);
+      const violations = moduleBoundaryViolations(key);
+      const clean = violations.length === 0;
+      const provides = Array.isArray(manifest.provides) ? manifest.provides : [];
+      // ADR 0107 §9: provenance — which Cloud Bongos CORE modules this instance
+      // loads vs. which modules the project built ITSELF. See
+      // src/module-loader/provenance.js for the (honest, pre-split) rule.
+      const provenance = deriveProvenance(manifest.origin, ownName);
+      if (provenance === 'own') ownCount += 1; else coreCount += 1;
+      const node = {
+        id: `mod:${key}`, label: key, sub: `${fmtLoc(loc)} lines`, kind: 'module', group: 'module',
+        loc, files, metric: `${fmtLoc(loc)} lines · ${files} files`, path: `modules/${key}/`,
+        provides, consumes: Array.isArray(manifest.consumes) ? manifest.consumes : [],
+        health: clean ? 'clean' : 'violation',
+        provenance,
+        author: manifest.author || null,
+        origin: manifest.origin || null,
+        license: manifest.license || null,
+        maintainer: manifest.maintainer || null,
+        desc: (manifest.description ? manifest.description.replace(/\s+/g, ' ').trim() + ' ' : '') +
+          (clean
+            ? 'Clean boundary: it reaches the core only through the published doorway — no sibling imports, no deep-core reach.'
+            : `Boundary VIOLATIONS (${violations.length}): ${violations.slice(0, 3).join('; ')}.`) +
+          (provides.length ? ` Provides seam(s): ${provides.join(', ')}.` : '') +
+          (provenance === 'core' ? ` Core-loaded — built by ${manifest.origin}, pulled in from the shared Cloud Bongos catalog.` : ' Built by this project.'),
+      };
+      if (!clean) node.badge = { t: `${violations.length} violations`, k: 'danger' };
+      else if (loc === 0) node.badge = { t: 'declaration-only', k: 'info' };
+      nodes.push(node);
+      edges.push({ a: `mod:${key}`, b: 'core', kind: clean ? 'clean' : 'violation', ports: provides });
+    } else {
+      ghostCount += 1;
+      const fused = (scope.globs || []).some((g) => g.startsWith('src/bongos/'));
+      nodes.push({
+        id: `ghost:${key}`, label: key, sub: 'planned', kind: 'ghost', group: 'ghost', fused,
+        path: '(no modules/ dir yet)',
+        desc: fused
+          ? `On the design's module map, but no modules/${key}/ folder exists yet — its code is still fused inside the core blob (${(scope.globs || []).filter((g) => g.startsWith('src/bongos/')).slice(0, 3).join(', ') || 'src/bongos/'}). Shown as a ghost tethered to where it lives today.`
+          : `Planned module — its code lives in its own dir (${(scope.globs || [])[0] || '?'}) but it has not been wrapped as a formal module/<key>/ yet.`,
+      });
+      if (fused) edges.push({ a: `ghost:${key}`, b: 'core', kind: 'ghost' });
+    }
+  }
+
+  return {
+    blurb: 'The TRUTH, generated straight from the code: which modules are really separated into clean files (green), what is still fused inside the core blob (the big island), and what is only a plan (the ghost outlines). Connections are real dependency + boundary facts.',
+    sub: `Generated from the repo on the last deploy. ${realCount} real modules (${ownCount} built by this project · ${coreCount} core-loaded) · ${ghostCount} planned/ghost · core ${fmtLoc(core.loc)} lines${Number.isFinite(leaks) ? ` · ${leaks} kernel leaks` : ''}.`,
+    provenance: { own: ownCount, core: coreCount },
+    legend: [
+      { sw: 'good', t: 'Real module — clean boundary' },
+      { sw: 'core', t: 'Core blob — still fused' },
+      { sw: 'db', t: 'db.js — the monolith' },
+      { sw: 'ghost', dash: true, t: 'Planned, not yet carved out' },
+      { ln: 'danger', dash: true, t: 'Coupling / violation' },
+    ],
+    nodes, edges,
+  };
+}
+
+// ---------------------------------------------------------------------------
+function main() {
+  const args = process.argv.slice(2);
+  const outIdx = args.indexOf('--out');
+  const outPath = outIdx !== -1 ? args[outIdx + 1] : path.join(REPO_ROOT, 'modules', 'hall-ui', 'public', 'atlas.json');
+  const toStdout = args.includes('--stdout');
+
+  const data = {
+    generatedAt: new Date().toISOString(),
+    views: { context: buildContextView(), modules: buildModuleView() },
+  };
+  const json = JSON.stringify(data, null, 2);
+
+  if (toStdout) { process.stdout.write(json + '\n'); return; }
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, json + '\n');
+  const ctx = data.views.context, mod = data.views.modules;
+  console.log(`gen-atlas: wrote ${path.relative(REPO_ROOT, outPath)} — context ${ctx.nodes.length} nodes/${ctx.edges.length} edges · modules ${mod.nodes.length} nodes/${mod.edges.length} edges`);
+}
+
+if (require.main === module) main();
+
+module.exports = { buildContextView, buildModuleView };