@bongos/core 1.19.99 → 1.19.100

package/tests/module_catalog.mjs

@@ -0,0 +1,304 @@
+// tests/module_catalog.mjs — the browsable module catalog (ADR 0107 §2/§3,
+// task 1001772). src/module-loader/catalog.js is the ONE model behind both the
+// hall's Modules tab and `bongos module list --catalog`, so these tests pin the
+// two axes that were conflated before it existed:
+//
+//   source     which TREE a module ships from (core package vs. this repo) —
+//              the catalog axis, read structurally off the discovery root.
+//   provenance WHO built it — the credit axis, read off manifest.origin.
+//
+// Pure + hermetic: every case injects its own loaded[]/roots, so nothing here
+// touches the real modules/ tree or a running server. DB-free → picked up by
+// scripts/gds/run-unit-tests.js (the `unit` gate).
+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 catalog = require(path.join(ROOT, 'src', 'module-loader', 'catalog.js'));
+const mod = require(path.join(ROOT, 'scripts', 'gds', 'module.js'));
+
+const CORE = path.join(path.sep, 'srv', 'app', 'node_modules', '@bongos', 'core');
+const INST = path.join(path.sep, 'srv', 'app');
+
+const manifest = (over = {}) => ({
+  key: 'x', title: 'X', description: 'a module', coreVersion: '^1.0.0', contributes: {}, ...over,
+});
+const loadedIn = (root, key, over = {}) => ({
+  key, dir: path.join(root, 'modules', key), manifest: manifest({ key, title: key, ...over }),
+});
+
+// ---------------------------------------------------------------------------
+// deriveSource — the catalog axis
+// ---------------------------------------------------------------------------
+
+test('deriveSource: distinct roots → structural (core package tree = the catalog)', () => {
+  const opts = { coreRoot: CORE, instanceRoot: INST };
+  assert.equal(catalog.deriveSource(path.join(CORE, 'modules', 'economy'), opts), 'core');
+  assert.equal(catalog.deriveSource(path.join(INST, 'modules', 'game'), opts), 'instance');
+});
+
+test('deriveSource: a sibling dir that merely starts with "modules" is not inside modules/', () => {
+  const opts = { coreRoot: CORE, instanceRoot: INST };
+  // path-segment aware — ".../modules-extra/economy" must not read as core.
+  assert.equal(catalog.deriveSource(path.join(CORE, 'modules-extra', 'economy'), opts), 'instance');
+});
+
+test('deriveSource: unknown root (neither tree) is never claimed for the catalog', () => {
+  const opts = { coreRoot: CORE, instanceRoot: INST };
+  assert.equal(catalog.deriveSource(path.join(path.sep, 'elsewhere', 'modules', 'x'), opts), 'instance');
+});
+
+test('deriveSource: coincident roots fall back to what the checkout says it is', () => {
+  const dir = path.join(INST, 'modules', 'economy');
+  // The core's own repo: modules/ IS the catalog.
+  assert.equal(catalog.deriveSource(dir, { coreRoot: INST, instanceRoot: INST, coreCheckout: true }), 'core');
+  // A single-checkout instance: its modules/ are its own, not a shared catalog.
+  assert.equal(catalog.deriveSource(dir, { coreRoot: INST, instanceRoot: INST, coreCheckout: false }), 'instance');
+});
+
+test('isCorePackageName: recognises the published + source names, nothing else', () => {
+  assert.equal(catalog.isCorePackageName('@bongos/core'), true);
+  assert.equal(catalog.isCorePackageName('cloud-bongos'), true);
+  assert.equal(catalog.isCorePackageName(' cloud-bongos '), true, 'tolerates stray whitespace');
+  assert.equal(catalog.isCorePackageName('some-instance'), false);
+  assert.equal(catalog.isCorePackageName(undefined), false);
+});
+
+// ---------------------------------------------------------------------------
+// creditFor — the ADR 0107 §2/§3 attribution record
+// ---------------------------------------------------------------------------
+
+test('creditFor: a declared author + origin is passed through untouched, not inferred', () => {
+  const c = catalog.creditFor({ author: 'Mercury', origin: 'Mercury (mercury.example)' }, { source: 'core' });
+  assert.deepEqual(c, { author: 'Mercury', origin: 'Mercury (mercury.example)', inferred: false });
+});
+
+test('creditFor: a core module declaring nothing is credited to the platform, and marked inferred', () => {
+  const c = catalog.creditFor({}, { source: 'core' });
+  assert.equal(c.author, catalog.CORE_PROJECT_NAME);
+  assert.equal(c.origin, catalog.CORE_PROJECT_NAME);
+  assert.equal(c.inferred, true, 'an inferred credit MUST be marked — it is not a claim the author made');
+});
+
+test('creditFor: an instance module declaring nothing stays uncredited rather than borrowing the platform name', () => {
+  const c = catalog.creditFor({}, { source: 'instance' });
+  assert.deepEqual(c, { author: null, origin: null, inferred: false });
+});
+
+test('creditFor: a half-declared credit still marks inferred (the filled half came from the fallback)', () => {
+  const c = catalog.creditFor({ author: 'Mercury' }, { source: 'core' });
+  assert.equal(c.author, 'Mercury');
+  assert.equal(c.origin, catalog.CORE_PROJECT_NAME);
+  assert.equal(c.inferred, true);
+});
+
+test('creditFor: whitespace-only attribution counts as undeclared', () => {
+  const c = catalog.creditFor({ author: '   ', origin: '' }, { source: 'core' });
+  assert.equal(c.author, catalog.CORE_PROJECT_NAME);
+  assert.equal(c.inferred, true);
+});
+
+// ---------------------------------------------------------------------------
+// buildCatalog — the row model both surfaces render
+// ---------------------------------------------------------------------------
+
+test('buildCatalog: keeps the DECLARED manifest fields beside the display credit', () => {
+  const [row] = catalog.buildCatalog({
+    loaded: [loadedIn(CORE, 'economy')],
+    coreRoot: CORE, instanceRoot: INST,
+  });
+  // The declared fields are what provenance is derived from; blanking them
+  // would silently reclassify every core module as core-loaded.
+  assert.equal(row.author, null);
+  assert.equal(row.origin, null);
+  assert.equal(row.credit.author, catalog.CORE_PROJECT_NAME);
+  assert.equal(row.provenance, 'own', 'no declared origin → own-built (ADR 0107 §9)');
+});
+
+test('buildCatalog: source and provenance are independent axes', () => {
+  const rows = catalog.buildCatalog({
+    loaded: [loadedIn(CORE, 'provisioning', { origin: 'Off the Boats', author: 'Off the Boats' })],
+    coreRoot: CORE, instanceRoot: INST,
+    ownProjectName: 'Mercury',
+  });
+  // Ships from the core package (so: enable-able catalog) but was BUILT by
+  // another project (so: core-loaded credit). Exactly the case the catalog exists for.
+  assert.equal(rows[0].source, 'core');
+  assert.equal(rows[0].provenance, 'core');
+});
+
+test('buildCatalog: enablement comes from the resolved map, and rows sort by key', () => {
+  const rows = catalog.buildCatalog({
+    loaded: [loadedIn(CORE, 'zeta'), loadedIn(CORE, 'alpha'), loadedIn(INST, 'mid')],
+    enabled: { alpha: true, mid: false },
+    coreRoot: CORE, instanceRoot: INST,
+  });
+  assert.deepEqual(rows.map((r) => r.key), ['alpha', 'mid', 'zeta']);
+  assert.deepEqual(rows.map((r) => r.enabled), [true, false, false]);
+});
+
+test('buildCatalog: survives a manifest with nothing but the required keys', () => {
+  const [row] = catalog.buildCatalog({ loaded: [loadedIn(INST, 'bare')], coreRoot: CORE, instanceRoot: INST });
+  assert.equal(row.title, 'bare');
+  assert.deepEqual(row.contributes, {});
+  assert.equal(row.maintenance, null);
+  assert.equal(row.default, false);
+});
+
+// ---------------------------------------------------------------------------
+// catalogRows / searchCatalog / summarize
+// ---------------------------------------------------------------------------
+
+const sample = () => catalog.buildCatalog({
+  loaded: [
+    loadedIn(CORE, 'economy', { description: 'drachmae and credits' }),
+    loadedIn(CORE, 'provisioning', { author: 'Off the Boats', origin: 'Off the Boats', license: 'AGPL-3.0' }),
+    loadedIn(INST, 'game', { description: 'the world' }),
+  ],
+  enabled: { economy: true, game: true },
+  coreRoot: CORE, instanceRoot: INST,
+});
+
+test('catalogRows / instanceRows: the catalog is exactly the core-shipped half', () => {
+  const rows = sample();
+  assert.deepEqual(catalog.catalogRows(rows).map((r) => r.key), ['economy', 'provisioning']);
+  assert.deepEqual(catalog.instanceRows(rows).map((r) => r.key), ['game']);
+});
+
+test('searchCatalog: matches key, description, author, origin and licence; empty query is a pass-through', () => {
+  const rows = sample();
+  assert.equal(catalog.searchCatalog(rows, '').length, 3);
+  assert.equal(catalog.searchCatalog(rows, '   ').length, 3);
+  assert.deepEqual(catalog.searchCatalog(rows, 'DRACHMAE').map((r) => r.key), ['economy'], 'case-insensitive, over description');
+  assert.deepEqual(catalog.searchCatalog(rows, 'off the boats').map((r) => r.key), ['provisioning'], 'over the credit');
+  assert.deepEqual(catalog.searchCatalog(rows, 'agpl').map((r) => r.key), ['provisioning'], 'over the licence');
+  assert.deepEqual(catalog.searchCatalog(rows, 'nothing-matches-this'), []);
+});
+
+test('searchCatalog: searches the INFERRED credit too, so core modules are findable by the platform name', () => {
+  const rows = sample();
+  const hits = catalog.searchCatalog(rows, catalog.CORE_PROJECT_NAME.toLowerCase()).map((r) => r.key);
+  assert.ok(hits.includes('economy'), 'a core module with no declared author is still findable by its shipper');
+  assert.ok(!hits.includes('game'), 'an instance module must not borrow the platform credit');
+});
+
+test('summarize: counts the catalog half and the enabled half separately', () => {
+  assert.deepEqual(catalog.summarize(sample()), {
+    total: 3, catalog: 2, instance: 1, enabled: 2, catalog_enabled: 1,
+  });
+});
+
+// ---------------------------------------------------------------------------
+// `bongos module list` — the CLI surface over the same model
+// ---------------------------------------------------------------------------
+
+test('formatCatalog: renders every row with its credit, and marks the inferred ones', () => {
+  const out = mod.formatCatalog(sample(), { core: '1.19.0' });
+  assert.match(out, /every module on disk/);
+  assert.match(out, /2 in the core catalog \(1 enabled\) · 1 built here · 3 total/);
+  assert.match(out, /\[x\]\s+economy/, 'an enabled module is marked [x]');
+  assert.match(out, /\[ \]\s+provisioning/, 'a disabled module is marked [ ]');
+  assert.match(out, /Off the Boats/, 'a declared credit is shown');
+  assert.match(out, /credit not declared in module\.json/, 'the inferred-credit footnote appears when one is shown');
+});
+
+test('formatCatalog: --catalog narrows to the core-shipped modules only', () => {
+  const out = mod.formatCatalog(sample(), { catalogOnly: true });
+  assert.match(out, /core modules this instance can enable/);
+  assert.ok(!/\bgame\b/.test(out), 'an instance module is not part of the core catalog listing');
+});
+
+test('formatCatalog: a search reports its own hit count and drops the rest', () => {
+  const out = mod.formatCatalog(sample(), { query: 'drachmae' });
+  assert.match(out, /filter "drachmae" — 1 match\(es\)/);
+  assert.match(out, /economy/);
+  assert.ok(!/provisioning/.test(out));
+});
+
+test('formatCatalog: a search with no hits says so instead of printing an empty table', () => {
+  const out = mod.formatCatalog(sample(), { query: 'zzz-nothing' });
+  assert.match(out, /no module matches that filter/);
+  assert.ok(!/KEY\s+SOURCE/.test(out), 'no header row over an empty result');
+});
+
+test('cmdList: --json emits the rows + summary, and honours --catalog/--search', () => {
+  const lines = [];
+  const code = mod.cmdList(['--json', '--catalog', '--search', 'off the boats'], {
+    log: (s) => lines.push(s),
+    gather: () => ({ rows: sample(), skipped: [], errors: [], core: '1.19.0' }),
+  });
+  assert.equal(code, 0);
+  const payload = JSON.parse(lines.join('\n'));
+  assert.equal(payload.core, '1.19.0');
+  assert.deepEqual(payload.summary, { total: 3, catalog: 2, instance: 1, enabled: 2, catalog_enabled: 1 },
+    'the summary describes the WHOLE catalog, not the filtered slice');
+  assert.deepEqual(payload.modules.map((m) => m.key), ['provisioning']);
+});
+
+test('cmdList: --search with no value is a usage error, not a silent empty listing', () => {
+  const errs = [];
+  const code = mod.cmdList(['--search'], { log: () => {}, errlog: (s) => errs.push(s), gather: () => { throw new Error('must not gather'); } });
+  assert.equal(code, 2);
+  assert.match(errs.join('\n'), /usage: bongos module list/);
+});
+
+test('cmdList: a coreVersion-skipped module is surfaced on stderr, not silently dropped', () => {
+  const errs = [];
+  const code = mod.cmdList([], {
+    log: () => {},
+    errlog: (s) => errs.push(s),
+    gather: () => ({ rows: sample(), skipped: [{ key: 'rotted', reason: 'coreVersion "^0.1.0" not satisfied by core 1.19.0' }], errors: [], core: '1.19.0' }),
+  });
+  assert.equal(code, 0);
+  assert.match(errs.join('\n'), /rotted: not listed — coreVersion/);
+});
+
+// ---------------------------------------------------------------------------
+// The live tree — the catalog must actually describe THIS checkout
+// ---------------------------------------------------------------------------
+
+test('gatherCatalog: this checkout is the core, so its modules are the catalog', () => {
+  const { rows } = mod.gatherCatalog();
+  assert.ok(rows.length >= 5, `expected a real module roster, found ${rows.length}`);
+  for (const r of rows) {
+    assert.ok(['core', 'instance'].includes(r.source), `${r.key}: source is core|instance`);
+    assert.equal(typeof r.enabled, 'boolean');
+    assert.ok(r.credit && 'inferred' in r.credit, `${r.key}: carries a credit record`);
+  }
+  // detectRoots() reads THIS package.json, which names the core — so every
+  // module discovered here belongs to the catalog. If this ever fails, the
+  // catalog is quietly telling instances they can't enable anything.
+  assert.equal(catalog.instanceRows(rows).length, 0, 'the core checkout has no instance-only modules');
+  assert.equal(catalog.catalogRows(rows).length, rows.length);
+});
+
+test('detectRoots: identifies this repo as the core checkout', () => {
+  catalog._resetRoots();
+  const roots = catalog.detectRoots();
+  assert.equal(roots.coreCheckout, true);
+  assert.ok(catalog.isCorePackageName(roots.corePackageName));
+});
+
+test('detectRoots: memoized — listModules() is on the GET /modules request path, so it must not re-read the disk per call', () => {
+  catalog._resetRoots();
+  const first = catalog.detectRoots();
+  assert.equal(catalog.detectRoots(), first, 'the no-arg result is the SAME object — computed once, not per call');
+  catalog._resetRoots();
+  assert.notEqual(catalog.detectRoots(), first, '_resetRoots() drops the memo');
+});
+
+test('detectRoots: an explicit root bypasses the memo in both directions', () => {
+  catalog._resetRoots();
+  const cached = catalog.detectRoots();
+  const explicit = catalog.detectRoots({ coreRoot: CORE, instanceRoot: INST });
+  // Asking about a SPECIFIC tree must not return this process's memoized answer…
+  assert.equal(explicit.coreRoot, CORE);
+  assert.equal(explicit.instanceRoot, INST);
+  assert.notEqual(explicit, cached);
+  // …nor poison the memo for every later caller that asks about this process.
+  assert.equal(catalog.detectRoots(), cached);
+});