co-maintainer 0.4.0-beta.1

package/dist/src/knowledge/validate.js

@@ -0,0 +1,134 @@
+import { stat } from "../util/runtime.js";
+export async function validateSkill(markdown, outputDirectory, source) {
+    const errors = [];
+    if (!markdown.startsWith("---\n"))
+        errors.push("missing YAML frontmatter");
+    if (!/^name:\s+\S+/m.test(markdown))
+        errors.push("missing frontmatter name");
+    if (!/^description:\s+\S+/m.test(markdown)) {
+        errors.push("missing frontmatter description");
+    }
+    if (!/^#\s+\S+/m.test(markdown))
+        errors.push("missing skill heading");
+    if (markdown.includes("```")) {
+        errors.push("skill contains an unrequested code fence");
+    }
+    if (!(markdown.match(/^##\s+.+$/gm) ?? []).length) {
+        errors.push("skill has no Markdown sections");
+    }
+    for (const section of markdown.split(/^##\s+/m).slice(1)) {
+        const bullets = section.match(/^-\s+/gm) ?? [];
+        if (bullets.length > 6) {
+            errors.push("section exceeds six bullets");
+        }
+        if (section.split("\n").some((line) => /^\s*[-*+]\s*$/.test(line))) {
+            errors.push("skill contains an incomplete bullet");
+        }
+    }
+    if ((markdown.match(/^\|.*\|$/gm) ?? []).length >= 3) {
+        errors.push("skill contains a raw Markdown table");
+    }
+    if (source) {
+        const paths = new Set([...source.tree, ...Object.keys(source.files)]);
+        const repositoryName = String(source.repo.full_name ?? "");
+        const commands = new Set();
+        for (const [path, content] of Object.entries(source.files)) {
+            if (path.endsWith("package.json")) {
+                try {
+                    const scripts = JSON.parse(content)
+                        .scripts ?? {};
+                    const prefix = source.tree.some((item) => /pnpm-lock\.yaml$/.test(item))
+                        ? "pnpm"
+                        : source.tree.some((item) => /yarn\.lock$/.test(item))
+                            ? "yarn"
+                            : "npm";
+                    for (const name of Object.keys(scripts)) {
+                        commands.add(`${prefix} ${name}`);
+                        commands.add(`${prefix} run ${name}`);
+                        commands.add(String(scripts[name]));
+                    }
+                }
+                catch {
+                    // Ignore malformed manifests; syntax validation is outside this gate.
+                }
+            }
+            if (/deno\.jsonc?$/.test(path)) {
+                try {
+                    const tasks = JSON.parse(content).tasks ??
+                        {};
+                    for (const [name, task] of Object.entries(tasks)) {
+                        commands.add(`deno task ${name}`);
+                        commands.add(String(task));
+                    }
+                }
+                catch {
+                    // Ignore malformed manifests; syntax validation is outside this gate.
+                }
+            }
+            for (const match of content.matchAll(/^\s*run:\s*([^\s#].*?)\s*$/gm)) {
+                commands.add(match[1].replace(/^['"]|['"]$/g, ""));
+            }
+            for (const match of content.matchAll(/`((?:npm|pnpm|yarn|bun|deno|cargo|make|go|python|node|git)\s+[^`\n]+)`/g)) {
+                commands.add(match[1]);
+            }
+            for (const match of content.matchAll(/^\s*((?:npm|pnpm|yarn|bun|deno|cargo|make|go|python|node|git)\s+[^\n`]+)$/gm)) {
+                commands.add(match[1].trim());
+            }
+        }
+        if (source.tree.some((path) => /Cargo\.toml$/.test(path))) {
+            commands.add("cargo test");
+            commands.add("cargo build");
+        }
+        const references = [...markdown.matchAll(/`([^`\n]+)`/g)].map((match) => match[1]);
+        for (const reference of references) {
+            const isQualifier = /^[a-z][a-z\d_-]*:/i.test(reference);
+            if (reference.includes("/") &&
+                !reference.startsWith("@") &&
+                !reference.startsWith("http") &&
+                !isQualifier &&
+                !reference.startsWith("./") &&
+                !reference.includes(" ")) {
+                const normalized = reference
+                    .replace(/^\.\/+/, "")
+                    .replace(/^\/+/, "")
+                    .replace(/\/+$/, "");
+                if (normalized === repositoryName)
+                    continue;
+                const wildcardPattern = normalized.includes("*")
+                    ? new RegExp(`^${normalized
+                        .split("*")
+                        .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+                        .join(".*")}$`)
+                    : undefined;
+                if (!paths.has(normalized) &&
+                    ![...paths].some((path) => wildcardPattern
+                        ? wildcardPattern.test(path)
+                        : path.startsWith(`${normalized}/`))) {
+                    errors.push(`referenced path is absent from source: ${reference}`);
+                }
+            }
+            if (/^(?:npm|pnpm|yarn|bun|deno|cargo|make|go|python|node|git)\s/.test(reference) &&
+                ![...commands].some((command) => reference === command ||
+                    reference.startsWith(`${command} `) ||
+                    command.startsWith(`${reference} `))) {
+                errors.push(`referenced command is absent from source: ${reference}`);
+            }
+        }
+    }
+    const links = [...markdown.matchAll(/\[[^\]]+\]\(([^)]+)\)/g)].map((match) => match[1]);
+    for (const link of links) {
+        if (/^[a-z][a-z\d+.-]*:/i.test(link) ||
+            link.startsWith("/") ||
+            link.includes("..")) {
+            errors.push(`link is not relative: ${link}`);
+            continue;
+        }
+        try {
+            await stat(`${outputDirectory}/${link}`);
+        }
+        catch {
+            errors.push(`linked file does not exist: ${link}`);
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}

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

@@ -0,0 +1,18 @@
+import type { RevisionFile } from "../review/revision.ts";
+import type { StoredFinding } from "../review/carry_over.ts";
+export type LocalCarrySnapshot = {
+    subjectId: string;
+    files: RevisionFile[];
+    visiblePaths: string[];
+    findings: StoredFinding[];
+    guideBuiltAt: string | null;
+};
+export declare function localSubjectId(repo: string, root: string, branch: string): string;
+export declare function loadLocalCarry(repo: string, root: string, branch: string): Promise<LocalCarrySnapshot | null>;
+/** Plan E163 — corrupt or locked cache must not abort review. */
+export declare function tryLoadLocalCarry(repo: string, root: string, branch: string): Promise<{
+    data: LocalCarrySnapshot | null;
+    unavailable: boolean;
+}>;
+export declare function saveLocalCarry(snapshot: LocalCarrySnapshot): Promise<void>;
+export declare function clearLocalCarry(repo: string, root: string, branch: string): Promise<void>;

package/dist/src/local/carry_over_store.js

@@ -0,0 +1,40 @@
+import { cacheDelete, cacheGet, cacheSet } from "../store/cache_db.js";
+const NS = "local-review";
+function key(repo, root, branch) {
+    return `${repo}\0${root}\0${branch}`;
+}
+export function localSubjectId(repo, root, branch) {
+    return key(repo, root, branch);
+}
+export async function loadLocalCarry(repo, root, branch) {
+    const loaded = await tryLoadLocalCarry(repo, root, branch);
+    if (loaded.unavailable) {
+        throw new Error("local carry-over cache is unreadable");
+    }
+    return loaded.data;
+}
+/** Plan E163 — corrupt or locked cache must not abort review. */
+export async function tryLoadLocalCarry(repo, root, branch) {
+    try {
+        const raw = await cacheGet(NS, key(repo, root, branch));
+        if (!raw)
+            return { data: null, unavailable: false };
+        return { data: JSON.parse(raw), unavailable: false };
+    }
+    catch {
+        return { data: null, unavailable: true };
+    }
+}
+export async function saveLocalCarry(snapshot) {
+    const { subjectId, ...rest } = snapshot;
+    const parts = subjectId.split("\0");
+    if (parts.length !== 3)
+        throw new Error("invalid local subject id");
+    await cacheSet(NS, key(parts[0], parts[1], parts[2]), JSON.stringify({
+        subjectId,
+        ...rest,
+    }));
+}
+export async function clearLocalCarry(repo, root, branch) {
+    await cacheDelete(NS, key(repo, root, branch));
+}

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

@@ -0,0 +1,3 @@
+import type { Run } from "../pr/checkout.ts";
+/** Plan §13.2 — hide the local codegraph index from git status. */
+export declare function ensureCodegraphGitExclude(gitRoot: string, run: Run): Promise<void>;

package/dist/src/local/codegraph_exclude.js

@@ -0,0 +1,26 @@
+import { dirname } from "node:path";
+import { isNotFound, mkdir, readTextFile, writeTextFile, } from "../util/runtime.js";
+const EXCLUDE_LINE = "/.co-maintainer-codegraph/";
+/** Plan §13.2 — hide the local codegraph index from git status. */
+export async function ensureCodegraphGitExclude(gitRoot, run) {
+    const pathResult = await run("git", ["rev-parse", "--git-path", "info/exclude"], gitRoot);
+    if (pathResult.code !== 0)
+        return;
+    const excludePath = pathResult.stdout.trim();
+    if (!excludePath)
+        return;
+    let text = "";
+    try {
+        text = await readTextFile(excludePath);
+    }
+    catch (error) {
+        if (!isNotFound(error))
+            throw error;
+    }
+    const lines = text.split("\n").map((line) => line.trim());
+    if (lines.includes(EXCLUDE_LINE.trim()))
+        return;
+    const prefix = text.length > 0 && !text.endsWith("\n") ? "\n" : "";
+    await mkdir(dirname(excludePath), { recursive: true }).catch(() => { });
+    await writeTextFile(excludePath, `${text}${prefix}${EXCLUDE_LINE}\n`);
+}

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

@@ -0,0 +1,17 @@
+import type { ToolHandler } from "../ai/mermaid_loop.ts";
+import { type Presence } from "../tools/codegraph.ts";
+import { type Run } from "../pr/checkout.ts";
+export type LocalCodegraphState = "used" | "disabled" | "unavailable";
+export type LocalCodegraphPrepare = {
+    state: LocalCodegraphState;
+    reason: string | null;
+    tools: ToolHandler[];
+};
+export declare function prepareLocalCodegraph(input: {
+    gitRoot: string;
+    enabled: boolean;
+    allowInstall: boolean;
+    interactive: boolean;
+    run?: Run;
+    detect?: () => Promise<Presence>;
+}): Promise<LocalCodegraphPrepare>;

package/dist/src/local/codegraph_prepare.js

@@ -0,0 +1,51 @@
+import { codegraphTools, ensureCodegraphIndex } from "../pr/codegraph_tools.js";
+import { ensureCodegraphForReview } from "../tools/codegraph.js";
+import { createCodegraphRunner, LOCAL_CODEGRAPH_DIR, } from "../tools/codegraph_exec.js";
+import { log, startHeartbeat } from "../util/log.js";
+import { ensureCodegraphGitExclude } from "./codegraph_exclude.js";
+import { pathExists, runCommand } from "../pr/checkout.js";
+export async function prepareLocalCodegraph(input) {
+    if (!input.enabled) {
+        return { state: "disabled", reason: null, tools: [] };
+    }
+    const run = input.run ?? runCommand;
+    await ensureCodegraphGitExclude(input.gitRoot, run);
+    const resolved = await ensureCodegraphForReview({
+        allowInstall: input.allowInstall,
+        interactive: input.interactive,
+        log: (message) => log("codegraph", message.replace(/^\[codegraph\]\s*/, "")),
+    });
+    if (!("path" in resolved)) {
+        log("codegraph", `tools unavailable · ${resolved.reason}`);
+        return { state: "unavailable", reason: resolved.reason, tools: [] };
+    }
+    const binary = resolved.path;
+    const cgRun = createCodegraphRunner(LOCAL_CODEGRAPH_DIR);
+    try {
+        const fresh = !(await pathExists(`${input.gitRoot}/${LOCAL_CODEGRAPH_DIR}`));
+        if (fresh) {
+            log("codegraph", "building code index for the first time (this can take a few minutes)");
+            const stop = startHeartbeat("codegraph init");
+            try {
+                await ensureCodegraphIndex(binary, input.gitRoot, cgRun, LOCAL_CODEGRAPH_DIR);
+            }
+            finally {
+                stop();
+            }
+        }
+        else {
+            await ensureCodegraphIndex(binary, input.gitRoot, cgRun, LOCAL_CODEGRAPH_DIR);
+        }
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        const line = reason.split("\n")[0] || "codegraph index failed";
+        log("codegraph", `tools unavailable · ${line}`);
+        return { state: "unavailable", reason: line, tools: [] };
+    }
+    return {
+        state: "used",
+        reason: null,
+        tools: codegraphTools(binary, input.gitRoot, cgRun),
+    };
+}

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

@@ -0,0 +1,12 @@
+import { type Run } from "../pr/checkout.ts";
+export declare function gitRoot(cwd: string, run?: Run): Promise<string>;
+export declare class ReviewCliError extends Error {
+    code: string;
+    hint?: string;
+    exitCode: number;
+    constructor(code: string, message: string, hint?: string, exitCode?: number);
+}
+export declare function assertGitQuiet(cwd: string, run?: Run): Promise<void>;
+export declare function detectRemoteRepo(cwd: string, override?: string, run?: Run): Promise<string>;
+export declare function currentBranch(cwd: string, override?: string, run?: Run): Promise<string>;
+export declare function headSha(cwd: string, run?: Run): Promise<string>;

package/dist/src/local/git_ops.js

@@ -0,0 +1,98 @@
+import { runCommand } from "../pr/checkout.js";
+import { normalizeGithubRemote } from "./git_parse.js";
+import { stat } from "../util/runtime.js";
+export async function gitRoot(cwd, run = runCommand) {
+    const result = await run("git", ["rev-parse", "--show-toplevel"], cwd);
+    if (result.code !== 0) {
+        throw new ReviewCliError("not_a_git_repo", "This directory is not inside a git repository.");
+    }
+    return result.stdout.trim();
+}
+export class ReviewCliError extends Error {
+    code;
+    hint;
+    exitCode;
+    constructor(code, message, hint, exitCode = 2) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+        this.exitCode = exitCode;
+    }
+}
+export async function assertGitQuiet(cwd, run = runCommand) {
+    const heads = ["MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD"];
+    for (const name of heads) {
+        const path = await run("git", ["rev-parse", "--git-path", name], cwd);
+        if (path.code !== 0)
+            continue;
+        try {
+            await stat(path.stdout.trim());
+            throw new ReviewCliError("git_operation_in_progress", "Finish the in-progress git operation before running review.");
+        }
+        catch (error) {
+            if (error instanceof ReviewCliError)
+                throw error;
+        }
+    }
+    for (const dir of ["rebase-merge", "rebase-apply"]) {
+        const path = await run("git", ["rev-parse", "--git-path", dir], cwd);
+        if (path.code !== 0)
+            continue;
+        try {
+            const info = await stat(path.stdout.trim());
+            if (info.isDirectory()) {
+                throw new ReviewCliError("git_operation_in_progress", "Finish the in-progress rebase before running review.");
+            }
+        }
+        catch (error) {
+            if (error instanceof ReviewCliError)
+                throw error;
+        }
+    }
+    const conflicts = await run("git", ["diff", "--name-only", "--diff-filter=U"], cwd);
+    if (conflicts.stdout.trim()) {
+        throw new ReviewCliError("git_operation_in_progress", "Resolve merge conflicts before running review.");
+    }
+}
+export async function detectRemoteRepo(cwd, override, run = runCommand) {
+    if (override) {
+        if (!/^[^/]+\/[^/]+$/.test(override)) {
+            throw new ReviewCliError("usage", "Repository must look like owner/repo");
+        }
+        return override;
+    }
+    const remotes = await run("git", ["remote"], cwd);
+    const names = remotes.stdout
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean);
+    const pick = ["upstream", "origin"].find((n) => names.includes(n)) ??
+        (names.length === 1 ? names[0] : undefined);
+    if (!pick) {
+        throw new ReviewCliError("repo_not_detected", "Could not detect the GitHub repository from remotes.", "--repo=owner/repo");
+    }
+    const url = await run("git", ["remote", "get-url", pick], cwd);
+    if (url.code !== 0) {
+        throw new ReviewCliError("repo_not_detected", "Could not read git remote URL.");
+    }
+    const normalized = normalizeGithubRemote(url.stdout.trim());
+    if (!normalized.ok) {
+        throw new ReviewCliError("unsupported_host", "Only github.com remotes are supported for local review.");
+    }
+    return normalized.fullName;
+}
+export async function currentBranch(cwd, override, run = runCommand) {
+    if (override)
+        return override;
+    const result = await run("git", ["symbolic-ref", "--short", "-q", "HEAD"], cwd);
+    if (result.code !== 0 || !result.stdout.trim()) {
+        throw new ReviewCliError("detached_head", "Detached HEAD; pass --branch=<name> to review.");
+    }
+    return result.stdout.trim();
+}
+export async function headSha(cwd, run = runCommand) {
+    const result = await run("git", ["rev-parse", "HEAD"], cwd);
+    if (result.code !== 0)
+        throw new ReviewCliError("internal", "Could not read HEAD.");
+    return result.stdout.trim();
+}

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

@@ -0,0 +1,27 @@
+/** Pure parsers for git -z output and remote URL normalization (plan §10). */
+export type NameStatusEntry = {
+    status: "added" | "modified" | "removed" | "renamed";
+    path: string;
+    previousPath?: string;
+};
+export type NumstatEntry = {
+    additions: number;
+    deletions: number;
+    binary: boolean;
+};
+export type NormalizeRemoteResult = {
+    ok: true;
+    fullName: string;
+} | {
+    ok: false;
+    code: "unsupported_host";
+};
+export declare function normalizeGithubRemote(url: string): NormalizeRemoteResult;
+/** Parse `git diff --name-status -z` records (NUL-separated). */
+export declare function parseNameStatusZ(raw: string): NameStatusEntry[];
+/** Parse `git diff --numstat -z` (`add\tdelete\tpath\0` per file). */
+export declare function parseNumstatZ(raw: string): Map<string, NumstatEntry>;
+/** Paths from name-status that have no entry in a bulk unified diff (plan §10.7). */
+export declare function pathsMissingPatches(statuses: NameStatusEntry[], patches: Map<string, string>): string[];
+/** Split unified diff output into per-file patch bodies (without diff --git header). */
+export declare function splitDiffPatches(raw: string): Map<string, string>;

package/dist/src/local/git_parse.js

@@ -0,0 +1,131 @@
+/** Pure parsers for git -z output and remote URL normalization (plan §10). */
+export function normalizeGithubRemote(url) {
+    const trimmed = url.trim().replace(/\/+$/, "");
+    let host = "";
+    let path = "";
+    if (trimmed.startsWith("git@")) {
+        const match = /^git@([^:]+):(.+)$/i.exec(trimmed);
+        if (!match)
+            return { ok: false, code: "unsupported_host" };
+        host = match[1];
+        path = match[2];
+    }
+    else if (trimmed.startsWith("ssh://")) {
+        try {
+            const parsed = new URL(trimmed);
+            host = parsed.hostname;
+            path = parsed.pathname.replace(/^\//, "");
+        }
+        catch {
+            return { ok: false, code: "unsupported_host" };
+        }
+    }
+    else if (/^https?:\/\//i.test(trimmed)) {
+        try {
+            const parsed = new URL(trimmed);
+            host = parsed.hostname;
+            path = parsed.pathname.replace(/^\//, "");
+        }
+        catch {
+            return { ok: false, code: "unsupported_host" };
+        }
+    }
+    else {
+        return { ok: false, code: "unsupported_host" };
+    }
+    if (host.toLowerCase() !== "github.com") {
+        return { ok: false, code: "unsupported_host" };
+    }
+    if (path.endsWith(".git"))
+        path = path.slice(0, -4);
+    const parts = path.split("/").filter(Boolean);
+    if (parts.length < 2)
+        return { ok: false, code: "unsupported_host" };
+    const owner = parts[0];
+    const repo = parts[1];
+    return { ok: true, fullName: `${owner}/${repo}` };
+}
+/** Parse `git diff --name-status -z` records (NUL-separated). */
+export function parseNameStatusZ(raw) {
+    if (!raw)
+        return [];
+    const parts = raw.split("\0").filter((p) => p.length > 0);
+    const entries = [];
+    for (let i = 0; i < parts.length; i++) {
+        const token = parts[i];
+        if (token.startsWith("R")) {
+            const path = parts[i + 2];
+            const previousPath = parts[i + 1];
+            if (!path || !previousPath)
+                break;
+            entries.push({ status: "renamed", path, previousPath });
+            i += 2;
+            continue;
+        }
+        if (token === "T") {
+            const path = parts[i + 1];
+            if (!path)
+                break;
+            entries.push({ status: "modified", path });
+            i += 1;
+            continue;
+        }
+        const path = parts[i + 1];
+        if (!path)
+            break;
+        if (token === "A")
+            entries.push({ status: "added", path });
+        else if (token === "M")
+            entries.push({ status: "modified", path });
+        else if (token === "D")
+            entries.push({ status: "removed", path });
+        i += 1;
+    }
+    return entries;
+}
+/** Parse `git diff --numstat -z` (`add\tdelete\tpath\0` per file). */
+export function parseNumstatZ(raw) {
+    const map = new Map();
+    for (const record of raw.split("\0").filter((part) => part.length > 0)) {
+        const match = /^([^\t]*)\t([^\t]*)\t(.*)$/.exec(record);
+        if (!match)
+            continue;
+        const addRaw = match[1];
+        const delRaw = match[2];
+        const path = match[3];
+        const binary = addRaw === "-" && delRaw === "-";
+        map.set(path, {
+            additions: binary ? 0 : Number(addRaw),
+            deletions: binary ? 0 : Number(delRaw),
+            binary,
+        });
+    }
+    return map;
+}
+/** Paths from name-status that have no entry in a bulk unified diff (plan §10.7). */
+export function pathsMissingPatches(statuses, patches) {
+    return statuses
+        .filter((entry) => entry.status !== "removed")
+        .map((entry) => entry.path)
+        .filter((path) => !patches.has(path) || patches.get(path) === "");
+}
+/** Split unified diff output into per-file patch bodies (without diff --git header). */
+export function splitDiffPatches(raw) {
+    const map = new Map();
+    const chunks = raw.split(/^diff --git /m).filter(Boolean);
+    for (const chunk of chunks) {
+        const headerEnd = chunk.indexOf("\n");
+        if (headerEnd === -1)
+            continue;
+        const header = chunk.slice(0, headerEnd);
+        const pathMatch = /^a\/(.+?) b\/(.+)$/m.exec(header) ??
+            /^a\/(.+?) b\/(.+)$/m.exec(header.replace(/\t.*$/, ""));
+        const path = pathMatch?.[2] ?? pathMatch?.[1];
+        if (!path)
+            continue;
+        const body = chunk.slice(headerEnd + 1);
+        const patchStart = body.indexOf("@@");
+        map.set(path, patchStart === -1 ? "" : body.slice(patchStart));
+    }
+    return map;
+}

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

@@ -0,0 +1,15 @@
+import type { Run } from "../pr/checkout.ts";
+import { type Revision } from "../review/revision.ts";
+import { type UntrackedWarning } from "./git_untracked.ts";
+/** Single-file unified patch when bulk `git diff` did not map a path (plan §10.7). */
+export declare function perFileUnifiedPatch(cwd: string, base: string, path: string, run: Run): Promise<string>;
+export declare function mergeBase(cwd: string, baseRef: string, remote: string, run: Run): Promise<string>;
+export declare function resolveBaseRef(cwd: string, remote: string, toBranch: string | undefined, run: Run): Promise<{
+    ref: string;
+    label: string;
+}>;
+export type LocalRevisionBuild = {
+    revision: Revision;
+    warnings: UntrackedWarning[];
+};
+export declare function buildLocalRevision(cwd: string, mergeBaseSha: string, baseLabel: string, run: Run): Promise<LocalRevisionBuild>;