@bongos/core 1.19.64 → 1.19.65

package/tests/module_manifest.mjs

@@ -211,3 +211,68 @@ test('dependencies: a non-object, or a non-string range, is rejected', () => {
     assert.ok(r.errors.some((e) => e.startsWith('dependencies')), `error should mention dependencies: ${r.errors}`);
   }
 });
+
+// --- maintenance & deprecation policy (ADR 0107 §7 / ADR 0166) ---
+
+test('maintenance: omitted is fine (optional — pre-policy manifests still validate)', () => {
+  assert.equal(validateManifest(baseManifest()).valid, true);
+});
+
+test('maintenance: each of the four statuses validates when its own obligations are met', () => {
+  const cases = [
+    { maintenance: { status: 'core-maintained' } },
+    { maintainer: 'A. Builder', maintenance: { status: 'maintained' } },
+    { maintenance: { status: 'deprecated', successor: 'econ-v2', removeAfter: '1.12.0' } },
+    { maintenance: { status: 'orphaned', note: 'Author unreachable since 2026-07; enable at your own risk.' } },
+  ];
+  for (const extra of cases) {
+    const r = validateManifest({ ...baseManifest(), ...extra });
+    assert.equal(r.valid, true, `${extra.maintenance.status}: ${r.errors.join('; ')}`);
+  }
+});
+
+test('maintenance: "maintained" without a named top-level maintainer is rejected', () => {
+  const r = validateManifest({ ...baseManifest(), maintenance: { status: 'maintained' } });
+  assert.equal(r.valid, false, 'an unnamed maintainer IS the orphaning failure the policy prevents');
+  assert.ok(r.errors.some((e) => /maintained.*maintainer/.test(e)), r.errors.join('; '));
+});
+
+test('maintenance: a sunset status with no deprecation path (no successor, no note) is rejected', () => {
+  for (const status of ['deprecated', 'orphaned']) {
+    const r = validateManifest({ ...baseManifest(), maintenance: { status } });
+    assert.equal(r.valid, false, `${status} must state a path out`);
+    assert.ok(r.errors.some((e) => /deprecation path/.test(e)), r.errors.join('; '));
+  }
+});
+
+test('maintenance: an unknown status, an unknown key, or a bad version is rejected', () => {
+  const bad = [
+    { status: 'someday' },
+    { status: 'core-maintained', removeafter: '1.2.0' },
+    { status: 'core-maintained', since: 'v1.2' },
+    { status: 'deprecated', successor: 'Econ_V2' },
+    'core-maintained',
+  ];
+  for (const m of bad) {
+    const r = validateManifest({ ...baseManifest(), maintenance: m });
+    assert.equal(r.valid, false, `should reject ${JSON.stringify(m)}`);
+  }
+});
+
+test('maintenance: removeAfter only applies to a module on its way out', () => {
+  const r = validateManifest({ ...baseManifest(), maintenance: { status: 'core-maintained', removeAfter: '1.12.0' } });
+  assert.equal(r.valid, false);
+  assert.ok(r.errors.some((e) => /removeAfter only applies/.test(e)), r.errors.join('; '));
+});
+
+test('every bundled module declares a maintenance posture (the catalog has no unowned entries)', async () => {
+  const fsm = (await import('node:fs')).default;
+  const modulesDir = path.join(ROOT, 'modules');
+  const undeclared = fsm.readdirSync(modulesDir)
+    .filter((k) => fsm.existsSync(path.join(modulesDir, k, 'module.json')))
+    .filter((k) => {
+      const m = JSON.parse(fsm.readFileSync(path.join(modulesDir, k, 'module.json'), 'utf8'));
+      return !m.maintenance || !m.maintenance.status;
+    });
+  assert.deepEqual(undeclared, [], `these modules declare no maintenance.status: ${undeclared.join(', ')}`);
+});

package/tests/upgrade.mjs

@@ -935,6 +935,100 @@ t('healDocAssets: a generator absent from this core is recorded, not spawned', (
   assert.equal(spawned.length, 1, 'the absent script is never spawned');
 });
 
+// --- module maintenance & deprecation surfacing (ADR 0107 §7 / ADR 0166, task 1001773) ---
+//
+// The bug this pins: preflightModules used to return ONLY `blocking`, so a DISABLED module
+// whose coreVersion the target core no longer satisfies vanished from a real bump entirely.
+// An accepted catalog module ships default:false (ADR 0107 §6) — so that was every rotted
+// catalog entry, silently.
+
+// A modules/ dir on disk that preflightModules will really discover, driven through a stub
+// moduleLib so the verdict shape (not the loader) is what's under test.
+function moduleLibStub(verdict) {
+  return { gatherUpgrade: () => ({ rows: verdict.rows || [], errors: [], core: verdict.core }), evaluateUpgrade: () => verdict };
+}
+
+t('preflightModules: a DISABLED incompatible module is returned as a warning, not dropped', () => {
+  const dir = scratchConsumer();
+  mkdirSync(join(dir, 'modules'), { recursive: true });
+  const warned = { key: 'stale-catalog-entry', coreVersion: '^1.0.0', enabled: false, satisfied: false, maintainer: 'Ada <ada@example.com>', maintenance: { status: 'maintained' } };
+  const res = u.preflightModules({ instanceDir: dir, targetVersion: '2.0.0' }, {
+    moduleLib: moduleLibStub({ ok: true, blocking: [], warnings: [warned], deprecations: [], expired: [], core: '2.0.0' }),
+  });
+  assert.equal(res.ok, true, 'a disabled mismatch must never block the bump');
+  assert.deepEqual(res.warnings.map((w) => w.key), ['stale-catalog-entry']);
+  assert.match(res.note, /1 disabled module\(s\) do NOT/, 'the headline note admits the rot instead of claiming all-clear');
+});
+
+t('preflightModules: with everything healthy the note stays the plain all-clear', () => {
+  const dir = scratchConsumer();
+  mkdirSync(join(dir, 'modules'), { recursive: true });
+  const res = u.preflightModules({ instanceDir: dir, targetVersion: '2.0.0' }, {
+    moduleLib: moduleLibStub({ ok: true, blocking: [], warnings: [], deprecations: [], expired: [], core: '2.0.0' }),
+  });
+  assert.equal(res.note, 'all enabled modules satisfy the target');
+  assert.deepEqual(res.warnings, []);
+});
+
+t('preflightModules: no modules/ dir returns every collection empty (a vanilla consumer)', () => {
+  const dir = scratchConsumer();
+  const res = u.preflightModules({ instanceDir: dir, targetVersion: '2.0.0' });
+  assert.equal(res.ok, true);
+  for (const k of ['blocking', 'warnings', 'deprecations', 'expired']) assert.deepEqual(res[k], [], k);
+});
+
+t('reportModulePreflight: prints the rotted-but-disabled module WITH its maintainer named', () => {
+  const out = [];
+  const mods = {
+    warnings: [{ key: 'stale-catalog-entry', coreVersion: '^1.0.0', maintainer: 'Ada <ada@example.com>', maintenance: { status: 'maintained' } }],
+    deprecations: [], expired: [],
+  };
+  u.reportModulePreflight(mods, '2.0.0', { log: (s) => out.push(s), err: (s) => out.push(s) });
+  const text = out.join('\n');
+  assert.match(text, /stale-catalog-entry/);
+  assert.match(text, /silently fail to mount/);
+  assert.match(text, /maintainer Ada <ada@example\.com>/);
+});
+
+t('reportModulePreflight: calls out a deprecation the core has already passed removeAfter', () => {
+  const out = [];
+  const dep = { key: 'sunset', maintenance: { status: 'deprecated', successor: 'newer', removeAfter: '1.12.0' } };
+  u.reportModulePreflight({ warnings: [], deprecations: [dep], expired: [dep] }, '1.13.0', { log: (s) => out.push(s), err: (s) => out.push(s) });
+  const text = out.join('\n');
+  assert.match(text, /module "sunset" is deprecated/);
+  assert.match(text, /PAST its removeAfter 1\.12\.0/);
+  assert.match(text, /due for removal/);
+});
+
+t('reportModulePreflight: nothing to say prints nothing', () => {
+  const out = [];
+  const lines = u.reportModulePreflight({ warnings: [], deprecations: [], expired: [] }, '2.0.0', { log: (s) => out.push(s), err: (s) => out.push(s) });
+  assert.deepEqual(lines, []);
+  assert.deepEqual(out, []);
+});
+
+t('runUpgrade: a REFUSED bump still reports the non-blocking module findings', async () => {
+  // A refusal is exactly when someone is reading this output, so the warnings must
+  // already have been emitted by the time the blocking check returns.
+  const dir = scratchConsumer();
+  mkdirSync(join(dir, 'modules'), { recursive: true });
+  const out = [];
+  const res = await u.runUpgrade({ to: '2.0.0', instance: dir, force: true, dryRun: true }, {
+    log: (s) => out.push(String(s)),
+    err: (s) => out.push(String(s)),
+    moduleLib: moduleLibStub({
+      ok: false,
+      blocking: [{ key: 'enabled-breaker', coreVersion: '^1.0.0', enabled: true, satisfied: false }],
+      warnings: [{ key: 'stale-catalog-entry', coreVersion: '^1.0.0', maintenance: { status: 'orphaned', note: 'author unreachable' } }],
+      deprecations: [], expired: [], core: '2.0.0',
+    }),
+  });
+  assert.equal(res.ok, false, 'the enabled mismatch still refuses');
+  const text = out.join('\n');
+  assert.match(text, /stale-catalog-entry/, 'the disabled rot is reported even on a refused bump');
+  assert.match(text, /author unreachable/);
+});
+
 await Promise.all(pending);
 console.log(`\nupgrade: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);