@wardby/cli 0.6.0 → 0.7.0

package/dist/providers/review-host/local.js

@@ -1,10 +1,11 @@
 import { LocalRepoError, loadLocalRepoRoots, normalizeLocalRepository, resolveLocalRepository, } from "../../coding/local-repo.js";
 import { SHA, isSafeRefName, isSafeRepoPath, localGit as git } from "../../coding/local-git.js";
 import { skippedInListing } from "./github.js";
+import { pagePatches } from "./patch-pages.js";
 import { verdictConclusion } from "./review-format.js";
 import { ReviewHostError, } from "./types.js";
-/** GitHub lists at most 3 pages of 100 files; match it. */
-const MAX_PR_FILES = 300;
+/** A pull request's file list is cut at this many files (as GitHub's host bounds its paging). */
+const MAX_PR_FILES = 1000;
 const MAX_LISTED_FILES = 1000;
 const MAX_BODY_CHARS = 8000;
 const MAX_LOGGED_COMMITS = 100;
@@ -117,7 +118,10 @@ export class LocalReviewHost {
             return false;
         }
     }
-    /** Files changed between two commits (both 40-hex), with rename detection, in git's order. */
+    /**
+     * Files changed between two commits (both 40-hex), with rename detection, in git's order, at
+     * most MAX_PR_FILES of them; `complete` is false when the list was cut.
+     */
     async changedFiles(dir, from, to) {
         const diff = ["diff", "--no-ext-diff", "--no-textconv", "--no-color", "-M", "-z"];
         let nameStatus;
@@ -166,23 +170,19 @@ export class LocalReviewHost {
                 ...(counts.get(filename) ?? { additions: 0, deletions: 0 }),
             });
         }
-        return files.slice(0, MAX_PR_FILES);
+        return { files: files.slice(0, MAX_PR_FILES), complete: files.length <= MAX_PR_FILES };
     }
-    /** Attaches patches, sharing one character budget across files and flagging truncation like GitHub. */
-    async withPatches(dir, from, to, files, maxPatchChars) {
-        let budget = maxPatchChars;
-        const out = [];
-        for (const file of files) {
-            const changes = file.additions + file.deletions;
-            if (budget <= 0) {
-                out.push({ ...file, patch: "", patchTruncated: changes > 0 });
-                continue;
-            }
-            let patch;
-            let complete = true;
+    /** Pages patches like GitHub (patch-pages.ts); a diff is run only for files on the page. */
+    async withPatches(dir, from, to, files, opts) {
+        return pagePatches(files.map((f) => ({ ...f, changes: f.additions + f.deletions })), {
+            budget: opts.maxPatchChars,
+            cursor: opts.patchCursor,
+            headSha: opts.headSha,
+            comparedFrom: opts.comparedFrom,
+        }, async (file) => {
+            const paths = file.previousFilename ? [file.previousFilename, file.filename] : [file.filename];
             try {
-                const paths = file.previousFilename ? [file.previousFilename, file.filename] : [file.filename];
-                patch = hunks(await git(dir, [
+                return hunks(await git(dir, [
                     "diff",
                     "--no-ext-diff",
                     "--no-textconv",
@@ -196,15 +196,10 @@ export class LocalReviewHost {
                 ]));
             }
             catch {
-                // Too large for the buffer (or unreadable): no patch, flagged.
-                patch = "";
-                complete = changes === 0;
+                // Too large for the buffer (or unreadable): no patch (unavailable when it has changes).
+                return undefined;
             }
-            const kept = patch.length <= budget ? patch : patch.slice(0, Math.max(0, budget));
-            budget -= kept.length;
-            out.push({ ...file, patch: kept, patchTruncated: kept.length < patch.length || !complete });
-        }
-        return out;
+        });
     }
     async repositoryPermission(_repository, _user) {
         return { level: "admin", login: "local" };
@@ -225,12 +220,13 @@ export class LocalReviewHost {
             fail("no common ancestor between the branch and its base");
         let from = baseSha;
         let files = null;
+        let fileListComplete = true;
         let comparedFrom = null;
         let baseMergedSince = false;
         const since = opts.sinceSha;
         if (since && SHA.test(since) && since !== headSha && (await this.isAncestor(dir, since, headSha))) {
             comparedFrom = since;
-            files = await this.changedFiles(dir, since, headSha);
+            ({ files, complete: fileListComplete } = await this.changedFiles(dir, since, headSha));
             from = since;
             let merges = "0";
             try {
@@ -243,11 +239,14 @@ export class LocalReviewHost {
             if (baseMergedSince) {
                 // As on GitHub: the PR's own diff against its base, limited to files that changed since.
                 const changedSince = new Set(files.map((f) => f.filename));
-                files = (await this.changedFiles(dir, baseSha, headSha)).filter((f) => changedSince.has(f.filename));
+                const all = await this.changedFiles(dir, baseSha, headSha);
+                files = all.files.filter((f) => changedSince.has(f.filename));
+                fileListComplete &&= all.complete;
                 from = baseSha;
             }
         }
-        files ??= await this.changedFiles(dir, baseSha, headSha);
+        if (!files)
+            ({ files, complete: fileListComplete } = await this.changedFiles(dir, baseSha, headSha));
         let log = "";
         try {
             log = await git(dir, [
@@ -262,11 +261,23 @@ export class LocalReviewHost {
         catch {
             // The commit list is a courtesy; the diff is the review.
         }
+        const page = await this.withPatches(dir, from, headSha, files, {
+            maxPatchChars: opts.maxPatchChars,
+            patchCursor: opts.patchCursor,
+            headSha,
+            comparedFrom,
+        });
         const last = await this.db.localReview.findFirst({
             where: { pullRequestId: row.id, agentId: opts.agentMarker },
             orderBy: { createdAt: "desc" },
             select: { headSha: true },
         });
+        // A review that did not read every file leaves coveredSha null, so the latest covered one counts.
+        const covered = await this.db.localReview.findFirst({
+            where: { pullRequestId: row.id, agentId: opts.agentMarker, coveredSha: { not: null } },
+            orderBy: { createdAt: "desc" },
+            select: { coveredSha: true },
+        });
         return {
             number: row.number,
             title: `${row.branch} into ${row.base}`,
@@ -281,9 +292,15 @@ export class LocalReviewHost {
             isFork: false,
             htmlUrl: prUrl(row),
             lastReviewedSha: last?.headSha ?? null,
+            lastCoveredSha: covered?.coveredSha ?? null,
             comparedFrom,
             baseMergedSince,
-            files: await this.withPatches(dir, from, headSha, files, opts.maxPatchChars),
+            files: page.files,
+            fileListComplete,
+            patchesComplete: page.patchesComplete,
+            truncatedFiles: page.truncatedFiles,
+            nextPatchCursor: page.nextPatchCursor,
+            remainingPatchFiles: page.remainingPatchFiles,
             openThreads: [],
             ci: { headSha, state: "none", checks: [], truncated: false, statusesUnavailable: false },
         };
@@ -385,6 +402,7 @@ export class LocalReviewHost {
                 pullRequestId: row.id,
                 agentId: input.agentMarker,
                 headSha: currentHeadSha,
+                coveredSha: input.coveredSha === currentHeadSha ? currentHeadSha : null,
                 verdict: input.verdict,
                 summary: input.summary,
                 body: input.body,
@@ -426,7 +444,7 @@ export class LocalReviewHost {
         return { url: `${prUrl(row)}#${review.id}`, id: review.id };
     }
     async editComment(_repository, _input) { }
-    async acknowledge(_repository, _target) { }
+    async acknowledge(_repository, _target, _outcome) { }
     async startCheck(_repository, _input) {
         return { checkId: "local" };
     }

package/dist/providers/review-host/patch-pages.d.ts

@@ -0,0 +1,41 @@
+/**
+ * repo_pr_read's diff pages: which files get the patch budget first (code before docs, help,
+ * lockfiles, generated files and fixtures), how a page is filled from a cursor, and the cursor
+ * itself. Shared by every review host so paging behaves the same on GitHub and local repositories.
+ */
+import { type PullRequestFileView } from "./types.js";
+export interface PatchSource {
+    filename: string;
+    status: string;
+    additions: number;
+    deletions: number;
+    previousFilename?: string;
+    /** Changed lines as the host counts them; 0 means there is nothing to show. */
+    changes: number;
+}
+export interface PatchPage {
+    files: PullRequestFileView[];
+    patchesComplete: boolean;
+    truncatedFiles: string[];
+    nextPatchCursor: string | null;
+    remainingPatchFiles: number;
+}
+/** The longest patchCursor this module issues or accepts; callers use it as the tool schema's maximum. */
+export declare const MAX_PATCH_CURSOR_CHARS = 4000;
+/** "code" (source, tests, config, migrations) is filled first; "other" is everything a review can skim. */
+export declare function reviewGroup(path: string): "code" | "other";
+/** Code first; the host's order within each group (stable). */
+export declare function reviewOrder<T extends {
+    filename: string;
+}>(files: T[]): T[];
+/**
+ * One page of patches: every file in review order, with patch content for the files from the
+ * cursor on until `budget` characters are used. `load` is called only for files on this page
+ * (undefined: the host has no patch, which is unavailable when the file has changes).
+ */
+export declare function pagePatches(sources: PatchSource[], opts: {
+    budget: number;
+    cursor?: string;
+    headSha: string;
+    comparedFrom: string | null;
+}, load: (file: PatchSource) => Promise<string | undefined>): Promise<PatchPage>;

package/dist/providers/review-host/patch-pages.js

@@ -0,0 +1,176 @@
+/**
+ * repo_pr_read's diff pages: which files get the patch budget first (code before docs, help,
+ * lockfiles, generated files and fixtures), how a page is filled from a cursor, and the cursor
+ * itself. Shared by every review host so paging behaves the same on GitHub and local repositories.
+ */
+import { PatchCursorError } from "./types.js";
+const LOCKFILES = new Set([
+    "package-lock.json",
+    "npm-shrinkwrap.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    "bun.lockb",
+    "poetry.lock",
+    "uv.lock",
+    "Pipfile.lock",
+    "Cargo.lock",
+    "go.sum",
+    "Gemfile.lock",
+    "composer.lock",
+    "mix.lock",
+    "pubspec.lock",
+]);
+const OTHER_EXTENSIONS = /\.(md|mdx|rst|adoc|txt|snap|svg|png|jpe?g|gif|webp|ico|pdf|lock)$/i;
+// docs/ and help/ are the repository's own documentation folders (root only); the rest can be anywhere.
+const OTHER_DIRECTORY = /^(docs?|help)\/|(^|\/)(generated|__generated__|dist|vendor|fixtures|__fixtures__|__snapshots__|testdata)\//i;
+const MINIFIED = /\.min\.(js|css)$/i;
+/** The longest patchCursor this module issues or accepts; callers use it as the tool schema's maximum. */
+export const MAX_PATCH_CURSOR_CHARS = 4000;
+/** "code" (source, tests, config, migrations) is filled first; "other" is everything a review can skim. */
+export function reviewGroup(path) {
+    const base = path.slice(path.lastIndexOf("/") + 1);
+    if (/^requirements.*\.txt$/i.test(base) || base === "CMakeLists.txt")
+        return "code";
+    if (LOCKFILES.has(base) || OTHER_EXTENSIONS.test(base) || MINIFIED.test(base) || OTHER_DIRECTORY.test(path))
+        return "other";
+    return "code";
+}
+/** Code first; the host's order within each group (stable). */
+export function reviewOrder(files) {
+    return [
+        ...files.filter((f) => reviewGroup(f.filename) === "code"),
+        ...files.filter((f) => reviewGroup(f.filename) === "other"),
+    ];
+}
+const CURSOR = /^v1\.([0-9a-f]{40})\.([0-9a-f]{40}|-)\.(\d{1,6})\.(\d{1,9})\.(-|\d{1,6}(?:,\d{1,6})*)$/;
+function encodeCursor(headSha, comparedFrom, pos) {
+    const u = pos.unavailable.length ? pos.unavailable.join(",") : "-";
+    return `v1.${headSha}.${comparedFrom ?? "-"}.${pos.fileIndex}.${pos.offset}.${u}`;
+}
+function parseCursor(cursor, headSha, comparedFrom, fileCount) {
+    const m = cursor.length <= MAX_PATCH_CURSOR_CHARS ? CURSOR.exec(cursor) : null;
+    if (!m)
+        throw new PatchCursorError("malformed");
+    if (m[1] !== headSha || m[2] !== (comparedFrom ?? "-"))
+        throw new PatchCursorError("stale");
+    const pos = {
+        fileIndex: Number(m[3]),
+        offset: Number(m[4]),
+        unavailable: m[5] === "-" ? [] : m[5].split(",").map(Number),
+    };
+    if (pos.fileIndex > fileCount)
+        throw new PatchCursorError("malformed");
+    let previous = -1;
+    for (const index of pos.unavailable) {
+        if (index <= previous || index >= pos.fileIndex)
+            throw new PatchCursorError("malformed");
+        previous = index;
+    }
+    return pos;
+}
+/**
+ * The longest prefix of `text` within `max` characters that ends at a line break. With no break
+ * in range, a single longer line is cut at `max` when `hardCut`, else nothing is returned.
+ */
+function cutAtLine(text, max, hardCut) {
+    if (text.length <= max)
+        return text;
+    const cut = text.lastIndexOf("\n", max - 1);
+    if (cut >= 0)
+        return text.slice(0, cut + 1);
+    return hardCut ? text.slice(0, max) : "";
+}
+/**
+ * One page of patches: every file in review order, with patch content for the files from the
+ * cursor on until `budget` characters are used. `load` is called only for files on this page
+ * (undefined: the host has no patch, which is unavailable when the file has changes).
+ */
+export async function pagePatches(sources, opts, load) {
+    const ordered = reviewOrder(sources);
+    const start = opts.cursor
+        ? parseCursor(opts.cursor, opts.headSha, opts.comparedFrom, ordered.length)
+        : { fileIndex: 0, offset: 0, unavailable: [] };
+    const earlierUnavailable = new Set(start.unavailable);
+    const unavailable = [...start.unavailable];
+    let budget = opts.budget;
+    let next = null;
+    const files = [];
+    let pageHasCode = false;
+    for (const [index, source] of ordered.entries()) {
+        const { changes, ...view } = source;
+        const out = (patchStatus, patch = "", part) => ({
+            ...view,
+            patch,
+            patchStatus,
+            patchTruncated: patchStatus === "later_page" || patchStatus === "unavailable" || (part?.continues ?? false),
+            ...(part ? { patchOffset: part.offset, patchContinues: part.continues } : {}),
+        });
+        if (index < start.fileIndex) {
+            files.push(out(changes === 0 ? "empty" : earlierUnavailable.has(index) ? "unavailable" : "earlier_page"));
+            continue;
+        }
+        if (next) {
+            files.push(out(changes === 0 ? "empty" : "later_page"));
+            continue;
+        }
+        // A page that carries code ends where the docs, lockfiles and generated files begin, so a
+        // reviewer can stop paging there without that text sitting in its context.
+        if (pageHasCode && changes > 0 && reviewGroup(source.filename) === "other") {
+            files.push(out("later_page"));
+            next = { fileIndex: index, offset: 0 };
+            continue;
+        }
+        const patch = await load(source);
+        const offset = index === start.fileIndex ? start.offset : 0;
+        if (patch === undefined || patch === "") {
+            if (offset > 0)
+                throw new PatchCursorError("malformed");
+            if (changes === 0) {
+                files.push(out("empty"));
+            }
+            else {
+                files.push(out("unavailable"));
+                unavailable.push(index);
+            }
+            continue;
+        }
+        // A cursor never points at the end: the part that reaches it does not continue.
+        if (offset >= patch.length && offset > 0)
+            throw new PatchCursorError("malformed");
+        const rest = patch.slice(offset);
+        if (reviewGroup(source.filename) === "code")
+            pageHasCode = true;
+        if (rest.length <= budget) {
+            files.push(offset === 0 ? out("complete", rest) : out("partial", rest, { offset, continues: false }));
+            budget -= rest.length;
+            if (budget <= 0 && index + 1 < ordered.length)
+                next = { fileIndex: index + 1, offset: 0 };
+            continue;
+        }
+        // A single line longer than the whole budget is cut only when nothing else is on the page;
+        // otherwise the file waits for the next page.
+        const firstContent = !files.some((f) => f.patchStatus === "complete" || f.patchStatus === "partial");
+        const part = budget > 0 ? cutAtLine(rest, budget, firstContent) : "";
+        if (part.length === 0) {
+            files.push(out("later_page"));
+            next = { fileIndex: index, offset };
+            continue;
+        }
+        files.push(out("partial", part, { offset, continues: true }));
+        next = { fileIndex: index, offset: offset + part.length };
+    }
+    const truncatedFiles = files.filter((f) => f.patchTruncated).map((f) => f.filename);
+    const remainingPatchFiles = files.filter((f) => f.patchStatus === "later_page" || (f.patchStatus === "partial" && f.patchContinues)).length;
+    return {
+        files,
+        truncatedFiles,
+        remainingPatchFiles,
+        nextPatchCursor: next
+            ? encodeCursor(opts.headSha, opts.comparedFrom, {
+                ...next,
+                unavailable: unavailable.filter((i) => i < next.fileIndex),
+            })
+            : null,
+        patchesComplete: next === null && unavailable.length === 0,
+    };
+}

package/dist/providers/review-host/review-format.d.ts

@@ -1,9 +1,26 @@
 import type { CheckConclusion, InlineComment, ReviewVerdict } from "./types.js";
 /** Agent ids are cuids; anything else could break out of the HTML comment. */
 export declare const SAFE_AGENT_MARKER: RegExp;
-export declare function reviewMarker(agentMarker: string, headSha: string): string;
+/**
+ * `coveredSha`: the latest head this agent reviewed after reading every file. A marker without
+ * it (an older one included) means none.
+ */
+export declare function reviewMarker(agentMarker: string, headSha: string, coveredSha?: string | null): string;
+/**
+ * The review marker counts only at the very start of a body, where renderSummaryComment writes it:
+ * anywhere else it is text someone else wrote (model text the App posted, for one).
+ */
 export declare function hasReviewMarker(body: string, agentMarker: string): boolean;
 export declare function parseReviewMarker(body: string, agentMarker: string): string | null;
+/** The marker's covered head; null for a marker without one. */
+export declare function parseCoveredMarker(body: string, agentMarker: string): string | null;
+/**
+ * Model-written text the App posts, with each opener of a wardby marker escaped (`<!--`, shown
+ * as text), so no wardby marker can come from it. Any other `<!--` (in a code block or a
+ * ```suggestion, say) is left as written. One pass is enough: the replacement adds no `<` and no
+ * marker name, so it can never complete a new opener. wardby adds its own markers after this.
+ */
+export declare function escapeHtmlComments(text: string): string;
 export declare function verdictConclusion(verdict: ReviewVerdict): CheckConclusion;
 /** Tags an inline comment with the agent that wrote it, so only that agent resolves its thread. */
 export declare function findingMarker(agentMarker: string): string;
@@ -12,6 +29,7 @@ export declare function renderInlineComment(comment: InlineComment, agentMarker:
 export declare function renderSummaryComment(input: {
     agentMarker: string;
     headSha: string;
+    coveredSha?: string | null;
     verdict: ReviewVerdict;
     summary: string;
     body: string;

package/dist/providers/review-host/review-format.js

@@ -6,20 +6,51 @@ function assertMarker(agentMarker) {
     if (!SAFE_AGENT_MARKER.test(agentMarker))
         throw new Error("review_marker_invalid");
 }
-export function reviewMarker(agentMarker, headSha) {
+/**
+ * `coveredSha`: the latest head this agent reviewed after reading every file. A marker without
+ * it (an older one included) means none.
+ */
+export function reviewMarker(agentMarker, headSha, coveredSha) {
     assertMarker(agentMarker);
     if (!SAFE_SHA.test(headSha))
         throw new Error("review_marker_invalid");
-    return `${MARKER_PREFIX}${agentMarker} sha=${headSha} -->`;
+    if (coveredSha && !SAFE_SHA.test(coveredSha))
+        throw new Error("review_marker_invalid");
+    return `${MARKER_PREFIX}${agentMarker} sha=${headSha}${coveredSha ? ` covered=${coveredSha}` : ""} -->`;
 }
+/**
+ * The review marker counts only at the very start of a body, where renderSummaryComment writes it:
+ * anywhere else it is text someone else wrote (model text the App posted, for one).
+ */
 export function hasReviewMarker(body, agentMarker) {
     assertMarker(agentMarker);
-    return body.includes(`${MARKER_PREFIX}${agentMarker} sha=`);
+    return body.startsWith(`${MARKER_PREFIX}${agentMarker} sha=`);
 }
-export function parseReviewMarker(body, agentMarker) {
+function matchReviewMarker(body, agentMarker) {
     assertMarker(agentMarker);
-    const match = new RegExp(`${MARKER_PREFIX}${agentMarker} sha=([0-9a-f]{40}) -->`).exec(body);
-    return match ? match[1] : null;
+    return new RegExp(`^${MARKER_PREFIX}${agentMarker} sha=([0-9a-f]{40})(?: covered=([0-9a-f]{40}))? -->`).exec(body);
+}
+export function parseReviewMarker(body, agentMarker) {
+    return matchReviewMarker(body, agentMarker)?.[1] ?? null;
+}
+/** The marker's covered head; null for a marker without one. */
+export function parseCoveredMarker(body, agentMarker) {
+    return matchReviewMarker(body, agentMarker)?.[2] ?? null;
+}
+/**
+ * An HTML comment opener that starts a wardby marker: every marker wardby writes or ever wrote
+ * names `wardby…` (wardby:review/finding, wardby-status/description/latest/related) or the legacy
+ * `reevo-run…`. Case-insensitive, wider than any parse of them.
+ */
+const MARKER_OPENER = /<!--(?=\s*(?:wardby|reevo-run))/gi;
+/**
+ * Model-written text the App posts, with each opener of a wardby marker escaped (`&lt;!--`, shown
+ * as text), so no wardby marker can come from it. Any other `<!--` (in a code block or a
+ * ```suggestion, say) is left as written. One pass is enough: the replacement adds no `<` and no
+ * marker name, so it can never complete a new opener. wardby adds its own markers after this.
+ */
+export function escapeHtmlComments(text) {
+    return text.replace(MARKER_OPENER, "&lt;!--");
 }
 export function verdictConclusion(verdict) {
     if (verdict === "APPROVE")
@@ -47,7 +78,7 @@ export function renderInlineComment(comment, agentMarker) {
 }
 export function renderSummaryComment(input) {
     const sections = [
-        reviewMarker(input.agentMarker, input.headSha),
+        reviewMarker(input.agentMarker, input.headSha, input.coveredSha),
         `${BADGES[input.verdict]} — reviewed \`${input.headSha.slice(0, 7)}\``,
         input.summary,
         input.body,