@open-agent-toolkit/cli 0.1.12 → 0.1.14

package/dist/review-remote/body-builder.js

@@ -0,0 +1,103 @@
+/**
+ * Builder for the posted-review-body (see design.md → Data Models →
+ * Posted-review-body) and the verdict mapper that decides the GitHub review
+ * `event`.
+ *
+ * The body is the durable handoff to `*-receive-remote`: a leading
+ * HTML-comment marker block (parsed back by {@link parseMarkerBlock}) followed
+ * by human-readable prose (summary, severity counts, optional minor-fix nudge,
+ * optional verification commands).
+ */
+import { MARKER_BLOCK_OPEN } from './marker-parser.js';
+/**
+ * Map a finding set to the GitHub review verdict: `REQUEST_CHANGES` when any
+ * critical or important finding is present, otherwise `COMMENT` (including the
+ * zero-findings clean-review case). Never auto-`APPROVE`.
+ */
+export function mapVerdict(findings) {
+    const hasBlocking = findings.some((f) => f.severity === 'critical' || f.severity === 'important');
+    return hasBlocking ? 'REQUEST_CHANGES' : 'COMMENT';
+}
+function countSeverities(findings) {
+    const counts = {
+        critical: 0,
+        important: 0,
+        medium: 0,
+        minor: 0,
+    };
+    for (const f of findings) {
+        counts[f.severity] += 1;
+    }
+    return counts;
+}
+/**
+ * Emit the leading marker block. Mirrors the parser's expected single-line
+ * scalar shape so {@link parseMarkerBlock} round-trips a built body cleanly.
+ * `oat_project` is emitted only when present (key-omitted on the ad-hoc rail).
+ */
+function buildMarkerBlock(input) {
+    const lines = [
+        'oat_provide_remote: true',
+        `oat_review_head_sha: ${input.headSha}`,
+        `oat_review_scope: ${input.scope}`,
+    ];
+    if (input.project !== undefined && input.project !== '') {
+        lines.push(`oat_project: ${input.project}`);
+    }
+    lines.push(`oat_review_invocation: ${input.invocation}`);
+    return `<!-- ${MARKER_BLOCK_OPEN}\n${lines.join('\n')}\n-->`;
+}
+/**
+ * Render the "Findings outside the PR diff" subsection (design.md → Error
+ * Handling → Inline-comment line mapping). Each entry shows its original
+ * `file:line` reference followed by the preserved finding body. A `null` line
+ * renders the bare file path (file-scoped finding). Returns `null` when there
+ * are no out-of-diff findings so no empty heading is emitted.
+ */
+function buildOutOfDiffSection(findings) {
+    if (!findings || findings.length === 0) {
+        return null;
+    }
+    const entries = findings.map((f) => {
+        const reference = f.line === null ? f.file : `${f.file}:${f.line}`;
+        const heading = f.title ? `${reference} — ${f.title}` : reference;
+        return `- **${heading}**\n\n  ${f.body}`;
+    });
+    return ['## Findings outside the PR diff', '', ...entries].join('\n');
+}
+const MINOR_FIX_NUDGE = 'Minor findings are included inline. We recommend fixing minors during ' +
+    'this cycle rather than tracking them as backlog items — they are usually ' +
+    'faster to just resolve than to manage.';
+/**
+ * Build the posted-review body and compute its verdict.
+ */
+export function buildReviewBody(input) {
+    const counts = countSeverities(input.findings);
+    const verdict = mapVerdict(input.findings);
+    const sections = [
+        buildMarkerBlock(input),
+        `## Summary\n\n${input.summary}`,
+        [
+            '## Severity Counts',
+            '',
+            `- Critical: ${counts.critical}`,
+            `- Important: ${counts.important}`,
+            `- Medium: ${counts.medium}`,
+            `- Minor: ${counts.minor}`,
+        ].join('\n'),
+    ];
+    const outOfDiffSection = buildOutOfDiffSection(input.outOfDiffFindings);
+    if (outOfDiffSection !== null) {
+        sections.push(outOfDiffSection);
+    }
+    if (counts.minor > 0) {
+        sections.push(`## Notes\n\n${MINOR_FIX_NUDGE}`);
+    }
+    if (input.verificationCommands && input.verificationCommands.length > 0) {
+        const commands = input.verificationCommands
+            .map((cmd) => `- \`${cmd}\``)
+            .join('\n');
+        sections.push(`## Verification\n\n${commands}`);
+    }
+    return { body: sections.join('\n\n'), verdict };
+}

package/dist/review-remote/capability-probe.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Capability probe for the optional `agent-reviews` posting flow (see design.md
+ * → Error Handling → Capability probe).
+ *
+ * The provide-remote skills prefer `agent-reviews` for tooling symmetry IF it
+ * exposes a "post / submit a full PR review" flow. The probe runs a
+ * non-mutating `agent-reviews --help` once, parses the help text for such a
+ * flag, and caches the result for the run. `gh api` is always the safe
+ * fallback — the probe never fails the skill.
+ *
+ * Empirical current-state finding (probed 2026-05-29, `agent-reviews@1.0.2`):
+ * the CLI exposes list/detail/watch commands plus `--reply <id>` for replying
+ * to existing comments, but NO command or flag that posts a full PR review. So
+ * the probe returns `not-supported` today and the skill posts via `gh api`.
+ * The probe is forward-compatible: when `agent-reviews` gains a posting flow,
+ * this parser recognizes it without a code change to the skill.
+ */
+/** Outcome of running the `agent-reviews --help` probe command. */
+export interface HelpProbeResult {
+    /** Whether the probe command ran to completion (exit 0). */
+    ok: boolean;
+    /** Captured stdout (the help text), empty when the command errored. */
+    stdout: string;
+    /** Captured stderr, when the command errored. */
+    stderr?: string;
+}
+/**
+ * Injectable invoker that runs `agent-reviews --help` (or equivalent). The
+ * skill provides a real `npx agent-reviews --help` runner; tests pass a stub.
+ * It MUST resolve (never reject) — a failed invocation is reported via
+ * `ok: false` so the probe can map it to `unknown`.
+ */
+export type HelpProbe = () => Promise<HelpProbeResult>;
+export type PostingSupport = 'supported' | 'not-supported' | 'unknown';
+export interface CapabilityResult {
+    /**
+     * Whether `agent-reviews` exposes a review-posting flow:
+     * - `supported`: a posting flag was found (`flag` is set).
+     * - `not-supported`: the probe ran but no posting flag exists.
+     * - `unknown`: the probe could not run; caller falls back to `gh api`.
+     */
+    posting: PostingSupport;
+    /** The discovered posting flag (e.g., `--post-review`), when supported. */
+    flag?: string;
+}
+/**
+ * Per-run cache. Pass the same object across calls within a single skill run so
+ * the help command is invoked at most once. Omit it to force a fresh probe.
+ */
+export interface ProbeCache {
+    result?: CapabilityResult;
+}
+/**
+ * Probe whether `agent-reviews` supports posting a full PR review.
+ *
+ * @param probe injectable `agent-reviews --help` runner.
+ * @param cache optional per-run cache; when provided, the probe runs at most
+ *   once and subsequent calls return the cached result.
+ */
+export declare function probeAgentReviewsPosting(probe: HelpProbe, cache?: ProbeCache): Promise<CapabilityResult>;
+//# sourceMappingURL=capability-probe.d.ts.map

package/dist/review-remote/capability-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-probe.d.ts","sourceRoot":"","sources":["../../src/review-remote/capability-probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,EAAE,EAAE,OAAO,CAAC;IACZ,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,eAAe,CAAC,CAAC;AAEvD,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,eAAe,GAAG,SAAS,CAAC;AAEvE,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,OAAO,EAAE,cAAc,CAAC;IACxB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AA4CD;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,SAAS,EAChB,KAAK,CAAC,EAAE,UAAU,GACjB,OAAO,CAAC,gBAAgB,CAAC,CA2B3B"}

package/dist/review-remote/capability-probe.js

@@ -0,0 +1,87 @@
+/**
+ * Capability probe for the optional `agent-reviews` posting flow (see design.md
+ * → Error Handling → Capability probe).
+ *
+ * The provide-remote skills prefer `agent-reviews` for tooling symmetry IF it
+ * exposes a "post / submit a full PR review" flow. The probe runs a
+ * non-mutating `agent-reviews --help` once, parses the help text for such a
+ * flag, and caches the result for the run. `gh api` is always the safe
+ * fallback — the probe never fails the skill.
+ *
+ * Empirical current-state finding (probed 2026-05-29, `agent-reviews@1.0.2`):
+ * the CLI exposes list/detail/watch commands plus `--reply <id>` for replying
+ * to existing comments, but NO command or flag that posts a full PR review. So
+ * the probe returns `not-supported` today and the skill posts via `gh api`.
+ * The probe is forward-compatible: when `agent-reviews` gains a posting flow,
+ * this parser recognizes it without a code change to the skill.
+ */
+/**
+ * Candidate flag tokens that, if present in the help text, indicate a
+ * full-review posting flow. Reply-to-comment flags (`--reply`) are deliberately
+ * excluded — replying to an existing comment is not posting a review.
+ *
+ * The intent-specific tokens (`--post-review`, `--submit-review`) come first;
+ * the generic `--review`/`--post` are kept as broad fallbacks. The generic
+ * tokens carry a small forward-compat false-positive risk: a future
+ * `agent-reviews` could add `--review` with an unrelated meaning (e.g.
+ * "show a review"), which the probe would report as `supported`. That risk is
+ * accepted here because `gh api` remains the safe posting path even when the
+ * probe mis-detects an `agent-reviews` posting flow — a false positive degrades
+ * to the same fallback as `unknown`, it never drops or corrupts a review.
+ */
+const POSTING_FLAG_CANDIDATES = [
+    '--post-review',
+    '--submit-review',
+    '--review',
+    '--post',
+];
+/** Extract the first posting flag present in the help text, or `undefined`. */
+function findPostingFlag(helpText) {
+    for (const flag of POSTING_FLAG_CANDIDATES) {
+        // Word-boundary-ish match: the flag followed by whitespace, `=`, or EOL, so
+        // `--post` does not spuriously match `--post-review` (and vice versa) and a
+        // substring of an unrelated token never matches.
+        const pattern = new RegExp(`(?:^|\\s)${escapeRegExp(flag)}(?=$|[\\s=])`, 'm');
+        if (pattern.test(helpText)) {
+            return flag;
+        }
+    }
+    return undefined;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Probe whether `agent-reviews` supports posting a full PR review.
+ *
+ * @param probe injectable `agent-reviews --help` runner.
+ * @param cache optional per-run cache; when provided, the probe runs at most
+ *   once and subsequent calls return the cached result.
+ */
+export async function probeAgentReviewsPosting(probe, cache) {
+    if (cache?.result !== undefined) {
+        return cache.result;
+    }
+    let outcome;
+    try {
+        outcome = await probe();
+    }
+    catch {
+        // A rejecting probe is treated the same as an errored one: unknown.
+        outcome = { ok: false, stdout: '' };
+    }
+    let result;
+    if (!outcome.ok) {
+        result = { posting: 'unknown' };
+    }
+    else {
+        const flag = findPostingFlag(outcome.stdout);
+        result = flag
+            ? { posting: 'supported', flag }
+            : { posting: 'not-supported' };
+    }
+    if (cache) {
+        cache.result = result;
+    }
+    return result;
+}

package/dist/review-remote/line-mapper.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Inline-comment line-mapping validator (see design.md → Error Handling →
+ * Inline-comment line mapping).
+ *
+ * GitHub's `POST /repos/:owner/:repo/pulls/:N/reviews` rejects inline comments
+ * at file:line positions not present in the PR diff. Before adding a finding to
+ * the `comments[]` payload, the caller classifies it against the parsed hunk
+ * ranges. Out-of-diff findings are NOT silently dropped or shifted — the caller
+ * downgrades them to a top-level "Findings outside the PR diff" subsection.
+ *
+ * Two parsers feed one classifier with a single shared {@link HunkRange} shape:
+ *  - {@link parsePullFilesPatch} for the per-file `patch` field of
+ *    `gh api /repos/.../pulls/<N>/files` (rich-context mode).
+ *  - {@link parseUnifiedDiff} for `gh pr diff <N>` (diff-only fallback mode).
+ */
+/** A single diff hunk's old- and new-side ranges. Shared by both parsers. */
+export interface HunkRange {
+    /** 1-based start line on the old (LEFT) side. */
+    oldStart: number;
+    /** Line count on the old side. */
+    oldCount: number;
+    /** 1-based start line on the new (RIGHT) side. */
+    newStart: number;
+    /** Line count on the new side. */
+    newCount: number;
+    /** Pre-rename path, when the owning file was renamed. */
+    previousFilename?: string;
+}
+/** A finding location to classify against a file's hunk ranges. */
+export interface FindingLocation {
+    file: string;
+    line: number;
+    /** Set when the finding is explicitly about removed code (LEFT side). */
+    removed?: boolean;
+}
+export interface InDiffClassification {
+    status: 'in-diff';
+    side: 'RIGHT' | 'LEFT';
+    line: number;
+}
+export interface OutOfDiffClassification {
+    status: 'out-of-diff';
+    /** Original file reference, carried through for the downgrade subsection. */
+    file: string;
+    /** Original line reference, carried through for the downgrade subsection. */
+    line: number;
+}
+export type FindingClassification = InDiffClassification | OutOfDiffClassification;
+/**
+ * Parse the `patch` field of a single `gh api .../pulls/<N>/files` entry into
+ * its hunk ranges. Returns `[]` for an empty patch (e.g., a binary file, whose
+ * entry has no `patch`).
+ *
+ * Caller contract for renamed files: a `gh api .../files` entry carries the
+ * pre-rename path in a sibling `previous_filename` field, NOT in `patch`. This
+ * parser only sees `patch`, so it cannot populate `HunkRange.previousFilename`
+ * in rich-context (gh api) mode. When a finding is reported against the
+ * pre-rename path, the caller must remap it to the entry's post-rename
+ * `filename` (using the JSON `previous_filename`) before calling
+ * `classifyFinding` — otherwise the finding is treated as out-of-diff. (The
+ * `gh pr diff` path handles this internally: `parseUnifiedDiff` records
+ * `previousFilename` from the `rename from` header.)
+ */
+export declare function parsePullFilesPatch(patch: string): HunkRange[];
+/**
+ * Parse a full `gh pr diff <N>` unified diff into a map of post-image file path
+ * → hunk ranges. Renamed files are keyed under their post-rename path with
+ * `previousFilename` recorded; binary files map to an empty array.
+ */
+export declare function parseUnifiedDiff(diff: string): Record<string, HunkRange[]>;
+/**
+ * Classify a finding against a file's hunk ranges.
+ *
+ * A line inside any hunk's new-side range is `in-diff` on the `RIGHT` side
+ * (additions/context); when the finding is explicitly about removed code it is
+ * mapped to the `LEFT` side instead. A line outside every hunk — or a file with
+ * no ranges (binary) — is `out-of-diff`, carrying the original `file:line` so
+ * the caller can downgrade it without mutating the source finding.
+ */
+export declare function classifyFinding(finding: FindingLocation, ranges: HunkRange[]): FindingClassification;
+//# sourceMappingURL=line-mapper.d.ts.map

package/dist/review-remote/line-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"line-mapper.d.ts","sourceRoot":"","sources":["../../src/review-remote/line-mapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,6EAA6E;AAC7E,MAAM,WAAW,SAAS;IACxB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,aAAa,CAAC;IACtB,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,qBAAqB,GAC7B,oBAAoB,GACpB,uBAAuB,CAAC;AAkB5B;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,CAY9D;AAUD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CA+E1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,SAAS,EAAE,GAClB,qBAAqB,CAevB"}

package/dist/review-remote/line-mapper.js

@@ -0,0 +1,165 @@
+/**
+ * Inline-comment line-mapping validator (see design.md → Error Handling →
+ * Inline-comment line mapping).
+ *
+ * GitHub's `POST /repos/:owner/:repo/pulls/:N/reviews` rejects inline comments
+ * at file:line positions not present in the PR diff. Before adding a finding to
+ * the `comments[]` payload, the caller classifies it against the parsed hunk
+ * ranges. Out-of-diff findings are NOT silently dropped or shifted — the caller
+ * downgrades them to a top-level "Findings outside the PR diff" subsection.
+ *
+ * Two parsers feed one classifier with a single shared {@link HunkRange} shape:
+ *  - {@link parsePullFilesPatch} for the per-file `patch` field of
+ *    `gh api /repos/.../pulls/<N>/files` (rich-context mode).
+ *  - {@link parseUnifiedDiff} for `gh pr diff <N>` (diff-only fallback mode).
+ */
+/** Matches a unified-diff hunk header: `@@ -a,b +c,d @@`. */
+const HUNK_HEADER_PATTERN = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
+function parseHunkHeader(line) {
+    const match = line.match(HUNK_HEADER_PATTERN);
+    if (!match) {
+        return null;
+    }
+    const oldStart = Number(match[1]);
+    // A missing count means 1 per unified-diff convention.
+    const oldCount = match[2] === undefined ? 1 : Number(match[2]);
+    const newStart = Number(match[3]);
+    const newCount = match[4] === undefined ? 1 : Number(match[4]);
+    return { oldStart, oldCount, newStart, newCount };
+}
+/**
+ * Parse the `patch` field of a single `gh api .../pulls/<N>/files` entry into
+ * its hunk ranges. Returns `[]` for an empty patch (e.g., a binary file, whose
+ * entry has no `patch`).
+ *
+ * Caller contract for renamed files: a `gh api .../files` entry carries the
+ * pre-rename path in a sibling `previous_filename` field, NOT in `patch`. This
+ * parser only sees `patch`, so it cannot populate `HunkRange.previousFilename`
+ * in rich-context (gh api) mode. When a finding is reported against the
+ * pre-rename path, the caller must remap it to the entry's post-rename
+ * `filename` (using the JSON `previous_filename`) before calling
+ * `classifyFinding` — otherwise the finding is treated as out-of-diff. (The
+ * `gh pr diff` path handles this internally: `parseUnifiedDiff` records
+ * `previousFilename` from the `rename from` header.)
+ */
+export function parsePullFilesPatch(patch) {
+    if (!patch) {
+        return [];
+    }
+    const ranges = [];
+    for (const line of patch.split('\n')) {
+        const hunk = parseHunkHeader(line);
+        if (hunk) {
+            ranges.push(hunk);
+        }
+    }
+    return ranges;
+}
+/** Strip a leading `a/` or `b/` diff prefix from a path token. */
+function stripDiffPrefix(path) {
+    if (path.startsWith('a/') || path.startsWith('b/')) {
+        return path.slice(2);
+    }
+    return path;
+}
+/**
+ * Parse a full `gh pr diff <N>` unified diff into a map of post-image file path
+ * → hunk ranges. Renamed files are keyed under their post-rename path with
+ * `previousFilename` recorded; binary files map to an empty array.
+ */
+export function parseUnifiedDiff(diff) {
+    const byFile = {};
+    if (!diff) {
+        return byFile;
+    }
+    const lines = diff.split('\n');
+    let currentFile = null;
+    let previousFilename;
+    let renameFrom;
+    const ensureFile = (path) => {
+        if (!byFile[path]) {
+            byFile[path] = [];
+        }
+        return byFile[path];
+    };
+    for (const line of lines) {
+        if (line.startsWith('diff --git ')) {
+            // `diff --git a/<old> b/<new>` — default the file to the new path.
+            const parts = line.slice('diff --git '.length).trim().split(' ');
+            const newPath = parts.length >= 2 ? stripDiffPrefix(parts[parts.length - 1]) : null;
+            currentFile = newPath;
+            previousFilename = undefined;
+            renameFrom = undefined;
+            if (currentFile) {
+                ensureFile(currentFile);
+            }
+            continue;
+        }
+        if (line.startsWith('rename from ')) {
+            renameFrom = line.slice('rename from '.length).trim();
+            continue;
+        }
+        if (line.startsWith('rename to ')) {
+            const renameTo = line.slice('rename to '.length).trim();
+            // Re-key under the post-rename path and drop the placeholder key.
+            if (currentFile && currentFile !== renameTo) {
+                delete byFile[currentFile];
+            }
+            currentFile = renameTo;
+            previousFilename = renameFrom;
+            ensureFile(currentFile);
+            continue;
+        }
+        if (line.startsWith('+++ ')) {
+            const token = line.slice('+++ '.length).trim();
+            if (token !== '/dev/null') {
+                const path = stripDiffPrefix(token);
+                if (path && path !== currentFile) {
+                    if (currentFile) {
+                        delete byFile[currentFile];
+                    }
+                    currentFile = path;
+                    ensureFile(currentFile);
+                }
+            }
+            continue;
+        }
+        if (line.startsWith('Binary files ')) {
+            // Binary file: no hunks, keep the (already-ensured) empty array.
+            continue;
+        }
+        const hunk = parseHunkHeader(line);
+        if (hunk && currentFile) {
+            if (previousFilename) {
+                hunk.previousFilename = previousFilename;
+            }
+            ensureFile(currentFile).push(hunk);
+        }
+    }
+    return byFile;
+}
+/**
+ * Classify a finding against a file's hunk ranges.
+ *
+ * A line inside any hunk's new-side range is `in-diff` on the `RIGHT` side
+ * (additions/context); when the finding is explicitly about removed code it is
+ * mapped to the `LEFT` side instead. A line outside every hunk — or a file with
+ * no ranges (binary) — is `out-of-diff`, carrying the original `file:line` so
+ * the caller can downgrade it without mutating the source finding.
+ */
+export function classifyFinding(finding, ranges) {
+    for (const range of ranges) {
+        if (finding.removed) {
+            const oldEnd = range.oldStart + range.oldCount - 1;
+            if (finding.line >= range.oldStart && finding.line <= oldEnd) {
+                return { status: 'in-diff', side: 'LEFT', line: finding.line };
+            }
+            continue;
+        }
+        const newEnd = range.newStart + range.newCount - 1;
+        if (finding.line >= range.newStart && finding.line <= newEnd) {
+            return { status: 'in-diff', side: 'RIGHT', line: finding.line };
+        }
+    }
+    return { status: 'out-of-diff', file: finding.file, line: finding.line };
+}

package/dist/review-remote/marker-parser.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Parser for the posted-review-body marker block.
+ *
+ * The marker block is an HTML comment opened by `<!-- oat-review-metadata`
+ * carrying simple single-line YAML-ish scalars (see design.md → Data Models →
+ * Posted-review-body). GitHub renders the comment as nothing but preserves it
+ * across round-trips, so it is the durable routing channel between the
+ * provide-remote skills (writers) and the receive-remote skills (readers).
+ *
+ * This is intentionally a tolerant single-line scalar parser — NOT a full YAML
+ * parser. The schema is flat (no nested structures), so a line-oriented reader
+ * is sufficient and avoids a dependency the schema does not need.
+ */
+/** Token that opens the marker comment block. */
+export declare const MARKER_BLOCK_OPEN = "oat-review-metadata";
+export type ReviewInvocation = 'manual' | 'auto';
+export interface MarkerBlock {
+    /** Always `true` for an OAT provide-remote review; the discriminator. */
+    oat_provide_remote: true;
+    /** Full 40-char hex SHA of the reviewed PR HEAD. */
+    oat_review_head_sha: string;
+    /** Scope token (`pNN`, `final`, …) or the `ad-hoc` sentinel. */
+    oat_review_scope: string;
+    /**
+     * Project path — present only on the project rail. Key existence (not a
+     * `null` value) discriminates project rail from ad-hoc rail.
+     */
+    oat_project?: string;
+    /** How the review was invoked. Defaults to `manual` when omitted. */
+    oat_review_invocation: ReviewInvocation;
+    /** Forward-compat bag for unknown marker keys. Omitted when none seen. */
+    extras?: Record<string, string>;
+}
+/**
+ * Parse the first OAT marker block out of a posted-review body.
+ *
+ * Returns `null` when the body is not an OAT provide-remote review — either
+ * because no marker block exists, because `oat_provide_remote` is not `true`,
+ * or because the recorded head SHA is not a valid 40-char hex SHA (a value the
+ * caller could not safely narrow against; returning null lets the caller fall
+ * back to full-scope review).
+ */
+export declare function parseMarkerBlock(body: string): MarkerBlock | null;
+//# sourceMappingURL=marker-parser.d.ts.map

package/dist/review-remote/marker-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker-parser.d.ts","sourceRoot":"","sources":["../../src/review-remote/marker-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,iDAAiD;AACjD,eAAO,MAAM,iBAAiB,wBAAwB,CAAC;AAavD,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,kBAAkB,EAAE,IAAI,CAAC;IACzB,oDAAoD;IACpD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,qBAAqB,EAAE,gBAAgB,CAAC;IACxC,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAUD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAqEjE"}

package/dist/review-remote/marker-parser.js

@@ -0,0 +1,97 @@
+/**
+ * Parser for the posted-review-body marker block.
+ *
+ * The marker block is an HTML comment opened by `<!-- oat-review-metadata`
+ * carrying simple single-line YAML-ish scalars (see design.md → Data Models →
+ * Posted-review-body). GitHub renders the comment as nothing but preserves it
+ * across round-trips, so it is the durable routing channel between the
+ * provide-remote skills (writers) and the receive-remote skills (readers).
+ *
+ * This is intentionally a tolerant single-line scalar parser — NOT a full YAML
+ * parser. The schema is flat (no nested structures), so a line-oriented reader
+ * is sufficient and avoids a dependency the schema does not need.
+ */
+/** Token that opens the marker comment block. */
+export const MARKER_BLOCK_OPEN = 'oat-review-metadata';
+/**
+ * Matches the first `<!-- oat-review-metadata ... -->` HTML comment block.
+ * Non-greedy body capture so a later comment in prose never wins.
+ */
+const MARKER_BLOCK_PATTERN = new RegExp(`<!--\\s*${MARKER_BLOCK_OPEN}\\s*([\\s\\S]*?)-->`);
+/** A full 40-character lowercase/uppercase hex SHA. */
+const FULL_SHA_PATTERN = /^[0-9a-fA-F]{40}$/;
+const KNOWN_KEYS = new Set([
+    'oat_provide_remote',
+    'oat_review_head_sha',
+    'oat_review_scope',
+    'oat_project',
+    'oat_review_invocation',
+]);
+/**
+ * Parse the first OAT marker block out of a posted-review body.
+ *
+ * Returns `null` when the body is not an OAT provide-remote review — either
+ * because no marker block exists, because `oat_provide_remote` is not `true`,
+ * or because the recorded head SHA is not a valid 40-char hex SHA (a value the
+ * caller could not safely narrow against; returning null lets the caller fall
+ * back to full-scope review).
+ */
+export function parseMarkerBlock(body) {
+    if (!body) {
+        return null;
+    }
+    const match = body.match(MARKER_BLOCK_PATTERN);
+    if (!match || match[1] === undefined) {
+        return null;
+    }
+    const raw = {};
+    for (const line of match[1].split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '') {
+            continue;
+        }
+        const sep = trimmed.indexOf(':');
+        if (sep === -1) {
+            continue;
+        }
+        const key = trimmed.slice(0, sep).trim().toLowerCase();
+        const value = trimmed.slice(sep + 1).trim();
+        if (key === '') {
+            continue;
+        }
+        raw[key] = value;
+    }
+    if (raw['oat_provide_remote'] !== 'true') {
+        return null;
+    }
+    const headSha = raw['oat_review_head_sha'];
+    if (!headSha || !FULL_SHA_PATTERN.test(headSha)) {
+        return null;
+    }
+    const scope = raw['oat_review_scope'];
+    if (!scope) {
+        return null;
+    }
+    const invocationRaw = raw['oat_review_invocation'];
+    const oat_review_invocation = invocationRaw === 'auto' ? 'auto' : 'manual';
+    const block = {
+        oat_provide_remote: true,
+        oat_review_head_sha: headSha,
+        oat_review_scope: scope,
+        oat_review_invocation,
+    };
+    // Project key existence (not a null value) discriminates the rail.
+    if ('oat_project' in raw && raw['oat_project'] !== '') {
+        block.oat_project = raw['oat_project'];
+    }
+    const extras = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!KNOWN_KEYS.has(key)) {
+            extras[key] = value;
+        }
+    }
+    if (Object.keys(extras).length > 0) {
+        block.extras = extras;
+    }
+    return block;
+}