co-maintainer 0.4.0-beta.1

package/dist/src/local/git_revision.js

@@ -0,0 +1,141 @@
+import { resolveDefaultBranchName } from "../git/default_branch.js";
+import { normalizePath, } from "../review/revision.js";
+import { parseNameStatusZ, parseNumstatZ, pathsMissingPatches, splitDiffPatches, } from "./git_parse.js";
+import { revisionFileFromUntracked, } from "./git_untracked.js";
+import { ReviewCliError } from "./git_ops.js";
+const diffEnv = ["-c", "core.quotePath=false"];
+const unifiedDiffArgs = [
+    "diff",
+    "--no-color",
+    "--no-ext-diff",
+    "--no-textconv",
+    "-M",
+    "--unified=3",
+];
+/** Single-file unified patch when bulk `git diff` did not map a path (plan §10.7). */
+export async function perFileUnifiedPatch(cwd, base, path, run) {
+    const result = await run("git", [...diffEnv, ...unifiedDiffArgs, base, "--", path], cwd);
+    if (result.code !== 0 || !result.stdout.trim())
+        return "";
+    const map = splitDiffPatches(result.stdout);
+    return map.get(path) ?? map.values().next().value ?? "";
+}
+export async function mergeBase(cwd, baseRef, remote, run) {
+    const result = await run("git", [...diffEnv, "merge-base", baseRef, "HEAD"], cwd);
+    if (result.code === 0 && result.stdout.trim()) {
+        return result.stdout.trim();
+    }
+    const shallow = await run("git", ["rev-parse", "--is-shallow-repository"], cwd);
+    if (shallow.stdout.trim() === "true") {
+        await run("git", ["fetch", "--quiet", "--unshallow", remote], cwd);
+        const retry = await run("git", [...diffEnv, "merge-base", baseRef, "HEAD"], cwd);
+        if (retry.code === 0 && retry.stdout.trim())
+            return retry.stdout.trim();
+    }
+    throw new ReviewCliError("no_merge_base", "Could not find a merge base between HEAD and the target branch.");
+}
+export async function resolveBaseRef(cwd, remote, toBranch, run) {
+    let branch = toBranch;
+    if (!branch) {
+        branch = await resolveDefaultBranchName(cwd, remote, run);
+    }
+    if (!branch) {
+        throw new ReviewCliError("base_not_found", "Could not determine the default branch.", "--to-branch=<name>");
+    }
+    const ref = `refs/remotes/${remote}/${branch}`;
+    const verify = await run("git", ["rev-parse", "--verify", ref], cwd);
+    if (verify.code !== 0) {
+        await run("git", ["fetch", "--quiet", remote, branch], cwd);
+    }
+    const again = await run("git", ["rev-parse", "--verify", ref], cwd);
+    if (again.code !== 0) {
+        throw new ReviewCliError("base_not_found", `Could not resolve ${remote}/${branch}.`, "--to-branch=<name>");
+    }
+    return { ref, label: `${remote}/${branch}` };
+}
+export async function buildLocalRevision(cwd, mergeBaseSha, baseLabel, run) {
+    const base = mergeBaseSha;
+    const nameStatus = await run("git", [
+        ...diffEnv,
+        "diff",
+        "--no-color",
+        "--no-ext-diff",
+        "--no-textconv",
+        "-M",
+        "--name-status",
+        "-z",
+        base,
+    ], cwd);
+    const numstat = await run("git", [
+        ...diffEnv,
+        "diff",
+        "--no-color",
+        "--no-ext-diff",
+        "--no-textconv",
+        "-M",
+        "--numstat",
+        "-z",
+        base,
+    ], cwd);
+    const unified = await run("git", [...diffEnv, ...unifiedDiffArgs, base], cwd);
+    if (nameStatus.code !== 0) {
+        throw new ReviewCliError("internal", "git diff failed.");
+    }
+    const statuses = parseNameStatusZ(nameStatus.stdout);
+    const stats = parseNumstatZ(numstat.stdout);
+    const patches = unified.code === 0
+        ? splitDiffPatches(unified.stdout)
+        : new Map();
+    const needsPerFile = new Set(unified.code !== 0
+        ? statuses.filter((e) => e.status !== "removed").map((e) => e.path)
+        : pathsMissingPatches(statuses, patches));
+    const files = [];
+    for (const entry of statuses) {
+        const stat = stats.get(entry.path);
+        const file = {
+            path: normalizePath(entry.path),
+            previousPath: entry.previousPath
+                ? normalizePath(entry.previousPath)
+                : null,
+            status: entry.status,
+            binary: stat?.binary ?? false,
+            additions: stat?.additions ?? 0,
+            deletions: stat?.deletions ?? 0,
+            patch: patches.get(entry.path) ?? "",
+        };
+        if (needsPerFile.has(entry.path) &&
+            file.status !== "removed" &&
+            !file.binary) {
+            file.patch = await perFileUnifiedPatch(cwd, base, entry.path, run);
+        }
+        files.push(file);
+    }
+    const warnings = [];
+    const tracked = new Set(files.map((f) => f.path));
+    const untracked = await run("git", [...diffEnv, "ls-files", "--others", "--exclude-standard", "-z"], cwd);
+    if (untracked.code === 0 && untracked.stdout) {
+        for (const rel of untracked.stdout.split("\0").filter(Boolean)) {
+            const path = normalizePath(rel);
+            if (tracked.has(path))
+                continue;
+            tracked.add(path);
+            const result = await revisionFileFromUntracked(cwd, rel);
+            if ("warning" in result) {
+                warnings.push(result.warning);
+                continue;
+            }
+            files.push(result.file);
+        }
+    }
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    return {
+        revision: {
+            files,
+            title: "",
+            description: "",
+            baseLabel,
+            producer: "local",
+        },
+        warnings,
+    };
+}

package/dist/src/local/git_untracked.d.ts

@@ -0,0 +1,21 @@
+import { type RevisionFile } from "../review/revision.ts";
+export type UntrackedWarning = {
+    code: "untracked_unreadable";
+    message: string;
+};
+/** Build patch for a new untracked file (plan §10.8). */
+export declare function patchFromNewFileContent(content: Uint8Array): {
+    patch: string;
+    additions: number;
+    binary: boolean;
+};
+export declare function patchFromSymlinkTarget(target: string): {
+    patch: string;
+    additions: number;
+    binary: boolean;
+};
+export declare function revisionFileFromUntracked(cwd: string, relPath: string): Promise<{
+    file: RevisionFile;
+} | {
+    warning: UntrackedWarning;
+}>;

package/dist/src/local/git_untracked.js

@@ -0,0 +1,79 @@
+import { join } from "node:path";
+import { normalizePath } from "../review/revision.js";
+import { lstat, readFile, readLink } from "../util/runtime.js";
+const NUL_SCAN_BYTES = 8000;
+/** Build patch for a new untracked file (plan §10.8). */
+export function patchFromNewFileContent(content) {
+    const scan = content.subarray(0, Math.min(content.length, NUL_SCAN_BYTES));
+    if (scan.includes(0)) {
+        return { patch: "", additions: 0, binary: true };
+    }
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(content);
+    }
+    catch {
+        return { patch: "", additions: 0, binary: true };
+    }
+    if (text.length === 0) {
+        return { patch: "", additions: 0, binary: false };
+    }
+    const endsWithNewline = text.endsWith("\n");
+    const lines = text.split("\n");
+    if (endsWithNewline && lines.at(-1) === "")
+        lines.pop();
+    const n = lines.length;
+    const body = lines.map((line) => `+${line}`).join("\n");
+    const header = `@@ -0,0 +1,${n} @@`;
+    const patch = endsWithNewline
+        ? `${header}\n${body}\n`
+        : `${header}\n${body}\n\\n`;
+    return { patch, additions: n, binary: false };
+}
+export function patchFromSymlinkTarget(target) {
+    const patch = `@@ -0,0 +1 @@\n+${target}\n`;
+    return { patch, additions: 1, binary: false };
+}
+export async function revisionFileFromUntracked(cwd, relPath) {
+    const path = normalizePath(relPath);
+    const abs = join(cwd, relPath);
+    try {
+        const info = await lstat(abs);
+        if (info.isSymbolicLink()) {
+            const target = await readLink(abs);
+            const { patch, additions, binary } = patchFromSymlinkTarget(target);
+            return {
+                file: {
+                    path,
+                    previousPath: null,
+                    status: "added",
+                    binary,
+                    additions,
+                    deletions: 0,
+                    patch,
+                },
+            };
+        }
+        const content = await readFile(abs);
+        const { patch, additions, binary } = patchFromNewFileContent(content);
+        return {
+            file: {
+                path,
+                previousPath: null,
+                status: "added",
+                binary,
+                additions,
+                deletions: 0,
+                patch,
+            },
+        };
+    }
+    catch {
+        return {
+            warning: {
+                code: "untracked_unreadable",
+                message: `Could not read untracked file: ${path}`,
+            },
+        };
+    }
+}

package/dist/src/local/review_local.d.ts

@@ -0,0 +1,4 @@
+import { type ReviewCliArgs } from "../cli/review_args.ts";
+export declare function runLocalReview(cli: ReviewCliArgs & {
+    mode: "local";
+}): Promise<void>;

package/dist/src/local/review_local.js

@@ -0,0 +1,273 @@
+import { parseArgs } from "../cli/args.js";
+import { filterReviewConfigArgs, } from "../cli/review_args.js";
+import { buildLocalReviewJson, formatHumanLocalReview, resolvedFromFirstReview, reviewExitCodeFromResolved, } from "../cli/review_result.js";
+import { emptyAiMetrics, recordAiCost, runInitOrRemake, } from "../services/setup.js";
+import { aiFor } from "../services/review.js";
+import { loadGuides } from "../review/guides.js";
+import { buildCarryPromptSection, classifyCarryItems, incrementalDiffPaths, parsePreviousVerdicts, resolveCarryOutcomes, } from "../review/carry_over.js";
+import { revisionHash } from "../review/revision.js";
+import { parseFindings } from "../pr/findings.js";
+import { reviewWorkspaceRevision } from "../pr/reviewer.js";
+import { runCommand } from "../pr/checkout.js";
+import { log, startHeartbeat, timed, withCliLogsToStderr, } from "../util/log.js";
+import { setCliInteractive } from "../cli/args.js";
+import { prepareLocalCodegraph } from "./codegraph_prepare.js";
+import { acquireLocalReviewLock } from "./review_lock.js";
+import { assertGitQuiet, currentBranch, detectRemoteRepo, gitRoot, headSha, ReviewCliError, } from "./git_ops.js";
+import { buildLocalRevision, mergeBase, resolveBaseRef, } from "./git_revision.js";
+import { clearLocalCarry, localSubjectId, saveLocalCarry, tryLoadLocalCarry, } from "./carry_over_store.js";
+function storedFindings(resolved) {
+    return resolved
+        .filter((row) => row.state === "new" || row.state === "open")
+        .map((row) => ({
+        id: row.id,
+        path: row.path,
+        lineFrom: row.lineFrom,
+        lineTo: row.lineTo,
+        title: row.title,
+        bodyMd: row.bodyMd,
+        anchorText: row.anchorText,
+        severity: row.severity,
+        firstSeenReviewId: row.firstSeenReviewId,
+    }));
+}
+function fail(error, json) {
+    if (json) {
+        console.log(JSON.stringify({
+            schemaVersion: 1,
+            ok: false,
+            error: { code: error.code, message: error.message, hint: error.hint },
+            exitCode: error.exitCode,
+        }));
+    }
+    else {
+        console.error(error.message);
+        if (error.hint)
+            console.error(`Hint: ${error.hint}`);
+    }
+    process.exit(error.exitCode);
+}
+function installInterruptCleanup(releaseSync, json) {
+    const onSignal = () => {
+        releaseSync()?.();
+        if (json) {
+            console.log(JSON.stringify({
+                schemaVersion: 1,
+                ok: false,
+                error: {
+                    code: "aborted",
+                    message: "Review canceled.",
+                },
+                exitCode: 3,
+            }));
+        }
+        process.exit(3);
+    };
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+        try {
+            process.on(signal, onSignal);
+        }
+        catch {
+            // unavailable on some platforms
+        }
+    }
+    return () => {
+        for (const signal of ["SIGINT", "SIGTERM"]) {
+            try {
+                process.removeListener(signal, onSignal);
+            }
+            catch {
+                // ignore
+            }
+        }
+    };
+}
+export async function runLocalReview(cli) {
+    const json = cli.json;
+    setCliInteractive(!json);
+    let lock = null;
+    const clearInterrupt = installInterruptCleanup(() => lock?.releaseSync ?? null, json);
+    await withCliLogsToStderr(async () => {
+        try {
+            const cwd = process.cwd();
+            const root = await gitRoot(cwd);
+            await assertGitQuiet(root);
+            const repo = await detectRemoteRepo(root, cli.repoOverride);
+            const branch = await currentBranch(root, cli.branch);
+            const options = await parseArgs([
+                "review",
+                repo,
+                ...filterReviewConfigArgs(cli.rawArgs),
+            ]);
+            options.useCodegraph = cli.disableCodegraph ? false : true;
+            const guides = await loadGuides(repo);
+            if (!guides.shortGuide && !guides.skill) {
+                throw new ReviewCliError("not_initialized", `Review guides are missing for ${repo}.`, `co-maintainer init ${repo}`);
+            }
+            if (cli.remakeBeforeReview) {
+                if (options.auth !== "gh") {
+                    throw new ReviewCliError("usage", "Remake before review requires GitHub CLI authentication (`--auth=gh`).");
+                }
+                await runInitOrRemake({ ...options, command: "remake" });
+            }
+            const remotes = await runCommand("git", ["remote"], root);
+            const remoteName = ["upstream", "origin"].find((n) => remotes.stdout
+                .split("\n")
+                .map((l) => l.trim())
+                .includes(n)) ??
+                remotes.stdout
+                    .split("\n")
+                    .map((l) => l.trim())
+                    .filter(Boolean)[0];
+            const base = await resolveBaseRef(root, remoteName, cli.toBranch, runCommand);
+            const baseSha = await mergeBase(root, base.ref, remoteName, runCommand);
+            const built = await buildLocalRevision(root, baseSha, base.label, runCommand);
+            let revision = built.revision;
+            const warnings = built.warnings.map((w) => ({
+                code: w.code,
+                message: w.message,
+            }));
+            if (revision.files.length === 0) {
+                if (json) {
+                    console.log(JSON.stringify({
+                        schemaVersion: 1,
+                        ok: true,
+                        mode: "local",
+                        message: "No changes to review.",
+                    }));
+                }
+                else {
+                    console.log("No changes to review.");
+                }
+                process.exit(0);
+            }
+            const subjectId = localSubjectId(repo, root, branch);
+            if (cli.fresh)
+                await clearLocalCarry(repo, root, branch);
+            const carryLoad = await tryLoadLocalCarry(repo, root, branch);
+            if (carryLoad.unavailable) {
+                warnings.push({
+                    code: "carry_over_unavailable",
+                    message: "Could not read the local carry-over cache; continuing without prior findings.",
+                });
+            }
+            const previous = carryLoad.data;
+            let carryPrevious = null;
+            let carryItems = [];
+            const extras = {};
+            if (previous) {
+                carryPrevious = {
+                    files: previous.files,
+                    visiblePaths: new Set(previous.visiblePaths),
+                    findings: previous.findings,
+                    guideBuiltAt: previous.guideBuiltAt,
+                };
+                const { unchanged } = incrementalDiffPaths(revision, previous.files);
+                extras.unchangedPaths = unchanged;
+                carryItems = classifyCarryItems(carryPrevious, revision, carryPrevious.visiblePaths, guides.guideBuiltAt);
+                extras.carryPrompt = buildCarryPromptSection(carryItems, revision);
+            }
+            const sha = await headSha(root);
+            const revisionHashBefore = await revisionHash(revision);
+            lock = await acquireLocalReviewLock(root);
+            const codegraphPrep = await prepareLocalCodegraph({
+                gitRoot: root,
+                enabled: options.useCodegraph === true,
+                allowInstall: cli.allowToolInstall,
+                interactive: !json,
+            });
+            extras.prepareCodegraphTools = () => Promise.resolve(codegraphPrep.tools);
+            const stopHeartbeat = startHeartbeat("reviewing local changes");
+            const started = performance.now();
+            const aiMetrics = emptyAiMetrics();
+            let response;
+            try {
+                response = await timed("local review AI", options.logTime, () => reviewWorkspaceRevision(revision, options, sha, async (usage) => {
+                    aiMetrics.calls++;
+                    aiMetrics.tokensIn += usage.tokensIn;
+                    aiMetrics.tokensOut += usage.tokensOut;
+                    if (usage.cost === undefined)
+                        aiMetrics.costKnown = false;
+                    else
+                        aiMetrics.cost += usage.cost;
+                    await recordAiCost(repo, "review_local", usage);
+                }, aiFor(options), (message) => log("review", message), extras));
+            }
+            finally {
+                await lock?.release();
+                lock = null;
+            }
+            stopHeartbeat();
+            const codegraphState = codegraphPrep.state;
+            const visiblePaths = new Set(response.visiblePaths);
+            if (carryPrevious) {
+                carryItems = classifyCarryItems(carryPrevious, revision, visiblePaths, response.guideBuiltAt);
+            }
+            const parsed = parseFindings(response.text);
+            const filesByPath = new Map(revision.files.map((f) => [f.path, f]));
+            const allResolved = carryPrevious
+                ? resolveCarryOutcomes(carryItems, revision, visiblePaths, parsePreviousVerdicts(response.text), parsed, response.guideBuiltAt, carryPrevious)
+                : resolvedFromFirstReview(parsed, filesByPath);
+            const findingsToStore = storedFindings(allResolved);
+            const afterBuilt = await buildLocalRevision(root, baseSha, base.label, runCommand);
+            const revisionHashAfter = await revisionHash(afterBuilt.revision);
+            if (revisionHashAfter !== revisionHashBefore) {
+                warnings.push({
+                    code: "working_tree_changed",
+                    message: "Files changed while the review was running. Results reflect the state at submit time.",
+                });
+            }
+            try {
+                await saveLocalCarry({
+                    subjectId,
+                    files: revision.files,
+                    visiblePaths: [...visiblePaths],
+                    findings: findingsToStore,
+                    guideBuiltAt: response.guideBuiltAt,
+                });
+            }
+            catch {
+                warnings.push({
+                    code: "carry_over_unavailable",
+                    message: "Could not save local carry-over state for the next review.",
+                });
+            }
+            const header = `co-maintainer review · ${repo} · ${branch} → ${base.label}`;
+            const durationMs = Math.round(performance.now() - started);
+            const usage = {
+                tokensIn: aiMetrics.tokensIn,
+                tokensOut: aiMetrics.tokensOut,
+                costUsd: aiMetrics.costKnown ? aiMetrics.cost : null,
+            };
+            if (json) {
+                console.log(buildLocalReviewJson({
+                    repo,
+                    branch,
+                    baseLabel: base.label,
+                    revision,
+                    guideBuiltAt: response.guideBuiltAt,
+                    codegraphState,
+                    codegraphReason: codegraphPrep.reason,
+                    findings: allResolved,
+                    warnings,
+                    usage,
+                    durationMs,
+                }));
+            }
+            else {
+                console.log("\n" +
+                    formatHumanLocalReview(header, revision, response.guideBuiltAt, codegraphState, allResolved, warnings) +
+                    "\n");
+            }
+            process.exit(reviewExitCodeFromResolved(allResolved));
+        }
+        catch (error) {
+            if (error instanceof ReviewCliError)
+                fail(error, json);
+            throw error;
+        }
+        finally {
+            clearInterrupt();
+        }
+    });
+}

package/dist/src/local/review_lock.d.ts

@@ -0,0 +1,7 @@
+export type LocalReviewLock = {
+    release: () => Promise<void>;
+    /** For signal handlers — must not await before exit. */
+    releaseSync: () => void;
+};
+/** One local review per repo root (plan §13.3). */
+export declare function acquireLocalReviewLock(gitRoot: string): Promise<LocalReviewLock>;

package/dist/src/local/review_lock.js

@@ -0,0 +1,45 @@
+import { getCacheDir } from "../config.js";
+import { ReviewCliError } from "./git_ops.js";
+import { isNotFound, isProcessAlive, mkdir, readTextFile, remove, removeSync, writeTextFile, } from "../util/runtime.js";
+async function lockPath(gitRoot) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(gitRoot));
+    const hex = [...new Uint8Array(digest)]
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("")
+        .slice(0, 16);
+    const dir = `${getCacheDir()}/co-maintainer/locks`;
+    await mkdir(dir, { recursive: true });
+    return `${dir}/${hex}.lock`;
+}
+/** One local review per repo root (plan §13.3). */
+export async function acquireLocalReviewLock(gitRoot) {
+    const path = await lockPath(gitRoot);
+    let existingPid;
+    try {
+        existingPid = Number((await readTextFile(path)).trim());
+    }
+    catch (error) {
+        if (!isNotFound(error))
+            throw error;
+    }
+    if (existingPid !== undefined &&
+        Number.isInteger(existingPid) &&
+        isProcessAlive(existingPid)) {
+        throw new ReviewCliError("usage", `Another co-maintainer review is running in this repository (PID ${existingPid}).`);
+    }
+    await writeTextFile(path, String(process.pid));
+    const releaseSync = () => {
+        try {
+            removeSync(path);
+        }
+        catch {
+            // already removed
+        }
+    };
+    return {
+        release: async () => {
+            await remove(path).catch(() => { });
+        },
+        releaseSync,
+    };
+}

package/dist/src/pr/checkout.d.ts

@@ -0,0 +1,25 @@
+export declare function withCloneLock<T>(repo: string, fn: () => Promise<T>): Promise<T>;
+/** Shared git plumbing for anything that needs a real checkout of a
+ * repository — the codegraph map and the upstream/own-work scope both need
+ * a clone and a way to resolve a commit that is not necessarily reachable
+ * from any branch (a squash-merged or rebased-away PR head). One
+ * implementation, so the two never manage the same on-disk clone in two
+ * slightly different ways. */
+export type CommandResult = {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+export type Run = (command: string, args: string[], cwd?: string) => Promise<CommandResult>;
+export declare function runCommand(command: string, args: string[], cwd?: string): Promise<CommandResult>;
+export declare function pathExists(path: string): Promise<boolean>;
+/** Like `ensureClone` but assumes the caller already holds `withCloneLock`. */
+export declare function ensureCloneUnlocked(repo: string, run: Run): Promise<string>;
+export declare function ensureClone(repo: string, run: Run): Promise<string>;
+/** Resolves `revision` — a branch name, a remote-tracking ref, or a commit SHA
+ * — to a commit SHA, fetching it directly if it is a SHA the clone does not
+ * have. A round's boundary commit is often reachable only by SHA once its
+ * branch has moved on or the PR was squash-merged, so no local or
+ * remote-tracking ref points at it any more. */
+export declare function ensureCommit(clone: string, revision: string, run: Run): Promise<string>;
+export declare function ensureWorktree(repo: string, pr: number, commit: string, run: Run): Promise<string>;