@open-agent-toolkit/cli 0.1.13 → 0.1.15

package/dist/commands/project/new/scaffold.js

@@ -1,3 +1,4 @@
+import { execFileSync } from 'node:child_process';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { resolveProjectsRoot } from '../../shared/oat-paths.js';
@@ -105,6 +106,62 @@ function applyTemplateReplacements(template, projectName, today, nowUtc, mode) {
 async function defaultRefreshDashboard(repoRoot) {
     await generateStateDashboard({ repoRoot });
 }
+/**
+ * Scoped, fail-safe commit of just the files this run created.
+ *
+ * Stages and commits only the pathspecs derived from `createdFiles` (under
+ * `projectPath`) so unrelated working-tree changes — including pre-existing
+ * dirty edits inside the same project directory on a re-run, and the
+ * `.oat/state.md` dashboard outside it — are never swept in. The returned
+ * status distinguishes a clean commit from each skip reason and from a genuine
+ * git failure; on failure the captured git stderr is surfaced via `error`. This
+ * never throws: any git error is classified as `failed`, not propagated.
+ */
+function commitScaffold(cwd, projectPath, projectName, createdFiles) {
+    const run = (args) => execFileSync('git', args, {
+        cwd,
+        encoding: 'utf8',
+        // Capture stderr instead of inheriting it so deliberate skip/failure
+        // probes (e.g. tests) do not leak raw `git fatal:` lines to the terminal.
+        stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+    try {
+        run(['rev-parse', '--is-inside-work-tree']);
+    }
+    catch {
+        return { status: 'skipped_no_worktree', committed: false };
+    }
+    // Only commit files this run created. Nothing created => nothing to commit,
+    // which guarantees a re-run never touches unrelated working-tree edits.
+    if (createdFiles.length === 0) {
+        return { status: 'skipped_nothing', committed: false };
+    }
+    const pathspecs = createdFiles.map((file) => join(projectPath, file));
+    try {
+        run(['add', '--', ...pathspecs]);
+        const staged = run(['diff', '--cached', '--name-only', '--', ...pathspecs]);
+        if (staged.length === 0) {
+            return { status: 'skipped_nothing', committed: false };
+        }
+        run([
+            'commit',
+            '-m',
+            `chore(oat): scaffold ${projectName}`,
+            '--',
+            ...pathspecs,
+        ]);
+        const commitSha = run(['rev-parse', 'HEAD']);
+        return { status: 'committed', committed: true, commitSha };
+    }
+    catch (error) {
+        const stderr = error && typeof error === 'object' && 'stderr' in error
+            ? error.stderr
+            : undefined;
+        const message = (stderr != null ? stderr.toString().trim() : '') ||
+            (error instanceof Error ? error.message : String(error));
+        return { status: 'failed', committed: false, error: message };
+    }
+}
 async function scaffoldModeTemplates(repoRoot, projectPath, projectName, mode, today, nowUtc) {
     const templatesDir = join(repoRoot, '.oat', 'templates');
     const createdFiles = [];
@@ -169,6 +226,19 @@ export async function scaffoldProject(options) {
             console.error(`Warning: dashboard refresh failed: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    let committed = false;
+    let commitSha;
+    let commitStatus = 'skipped_disabled';
+    let commitError;
+    if (options.commit) {
+        // `projectPath` is relative to `repoRoot`, so git must run there for the
+        // pathspecs to resolve to the scaffolded files.
+        const commitResult = commitScaffold(options.repoRoot, projectPath, options.projectName, createdFiles);
+        committed = commitResult.committed;
+        commitSha = commitResult.commitSha;
+        commitStatus = commitResult.status;
+        commitError = commitResult.error;
+    }
     return {
         mode,
         projectsRoot,
@@ -177,5 +247,9 @@ export async function scaffoldProject(options) {
         skippedFiles,
         activePointerUpdated: setActive,
         dashboardRefreshed,
+        committed,
+        commitSha,
+        commitStatus,
+        commitError,
     };
 }

package/dist/review-remote/body-builder.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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 { type ReviewInvocation } from './marker-parser.js';
+export type ReviewVerdict = 'REQUEST_CHANGES' | 'COMMENT';
+export type FindingSeverity = 'critical' | 'important' | 'medium' | 'minor';
+/** Minimal finding shape the builder needs — only severity is required. */
+export interface BuilderFinding {
+    severity: FindingSeverity;
+}
+/**
+ * A finding whose `file:line` is NOT present in the PR diff and therefore
+ * cannot be posted as a GitHub inline comment (see design.md → Error Handling →
+ * Inline-comment line mapping). Such findings must NOT be dropped — they are
+ * downgraded into the top-level body via a "Findings outside the PR diff"
+ * subsection carrying the original `file:line` reference and finding body.
+ *
+ * Field names mirror the `StructuredFindings` finding shape (design.md → Data
+ * Models → StructuredFindings) so callers can pass entries through unchanged;
+ * `line` is `number | null` because a reviewer-level finding may be file-scoped
+ * with no specific line.
+ */
+export interface OutOfDiffFinding {
+    /** Repo-relative path the original finding referenced. */
+    file: string;
+    /** 1-based line the original finding referenced, or `null` if file-scoped. */
+    line: number | null;
+    severity: FindingSeverity;
+    /** Optional short title carried from the structured finding. */
+    title?: string;
+    /** Finding description / rationale — preserved verbatim, never dropped. */
+    body: string;
+}
+export interface BuildInput {
+    /** Full 40-char hex SHA of the reviewed PR HEAD. */
+    headSha: string;
+    /** Scope token (`pNN`, `final`, …) or the `ad-hoc` sentinel. */
+    scope: string;
+    /** Project path — set only on the project rail; omitted on ad-hoc. */
+    project?: string;
+    /** How the review was invoked. */
+    invocation: ReviewInvocation;
+    /** 2-3 sentence human-readable summary. */
+    summary: string;
+    findings: BuilderFinding[];
+    /**
+     * Findings whose `file:line` is not in the PR diff, downgraded into the body
+     * instead of posted inline. Omitted/empty renders no subsection (the body is
+     * byte-identical to a build without the field).
+     *
+     * Count contract: these findings MUST also appear in {@link BuildInput.findings}
+     * so the severity counts stay complete. This field only drives body rendering
+     * — the builder never re-derives severity counts from it.
+     */
+    outOfDiffFindings?: OutOfDiffFinding[];
+    /** Commands the user can run to verify fixes; omitted when absent/empty. */
+    verificationCommands?: string[];
+}
+/**
+ * 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 declare function mapVerdict(findings: BuilderFinding[]): ReviewVerdict;
+/**
+ * Build the posted-review body and compute its verdict.
+ */
+export declare function buildReviewBody(input: BuildInput): {
+    body: string;
+    verdict: ReviewVerdict;
+};
+//# sourceMappingURL=body-builder.d.ts.map

package/dist/review-remote/body-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"body-builder.d.ts","sourceRoot":"","sources":["../../src/review-remote/body-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAE3E,MAAM,MAAM,aAAa,GAAG,iBAAiB,GAAG,SAAS,CAAC;AAE1D,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE5E,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,eAAe,CAAC;CAC3B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,eAAe,CAAC;IAC1B,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,UAAU,EAAE,gBAAgB,CAAC;IAC7B,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACvC,4EAA4E;IAC5E,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,aAAa,CAKpE;AAkED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,aAAa,CAAC;CACxB,CAkCA"}

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"}