@verevoir/review 0.2.0 → 0.3.0

package/dist/context-files.js

@@ -0,0 +1,174 @@
+// Whole-file context for a diff: for each file the diff touches that still
+// exists at the change's head, its full post-change text, so a lens can see
+// what sits outside the hunks (e.g. a workflow's `on:` block 30 lines above
+// the changed step).
+//
+// SAFETY: paths come from the diff's own `+++` headers, so they are
+// untrusted. A path is refused (never read) when it is absolute, contains a
+// `..` segment or a NUL; and the resolved real path of every candidate must
+// stay inside the real path of the context root, so a symlink pointing out
+// of the tree is refused too. Refusals are listed in the section, not thrown.
+//
+// PURE-ish: all disk access goes through the injected `ContextFs`, so tests
+// use fakes.
+/** Files larger than this (bytes) are skipped, with the reason named. */
+export const MAX_CONTEXT_FILE_BYTES = 16 * 1024;
+/** The one line used when there is no context root (diff read from stdin). */
+export const NO_FILE_CONTEXT_NOTE = 'No file context: the diff was read from stdin and no --context-root was given, so only the ' +
+    'diff hunks are shown.';
+function unquote(raw) {
+    const tab = raw.indexOf('\t');
+    const trimmed = (tab === -1 ? raw : raw.slice(0, tab)).trim();
+    if (!trimmed.startsWith('"'))
+        return trimmed;
+    try {
+        const parsed = JSON.parse(trimmed);
+        return typeof parsed === 'string' ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function stripPrefix(path, prefix) {
+    return path.startsWith(prefix) ? path.slice(prefix.length) : path;
+}
+/**
+ * The files a unified diff touches, from its `--- ` / `+++ ` header pairs
+ * (a `+++` only counts when the line before it is a `--- `). A path git had
+ * to quote with escapes is reported with `unreadable: true` via an empty
+ * path so the caller can say it was skipped.
+ */
+export function diffPaths(diff) {
+    const lines = diff.split(/\r?\n/);
+    const seen = new Set();
+    const out = [];
+    for (let i = 0; i + 1 < lines.length; i++) {
+        const oldLine = lines[i] ?? '';
+        const newLine = lines[i + 1] ?? '';
+        if (!oldLine.startsWith('--- ') || !newLine.startsWith('+++ '))
+            continue;
+        const next = unquote(newLine.slice(4));
+        const prev = unquote(oldLine.slice(4));
+        let entry;
+        if (next === undefined || prev === undefined) {
+            entry = { path: '', deleted: false };
+        }
+        else if (next === '/dev/null') {
+            entry = { path: stripPrefix(prev, 'a/'), deleted: true };
+        }
+        else {
+            entry = { path: stripPrefix(next, 'b/'), deleted: false };
+        }
+        const key = `${entry.deleted ? 'D' : 'M'}:${entry.path}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(entry);
+    }
+    return out;
+}
+/** Why a diff-supplied path must not be read, or undefined if it is acceptable. */
+export function unsafePathReason(path) {
+    if (path === '')
+        return 'path could not be read from the diff header';
+    if (path.includes('\0'))
+        return 'path contains a NUL byte';
+    if (path.startsWith('/') || path.startsWith('\\') || /^[A-Za-z]:[\\/]/.test(path)) {
+        return 'absolute path';
+    }
+    if (path.split(/[\\/]/).includes('..'))
+        return 'path contains a ".." segment';
+    return undefined;
+}
+function isAbsent(cause) {
+    const code = cause.code;
+    return code === 'ENOENT' || code === 'ENOTDIR';
+}
+function describe(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+function fenceFor(text) {
+    let longest = 2;
+    for (const run of text.match(/`+/g) ?? [])
+        longest = Math.max(longest, run.length);
+    return '`'.repeat(longest + 1);
+}
+/**
+ * Build the body of the "Changed files in full" section for `diff`, reading
+ * from `root`. Throws only when the root itself cannot be resolved; every
+ * per-file problem becomes a "skipped" line naming the reason.
+ */
+export async function buildFileContext(diff, root, fs) {
+    let rootReal;
+    try {
+        rootReal = await fs.realpath(root);
+    }
+    catch (cause) {
+        throw new Error(`--context-root ${root} could not be resolved: ${describe(cause)}`);
+    }
+    const prefix = rootReal.endsWith('/') ? rootReal : `${rootReal}/`;
+    const shown = [];
+    const skipped = [];
+    for (const entry of diffPaths(diff)) {
+        const label = entry.path === '' ? '(unreadable path)' : entry.path;
+        if (entry.deleted) {
+            skipped.push(`- \`${label}\`: deleted by this change`);
+            continue;
+        }
+        const unsafe = unsafePathReason(entry.path);
+        if (unsafe !== undefined) {
+            skipped.push(`- \`${label}\`: refused (${unsafe})`);
+            continue;
+        }
+        let real;
+        try {
+            real = await fs.realpath(`${prefix}${entry.path}`);
+        }
+        catch (cause) {
+            skipped.push(isAbsent(cause)
+                ? `- \`${label}\`: not present at the context root`
+                : `- \`${label}\`: could not be resolved (${describe(cause)})`);
+            continue;
+        }
+        if (real !== rootReal && !real.startsWith(prefix)) {
+            skipped.push(`- \`${label}\`: refused (resolves outside the context root)`);
+            continue;
+        }
+        try {
+            const stat = await fs.statFile(real);
+            if (!stat.isFile) {
+                skipped.push(`- \`${label}\`: not a regular file`);
+                continue;
+            }
+            if (stat.size > MAX_CONTEXT_FILE_BYTES) {
+                skipped.push(`- \`${label}\`: too large (${String(stat.size)} bytes; limit ` +
+                    `${String(MAX_CONTEXT_FILE_BYTES)})`);
+                continue;
+            }
+            const text = await fs.readFile(real);
+            if (text.includes('\0')) {
+                skipped.push(`- \`${label}\`: binary file`);
+                continue;
+            }
+            const fence = fenceFor(text);
+            shown.push(`### ${entry.path}\n\n${fence}\n${text.replace(/\n$/, '')}\n${fence}`);
+        }
+        catch (cause) {
+            skipped.push(isAbsent(cause)
+                ? `- \`${label}\`: not present at the context root`
+                : `- \`${label}\`: could not be read (${describe(cause)})`);
+        }
+    }
+    const parts = [];
+    if (shown.length === 0 && skipped.length === 0) {
+        return 'No changed files could be identified from the diff headers, so only the hunks are shown.';
+    }
+    parts.push('Each file below is its full text as it stands after this change, so context outside the ' +
+        'diff hunks is visible. Lines the diff does not touch are unchanged context.');
+    if (shown.length > 0)
+        parts.push(shown.join('\n\n'));
+    if (skipped.length > 0) {
+        parts.push(`Not shown in full:\n\n${skipped.join('\n')}`);
+    }
+    return parts.join('\n\n');
+}

package/dist/context-types.d.ts

@@ -0,0 +1,28 @@
+/** One of the diff's own touched symbols, with evidence about it drawn
+ * from the rest of the tree. `definition` is absent only when the
+ * assembler chose not to include a body (reserved for a future budget
+ * mode that keeps the reference but drops the text); PR 2 always
+ * populates it when a symbol is included at all. */
+export interface SubjectContextEntry {
+    readonly symbol: string;
+    readonly file: string;
+    readonly definition?: string;
+    /** Names of symbols, anywhere in the warmed tree, with a call edge TO
+     * this symbol. Name-based, approximate -- @verevoir/context's own
+     * documented limit (no type resolution). */
+    readonly callers: readonly string[];
+    /** Names of symbols this symbol's own body calls. Same name-based
+     * approximation as `callers`. */
+    readonly callees: readonly string[];
+}
+/** A symbol or file the assembler could not resolve, and why -- never a
+ * silent empty result. Mirrors the "disclosed, never silently absent"
+ * discipline v5's own symbol-table.ts documented for its empty cases. */
+export interface SubjectContextOmission {
+    readonly symbol: string;
+    readonly reason: string;
+}
+export interface SubjectContext {
+    readonly entries: readonly SubjectContextEntry[];
+    readonly omitted: readonly SubjectContextOmission[];
+}

package/dist/context-types.js

@@ -0,0 +1,5 @@
+// The shape of CONTEXT about a diff -- evidence drawn read-only from the
+// codebase at the head ref, never a second subject. Kept in its own file
+// (no logic here) so both the assembler (context-assembler.ts) and the
+// renderer (subject-context-render.ts) depend on one definition.
+export {};

package/dist/dedup.d.ts

@@ -0,0 +1,40 @@
+import type { Reviewer } from './panel.js';
+import type { Prompt } from './prompt.js';
+import type { DedupGroupView } from './report.js';
+import type { Finding } from './verdict.js';
+/** The lens id the extra call is made under. */
+export declare const DEDUP_LENS = "dedup";
+export interface NumberedFinding {
+    /** `lens:index`, the index counting that lens's findings from 0 in report order. */
+    readonly id: string;
+    readonly finding: Finding;
+}
+export declare function numberFindings(findings: readonly Finding[]): NumberedFinding[];
+export declare function buildDedupPrompt(items: readonly NumberedFinding[]): Prompt;
+export type GroupsResult = {
+    readonly ok: true;
+    readonly groups: readonly (readonly string[])[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** Parse and validate a reply: every one of `ids` in exactly one group. */
+export declare function parseGroups(reply: string, ids: readonly string[]): GroupsResult;
+export type DedupResult = {
+    readonly ok: true;
+    readonly groups: readonly (readonly NumberedFinding[])[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** Ask the model to group `items`; members come back in their input order. */
+export declare function dedupFindings(items: readonly NumberedFinding[], review: Reviewer): Promise<DedupResult>;
+/**
+ * The report view of each group: the highest tier among its members, the text of its highest-tier member (the first blocking one, else the first),
+ * and who raised it, naming the practices of each lens that the members' text mentions (by id
+ * or title).
+ */
+export declare function toGroupViews(groups: readonly (readonly NumberedFinding[])[], practiceNames?: Readonly<Record<string, readonly {
+    id: string;
+    title: string;
+}[]>>): DedupGroupView[];

package/dist/dedup.js

@@ -0,0 +1,151 @@
+// De-duplicates findings across lenses with ONE extra model call through the same Reviewer the
+// panel used. The panel is not restructured: the Reviewer takes (lensId, prompt) and a transport
+// uses the lens id only to key its resolved-model callback, so a non-lens call under the id
+// `dedup` is an ordinary call that onCall records like any other (so its usage reaches the
+// footer).
+//
+// The model returns groups of finding ids; the reply is validated deterministically (every
+// input id in exactly one group, no unknown ids, no empty groups). Anything else -- a thrown
+// call, unparseable text, a failed validation -- is a skip with a reason, never a guess.
+import { normaliseReviewerReply } from './panel.js';
+import { normaliseForQuote } from './tier.js';
+/** The lens id the extra call is made under. */
+export const DEDUP_LENS = 'dedup';
+/** Detail text sent per finding is cut to this many characters. */
+const DETAIL_LIMIT = 800;
+export function numberFindings(findings) {
+    const next = new Map();
+    return findings.map((finding) => {
+        const index = next.get(finding.lens) ?? 0;
+        next.set(finding.lens, index + 1);
+        return { id: `${finding.lens}:${String(index)}`, finding };
+    });
+}
+export function buildDedupPrompt(items) {
+    const list = items.map(({ id, finding }) => {
+        const detail = (finding.detail ?? '').trim();
+        const shown = detail.length > DETAIL_LIMIT ? `${detail.slice(0, DETAIL_LIMIT)}...` : detail;
+        return [
+            `### ${id} [${finding.blocking ? 'blocking' : 'smell'}]`,
+            '',
+            finding.summary,
+            ...(shown === '' ? [] : ['', shown]),
+        ].join('\n');
+    });
+    const shared = [
+        'Several reviewers each reviewed the same change and raised the findings below. Some of ' +
+            'them describe the SAME defect, restated by different reviewers or in different words.',
+        '',
+        'Group the findings that describe the same underlying defect: the same root cause in the ' +
+            'same place. Findings that only touch the same file or the same practice but are ' +
+            'different defects stay in separate groups. A finding with no duplicate is a group of ' +
+            'one. Every id below must appear in exactly one group.',
+        '',
+        '## Findings',
+        '',
+        list.join('\n\n'),
+    ].join('\n');
+    const perLens = [
+        '## Your task',
+        '',
+        'Reply with ONLY a JSON array of arrays of ids, for example ' +
+            '[["a:0","b:1"],["a:1"],["b:0"]]. No prose, no markdown fence, no verdict line.',
+    ].join('\n');
+    return { shared, perLens };
+}
+/** Parse and validate a reply: every one of `ids` in exactly one group. */
+export function parseGroups(reply, ids) {
+    const start = reply.indexOf('[');
+    const end = reply.lastIndexOf(']');
+    if (start === -1 || end <= start) {
+        return { ok: false, reason: 'the reply held no JSON array of groups' };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(reply.slice(start, end + 1));
+    }
+    catch {
+        return { ok: false, reason: 'the reply was not valid JSON' };
+    }
+    if (!Array.isArray(parsed))
+        return { ok: false, reason: 'the reply was not an array' };
+    const known = new Set(ids);
+    const seen = new Set();
+    const groups = [];
+    for (const group of parsed) {
+        if (!Array.isArray(group) || group.length === 0) {
+            return { ok: false, reason: 'a group was empty or not an array' };
+        }
+        const members = [];
+        for (const id of group) {
+            if (typeof id !== 'string' || !known.has(id)) {
+                return { ok: false, reason: `a group named an unknown id (${JSON.stringify(id)})` };
+            }
+            if (seen.has(id))
+                return { ok: false, reason: `id ${id} appeared in more than one group` };
+            seen.add(id);
+            members.push(id);
+        }
+        groups.push(members);
+    }
+    const missing = ids.filter((id) => !seen.has(id));
+    if (missing.length > 0) {
+        return { ok: false, reason: `ids missing from every group: ${missing.join(', ')}` };
+    }
+    return { ok: true, groups };
+}
+/** Ask the model to group `items`; members come back in their input order. */
+export async function dedupFindings(items, review) {
+    let text;
+    try {
+        text = normaliseReviewerReply(await review(DEDUP_LENS, buildDedupPrompt(items))).text;
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            reason: `the extra call failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+        };
+    }
+    const parsed = parseGroups(text, items.map((i) => i.id));
+    if (!parsed.ok)
+        return { ok: false, reason: `the grouping was invalid: ${parsed.reason}` };
+    const position = new Map(items.map((item, index) => [item.id, index]));
+    const byId = new Map(items.map((item) => [item.id, item]));
+    const groups = parsed.groups
+        .map((ids) => ids
+        .slice()
+        .sort((a, b) => (position.get(a) ?? 0) - (position.get(b) ?? 0))
+        .map((id) => byId.get(id)))
+        .sort((a, b) => (position.get(a[0]?.id ?? '') ?? 0) - (position.get(b[0]?.id ?? '') ?? 0));
+    return { ok: true, groups };
+}
+/**
+ * The report view of each group: the highest tier among its members, the text of its highest-tier member (the first blocking one, else the first),
+ * and who raised it, naming the practices of each lens that the members' text mentions (by id
+ * or title).
+ */
+export function toGroupViews(groups, practiceNames = {}) {
+    return groups.map((members) => {
+        const lenses = [];
+        for (const { finding } of members)
+            if (!lenses.includes(finding.lens))
+                lenses.push(finding.lens);
+        const raisedBy = lenses.map((lens) => {
+            const text = normaliseForQuote(members
+                .filter((m) => m.finding.lens === lens)
+                .map((m) => `${m.finding.summary}\n${m.finding.detail ?? ''}`)
+                .join('\n'));
+            const named = (practiceNames[lens] ?? []).filter((p) => text.includes(normaliseForQuote(p.id)) ||
+                (p.title !== '' && text.includes(normaliseForQuote(p.title))));
+            return { lens, practices: named.map((p) => p.id) };
+        });
+        // The text of the highest-tier member, so a blocking group never shows a downgraded smell.
+        const shown = (members.find((m) => m.finding.blocking) ?? members[0])
+            .finding;
+        return {
+            blocking: members.some((m) => m.finding.blocking),
+            finding: shown,
+            raisedBy,
+        };
+    });
+}

package/dist/diff-hunks.d.ts

@@ -0,0 +1,17 @@
+export interface HunkRange {
+    readonly startLine: number;
+    readonly endLine: number;
+}
+/** path -> new-side line ranges the diff's hunks actually cover, in the
+ * order they appear. A path present in the diff with every hunk a pure
+ * deletion maps to an empty array, deliberately -- "touched, but nothing
+ * to show on the new side" is a real, distinct answer from "not in this
+ * diff at all" (absent from the map entirely). */
+export declare function parseDiffHunks(diffText: string): ReadonlyMap<string, readonly HunkRange[]>;
+/** Every path the diff's `+++ b/<path>` headers name, in order of first
+ * appearance. */
+export declare function touchedFiles(diffText: string): readonly string[];
+/** True iff `[startLine, endLine]` overlaps at least one of the diff's
+ * new-side hunk ranges for `path`. A path not in the diff, or present
+ * with only pure-deletion hunks, never overlaps anything. */
+export declare function rangeTouchedByDiff(hunks: ReadonlyMap<string, readonly HunkRange[]>, path: string, startLine: number, endLine: number): boolean;

package/dist/diff-hunks.js

@@ -0,0 +1,73 @@
+// Parses unified-diff hunk headers to find which NEW-side line ranges a
+// diff actually touches, per file. This is intentionally narrow: it reads
+// `+++ b/<path>` file headers and `@@ -a,b +c,d @@` hunk headers, nothing
+// else -- no `---` old-side headers, no rename detection, no binary-diff
+// markers. It is the shared primitive this library's context assembler
+// (PR 2) uses to decide which symbols in a touched file count as
+// "touched", and PR 3's diff-anchor validator is expected to use the same
+// primitive to decide whether a finding's cited location is inside the
+// diff at all -- written once here so both consumers agree on hunk
+// semantics, rather than parsing unified-diff text twice independently
+// the way v5 duplicated `git diff --merge-base` across preflight.mjs and
+// the CI workflow (named explicitly in this library's own grounding).
+//
+// NEW-side only: a pure deletion (a hunk whose new-side count is 0)
+// contributes no range. That is a deliberate, narrow simplification for
+// this file's two current consumers -- "which symbols does this diff
+// touch" is answered well enough by the lines that still exist after the
+// change. PR 3's anchor validator may need the OLD-side range too, for a
+// finding that cites a deleted line; that is this file's own documented
+// gap, not silently assumed away.
+//
+// A file diffed only as a deletion recorded as `+++ /dev/null` never
+// appears here at all: the file-header pattern only recognises `+++
+// b/<path>`, and `/dev/null` is never a real path worth resolving symbols
+// against.
+const FILE_HEADER = /^\+\+\+ b\/(.+)$/;
+const HUNK_HEADER = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/;
+/** path -> new-side line ranges the diff's hunks actually cover, in the
+ * order they appear. A path present in the diff with every hunk a pure
+ * deletion maps to an empty array, deliberately -- "touched, but nothing
+ * to show on the new side" is a real, distinct answer from "not in this
+ * diff at all" (absent from the map entirely). */
+export function parseDiffHunks(diffText) {
+    const result = new Map();
+    let currentPath = null;
+    for (const line of diffText.split('\n')) {
+        const fileMatch = FILE_HEADER.exec(line);
+        if (fileMatch) {
+            currentPath = fileMatch[1];
+            if (!result.has(currentPath))
+                result.set(currentPath, []);
+            continue;
+        }
+        if (currentPath === null)
+            continue;
+        const hunkMatch = HUNK_HEADER.exec(line);
+        if (hunkMatch) {
+            const start = Number(hunkMatch[1]);
+            const count = hunkMatch[2] === undefined ? 1 : Number(hunkMatch[2]);
+            if (count > 0) {
+                result.get(currentPath).push({ startLine: start, endLine: start + count - 1 });
+            }
+        }
+    }
+    return result;
+}
+/** Every path the diff's `+++ b/<path>` headers name, in order of first
+ * appearance. */
+export function touchedFiles(diffText) {
+    return [...parseDiffHunks(diffText).keys()];
+}
+function overlaps(a, startLine, endLine) {
+    return a.startLine <= endLine && startLine <= a.endLine;
+}
+/** True iff `[startLine, endLine]` overlaps at least one of the diff's
+ * new-side hunk ranges for `path`. A path not in the diff, or present
+ * with only pure-deletion hunks, never overlaps anything. */
+export function rangeTouchedByDiff(hunks, path, startLine, endLine) {
+    const ranges = hunks.get(path);
+    if (!ranges)
+        return false;
+    return ranges.some((r) => overlaps(r, startLine, endLine));
+}

package/dist/fs-source-access.d.ts

@@ -0,0 +1,7 @@
+import type { SourceAccess } from './source-access.js';
+/** The default, fs-rooted `SourceAccess` -- reads a checked-out worktree
+ * directly. This is what every stage with a local checkout (pump,
+ * preflight, eval, and the CI Action's own `actions/checkout`, per the
+ * operator's confirmation) supplies; nothing in this library performs a
+ * fetch of its own. */
+export declare function fsSourceAccess(root: string): SourceAccess;

package/dist/fs-source-access.js

@@ -0,0 +1,39 @@
+import { readFile as fsReadFile, readdir } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+const IGNORED_DIRS = new Set(['.git', 'node_modules', 'dist', 'build']);
+async function walk(root, dir, out) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            if (IGNORED_DIRS.has(entry.name))
+                continue;
+            await walk(root, join(dir, entry.name), out);
+            continue;
+        }
+        if (entry.isFile()) {
+            out.push(relative(root, join(dir, entry.name)).split(sep).join('/'));
+        }
+    }
+}
+/** The default, fs-rooted `SourceAccess` -- reads a checked-out worktree
+ * directly. This is what every stage with a local checkout (pump,
+ * preflight, eval, and the CI Action's own `actions/checkout`, per the
+ * operator's confirmation) supplies; nothing in this library performs a
+ * fetch of its own. */
+export function fsSourceAccess(root) {
+    return {
+        async listFiles() {
+            const out = [];
+            await walk(root, root, out);
+            return out.sort();
+        },
+        async readFile(path) {
+            try {
+                return await fsReadFile(join(root, path), 'utf8');
+            }
+            catch {
+                return undefined;
+            }
+        },
+    };
+}

package/dist/parseReply.js

@@ -75,6 +75,51 @@ function taggedLines(lines, marker) {
         .filter((line) => line.trimStart().startsWith(marker))
         .map((line) => line.trimStart().slice(marker.length).trim());
 }
+const ALL_MARKERS = [VERDICT_MARKER, FINDING_MARKER, REASON_MARKER, RULING_MARKER];
+function isMarkerLine(line) {
+    const trimmed = line.trimStart();
+    return ALL_MARKERS.some((marker) => trimmed.startsWith(marker));
+}
+/** An indented line, a list item, or a numbered item: a continuation even after a blank. */
+function isIndentedOrListed(line) {
+    return /^[ \t]+\S/.test(line) || /^[-*+]\s/.test(line) || /^\d+[.)]\s/.test(line);
+}
+/**
+ * Every `FINDING:` line with the lines that continue it. A finding runs from
+ * its marker line until the next marker line (FINDING:, VERDICT:, REASON:,
+ * RULING:), a markdown heading, or the end of the reply; a blank line ends it
+ * unless the next non-blank line is indented or a list item (so sub-bullets
+ * after a blank still belong to it). Without this a finding whose sentence
+ * wraps, or that is followed by sub-bullets, was cut at its first line.
+ */
+function findingBlocks(lines) {
+    const blocks = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (!line.trimStart().startsWith(FINDING_MARKER))
+            continue;
+        const raw = line.trimStart().slice(FINDING_MARKER.length).trim();
+        const detail = [];
+        let pendingBlanks = 0;
+        for (let j = i + 1; j < lines.length; j++) {
+            const next = lines[j] ?? '';
+            if (isMarkerLine(next) || /^#{1,6}\s/.test(next))
+                break;
+            if (next.trim() === '') {
+                pendingBlanks++;
+                continue;
+            }
+            if (pendingBlanks > 0 && !isIndentedOrListed(next))
+                break;
+            for (let b = 0; b < pendingBlanks; b++)
+                detail.push('');
+            pendingBlanks = 0;
+            detail.push(next.replace(/\s+$/, ''));
+        }
+        blocks.push({ raw, detail: detail.join('\n') });
+    }
+    return blocks;
+}
 function cannotRun(lens, reason) {
     return { lens, outcome: 'could_not_run', findings: [], reason };
 }
@@ -147,16 +192,22 @@ function parseReplyBase(lens, text) {
     if (verdict === '') {
         return cannotRun(lens, `reply carried an empty ${VERDICT_MARKER} line`);
     }
-    const findingLines = taggedLines(lines, FINDING_MARKER);
-    const findings = findingLines
-        .filter((raw) => raw !== '')
-        .map((raw) => severityOf(lens, raw))
+    const blocks = findingBlocks(lines);
+    const findings = blocks
+        .filter((block) => block.raw !== '')
+        .map((block) => {
+        const finding = severityOf(lens, block.raw);
+        return block.detail === '' ? finding : { ...finding, detail: block.detail };
+    })
         .filter((finding) => finding.summary !== '');
-    const emptyFindings = findingLines.length - findings.length;
+    const emptyFindings = blocks.length - findings.length;
     const blockingFindings = findings.filter((finding) => finding.blocking);
     if (verdict === APPROVED_WORD || verdict === REJECTED_WORD) {
+        // An optional one-line account of the judgement, shown in the report next to the verdict.
+        const note = taggedLines(lines, REASON_MARKER).find((reason) => reason !== '');
+        const withNote = note === undefined ? {} : { reason: note };
         if (blockingFindings.length > 0) {
-            return { lens, outcome: 'rejected', findings };
+            return { lens, outcome: 'rejected', findings, ...withNote };
         }
         if (emptyFindings > 0) {
             return cannotRun(lens, `reply carried ${emptyFindings} empty ${FINDING_MARKER} line(s) — named nothing ` +
@@ -168,7 +219,7 @@ function parseReplyBase(lens, text) {
                     `finding(s); a rejection requires at least one blocking finding`
                 : `reply said ${REJECTED_WORD} without naming a finding`);
         }
-        return { lens, outcome: 'approved', findings };
+        return { lens, outcome: 'approved', findings, ...withNote };
     }
     if (verdict === CANNOT_RUN_WORD) {
         const reasons = taggedLines(lines, REASON_MARKER).filter((reason) => reason !== '');