co-maintainer 0.4.0-beta.1

package/dist/src/pr/findings.js

@@ -0,0 +1,94 @@
+const FILE_LINE = /(?<path>(?:[\w.-]+\/)*[\w.-]+\.[A-Za-z0-9]+):(?<from>\d+)(?:-(?<to>\d+))?/g;
+const NEW_HEADING = /^\[(?<severity>P[0-3])\s*·\s*(?<impact>blocking|non-blocking)\]\s+(?<path>.+?)\s+—\s+(?<symbol>.+)$/;
+function uncode(value) {
+    return value.trim().replace(/^`|`$/g, "").trim();
+}
+function location(block) {
+    const match = block.match(/^\s*(?:Location|File)\s*:\s*`?(.+?)`?\s*$/im);
+    const source = match?.[1] ?? block;
+    const found = [...source.matchAll(FILE_LINE)][0];
+    if (!found?.groups?.path || !found.groups.from)
+        return undefined;
+    const from = Number(found.groups.from);
+    return {
+        path: found.groups.path,
+        from,
+        to: found.groups.to ? Number(found.groups.to) : from,
+    };
+}
+function bodyWithoutLocation(block) {
+    return block.replace(/^\s*(?:Location|File)\s*:\s*`?.+?`?\s*$/im, "").trim();
+}
+function newFinding(header, block) {
+    const meta = NEW_HEADING.exec(header);
+    if (!meta?.groups)
+        return undefined;
+    const at = location(block);
+    if (!at)
+        return undefined;
+    const path = uncode(meta.groups.path);
+    const symbol = uncode(meta.groups.symbol);
+    const severity = meta.groups.severity;
+    const impact = meta.groups.impact;
+    const excerpt = bodyWithoutLocation(block);
+    const summary = excerpt.split(/\r?\n/).find((line) => line.trim()) ?? "";
+    return {
+        ...at,
+        path,
+        heading: `[${severity} · ${impact}] \`${path}\` — \`${symbol}\``,
+        excerpt,
+        severity,
+        blocking: impact === "blocking",
+        symbol,
+        summary,
+    };
+}
+export function parseFindings(markdown) {
+    const previousHeading = markdown.search(/^## Previous findings\b/im);
+    const withoutVerdicts = previousHeading === -1 ? markdown : markdown.slice(0, previousHeading);
+    const findingsHeading = withoutVerdicts.search(/^## Findings\b/m);
+    const body = findingsHeading === -1
+        ? withoutVerdicts
+        : withoutVerdicts.slice(findingsHeading);
+    if (/No actionable findings/i.test(body))
+        return [];
+    const findings = [];
+    const headings = [...body.matchAll(/^###\s+(.+)$/gm)];
+    for (let index = 0; index < headings.length; index++) {
+        const current = headings[index];
+        const start = (current.index ?? 0) + current[0].length;
+        const end = headings[index + 1]?.index ?? body.length;
+        const parsed = newFinding(current[1].trim(), body.slice(start, end));
+        if (parsed)
+            findings.push(parsed);
+    }
+    if (findings.length > 0)
+        return findings;
+    const seen = new Set();
+    for (const lined of body.matchAll(FILE_LINE)) {
+        if (!lined.groups?.path || !lined.groups.from)
+            continue;
+        const lineStart = body.lastIndexOf("\n", lined.index ?? 0) + 1;
+        if (/^\s*Suggestion\s*:/.test(body.slice(lineStart, lined.index)))
+            continue;
+        const from = Number(lined.groups.from);
+        const to = lined.groups.to ? Number(lined.groups.to) : from;
+        const key = `${lined.groups.path}:${from}-${to}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const at = lined.index ?? 0;
+        const headingStart = body.lastIndexOf("\n###", at);
+        const headingLine = headingStart >= 0
+            ? body.slice(headingStart, body.indexOf("\n", headingStart + 1)).trim()
+            : "";
+        findings.push({
+            path: lined.groups.path,
+            from,
+            to,
+            heading: headingLine.replace(/^###\s*/, ""),
+            excerpt: body.slice(Math.max(0, at - 80), at + 200).trim(),
+        });
+    }
+    return findings;
+}

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

@@ -0,0 +1,4 @@
+import type { Json } from "../types.ts";
+import { type Revision, type RevisionFile } from "../review/revision.ts";
+export declare function githubFileToRevisionFile(file: Json): RevisionFile;
+export declare function githubPullRequestToRevision(files: Json[], pr: Json, baseLabel: string): Revision;

package/dist/src/pr/github_revision.js

@@ -0,0 +1,39 @@
+import { normalizePath, } from "../review/revision.js";
+function githubStatus(raw) {
+    if (raw === "added")
+        return "added";
+    if (raw === "removed")
+        return "removed";
+    if (raw.startsWith("renamed"))
+        return "renamed";
+    return "modified";
+}
+export function githubFileToRevisionFile(file) {
+    const path = normalizePath(String(file.filename ?? ""));
+    const status = githubStatus(String(file.status ?? "modified"));
+    const additions = Number(file.additions ?? 0);
+    const deletions = Number(file.deletions ?? 0);
+    const patch = String(file.patch ?? "");
+    // GitHub omits large text patches; do not treat that as binary (plan §10.7).
+    const binary = false;
+    return {
+        path,
+        previousPath: file.previous_filename
+            ? normalizePath(String(file.previous_filename))
+            : null,
+        status,
+        binary,
+        additions,
+        deletions,
+        patch,
+    };
+}
+export function githubPullRequestToRevision(files, pr, baseLabel) {
+    return {
+        files: files.map((file) => githubFileToRevisionFile(file)),
+        title: String(pr.title ?? ""),
+        description: String(pr.body ?? ""),
+        baseLabel,
+        producer: "github",
+    };
+}

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

@@ -0,0 +1,18 @@
+export type Anchor = {
+    line: number;
+    start_line?: number;
+};
+/** New file line ranges each hunk covers. A hunk with a zero count (a
+ * deleted file) covers nothing on the RIGHT side. */
+export declare function rightHunks(patch: string): [number, number][];
+/** Where GitHub will accept a review comment for this span. The whole span
+ * when one hunk holds it, otherwise one end of it, otherwise nowhere. */
+export declare function anchorFor(patch: string, from: number, to: number): Anchor | undefined;
+/** Prefixes each diff line with its line number in the new file, so the
+ * reviewer copies Location numbers instead of counting from the @@ header.
+ * Removed lines get no number because GitHub cannot anchor a RIGHT side
+ * comment to them. */
+export declare function numberPatch(patch: string): string;
+/** The new file's text for every line the patch shows, without the diff
+ * prefix. */
+export declare function rightLines(patch: string): Map<number, string>;

package/dist/src/pr/hunks.js

@@ -0,0 +1,73 @@
+const HUNK = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/;
+const GUTTER = 6;
+/** New file line ranges each hunk covers. A hunk with a zero count (a
+ * deleted file) covers nothing on the RIGHT side. */
+export function rightHunks(patch) {
+    const ranges = [];
+    for (const match of patch.matchAll(new RegExp(HUNK.source, "gm"))) {
+        const start = Number(match[1]);
+        const count = match[2] === undefined ? 1 : Number(match[2]);
+        if (count > 0)
+            ranges.push([start, start + count - 1]);
+    }
+    return ranges;
+}
+/** Where GitHub will accept a review comment for this span. The whole span
+ * when one hunk holds it, otherwise one end of it, otherwise nowhere. */
+export function anchorFor(patch, from, to) {
+    const low = Math.min(from, to);
+    const high = Math.max(from, to);
+    // GitHub withholds the patch for very large files, so there is nothing to
+    // check against. Keep the single line anchor reviews always used.
+    if (patch === "")
+        return { line: high };
+    const hunks = rightHunks(patch);
+    const inside = (a, b) => hunks.some(([start, end]) => a >= start && b <= end);
+    if (low < high && inside(low, high))
+        return { start_line: low, line: high };
+    if (inside(high, high))
+        return { line: high };
+    if (inside(low, low))
+        return { line: low };
+    return undefined;
+}
+function* walk(patch) {
+    let next = 0;
+    for (const text of patch.split("\n")) {
+        const hunk = HUNK.exec(text);
+        if (hunk) {
+            next = Number(hunk[1]);
+            yield { text, inHunk: false };
+        }
+        else if (next === 0 || text === "") {
+            yield { text, inHunk: false };
+        }
+        else if (text.startsWith("-") || text.startsWith("\\")) {
+            yield { text, inHunk: true };
+        }
+        else {
+            yield { text, number: next++, inHunk: true };
+        }
+    }
+}
+/** Prefixes each diff line with its line number in the new file, so the
+ * reviewer copies Location numbers instead of counting from the @@ header.
+ * Removed lines get no number because GitHub cannot anchor a RIGHT side
+ * comment to them. */
+export function numberPatch(patch) {
+    return [...walk(patch)]
+        .map(({ text, number, inHunk }) => !inHunk
+        ? text
+        : `${number === undefined ? "".padStart(GUTTER) : String(number).padStart(GUTTER)} ${text}`)
+        .join("\n");
+}
+/** The new file's text for every line the patch shows, without the diff
+ * prefix. */
+export function rightLines(patch) {
+    const lines = new Map();
+    for (const { text, number } of walk(patch)) {
+        if (number !== undefined)
+            lines.set(number, text.slice(1));
+    }
+    return lines;
+}

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

@@ -0,0 +1,40 @@
+import { type ToolHandler } from "../ai/mermaid_loop.ts";
+import type { Revision } from "../review/revision.ts";
+import type { Snapshot } from "./snapshot.ts";
+import type { AiProvider, AiResponse, GitHubClient, Json, Options } from "../types.ts";
+type UsageSink = (response: AiResponse) => Promise<void>;
+type ProgressSink = (message: string) => void;
+export type ReviewExtras = {
+    carryPrompt?: string;
+    unchangedPaths?: string[];
+    prepareCodegraphTools?: () => Promise<ToolHandler[]>;
+};
+export declare const MERMAID_GUIDANCE = "Mermaid selection and minimal syntax:\nflowchart = decisions, branches, pipelines, and fallback paths;\nswimlane-beta = work crossing owners, actors, services, teams, or layers;\nsequenceDiagram = ordered calls, webhooks, retries, responses, and timing;\nclassDiagram = class, interface, type, inheritance, or composition relationships;\nstateDiagram-v2 = lifecycle and state transitions;\nerDiagram = database entities, keys, and cardinality;\nrequirementDiagram = requirements linked to tests or implementation;\nusecase-beta = actors and system capabilities;\nC4Context = users, systems, boundaries, and integrations;\nzenuml = compact nested call sequences;\npacket = binary fields, bit ranges, and protocol layout;\narchitecture-beta = services, containers, storage, and deployment topology;\neventmodeling = commands, events, processors, read models, and timelines;\ntreeView-beta = directory, file, module, or dependency hierarchy.\nIf a diagram is useful, call read-mermaid-syntaxes before writing any Mermaid.\nRequest every type you need in a single call, because repeated tool rounds are\ncapped. Use the smallest type that matches the evidence.";
+/** Without tool support the model cannot read the Mermaid syntax docs, so
+ * asking for a diagram only invites invented syntax. */
+export declare const NO_DIAGRAM_RULES = "Do not use Mermaid or any other diagram. Explain with prose only.";
+export declare function reviewSystemPrompt(diagrams: boolean): string;
+/** Shared PR and local/remote workspace review instructions: confirm claims
+ * against the indexed graph, not only the diff slice. */
+export declare const CODEGRAPH_DIFF_VERIFICATION = "Examine the changes line by line, not just file by file \u2014 a single file can\ncontain more than one independent defect, and a change that looks fine in\nisolation can be wrong once you trace what calls it or what else it affects.\nWhen a finding depends on behavior outside the changed lines, confirm it with\ncodegraph-node, codegraph-callers, codegraph-callees, codegraph-impact, and\ncodegraph-affected before reporting it. Drop or correct findings that only seem\nplausible from the diff but contradict unchanged callers, callees, or the same\npattern elsewhere in the repo. Use those tools to check blast radius and whether\na test reaches the path \u2014 do not guess coverage or impact from the diff alone\nwhen a tool can answer. A missing regression test is not a substitute for\nidentifying the concrete input or code path that misbehaves when you can.";
+/** GitHub omits `patch` entirely for files it considers too large, and the file
+ * still appears in the compare response with only its counts. Rendering that as
+ * an empty body reads as "this file did not change", and a reviewer then
+ * reports the absence as a finding (a lockfile that was in fact regenerated,
+ * say). Say plainly that the hunks are missing, and mark a per-file truncation
+ * for the same reason. */
+export declare function filePatch(file: Json): string;
+export declare function clampToolRounds(totalDiffLines: number): number;
+export declare function clampImproveMatrix(matrix: number): number;
+export declare function readGuide(repo: string, name: string): Promise<string>;
+export type { Snapshot };
+export declare function reviewPullRequest(client: GitHubClient, options: Options, usage?: UsageSink, snapshot?: Snapshot, ai?: AiProvider, progress?: ProgressSink, extras?: ReviewExtras): Promise<AiResponse & {
+    visiblePaths: string[];
+    guideBuiltAt: string | null;
+}>;
+/** Local workspace review — same prompt loop as PR review without GitHub. */
+export declare function reviewWorkspaceRevision(revision: Revision, options: Options, headSha: string, usage?: UsageSink, ai?: AiProvider, progress?: ProgressSink, extras?: ReviewExtras): Promise<AiResponse & {
+    visiblePaths: string[];
+    guideBuiltAt: string | null;
+    codegraphState: "used" | "disabled" | "unavailable";
+}>;