@open-cr-agent/vcs-platform 0.1.2 → 0.3.0

package/dist/index.d.ts

@@ -1,6 +1,4 @@
-export * from "./platform.js";
-export * from "./render.js";
-export * from "./retry.js";
-export * from "./review.js";
-export * from "./state.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";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,6 +1,3 @@
-export * from "./platform.js";
-export * from "./render.js";
-export * from "./retry.js";
-export * from "./review.js";
-export * from "./state.js";
+export { MAX_ATTEMPTS, retryDecision } from "./retry.js";
+export { PlatformReview, } from "./review.js";
 //# sourceMappingURL=index.js.map

package/dist/internal.d.ts

@@ -0,0 +1,5 @@
+export { safeMarkdown } from "./neutralize.js";
+export { renderSummary } from "./render.js";
+export { declinesFinding } from "./review.js";
+export { MAX_WRITTEN_STATE_CHARS, readState, SUMMARY_MARKER, writeState } from "./state.js";
+//# sourceMappingURL=internal.d.ts.map

package/dist/internal.js

@@ -0,0 +1,7 @@
+// "@open-cr-agent/vcs-platform/internal": what the platform adapters' tests
+// check against. Not a contract: any release may change it.
+export { safeMarkdown } from "./neutralize.js";
+export { renderSummary } from "./render.js";
+export { declinesFinding } from "./review.js";
+export { MAX_WRITTEN_STATE_CHARS, readState, SUMMARY_MARKER, writeState } from "./state.js";
+//# sourceMappingURL=internal.js.map

package/dist/neutralize.d.ts

@@ -0,0 +1,5 @@
+export interface Placement {
+    startsLine?: boolean;
+}
+export declare function safeMarkdown(text: string, { startsLine }?: Placement): string;
+//# sourceMappingURL=neutralize.d.ts.map

package/dist/neutralize.js

@@ -0,0 +1,117 @@
+// 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
+// (GitLab runs a line such as `/merge` or `/approve` in a comment as a quick
+// action, with the rights of the token that posted it), or become a link at
+// all. A pull request can plant an address for a reviewer to repeat (the
+// adversarial probe saw one), and a bot comment lends it credibility.
+// Character references get a zero-width space after their `&` and stay as
+// typed, since both platforms look for mentions after decoding them
+// (`@all`); unlike `&`, it keeps `<` quoted in code readable.
+// Every `@` gets one too, which no mention survives (GitLab usernames may
+// start with `_` or `.`), nor an email address. Inline links lose their `](`,
+// and every `]:` is escaped, so no link reference definition (`[1]: https://…`)
+// can form, at line start or inside a blockquote or list item, and no
+// reference-style link (`[x][1]`, `[x][]`, `[1]`) has anything to resolve to.
+// Addresses of every scheme get a zero-width space after the colon (GitLab
+// links `smb://` and `vscode://` too), and `www.` one before its dot, so they
+// read the same and stay text.
+//
+// Code is left as written, so that a reader who copies what a finding quotes
+// gets the code and not our zero-width spaces: nothing inside a code span
+// renders as a mention, link, image or HTML on either platform, and GitLab's
+// quick-action extractor skips code blocks and inline code. Code is what
+// CommonMark would render as code where the text is posted, and only what
+// both platforms agree on: a backtick fence that starts a line of the posted
+// comment and is closed, and an inline backtick run closed on the same line by
+// a run of the same length. A `~~~` fence, an indented block and a span across
+// lines keep the text rules. An unbalanced backtick run is text; it is escaped
+// so that it cannot pair with a backtick in a later piece of the same comment
+// and open a span that we did not neutralize. Two things stay neutralized in
+// code because ocra reads them from the raw body, not the rendering: an HTML
+// comment opener (ocra's markers) and `/ocra` (its commands).
+const CHARACTER_REFERENCE = /&(?=#\d{1,7};|#[xX][\da-fA-F]{1,6};|[A-Za-z][A-Za-z\d]{1,31};)/g;
+const FENCE_OPENER = /^ {0,3}(`{3,})[^`]*$/;
+// A backtick string; `\`` is an escaped backtick, so never part of one.
+const BACKTICK_RUN = /\\`|`+/g;
+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 opener = i > 0 || startsLine ? FENCE_OPENER.exec(line) : null;
+        const end = opener ? closingFence(lines, i + 1, opener[1].length) : -1;
+        if (end === -1) {
+            out.push(neutralizeInline(line));
+            continue;
+        }
+        for (let j = i; j <= end; j++)
+            out.push(neutralizeCode(lines[j]));
+        i = end;
+    }
+    return out.join("\n");
+}
+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]))
+            return j;
+    return -1;
+}
+// One line: code spans per CommonMark's pairing of backtick strings, the
+// text between them neutralized, unpaired strings escaped.
+function neutralizeInline(line) {
+    const runs = [...line.matchAll(BACKTICK_RUN)]
+        .filter((m) => m[0] !== "\\`")
+        .map((m) => ({ start: m.index, end: m.index + m[0].length }));
+    const out = [];
+    let cursor = 0;
+    let text = "";
+    const flushText = (upTo) => {
+        text += line.slice(cursor, upTo);
+        cursor = upTo;
+    };
+    const emitText = () => {
+        if (text !== "")
+            out.push(neutralizeText(text, out.length === 0));
+        text = "";
+    };
+    for (let k = 0; k < runs.length; k++) {
+        const open = runs[k];
+        const length = open.end - open.start;
+        const closeAt = runs.findIndex((r, j) => j > k && r.end - r.start === length);
+        if (closeAt === -1) {
+            flushText(open.start);
+            text += "\\`".repeat(length);
+            cursor = open.end;
+            continue;
+        }
+        const close = runs[closeAt];
+        flushText(open.start);
+        emitText();
+        out.push(neutralizeCode(line.slice(open.start, close.end)));
+        cursor = close.end;
+        k = closeAt;
+    }
+    flushText(line.length);
+    emitText();
+    return out.join("");
+}
+function neutralizeText(text, atLineStart) {
+    const safe = text
+        .replace(CHARACTER_REFERENCE, "&​")
+        .replaceAll("<!--", "&lt;!--")
+        .replace(/<\/?[a-zA-Z][^>]*>/g, (tag) => tag.replaceAll("<", "&lt;"))
+        .replaceAll("@", "@​")
+        .replace(/!\[/g, "!​[")
+        .replace(/\/(?=ocra)/gi, "/​")
+        .replace(/:(?=\/\/)/g, ":​")
+        .replace(/\bwww(?=\.)/gi, "www​")
+        .replaceAll("](", "]\\(")
+        .replaceAll("]:", "]\\:");
+    return atLineStart ? safe.replace(/^([ \t]*)\//, "$1​/") : safe;
+}
+function neutralizeCode(code) {
+    return code.replaceAll("<!--", "<!​--").replace(/\/(?=ocra)/gi, "/​");
+}
+//# sourceMappingURL=neutralize.js.map

package/dist/render.d.ts

@@ -4,7 +4,6 @@ export interface PlatformText {
     changeRequest: string;
     authority: string;
 }
-export declare function safeMarkdown(text: string): string;
 export declare function codeSpan(text: string): string;
 export declare const FINDING_MARKER: RegExp;
 export declare function inlineBody(f: Finding): string;

package/dist/render.js

@@ -1,4 +1,5 @@
 import { coverageGaps, } from "@open-cr-agent/core";
+import { safeMarkdown } from "./neutralize.js";
 import { SUMMARY_MARKER, writeState } from "./state.js";
 // GitHub rejects comments over 65,536 characters; GitLab takes 1,000,000,
 // but a summary that long is no use to anyone.
@@ -52,39 +53,6 @@ const VERDICT = {
     minor_issues: "⚠️ Minor issues",
     significant_concerns: "🛑 Significant concerns",
 };
-// 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
-// (GitLab runs a line such as `/merge` or `/approve` in a comment as a quick
-// action, with the rights of the token that posted it), or become a link at
-// all. A pull request can plant an address for a reviewer to repeat (the
-// adversarial probe saw one), and a bot comment lends it credibility.
-// Character references get a zero-width space after their `&` and stay as
-// typed, since both platforms look for mentions after decoding them
-// (`@all`); unlike `&`, it keeps `<` quoted in code readable.
-// Every `@` gets one too, which no mention survives (GitLab usernames may
-// start with `_` or `.`), nor an email address. Inline links lose their `](`,
-// and every `]:` is escaped, so no link reference definition (`[1]: https://…`)
-// can form, at line start or inside a blockquote or list item, and no
-// reference-style link (`[x][1]`, `[x][]`, `[1]`) has anything to resolve to.
-// Addresses of every scheme get a zero-width space after the colon (GitLab
-// links `smb://` and `vscode://` too), and `www.` one before its dot, so they
-// read the same and stay text.
-const CHARACTER_REFERENCE = /&(?=#\d{1,7};|#[xX][\da-fA-F]{1,6};|[A-Za-z][A-Za-z\d]{1,31};)/g;
-export function safeMarkdown(text) {
-    return text
-        .replace(CHARACTER_REFERENCE, "&\u200b")
-        .replaceAll("<!--", "&lt;!--")
-        .replace(/<\/?[a-zA-Z][^>]*>/g, (tag) => tag.replaceAll("<", "&lt;"))
-        .replaceAll("@", "@\u200b")
-        .replace(/!\[/g, "!\u200b[")
-        .replace(/\/(?=ocra)/gi, "/\u200b")
-        .replace(/^([ \t]*)\//gm, "$1\u200b/")
-        .replace(/:(?=\/\/)/g, ":\u200b")
-        .replace(/\bwww(?=\.)/gi, "www\u200b")
-        .replaceAll("](", "]\\(")
-        .replaceAll("]:", "]\\:");
-}
 // 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.
@@ -108,7 +76,7 @@ export function inlineBody(f) {
         `<!-- ocra:finding ${f.fingerprint} -->`,
         `${ICON[f.severity]} **${safeMarkdown(f.title)}** · ${f.severity} · ${verification(f)} · ${f.reviewer}${f.lowConfidence ? " · low confidence" : ""}`,
         "",
-        safeMarkdown(f.body),
+        safeMarkdown(f.body, { startsLine: true }),
     ];
     if (f.suggestion)
         parts.push("", `**Suggestion:** ${safeMarkdown(f.suggestion)}`);
@@ -122,7 +90,7 @@ export function renderSummary({ report, commented, state, text, unattributed = 0
         SUMMARY_MARKER,
         `## ocra review · ${headline(report)}`,
         "",
-        safeMarkdown(report.summary),
+        safeMarkdown(report.summary, { startsLine: true }),
         ...overrideNote(report, text),
         "",
         `**${report.findings.length} finding(s)** (${counts}) · risk tier \`${report.tier}\``,
@@ -158,7 +126,7 @@ export function renderSummary({ report, commented, state, text, unattributed = 0
     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", " ")}`);
+            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) {
@@ -192,7 +160,7 @@ export function renderSummary({ report, commented, state, text, unattributed = 0
     }
     const failed = report.coverage.filter((c) => c.status === "failed" || c.status === "unreviewed");
     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)}`, ...failed.map((c) => `- not reviewed: ${codeSpan(c.path)}`), "", "</details>");
+    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;

package/dist/review.d.ts

@@ -1,4 +1,4 @@
-import { type ChangeRequest, type CodeMatch, type FileDiff, type PriorReview, type ReviewReport, type VcsAdapter } from "@open-cr-agent/core";
+import type { ChangeRequest, CodeMatch, FileDiff, PriorReview, ReviewReport, VcsAdapter } from "@open-cr-agent/core";
 import type { ReviewPlatform } from "./platform.js";
 export type CodeSource = Pick<VcsAdapter, "getDiff" | "readFile" | "searchCode">;
 export interface History {

package/dist/review.js

@@ -1,4 +1,4 @@
-import { errorMessage, } from "@open-cr-agent/core";
+import { errorMessage } from "@open-cr-agent/core/internal";
 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;

package/dist/state.d.ts

@@ -1,5 +1,4 @@
-import type { PriorFinding } from "@open-cr-agent/core";
-import { type RiskTier } from "@open-cr-agent/core";
+import type { PriorFinding, RiskTier } from "@open-cr-agent/core";
 export declare const SUMMARY_MARKER = "<!-- ocra:review -->";
 export declare const MAX_WRITTEN_STATE_CHARS = 30000;
 export interface ReviewState {

package/dist/state.js

@@ -1,4 +1,4 @@
-import { RISK_TIERS, severitySchema, verificationSchema } from "@open-cr-agent/core";
+import { RISK_TIERS, severitySchema, verificationSchema } from "@open-cr-agent/core/internal";
 import { z } from "zod";
 export const SUMMARY_MARKER = "<!-- ocra:review -->";
 // Only a state block that ends the comment counts: author-controlled text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-cr-agent/vcs-platform",
-  "version": "0.1.2",
+  "version": "0.3.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",
@@ -19,18 +19,26 @@
     "node": ">=22.19"
   },
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
+      "@open-cr-agent/source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./internal": {
+      "@open-cr-agent/source": "./src/internal.ts",
+      "types": "./dist/internal.d.ts",
+      "default": "./dist/internal.js"
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
     "!dist/**/*.map"
   ],
   "dependencies": {
-    "@open-cr-agent/core": "0.1.2",
+    "@open-cr-agent/core": "0.3.0",
     "zod": "^4.6.5"
   },
   "publishConfig": {