@boyingliu01/xp-gate 0.30.1 → 0.30.2

package/bin/xp-gate.js

@@ -350,6 +350,14 @@ const COMMANDS = {
     },
     usage: 'xp-gate retro [--days N] [--all] [--json] [--sprint <id>]'
   },
+  'crap': {
+    description: 'Rank functions by CRAP score (complexity x weak coverage) — advisory, never blocks (#404)',
+    run: subargs => {
+      const { handleCrap } = require('../lib/crap-cli.js');
+      handleCrap(subargs).then(code => process.exit(code));
+    },
+    usage: 'xp-gate crap [--top N] [--threshold N] [--json] [--paths <p...>] [--include-mirrors]'
+  },
   'sprint-init': {
     description: 'Initialize sprint state (single entry point for sprint creation, resolves #366)',
     run: subargs => {

package/gate-3.sh

@@ -179,16 +179,40 @@ else
           GATE_3_STATUS="PASS"
         fi
       else
-      # Parse warning count from the summary table: "Warning cnt   8"
-      # Use anchored grep to avoid matching lizard table headers (e.g. "Rt" column)
-      CC_WARNINGS=$(echo "$CC_OUTPUT" | grep "^Warning cnt" | awk '{print $NF}' | tr -d '[:space:]' | sed 's/[^0-9]//g' || true)
-      CC_WARNINGS=${CC_WARNINGS:-0}
-      
-      if [ "$CC_WARNINGS" -gt 0 ]; then
+      # #543: count from lizard's machine-readable CSV, never its tables.
+      #
+      # The previous parser grepped '^Warning cnt' for a summary row. Two things
+      # made that never match: "Warning cnt" is a column header in the MIDDLE of
+      # a line ("Total nloc  Avg.NLOC  ...  Warning cnt  Fun Rt  nloc Rt"), and
+      # lizard omits the summary block entirely when given explicit file
+      # arguments -- which is how this gate always invokes it. CC_WARNINGS was
+      # therefore always 0 and the flat-threshold path could not block anything.
+      #
+      # --csv has a stable column order (NLOC,CCN,token,PARAM,length,location,
+      # file,name,signature,...), so the verdict comes from the same numbers
+      # lizard uses, independent of version and table formatting. --csv here is
+      # the flat-threshold run; the ratchet branch above builds its own.
+      CC_CSV_FLAT=$("$LIZARD_PATH" --csv -C "$CCN_THRESHOLD" ${CC_FILES_ARGS[@]+"${CC_FILES_ARGS[@]}"} 2>/dev/null || true)
+      CC_WARNINGS=$(printf '%s\n' "$CC_CSV_FLAT" | awk -F, -v t="$CCN_THRESHOLD" '
+        NF > 1 && $2 + 0 > t + 0 { c++ }
+        END { print c + 0 }
+      ')
+      # A lizard that produced no parsable row must not read as "clean". Without
+      # this, a crashing or mis-invoked lizard yields 0 warnings and the gate
+      # reports PASSED on zero analysed functions -- the same silent-success
+      # failure this issue is about.
+      if ! printf '%s\n' "$CC_CSV_FLAT" | awk -F, 'NF > 1 && $2 ~ /^[0-9]+$/ { found = 1; exit }
+                                                 END { exit(found ? 0 : 1) }'; then
+        echo "⚠️  WARN - lizard produced no parsable results; complexity not verified"
+        GATE_3_STATUS="WARN"
+        GATE_3_REASON="lizard_output_unparsable"
+      elif [ "$CC_WARNINGS" -gt 0 ]; then
         echo "$CC_OUTPUT"
         echo ""
         echo "❌ BLOCKED - $CC_WARNINGS functions with CCN > $CCN_THRESHOLD found."
         echo "Refactor high-complexity functions to keep below $CCN_THRESHOLD complexity."
+        GATE_3_STATUS="BLOCK"
+        GATE_3_REASON="ccn_over_threshold"
         exit 1
       else
         echo "✅ PASSED - All functions within complexity threshold ($CCN_THRESHOLD)."

package/hooks/gate-3.sh

@@ -179,16 +179,40 @@ else
           GATE_3_STATUS="PASS"
         fi
       else
-      # Parse warning count from the summary table: "Warning cnt   8"
-      # Use anchored grep to avoid matching lizard table headers (e.g. "Rt" column)
-      CC_WARNINGS=$(echo "$CC_OUTPUT" | grep "^Warning cnt" | awk '{print $NF}' | tr -d '[:space:]' | sed 's/[^0-9]//g' || true)
-      CC_WARNINGS=${CC_WARNINGS:-0}
-      
-      if [ "$CC_WARNINGS" -gt 0 ]; then
+      # #543: count from lizard's machine-readable CSV, never its tables.
+      #
+      # The previous parser grepped '^Warning cnt' for a summary row. Two things
+      # made that never match: "Warning cnt" is a column header in the MIDDLE of
+      # a line ("Total nloc  Avg.NLOC  ...  Warning cnt  Fun Rt  nloc Rt"), and
+      # lizard omits the summary block entirely when given explicit file
+      # arguments -- which is how this gate always invokes it. CC_WARNINGS was
+      # therefore always 0 and the flat-threshold path could not block anything.
+      #
+      # --csv has a stable column order (NLOC,CCN,token,PARAM,length,location,
+      # file,name,signature,...), so the verdict comes from the same numbers
+      # lizard uses, independent of version and table formatting. --csv here is
+      # the flat-threshold run; the ratchet branch above builds its own.
+      CC_CSV_FLAT=$("$LIZARD_PATH" --csv -C "$CCN_THRESHOLD" ${CC_FILES_ARGS[@]+"${CC_FILES_ARGS[@]}"} 2>/dev/null || true)
+      CC_WARNINGS=$(printf '%s\n' "$CC_CSV_FLAT" | awk -F, -v t="$CCN_THRESHOLD" '
+        NF > 1 && $2 + 0 > t + 0 { c++ }
+        END { print c + 0 }
+      ')
+      # A lizard that produced no parsable row must not read as "clean". Without
+      # this, a crashing or mis-invoked lizard yields 0 warnings and the gate
+      # reports PASSED on zero analysed functions -- the same silent-success
+      # failure this issue is about.
+      if ! printf '%s\n' "$CC_CSV_FLAT" | awk -F, 'NF > 1 && $2 ~ /^[0-9]+$/ { found = 1; exit }
+                                                 END { exit(found ? 0 : 1) }'; then
+        echo "⚠️  WARN - lizard produced no parsable results; complexity not verified"
+        GATE_3_STATUS="WARN"
+        GATE_3_REASON="lizard_output_unparsable"
+      elif [ "$CC_WARNINGS" -gt 0 ]; then
         echo "$CC_OUTPUT"
         echo ""
         echo "❌ BLOCKED - $CC_WARNINGS functions with CCN > $CCN_THRESHOLD found."
         echo "Refactor high-complexity functions to keep below $CCN_THRESHOLD complexity."
+        GATE_3_STATUS="BLOCK"
+        GATE_3_REASON="ccn_over_threshold"
         exit 1
       else
         echo "✅ PASSED - All functions within complexity threshold ($CCN_THRESHOLD)."

package/lib/__tests__/crap-cli.test.js

@@ -0,0 +1,76 @@
+/**
+ * @test REQ-404 CRAP advisory CLI
+ * @intent Verify `xp-gate crap` renders a ranking, stays advisory (exit 0 no
+ *         matter what it finds), and refuses to invent a ranking when its
+ *         inputs are missing.
+ * @covers AC-404
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { handleCrap, parseArgs } = require('../crap-cli.js');
+
+function capture(fn) {
+  const logs = [];
+  const errs = [];
+  const origLog = console.log;
+  const origErr = console.error;
+  console.log = (...a) => logs.push(a.join(' '));
+  console.error = (...a) => errs.push(a.join(' '));
+  return fn()
+    .then((code) => ({ code, out: logs.join('\n'), err: errs.join('\n') }))
+    .finally(() => {
+      console.log = origLog;
+      console.error = origErr;
+    });
+}
+
+describe('crap-cli.js - argument parsing', () => {
+  it('defaults to top 20, threshold 6, mirrors excluded', () => {
+    const opts = parseArgs([]);
+    expect(opts.top).toBe(20);
+    expect(opts.threshold).toBe(6);
+    expect(opts.includeMirrors).toBe(false);
+    expect(opts.json).toBe(false);
+  });
+
+  it('parses the documented flags', () => {
+    const opts = parseArgs(['--top', '5', '--threshold', '12', '--json', '--include-mirrors']);
+    expect(opts.top).toBe(5);
+    expect(opts.threshold).toBe(12);
+    expect(opts.json).toBe(true);
+    expect(opts.includeMirrors).toBe(true);
+  });
+
+  it('collects multiple --paths values', () => {
+    expect(parseArgs(['--paths', 'src', 'scripts']).paths).toEqual(['src', 'scripts']);
+  });
+});
+
+describe('crap-cli.js - advisory contract', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'crap-cli-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('prints usage and exits 0 on --help', async () => {
+    const res = await capture(() => handleCrap(['--help']));
+    expect(res.code).toBe(0);
+    expect(res.out).toContain('ADVISORY ONLY');
+  });
+
+  it('refuses to rank when there is no coverage artifact', async () => {
+    // Without coverage every function is unmeasured; printing an empty ranking
+    // would read as "nothing to fix", which is the opposite of the truth.
+    const missing = path.join(tmpDir, 'does-not-exist.json');
+    const res = await capture(() => handleCrap(['--coverage', missing]));
+    expect(res.code).toBe(1);
+    expect(res.err).toContain('No coverage artifact');
+  });
+});

package/lib/__tests__/crap.test.js

@@ -0,0 +1,137 @@
+/**
+ * @test REQ-404 CRAP advisory ranking
+ * @intent Verify the CRAP indicator ranks "complex and weakly tested" functions
+ *         without silently treating missing coverage as either perfect or zero,
+ *         and that it never presents itself as a blocking gate (#404 P1-2).
+ * @covers AC-404
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const {
+  computeCrap,
+  joinCoverage,
+  buildCrapReport,
+  isMirrorPath,
+} = require('../crap.js');
+
+describe('crap.js - CRAP formula', () => {
+  it('computes comp^2 * (1 - cov) + comp', () => {
+    // CCN 10, 50% covered -> 100 * 0.5 + 10 = 60
+    expect(computeCrap(10, 0.5)).toBeCloseTo(60, 5);
+    // CCN 4, fully covered -> 0 + 4 = 4
+    expect(computeCrap(4, 1)).toBeCloseTo(4, 5);
+    // CCN 12, no coverage -> 144 + 12 = 156
+    expect(computeCrap(12, 0)).toBeCloseTo(156, 5);
+  });
+
+  it('returns null when coverage is unknown rather than guessing', () => {
+    // The whole reason this function exists: an unmeasured function must not be
+    // scored as if it were untested (that inflates it to the top of the ranking)
+    // nor as if it were fully tested (that hides it). It is simply unmeasured.
+    expect(computeCrap(10, null)).toBeNull();
+    expect(computeCrap(10, undefined)).toBeNull();
+    expect(computeCrap(10, NaN)).toBeNull();
+  });
+
+  it('clamps out-of-range coverage instead of producing negative scores', () => {
+    // Istanbul occasionally reports slightly out-of-range values; a negative
+    // CRAP would sort below genuinely clean functions and hide a hotspot.
+    expect(computeCrap(5, 1.2)).toBeCloseTo(5, 5);
+    expect(computeCrap(5, -0.1)).toBeCloseTo(30, 5);
+  });
+});
+
+describe('crap.js - coverage joining', () => {
+  it('joins per-file coverage using a repo-relative path', () => {
+    const coverage = new Map([['src/a.ts', 0.5]]);
+    const functions = [{ file: 'src/a.ts', name: 'f', ccn: 10 }];
+    const joined = joinCoverage(functions, coverage);
+    expect(joined).toHaveLength(1);
+    expect(joined[0].cov).toBeCloseTo(0.5, 5);
+    expect(joined[0].crap).toBeCloseTo(60, 5);
+  });
+
+  it('marks functions whose file has no coverage as unmeasured', () => {
+    const coverage = new Map([['src/a.ts', 0.5]]);
+    const functions = [{ file: 'src/never-loaded.ts', name: 'g', ccn: 20 }];
+    const joined = joinCoverage(functions, coverage);
+    expect(joined[0].cov).toBeNull();
+    expect(joined[0].crap).toBeNull();
+  });
+});
+
+describe('crap.js - report', () => {
+  const functions = [
+    { file: 'src/gates/gate-7.ts', name: 'runGate7', ccn: 14, cov: 0 },
+    { file: 'src/gates/ok.ts', name: 'clean', ccn: 3, cov: 1 },
+    { file: 'src/gates/mid.ts', name: 'mid', ccn: 9, cov: 0.8 },
+  ];
+
+  it('ranks by CRAP descending and drops functions below the bar', () => {
+    const report = buildCrapReport(functions, { threshold: 6 });
+    // clean: 9 * 0 + 3 = 3 -> below the bar, excluded
+    // mid:   81 * 0.2 + 9 = 25.2
+    // runGate7: 196 + 14 = 210
+    expect(report.hotspots.map((h) => h.name)).toEqual(['runGate7', 'mid']);
+    expect(report.hotspots[0].crap).toBeCloseTo(210, 5);
+  });
+
+  it('reports how many functions could not be measured', () => {
+    const withUnknown = [
+      ...functions,
+      { file: 'src/gates/never.ts', name: 'nope', ccn: 30, cov: null },
+    ];
+    const report = buildCrapReport(withUnknown, { threshold: 6 });
+    expect(report.unmeasured).toBe(1);
+    expect(report.measured).toBe(3);
+  });
+
+  it('labels itself advisory', () => {
+    const report = buildCrapReport(functions, { threshold: 6 });
+    // A ranking nobody is blocked by must say so; the RFC is explicit that this
+    // navigates refactoring and does not replace security/performance review.
+    expect(report.advisory).toBe(true);
+    expect(report.blocking).toBe(false);
+  });
+
+  it('honours an explicit top-N limit', () => {
+    const report = buildCrapReport(functions, { threshold: 6, top: 1 });
+    expect(report.hotspots).toHaveLength(1);
+  });
+});
+
+describe('crap.js - mirror exclusion', () => {
+  it('recognises the generated npm-package mirror', () => {
+    // Refactoring a mirror is refactoring a copy that prepack overwrites.
+    expect(isMirrorPath('src/npm-package/lib/doctor.js')).toBe(true);
+    expect(isMirrorPath('src/npm-package/principles/config.ts')).toBe(true);
+  });
+
+  it('does not treat real source as a mirror', () => {
+    expect(isMirrorPath('src/gates/gate-7.ts')).toBe(false);
+    expect(isMirrorPath('plugins/qoder/src/index.ts')).toBe(false);
+  });
+
+  it('excludes mirror-tree functions from the ranking by default', () => {
+    // A mirror hotspot outranks everything real (measured: findBodyBrace at
+    // CRAP 4830 for being a big untested generated copy), so the default has to
+    // be exclusion or the ranking is useless out of the box.
+    const mixed = [
+      { file: 'src/npm-package/lib/huge.js', name: 'mirrorFn', ccn: 60, cov: 0 },
+      { file: 'src/gates/real.ts', name: 'realFn', ccn: 10, cov: 0 },
+    ];
+    const report = buildCrapReport(mixed, { threshold: 6 });
+    expect(report.hotspots.map((h) => h.name)).toEqual(['realFn']);
+  });
+
+  it('includes mirrors only when explicitly asked', () => {
+    const mixed = [
+      { file: 'src/npm-package/lib/huge.js', name: 'mirrorFn', ccn: 60, cov: 0 },
+      { file: 'src/gates/real.ts', name: 'realFn', ccn: 10, cov: 0 },
+    ];
+    const report = buildCrapReport(mixed, { threshold: 6, mirrors: true });
+    expect(report.hotspots.map((h) => h.name)).toEqual(['mirrorFn', 'realFn']);
+  });
+});

package/lib/__tests__/retro-gate-m.test.js

@@ -0,0 +1,144 @@
+/**
+ * @test REQ-404 Gate M in retrospective
+ * @intent Verify `xp-gate retro` reports Gate M (mutation) evidence from the
+ *         pre-push journal, and that it distinguishes "never measured" from
+ *         "measured and scored well" instead of printing a healthy average over
+ *         an empty sample (#404 P1-3).
+ *
+ * @covers AC-404
+ */
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const { handleRetro } = require('../retro');
+
+let TMP_DIR;
+let cwdSpy;
+
+beforeAll(() => {
+  TMP_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'retro-gatem-test-'));
+  cwdSpy = vi.spyOn(process, 'cwd').mockReturnValue(TMP_DIR);
+});
+
+afterAll(() => {
+  cwdSpy.mockRestore();
+  fs.rmSync(TMP_DIR, { recursive: true, force: true });
+});
+
+function cleanDir() {
+  for (const sub of ['.xp-gate', '.sprint-state', 'coverage']) {
+    fs.rmSync(path.join(TMP_DIR, sub), { recursive: true, force: true });
+  }
+  fs.rmSync(path.join(TMP_DIR, '.quality-history.jsonl'), { force: true });
+}
+
+/** Write pre-push journals. `runs` is a list of Gate M detail objects. */
+function writeJournals(runs) {
+  const dir = path.join(TMP_DIR, '.xp-gate', 'reports', 'pre-push');
+  fs.mkdirSync(dir, { recursive: true });
+  runs.forEach((gateM, i) => {
+    const stamp = `2026-10-${String(10 + i).padStart(2, '0')}T00:00:00Z`;
+    fs.writeFileSync(
+      path.join(dir, `${stamp.replace(/[:]/g, '-')}.json`),
+      JSON.stringify({
+        timestamp: stamp,
+        trigger: 'pre-push',
+        branch: 'main',
+        commit: `sha${i}`,
+        changed_files: ['src/a.ts'],
+        overall: gateM.status,
+        gates: [{ id: 'M', name: 'Mutation Testing', status: gateM.status, details: gateM.details || {} }],
+        warnings: [],
+        errors: [],
+      })
+    );
+  });
+}
+
+async function runRetro(args = ['--days', '30']) {
+  const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+  const code = await handleRetro(args);
+  const output = logSpy.mock.calls.map((c) => c.join(' ')).join('\n');
+  logSpy.mockRestore();
+  return { code, output };
+}
+
+describe('retro - Gate M evidence (#404)', () => {
+  test('reports skip rate, measured duration and score distribution', async () => {
+    cleanDir();
+    writeJournals([
+      { status: 'PASS', details: { duration_ms: '120000', mutation_score: '75.5', skip_reason: '' } },
+      { status: 'PASS', details: { duration_ms: '180000', mutation_score: '82.1', skip_reason: '' } },
+      { status: 'SKIP', details: { skip_reason: 'stryker_not_installed' } },
+      { status: 'SKIP', details: { skip_reason: 'no_mutable_files' } },
+    ]);
+
+    const { code, output } = await runRetro();
+    expect(code).toBe(0);
+    expect(output).toContain('Gate M');
+    // 2 of 4 skipped
+    expect(output).toContain('50.0%');
+    // Both skip reasons must survive into the report, not be collapsed.
+    expect(output).toContain('stryker_not_installed');
+    expect(output).toContain('no_mutable_files');
+    // score median of [75.5, 82.1] is 82.1 with this sort convention; assert the
+    // scores are present rather than pinning the exact tie-break.
+    expect(output).toMatch(/75\.5|82\.1/);
+  });
+
+  test('says "never measured" rather than reporting a clean 0% average', async () => {
+    cleanDir();
+    // The exact shape of all 68 journals before the #404 fix: SKIP with an empty
+    // details object. An average over zero samples is not a healthy score.
+    writeJournals([
+      { status: 'SKIP', details: {} },
+      { status: 'SKIP', details: {} },
+    ]);
+
+    const { code, output } = await runRetro();
+    expect(code).toBe(0);
+    expect(output).toContain('Gate M');
+    expect(output).toMatch(/no measured|never measured|not measured/i);
+    // A fabricated average over an empty sample is the failure being prevented.
+    expect(output).not.toMatch(/median mutation score.*\d+\.\d+%/i);
+  });
+
+  test('reports no Gate M data at all when there are no journals', async () => {
+    cleanDir();
+    const { code, output } = await runRetro();
+    expect(code).toBe(0);
+    expect(output).toMatch(/no pre-push|no Gate M/i);
+  });
+
+  test('counts a TIMEOUT separately from a SKIP', async () => {
+    cleanDir();
+    writeJournals([
+      { status: 'TIMEOUT', details: { skip_reason: 'exceeded_budget' } },
+      { status: 'SKIP', details: { skip_reason: 'no_mutable_files' } },
+    ]);
+
+    const { output } = await runRetro();
+    // Timeouts are a distinct failure mode: lumping them into SKIP hides a
+    // gate that started work and could not finish.
+    expect(output).toMatch(/TIMEOUT|timeout/i);
+  });
+
+  test('counts BLOCKED, which is the spelling the journals actually write', async () => {
+    cleanDir();
+    // Measured against this repo's real journals: 62 SKIP, 5 BLOCKED, 1 PASS.
+    // An implementation that only matched "BLOCK" reported the 5 real mutation
+    // blocks as zero -- precisely the silent-success failure #404 is about.
+    writeJournals([
+      { status: 'BLOCKED', details: { skip_reason: 'mutation_score_below_threshold' } },
+      { status: 'BLOCKED', details: {} },
+      { status: 'SKIP', details: { skip_reason: 'no_mutable_files' } },
+      { status: 'PASS', details: { mutation_score: '71.0' } },
+    ]);
+
+    const { output } = await runRetro();
+    expect(output).toContain('BLOCK 2');
+    expect(output).toContain('SKIP 1');
+    expect(output).toContain('PASS 1');
+  });
+});

package/lib/crap-cli.js

@@ -0,0 +1,191 @@
+'use strict';
+
+/**
+ * `xp-gate crap` — advisory CRAP hotspot ranking (#404 P1-2).
+ *
+ * Prints the functions whose CRAP score is at or above the bar, worst first.
+ * This is a NAVIGATION aid: it exits 0 whatever it finds, because the indicator
+ * depends on coverage that 21.8% of this repo's source files do not have (see
+ * crap.js). A ranking that cannot measure a fifth of its population must not
+ * be allowed to fail a build.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const {
+  buildCrapReport,
+  joinCoverage,
+  readFileCoverage,
+  parseLizardCsv,
+} = require('./crap.js');
+
+const USAGE = `Usage: xp-gate crap [options]
+
+Rank functions by CRAP score = CCN^2 * (1 - coverage) + CCN, worst first.
+ADVISORY ONLY: never blocks, always exits 0.
+
+Options:
+  --top N            show at most N hotspots (default 20)
+  --threshold N      CRAP bar; functions at or above it are listed (default 6)
+  --json             machine-readable output
+  --coverage <file>  istanbul coverage-final.json (default coverage/coverage-final.json)
+  --paths <p...>     directories to scan (default src)
+  --include-mirrors  also rank src/npm-package/** (overwritten at publish)
+  -h, --help         show this help
+
+Unmeasured = the function's file was never loaded by any test, so coverage is
+unknown. Those functions are counted, not scored. Treating them as 0% would put
+every untested file at the top of the ranking; treating them as 100% would hide
+them.
+`;
+
+function parseArgs(argv) {
+  const opts = {
+    top: 20,
+    threshold: 6,
+    json: false,
+    coverage: path.join(process.cwd(), 'coverage', 'coverage-final.json'),
+    paths: ['src'],
+    includeMirrors: false,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    switch (arg) {
+      case '--top':
+        opts.top = Number(argv[++i]);
+        break;
+      case '--threshold':
+        opts.threshold = Number(argv[++i]);
+        break;
+      case '--json':
+        opts.json = true;
+        break;
+      case '--coverage':
+        opts.coverage = argv[++i];
+        break;
+      case '--include-mirrors':
+        opts.includeMirrors = true;
+        break;
+      case '--paths': {
+        opts.paths = [];
+        while (i + 1 < argv.length && !argv[i + 1].startsWith('-')) {
+          opts.paths.push(argv[++i]);
+        }
+        break;
+      }
+      case '-h':
+      case '--help':
+        opts.help = true;
+        break;
+      default:
+        break;
+    }
+  }
+  return opts;
+}
+
+/** Run lizard and return its CSV. Missing lizard is not an error for a
+ *  navigation command: the caller reports that it could not measure. */
+function runLizard(paths) {
+  try {
+    return execFileSync('lizard', ['--csv', '-C', '99999', ...paths], {
+      encoding: 'utf8',
+      maxBuffer: 64 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch (err) {
+    // lizard exits non-zero when it cannot scan everything; its stdout is still
+    // usable. Anything else (ENOENT) means no data at all.
+    if (err && typeof err.stdout === 'string' && err.stdout.length) return err.stdout;
+    return null;
+  }
+}
+
+function formatRow(hotspot) {
+  const crap = hotspot.crap.toFixed(1).padStart(8);
+  const ccn = String(hotspot.ccn).padStart(4);
+  const cov = `${Math.round(hotspot.cov * 100)}%`.padStart(4);
+  return `  ${crap}  CCN ${ccn}  cov ${cov}  ${hotspot.file}  ${hotspot.name}`;
+}
+
+function render(report, opts) {
+  const lines = [];
+  lines.push('━━━ CRAP hotspot ranking (advisory, never blocks) ━━━');
+
+  if (!report.measured && !report.unmeasured) {
+    lines.push('');
+    lines.push('No functions found. Check that lizard is installed and --paths points at real code:');
+    lines.push(`  lizard --csv -C 99999 ${opts.paths.join(' ')}`);
+    return lines.join('\n');
+  }
+
+  lines.push('');
+  lines.push(
+    `measured ${report.measured} functions, ${report.unmeasured} unmeasured (no coverage for their file)`
+  );
+  lines.push(`CRAP >= ${report.threshold}: ${report.hotspots.length} shown`);
+
+  if (!report.hotspots.length) {
+    lines.push('');
+    lines.push(`✅ Nothing at or above CRAP ${report.threshold}.`);
+    return lines.join('\n');
+  }
+
+  lines.push('');
+  lines.push('  CRAP      complexity coverage  location');
+  const dash = '  ' + '─'.repeat(74);
+  lines.push(dash);
+  for (const hotspot of report.hotspots) lines.push(formatRow(hotspot));
+  lines.push(dash);
+  lines.push('');
+  lines.push('Navigation aid: pick from the top. This does not replace security,');
+  lines.push('performance or architecture review, and score-chasing is not a goal.');
+  return lines.join('\n');
+}
+
+async function handleCrap(argv) {
+  const opts = parseArgs(argv);
+
+  if (opts.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const csv = runLizard(opts.paths);
+  if (csv === null) {
+    console.error('✗ Could not run lizard. Install it with: pip install --user lizard');
+    return 1;
+  }
+
+  if (!fs.existsSync(opts.coverage)) {
+    console.error(`✗ No coverage artifact at ${opts.coverage}`);
+    console.error('  Run the test suite with coverage first: npx vitest run --coverage');
+    console.error('  (Without it every function is unmeasured, which is not a ranking.)');
+    return 1;
+  }
+
+  const functions = parseLizardCsv(csv);
+  const coverage = readFileCoverage(opts.coverage);
+  const joined = joinCoverage(functions, coverage);
+
+  const report = buildCrapReport(joined, {
+    threshold: opts.threshold,
+    top: opts.top,
+    mirrors: opts.includeMirrors,
+  });
+
+  if (opts.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return 0;
+  }
+
+  console.log(render(report, opts));
+  // Advisory by construction: the ranking never changes the exit code.
+  return 0;
+}
+
+module.exports = { handleCrap, parseArgs, render, runLizard };