semantic-review 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikkel Malmberg
+
+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,35 @@
+<img src="semantic-review.webp" width="452">
+
+# semantic-review
+
+> Tell me that again but _slowly_...
+
+Semantic diff review for coding agents.
+
+An LLM reads a git diff and reorganizes it into a **narrative HTML report** — grouped by concern, not alphabetically, with the interesting excerpts inline, highlighted and commentable. When the reviewer clicks **Done**, their comments print to `stdout` as plaintext for the agent that invoked it.
+
+```
+agent runs `semantic-review` ──► LLM analyzes the diff ──► browser opens the report
+agent reads stdout ◄── plaintext feedback ◄── human comments, clicks Done
+```
+
+Requires Node >= 20 (or [Bun](https://bun.sh)) and one backend: `ANTHROPIC_API_KEY`, or an installed `claude`, `codex`, `gemini`, or `pi` CLI.
+
+```sh
+npx semantic-review
+```
+
+
+Run it like `$ git diff`:
+
+```
+semantic-review                        # review uncommitted changes
+semantic-review main...HEAD            # review a branch
+git diff -U10 | semantic-review        # review any piped diff
+semantic-review --with anthropic,codex # one analysis per backend, tabbed
+semantic-review --model claude-sonnet-5 --effort medium
+```
+
+Tell your agent (`CLAUDE.md`, `AGENTS.md`, …):
+
+> After completing a substantial change, run `npx semantic-review` and wait for it to exit. Its stdout is the user's review feedback — treat each comment as a change request and address it.

package/dist/cli.js

@@ -0,0 +1,772 @@
+#!/usr/bin/env node
+
+// src/diff.ts
+function parseDiff(diff) {
+  const files = [];
+  let file = null;
+  let hunk = null;
+  let oldNo = 0;
+  let newNo = 0;
+  let hunkCount = 0;
+  const lines = diff.split("\n");
+  if (lines[lines.length - 1] === "") lines.pop();
+  for (const line of lines) {
+    if (line.startsWith("diff --git ")) {
+      const m = line.match(/^diff --git a\/(.*) b\/(.*)$/);
+      file = {
+        path: m ? m[2] : line.slice("diff --git ".length),
+        oldPath: m ? m[1] : "",
+        status: "modified",
+        hunks: []
+      };
+      files.push(file);
+      hunk = null;
+      continue;
+    }
+    if (!file) continue;
+    if (line.startsWith("new file mode")) file.status = "added";
+    else if (line.startsWith("deleted file mode")) file.status = "deleted";
+    else if (line.startsWith("rename from")) file.status = "renamed";
+    else if (line.startsWith("Binary files")) file.status = "binary";
+    const hm = line.match(/^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+    if (hm) {
+      oldNo = parseInt(hm[1], 10);
+      newNo = parseInt(hm[2], 10);
+      hunk = { id: `h${++hunkCount}`, header: line, lines: [] };
+      file.hunks.push(hunk);
+      continue;
+    }
+    if (!hunk) continue;
+    if (line.startsWith("+")) {
+      hunk.lines.push({ kind: "add", oldNo: null, newNo: newNo++, text: line.slice(1) });
+    } else if (line.startsWith("-")) {
+      hunk.lines.push({ kind: "del", oldNo: oldNo++, newNo: null, text: line.slice(1) });
+    } else if (line.startsWith(" ") || line === "") {
+      hunk.lines.push({ kind: "context", oldNo: oldNo++, newNo: newNo++, text: line.slice(1) });
+    }
+  }
+  return files;
+}
+function hunkById(files) {
+  const map = /* @__PURE__ */ new Map();
+  for (const file of files) for (const hunk of file.hunks) map.set(hunk.id, { file, hunk });
+  return map;
+}
+function diffForModel(files) {
+  const parts = [];
+  for (const file of files) {
+    if (file.status === "binary") {
+      parts.push(`### ${file.path} (binary, ${file.status})`);
+      continue;
+    }
+    for (const hunk of file.hunks) {
+      parts.push(`### hunk ${hunk.id} \u2014 ${file.path} (${file.status}) ${hunk.header}`);
+      parts.push(
+        hunk.lines.map((l) => {
+          const no = l.newNo != null ? `${l.newNo}` : `-${l.oldNo}`;
+          const sign = l.kind === "add" ? "+" : l.kind === "del" ? "-" : " ";
+          return `${no}|${sign}${l.text}`;
+        }).join("\n")
+      );
+    }
+  }
+  return parts.join("\n");
+}
+
+// src/backends.ts
+import Anthropic from "@anthropic-ai/sdk";
+import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
+
+// src/analysis.ts
+import { z } from "zod";
+var AnalysisSchema = z.object({
+  title: z.string(),
+  summary: z.string(),
+  diagram: z.string(),
+  sections: z.array(
+    z.object({
+      heading: z.string(),
+      intro: z.string(),
+      diagram: z.string(),
+      snippets: z.array(
+        z.object({
+          hunk_id: z.string(),
+          from: z.number().nullable(),
+          to: z.number().nullable(),
+          note: z.string()
+        })
+      )
+    })
+  ),
+  notes: z.array(z.string())
+});
+function analysisPrompt(annotatedDiff) {
+  return `You are writing a short semantic review guide for a git diff. Traditional diffs list files alphabetically; your job is to reorganize the change into a brief narrative a reviewer can follow in a minute or two. The reviewer also has the full diff available below your guide, so you do NOT need to show everything \u2014 show only the lines that carry the meaning of the change.
+
+Each hunk is labeled "hunk hN". Every line is prefixed with its line number in the new file ("42|+code"); deleted lines carry the old-file number prefixed with a minus ("-17|-code").
+
+Produce a JSON object with exactly this shape:
+
+{
+  "title": "short title for the change",
+  "summary": "1-2 sentence TL;DR: what the change does and why",
+  "diagram": "optional mermaid diagram source, or \\"\\"",
+  "sections": [
+    {
+      "heading": "...",
+      "intro": "1-2 sentences introducing this part of the change",
+      "diagram": "optional mermaid diagram source for this section, or \\"\\"",
+      "snippets": [
+        { "hunk_id": "h3", "from": 40, "to": 48, "note": "one short line bridging to the next snippet (or \\"\\")" }
+      ]
+    }
+  ],
+  "notes": ["risks or things a reviewer should double-check", ...]
+}
+
+Rules:
+- Be brief. Section intros are 1-2 sentences; snippet notes are one short line or "". No filler.
+- "diagram" (top level and per section): include a small mermaid diagram ONLY when that part of the change is genuinely graph-shaped (data flowing through new pieces, call-order changes, moved responsibilities) \u2014 a "flowchart LR" or "sequenceDiagram" with 3-8 nodes, no styling directives. The top-level diagram is a whole-change overview; a section diagram covers just that section. Use "" when a diagram would not beat prose \u2014 most small changes need none, and few sections deserve their own.
+- Snippets are EXCERPTS: pick the smallest line range that shows the interesting part (typically 3-12 lines), using the line-number prefixes. from/to use new-file numbers; for ranges of deleted lines use the old-file numbers (positive). Use null for both to include the whole hunk \u2014 only when the hunk is already small.
+- Group by code path / concern, not by file. Order sections by importance: core change first.
+- Purely mechanical changes (renames, lockfiles, formatting) need no snippet \u2014 mention them in one sentence in an intro or the summary.
+- Prose is plain text; use backticks for identifiers. No markdown headings.
+- "notes" is for behavior changes, missing tests, edge cases, inconsistencies. Empty array if none.
+- Respond with ONLY the JSON object, no fences, no commentary.
+
+The diff:
+
+${annotatedDiff}`;
+}
+function extractAnalysis(raw) {
+  let text = raw.trim();
+  const fence = text.match(/```(?:json)?\s*([\s\S]*?)```/);
+  if (fence) text = fence[1].trim();
+  if (!text.startsWith("{")) {
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    if (start === -1 || end === -1) throw new Error(`no JSON object found in output:
+${raw.slice(0, 500)}`);
+    text = text.slice(start, end + 1);
+  }
+  return AnalysisSchema.parse(JSON.parse(text));
+}
+
+// src/proc.ts
+import { spawn } from "node:child_process";
+function run(argv, stdin) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(argv[0], argv.slice(1), { stdio: ["pipe", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    proc.stdout.setEncoding("utf8").on("data", (chunk) => stdout += chunk);
+    proc.stderr.setEncoding("utf8").on("data", (chunk) => stderr += chunk);
+    proc.on("error", reject);
+    proc.on("close", (code) => resolve({ stdout, stderr, code: code ?? 1 }));
+    if (stdin !== void 0) proc.stdin.write(stdin);
+    proc.stdin.end();
+  });
+}
+
+// src/backends.ts
+function haveCommand(cmd) {
+  return run(["sh", "-c", `command -v ${cmd}`]).then(
+    ({ code }) => code === 0,
+    () => false
+  );
+}
+function cliBackend(name, argv) {
+  return {
+    name,
+    available: () => haveCommand(argv({})[0]),
+    async analyze(annotatedDiff, opts) {
+      const { stdout, stderr, code } = await run(argv(opts), analysisPrompt(annotatedDiff));
+      if (code !== 0) throw new Error(`${name} exited ${code}: ${stderr.slice(0, 500)}`);
+      return extractAnalysis(stdout);
+    }
+  };
+}
+var anthropicBackend = {
+  name: "anthropic",
+  available: async () => !!(process.env.ANTHROPIC_API_KEY || process.env.ANTHROPIC_AUTH_TOKEN),
+  async analyze(annotatedDiff, opts) {
+    const client = new Anthropic();
+    const stream = client.messages.stream({
+      model: opts.model || process.env.SEMANTIC_REVIEW_MODEL || "claude-opus-5",
+      max_tokens: 32e3,
+      output_config: {
+        format: zodOutputFormat(AnalysisSchema),
+        // SDK typings lag the API: "xhigh" is valid but missing from the union.
+        ...opts.effort ? { effort: opts.effort } : {}
+      },
+      messages: [{ role: "user", content: analysisPrompt(annotatedDiff) }]
+    });
+    const message = await stream.finalMessage();
+    const text = message.content.find((b) => b.type === "text");
+    if (!text || text.type !== "text") throw new Error(`no text in response (stop_reason: ${message.stop_reason})`);
+    return AnalysisSchema.parse(JSON.parse(text.text));
+  }
+};
+var modelFlag = (o, flag = "--model") => o.model ? [flag, o.model] : [];
+var BACKENDS = {
+  anthropic: anthropicBackend,
+  claude: cliBackend("claude", (o) => ["claude", "-p", ...modelFlag(o)]),
+  codex: cliBackend("codex", (o) => ["codex", "exec", "--skip-git-repo-check", ...modelFlag(o, "-m"), "-"]),
+  gemini: cliBackend("gemini", (o) => ["gemini", ...modelFlag(o)]),
+  pi: cliBackend("pi", (o) => ["pi", "-p", "--no-session", "--no-tools", ...modelFlag(o)])
+};
+async function resolveBackends(requested) {
+  if (requested && requested.length > 0) {
+    return requested.map((name) => {
+      const backend = BACKENDS[name];
+      if (!backend) throw new Error(`unknown backend "${name}" (known: ${Object.keys(BACKENDS).join(", ")})`);
+      return backend;
+    });
+  }
+  for (const backend of Object.values(BACKENDS)) {
+    if (await backend.available()) return [backend];
+  }
+  throw new Error(
+    "no backend available: set ANTHROPIC_API_KEY, or install one of: claude, codex, gemini (or pass --with)"
+  );
+}
+async function runBackends(backends, annotatedDiff, opts = {}) {
+  const settled = await Promise.allSettled(
+    backends.map(async (b) => ({ backend: b.name, analysis: await b.analyze(annotatedDiff, opts) }))
+  );
+  const results = [];
+  for (let i = 0; i < settled.length; i++) {
+    const s = settled[i];
+    if (s.status === "fulfilled") results.push(s.value);
+    else console.error(`semantic-review: backend ${backends[i].name} failed: ${s.reason?.message ?? s.reason}`);
+  }
+  if (results.length === 0) throw new Error("all backends failed");
+  return results;
+}
+
+// src/render.ts
+import { createHighlighter, bundledLanguages } from "shiki";
+var LANG_BY_EXT = {
+  ts: "typescript",
+  tsx: "tsx",
+  js: "javascript",
+  jsx: "jsx",
+  mjs: "javascript",
+  cjs: "javascript",
+  rb: "ruby",
+  py: "python",
+  go: "go",
+  rs: "rust",
+  java: "java",
+  kt: "kotlin",
+  swift: "swift",
+  c: "c",
+  h: "c",
+  cc: "cpp",
+  cpp: "cpp",
+  hpp: "cpp",
+  cs: "csharp",
+  php: "php",
+  sh: "shellscript",
+  bash: "shellscript",
+  zsh: "shellscript",
+  fish: "fish",
+  html: "html",
+  erb: "erb",
+  css: "css",
+  scss: "scss",
+  json: "json",
+  yml: "yaml",
+  yaml: "yaml",
+  toml: "toml",
+  md: "markdown",
+  sql: "sql",
+  ex: "elixir",
+  exs: "elixir",
+  vue: "vue",
+  svelte: "svelte"
+};
+function langFor(path) {
+  const ext = path.split(".").pop()?.toLowerCase() ?? "";
+  const lang = LANG_BY_EXT[ext];
+  return lang && lang in bundledLanguages ? lang : "text";
+}
+var esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+function prose(text) {
+  return text.split(/\n\n+/).map((p) => `<p>${esc(p).replace(/`([^`]+)`/g, "<code>$1</code>")}</p>`).join("");
+}
+function tokenStyle(token) {
+  if (token.htmlStyle) {
+    if (typeof token.htmlStyle === "string") return token.htmlStyle;
+    return Object.entries(token.htmlStyle).map(([k, v]) => `${k}:${v}`).join(";");
+  }
+  return token.color ? `color:${token.color}` : "";
+}
+var CARD = "rounded-lg border border-stone-200 bg-white dark:border-stone-800 dark:bg-stone-900";
+function renderHunk(hl, file, hunk, range) {
+  const lang = langFor(file.path);
+  const code = hunk.lines.map((l) => l.text).join("\n");
+  let tokenLines;
+  try {
+    tokenLines = hl.codeToTokens(code, {
+      lang,
+      themes: { light: "github-light", dark: "github-dark" }
+    }).tokens;
+  } catch {
+    tokenLines = hunk.lines.map((l) => [{ content: l.text }]);
+  }
+  let indices = hunk.lines.map((_, i) => i);
+  if (range) {
+    const within = (n) => n != null && n >= range.from && n <= range.to;
+    const sliced = indices.filter((i) => within(hunk.lines[i].newNo) || within(hunk.lines[i].oldNo));
+    if (sliced.length > 0) indices = sliced;
+  }
+  const elided = indices.length < hunk.lines.length;
+  const rows = indices.map((i) => {
+    const line = hunk.lines[i];
+    const tokens = tokenLines[i] ?? [{ content: line.text }];
+    const codeHtml = tokens.map((t) => `<span style="${esc(tokenStyle(t))}">${esc(t.content)}</span>`).join("") || "&nbsp;";
+    const lineRef = line.newNo != null ? `${file.path}:${line.newNo}` : `${file.path}:${line.oldNo} (old)`;
+    return `<tr class="${line.kind}" data-ref="${esc(lineRef)}">
+      <td class="g">${line.oldNo ?? ""}</td><td class="g">${line.newNo ?? ""}</td>
+      <td class="m">${line.kind === "add" ? "+" : line.kind === "del" ? "\u2212" : ""}</td>
+      <td class="c"><button class="lc" title="Comment on this line">\uFF0B</button>${codeHtml}</td>
+    </tr>`;
+  });
+  return `<div class="hunk ${CARD} my-3 overflow-hidden">
+    <div class="flex gap-3 border-b border-stone-200 bg-stone-100 px-3 py-1.5 font-mono text-xs dark:border-stone-800 dark:bg-stone-950/60">
+      <span class="font-semibold">${esc(file.path)}</span>
+      <span class="uppercase tracking-wider text-stone-400">${elided ? "excerpt" : ""}</span>
+      <span class="text-stone-400">${esc(hunk.header)}</span>
+    </div>
+    <table class="diff"><tbody>${rows.join("")}</tbody></table>
+  </div>`;
+}
+async function renderReport(results, files) {
+  const langs = [...new Set(files.map((f) => langFor(f.path)).filter((l) => l !== "text"))];
+  const hl = await createHighlighter({ themes: ["github-light", "github-dark"], langs });
+  const hunks = hunkById(files);
+  const anyDiagram = results.some(
+    (r) => r.analysis.diagram.trim() || r.analysis.sections.some((s) => s.diagram.trim())
+  );
+  const diagramCard = (source) => source.trim() ? `<div class="${CARD} my-4 p-4"><pre class="mermaid">${esc(source)}</pre></div>` : "";
+  const agentOptions = results.map((r, i) => `<option value="${i}">${esc(r.backend)}</option>`).join("");
+  const panels = results.map((r, i) => {
+    const toc = r.analysis.sections.map((s, si) => `<a class="text-indigo-600 hover:underline dark:text-indigo-400" href="#p${i}s${si}">${esc(s.heading)}</a>`).join("");
+    const sections = r.analysis.sections.map((s, si) => {
+      const snippets = s.snippets.map((sn) => {
+        const found = hunks.get(sn.hunk_id);
+        if (!found) return `<p class="text-sm italic text-stone-400">unknown hunk ${esc(sn.hunk_id)}</p>`;
+        const range = sn.from != null && sn.to != null ? { from: sn.from, to: sn.to } : null;
+        const note = sn.note.trim() ? `<p class="note mb-4 text-[13.5px] text-stone-500 dark:text-stone-400">${esc(sn.note).replace(/`([^`]+)`/g, "<code>$1</code>")}</p>` : "";
+        return renderHunk(hl, found.file, found.hunk, range) + note;
+      }).join("");
+      return `<section id="p${i}s${si}" data-ctx="${esc(s.heading)}" class="mt-10">
+            <h2 class="font-serif text-xl">${esc(s.heading)}</h2>
+            <div class="prose-x">${prose(s.intro)}</div>
+            ${diagramCard(s.diagram)}
+            ${snippets}
+          </section>`;
+    }).join("");
+    const notes = r.analysis.notes.length ? `<section data-ctx="Agent's notes" class="agent-notes mt-10">
+            <div class="flex items-baseline justify-between gap-4">
+              <h2 class="font-serif text-xl">Agent&#8217;s notes</h2>
+              <label class="flex cursor-pointer items-center gap-1.5 text-sm text-stone-500 dark:text-stone-400">
+                <input type="checkbox" class="include-notes accent-indigo-600"> Include in review
+              </label>
+            </div>
+            <ul class="mt-2 list-disc space-y-1 pl-5">${r.analysis.notes.map((n) => `<li>${esc(n).replace(/`([^`]+)`/g, "<code>$1</code>")}</li>`).join("")}</ul>
+          </section>` : "";
+    return `<div class="panel${i === 0 ? " active" : ""}" data-panel="${i}" data-backend="${esc(r.backend)}">
+        <div class="tldr ${CARD} p-5" data-ctx="TL;DR">
+          <span class="text-xs font-bold uppercase tracking-wider text-indigo-600 dark:text-indigo-400">TL;DR</span>
+          <div class="prose-x">${prose(r.analysis.summary)}</div>
+          ${r.analysis.sections.length > 1 ? `<nav class="mt-2 flex flex-wrap gap-x-4 gap-y-1 text-sm">${toc}</nav>` : ""}
+        </div>
+        ${diagramCard(r.analysis.diagram)}
+        ${sections}${notes}
+      </div>`;
+  }).join("");
+  const fullDiff = files.map((file) => {
+    const adds = file.hunks.reduce((n, h) => n + h.lines.filter((l) => l.kind === "add").length, 0);
+    const dels = file.hunks.reduce((n, h) => n + h.lines.filter((l) => l.kind === "del").length, 0);
+    const body = file.status === "binary" ? `<p class="text-sm italic text-stone-400">binary file</p>` : file.hunks.map((h) => renderHunk(hl, file, h)).join("");
+    return `<details class="my-2" data-ctx="Full diff: ${esc(file.path)}">
+        <summary class="${CARD} flex cursor-pointer items-baseline gap-3 px-3 py-2">
+          <span class="flex-1 font-mono text-sm font-semibold">${esc(file.path)}</span>
+          <span class="text-xs text-stone-500">
+            <b class="font-semibold text-emerald-600 dark:text-emerald-400">+${adds}</b>
+            <b class="font-semibold text-red-600 dark:text-red-400">\u2212${dels}</b>${file.status !== "modified" ? ` \xB7 ${file.status}` : ""}</span>
+        </summary>
+        ${body}
+      </details>`;
+  }).join("");
+  const title = results[0].analysis.title;
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(title)} \u2014 semantic-review</title>
+<script src="https://cdn.tailwindcss.com"></script>
+<style>
+/* Custom layer for what Tailwind doesn't cover cleanly: diff tables, shiki
+   dual themes, brevity-level visibility, and the dynamic comment UI. */
+:root { --add-bg: #dafbe1; --del-bg: #ffebe9; color-scheme: light dark; }
+@media (prefers-color-scheme: dark) {
+  :root { --add-bg: #12261e; --del-bg: #2d1214; }
+  .diff span[style] { color: var(--shiki-dark, inherit) !important; }
+}
+.prose-x p { margin: 6px 0; }
+code { background: rgb(245 245 244 / .8); border: 1px solid rgb(214 211 209); border-radius: 4px;
+  padding: 1px 4px; font: 12.5px ui-monospace, SFMono-Regular, Menlo, monospace; }
+@media (prefers-color-scheme: dark) { code { background: rgb(28 25 23); border-color: rgb(41 37 36); } }
+.panel { display: none; } .panel.active { display: block; }
+/* Brevity levels: tldr = summary + notes; walk = + sections; full = full diff only */
+body.level-tldr section { display: none; }
+body.level-tldr section[data-ctx="Agent's notes"] { display: block; }
+body.level-tldr #fulldiff, body.level-walk #fulldiff { display: none; }
+body.level-full .panel.active, body.level-full #agent { display: none; }
+.levels button.active { background: rgb(231 229 228); color: inherit; font-weight: 600; }
+@media (prefers-color-scheme: dark) { .levels button.active { background: rgb(41 37 36); } }
+.diff { width: 100%; border-collapse: collapse; font: 12.5px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace; }
+.diff td { padding: 0 8px; white-space: pre-wrap; word-break: break-all; vertical-align: top; }
+.diff .g { width: 1%; min-width: 34px; text-align: right; color: rgb(168 162 158); user-select: none;
+  white-space: nowrap; word-break: normal; }
+.diff .m { width: 1%; user-select: none; color: rgb(168 162 158); }
+.diff tr.add td { background: var(--add-bg); } .diff tr.del td { background: var(--del-bg); }
+.diff .c { position: relative; padding-left: 26px; }
+.lc { position: absolute; left: 2px; top: 1px; width: 18px; height: 18px; border-radius: 4px; border: 0;
+  background: #4f46e5; color: #fff; font-size: 12px; line-height: 1; cursor: pointer;
+  opacity: 0; transition: opacity .1s; padding: 0; }
+tr:hover .lc { opacity: 1; }
+.mermaid { display: flex; justify-content: center; }
+#bubble { position: absolute; display: none; z-index: 10; background: #4f46e5; color: #fff; border: 0;
+  border-radius: 6px; padding: 5px 10px; font-size: 13px; cursor: pointer; box-shadow: 0 2px 8px rgba(0,0,0,.25); }
+#composer blockquote, .comment-card blockquote { margin: 6px 0 8px; padding: 4px 8px;
+  border-left: 3px solid #4f46e5; font: 11.5px ui-monospace, Menlo, monospace;
+  white-space: pre-wrap; word-break: break-all; max-height: 90px; overflow: auto; }
+.comment-card blockquote { border-left-color: rgb(214 211 209); color: rgb(120 113 108); overflow: hidden; }
+</style>
+</head>
+<body class="level-walk bg-stone-50 font-sans text-slate-900 dark:bg-stone-950 dark:text-stone-100">
+<header class="sticky top-0 z-20 flex items-center gap-3 border-b border-stone-200 bg-stone-50/90 px-6 py-2.5 backdrop-blur dark:border-stone-800 dark:bg-stone-950/90">
+  <span class="text-sm text-stone-400">semantic-review</span>
+  <h1 class="flex-1 truncate font-serif text-lg">${esc(title)}</h1>
+  ${results.length > 1 ? `<select id="agent" title="Analysis by" class="rounded-lg border border-stone-200 bg-white px-2 py-1.5 text-sm dark:border-stone-800 dark:bg-stone-900">${agentOptions}</select>` : ""}
+  <div class="levels inline-flex overflow-hidden rounded-lg border border-stone-200 text-sm text-stone-500 dark:border-stone-800 dark:text-stone-400">
+    <button data-level="tldr" class="border-r border-stone-200 px-3.5 py-1.5 dark:border-stone-800">TL;DR</button>
+    <button data-level="walk" class="active border-r border-stone-200 px-3.5 py-1.5 dark:border-stone-800">Walkthrough</button>
+    <button data-level="full" class="px-3.5 py-1.5">Full diff</button>
+  </div>
+  <button id="done" class="rounded-lg bg-indigo-600 px-4 py-1.5 text-sm font-semibold text-white hover:bg-indigo-700">Done</button>
+</header>
+<main class="grid grid-cols-[minmax(0,1fr)_320px]">
+  <div id="report" class="max-w-4xl px-7 pb-24 pt-6">
+    ${panels}
+    <div id="fulldiff" data-ctx="Full diff">
+      ${fullDiff}
+    </div>
+  </div>
+  <aside class="sticky top-[53px] h-[calc(100vh-53px)] overflow-y-auto border-l border-stone-200 p-4 dark:border-stone-800">
+    <h3 class="mb-2 text-xs font-bold uppercase tracking-wider text-stone-400">Comments</h3>
+    <div id="comments"><p id="empty" class="text-sm text-stone-400">Select any text or hover a line and hit \uFF0B to comment.</p></div>
+    <h3 class="mb-2 mt-6 text-xs font-bold uppercase tracking-wider text-stone-400">Overall</h3>
+    <textarea id="overall" placeholder="Optional overall feedback\u2026" class="min-h-[70px] w-full resize-y rounded-lg border border-stone-200 bg-white p-2 text-sm dark:border-stone-800 dark:bg-stone-900"></textarea>
+  </aside>
+</main>
+<button id="bubble">\u{1F4AC} Comment</button>
+<div id="composer" class="fixed bottom-5 right-[340px] z-30 hidden w-[380px] rounded-xl border border-stone-200 bg-white p-3 shadow-2xl dark:border-stone-800 dark:bg-stone-900">
+  <div class="ref mb-1.5 font-mono text-[11px] text-stone-400 [word-break:break-all]"></div>
+  <blockquote></blockquote>
+  <textarea placeholder="Write a comment\u2026 (\u2318\u23CE to save)" class="min-h-[80px] w-full resize-y rounded-lg border border-stone-200 bg-white p-2 text-sm dark:border-stone-700 dark:bg-stone-950"></textarea>
+  <div class="mt-2 flex justify-end gap-2 text-sm">
+    <button class="cancel rounded-lg border border-stone-200 px-3 py-1 dark:border-stone-700">Cancel</button>
+    <button class="save rounded-lg bg-indigo-600 px-3 py-1 font-semibold text-white">Save</button>
+  </div>
+</div>
+<div id="finished" class="hidden px-5 py-24 text-center">
+  <h2 class="font-serif text-2xl">Review sent \u2713</h2>
+  <p class="mt-2 text-stone-500">Feedback was delivered back to the agent. You can close this tab.</p>
+</div>
+<script type="module">
+${anyDiagram ? `import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+mermaid.initialize({
+  startOnLoad: false,
+  theme: matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "neutral",
+  securityLevel: "loose",
+});
+async function renderDiagrams() {
+  const nodes = [...document.querySelectorAll(".panel.active .mermaid:not([data-processed])")];
+  if (nodes.length) await mermaid.run({ nodes }).catch(console.error);
+}
+renderDiagrams();` : `function renderDiagrams() {}`}
+
+const comments = [];
+const $ = (s, el) => (el || document).querySelector(s);
+const multiTab = ${results.length > 1 ? "true" : "false"};
+
+// Agent selector
+const agentSelect = $("#agent");
+if (agentSelect) agentSelect.addEventListener("change", () => {
+  document.querySelectorAll(".panel").forEach(p =>
+    p.classList.toggle("active", p.dataset.panel === agentSelect.value));
+  renderDiagrams();
+});
+
+// Brevity levels
+document.querySelectorAll(".levels button").forEach(btn => btn.addEventListener("click", () => {
+  document.querySelectorAll(".levels button").forEach(b => b.classList.toggle("active", b === btn));
+  document.body.className = document.body.className.replace(/level-\\w+/, "level-" + btn.dataset.level);
+  renderDiagrams();
+}));
+
+function currentBackend() {
+  const panel = $(".panel.active");
+  return panel ? panel.dataset.backend : "";
+}
+
+// Comment composer
+const composer = $("#composer");
+let pending = null;
+function openComposer(ref, quote) {
+  pending = { ref, quote, backend: currentBackend() };
+  $(".ref", composer).textContent = ref;
+  $("blockquote", composer).textContent = quote || "";
+  $("blockquote", composer).style.display = quote ? "" : "none";
+  $("textarea", composer).value = "";
+  composer.style.display = "block";
+  $("textarea", composer).focus();
+}
+function closeComposer() { composer.style.display = "none"; pending = null; }
+$(".cancel", composer).addEventListener("click", closeComposer);
+function saveComment() {
+  const text = $("textarea", composer).value.trim();
+  if (!text || !pending) return;
+  comments.push({ ...pending, text });
+  closeComposer();
+  renderComments();
+}
+$(".save", composer).addEventListener("click", saveComment);
+$("textarea", composer).addEventListener("keydown", e => {
+  if ((e.metaKey || e.ctrlKey) && e.key === "Enter") saveComment();
+  if (e.key === "Escape") closeComposer();
+});
+
+function renderComments() {
+  const box = $("#comments");
+  if (!comments.length) { box.innerHTML = '<p id="empty" class="text-sm text-stone-400">Select any text or hover a line and hit \uFF0B to comment.</p>'; return; }
+  box.innerHTML = "";
+  comments.forEach((c, i) => {
+    const card = document.createElement("div");
+    card.className = "comment-card mb-2.5 rounded-lg border border-stone-200 bg-white p-2.5 text-sm dark:border-stone-800 dark:bg-stone-900";
+    const ref = document.createElement("div");
+    ref.className = "font-mono text-[11px] text-stone-400 [word-break:break-all]";
+    ref.textContent = (multiTab && c.backend ? "[" + c.backend + "] " : "") + c.ref;
+    const del = document.createElement("button");
+    del.className = "float-right text-stone-400 hover:text-stone-600";
+    del.textContent = "\u2715";
+    del.addEventListener("click", () => { comments.splice(i, 1); renderComments(); });
+    card.append(del, ref);
+    if (c.quote) { const q = document.createElement("blockquote"); q.textContent = c.quote; card.append(q); }
+    const body = document.createElement("div"); body.textContent = c.text; card.append(body);
+    box.append(card);
+  });
+}
+
+// Line comments
+document.querySelectorAll(".lc").forEach(btn => btn.addEventListener("click", e => {
+  e.stopPropagation();
+  const tr = btn.closest("tr");
+  openComposer(tr.dataset.ref, tr.querySelector(".c").textContent.replace(/^\uFF0B/, ""));
+}));
+
+// Selection comments
+const bubble = $("#bubble");
+document.addEventListener("mouseup", e => {
+  if (composer.contains(e.target) || bubble.contains(e.target)) return;
+  setTimeout(() => {
+    const sel = window.getSelection();
+    if (!sel || sel.isCollapsed || !sel.toString().trim()) { bubble.style.display = "none"; return; }
+    const rect = sel.getRangeAt(0).getBoundingClientRect();
+    bubble.style.display = "block";
+    bubble.style.left = Math.max(8, rect.left + window.scrollX) + "px";
+    bubble.style.top = (rect.bottom + window.scrollY + 6) + "px";
+  }, 0);
+});
+bubble.addEventListener("click", () => {
+  const sel = window.getSelection();
+  if (!sel || sel.isCollapsed) return;
+  const quote = sel.toString().trim();
+  let node = sel.anchorNode;
+  if (node && node.nodeType === Node.TEXT_NODE) node = node.parentElement;
+  const tr = node && node.closest ? node.closest("tr[data-ref]") : null;
+  const section = node && node.closest ? node.closest("[data-ctx]") : null;
+  const ref = tr ? tr.dataset.ref : section ? "\xA7 " + section.dataset.ctx : "report";
+  bubble.style.display = "none";
+  sel.removeAllRanges();
+  openComposer(ref, quote);
+});
+
+// Done
+$("#done").addEventListener("click", async () => {
+  const notes = [...document.querySelectorAll(".include-notes:checked")].map((cb) => {
+    const panel = cb.closest(".panel");
+    return {
+      backend: panel.dataset.backend,
+      items: [...panel.querySelectorAll(".agent-notes li")].map((li) => li.textContent.trim()),
+    };
+  });
+  const payload = { comments, overall: $("#overall").value.trim(), notes };
+  await fetch("/done", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(payload) });
+  $("main").style.display = "none";
+  $("#finished").style.display = "block";
+});
+</script>
+</body>
+</html>`;
+}
+
+// src/server.ts
+import { createServer } from "node:http";
+import { spawn as spawn2 } from "node:child_process";
+function serveReview(html, openBrowser) {
+  return new Promise((resolve) => {
+    const server = createServer((req, res) => {
+      const path = new URL(req.url ?? "/", "http://127.0.0.1").pathname;
+      if (path === "/" && req.method === "GET") {
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(html);
+        return;
+      }
+      if (path === "/done" && req.method === "POST") {
+        let body = "";
+        req.setEncoding("utf8");
+        req.on("data", (chunk) => body += chunk);
+        req.on("end", () => {
+          const result = JSON.parse(body);
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ ok: true }), () => {
+            server.close();
+            server.closeAllConnections();
+            resolve({ comments: result.comments ?? [], overall: result.overall ?? "", notes: result.notes ?? [] });
+          });
+        });
+        return;
+      }
+      res.writeHead(404);
+      res.end("not found");
+    });
+    server.listen(0, "127.0.0.1", () => {
+      const { port } = server.address();
+      const url = `http://127.0.0.1:${port}/`;
+      console.error(`semantic-review: review at ${url} \u2014 waiting for Done\u2026`);
+      if (openBrowser) {
+        const opener = process.platform === "darwin" ? "open" : "xdg-open";
+        spawn2(opener, [url], { stdio: "ignore" }).on("error", () => {
+        });
+      }
+    });
+  });
+}
+function formatReview(result, multiTab) {
+  const lines = [];
+  const notes = result.notes ?? [];
+  if (result.comments.length === 0 && !result.overall) {
+    lines.push("Review complete: approved, no comments.");
+  } else {
+    lines.push(`Review feedback (${result.comments.length} comment${result.comments.length === 1 ? "" : "s"}):`);
+    result.comments.forEach((c, i) => {
+      const tag = multiTab && c.backend ? `[${c.backend}] ` : "";
+      lines.push("", `${i + 1}. ${tag}${c.ref}`);
+      if (c.quote) lines.push(...c.quote.split("\n").map((q) => `   > ${q}`));
+      lines.push(...c.text.split("\n").map((t) => `   ${t}`));
+    });
+    if (result.overall) lines.push("", `Overall: ${result.overall}`);
+  }
+  for (const n of notes) {
+    lines.push("", multiTab ? `Agent's notes [${n.backend}]:` : "Agent's notes:");
+    lines.push(...n.items.map((item) => `- ${item}`));
+  }
+  return lines.join("\n");
+}
+
+// src/cli.ts
+var USAGE = `usage: semantic-review [options] [git diff args...]
+
+Reads the diff from stdin if piped, otherwise runs \`git diff <args>\`
+(default: git diff HEAD). Prints the human's review feedback to stdout.
+
+options:
+  --with <backend,...>   backends: ${Object.keys(BACKENDS).join(", ")} (default: auto-detect)
+  --model <id>           model for the anthropic backend (default: claude-opus-5,
+                         env SEMANTIC_REVIEW_MODEL; e.g. claude-sonnet-5, claude-haiku-4-5)
+  --effort <level>       low|medium|high|xhigh|max (anthropic backend; default: API default)
+  --no-open              don't open the browser
+
+examples:
+  semantic-review                      review uncommitted changes
+  semantic-review main...HEAD          review a branch
+  git diff -U10 | semantic-review      review a piped diff with more context
+  semantic-review --with anthropic,codex   two analyses, tabbed
+  semantic-review --model claude-sonnet-5 --effort medium   cheaper/faster analysis`;
+async function getDiff(gitArgs) {
+  if (!process.stdin.isTTY) {
+    let piped = "";
+    for await (const chunk of process.stdin.setEncoding("utf8")) piped += chunk;
+    if (piped.trim()) return piped;
+  }
+  const args = gitArgs.length > 0 ? gitArgs : ["HEAD"];
+  const { stdout, stderr, code } = await run(["git", "diff", "--no-color", ...args]);
+  if (code !== 0) throw new Error(`git diff failed: ${stderr.trim()}`);
+  return stdout;
+}
+async function main() {
+  const argv = process.argv.slice(2);
+  const gitArgs = [];
+  let withBackends = null;
+  let openBrowser = true;
+  let model;
+  let effort;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") {
+      console.log(USAGE);
+      return;
+    } else if (arg === "--no-open") {
+      openBrowser = false;
+    } else if (arg === "--with") {
+      withBackends = (argv[++i] ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+    } else if (arg === "--model") {
+      model = argv[++i];
+    } else if (arg === "--effort") {
+      const level = argv[++i];
+      if (!["low", "medium", "high", "xhigh", "max"].includes(level ?? "")) {
+        throw new Error(`invalid --effort "${level}" (low|medium|high|xhigh|max)`);
+      }
+      effort = level;
+    } else {
+      gitArgs.push(arg);
+    }
+  }
+  const diff = await getDiff(gitArgs);
+  const files = parseDiff(diff);
+  const hunkCount = files.reduce((n, f) => n + f.hunks.length, 0);
+  if (hunkCount === 0) {
+    console.error("semantic-review: no changes to review");
+    process.exit(1);
+  }
+  const backends = await resolveBackends(withBackends);
+  console.error(
+    `semantic-review: analyzing ${hunkCount} hunk${hunkCount === 1 ? "" : "s"} across ${files.length} file${files.length === 1 ? "" : "s"} with ${backends.map((b) => b.name).join(", ")}\u2026`
+  );
+  const annotated = diffForModel(files);
+  const results = await runBackends(backends, annotated, { model, effort });
+  const html = await renderReport(results, files);
+  const review = await serveReview(html, openBrowser);
+  console.log(formatReview(review, results.length > 1));
+}
+main().catch((err) => {
+  console.error(`semantic-review: ${err.message ?? err}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "semantic-review",
+  "version": "0.1.0",
+  "description": "Semantic diff review for coding agents: an LLM turns a git diff into a narrative HTML report, a human comments on it, and the feedback comes back as plaintext.",
+  "type": "module",
+  "license": "MIT",
+  "repository": "github:mikker/semantic-review",
+  "bin": {
+    "semantic-review": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "semantic-review.webp"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "esbuild src/cli.ts --bundle --packages=external --platform=node --format=esm --outfile=dist/cli.js",
+    "prepublishOnly": "npm run build",
+    "test": "bun test",
+    "eval": "bun evals/run.ts",
+    "typecheck": "bunx tsc --noEmit"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.74.0",
+    "shiki": "^3.13.0",
+    "zod": "^4"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.0",
+    "esbuild": "^0.28.1",
+    "typescript": "^5.9.0"
+  }
+}