config-audit/tests/lib/campaign-ledger.test.mjs

import { describe, it, after } from 'node:test';
import assert from 'node:assert/strict';
import { join } from 'node:path';
import { mkdtemp, rm, readFile } from 'node:fs/promises';
import { tmpdir, homedir } from 'node:os';
import {
  CAMPAIGN_SCHEMA_VERSION,
  STATUSES,
  SEVERITY_WEIGHTS,
  createLedger,
  addRepo,
  setRepoStatus,
  setSharedGlobal,
  setRepoTokens,
  rollUp,
  buildBacklog,
  validateLedger,
  defaultLedgerPath,
  loadLedger,
  saveLedger,
} from '../../scanners/lib/campaign-ledger.mjs';

const NOW = '2026-06-22';
const LATER = '2026-06-23';

/**
 * Build a load-pattern summary in the exact shape manifest's `summarizeByLoadPattern`
 * emits (and the shape B2b will store): one {tokens,count} bucket per load pattern.
 */
const tokSummary = (always, onDemand = 0, external = 0, unknown = 0) => ({
  always: { tokens: always, count: 1 },
  onDemand: { tokens: onDemand, count: 1 },
  external: { tokens: external, count: 1 },
  unknown: { tokens: unknown, count: 1 },
});

describe('constants', () => {
  it('schema version is 1', () => {
    assert.equal(CAMPAIGN_SCHEMA_VERSION, 1);
  });
  it('STATUSES is the frozen four-step lifecycle', () => {
    assert.deepEqual([...STATUSES], ['pending', 'audited', 'planned', 'implemented']);
    assert.ok(Object.isFrozen(STATUSES));
  });
});

describe('createLedger', () => {
  it('builds an empty, versioned ledger stamped with `now`', () => {
    const l = createLedger({ now: NOW });
    assert.deepEqual(l, {
      schemaVersion: 1,
      createdDate: NOW,
      updatedDate: NOW,
      repos: [],
    });
  });
  it('throws on a missing/invalid now', () => {
    assert.throws(() => createLedger({}), /now/);
    assert.throws(() => createLedger({ now: 'June 22' }), /now/);
  });
});

describe('addRepo', () => {
  it('adds a pending repo with name, resolved path, and stamps', () => {
    const l = addRepo(createLedger({ now: NOW }), { path: '/Users/ktg/repos/foo', name: 'foo' }, { now: NOW });
    assert.equal(l.repos.length, 1);
    assert.deepEqual(l.repos[0], {
      path: '/Users/ktg/repos/foo',
      name: 'foo',
      status: 'pending',
      sessionId: null,
      findingsBySeverity: null,
      tokens: null,
      updatedDate: NOW,
    });
  });

  it('normalizes the path (trailing slash, .. segments)', () => {
    const l = addRepo(createLedger({ now: NOW }), { path: '/Users/ktg/repos/foo/../foo/', name: 'foo' }, { now: NOW });
    assert.equal(l.repos[0].path, '/Users/ktg/repos/foo');
  });

  it('is idempotent on path — no duplicate, status preserved', () => {
    let l = addRepo(createLedger({ now: NOW }), { path: '/r/foo', name: 'foo' }, { now: NOW });
    l = setRepoStatus(l, '/r/foo', 'audited', { now: NOW });
    l = addRepo(l, { path: '/r/foo', name: 'foo' }, { now: LATER });
    assert.equal(l.repos.length, 1);
    assert.equal(l.repos[0].status, 'audited'); // progress not reset
  });

  it('bumps ledger.updatedDate but not createdDate', () => {
    const base = createLedger({ now: NOW });
    const l = addRepo(base, { path: '/r/foo', name: 'foo' }, { now: LATER });
    assert.equal(l.createdDate, NOW);
    assert.equal(l.updatedDate, LATER);
  });

  it('does not mutate the input ledger', () => {
    const base = createLedger({ now: NOW });
    addRepo(base, { path: '/r/foo', name: 'foo' }, { now: NOW });
    assert.equal(base.repos.length, 0);
  });

  it('throws on a missing path', () => {
    assert.throws(() => addRepo(createLedger({ now: NOW }), { name: 'foo' }, { now: NOW }), /path/);
  });
});

describe('setRepoStatus', () => {
  const seed = () => addRepo(createLedger({ now: NOW }), { path: '/r/foo', name: 'foo' }, { now: NOW });

  it('updates status and stamps the repo + ledger', () => {
    const l = setRepoStatus(seed(), '/r/foo', 'audited', { now: LATER });
    assert.equal(l.repos[0].status, 'audited');
    assert.equal(l.repos[0].updatedDate, LATER);
    assert.equal(l.updatedDate, LATER);
  });

  it('attaches findingsBySeverity and sessionId when provided', () => {
    const findings = { critical: 0, high: 2, medium: 5, low: 3 };
    const l = setRepoStatus(seed(), '/r/foo', 'audited', { now: NOW, findingsBySeverity: findings, sessionId: '20260404_162210' });
    assert.deepEqual(l.repos[0].findingsBySeverity, findings);
    assert.equal(l.repos[0].sessionId, '20260404_162210');
  });

  it('resolves the path the same way addRepo does', () => {
    const l = setRepoStatus(seed(), '/r/foo/', 'planned', { now: NOW });
    assert.equal(l.repos[0].status, 'planned');
  });

  it('throws on an invalid status', () => {
    assert.throws(() => setRepoStatus(seed(), '/r/foo', 'done', { now: NOW }), /status/);
  });

  it('throws on an unknown path', () => {
    assert.throws(() => setRepoStatus(seed(), '/r/bar', 'audited', { now: NOW }), /not in the ledger|unknown/i);
  });

  it('does not mutate the input ledger', () => {
    const l = seed();
    setRepoStatus(l, '/r/foo', 'audited', { now: NOW });
    assert.equal(l.repos[0].status, 'pending');
  });
});

describe('rollUp', () => {
  it('returns all-zero buckets for an empty ledger', () => {
    const r = rollUp(createLedger({ now: NOW }));
    assert.equal(r.totalRepos, 0);
    assert.deepEqual(r.byStatus, { pending: 0, audited: 0, planned: 0, implemented: 0 });
    assert.deepEqual(r.bySeverity, { critical: 0, high: 0, medium: 0, low: 0 });
    assert.equal(r.reposWithFindings, 0);
  });

  it('counts statuses and aggregates severity machine-wide', () => {
    let l = createLedger({ now: NOW });
    l = addRepo(l, { path: '/r/a', name: 'a' }, { now: NOW });
    l = addRepo(l, { path: '/r/b', name: 'b' }, { now: NOW });
    l = addRepo(l, { path: '/r/c', name: 'c' }, { now: NOW });
    l = setRepoStatus(l, '/r/a', 'audited', { now: NOW, findingsBySeverity: { critical: 1, high: 2, medium: 0, low: 4 } });
    l = setRepoStatus(l, '/r/b', 'implemented', { now: NOW, findingsBySeverity: { critical: 0, high: 1, medium: 3, low: 0 } });
    // c stays pending, no findings

    const r = rollUp(l);
    assert.equal(r.totalRepos, 3);
    assert.deepEqual(r.byStatus, { pending: 1, audited: 1, planned: 0, implemented: 1 });
    assert.deepEqual(r.bySeverity, { critical: 1, high: 3, medium: 3, low: 4 });
    assert.equal(r.reposWithFindings, 2);
  });
});

describe('machine-wide token roll-up (B2a)', () => {
  it('addRepo seeds a null tokens field (mirrors findingsBySeverity)', () => {
    const l = addRepo(createLedger({ now: NOW }), { path: '/r/a', name: 'a' }, { now: NOW });
    assert.equal(l.repos[0].tokens, null);
  });

  it('setSharedGlobal stores the shared layer at the ledger root, immutably + stamps', () => {
    const l0 = createLedger({ now: NOW });
    const l1 = setSharedGlobal(l0, tokSummary(1000, 50, 7), { now: LATER });
    assert.deepEqual(l1.sharedGlobal, tokSummary(1000, 50, 7));
    assert.equal(l1.updatedDate, LATER);
    // immutable: original untouched, no sharedGlobal leaked onto it
    assert.equal(l0.sharedGlobal, undefined);
    assert.equal(l0.updatedDate, NOW);
  });

  it('setRepoTokens attaches per-repo tokens, immutably + stamps', () => {
    let l = addRepo(createLedger({ now: NOW }), { path: '/r/a', name: 'a' }, { now: NOW });
    const before = l;
    l = setRepoTokens(l, '/r/a', tokSummary(120), { now: LATER });
    assert.deepEqual(l.repos[0].tokens, tokSummary(120));
    assert.equal(l.repos[0].updatedDate, LATER);
    assert.equal(l.updatedDate, LATER);
    assert.equal(before.repos[0].tokens, null); // input ledger not mutated
  });

  it('setRepoTokens throws when the repo is not tracked', () => {
    const l = createLedger({ now: NOW });
    assert.throws(() => setRepoTokens(l, '/r/missing', tokSummary(1), { now: NOW }), /not in the ledger/);
  });

  it('rollUp returns an all-zero token aggregate for a fresh ledger', () => {
    const r = rollUp(createLedger({ now: NOW }));
    assert.deepEqual(r.tokens, {
      sharedGlobal: { always: 0, onDemand: 0, external: 0, unknown: 0 },
      perRepoDelta: { always: 0, onDemand: 0, external: 0, unknown: 0 },
      machineWide: { always: 0, onDemand: 0, external: 0, unknown: 0 },
      reposWithTokens: 0,
      byRepo: [],
    });
  });

  it('counts the shared-global layer ONCE, not per repo (double-count regression guard)', () => {
    let l = createLedger({ now: NOW });
    l = setSharedGlobal(l, tokSummary(1000), { now: NOW }); // shared always-loaded = 1000
    for (const name of ['a', 'b', 'c']) {
      l = addRepo(l, { path: `/r/${name}`, name }, { now: NOW });
      l = setRepoTokens(l, `/r/${name}`, tokSummary(100), { now: NOW }); // each per-repo delta = 100
    }
    const t = rollUp(l).tokens;
    assert.equal(t.sharedGlobal.always, 1000, 'shared layer stored once');
    assert.equal(t.perRepoDelta.always, 300, 'sum of three per-repo deltas');
    // THE invariant: shared layer counted ONCE (1000 + 300), NOT once per repo (3*1000 + 300)
    assert.equal(t.machineWide.always, 1300);
    assert.equal(t.reposWithTokens, 3);
  });

  it('ranks byRepo DESC by always-tokens with a deterministic name tie-break', () => {
    let l = createLedger({ now: NOW });
    // deltas out of order + a tie at 100 to exercise the name tie-break
    const spec = [['a', 100], ['z', 300], ['m', 100], ['q', 50]];
    for (const [name, always] of spec) {
      l = addRepo(l, { path: `/r/${name}`, name }, { now: NOW });
      l = setRepoTokens(l, `/r/${name}`, tokSummary(always), { now: NOW });
    }
    const byRepo = rollUp(l).tokens.byRepo;
    assert.deepEqual(byRepo.map((r) => r.name), ['z', 'a', 'm', 'q']);
    assert.deepEqual(byRepo[0], { name: 'z', path: '/r/z', always: 300, onDemand: 0, external: 0 });
  });

  it('tolerates old ledgers: no sharedGlobal + repos without tokens → all zero', () => {
    let l = createLedger({ now: NOW });
    l = addRepo(l, { path: '/r/a', name: 'a' }, { now: NOW }); // no tokens set
    const t = rollUp(l).tokens;
    assert.equal(t.machineWide.always, 0);
    assert.equal(t.reposWithTokens, 0);
    assert.deepEqual(t.byRepo, []);
  });
});

describe('buildBacklog', () => {
  // Seed a ledger from a compact spec. A repo with `status` (and optional `findings`) is
  // transitioned; a bare repo stays `pending` with null findings.
  function ledgerWith(specs) {
    let l = createLedger({ now: NOW });
    for (const s of specs) {
      l = addRepo(l, { path: s.path, name: s.name }, { now: NOW });
      if (s.status) {
        l = setRepoStatus(l, s.path, s.status, {
          now: NOW,
          findingsBySeverity: s.findings,
          sessionId: s.sessionId,
        });
      }
    }
    return l;
  }

  it('SEVERITY_WEIGHTS is the frozen order-of-magnitude weighting', () => {
    assert.deepEqual({ ...SEVERITY_WEIGHTS }, { critical: 1000, high: 100, medium: 10, low: 1 });
    assert.ok(Object.isFrozen(SEVERITY_WEIGHTS));
  });

  it('returns [] for an empty ledger', () => {
    assert.deepEqual(buildBacklog(createLedger({ now: NOW })), []);
  });

  it('excludes implemented, pending, and zero-finding repos', () => {
    const l = ledgerWith([
      { path: '/r/done', name: 'done', status: 'implemented', findings: { critical: 5, high: 0, medium: 0, low: 0 } },
      { path: '/r/pend', name: 'pend' }, // pending, no findings
      { path: '/r/clean', name: 'clean', status: 'audited', findings: { critical: 0, high: 0, medium: 0, low: 0 } },
    ]);
    assert.deepEqual(buildBacklog(l), []);
  });

  it('includes audited and planned repos that still have findings', () => {
    const l = ledgerWith([
      { path: '/r/a', name: 'a', status: 'audited', findings: { critical: 0, high: 1, medium: 0, low: 0 } },
      { path: '/r/p', name: 'p', status: 'planned', findings: { critical: 0, high: 0, medium: 2, low: 0 } },
    ]);
    const names = buildBacklog(l).map((i) => i.name).sort();
    assert.deepEqual(names, ['a', 'p']);
  });

  it('ranks by severity (critical outranks high outranks low) and assigns rank 1..n', () => {
    const l = ledgerWith([
      { path: '/r/low', name: 'low', status: 'audited', findings: { critical: 0, high: 0, medium: 0, low: 9 } },
      { path: '/r/crit', name: 'crit', status: 'audited', findings: { critical: 1, high: 0, medium: 0, low: 0 } },
      { path: '/r/high', name: 'high', status: 'planned', findings: { critical: 0, high: 5, medium: 0, low: 0 } },
    ]);
    const backlog = buildBacklog(l);
    assert.deepEqual(backlog.map((i) => i.name), ['crit', 'high', 'low']);
    assert.deepEqual(backlog.map((i) => i.rank), [1, 2, 3]);
  });

  it('computes weightedScore and totalFindings, normalizing missing severity keys to 0', () => {
    const l = ledgerWith([
      { path: '/r/x', name: 'x', status: 'audited', findings: { high: 2 } }, // critical/medium/low missing
    ]);
    const [item] = buildBacklog(l);
    assert.deepEqual(item.findingsBySeverity, { critical: 0, high: 2, medium: 0, low: 0 });
    assert.equal(item.totalFindings, 2);
    assert.equal(item.weightedScore, 200);
  });

  it('breaks a weightedScore tie by critical count, then by name', () => {
    const l = ledgerWith([
      // both score 1000: 10 high vs 1 critical → critical wins the tie
      { path: '/r/tenHigh', name: 'tenHigh', status: 'audited', findings: { critical: 0, high: 10, medium: 0, low: 0 } },
      { path: '/r/oneCrit', name: 'oneCrit', status: 'audited', findings: { critical: 1, high: 0, medium: 0, low: 0 } },
    ]);
    assert.deepEqual(buildBacklog(l).map((i) => i.name), ['oneCrit', 'tenHigh']);

    // fully identical findings → final tie-break is name (ascending)
    const l2 = ledgerWith([
      { path: '/r/zebra', name: 'zebra', status: 'audited', findings: { critical: 0, high: 1, medium: 0, low: 0 } },
      { path: '/r/alpha', name: 'alpha', status: 'audited', findings: { critical: 0, high: 1, medium: 0, low: 0 } },
    ]);
    assert.deepEqual(buildBacklog(l2).map((i) => i.name), ['alpha', 'zebra']);
  });

  it('carries per-repo provenance on each item', () => {
    const l = ledgerWith([
      { path: '/r/a', name: 'a', status: 'audited', findings: { critical: 1, high: 0, medium: 0, low: 0 }, sessionId: '20260622_120000' },
    ]);
    const [item] = buildBacklog(l);
    assert.equal(item.path, '/r/a');
    assert.equal(item.name, 'a');
    assert.equal(item.status, 'audited');
    assert.equal(item.sessionId, '20260622_120000');
  });

  it('does not mutate the input ledger', () => {
    const l = ledgerWith([
      { path: '/r/a', name: 'a', status: 'audited', findings: { critical: 1, high: 0, medium: 0, low: 0 } },
    ]);
    const snapshot = JSON.stringify(l);
    buildBacklog(l);
    assert.equal(JSON.stringify(l), snapshot);
  });
});

describe('validateLedger', () => {
  const good = () => setRepoStatus(
    addRepo(createLedger({ now: NOW }), { path: '/r/foo', name: 'foo' }, { now: NOW }),
    '/r/foo', 'audited', { now: NOW, findingsBySeverity: { critical: 0, high: 0, medium: 1, low: 0 } },
  );

  it('accepts a well-formed ledger', () => {
    const res = validateLedger(good());
    assert.equal(res.valid, true, res.errors.join('; '));
    assert.deepEqual(res.errors, []);
  });

  it('rejects a non-object', () => {
    assert.equal(validateLedger(null).valid, false);
    assert.equal(validateLedger([]).valid, false);
  });

  it('rejects a bad schemaVersion', () => {
    const l = { ...good(), schemaVersion: '1' };
    assert.equal(validateLedger(l).valid, false);
  });

  it('rejects repos that is not an array', () => {
    const l = { ...good(), repos: {} };
    assert.equal(validateLedger(l).valid, false);
  });

  it('rejects a repo missing a path', () => {
    const l = good();
    l.repos = [{ ...l.repos[0], path: undefined }];
    assert.equal(validateLedger(l).valid, false);
  });

  it('rejects a repo with an out-of-enum status', () => {
    const l = good();
    l.repos = [{ ...l.repos[0], status: 'done' }];
    assert.equal(validateLedger(l).valid, false);
  });

  it('rejects duplicate repo paths', () => {
    const l = good();
    l.repos = [l.repos[0], { ...l.repos[0] }];
    assert.equal(validateLedger(l).valid, false);
  });
});

describe('persistence (IO)', () => {
  it('defaultLedgerPath lives under ~/.claude/config-audit (survives uninstall)', () => {
    const p = defaultLedgerPath();
    assert.equal(p, join(homedir(), '.claude', 'config-audit', 'campaign-ledger.json'));
  });

  it('round-trips through save/load and creates parent dirs', async () => {
    const dir = await mkdtemp(join(tmpdir(), 'ca-ledger-'));
    after(() => rm(dir, { recursive: true, force: true }));
    const file = join(dir, 'nested', 'campaign-ledger.json');
    const l = good();
    function good() {
      return addRepo(createLedger({ now: NOW }), { path: '/r/foo', name: 'foo' }, { now: NOW });
    }
    await saveLedger(file, l);
    const loaded = await loadLedger(file);
    assert.deepEqual(loaded, l);
    // human-readable JSON on disk
    const raw = await readFile(file, 'utf8');
    assert.match(raw, /\n/);
  });

  it('loadLedger returns null for a missing file (graceful first run)', async () => {
    const dir = await mkdtemp(join(tmpdir(), 'ca-ledger-'));
    after(() => rm(dir, { recursive: true, force: true }));
    const loaded = await loadLedger(join(dir, 'nope.json'));
    assert.equal(loaded, null);
  });
});