@open-cr-agent/vcs-platform 0.4.0 → 0.6.0

package/dist/http.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+export interface PlatformApi {
+    platform: string;
+    headers: Record<string, string>;
+    fetch: typeof fetch;
+    sleep?: ((ms: number) => Promise<void>) | undefined;
+    timeoutMs: (method: string, path: string) => number;
+    toError: (status: number, message: string) => Error;
+}
+export interface PlatformCall {
+    method: string;
+    url: string;
+    path: string;
+    body?: unknown;
+    idempotent?: boolean;
+}
+export declare function sendWithRetry(api: PlatformApi, call: PlatformCall): Promise<unknown>;
+export declare const pageInfoSchema: z.ZodObject<{
+    hasNextPage: z.ZodBoolean;
+    endCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.js

@@ -0,0 +1,53 @@
+import { setTimeout as wait } from "node:timers/promises";
+import { z } from "zod";
+import { retryDecision } from "./retry.js";
+const USER_AGENT = "open-cr-agent";
+// How much of a refused request's answer an error quotes.
+const MAX_DETAIL_CHARS = 500;
+// Sends a JSON request to a platform's API, retrying rate limits, outages
+// and lost connections a bounded number of times; resolves to the parsed
+// answer, or undefined for a 204.
+export async function sendWithRetry(api, call) {
+    const { method, url, path, body } = call;
+    const idempotent = call.idempotent ?? method !== "POST";
+    const sleep = api.sleep ?? ((ms) => wait(ms));
+    for (let attempt = 1;; attempt += 1) {
+        const init = {
+            method,
+            headers: {
+                ...api.headers,
+                "User-Agent": USER_AGENT,
+                ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+            },
+            signal: AbortSignal.timeout(api.timeoutMs(method, path)),
+        };
+        if (body !== undefined)
+            init.body = JSON.stringify(body);
+        let response;
+        try {
+            response = await api.fetch(url, init);
+        }
+        catch (error) {
+            const next = retryDecision(method, idempotent, "network_error", attempt);
+            if (!next.retry)
+                throw error;
+            await sleep(next.waitMs);
+            continue;
+        }
+        if (response.ok)
+            return response.status === 204 ? undefined : response.json();
+        const detail = (await response.text().catch(() => "")).slice(0, MAX_DETAIL_CHARS);
+        const next = retryDecision(method, idempotent, { status: response.status, headers: response.headers, body: detail }, attempt);
+        if (!next.retry) {
+            const where = `${api.platform} ${method} ${path.split("?")[0]}`;
+            throw api.toError(response.status, `${where} failed with ${response.status}: ${detail}`);
+        }
+        await sleep(next.waitMs);
+    }
+}
+// Both platforms' GraphQL APIs page connections the same way.
+export const pageInfoSchema = z.object({
+    hasNextPage: z.boolean(),
+    endCursor: z.string().nullable(),
+});
+//# sourceMappingURL=http.js.map

package/dist/index.d.ts

@@ -1,4 +1,7 @@
+export { changeRequestSchema, codeSourceSchema, commitIdSchema, fetchSchema, historySchema, } from "./options.js";
 export type { Bot, InlineFinding, PlatformChangeRequest, PlatformComment, PlatformThread, PublishedFindings, ReviewPlatform, } from "./platform.js";
 export { MAX_ATTEMPTS, type RetryDecision, retryDecision } from "./retry.js";
 export { type CodeSource, type History, PlatformReview, type PlatformReviewOptions, } from "./review.js";
+export { githubSuggestion, gitlabSuggestion, type SuggestionFence, } from "./suggestion.js";
+export type { ChangeRequestRef, LocalCode, PlatformTarget, ResolveTargetOptions, } from "./target.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,3 +1,7 @@
+// The review conversation every platform adapter shares (ADR-0016), for
+// ocra's own adapters. Not a contract yet: a minor release may change it.
+export { changeRequestSchema, codeSourceSchema, commitIdSchema, fetchSchema, historySchema, } from "./options.js";
 export { MAX_ATTEMPTS, retryDecision } from "./retry.js";
 export { PlatformReview, } from "./review.js";
+export { githubSuggestion, gitlabSuggestion, } from "./suggestion.js";
 //# sourceMappingURL=index.js.map

package/dist/internal.d.ts

@@ -1,3 +1,4 @@
+export { type PlatformApi, type PlatformCall, pageInfoSchema, sendWithRetry, } from "./http.js";
 export { safeMarkdown } from "./neutralize.js";
 export { renderSummary } from "./render.js";
 export { declinesFinding } from "./review.js";

package/dist/internal.js

@@ -1,5 +1,6 @@
 // "@open-cr-agent/vcs-platform/internal": what the platform adapters' tests
 // check against. Not a contract: any release may change it.
+export { pageInfoSchema, sendWithRetry, } from "./http.js";
 export { safeMarkdown } from "./neutralize.js";
 export { renderSummary } from "./render.js";
 export { declinesFinding } from "./review.js";

package/dist/neutralize.js

@@ -1,3 +1,4 @@
+import { at } from "@open-cr-agent/core/internal";
 // Model text is untrusted: it may not close our markup, mention people,
 // pull in images, spell one of ocra's commands (`/ocra …`, which would count
 // if ocra posted as a person with write access), start a line with a slash
@@ -38,15 +39,15 @@ export function safeMarkdown(text, { startsLine = false } = {}) {
     const lines = text.split("\n");
     const out = [];
     for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
+        const line = at(lines, i);
         const opener = i > 0 || startsLine ? FENCE_OPENER.exec(line) : null;
-        const end = opener ? closingFence(lines, i + 1, opener[1].length) : -1;
+        const end = opener ? closingFence(lines, i + 1, at(opener, 1).length) : -1;
         if (end === -1) {
             out.push(neutralizeInline(line));
             continue;
         }
         for (let j = i; j <= end; j++)
-            out.push(neutralizeCode(lines[j]));
+            out.push(neutralizeCode(at(lines, j)));
         i = end;
     }
     return out.join("\n");
@@ -54,7 +55,7 @@ export function safeMarkdown(text, { startsLine = false } = {}) {
 function closingFence(lines, from, length) {
     const closer = new RegExp(`^ {0,3}\`{${length},}[ \\t]*$`);
     for (let j = from; j < lines.length; j++)
-        if (closer.test(lines[j]))
+        if (closer.test(at(lines, j)))
             return j;
     return -1;
 }

package/dist/options.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import type { CodeSource, History } from "./review.js";
+export declare const codeSourceSchema: z.ZodCustom<CodeSource, CodeSource>;
+export declare const historySchema: z.ZodCustom<History, History>;
+export declare const fetchSchema: z.ZodCustom<typeof fetch, typeof fetch>;
+export declare const commitIdSchema: z.ZodString;
+export declare const changeRequestSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodString;
+    baseSha: z.ZodString;
+    headSha: z.ZodString;
+    author: z.ZodExactOptional<z.ZodString>;
+}, z.core.$strip>;
+//# sourceMappingURL=options.d.ts.map

package/dist/options.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+// What every platform adapter's registry options share. The code source and
+// the history are ports the caller implements, so only their shape can be
+// checked; the change request is data and is validated in full.
+const hasMethods = (value, methods) => typeof value === "object" &&
+    value !== null &&
+    methods.every((m) => typeof value[m] === "function");
+export const codeSourceSchema = z.custom((value) => hasMethods(value, ["getDiff", "readFile", "searchCode"]), "code must provide getDiff, readFile and searchCode");
+export const historySchema = z.custom((value) => hasMethods(value, ["filesChangedSince"]), "history must provide filesChangedSince");
+export const fetchSchema = z.custom((value) => typeof value === "function");
+// Commit ids reach git as arguments; anything else is refused at the boundary.
+export const commitIdSchema = z.string().regex(/^[0-9a-f]{40}([0-9a-f]{24})?$/, "not a commit id");
+// The change request as the diff under review was built from it.
+export const changeRequestSchema = z.object({
+    id: z.string().min(1),
+    title: z.string(),
+    description: z.string(),
+    baseSha: commitIdSchema,
+    headSha: commitIdSchema,
+    author: z.string().exactOptional(),
+});
+//# sourceMappingURL=options.js.map

package/dist/platform.d.ts

@@ -1,7 +1,9 @@
 import type { Finding, ReviewReport } from "@open-cr-agent/core";
 import type { PlatformText } from "./render.js";
+import type { SuggestionFence } from "./suggestion.js";
 export interface ReviewPlatform {
     readonly text: PlatformText;
+    readonly suggestionFence: SuggestionFence;
     bot(): Promise<Bot>;
     changeRequest(): Promise<PlatformChangeRequest>;
     comments(): Promise<PlatformComment[]>;

package/dist/render.d.ts

@@ -1,12 +1,12 @@
 import { type Finding, type ReviewReport } from "@open-cr-agent/core";
 import { type ReviewState } from "./state.js";
+import { type SuggestionFence } from "./suggestion.js";
 export interface PlatformText {
     changeRequest: string;
     authority: string;
 }
-export declare function codeSpan(text: string): string;
 export declare const FINDING_MARKER: RegExp;
-export declare function inlineBody(f: Finding): string;
+export declare function inlineBody(f: Finding, fence: SuggestionFence): string;
 export interface SummaryInput {
     report: ReviewReport;
     commented: ReadonlySet<string>;

package/dist/render.js

@@ -1,6 +1,7 @@
 import { coverageGaps, } from "@open-cr-agent/core";
 import { safeMarkdown } from "./neutralize.js";
 import { SUMMARY_MARKER, writeState } from "./state.js";
+import { suggestionBlock } from "./suggestion.js";
 // GitHub rejects comments over 65,536 characters; GitLab takes 1,000,000,
 // but a summary that long is no use to anyone.
 const MAX_SUMMARY_CHARS = 65_000;
@@ -56,7 +57,7 @@ const VERDICT = {
 // File paths come from the diff, so the author controls them: a backtick or
 // newline must not end the code span and let markup through, and angle
 // brackets must not form ocra's HTML-comment markers in the raw body.
-export function codeSpan(text) {
+function codeSpan(text) {
     const safe = text
         .replaceAll("`", "\u02cb")
         .replace(/[\r\n]+/g, " ")
@@ -70,8 +71,9 @@ function location(f) {
     const { start, end } = f.lineRange;
     return codeSpan(`${f.file}:${start === end ? start : `${start}-${end}`}`);
 }
+const TILDE_FENCE = /^ {0,3}~{3,}/m;
 export const FINDING_MARKER = /<!-- ocra:finding ([0-9a-f]{16}) -->/;
-export function inlineBody(f) {
+export function inlineBody(f, fence) {
     const parts = [
         `<!-- ocra:finding ${f.fingerprint} -->`,
         `${ICON[f.severity]} **${safeMarkdown(f.title)}** · ${f.severity} · ${verification(f)} · ${f.reviewer}${f.lowConfidence ? " · low confidence" : ""}`,
@@ -80,13 +82,34 @@ export function inlineBody(f) {
     ];
     if (f.suggestion)
         parts.push("", `**Suggestion:** ${safeMarkdown(f.suggestion)}`);
+    // A `~~~` fence in model text stays text to safeMarkdown, and one left open
+    // would run to the end of the comment and swallow the suggestion.
+    const block = TILDE_FENCE.test(parts.join("\n")) ? undefined : suggestionBlock(f, fence);
+    if (block)
+        parts.push("", block);
     return parts.join("\n");
 }
 export function renderSummary({ report, commented, state, text, unattributed = 0, }) {
+    const lines = [
+        ...verdictSection(report, text),
+        ...scopeNote(report),
+        ...incompleteNotes(report, text),
+        ...unattributedNote(unattributed),
+        ...outsideDiff(report.findings, commented),
+        ...memoryNotes(report.remembered),
+        ...rereviewSections(report.rereview),
+        ...coverageAndCost(report),
+    ];
+    const markdown = lines.join("\n");
+    const footer = `\n\n${writeState(state)}`;
+    const room = MAX_SUMMARY_CHARS - footer.length;
+    return ((markdown.length > room ? `${markdown.slice(0, room - 40)}\n\n…(truncated)` : markdown) + footer);
+}
+function verdictSection(report, text) {
     const counts = ["critical", "warning", "suggestion"]
         .map((s) => `${report.findings.filter((f) => f.severity === s).length} ${s}`)
         .join(", ");
-    const lines = [
+    return [
         SUMMARY_MARKER,
         `## ocra review · ${headline(report)}`,
         "",
@@ -95,12 +118,18 @@ export function renderSummary({ report, commented, state, text, unattributed = 0
         "",
         `**${report.findings.length} finding(s)** (${counts}) · risk tier \`${report.tier}\``,
     ];
+}
+function scopeNote(report) {
     if (report.scope?.mode === "incremental") {
-        lines.push("", `Reviewed only what changed since ${codeSpan(report.scope.since.slice(0, 7))}.`);
-    }
-    else if (report.scope) {
-        lines.push("", `Reviewed every file again: ${safeMarkdown(report.scope.reason)}.`);
+        return ["", `Reviewed only what changed since ${codeSpan(report.scope.since.slice(0, 7))}.`];
     }
+    if (report.scope)
+        return ["", `Reviewed every file again: ${safeMarkdown(report.scope.reason)}.`];
+    return [];
+}
+// Unverified criticals that cap the verdict, and what the run did not check.
+function incompleteNotes(report, text) {
+    const lines = [];
     // Only true while no confirmed critical blocks, and low-confidence
     // findings do not count at all.
     const unverified = report.verdict === "significant_concerns"
@@ -119,51 +148,90 @@ export function renderSummary({ report, commented, state, text, unattributed = 0
             : "";
         lines.push("", `**Incomplete:** ${notReviewed} selected file(s) were not reviewed${limit}. They are listed under Coverage and cost, and the next review of this ${text.changeRequest} includes them.`);
     }
-    if (unattributed > 0) {
-        lines.push("", `${unattributed} resolved thread(s) of ocra's did not dismiss their finding: nothing says who resolved them, as when a push resolves outdated threads. To dismiss a finding, answer its thread with \`/ocra dismiss\` or "won't fix".`);
-    }
-    const inSummary = report.findings.filter((f) => !commented.has(f.fingerprint));
-    if (inSummary.length > 0) {
-        lines.push("", "### Findings outside the diff");
-        for (const f of inSummary) {
-            lines.push(`- ${ICON[f.severity]} ${location(f)} **${safeMarkdown(f.title)}** _(${verification(f)}${f.lowConfidence ? ", low confidence" : ""})_: ${safeMarkdown(f.body.replaceAll("\n", " "))}`);
-        }
-    }
-    if (report.remembered.length > 0) {
-        lines.push("", `${report.remembered.length} finding(s) matched \`.ocra/memory.json\` and are not repeated.`);
-    }
-    const rereview = report.rereview;
-    if (rereview && rereview.fixed.length > 0) {
-        lines.push("", "### Fixed since the last review");
-        for (const f of rereview.fixed)
-            lines.push(`- ~~${safeMarkdown(f.title)}~~ ${codeSpan(f.file)}`);
-    }
-    if (rereview && rereview.notReproduced.length > 0) {
-        lines.push("", "### Not reported this time, code unchanged", "", "Still open and counted in the verdict until the code changes or a reviewer dismisses them.", "");
-        for (const f of rereview.notReproduced)
-            lines.push(`- ${ICON[f.severity]} ${safeMarkdown(f.title)} ${codeSpan(f.file)} _(${verification(f)})_`);
-    }
-    if (rereview && rereview.unchanged.length > 0) {
-        lines.push("", "### Still open in unchanged files", "", "Reported earlier in files not changed since; they count in the verdict.", "");
-        for (const f of rereview.unchanged)
-            lines.push(`- ${ICON[f.severity]} ${safeMarkdown(f.title)} ${codeSpan(f.file)} _(${verification(f)})_`);
-    }
-    if (rereview && rereview.dismissed.length > 0) {
-        lines.push("", "### Dismissed by reviewers");
-        for (const f of rereview.dismissed)
-            lines.push(`- ${safeMarkdown(f.title)} ${codeSpan(f.file)}`);
+    return lines;
+}
+function unattributedNote(unattributed) {
+    if (unattributed <= 0)
+        return [];
+    return [
+        "",
+        `${unattributed} resolved thread(s) of ocra's did not dismiss their finding: nothing says who resolved them, as when a push resolves outdated threads. To dismiss a finding, answer its thread with \`/ocra dismiss\` or "won't fix".`,
+    ];
+}
+function outsideDiff(findings, commented) {
+    const inSummary = findings.filter((f) => !commented.has(f.fingerprint));
+    if (inSummary.length === 0)
+        return [];
+    return [
+        "",
+        "### Findings outside the diff",
+        ...inSummary.map((f) => `- ${ICON[f.severity]} ${location(f)} **${safeMarkdown(f.title)}** _(${verification(f)}${f.lowConfidence ? ", low confidence" : ""})_: ${safeMarkdown(f.body.replaceAll("\n", " "))}`),
+    ];
+}
+function memoryNotes(remembered) {
+    const lines = [];
+    const fromRepository = remembered.filter((e) => e.source === "repository").length;
+    const fromAccount = remembered.length - fromRepository;
+    if (fromRepository > 0) {
+        lines.push("", `${fromRepository} finding(s) matched \`.ocra/memory.json\` and are not repeated.`);
     }
-    if (rereview && rereview.notRechecked.length > 0) {
-        lines.push("", "### Not re-checked this time", "", "Their files were not reviewed in this run; they stay open and count in the verdict.", "");
-        for (const f of rereview.notRechecked)
-            lines.push(`- ${ICON[f.severity]} ${safeMarkdown(f.title)} ${codeSpan(f.file)} _(${verification(f)})_`);
+    // The reviewer's own account memory can hide findings too; say so, so a
+    // suppression nobody on the team chose is visible (ADR-0028).
+    if (fromAccount > 0) {
+        lines.push("", `${fromAccount} finding(s) matched the reviewing account's ocra Cloud memory and are not repeated.`);
     }
+    return lines;
+}
+function rereviewSections(rereview) {
+    if (!rereview)
+        return [];
+    return [
+        ...(rereview.fixed.length > 0
+            ? [
+                "",
+                "### Fixed since the last review",
+                ...rereview.fixed.map((f) => `- ~~${safeMarkdown(f.title)}~~ ${codeSpan(f.file)}`),
+            ]
+            : []),
+        ...openList("Not reported this time, code unchanged", "Still open and counted in the verdict until the code changes or a reviewer dismisses them.", rereview.notReproduced),
+        ...openList("Still open in unchanged files", "Reported earlier in files not changed since; they count in the verdict.", rereview.unchanged),
+        ...(rereview.dismissed.length > 0
+            ? [
+                "",
+                "### Dismissed by reviewers",
+                ...rereview.dismissed.map((f) => `- ${safeMarkdown(f.title)} ${codeSpan(f.file)}`),
+            ]
+            : []),
+        ...openList("Not re-checked this time", "Their files were not reviewed in this run; they stay open and count in the verdict.", rereview.notRechecked),
+    ];
+}
+// Earlier findings still open, under a heading that says why.
+function openList(title, intro, findings) {
+    if (findings.length === 0)
+        return [];
+    return [
+        "",
+        `### ${title}`,
+        "",
+        intro,
+        "",
+        ...findings.map((f) => `- ${ICON[f.severity]} ${safeMarkdown(f.title)} ${codeSpan(f.file)} _(${verification(f)})_`),
+    ];
+}
+function coverageAndCost(report) {
     const failed = report.coverage.filter((c) => c.status === "failed" || c.status === "unreviewed");
+    const count = (status) => report.coverage.filter((c) => c.status === status).length;
     const { costUsd, inputTokens, outputTokens } = report.usage;
-    lines.push("", "_The verdict is advice from language models that read the change itself, and can be swayed by text in it. Do not use it as a security gate._", "", "<details><summary>Coverage and cost</summary>", "", `${report.coverage.filter((c) => c.status === "reviewed").length} reviewed · ${report.coverage.filter((c) => c.status === "unchanged").length} unchanged since the last review · ${failed.length} not reviewed · ${report.coverage.filter((c) => c.status === "excluded").length} excluded · ${inputTokens} in / ${outputTokens} out tokens · $${costUsd.toFixed(4)}${spendLimitNote(report)} · run ${codeSpan(report.runId)}`, ...failed.map((c) => `- not reviewed: ${codeSpan(c.path)}`), "", "</details>");
-    const markdown = lines.join("\n");
-    const footer = `\n\n${writeState(state)}`;
-    const room = MAX_SUMMARY_CHARS - footer.length;
-    return ((markdown.length > room ? `${markdown.slice(0, room - 40)}\n\n…(truncated)` : markdown) + footer);
+    return [
+        "",
+        "_The verdict is advice from language models that read the change itself, and can be swayed by text in it. Do not use it as a security gate._",
+        "",
+        "<details><summary>Coverage and cost</summary>",
+        "",
+        `${count("reviewed")} reviewed · ${count("unchanged")} unchanged since the last review · ${failed.length} not reviewed · ${count("excluded")} excluded · ${inputTokens} in / ${outputTokens} out tokens · $${costUsd.toFixed(4)}${spendLimitNote(report)} · run ${codeSpan(report.runId)}`,
+        ...failed.map((c) => `- not reviewed: ${codeSpan(c.path)}`),
+        "",
+        "</details>",
+    ];
 }
 //# sourceMappingURL=render.js.map

package/dist/review.d.ts

@@ -16,11 +16,11 @@ export interface PlatformReviewOptions {
 }
 export declare function declinesFinding(reply: string): boolean;
 export declare class PlatformReview implements VcsAdapter {
-    private readonly options;
     readonly name: string;
     private readonly platform;
     private readonly memo;
     private readonly writers;
+    private readonly options;
     constructor(options: PlatformReviewOptions);
     getChangeRequest(): Promise<ChangeRequest>;
     private override;

package/dist/review.js

@@ -1,4 +1,4 @@
-import { errorMessage } from "@open-cr-agent/core/internal";
+import { errorMessage } from "@open-cr-agent/core";
 import { FINDING_MARKER, inlineBody, renderSummary } from "./render.js";
 import { lostProgress, readState, SUMMARY_MARKER } from "./state.js";
 const OVERRIDE = /^\/ocra override ([0-9a-fA-F]{40}(?:[0-9a-fA-F]{24})?)\s+(\S.*)$/m;
@@ -25,11 +25,11 @@ export function declinesFinding(reply) {
 // which earlier state and which comments count, who may override or dismiss,
 // and what gets posted. The platform only maps its API (ReviewPlatform).
 export class PlatformReview {
-    options;
     name;
     platform;
     memo = new Map();
     writers = new Map();
+    options;
     constructor(options) {
         this.options = options;
         this.name = options.name;
@@ -215,7 +215,12 @@ export class PlatformReview {
         const fresh = report.findings.flatMap((f) => {
             if (alreadyCommented.has(f.fingerprint) || !f.lineRange || !f.anchor.inDiff)
                 return [];
-            return [{ finding: { ...f, lineRange: f.lineRange }, body: inlineBody(f) }];
+            return [
+                {
+                    finding: { ...f, lineRange: f.lineRange },
+                    body: inlineBody(f, this.platform.suggestionFence),
+                },
+            ];
         });
         const published = await this.platform.publishFindings(report, fresh);
         const commented = new Set([...alreadyCommented, ...published.posted]);
@@ -240,6 +245,7 @@ export class PlatformReview {
                 commented: commented.has(f.fingerprint),
                 ...(f.quote ? { quote: f.quote } : {}),
                 ...(f.verification ? { verification: f.verification } : {}),
+                reviewer: f.reviewer,
             })),
             ...quiet.filter((f) => !current.has(f.fingerprint)),
         ];

package/dist/state.js

@@ -27,6 +27,7 @@ const stateSchema = z.object({
         })
             .optional(),
         verification: verificationSchema.optional(),
+        reviewer: z.string().min(1).max(100).optional(),
     }))
         .max(MAX_STATE_FINDINGS),
     head: z.string().regex(SHA).optional(),
@@ -51,10 +52,11 @@ export function readState(body) {
             return undefined;
         const { head, pending, posted, tier } = parsed.data;
         return {
-            findings: parsed.data.findings.map(({ quote, verification, ...finding }) => ({
+            findings: parsed.data.findings.map(({ quote, verification, reviewer, ...finding }) => ({
                 ...finding,
                 ...(quote ? { quote } : {}),
                 ...(verification ? { verification } : {}),
+                ...(reviewer ? { reviewer } : {}),
             })),
             ...(head ? { head } : {}),
             ...(pending ? { pending } : {}),
@@ -75,6 +77,7 @@ export function writeState(state) {
         commented: f.commented,
         ...(f.quote ? { quote: f.quote } : {}),
         ...(f.verification ? { verification: f.verification } : {}),
+        ...(f.reviewer && f.reviewer.length <= 100 ? { reviewer: f.reviewer } : {}),
     }));
     // Without the full list of unfinished files the next run could skip one of
     // them, so a list that does not fit drops the head and forces a full review.

package/dist/suggestion.d.ts

@@ -0,0 +1,6 @@
+import type { Finding, LineRange } from "@open-cr-agent/core";
+export type SuggestionFence = (range: LineRange) => string | undefined;
+export declare const githubSuggestion: SuggestionFence;
+export declare const gitlabSuggestion: SuggestionFence;
+export declare function suggestionBlock(f: Finding, fence: SuggestionFence): string | undefined;
+//# sourceMappingURL=suggestion.d.ts.map

package/dist/suggestion.js

@@ -0,0 +1,46 @@
+import { isUnsafeCodePoint } from "@open-cr-agent/core/internal";
+// GitHub's comment spans its lines, so its suggestion replaces them.
+export const githubSuggestion = () => "suggestion";
+// GitLab's thread sits on the range's last line; the suggestion reaches the
+// lines above it, at most 100.
+const GITLAB_MAX_LINES_ABOVE = 100;
+export const gitlabSuggestion = ({ start, end }) => end - start > GITLAB_MAX_LINES_ABOVE ? undefined : `suggestion:-${end - start}+0`;
+const MAX_REPLACEMENT_CHARS = 20_000;
+// What safeMarkdown rewrites even in code, because ocra reads it from the raw
+// comment: its markers and its commands.
+const REWRITTEN_IN_CODE = /<!--|\/ocra/i;
+// A finding's fix as a committable suggestion (ADR-0029): only for a fix of
+// exactly the lines its inline comment is on, and only when the replacement
+// can be posted as written. Neutralizing it like other model text would
+// change the code a click commits, so anything that would need it gets no
+// block. The fence is longer than any backtick run inside, so the
+// replacement cannot close it; inside a code block nothing renders as a
+// mention, link or HTML, and GitLab runs no quick action.
+export function suggestionBlock(f, fence) {
+    const { fix, lineRange } = f;
+    if (!fix || !lineRange || !f.anchor.inDiff)
+        return undefined;
+    if (fix.startLine !== lineRange.start || fix.endLine !== lineRange.end)
+        return undefined;
+    if (!postable(fix.replacement))
+        return undefined;
+    const info = fence(lineRange);
+    if (info === undefined)
+        return undefined;
+    const longestRun = Math.max(0, ...(fix.replacement.match(/`+/g) ?? []).map((r) => r.length));
+    const ticks = "`".repeat(Math.max(3, longestRun + 1));
+    return [`${ticks}${info}`, ...(fix.replacement === "" ? [] : [fix.replacement]), ticks].join("\n");
+}
+// Carriage returns and controls are refused rather than stripped, like
+// everything else that would change the code.
+function postable(replacement) {
+    if (replacement.length > MAX_REPLACEMENT_CHARS || REWRITTEN_IN_CODE.test(replacement)) {
+        return false;
+    }
+    for (const char of replacement) {
+        if (isUnsafeCodePoint(char.codePointAt(0)))
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=suggestion.js.map

package/dist/target.d.ts

@@ -0,0 +1,26 @@
+import type { PluginRegistry, VcsAdapter } from "@open-cr-agent/core";
+import type { CodeSource, History } from "./review.js";
+export interface ChangeRequestRef {
+    number: number;
+    repository?: string;
+}
+export interface ResolveTargetOptions {
+    ref: ChangeRequestRef;
+    env: Readonly<Record<string, string | undefined>>;
+    origin(): Promise<string | undefined>;
+    warn(message: string): void;
+    fetch?: typeof fetch;
+}
+export interface LocalCode {
+    code: CodeSource;
+    history: History;
+}
+export interface PlatformTarget<Settings> {
+    platform: string;
+    baseSha: string;
+    headSha: string;
+    headRefs: string[];
+    webUrl: string;
+    createVcs(registry: Pick<PluginRegistry, "createVcs">, local: LocalCode, settings: Settings): VcsAdapter;
+}
+//# sourceMappingURL=target.d.ts.map

package/dist/target.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=target.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-cr-agent/vcs-platform",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "What Open-CR-Agent's code review platform adapters share: the review summary, its state, and who may command ocra",
   "keywords": [
     "code-review",
@@ -38,7 +38,7 @@
     "!dist/**/*.map"
   ],
   "dependencies": {
-    "@open-cr-agent/core": "0.4.0",
+    "@open-cr-agent/core": "0.6.0",
     "zod": "^4.6.5"
   },
   "publishConfig": {