Print the analysis as JSON with --json (and fix two defects it exposed)

[sudo97]

Charlie could only report through an HTML file. charlie --json now prints the analysis to stdout so it can be read in a terminal — or by an agent running Charlie against its own codebase.

charlie --json                 # prints the analysis, writes no HTML
charlie --json /path/to/repo   # path may precede or follow the flag
charlie --json > out.json      # stdout is JSON only; progress goes to stderr
charlie --json --all           # no limits

Two keys, hotspots and coupling, passed through from the existing Core types, 2-space indented. Bounded by default — the full analysis is 8.5 MB and ~2.2M tokens on a 518-file repo, which defeats the purpose — via percentile 0.95, a floor of 30 entries, and at most 10 partners per file. That gives 53 KB on the same repo. --all removes every bound.

Spec: 03-spec.md · Decisions: 02-decisions.md · Evidence: 05-verification.md

Two defects this work exposed, both pre-existing

Neither was planned. Both were found by runtime verification and fixed with the driver's agreement.

Charlie was silently dropping commits. produceGitLog returned a different number of commits on identical runs, depending on how the OS split git's stdout. Against ground truth: 31 or 30 of 32 here; 393 or 387 against a true 420 on a 518-file repo — ~7% of its history. Two causes: buffer.split('\n\n') destructured only two elements and discarded the rest, and onClose never drained the trailing buffer while git log --pretty=format: emits no trailing separator.

Every metric Charlie has ever produced — HTML report included — was computed from a truncated log. This repository's own hotspot count goes from 14 to 21. Now exact and deterministic:

git log says 34     parser 10x 34
git log says 420    parser 10x 420
git log says 18,492 parser 10x 18,492

The buffer draining was deleted rather than patched: a separator is just a blank line, so the parser walks lines and both defects become unrepresentable. It moved to the Core, which is what the existing FIXME on that function asked for, so it now sits under the 100%-coverage and 95%-mutation gates.

coupling() was quadratic. It re-scanned all 1,211,043 pairs once per SOC file — 8.2 billion comparisons, 32.5 s, 77% of a 44 s run. Indexed into a Map in one pass: 165 ms, 184x, byte-identical output on three repos.

This was only ever called by data-loader.ts before, which means the HTML report has always frozen for ~30 s on load for a repo this size, in the browser, with no progress indication.

sirvoy-project   44,254 ms -> 13,303 ms      (git log is now 76% of the run)
  couplingAnalysis  33,901 ms -> 2,719 ms

Verification

npm run verify green: 137 tests, Core coverage 100% statements/functions/lines and 97.91% branches, whole-Core mutation 97.66%, 0 clones, no dependency violations. Every new or changed Core file is at 100% mutation except coupled-pairs.ts at 95.08%.

Each commit compiles and tests green standalone (96 -> 100 -> 137 tests), so bisect works.

Things to push back on

• socPercentile was deleted. The driver chose it as the bounding mechanism, and its dependency on the new shared percentile.ts made soc.ts less stable than coupling.ts, which depends on it — an SDP violation. The arithmetic is still shared rather than duplicated, which was the point; the named wrapper had no caller before or after.
• The bounds grow the wrong way at scale. With a floor of 30, the floor does the work on ordinary repos; above ~600 files the percentile governs and grows output as the repo grows. Chosen deliberately over a fixed top-N. Lesson 9.
• Excluding large commits was refused. 11 commits touch >200 files (max 816) and generate 70% of all pair-occurrences. Excluding them cuts time 2,470 -> 898 ms but changes 135 of 339 reported coupling files, non-monotonically. That is a methodology decision needing its own spec, not an optimisation. Lesson 7.

Owed before merge

• Click the Coupling tab in a generated report. The frontend has no test coverage and I could not drive a browser, so that check is the computation run in Node against the report's own embedded log plus a successful build. Given the coupling() fix, this also confirms large-repo report load is now fast.

Lessons nominated

06-lessons.md has nine. Please decide on these before the folder is erased on merge:

1. Charlie's prior output was wrong and anyone who acted on it should know. No test can tell a user that — it may want a release note.
2. UTF-8 corruption at chunk boundaries, measured and deliberately deferred: a multi-byte character straddling a 64 KB boundary is destroyed, turning a non-ASCII author into a phantom second contributor. 0.0051% continuation bytes over 345 boundaries gives 1.7% per run on the worst repo available, and 0 observed in 10 real runs. The FIXME now carries the numbers.
3. Touching a Core file below 95% mutation fails CI on a score that predates your change, because CI mutates only changed files. coupled-pairs.ts was already at 94.44%. Also: a mutant that cannot change observable output is a signal to delete the code, not to write a cleverer test.

Also worth noting: I branched from a stale main and reported check:deps as passing when that base had 6 violations — all already fixed by PR #3, which had merged that morning. Corrected by resetting onto origin/main; lesson 4 is "git fetch before branching".

🤖 Generated with Claude Code