comprehende 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Máté Molnár
+
+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,94 @@
+# Comprehende
+
+Local review assistant for git diffs. Groups changes by review concern and shows them in a fixed UI. Diffs always come from git in the repo you run the CLI in — never from the model, never stored in the review document. The review UI paints `git diff` output with [`@pierre/diffs`](https://diffs.com), the same renderer [T3 Code](https://github.com/pingdotgg/t3code) uses. Full file and blame views use Pierre’s file renderer from `git show` / `git blame`.
+
+Product intent: [AGENTS.md](./AGENTS.md). Implementation plan: [PLAN.md](./PLAN.md).
+
+## Install
+
+Node.js 24+. Run the CLI **inside** the repository you want to review. There is no `--repo` flag.
+
+```sh
+npx comprehende@0.1.0 index --base origin/main
+npx comprehende@0.1.0 validate --data review.json
+npx comprehende@0.1.0 serve --data review.json --open
+```
+
+Pin the version. After a release, that version is on npm.
+
+## Review a clone
+
+```sh
+git clone <url>
+cd <repo>
+
+npx comprehende@0.1.0 index --base origin/main
+# write review.json from those hunk refs (the skill does this)
+
+npx comprehende@0.1.0 validate --data review.json
+npx comprehende@0.1.0 serve --data review.json --open
+```
+
+Three-dot range (`base...head`) is the merge-request / branch diff. `--base` defaults to `origin/HEAD` (or `main`/`master`). `--head` defaults to `HEAD`. `serve` binds `127.0.0.1` only and re-reads git on every request.
+
+## Install the skill
+
+From this checkout:
+
+```sh
+npx skills add ./ --skill comprehende
+```
+
+Once the package is on npm:
+
+```sh
+npx skills add matemolnar8/comprehende
+```
+
+The skill is the agent workflow: `index` → read the git diffs → write `review.json` (refs + summaries only) → `validate` → `serve`. Edit `src/schema/review.schema.json` and run `pnpm sync:skill` so the copy in the skill folder stays identical.
+
+## Commands
+
+```
+comprehende index [--base <ref>] [--head <ref>]
+comprehende validate --data <review.json>
+comprehende serve --data <review.json> [--port] [--open]
+```
+
+Defaults: `--head HEAD`, `--base` is `origin/HEAD` (or `main`/`master`).
+
+## Develop
+
+[pnpm](https://pnpm.io/).
+
+```sh
+pnpm install
+pnpm test
+pnpm typecheck
+pnpm build
+pnpm pack:smoke
+pnpm sync:skill
+pnpm dev -- --help
+```
+
+`pnpm build` emits `dist/cli` and `dist/ui`. `prepack` runs that build, so `pnpm pack` / `pnpm publish` always ship the UI.
+
+`pnpm dev` and `pnpm exec` run with this package as cwd, so they only make sense when *this* repo is the one under review. To review a different project from a checkout, `cd` into it and run `npx comprehende@0.1.0` (or `node /path/to/comprehende/dist/cli/main.js` after `pnpm build`).
+
+## Release
+
+Bump `version` in `package.json` when the CLI or UI changes. Do not bump it for skill-only edits.
+
+Push to `main`. CI packs and tests the tarball on every change. If the version is not on npm yet, CI publishes it. Skill-only commits keep the same version, so they do not publish.
+
+The first publish is manual (`pnpm publish --access public`) so you can claim the name. After that, add a GitHub Actions trusted publisher on npmjs.com for workflow `ci.yml`.
+
+## Fixture
+
+```sh
+pnpm fixture
+cd fixtures/repo
+node ../../dist/cli/main.js serve --data ../example/review.json
+```
+
+`pnpm fixture` writes a tiny git repo to `fixtures/repo` (gitignored) and a refs-only `fixtures/example/review.json`. Serve with cwd set to `fixtures/repo`.

package/dist/cli/args.d.ts

@@ -0,0 +1,20 @@
+export type CommandName = "index" | "validate" | "serve";
+export type CliRequest = {
+    kind: "help";
+} | {
+    kind: "version";
+} | {
+    kind: "error";
+    message: string;
+} | {
+    kind: "command";
+    command: CommandName;
+    cwd: string;
+    base?: string;
+    head?: string;
+    data?: string;
+    port: number;
+    open: boolean;
+};
+export declare const USAGE = "Usage: comprehende <command> [options]\n\nRun inside the git repository under review. Cwd is the repo.\n\nCommands:\n  index     [--base <ref>] [--head <ref>]\n            List hunk refs from live git (no patch text)\n\n  validate  --data <review.json>\n            Check schema, ref resolution, and hunk coverage\n\n  serve     --data <review.json> [--port <n>] [--open]\n            Serve the local UI on 127.0.0.1 (re-reads git on each request)\n\nOptions:\n  --base <ref>     Base ref (default: origin/HEAD or main/master)\n  --head <ref>     Head ref (default: HEAD)\n  --data <path>    Review document path\n  --port <n>       Listen port (default: 4567, 0 for ephemeral)\n  --open           Open the UI in a browser\n  -h, --help       Show this help\n  -v, --version    Show version\n\nDiffs always come from git in cwd. The review document is interpretation only.\n";
+export declare function parseArgv(argv: string[], cwd?: string): CliRequest;

package/dist/cli/args.js

@@ -0,0 +1,89 @@
+const COMMANDS = new Set(["index", "validate", "serve"]);
+export const USAGE = `Usage: comprehende <command> [options]
+
+Run inside the git repository under review. Cwd is the repo.
+
+Commands:
+  index     [--base <ref>] [--head <ref>]
+            List hunk refs from live git (no patch text)
+
+  validate  --data <review.json>
+            Check schema, ref resolution, and hunk coverage
+
+  serve     --data <review.json> [--port <n>] [--open]
+            Serve the local UI on 127.0.0.1 (re-reads git on each request)
+
+Options:
+  --base <ref>     Base ref (default: origin/HEAD or main/master)
+  --head <ref>     Head ref (default: HEAD)
+  --data <path>    Review document path
+  --port <n>       Listen port (default: 4567, 0 for ephemeral)
+  --open           Open the UI in a browser
+  -h, --help       Show this help
+  -v, --version    Show version
+
+Diffs always come from git in cwd. The review document is interpretation only.
+`;
+export function parseArgv(argv, cwd = process.cwd()) {
+    const args = argv[0] === "--" ? argv.slice(1) : [...argv];
+    if (args.length === 0 || args.includes("-h") || args.includes("--help")) {
+        return { kind: "help" };
+    }
+    if (args.includes("-v") || args.includes("--version")) {
+        return { kind: "version" };
+    }
+    const command = args[0];
+    if (command === undefined) {
+        return { kind: "help" };
+    }
+    if (!isCommand(command)) {
+        return { kind: "error", message: `Unknown command: ${command}\n\n${USAGE}` };
+    }
+    const rest = args.slice(1);
+    try {
+        const port = Number(flag(rest, "--port") ?? "4567");
+        if (!Number.isInteger(port) || port < 0) {
+            throw new Error("--port must be a non-negative integer");
+        }
+        return {
+            kind: "command",
+            command,
+            cwd,
+            base: flag(rest, "--base"),
+            head: flag(rest, "--head"),
+            data: flag(rest, "--data"),
+            port,
+            open: rest.includes("--open"),
+        };
+    }
+    catch (error) {
+        return { kind: "error", message: error instanceof Error ? error.message : String(error) };
+    }
+}
+function isCommand(value) {
+    return COMMANDS.has(value);
+}
+function flag(args, name) {
+    const prefix = `${name}=`;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === undefined) {
+            continue;
+        }
+        if (arg === name) {
+            const value = args[i + 1];
+            if (value === undefined || value.startsWith("-")) {
+                throw new Error(`${name} requires a value`);
+            }
+            return value;
+        }
+        if (arg.startsWith(prefix)) {
+            const value = arg.slice(prefix.length);
+            if (value === "") {
+                throw new Error(`${name} requires a value`);
+            }
+            return value;
+        }
+    }
+    return undefined;
+}

package/dist/cli/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands.d.ts

@@ -0,0 +1,12 @@
+import type { HunkIndex, ReviewDocument } from "../schema/types.ts";
+export declare function resolveRange(cwd: string, base: string | undefined, head: string | undefined): Promise<{
+    baseRef: string;
+    headRef: string;
+}>;
+export declare function cmdIndex(cwd: string, base: string | undefined, head: string | undefined): Promise<HunkIndex>;
+export declare function loadDocument(dataPath: string): Promise<ReviewDocument>;
+export declare function resolveDataPath(data: string | undefined, cwd: string): string;
+export declare function cmdValidate(cwd: string, dataPath: string): Promise<{
+    document: ReviewDocument;
+    warnings: string[];
+}>;

package/dist/cli/commands.js

@@ -0,0 +1,40 @@
+import { readFile } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import { readHunkIndex, resolveSource } from "../git/diff.js";
+import { defaultBaseRef } from "../git/repo.js";
+import { coverReview, coverageErrors } from "../review/coverage.js";
+import { parseReviewJson } from "../schema/parse.js";
+export async function resolveRange(cwd, base, head) {
+    const baseRef = base ?? (await defaultBaseRef(cwd));
+    const headRef = head ?? "HEAD";
+    await resolveSource(cwd, baseRef, headRef);
+    return { baseRef, headRef };
+}
+export async function cmdIndex(cwd, base, head) {
+    const range = await resolveRange(cwd, base, head);
+    return readHunkIndex(cwd, range.baseRef, range.headRef);
+}
+export async function loadDocument(dataPath) {
+    const text = await readFile(dataPath, "utf8");
+    const parsed = parseReviewJson(text);
+    if (!parsed.ok) {
+        throw new Error(`invalid review document:\n${parsed.errors.map((error) => `  - ${error}`).join("\n")}`);
+    }
+    return parsed.document;
+}
+export function resolveDataPath(data, cwd) {
+    if (data === undefined) {
+        throw new Error("missing --data <review.json>");
+    }
+    return isAbsolute(data) ? data : resolve(cwd, data);
+}
+export async function cmdValidate(cwd, dataPath) {
+    const document = await loadDocument(dataPath);
+    await resolveSource(cwd, document.source.baseRef, document.source.headRef);
+    const { coverage } = await coverReview(cwd, document);
+    const errors = coverageErrors(coverage);
+    if (errors.length > 0) {
+        throw new Error(errors.join("\n\n"));
+    }
+    return { document, warnings: [] };
+}

package/dist/cli/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../../src/cli/commands.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGrD,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,GAAW,EACX,IAAwB,EACxB,IAAwB;IAExB,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,MAAM,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;IACpD,MAAM,OAAO,GAAG,IAAI,IAAI,MAAM,CAAC;IAC/B,MAAM,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC3C,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC9B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,GAAW,EAAE,IAAwB,EAAE,IAAwB;IAC5F,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAClD,OAAO,aAAa,CAAC,GAAG,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,QAAgB;IACjD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,6BAA6B,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1G,CAAC;IACD,OAAO,MAAM,CAAC,QAAQ,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAwB,EAAE,GAAW;IACnE,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAW,EAAE,QAAgB;IAC7D,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC9C,MAAM,aAAa,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC3E,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,WAAW,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACtD,MAAM,MAAM,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IACxC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AACpC,CAAC"}

package/dist/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function run(argv: string[]): Promise<number>;

package/dist/cli/main.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgv, USAGE } from "./args.js";
+import { cmdIndex, cmdValidate, loadDocument, resolveDataPath } from "./commands.js";
+import { resolveSource } from "../git/diff.js";
+import { coverReview, coverageErrors } from "../review/coverage.js";
+import { assertWorkTree } from "../git/repo.js";
+import { readPackageVersion } from "../package-root.js";
+import { startServer } from "../server/http.js";
+export async function run(argv) {
+    const request = parseArgv(argv);
+    if (request.kind === "help") {
+        console.log(USAGE);
+        return 0;
+    }
+    if (request.kind === "version") {
+        console.log(readPackageVersion());
+        return 0;
+    }
+    if (request.kind === "error") {
+        console.error(request.message);
+        return 1;
+    }
+    try {
+        await assertWorkTree(request.cwd);
+        switch (request.command) {
+            case "index": {
+                const index = await cmdIndex(request.cwd, request.base, request.head);
+                console.log(JSON.stringify(index, null, 2));
+                return 0;
+            }
+            case "validate": {
+                const dataPath = resolveDataPath(request.data, request.cwd);
+                const { document } = await cmdValidate(request.cwd, dataPath);
+                const hunks = document.groups.reduce((sum, group) => sum + group.hunkRefs.length, 0);
+                console.log(`ok  ${document.groups.length} groups  ${hunks} hunk refs  ${dataPath}`);
+                return 0;
+            }
+            case "serve": {
+                const dataPath = resolveDataPath(request.data, request.cwd);
+                const document = await loadDocument(dataPath);
+                await resolveSource(request.cwd, document.source.baseRef, document.source.headRef);
+                const { coverage } = await coverReview(request.cwd, document);
+                const problems = coverageErrors(coverage);
+                if (problems.length > 0) {
+                    console.error(`coverage issues (serve continues; git wins, unassigned/stale are visible):\n${problems.join("\n\n")}`);
+                }
+                const running = await startServer({ cwd: request.cwd, dataPath, port: request.port });
+                console.log(running.url);
+                console.error(`serving ${dataPath}  cwd=${request.cwd}  localhost only`);
+                if (request.open) {
+                    openUrl(running.url);
+                }
+                await waitForClose(running.server);
+                return 0;
+            }
+        }
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}
+function waitForClose(server) {
+    return new Promise((resolve) => {
+        const shutdown = () => {
+            server.close(() => resolve());
+        };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
+        server.on("close", () => resolve());
+    });
+}
+function openUrl(url) {
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    spawn(command, args, { stdio: "ignore", detached: true }).unref();
+}
+const thisFile = fileURLToPath(import.meta.url);
+if (isCliEntry(thisFile, process.argv[1])) {
+    process.exitCode = await run(process.argv.slice(2));
+}
+export function isCliEntry(modulePath, argv1) {
+    if (argv1 === undefined) {
+        return false;
+    }
+    try {
+        if (realpathSync(modulePath) === realpathSync(argv1)) {
+            return true;
+        }
+    }
+    catch {
+        // argv[1] may not exist as a real path (tsx, some shims)
+    }
+    const entry = resolve(argv1).replaceAll("\\", "/");
+    return (/(?:^|\/)src\/cli\/main\.ts$/.test(entry) ||
+        /(?:^|\/)dist\/cli\/main\.js$/.test(entry) ||
+        /(?:^|\/)comprehende$/.test(entry));
+}

package/dist/cli/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"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"}

package/dist/git/blame.d.ts

@@ -0,0 +1,8 @@
+export type BlameLine = {
+    sha: string;
+    author: string;
+    timestamp: number;
+    line: number;
+    text: string;
+};
+export declare function blameFile(cwd: string, ref: string, path: string): Promise<BlameLine[]>;

package/dist/git/blame.js

@@ -0,0 +1,36 @@
+import { assertSafePath, assertSafeRef } from "./repo.js";
+import { git } from "./exec.js";
+export async function blameFile(cwd, ref, path) {
+    assertSafeRef(ref);
+    assertSafePath(path);
+    const stdout = await git(cwd, ["blame", "--line-porcelain", ref, "--", path]);
+    return parseBlamePorcelain(stdout);
+}
+function parseBlamePorcelain(text) {
+    const lines = [];
+    const raw = text.split("\n");
+    let sha = "";
+    let author = "";
+    let timestamp = 0;
+    let lineNo = 0;
+    for (const line of raw) {
+        const header = /^([0-9a-f]{40}) (\d+) (\d+)(?: (\d+))?$/.exec(line);
+        if (header && header[1] !== undefined && header[3] !== undefined) {
+            sha = header[1];
+            lineNo = Number(header[3]);
+            continue;
+        }
+        if (line.startsWith("author ")) {
+            author = line.slice("author ".length);
+            continue;
+        }
+        if (line.startsWith("author-time ")) {
+            timestamp = Number(line.slice("author-time ".length));
+            continue;
+        }
+        if (line.startsWith("\t")) {
+            lines.push({ sha, author, timestamp, line: lineNo, text: line.slice(1) });
+        }
+    }
+    return lines;
+}

package/dist/git/blame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blame.js","sourceRoot":"","sources":["../../src/git/blame.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAUhC,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAW,EAAE,GAAW,EAAE,IAAY;IACpE,aAAa,CAAC,GAAG,CAAC,CAAC;IACnB,cAAc,CAAC,IAAI,CAAC,CAAC;IACrB,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,kBAAkB,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;IAC9E,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC;AACrC,CAAC;AAED,SAAS,mBAAmB,CAAC,IAAY;IACvC,MAAM,KAAK,GAAgB,EAAE,CAAC;IAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,IAAI,IAAI,GAAG,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,yCAAyC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpE,IAAI,MAAM,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;YACjE,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;YAChB,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3B,SAAS;QACX,CAAC;QACD,IAAI,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC/B,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YACtC,SAAS;QACX,CAAC;QACD,IAAI,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;YACpC,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC;YACtD,SAAS;QACX,CAAC;QACD,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC5E,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/git/diff.d.ts

@@ -0,0 +1,13 @@
+import type { DiffFile, HunkIndex, HunkRef, LiveHunk, ReviewSource } from "../schema/types.ts";
+export declare function resolveSource(cwd: string, baseRef: string, headRef: string): Promise<{
+    source: ReviewSource;
+    baseSha: string;
+    headSha: string;
+}>;
+export declare function readDiff(cwd: string, baseRef: string, headRef: string): Promise<DiffFile[]>;
+export declare function readHunkIndex(cwd: string, baseRef: string, headRef: string): Promise<HunkIndex>;
+export declare function toHunkRef(hunk: HunkRef): HunkRef;
+export declare function parseUnifiedDiff(text: string): DiffFile[];
+export declare function filePatchFromGit(file: DiffFile, hunks: LiveHunk[]): string;
+export declare function flattenHunks(files: DiffFile[]): LiveHunk[];
+export declare function fileLanguage(path: string): string;