@verevoir/review 0.2.0 → 0.3.0

package/src/context-files.ts

@@ -0,0 +1,194 @@
+// 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.';
+
+export interface ContextFs {
+  /** Resolve symlinks. Rejects with an fs-style `code` (ENOENT...) if absent. */
+  readonly realpath: (path: string) => Promise<string>;
+  readonly statFile: (path: string) => Promise<{ readonly size: number; readonly isFile: boolean }>;
+  readonly readFile: (path: string) => Promise<string>;
+}
+
+export interface DiffPath {
+  readonly path: string;
+  /** True when the file is deleted by the change (`+++ /dev/null`). */
+  readonly deleted: boolean;
+}
+
+function unquote(raw: string): string | undefined {
+  const tab = raw.indexOf('\t');
+  const trimmed = (tab === -1 ? raw : raw.slice(0, tab)).trim();
+  if (!trimmed.startsWith('"')) return trimmed;
+  try {
+    const parsed: unknown = JSON.parse(trimmed);
+    return typeof parsed === 'string' ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function stripPrefix(path: string, prefix: 'a/' | 'b/'): string {
+  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: string): DiffPath[] {
+  const lines = diff.split(/\r?\n/);
+  const seen = new Set<string>();
+  const out: DiffPath[] = [];
+  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: DiffPath;
+    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: string): string | undefined {
+  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: unknown): boolean {
+  const code = (cause as { code?: unknown }).code;
+  return code === 'ENOENT' || code === 'ENOTDIR';
+}
+
+function describe(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+
+function fenceFor(text: string): string {
+  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: string, root: string, fs: ContextFs): Promise<string> {
+  let rootReal: string;
+  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: string[] = [];
+  const skipped: string[] = [];
+  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: string;
+    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: string[] = [];
+  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/src/dedup.ts

@@ -0,0 +1,187 @@
+// 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 type { Reviewer } from './panel.js';
+import type { Prompt } from './prompt.js';
+import { normaliseForQuote } from './tier.js';
+import type { DedupGroupView } from './report.js';
+import type { Finding } from './verdict.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 interface NumberedFinding {
+  /** `lens:index`, the index counting that lens's findings from 0 in report order. */
+  readonly id: string;
+  readonly finding: Finding;
+}
+
+export function numberFindings(findings: readonly Finding[]): NumberedFinding[] {
+  const next = new Map<string, number>();
+  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: readonly NumberedFinding[]): Prompt {
+  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 };
+}
+
+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 function parseGroups(reply: string, ids: readonly string[]): GroupsResult {
+  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: unknown;
+  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<string>();
+  const groups: string[][] = [];
+  for (const group of parsed as unknown[]) {
+    if (!Array.isArray(group) || group.length === 0) {
+      return { ok: false, reason: 'a group was empty or not an array' };
+    }
+    const members: string[] = [];
+    for (const id of group as unknown[]) {
+      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 };
+}
+
+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 async function dedupFindings(
+  items: readonly NumberedFinding[],
+  review: Reviewer,
+): Promise<DedupResult> {
+  let text: string;
+  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) as NumberedFinding),
+    )
+    .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: readonly (readonly NumberedFinding[])[],
+  practiceNames: Readonly<Record<string, readonly { id: string; title: string }[]>> = {},
+): DedupGroupView[] {
+  return groups.map((members) => {
+    const lenses: string[] = [];
+    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] as NumberedFinding))
+      .finding;
+    return {
+      blocking: members.some((m) => m.finding.blocking),
+      finding: shown,
+      raisedBy,
+    };
+  });
+}

package/src/parseReply.ts

@@ -98,6 +98,51 @@ function taggedLines(lines: readonly string[], marker: string): string[] {
     .map((line) => line.trimStart().slice(marker.length).trim());
 }
 
+const ALL_MARKERS = [VERDICT_MARKER, FINDING_MARKER, REASON_MARKER, RULING_MARKER];
+
+function isMarkerLine(line: string): boolean {
+  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: string): boolean {
+  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: readonly string[]): { raw: string; detail: string }[] {
+  const blocks: { raw: string; detail: string }[] = [];
+  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: string[] = [];
+    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: string, reason: string): LensResult {
   return { lens, outcome: 'could_not_run', findings: [], reason };
 }
@@ -187,17 +232,23 @@ function parseReplyBase(lens: string, text: string): LensResult {
     return cannotRun(lens, `reply carried an empty ${VERDICT_MARKER} line`);
   }
 
-  const findingLines = taggedLines(lines, FINDING_MARKER);
-  const findings: Finding[] = findingLines
-    .filter((raw) => raw !== '')
-    .map((raw) => severityOf(lens, raw))
+  const blocks = findingBlocks(lines);
+  const findings: Finding[] = blocks
+    .filter((block) => block.raw !== '')
+    .map((block): Finding => {
+      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) {
@@ -218,7 +269,7 @@ function parseReplyBase(lens: string, text: string): LensResult {
       );
     }
 
-    return { lens, outcome: 'approved', findings };
+    return { lens, outcome: 'approved', findings, ...withNote };
   }
 
   if (verdict === CANNOT_RUN_WORD) {