@christianmorup/review-intent 0.1.0

package/dist/scorecard.js

@@ -0,0 +1,101 @@
+const TEST_RE = /(?:[._-](?:test|spec)\.)|(?:^|\/)(?:tests?|__tests__|spec)\//i;
+const CODE_RE = /\.(ts|tsx|js|jsx|mjs|cjs|cs|go|py|java|rb|rs|cpp|cc|c|h|hpp|php|vue|svelte|kt|swift|scala)$/i;
+/** Lockfiles, generated/minified output, build dirs, and binaries — high churn,
+ *  low review value. Flagged so a reviewer knows how much of the diff is noise. */
+const NOISE_RE = /(?:^|\/)(?:package-lock\.json|yarn\.lock|pnpm-lock\.yaml|packages\.lock\.json)$|\.(?:lock|min\.js|min\.css|map|snap)$|(?:^|\/)(?:dist|build|node_modules|out)\/|\.(?:png|jpe?g|gif|svg|ico|webp|woff2?|ttf|eot|pdf)$/i;
+/** Debt/debug markers a reviewer should never let through unnoticed. */
+const DEBT_RE = /\b(?:TODO|FIXME|HACK|XXX)\b|console\.log|debugger\b/;
+export function isTestPath(path) {
+    return TEST_RE.test(path);
+}
+export function isCodePath(path) {
+    return CODE_RE.test(path);
+}
+export function isNoisePath(path) {
+    return NOISE_RE.test(path);
+}
+/** Pure: derive the objective surface-area scorecard from the parsed diff. */
+export function buildScorecard(diff, config) {
+    const byStatus = {};
+    let hunks = 0;
+    let added = 0;
+    let removed = 0;
+    let testFiles = 0;
+    let codeFiles = 0;
+    let testLines = 0;
+    let codeLines = 0;
+    let debtMarkers = 0;
+    let noiseFiles = 0;
+    let largestFile = null;
+    for (const file of diff) {
+        byStatus[file.status] = (byStatus[file.status] ?? 0) + 1;
+        hunks += file.hunks.length;
+        let fileChurn = 0;
+        for (const hunk of file.hunks) {
+            for (const line of hunk.lines) {
+                if (line.type === "add") {
+                    added++;
+                    fileChurn++;
+                    if (DEBT_RE.test(line.content))
+                        debtMarkers++;
+                }
+                else if (line.type === "del") {
+                    removed++;
+                    fileChurn++;
+                }
+            }
+        }
+        const isTest = isTestPath(file.path);
+        if (isTest) {
+            testFiles++;
+            testLines += fileChurn;
+        }
+        else if (isCodePath(file.path)) {
+            codeFiles++;
+            codeLines += fileChurn;
+        }
+        if (isNoisePath(file.path))
+            noiseFiles++;
+        if (!largestFile || fileChurn > largestFile.churn) {
+            largestFile = { path: file.path, churn: fileChurn };
+        }
+    }
+    const badges = [];
+    // Code changed but no test files touched — the headline review smell.
+    if (codeFiles > 0 && testFiles === 0) {
+        badges.push({ label: "no test changes", tone: "danger" });
+    }
+    // Sensitive paths (repo policy), de-duplicated by label.
+    const paths = diff.map((f) => f.path);
+    for (const sp of config.sensitivePaths) {
+        let re;
+        try {
+            re = new RegExp(sp.pattern, "i");
+        }
+        catch {
+            continue; // a bad policy regex shouldn't crash the scorecard
+        }
+        if (paths.some((p) => re.test(p))) {
+            badges.push({ label: `touches ${sp.label}`, tone: "danger" });
+        }
+    }
+    // Large change set (churn).
+    if (diff.length > config.churnFiles || added + removed > config.churnLines) {
+        badges.push({ label: "large change set", tone: "warn" });
+    }
+    return {
+        filesChanged: diff.length,
+        byStatus,
+        hunks,
+        added,
+        removed,
+        testFiles,
+        codeFiles,
+        testLines,
+        codeLines,
+        debtMarkers,
+        noiseFiles,
+        largestFile,
+        badges,
+    };
+}

package/dist/skill.js

@@ -0,0 +1,257 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+const SKILL_NAME = "review-intent-authoring";
+// Embedded content for the Claude Code skill that teaches the change-making
+// agent to author an honest .review/intent.json before review. Single source
+// of truth — the installer writes this byte-for-byte, and uninstall checks
+// against it (line-ending-normalized) to decide whether the file is still ours.
+export const SKILL_CONTENT = `---
+name: review-intent-authoring
+description: Use when you have just finished a set of code changes on a branch and the user (or another reviewer) is about to review the diff. Author a .review/intent.json that captures the genuine intent behind the changes — why, what you rejected, what it rests on — keyed to files and hunks, plus mermaid class and sequence diagrams. Then offer to render it with review-intent so the reviewer adjudicates decisions instead of skimming lines.
+---
+
+# Authoring an honest intent artifact
+
+A diff records *what* changed and erases *why*. \`review-intent\` renders your
+intent side-by-side with the diff so the reviewer adjudicates decisions, not
+lines. Your job is to write \`.review/intent.json\` — and to write it **honestly**,
+because a fluent rationalization is worse than nothing: it lowers the reviewer's
+guard while adding no real signal.
+
+## When to author
+
+After you finish a logical change set on a branch and before you hand it back
+for review. One artifact per branch / review.
+
+## When NOT to author
+
+- A trivial or purely mechanical change (rename, formatting, dependency bump)
+  where the diff already tells the whole story. Say so in chat; don't manufacture
+  intent.
+- You are mid-implementation, not at a reviewable stopping point.
+- The user has declined review-intent for this change set.
+
+## The honesty contract (read this before writing a word)
+
+These rules exist to keep the artifact from becoming post-hoc theater:
+
+1. **Intent is the reason you chose this, not a description of what it does.**
+   "Adds a cache" is not intent. "Chose an in-memory cache over Redis because the
+   data is request-scoped and we have one process" is intent.
+2. **Name what you rejected — truthfully.** If there was a real alternative, state
+   it and why you didn't take it. If there genuinely wasn't one, write "no real
+   alternative considered" — do **not** invent a rejected option to look thorough.
+3. **State what the change rests on.** The assumptions that, if false, make this
+   change wrong. This is the reviewer's highest-value target.
+4. **Mark incidental changes as incidental.** If a hunk is a mechanical
+   consequence (a signature changed so callers had to), say that plainly instead
+   of inventing a decision for it.
+5. **If you are uncertain, say you are uncertain.** "I think X but didn't verify
+   under concurrency" is more useful than false confidence.
+
+If following these makes a section short or admits a gap, that is a success, not
+a failure. The gap is the signal the reviewer needs.
+
+## Completeness is mandatory (this is enforced)
+
+Every changed file needs a \`what\` and a \`why\`, and **every hunk needs a \`what\`
+and a \`why\`**. \`review-intent\` runs a completeness gate and **refuses to render**
+if any changed file or hunk is missing intent — it prints the exact gaps. Do not
+hand back a change set with empty intent; fill it before you offer the review.
+(\`--allow-gaps\` exists for an explicit work-in-progress draft, and even then the
+gaps render as red markers — it is not a way to skip the work.) review-intent
+also renders an **intent-coverage gauge** — the measured share of files and hunks
+you annotated — so partial coverage is visible at a glance, draft or not.
+
+\`what\` vs \`why\`: \`what\` is a one-line description of the change (cheap — write it
+first). \`why\` is the decision behind it and must not restate the what. "Renamed
+\`x\` to \`y\`" is a what; "renamed for consistency with the \`z\` convention so callers
+don't guess" is a why. For a mechanical hunk, an honest why is "incidental —
+forced by the signature change above"; write that rather than leaving it blank.
+
+## The artifact: \`.review/intent.json\`
+
+Write it at the repo root. \`title\`, \`tldr\`, and \`overall\` are required, and so
+are \`what\`/\`why\` on every file and hunk you list (see the completeness gate
+above). The \`tldr\` is a five-second read shown as a lede at the top — the single
+headline (what + the most important why); \`overall\` is the fuller story beneath
+it. Don't make the tldr a copy of the title or just the "what" — it must carry a
+why.
+
+\`\`\`jsonc
+{
+  "title": "Short change-set title",
+  "tldr": "One or two sentences a reviewer can read in five seconds: what this does and the single most important why.",
+  "overall": "Why this change set exists. What you rejected and why. What it rests on (assumptions that, if false, break it). Markdown.",
+  "risks": [
+    { "assumption": "What the change rests on",
+      "ifFalse": "What breaks if it does not hold",
+      "howYoudKnow": "How a reviewer could check (optional)" }
+  ],
+  "tests": [
+    { "describes": "Plain-language sentence: what this test proves.",
+      "name": "RealTestIdentifier (optional, for cross-reference)",
+      "kind": "unit | integration | e2e | manual (optional)" }
+  ],
+  "diagrams": {
+    "class": "classDiagram\\n  ...",       // structures you added/changed
+    "sequence": "sequenceDiagram\\n  ..."   // a flow the change affects; highlight changed steps
+  },
+  "files": [
+    {
+      "path": "src/foo.ts",
+      "what": "What changed in this file (one line is fine).",
+      "why": "Why — the decision behind it. REQUIRED for every changed file.",
+      "hunks": [
+        { "anchor": 42,
+          "what": "What this specific change does.",
+          "why": "Why this specific change. REQUIRED. Anchor = a line number in the NEW file." }
+      ]
+    }
+  ]
+}
+\`\`\`
+
+### The blast radius (\`risks\`)
+
+The \`risks\` array is the change's blast radius — one row per thing it rests on.
+This is the reviewer's highest-value target, so write it to honesty-rule #3:
+
+- Each row is an **assumption** (what must be true), the **ifFalse** consequence
+  (what breaks if it isn't), and optionally **howYoudKnow** (how to check).
+- If the change genuinely rests on nothing, leave \`risks\` empty — but know that
+  review-intent renders an explicit "No risks declared" nudge, because a truly
+  assumption-free change is rare. An empty ledger is a claim, not a free pass.
+- **review-intent independently measures several signals and renders them next
+  to your ledger — you cannot edit them.** A surface-area scorecard (files,
+  ±lines, test-vs-code, debt/debug markers), a file-level reach graph, and the
+  **cyclomatic complexity of the changed functions** (hotspots above the repo
+  threshold are flagged, via \`lizard\`) all sit beside your claims. If you claim
+  "low risk" while the scorecard flags \`touches auth/, 0 test files\` or a
+  changed function jumps to CCN 30 and you never mention it, the contradiction is
+  visible at a glance.
+- **There is an "honesty quadrant"** that plots your *claimed* candor (declared
+  risks + intent coverage) against the *measured* blast radius (churn + reach). A
+  large, far-reaching change that declared little lands in a red corner. Padding
+  the ledger with throwaway risks to nudge the dot is pointless — a human reads
+  the prose. Write a ledger the measured facts won't embarrass: address the gap,
+  or name it as a risk. If a hunk added real branching/complexity, the *why* is
+  the place to justify it.
+
+### The tests section (\`tests\`)
+
+Optional. List the test cases that cover this change, each described in **plain
+language** — the value is a reviewer reading "Cache returns null on a miss"
+instead of decoding \`CacheMiss_ReturnsNull\`. Each entry needs a \`describes\`
+sentence; \`name\` (the real test identifier) and \`kind\` (\`unit\`, \`integration\`,
+\`e2e\`, \`manual\`) are optional — known kinds group the list.
+
+Honesty applies here too: describe the tests that **actually exist**, not the
+ones you wish you'd written. If a behaviour is untested, don't invent a case —
+either leave it out or, if it matters, name the gap in the risk ledger
+(\`howYoudKnow\` is often exactly that test). \`describes\` is what the test proves
+for a reader, not a restatement of its name. Omit the section entirely for a
+change with no meaningful tests rather than padding it.
+
+### Anchors
+
+\`anchor\` is a line number in the **new** version of the file (the right side of
+the diff). review-intent attaches the note to whichever hunk's new-line range
+contains that anchor. Pick a line inside the change you are explaining. If you
+get it wrong, the note still shows — under "Notes not matched to a hunk" — so it
+is never lost, but aim to land it in the hunk.
+
+### Diagrams (mermaid, authored by you)
+
+- **Class diagram**: the types/modules you added or reshaped and their relations.
+  Keep it to what the change touches, not the whole system.
+- **Sequence diagram**: a flow the change participates in. Highlight the steps
+  that changed using a \`rect\` block or a \`Note\`, e.g.:
+
+\`\`\`
+sequenceDiagram
+  Caller->>Service: request()
+  rect rgb(40,80,50)
+  Note over Service: CHANGED: now validates input first
+  end
+  Service-->>Caller: result
+\`\`\`
+
+Omit a diagram if the change genuinely has no structural or sequential story —
+don't draw a trivial two-box diagram to fill the slot.
+
+## After writing it
+
+Offer to render — never auto-launch:
+
+> I've written the review intent to \`.review/intent.json\`. Want me to open the
+> side-by-side review? (\`review-intent\`)
+
+If the user accepts, run \`review-intent\` via Bash from the repo root. It diffs
+the current branch against main and opens the rendered page in the browser.
+
+## Why this exists
+
+The friction of hand-writing code used to carry reflection along for free. With
+that friction gone, intent has to be chosen on purpose. This artifact is where
+you pay for it — deliberately, in the reviewer's currency: why, rejected
+alternatives, and assumptions. Render quality is not the hard part; the honesty
+of what you write here is.
+`;
+export function skillFile(opts = {}) {
+    const scope = opts.scope ?? "user";
+    const root = scope === "local"
+        ? (opts.cwd ?? process.cwd())
+        : (opts.home ?? os.homedir());
+    return path.join(root, ".claude", "skills", SKILL_NAME, "SKILL.md");
+}
+export async function installSkill(opts = {}) {
+    const file = skillFile(opts);
+    const existing = await readOrNull(file);
+    if (existing !== null && canonical(existing) === canonical(SKILL_CONTENT)) {
+        return "already";
+    }
+    if (existing !== null && !opts.force) {
+        return "conflict";
+    }
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, SKILL_CONTENT, "utf8");
+    return existing === null ? "installed" : "updated";
+}
+export async function uninstallSkill(opts = {}) {
+    const file = skillFile(opts);
+    const existing = await readOrNull(file);
+    if (existing === null)
+        return "not-installed";
+    if (canonical(existing) !== canonical(SKILL_CONTENT) && !opts.force) {
+        return "modified";
+    }
+    await fs.rm(file);
+    // Best-effort cleanup of the now-empty skill directory; leave it alone if the
+    // user dropped other files in there. Only swallow the expected codes.
+    try {
+        await fs.rmdir(path.dirname(file));
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOTEMPTY" && code !== "ENOENT" && code !== "EEXIST")
+            throw err;
+    }
+    return "removed";
+}
+// Normalize CRLF so an editor that rewrote line endings doesn't flip a clean
+// install into a "conflict" / "modified" state.
+function canonical(s) {
+    return s.replace(/\r\n/g, "\n");
+}
+async function readOrNull(p) {
+    try {
+        return await fs.readFile(p, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}

package/dist/types.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+/**
+ * The agent-authored artifact contract. The agent that made the changes writes
+ * this file (default `./.review/intent.json`); the CLI only ever reads it.
+ */
+export const HunkIntentSchema = z.object({
+    /** A line number in the NEW version of the file. The CLI attaches this note
+     *  to whichever diff hunk's new-line range contains the anchor. */
+    anchor: z.number().int().positive(),
+    /** What this specific change does. */
+    what: z.string().min(1),
+    /** Why it was made — the decision, not a restatement of the what. */
+    why: z.string().min(1),
+});
+export const FileIntentSchema = z.object({
+    path: z.string().min(1),
+    /** What changed in this file. */
+    what: z.string().min(1),
+    /** Why this file changed — the decision behind it (markdown). */
+    why: z.string().min(1),
+    hunks: z.array(HunkIntentSchema).optional().default([]),
+});
+export const DiagramsSchema = z
+    .object({
+    /** Mermaid `classDiagram` source, authored by the agent. */
+    class: z.string().optional(),
+    /** Mermaid `sequenceDiagram` source; changed steps highlighted by the agent. */
+    sequence: z.string().optional(),
+})
+    .optional()
+    .default({});
+/** One row of the agent-authored risk ledger (the "blast radius"). */
+export const RiskSchema = z.object({
+    /** Something the change rests on; if false, the change is wrong. */
+    assumption: z.string().min(1),
+    /** What breaks if the assumption does not hold. */
+    ifFalse: z.string().min(1),
+    /** How a reviewer could find out whether it holds. Optional. */
+    howYoudKnow: z.string().optional(),
+});
+/** One agent-described test case. Pure prose — the renderer never parses or
+ *  measures it; it sits on the "claimed" side, next to the measured test count. */
+export const TestCaseSchema = z.object({
+    /** A short, human-readable sentence: what the test proves. The only required
+     *  field — the point is a reviewer reading it instead of a cryptic test name. */
+    describes: z.string().min(1),
+    /** The real test identifier, for cross-reference (e.g. `CacheMiss_ReturnsNull`). */
+    name: z.string().optional(),
+    /** Free-form kind (e.g. `unit`, `integration`, `e2e`, `manual`). Known kinds
+     *  get a coloured tag and drive grouping; anything else is shown as-is. Kept a
+     *  free string so an unusual kind never rejects the artifact. */
+    kind: z.string().optional(),
+});
+export const ArtifactSchema = z.object({
+    title: z.string().min(1),
+    /** One- or two-sentence executive summary, shown as a lede above `overall`. */
+    tldr: z.string().min(1),
+    /** Why this change set exists, what was rejected, what it rests on (markdown). */
+    overall: z.string().min(1),
+    diagrams: DiagramsSchema,
+    risks: z.array(RiskSchema).optional().default([]),
+    /** Human-readable descriptions of the test cases covering the change (claimed). */
+    tests: z.array(TestCaseSchema).optional().default([]),
+    files: z.array(FileIntentSchema).optional().default([]),
+});

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@christianmorup/review-intent",
+  "version": "0.1.0",
+  "description": "Render the diff between the current branch and main as an intent-annotated HTML review page with mermaid class & sequence diagrams.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Christian Mørup <cmo@immeo.dk>",
+  "homepage": "https://github.com/ChristianMorup/review-intent#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ChristianMorup/review-intent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ChristianMorup/review-intent/issues"
+  },
+  "keywords": [
+    "code-review",
+    "diff",
+    "git",
+    "mermaid",
+    "cli"
+  ],
+  "bin": {
+    "review-intent": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "node --experimental-strip-types src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "sample": "tsc && node scripts/gen-sample.mjs",
+    "prepare": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "dependencies": {
+    "open": "^10.1.0",
+    "parse-diff": "^0.11.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}