@applesnort/crosscheck 0.3.0 → 0.6.0

package/lib/comment.mjs

@@ -0,0 +1,138 @@
+/*!
+ * Copyright (c) 2026 Joel Mangin. MIT License.
+ */
+// Build a pull-request comment.
+//
+// Deliberately a summary, not per-line review comments. SARIF uploaded to code
+// scanning already annotates the exact lines in the Files-changed view, and does
+// it better than a bot posting threads. What that view cannot show is the shape of
+// the run: which lenses were skipped, which died, what the baseline suppressed,
+// what verification refuted. That is what this comment carries.
+//
+// Every comment embeds a marker so a later run can edit the previous one instead
+// of stacking. A PR with eleven bot comments gets muted, and a muted reviewer
+// finds nothing.
+
+export const COMMENT_MARKER = '<!-- crosscheck:report -->';
+
+const LEVEL_LABEL = { BLOCK: '🔴 BLOCK', FIX: '🟡 FIX', CONSIDER: '⚪ CONSIDER' };
+
+function severitySection(findings, severity, { limit }) {
+  const group = findings.filter(f => f.severity === severity);
+  if (group.length === 0) {
+    return [];
+  }
+  const lines = [`### ${LEVEL_LABEL[severity]} (${group.length})`, ''];
+  for (const f of group.slice(0, limit)) {
+    const who = f.consensus
+      ? `**${f.lenses.join(' + ')}** agreed`
+      : `${f.lenses.join(', ')}`;
+    const collapsed = f.occurrences > f.lenses.length
+      ? ` · ${f.occurrences} reports across lines ${f.lines.join(', ')}`
+      : '';
+    lines.push(
+      `- \`${f.file}:${f.line}\` — ${f.issue}` +
+      (f.fix ? `\n  **Fix:** ${f.fix}` : '') +
+      `\n  <sub>${who}${collapsed}</sub>`);
+  }
+  if (group.length > limit) {
+    // Named, not hidden: a truncated list that does not say so reads as the
+    // whole list.
+    lines.push('', `_…and ${group.length - limit} more ${severity} finding(s) ` +
+      'not shown here. The full set is in the SARIF output and the run log._');
+  }
+  lines.push('');
+  return lines;
+}
+
+// merged: the object from mergeFindings, optionally with the run's disclosures.
+export function buildComment({
+  merged,
+  refuted = [],
+  suppressed = [],
+  dropped = [],
+  skipped = [],
+  target = null,
+  sarifPath = null,
+  limitPerSeverity = 10
+} = {}) {
+  const findings = merged?.findings ?? [];
+  const incomplete = merged?.incomplete ?? [];
+  const counts = {
+    BLOCK: findings.filter(f => f.severity === 'BLOCK').length,
+    FIX: findings.filter(f => f.severity === 'FIX').length,
+    CONSIDER: findings.filter(f => f.severity === 'CONSIDER').length
+  };
+
+  const out = [COMMENT_MARKER, '', '## crosscheck'];
+
+  if (target) {
+    out.push('', `Reviewed ${target}.`);
+  }
+
+  if (findings.length === 0) {
+    out.push('', 'No findings.');
+  } else {
+    out.push('',
+      `**${counts.BLOCK} block · ${counts.FIX} fix · ${counts.CONSIDER} consider**` +
+      (findings.some(f => f.consensus)
+        ? ` · ${findings.filter(f => f.consensus).length} agreed by more than one lens`
+        : ''),
+      '');
+    for (const severity of ['BLOCK', 'FIX', 'CONSIDER']) {
+      out.push(...severitySection(findings, severity, { limit: limitPerSeverity }));
+    }
+  }
+
+  // The disclosures. Each one is a hole in the coverage, and a report that omits
+  // them reads as completeness that was never there. Zeroes are stated too.
+  const notes = [];
+  notes.push(`Refuted in verification: ${refuted.length}`);
+  if (incomplete.length) {
+    notes.push(`**Did not complete: ${incomplete.join(', ')}** — their coverage ` +
+      'is missing from this report');
+  }
+  if (dropped.length) {
+    notes.push(`**Budget reached** — not run: ${dropped.map(d => d.lens ?? d).join(', ')}`);
+  }
+  if (suppressed.length) {
+    notes.push(`Suppressed by baseline: ${suppressed.length}`);
+  }
+  if (skipped.length) {
+    // Two different reasons — nothing in scope matched, or you excluded it — and
+    // calling an explicit exclusion "irrelevant" misstates the run.
+    const irrelevant = skipped.filter(s => !/--only|--skip/.test(s.reason ?? ''));
+    const excluded = skipped.filter(s => /--only|--skip/.test(s.reason ?? ''));
+    if (irrelevant.length) {
+      notes.push('Not applicable to these files: ' +
+        irrelevant.map(s => s.lens ?? s).join(', '));
+    }
+    if (excluded.length) {
+      notes.push('Excluded by request: ' +
+        excluded.map(s => s.lens ?? s).join(', '));
+    }
+  }
+  out.push('<details><summary>Run details</summary>', '');
+  for (const note of notes) {
+    out.push(`- ${note}`);
+  }
+  if (sarifPath) {
+    out.push('', `SARIF written to \`${sarifPath}\` — upload it to code scanning ` +
+      'for per-line annotations in the Files changed view.');
+  }
+  out.push('', '</details>');
+
+  return out.join('\n') + '\n';
+}
+
+// True when a comment body was written by crosscheck, so a run can edit its own
+// previous comment rather than adding another.
+export function isOwnComment(body) {
+  return String(body ?? '').includes(COMMENT_MARKER);
+}
+
+// Given the comments on a PR, the id of ours to update, or null to create one.
+export function findOwnComment(comments) {
+  const mine = (comments ?? []).filter(c => isOwnComment(c.body));
+  return mine.length ? mine[mine.length - 1].id ?? null : null;
+}

package/lib/config.mjs

@@ -23,7 +23,13 @@ export const CONFIG_FILENAMES = [
 // an error.
 export const CONFIG_KEYS = new Set([
   'exec', 'lenses', 'concurrency', 'only', 'skip', 'mixed',
-  'out', 'sarif', 'baseline', 'overlap'
+  'out', 'sarif', 'baseline', 'overlap',
+  // Phase 1: change-scoped review, verification, and a project's own gate.
+  'preflight', 'context', 'verify', 'no-verify', 'since',
+  // Phase 2: cost control.
+  'max-dispatches', 'no-cache', 'cache-dir',
+  // Phase 3: CI integration.
+  'comment-file'
 ]);
 
 const LIST_KEYS = new Set(['only', 'skip']);
@@ -60,18 +66,36 @@ export function validateConfig(raw, source = 'config') {
       }
       continue;
     }
-    if (key === 'concurrency') {
+    // `exec` may be one command for every lens, or a map choosing per lens so a
+    // cheap lens does not pay for an expensive model.
+    if (key === 'exec' && value && typeof value === 'object' &&
+        !Array.isArray(value)) {
+      const bad = Object.entries(value)
+        .filter(([, v]) => typeof v !== 'string' || v === '');
+      if (bad.length) {
+        problems.push(
+          `${source}: exec map entries must be non-empty strings ` +
+          `(${bad.map(([k]) => k).join(', ')})`);
+        continue;
+      }
+      config.exec = { ...value };
+      continue;
+    }
+    if (key === 'concurrency' || key === 'context' || key === 'max-dispatches') {
       const n = Number(value);
-      if (!Number.isInteger(n) || n < 1) {
-        problems.push(`${source}: "concurrency" must be a positive integer`);
+      const floor = key === 'context' ? 0 : 1;
+      if (!Number.isInteger(n) || n < floor) {
+        problems.push(
+          `${source}: "${key}" must be an integer >= ${floor}`);
         continue;
       }
       config[key] = n;
       continue;
     }
-    if (key === 'mixed') {
+    if (key === 'mixed' || key === 'verify' || key === 'no-verify' ||
+        key === 'no-cache') {
       if (typeof value !== 'boolean') {
-        problems.push(`${source}: "mixed" must be true or false`);
+        problems.push(`${source}: "${key}" must be true or false`);
         continue;
       }
       config[key] = value;

package/lib/merge.mjs

@@ -254,7 +254,13 @@ export function mergeFindings(reports, options = {}) {
     const finding = {
       ...rest,
       consensus: c.lenses.length > 1,
-      consensusScore: consensusScore(c.lenses, overlap)
+      consensusScore: consensusScore(c.lenses, overlap),
+      // How many reports collapsed into this entry. Clustering is transitive —
+      // a run of similar findings on consecutive lines chains into one — so a
+      // collapse much larger than the lens count needs to be visible rather
+      // than looking like a single finding.
+      occurrences: members.length,
+      lines: [...new Set(members.map(m => m.line))].sort((a, b) => a - b)
     };
     // The key is derived after clustering, from the reported anchor and the
     // representative issue, so a baseline stays stable across runs.

package/lib/prompt.mjs

@@ -14,6 +14,12 @@ export const CONTRACT_LINE =
 // The frontmatter is routing metadata — globs, cites, owns — consumed by the
 // router before dispatch. Sending it to the model costs tokens on every call and
 // tells it nothing it needs, so the body is what gets inlined.
+function formatSpans(spans) {
+  return spans
+    .map(([start, end]) => start === end ? `${start}` : `${start}-${end}`)
+    .join(', ');
+}
+
 export function stripFrontmatter(text) {
   return String(text ?? '').replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '').trim();
 }
@@ -26,6 +32,7 @@ export function buildLensPrompt(lens, files, options = {}) {
     definitionPath = null,
     definition = null,
     mixedCorpus = false,
+    rangesByFile = null,
     extra = null
   } = options;
 
@@ -68,9 +75,29 @@ export function buildLensPrompt(lens, files, options = {}) {
       'reporting them here duplicates that lens and weakens the panel.');
   }
 
+  const ranges = rangesByFile ?? {};
+  const hasRanges = files.some(f => (ranges[f] ?? []).length > 0);
   parts.push(
     `Audit exactly these ${files.length} file(s), reading each one completely ` +
-    'before reporting on it:\n' + files.map(f => `  - ${f}`).join('\n'));
+    'before reporting on it:\n' +
+    files.map(f => {
+      const spans = ranges[f] ?? [];
+      return spans.length
+        ? `  - ${f}  (changed lines: ${formatSpans(spans)})`
+        : `  - ${f}`;
+    }).join('\n'));
+
+  if (hasRanges) {
+    // Reporting only inside the diff would miss the common case: a change that
+    // breaks something it did not touch. The changed lines are the priority, not
+    // the boundary.
+    parts.push(
+      'This is a review of a change. The changed lines are listed above — read ' +
+      'each file completely for context, and concentrate on what the change ' +
+      'introduces or breaks. A defect elsewhere in the file is still worth ' +
+      'reporting when the change causes it or depends on it; a pre-existing ' +
+      'defect the change does not touch is not what this review is for.');
+  }
 
   if (mixedCorpus) {
     parts.push(
@@ -95,3 +122,62 @@ export function buildLensPrompt(lens, files, options = {}) {
 
   return parts.join('\n\n');
 }
+
+// The verification pass. `foreman.md` has always called for refuting every
+// BLOCK by default, on the grounds that a panel which cries wolf stops being
+// read. The skeptic is given the file rather than the finding's own account of
+// it, and told to default to refuted when the evidence is not there — a verifier
+// that accepts a plausible story adds cost and no signal.
+export function buildRefutePrompt(finding, options = {}) {
+  const { extra = null } = options;
+  if (!finding?.file) {
+    throw new Error('buildRefutePrompt requires a finding with a file');
+  }
+  const parts = [
+    'You are verifying one claimed defect. Your job is to REFUTE it.',
+    `Claim: ${finding.file}:${finding.line} — ${finding.issue}` +
+      (finding.fix ? `\nProposed fix: ${finding.fix}` : ''),
+    `Read \`${finding.file}\` yourself. Do not take the claim's description of ` +
+    'the code as accurate — check it. Then decide:\n\n' +
+    '  - Is the code actually as the claim describes?\n' +
+    '  - Can you name a concrete input, state, or sequence that triggers the ' +
+    'defect?\n' +
+    '  - Does something already in the code prevent it — a guard, a validation, ' +
+    'a caller contract, a type?',
+    'Default to refuted. If you cannot demonstrate the defect is real, it is ' +
+    'refuted. A finding that survives only because nobody could disprove it is ' +
+    'the kind this pass exists to remove.'
+  ];
+  if (extra) {
+    parts.push(extra);
+  }
+  parts.push(
+    'Reply with exactly one line:\n\n' +
+    '  REFUTED — why the claim does not hold\n' +
+    'or\n' +
+    '  CONFIRMED — the concrete trigger you verified\n\n' +
+    'No preamble, no other text.');
+  return parts.join('\n\n');
+}
+
+const REFUTED = /^\s*REFUTED\b/i;
+const CONFIRMED = /^\s*CONFIRMED\b/i;
+
+// An unparseable verdict is treated as refuted, matching the default above: a
+// verifier that produced nothing usable has not established the finding.
+export function parseVerdict(text) {
+  const line = String(text ?? '').trim().split('\n')
+    .find(l => REFUTED.test(l) || CONFIRMED.test(l)) ?? '';
+  if (CONFIRMED.test(line)) {
+    return {
+      refuted: false,
+      reason: line.replace(CONFIRMED, '').replace(/^\s*[—-]\s*/, '').trim() || null
+    };
+  }
+  return {
+    refuted: true,
+    reason: line
+      ? line.replace(REFUTED, '').replace(/^\s*[—-]\s*/, '').trim() || null
+      : 'verifier produced no usable verdict'
+  };
+}

package/lib/run.mjs

@@ -13,12 +13,42 @@
 // mean that lens did not produce a report — recorded as incomplete, never
 // silently treated as "found nothing".
 
-import { buildLensPrompt } from './prompt.mjs';
+import { buildLensPrompt, buildRefutePrompt, parseVerdict } from './prompt.mjs';
 import { applyOverrides, routeRoster } from './lenses.mjs';
 import { parseLensOutput } from './parse.mjs';
 
 export const DEFAULT_CONCURRENCY = 4;
 
+// Which command runs a given lens. A conventions lens checking copyright years
+// does not need what a security lens needs, and cost is what decides whether a
+// team leaves this switched on. Precedence: the lens's own `exec`, then a
+// per-lens entry in the config's exec map, then the single default.
+export function resolveExec(lens, exec) {
+  if (lens?.exec) {
+    return lens.exec;
+  }
+  if (exec && typeof exec === 'object') {
+    return exec[lens?.name] ?? exec.default ?? null;
+  }
+  return exec ?? null;
+}
+
+// crosscheck cannot see tokens or money — `--exec` is an arbitrary command — so
+// the only unit it can honestly cap is the number of dispatches. Pretending to
+// budget dollars would be a number made up from nothing.
+export function planBudget(jobs, maxDispatches) {
+  if (maxDispatches == null || maxDispatches >= (jobs ?? []).length) {
+    return { run: jobs ?? [], dropped: [] };
+  }
+  if (maxDispatches <= 0) {
+    return { run: [], dropped: jobs ?? [] };
+  }
+  return {
+    run: jobs.slice(0, maxDispatches),
+    dropped: jobs.slice(maxDispatches)
+  };
+}
+
 // lenses: [{name, when, owns, 'not-owns', definition?, definitionPath?}]
 // Returns {roster, skipped} — skipped always carries a reason, because a lens
 // dropped without one reads as coverage that never happened.
@@ -56,6 +86,49 @@ export function promptsFor(roster, options = {}) {
   }));
 }
 
+// Refute each finding independently, bounded by the same concurrency cap. Returns
+// verdicts keyed by finding key, plus any verifier that failed — a verifier that
+// did not run must not be read as agreement, so its finding is left standing and
+// the failure is reported.
+export async function verifyFindings({
+  findings,
+  exec,
+  concurrency = DEFAULT_CONCURRENCY,
+  onVerdict = null
+} = {}) {
+  if (typeof exec !== 'function') {
+    throw new Error('verifyFindings requires an exec function');
+  }
+  const targets = findings ?? [];
+  const verdicts = {};
+  const failures = [];
+  await mapLimit(targets, concurrency, async finding => {
+    let result;
+    try {
+      result = await exec({
+        prompt: buildRefutePrompt(finding),
+        lens: `verify:${finding.lenses?.[0] ?? 'finding'}`,
+        files: [finding.file]
+      });
+    } catch (error) {
+      failures.push({
+        finding: finding.key, reason: error?.message ?? String(error)
+      });
+      return;
+    }
+    if ((result?.code ?? 0) !== 0) {
+      failures.push({
+        finding: finding.key, reason: `verifier exited ${result?.code}`
+      });
+      return;
+    }
+    const verdict = parseVerdict(result?.stdout);
+    verdicts[finding.key] = verdict;
+    onVerdict?.(finding, verdict);
+  });
+  return { verdicts, failures };
+}
+
 // Bounded-concurrency map that preserves input order. Kept local rather than
 // pulling in a dependency for nine lines.
 async function mapLimit(items, limit, worker) {
@@ -84,17 +157,37 @@ export async function runPanel({
   exec,
   concurrency = DEFAULT_CONCURRENCY,
   promptOptions = {},
+  cache = null,
+  cacheKeyFor = null,
+  maxDispatches = null,
   onLensStart = null,
-  onLensDone = null
+  onLensDone = null,
+  onCacheHit = null
 } = {}) {
   if (typeof exec !== 'function') {
     throw new Error('runPanel requires an exec function');
   }
-  const jobs = promptsFor(roster ?? [], promptOptions);
+  const allJobs = promptsFor(roster ?? [], promptOptions);
   const failures = [];
 
+  // Truncation is disclosed, never silent: a run that quietly stopped early
+  // looks exactly like a run that found nothing.
+  const { run: jobs, dropped } = planBudget(allJobs, maxDispatches);
+
   const reports = await mapLimit(jobs, concurrency, async job => {
     onLensStart?.(job.lens);
+    const key = cache && cacheKeyFor ? cacheKeyFor(job) : null;
+    if (key) {
+      const cached = cache.get(key, job.lens);
+      if (cached != null) {
+        const { findings, unparsed } = parseLensOutput(cached);
+        onCacheHit?.(job.lens);
+        onLensDone?.(job.lens, {
+          ok: true, findings: findings.length, cached: true
+        });
+        return { lens: job.lens, findings, unparsed, output: cached };
+      }
+    }
     let result;
     try {
       result = await exec({ prompt: job.prompt, lens: job.lens, files: job.files });
@@ -124,11 +217,20 @@ export async function runPanel({
       return { lens: job.lens, findings: null, unparsed: [], output: null };
     }
     const { findings, unparsed } = parseLensOutput(stdout);
+    if (key) {
+      cache.set(key, job.lens, stdout);
+    }
     onLensDone?.(job.lens, { ok: true, findings: findings.length });
     // `output` is the verbatim lens text, kept so `--out` can save a run and it
     // can be rescored later without paying the model again.
     return { lens: job.lens, findings, unparsed, output: stdout };
   });
 
-  return { reports, skipped, failures };
+  return {
+    reports,
+    skipped,
+    failures,
+    dropped: dropped.map(j => ({ lens: j.lens, files: j.files.length })),
+    cacheStats: cache?.stats ?? null
+  };
 }

package/lib/target.mjs

@@ -0,0 +1,123 @@
+/*!
+ * Copyright (c) 2026 Joel Mangin. MIT License.
+ */
+// Resolve what to review from a diff.
+//
+// Auditing whole paths makes cost scale with repository size rather than change
+// size, and re-reviews code nobody touched. A review is of a change, so the
+// target is a diff — parsed here into files and the line ranges that moved.
+//
+// Pure: the caller runs git and passes the text in. That keeps this testable
+// against recorded diffs and keeps git invocation in one place.
+
+// `@@ -old,count +new,count @@` — the new-side numbers are the ones that exist in
+// the working tree, so those are what a lens can cite.
+const HUNK = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/;
+const FILE_HEADER = /^\+\+\+ (?:b\/)?(.+)$/;
+const RENAME_TO = /^rename to (.+)$/;
+
+// A deleted file has no new-side path; nothing can be reviewed in it.
+const DEV_NULL = '/dev/null';
+
+export function parseDiff(diffText) {
+  const byFile = new Map();
+  let current = null;
+  for (const rawLine of String(diffText ?? '').split('\n')) {
+    const renamed = RENAME_TO.exec(rawLine);
+    if (renamed) {
+      current = renamed[1].trim();
+      if (!byFile.has(current)) {
+        byFile.set(current, []);
+      }
+      continue;
+    }
+    const header = FILE_HEADER.exec(rawLine);
+    if (header) {
+      const path = header[1].trim();
+      current = path === DEV_NULL ? null : path;
+      if (current && !byFile.has(current)) {
+        byFile.set(current, []);
+      }
+      continue;
+    }
+    const hunk = HUNK.exec(rawLine);
+    if (hunk && current) {
+      const start = Number(hunk[1]);
+      const count = hunk[2] == null ? 1 : Number(hunk[2]);
+      // A hunk with count 0 is a pure deletion at that point: there are no new
+      // lines to review, so it contributes no range.
+      if (count > 0) {
+        byFile.get(current).push([start, start + count - 1]);
+      }
+    }
+  }
+  return [...byFile.entries()].map(([file, ranges]) => ({
+    file,
+    ranges: mergeRanges(ranges)
+  }));
+}
+
+// Adjacent or overlapping hunks read better as one range, and a lens does not
+// care that git split them.
+export function mergeRanges(ranges, gap = 1) {
+  const sorted = [...(ranges ?? [])].sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+  const out = [];
+  for (const [start, end] of sorted) {
+    const last = out[out.length - 1];
+    if (last && start <= last[1] + gap) {
+      last[1] = Math.max(last[1], end);
+      continue;
+    }
+    out.push([start, end]);
+  }
+  return out;
+}
+
+// Widen each range by `context` lines so a lens can see what surrounds a change.
+// A defect introduced by a diff is frequently visible only against the code the
+// diff did not touch.
+export function withContext(ranges, context = 20, maxLine = Infinity) {
+  return mergeRanges((ranges ?? []).map(([start, end]) =>
+    [Math.max(1, start - context), Math.min(maxLine, end + context)]));
+}
+
+export function changedFiles(diffText) {
+  return parseDiff(diffText).map(entry => entry.file);
+}
+
+// Files with no reviewable new-side content — deletions — are excluded by
+// parseDiff, so anything returned here exists and has lines a lens can cite.
+export function targetFromDiff(diffText, { filter = null } = {}) {
+  const entries = parseDiff(diffText)
+    .filter(entry => entry.ranges.length > 0)
+    .filter(entry => (filter ? filter(entry.file) : true));
+  return {
+    files: entries.map(e => e.file),
+    rangesByFile: Object.fromEntries(entries.map(e => [e.file, e.ranges]))
+  };
+}
+
+export function formatRanges(ranges) {
+  return (ranges ?? [])
+    .map(([start, end]) => start === end ? `${start}` : `${start}-${end}`)
+    .join(', ');
+}
+
+// The git command for each targeting mode. Returned rather than executed so the
+// caller owns process spawning and this stays pure.
+export function diffCommand({ diff, staged, since } = {}) {
+  // --unified=0 keeps hunk headers tight to the changed lines; context is added
+  // deliberately by withContext rather than inherited from git's default.
+  const base = ['diff', '--unified=0', '--no-color', '--no-ext-diff'];
+  if (staged) {
+    return [...base, '--cached'];
+  }
+  if (since) {
+    return [...base, `${since}...HEAD`];
+  }
+  if (typeof diff === 'string' && diff !== '' && diff !== 'true') {
+    return [...base, `${diff}...HEAD`];
+  }
+  // Bare --diff: everything not yet committed, staged or not.
+  return [...base, 'HEAD'];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applesnort/crosscheck",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "description": "Run independent review lenses in parallel and merge their findings into one deduped, consensus-ranked report \u2014 with SARIF output.",
   "license": "MIT",
   "author": "Joel Mangin",
@@ -21,7 +21,10 @@
     "./calibrate": "./lib/calibrate.mjs",
     "./run": "./lib/run.mjs",
     "./prompt": "./lib/prompt.mjs",
-    "./config": "./lib/config.mjs"
+    "./config": "./lib/config.mjs",
+    "./target": "./lib/target.mjs",
+    "./cache": "./lib/cache.mjs",
+    "./comment": "./lib/comment.mjs"
   },
   "files": [
     "bin/",