@applesnort/crosscheck 0.2.2 → 0.6.0

package/lib/cache.mjs

@@ -0,0 +1,100 @@
+/*!
+ * Copyright (c) 2026 Joel Mangin. MIT License.
+ */
+// Result cache.
+//
+// A panel that re-reviews unchanged files on every run costs money for nothing,
+// and a tool that costs money for nothing gets switched off. Caching is keyed on
+// everything that could change the answer: the lens definition, the files, their
+// contents, and the prompt options.
+//
+// The lens definition is part of the key on purpose. Editing a lens must
+// invalidate its cached results — a cache that survives a prompt change would
+// quietly serve answers from the old lens and there would be no way to tell.
+//
+// Pure key computation; IO is injected so this is testable without a disk.
+
+// FNV-1a over the inputs. Not cryptographic: it only has to distinguish inputs
+// within one project, and a collision costs a stale result rather than a
+// security failure.
+export function digest(parts) {
+  let h = 0x811c9dc5;
+  for (const part of parts) {
+    const s = String(part);
+    for (let i = 0; i < s.length; i++) {
+      h = Math.imul(h ^ s.charCodeAt(i), 0x01000193) >>> 0;
+    }
+    // Separator, so ['ab','c'] and ['a','bc'] do not collide.
+    h = Math.imul(h ^ 0x1f, 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
+export const CACHE_VERSION = 1;
+
+// files: [{path, content}] in the order the lens will see them.
+export function cacheKey({ lens, definition, files, promptOptions = {} }) {
+  if (!lens) {
+    throw new Error('cacheKey requires a lens name');
+  }
+  return digest([
+    `v${CACHE_VERSION}`,
+    lens,
+    // The definition body decides what the lens does, so it decides the answer.
+    definition ?? '',
+    ...(files ?? []).flatMap(f => [f.path, f.content ?? '']),
+    JSON.stringify(promptOptions ?? {})
+  ]);
+}
+
+// entry: {key, lens, output, storedAt}
+export function isUsableEntry(entry, key) {
+  return Boolean(
+    entry &&
+    entry.key === key &&
+    entry.version === CACHE_VERSION &&
+    typeof entry.output === 'string' &&
+    entry.output.length > 0);
+}
+
+export function makeEntry({ key, lens, output, now }) {
+  return {
+    version: CACHE_VERSION,
+    key,
+    lens,
+    // Recorded for a human reading the cache directory, not used for matching.
+    storedAt: now ?? null,
+    output
+  };
+}
+
+// A cache wired to injected IO. `read` returns a parsed entry or null; `write`
+// persists one. Both may be omitted to disable caching entirely, which is what
+// --no-cache does.
+export function createCache({ read = null, write = null } = {}) {
+  const stats = { hits: 0, misses: 0, writes: 0, hitLenses: [] };
+  return {
+    stats,
+    enabled: Boolean(read || write),
+    get(key, lens) {
+      if (!read) {
+        return null;
+      }
+      const entry = read(key);
+      if (isUsableEntry(entry, key)) {
+        stats.hits += 1;
+        stats.hitLenses.push(lens);
+        return entry.output;
+      }
+      stats.misses += 1;
+      return null;
+    },
+    set(key, lens, output, now = null) {
+      if (!write || !output) {
+        return;
+      }
+      write(key, makeEntry({ key, lens, output, now }));
+      stats.writes += 1;
+    }
+  };
+}

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/lenses.mjs

@@ -198,3 +198,38 @@ export function applyOverrides(routed, { only, skip } = {}) {
   }
   return { roster, skipped };
 }
+
+// Layered lens resolution.
+//
+// A single lens directory has to be either yours or the packaged one, which
+// forces anyone adding a lens to fork all of them and lose upstream changes.
+// Sources are layered instead, in increasing precedence: a later source with the
+// same lens `name` shadows an earlier one, so overriding one lens costs one file
+// rather than a fork.
+//
+// sources: [{origin, lenses: [{name, ...}]}] — origin is a label for reporting,
+// usually the directory the lenses were read from.
+export function resolveLensSet(sources) {
+  const byName = new Map();
+  const shadowed = [];
+  for (const source of sources ?? []) {
+    for (const lens of source.lenses ?? []) {
+      if (!lens?.name) {
+        continue;
+      }
+      const previous = byName.get(lens.name);
+      if (previous) {
+        shadowed.push({
+          name: lens.name,
+          winner: source.origin,
+          shadowedFrom: previous.origin
+        });
+      }
+      byName.set(lens.name, { ...lens, origin: source.origin });
+    }
+  }
+  return {
+    lenses: [...byName.values()].sort((a, b) => a.name.localeCompare(b.name)),
+    shadowed
+  };
+}

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
+  };
 }