@christianmorup/review-intent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christian Mørup
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,236 @@
+# review-intent
+
+A CLI that renders the diff between your current branch and `main` as an
+**intent-annotated** HTML review page — opened in your browser — with mermaid
+class & sequence diagrams.
+
+It exists to fix shallow PR review: a diff shows *what* changed but erases *why*.
+`review-intent` puts the agent's stated intent **side-by-side** with each change,
+so a reviewer adjudicates decisions instead of skimming lines.
+
+## How it works
+
+The CLI is a **pure renderer**. It does two things:
+
+1. Runs `git diff <base>...HEAD` itself (PR-style, merge-base diff).
+2. Reads an **agent-authored artifact** (`./.review/intent.json`) for the intent
+   prose and the mermaid diagram sources.
+
+It joins them and emits one self-contained `review.html`, then opens it. No LLM
+call, no API key, no token cost per run. The agent that *made* the changes is
+responsible for writing the artifact.
+
+## Usage
+
+Run it without installing:
+
+```sh
+npx @christianmorup/review-intent    # diff HEAD vs main, read ./.review/intent.json, open browser
+```
+
+Or install it globally:
+
+```sh
+npm install -g @christianmorup/review-intent
+review-intent
+```
+
+From a clone (development):
+
+```sh
+npm install
+npm run build
+node dist/cli.js              # diff HEAD vs main, read ./.review/intent.json, open browser
+```
+
+Options:
+
+| Flag | Default | Meaning |
+|------|---------|---------|
+| `--base <ref>` | `main`, else `master` | Base branch to diff against |
+| `--artifact <path>` | `.review/intent.json` | Intent artifact location |
+| `--out <path>` | OS temp file | Where to write the HTML |
+| `--no-open` | (opens) | Write the file but don't launch the browser |
+| `--allow-gaps` | (off) | Render a draft even if intent is incomplete; gaps render as red markers |
+
+## Blast-radius summary
+
+The top of the page carries a **blast-radius** block — the part that earns the
+tool its keep — with three parts that deliberately pit *claimed* against
+*measured*:
+
+1. **Surface-area scorecard** *(measured, CLI-computed from the diff)* — files/
+   hunks/±lines, test-vs-code file *and line* counts, net line delta,
+   hunks-per-file concentration, new-file count, file-level reach fan-in, intent
+   coverage (files & hunks annotated), diagram coverage, the single most-churned
+   file, a count of debt/debug markers introduced (`TODO`/`FIXME`/`console.log`/
+   `debugger`), a noise-file count (lockfiles, generated, build output,
+   binaries), a **red badge when code changed but no tests did**, sensitive-path
+   flags (`auth`, `*.bicep`, ADO pipelines, app config, secrets/Key Vault,
+   `Dockerfile`, dependency manifests), and a churn flag. Objective and
+   un-gameable.
+2. **Risk ledger** *(claimed, agent-authored)* — `assumption → if false → how
+   you'd know`. If absent, an honesty nudge appears instead of a blank.
+3. **Reach graph** *(measured, CLI-computed)* — a mermaid flowchart of repo files
+   that import the changed files. Heuristic (import/require/from scan), labelled
+   as such; bounded, and any truncation is shown, never silent.
+
+The scorecard sitting next to the ledger is the point: if the agent claims "low
+risk" while the scorecard flags `touches auth/, 0 tests`, the contradiction is
+visible at a glance.
+
+## Visual summary
+
+Below the blast radius is a **visual summary** — five charts rendered as pure,
+self-contained inline SVG (no charting dependency, deterministic output):
+
+1. **Diff mass** — diverging add/remove bars per file, sorted by churn, coloured
+   by category (test/code/noise) with a green/red dot for intent present/missing.
+2. **Change treemap** — rectangles sized by ± lines, coloured by top-level
+   directory; files with no intent get a red outline.
+3. **Intent-coverage rings** — donut gauges for the share of files and hunks
+   that carry agent rationale (the completeness contract, visualized).
+4. **Reach ripple** — the reach graph as concentric rings: changed files at the
+   centre, importers rippling outward.
+5. **Honesty quadrant** — the signature view: measured *blast radius* (churn +
+   reach) on the x-axis against claimed *candor* (intent coverage + declared
+   risks) on the y-axis. A dot landing in the shaded red corner is a high-impact
+   change that declared little risk — the contradiction made into a picture.
+
+`npm run sample` builds and writes a representative `sample-output.html` you can
+open to see the whole page.
+
+### Code complexity (optional, via `lizard`)
+
+If the [`lizard`](https://github.com/terryyin/lizard) analyzer is installed
+(`pip install lizard`), the scorecard also reports **measured cyclomatic
+complexity** of the changed functions — max CCN, a count of hotspots at/above the
+threshold, and a "complexity hotspots" bar chart in the visual summary. lizard
+covers the whole Immeo stack (C#, TS/JS, Python) from source, no build required.
+It's a *measured* signal, so it sits on the same un-gameable side as the
+scorecard. If lizard isn't on `PATH`, the page says so rather than hiding the
+gap — nothing else changes.
+
+### Optional repo policy — `.review/config.json`
+
+```jsonc
+{
+  "sensitivePaths": [ { "label": "pii", "pattern": "(^|/)pii" } ],  // regex on posix path; replaces defaults
+  "churnFiles": 20,           // flag "large change set" above this many files
+  "churnLines": 600,          // ...or this many ± lines
+  "complexityThreshold": 15   // cyclomatic complexity at/above which a function is a hotspot
+}
+```
+
+Absent → built-in defaults (tuned to the Immeo stack). It's repo *policy*, kept
+out of the per-change artifact so it can't be gamed per-PR.
+
+## The artifact contract (`.review/intent.json`)
+
+```jsonc
+{
+  "title": "Short change-set title",
+  "tldr": "Five-second headline: what this does + the single most important why.",
+  "overall": "Why this change set exists, what was rejected, what it rests on. (markdown)",
+  "risks": [
+    { "assumption": "Data is request-scoped", "ifFalse": "Cache leaks across users", "howYoudKnow": "Concurrent-session test" }
+  ],
+  "tests": [
+    { "describes": "Cache returns null on a miss instead of throwing.", "name": "CacheMiss_ReturnsNull", "kind": "unit" }
+  ],
+  "diagrams": {
+    "class": "classDiagram\n  ...",       // mermaid source, authored by the agent
+    "sequence": "sequenceDiagram\n  ..."   // highlight changed steps with rect / Note
+  },
+  "files": [
+    {
+      "path": "src/foo.ts",
+      "what": "What changed in this file.",
+      "why": "Why — the decision behind it. (markdown)",
+      "hunks": [
+        { "anchor": 42, "what": "What this change does.", "why": "Why this specific change." }
+      ]
+    }
+  ]
+}
+```
+
+`title`, `tldr`, `overall`, and every file/hunk's `what` + `why` are required.
+`diagrams`, `risks`, `tests`, and `hunks` are optional. The `tldr` renders as a
+lede at the top (a five-second read); `overall` is the fuller story in a
+collapsible block beneath it.
+
+### Tests section *(claimed, agent-authored)*
+
+`tests` is an optional list of test cases described in plain language — the point
+is a reviewer reading "Cache returns null on a miss" instead of decoding a name
+like `CacheMiss_ReturnsNull`. Each entry needs a `describes` sentence; `name` (the
+real test identifier, for cross-reference) and `kind` (`unit`, `integration`,
+`e2e`, `manual`, or anything else) are optional. Known kinds get a coloured tag
+and group the list. It renders as a standalone **Tests** section between the
+visual summary and the diagrams. It is pure display — review-intent never parses
+or runs your tests — so it sits on the *claimed* side, like the risk ledger.
+
+### Completeness is enforced
+
+The original pain point was agents leaving intent blank. So the contract has
+teeth: **every changed file needs a `what` + `why`, and every diff hunk needs an
+intent.** `review-intent` runs a completeness gate and **refuses to render** if
+anything is missing, printing the exact files and hunks that lack rationale:
+
+```
+Intent is incomplete — 2 gap(s) found:
+  - src/util.js: no what/why written for this changed file
+  - src/util.js: hunk @@ -1 +1 @@ has no intent
+```
+
+`--allow-gaps` renders a work-in-progress draft anyway, with each gap shown as a
+red marker in place — so even a draft can't hide an empty spot. `what` is a cheap
+one-line description; `why` is the decision and must not just restate the `what`.
+
+### How per-hunk intent is matched
+
+`anchor` is a **line number in the new version of the file**. The CLI attaches
+the note to whichever diff hunk's new-line range contains that anchor. This is
+robust to minor hunk-boundary shifts (unlike matching by hunk ordinal).
+
+Notes that match no hunk are surfaced under "Notes not matched to a hunk" —
+never silently dropped. Artifact entries for files absent from the diff appear
+under "Intent for files not in this diff". (Visibility over silent truncation,
+by design.)
+
+## Claude Code integration: authoring the artifact
+
+Nothing *generates* `intent.json` — that's the change-making agent's job, and
+whether the intent is genuine reasoning or post-hoc rationalization is the whole
+ballgame. `review-intent` ships a Claude Code skill that teaches the agent to
+author the artifact **honestly** (real rejected alternatives, stated
+assumptions, incidental changes marked as incidental) when it finishes a change
+set, then offer to render it.
+
+```sh
+review-intent skill install            # ~/.claude/skills/review-intent-authoring (all repos)
+review-intent skill install --local    # ./.claude/skills/review-intent-authoring (this repo only)
+review-intent skill uninstall          # remove user-scoped skill
+review-intent skill uninstall --local  # remove repo-scoped skill
+```
+
+The skill never auto-launches anything — it teaches the agent to write the
+artifact and then *ask* before opening the review. Add `--force` to overwrite or
+remove a hand-edited skill file. User and `--local` scopes are independent.
+
+The honesty contract is the point: a fluent rationalization is worse than
+nothing because it lowers the reviewer's guard while adding no signal. The skill
+pushes for "why I chose this over X" and "what this rests on" — and explicitly
+tells the agent to admit gaps rather than invent thoroughness.
+
+## Development
+
+```sh
+npm test          # vitest, pure-module unit tests
+npm run test:watch
+```
+
+Modules are deliberately small and single-purpose: `git.ts` (diff), `artifact.ts`
+(load + validate), `diff-parser.ts` (parse), `match.ts` (pure join), `render.ts`
+(pure HTML), `cli.ts` (thin orchestrator).

package/dist/artifact.js

@@ -0,0 +1,49 @@
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { ArtifactSchema } from "./types.js";
+export const DEFAULT_ARTIFACT_PATH = ".review/intent.json";
+export class ArtifactError extends Error {
+}
+/**
+ * Locate, parse, and validate the agent-authored intent artifact.
+ * Throws ArtifactError with a friendly, actionable message on any problem.
+ */
+export function loadArtifact(cwd, artifactPath = DEFAULT_ARTIFACT_PATH) {
+    const full = resolve(cwd, artifactPath);
+    if (!existsSync(full)) {
+        throw new ArtifactError(`No intent artifact found at ${full}\n\n` +
+            `The agent that made the changes must write one. Minimal example:\n\n` +
+            `  {\n` +
+            `    "title": "Short change-set title",\n` +
+            `    "overall": "Why this change set exists, what was rejected.",\n` +
+            `    "diagrams": { "class": "classDiagram\\n  ...", "sequence": "sequenceDiagram\\n  ..." },\n` +
+            `    "files": [\n` +
+            `      { "path": "src/foo.ts", "intent": "Why this file changed",\n` +
+            `        "hunks": [ { "anchor": 42, "intent": "Why this change" } ] }\n` +
+            `    ]\n` +
+            `  }\n\n` +
+            `Pass --artifact <path> to point at a different location.`);
+    }
+    let raw;
+    try {
+        raw = readFileSync(full, "utf8");
+    }
+    catch (err) {
+        throw new ArtifactError(`Could not read ${full}: ${err.message}`);
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new ArtifactError(`${full} is not valid JSON: ${err.message}`);
+    }
+    const result = ArtifactSchema.safeParse(json);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`)
+            .join("\n");
+        throw new ArtifactError(`${full} does not match the expected schema:\n${issues}`);
+    }
+    return result.data;
+}

package/dist/cli.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import open from "open";
+import { resolveBase, getDiff, GitError } from "./git.js";
+import { loadArtifact, ArtifactError, DEFAULT_ARTIFACT_PATH } from "./artifact.js";
+import { parseDiffText } from "./diff-parser.js";
+import { buildReviewModel } from "./match.js";
+import { renderHtml } from "./render.js";
+import { loadConfig, ConfigError } from "./config.js";
+import { buildScorecard, isCodePath } from "./scorecard.js";
+import { scanRepo, buildReachGraph } from "./reach.js";
+import { analyzeComplexity } from "./complexity.js";
+import { findGaps, formatGaps } from "./completeness.js";
+import { installSkill, uninstallSkill, skillFile, } from "./skill.js";
+const HELP = `review-intent — render an intent-annotated diff review in your browser.
+
+Usage:
+  review-intent [options]
+  review-intent skill install [--local] [--force]
+  review-intent skill uninstall [--local] [--force]
+
+Options:
+  --base <ref>        Base branch to diff against (default: main, then master)
+  --artifact <path>   Path to the intent artifact (default: ${DEFAULT_ARTIFACT_PATH})
+  --out <path>        Where to write the HTML (default: a temp file)
+  --no-open           Do not open the browser; just write the file
+  --allow-gaps        Render even if intent is incomplete (gaps shown in red)
+  -h, --help          Show this help
+
+Commands:
+  skill install       Install the review-intent-authoring Claude Code skill
+                      (default: ~/.claude/skills; --local: ./.claude/skills)
+  skill uninstall     Remove the skill
+`;
+function localFlag(scope) {
+    return scope === "local" ? " --local" : "";
+}
+async function runSkill(argv) {
+    const sub = argv[0];
+    const { values } = parseArgs({
+        args: argv.slice(1),
+        options: {
+            local: { type: "boolean", default: false },
+            force: { type: "boolean", default: false },
+        },
+    });
+    const scope = values.local ? "local" : "user";
+    const file = skillFile({ scope });
+    if (sub === "install") {
+        const result = await installSkill({ scope, force: values.force });
+        if (result === "installed")
+            process.stdout.write(`Installed skill: ${file}\n`);
+        else if (result === "updated")
+            process.stdout.write(`Updated skill: ${file}\n`);
+        else if (result === "already")
+            process.stdout.write(`Skill already up to date: ${file}\n`);
+        else {
+            process.stderr.write(`A different skill file already exists at ${file}.\n`);
+            process.stderr.write(`Run 'review-intent skill install${localFlag(scope)} --force' to overwrite.\n`);
+            process.exitCode = 1;
+        }
+        return;
+    }
+    if (sub === "uninstall") {
+        const result = await uninstallSkill({ scope, force: values.force });
+        if (result === "removed")
+            process.stdout.write(`Removed skill from ${file}\n`);
+        else if (result === "not-installed")
+            process.stdout.write(`No skill installed at ${file}\n`);
+        else {
+            process.stderr.write(`The skill file at ${file} has been modified.\n`);
+            process.stderr.write(`Run 'review-intent skill uninstall${localFlag(scope)} --force' to remove anyway.\n`);
+            process.exitCode = 1;
+        }
+        return;
+    }
+    process.stderr.write(`Unknown skill command: ${sub ?? "(none)"}\nTry: review-intent skill install | uninstall\n`);
+    process.exitCode = 1;
+}
+async function main() {
+    const rawArgv = process.argv.slice(2);
+    if (rawArgv[0] === "skill") {
+        await runSkill(rawArgv.slice(1));
+        return;
+    }
+    const { values } = parseArgs({
+        options: {
+            base: { type: "string" },
+            artifact: { type: "string" },
+            out: { type: "string" },
+            open: { type: "boolean", default: true },
+            "allow-gaps": { type: "boolean", default: false },
+            help: { type: "boolean", short: "h", default: false },
+        },
+        allowNegative: true,
+    });
+    if (values.help) {
+        process.stdout.write(HELP);
+        return;
+    }
+    const cwd = process.cwd();
+    const base = resolveBase(cwd, values.base);
+    const rawDiff = getDiff(cwd, base);
+    const artifact = loadArtifact(cwd, values.artifact);
+    const config = loadConfig(cwd);
+    const diff = parseDiffText(rawDiff);
+    // Part 1: objective scorecard, computed from the diff.
+    const scorecard = buildScorecard(diff, config);
+    // Part 3: file-level reach, computed by scanning the repo for importers of
+    // the changed code files.
+    const changedCodePaths = diff
+        .filter((f) => f.status !== "deleted" && isCodePath(f.path))
+        .map((f) => f.path);
+    const { files: repoFiles, truncated } = scanRepo(cwd);
+    const reach = buildReachGraph(repoFiles, changedCodePaths, {
+        scanTruncated: truncated,
+    });
+    // Part 1 (cont.): measured cyclomatic complexity of the changed code, via the
+    // external lizard analyzer. Degrades gracefully if lizard isn't installed.
+    const complexity = analyzeComplexity(cwd, changedCodePaths, config.complexityThreshold);
+    const model = buildReviewModel(artifact, diff, base, scorecard, reach, complexity);
+    // Strict completeness gate: refuse to render incomplete intent unless the
+    // author explicitly opts into a draft.
+    const gaps = findGaps(model);
+    if (gaps.length > 0 && !values["allow-gaps"]) {
+        process.stderr.write(`\n${formatGaps(gaps)}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const html = renderHtml(model);
+    const outPath = values.out ?? join(tmpdir(), `review-intent-${Date.now()}.html`);
+    writeFileSync(outPath, html, "utf8");
+    process.stdout.write(`Wrote review to ${outPath}\n`);
+    if (values.open) {
+        await open(outPath);
+    }
+}
+main().catch((err) => {
+    if (err instanceof GitError ||
+        err instanceof ArtifactError ||
+        err instanceof ConfigError) {
+        process.stderr.write(`\n${err.message}\n`);
+    }
+    else {
+        process.stderr.write(`\nUnexpected error: ${err.message}\n`);
+    }
+    process.exitCode = 1;
+});

package/dist/completeness.js

@@ -0,0 +1,36 @@
+/**
+ * Pure: find missing-rationale gaps in the joined model. The contract is strict
+ * — every changed file needs a why, and every diff hunk needs at least one
+ * intent. This needs the model (not just the artifact) because hunk coverage is
+ * only knowable after the artifact's anchors are matched against git's hunks.
+ */
+export function findGaps(model) {
+    const gaps = [];
+    for (const file of model.files) {
+        if (!file.why) {
+            gaps.push({
+                kind: "file",
+                path: file.path,
+                detail: "no what/why written for this changed file",
+            });
+        }
+        for (const hunk of file.hunks) {
+            if (hunk.intents.length === 0) {
+                gaps.push({
+                    kind: "hunk",
+                    path: file.path,
+                    detail: `hunk ${hunk.header} has no intent`,
+                });
+            }
+        }
+    }
+    return gaps;
+}
+/** Render a gap list as a human-readable, copy-pasteable error body. */
+export function formatGaps(gaps) {
+    const lines = gaps.map((g) => `  - ${g.path}: ${g.detail}`);
+    return (`Intent is incomplete — ${gaps.length} gap(s) found:\n` +
+        lines.join("\n") +
+        `\n\nEvery changed file needs a what/why, and every hunk needs an intent.\n` +
+        `Fix .review/intent.json, or pass --allow-gaps to render a draft with the gaps flagged.`);
+}

package/dist/complexity.js

@@ -0,0 +1,139 @@
+import { execFileSync } from "node:child_process";
+/** Languages in the Immeo stack that `lizard` parses reliably from source. */
+const ANALYZABLE_RE = /\.(cs|ts|tsx|js|jsx|mjs|cjs|py)$/i;
+/** Max hotspots to keep, so a pathological change set can't flood the report. */
+const MAX_HOTSPOTS = 12;
+export function isAnalyzablePath(path) {
+    return ANALYZABLE_RE.test(path);
+}
+/**
+ * Pure: split one `lizard --csv` line into fields. lizard quotes the location,
+ * file, name and long-name columns with the Python csv writer, and the long-name
+ * column contains commas (parameter lists) — so a naive split is wrong.
+ */
+export function parseCsvLine(line) {
+    const fields = [];
+    let cur = "";
+    let inQuotes = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (inQuotes) {
+            if (ch === '"') {
+                if (line[i + 1] === '"') {
+                    cur += '"'; // escaped quote
+                    i++;
+                }
+                else {
+                    inQuotes = false;
+                }
+            }
+            else {
+                cur += ch;
+            }
+        }
+        else if (ch === '"') {
+            inQuotes = true;
+        }
+        else if (ch === ",") {
+            fields.push(cur);
+            cur = "";
+        }
+        else {
+            cur += ch;
+        }
+    }
+    fields.push(cur);
+    return fields;
+}
+/** Pure: parse the full `lizard --csv` output into per-function records.
+ *  Columns: nloc, ccn, token, params, length, location, file, name, long_name, start, end. */
+export function parseLizardCsv(csv) {
+    const out = [];
+    for (const raw of csv.split(/\r?\n/)) {
+        if (raw.trim() === "")
+            continue;
+        const f = parseCsvLine(raw);
+        if (f.length < 11)
+            continue; // malformed row — skip rather than mis-read
+        out.push({
+            nloc: Number(f[0]),
+            ccn: Number(f[1]),
+            params: Number(f[3]),
+            file: f[6],
+            name: f[7],
+            line: Number(f[9]),
+        });
+    }
+    return out;
+}
+/** Pure: aggregate per-function records into the measured complexity model. */
+export function buildComplexityModel(funcs, threshold) {
+    const sorted = [...funcs].sort((a, b) => b.ccn - a.ccn);
+    return {
+        available: true,
+        threshold,
+        functionsAnalyzed: funcs.length,
+        maxCcn: funcs.reduce((m, f) => Math.max(m, f.ccn), 0),
+        worst: sorted[0] ?? null,
+        hotspots: sorted.filter((f) => f.ccn >= threshold).slice(0, MAX_HOTSPOTS),
+    };
+}
+/** A complexity model standing in for analysis that could not run — the note is
+ *  rendered so the absence is visible, never a silent skip. */
+export function unavailableComplexity(note) {
+    return {
+        available: false,
+        threshold: 0,
+        functionsAnalyzed: 0,
+        maxCcn: 0,
+        worst: null,
+        hotspots: [],
+        note,
+    };
+}
+/** Candidate ways to invoke lizard: the console script if on PATH, else the
+ *  Python module (covers `pip install --user` where the script isn't on PATH). */
+const INVOCATIONS = [
+    { cmd: "lizard", pre: [] },
+    { cmd: "python", pre: ["-m", "lizard"] },
+    { cmd: "python3", pre: ["-m", "lizard"] },
+    { cmd: "py", pre: ["-m", "lizard"] },
+];
+function runLizard(cwd, files) {
+    for (const inv of INVOCATIONS) {
+        try {
+            return execFileSync(inv.cmd, [...inv.pre, "--csv", ...files], {
+                cwd,
+                encoding: "utf8",
+                maxBuffer: 32 * 1024 * 1024,
+                stdio: ["ignore", "pipe", "ignore"],
+            });
+        }
+        catch (err) {
+            const e = err;
+            if (e.code === "ENOENT")
+                continue; // this invocation isn't available — try the next
+            // lizard ran but exited non-zero (e.g. threshold warnings); keep its output.
+            if (typeof e.stdout === "string" && e.stdout.trim() !== "")
+                return e.stdout;
+            return null;
+        }
+    }
+    return null; // no working lizard invocation
+}
+/**
+ * Side-effecting: measure complexity of the analyzable changed files via lizard.
+ * Degrades gracefully — a missing lizard yields an `available: false` model with
+ * a note rather than an error or a silent gap.
+ */
+export function analyzeComplexity(cwd, changedPaths, threshold) {
+    const files = changedPaths.filter(isAnalyzablePath);
+    if (files.length === 0) {
+        return { ...buildComplexityModel([], threshold), note: "no analyzable source files in this change set" };
+    }
+    const csv = runLizard(cwd, files);
+    if (csv === null) {
+        return unavailableComplexity("lizard not found — run `pip install lizard` to enable complexity metrics");
+    }
+    return buildComplexityModel(parseLizardCsv(csv), threshold);
+}