@koreanhole/requirement-agent 0.0.0-stage → 0.1.1

package/src/cli.js

@@ -0,0 +1,192 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { review, DEFAULTS, notices } from './orchestrator.js';
+import { defaultStore, listRuns, loadRun, readSnapshot, writeRun } from './store.js';
+import { compareSnapshots, snapshot, PreflightError } from './documents.js';
+import { probeAgents, AGENT_IDS } from './agents.js';
+import { ROLES, ROLE_IDS } from './roles.js';
+import { serve } from './server.js';
+import { clampInt } from './util.js';
+
+const HELP = `requirement-agent — review requirement documents with parallel agents
+
+Usage:
+  requirement-agent review <path> [options]
+  requirement-agent runs [--limit n]
+  requirement-agent show <run-id> [--raw <role>]
+  requirement-agent export <run-id> [--format md|json]
+  requirement-agent recover <run-id>
+  requirement-agent agents
+  requirement-agent roles
+  requirement-agent serve [--port n] [--allow-root dir]
+
+Review options:
+  --roles <a,b>            roles (default: ${DEFAULTS.roles.join(',')})
+  --agent <id>             force one agent (${AGENT_IDS.join(',')})
+  --model <name>           force one model
+  --concurrency <n>        parallel reviewers (default 3)
+  --timeout <s>            per-reviewer budget, including retry (default 240)
+  --run-timeout <s>        whole-run deadline (default 1200)
+  --max-doc-chars <n>      per-document cap (default 60000)
+  --max-total-chars <n>    total context cap (default 80000)
+  --exclude <glob>         repeatable
+  --out <dir>              artifact root
+  --store <dir>            artifact root for runs/show/export/serve
+  --yes                    acknowledge egress without prompting
+  --dry-run                inspect documents and agents, call none
+  --json                   print RunSummary JSON
+  --quiet                  print run id and report path only
+`;
+
+function parse(argv) {
+  const out = { _: [], exclude: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (!a.startsWith('--')) { out._.push(a); continue; }
+    const key = a.slice(2);
+    if (key === 'yes' || key === 'dry-run' || key === 'json' || key === 'quiet') { out[key] = true; continue; }
+    const val = argv[i + 1];
+    if (val == null || val.startsWith('--')) throw new Error(`--${key} needs a value`);
+    i += 1;
+    if (key === 'exclude') out.exclude.push(val); else out[key] = val;
+  }
+  return out;
+}
+
+const num = (v, d) => (v == null ? d : Number(v));
+
+export async function main(argv) {
+  const cmd = argv[0];
+  if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') { process.stdout.write(HELP); return 0; }
+  let args;
+  try { args = parse(argv.slice(1)); } catch (err) { process.stderr.write(`${err.message}\n`); return 1; }
+  const store = args.store ?? args.out ?? defaultStore();
+  try {
+    switch (cmd) {
+      case 'review': return await cmdReview(args, store);
+      case 'runs': return cmdRuns(args, store);
+      case 'show': return cmdShow(args, store);
+      case 'export': return cmdExport(args, store);
+      case 'recover': return cmdRecover(args, store);
+      case 'agents': return cmdAgents();
+      case 'roles': return cmdRoles();
+      case 'serve': return await serve({ port: num(args.port, 0), allowRoots: args['allow-root'] ? [args['allow-root']] : undefined, store });
+      default: process.stderr.write(`unknown command: ${cmd}\n\n${HELP}`); return 1;
+    }
+  } catch (err) {
+    if (err instanceof PreflightError) {
+      process.stderr.write(`${err.code}: ${err.message}\n`);
+      if (err.code === 'egress_unconfirmed') process.stderr.write(`agents: ${err.details.agents.join(', ')}\n`);
+      return ['output_refused'].includes(err.code) ? 4 : 3;
+    }
+    process.stderr.write(`${err.message}\n`);
+    return 1;
+  }
+}
+
+async function cmdReview(args, store) {
+  const input = args._[0];
+  if (!input) { process.stderr.write('review needs a path\n'); return 1; }
+  const autoAck = Boolean(args.yes || (process.stdin.isTTY && !args['dry-run'] && await askYes()));
+  const result = await review({
+    inputPath: input, store, out: args.out, roles: args.roles ? String(args.roles).split(',') : undefined,
+    agent: args.agent, model: args.model, concurrency: clampInt(args.concurrency, DEFAULTS.concurrency, 1, 6),
+    timeoutSeconds: num(args.timeout, DEFAULTS.timeoutSeconds), runTimeoutSeconds: num(args['run-timeout'], DEFAULTS.runTimeoutSeconds),
+    maxDocumentChars: num(args['max-doc-chars'], DEFAULTS.maxDocumentChars), maxTotalChars: num(args['max-total-chars'], DEFAULTS.maxTotalChars),
+    exclude: args.exclude, autoAck,
+  });
+  if (result.dryRun) {
+    process.stdout.write(`documents ${result.documentSet.documents.length} skipped ${result.documentSet.skipped.length} chars ${result.documentSet.totalChars} tokens ${result.documentSet.estimatedTokens}\n`);
+    for (const a of result.assignments) process.stdout.write(`${a.role}\t${a.agent}\n`);
+    return 0;
+  }
+  if (args.json) process.stdout.write(`${JSON.stringify(result.run, null, 2)}\n`);
+  else if (args.quiet) process.stdout.write(`${result.run.runId} ${join(result.dir, 'report.md')}\n`);
+  else process.stdout.write(summarize(result.run));
+  return result.exitCode;
+}
+
+function summarize(run) {
+  const c = run.counts ?? {};
+  const lines = [
+    `run ${run.runId}  status ${run.status}`,
+    `located citations ${c.locatedCitations ?? 0}  ambiguous ${c.ambiguousCitations ?? 0}  unlocated ${c.unlocatedCitations ?? 0}  anchor ${c.anchorCitations ?? 0}`,
+    `findings  blocker ${run.counts?.findingsBySeverity?.blocker ?? 0}  major ${run.counts?.findingsBySeverity?.major ?? 0}  minor ${run.counts?.findingsBySeverity?.minor ?? 0}`,
+  ];
+  for (const r of run.reviewers) lines.push(`${r.role}\t${r.agent}\t${r.status}${r.error ? ` (${r.error})` : ''}`);
+  if (run.coverageGaps?.length) lines.push(`coverage gaps: ${run.coverageGaps.join(', ')}`);
+  lines.push(`artifacts ${run.runId}`);
+  return `${lines.join('\n')}\n`;
+}
+
+async function askYes() {
+  process.stderr.write(`Agents receiving document text: ${probeAgents().filter((a) => a.state !== 'missing').map((a) => a.id).join(', ')}\n`);
+  process.stderr.write(`${notices().retention}\n${notices().injection}\n${notices().screening}\nProceed? [y/N] `);
+  const { createInterface } = await import('node:readline/promises');
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  const answer = await rl.question('');
+  rl.close();
+  return /^y(es)?$/i.test(answer.trim());
+}
+
+function cmdRuns(args, store) {
+  for (const r of listRuns(store, clampInt(args.limit, 50, 1, 500))) {
+    process.stdout.write(`${r.runId}\t${r.status}\t${r.startedAt}\t${r.documentSet?.inputPath}\t${r.counts?.locatedCitations ?? 0}\n`);
+  }
+  return 0;
+}
+
+function cmdShow(args, store) {
+  const id = args._[0];
+  const run = id && loadRun(store, id);
+  if (!run) { process.stderr.write('unknown run\n'); return 1; }
+  if (args.raw) {
+    const p = join(run.dir, 'raw', `${args.raw}.txt`);
+    if (!existsSync(p)) { process.stderr.write('no diagnostic for that role\n'); return 1; }
+    process.stdout.write(readFileSync(p, 'utf8'));
+    return 0;
+  }
+  process.stdout.write(`${JSON.stringify({ ...run, dir: undefined }, null, 2)}\n`);
+  return 0;
+}
+
+function cmdExport(args, store) {
+  const id = args._[0];
+  const run = id && loadRun(store, id);
+  if (!run) { process.stderr.write('unknown run\n'); return 1; }
+  const format = args.format ?? 'md';
+  if (format === 'json') {
+    const findings = JSON.parse(readFileSync(join(run.dir, 'findings.json'), 'utf8'));
+    process.stdout.write(`${JSON.stringify({ ...run, findings, dir: undefined }, null, 2)}\n`);
+  } else {
+    process.stdout.write(readFileSync(join(run.dir, 'report.md'), 'utf8'));
+  }
+  return 0;
+}
+
+function cmdRecover(args, store) {
+  const id = args._[0];
+  const run = id && loadRun(store, id);
+  if (!run) { process.stderr.write('unknown run\n'); return 1; }
+  if (!['running', 'interrupted'].includes(run.status)) { process.stderr.write('not recoverable\n'); return 3; }
+  if (run.pid && run.pid !== process.pid) {
+    try { process.kill(run.pid, 0); process.stderr.write('live run; refusing to signal\n'); return 3; } catch { /* dead */ }
+  }
+  const changes = compareSnapshots(readSnapshot(run.dir), snapshot(run.documentSet.inputPath));
+  run.status = changes.length ? 'failed' : 'interrupted';
+  if (changes.length) { run.failureReason = 'tree_changed'; run.coverageGaps = changes.map((c) => `${c.kind}:${c.path}`); }
+  run.finishedAt = new Date().toISOString();
+  for (const r of run.reviewers) if (r.status === 'running') r.status = 'interrupted';
+  writeRun(run.dir, run);
+  return changes.length ? 5 : 0;
+}
+
+function cmdAgents() {
+  for (const a of probeAgents()) process.stdout.write(`${a.id}\t${a.state}\n`);
+  return 0;
+}
+
+function cmdRoles() {
+  for (const id of ROLE_IDS) process.stdout.write(`${id}\t${ROLES[id].title}\n`);
+  return 0;
+}

package/src/documents.js

@@ -0,0 +1,173 @@
+import { readFileSync, statSync, readdirSync, lstatSync, realpathSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { basename, dirname, extname, join, relative, resolve } from 'node:path';
+import { sha256 } from './util.js';
+
+const EXTRACTORS = { '.md': 'text', '.markdown': 'text', '.txt': 'text', '.pdf': 'pdf', '.docx': 'docx' };
+const MAX_FILE_BYTES = 10 * 1024 * 1024;
+const EXTRACT_TIMEOUT_MS = 30_000;
+
+export class PreflightError extends Error {
+  constructor(code, message, details = {}) { super(message); this.code = code; this.details = details; }
+}
+
+export function globToRegExp(glob) {
+  let out = '';
+  for (let i = 0; i < glob.length; i += 1) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') { out += '.*'; i += 1; } else out += '[^/]*';
+    } else if (c === '?') out += '[^/]';
+    else out += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${out}$`);
+}
+
+function excluded(rel, matchers) { return matchers.some((m) => m.test(rel)); }
+
+export function discover(inputPath, { exclude = [], maxFiles = 200, maxSourceBytes = 50 * 1024 * 1024 } = {}) {
+  const input = resolve(inputPath);
+  let st;
+  try { st = statSync(input); } catch { throw new PreflightError('missing_path', `input not found: ${inputPath}`); }
+  const matchers = exclude.map(globToRegExp);
+  const candidates = [];
+  if (st.isFile()) {
+    candidates.push(input);
+  } else if (st.isDirectory()) {
+    const walk = (dir) => {
+      for (const name of readdirSync(dir).sort()) {
+        const p = join(dir, name);
+        const ls = lstatSync(p);
+        if (ls.isSymbolicLink()) continue;
+        if (ls.isDirectory()) { if (!excluded(`${relative(input, p)}/`, matchers)) walk(p); continue; }
+        if (ls.isFile()) candidates.push(p);
+      }
+    };
+    walk(input);
+  } else {
+    throw new PreflightError('missing_path', `unsupported input type: ${inputPath}`);
+  }
+  const root = st.isFile() ? dirname(input) : input;
+  const supported = [];
+  const skipped = [];
+  for (const abs of candidates) {
+    const rel = relative(root, abs) || basename(abs);
+    if (excluded(rel, matchers)) continue;
+    const ext = extname(abs).toLowerCase();
+    if (!EXTRACTORS[ext]) { skipped.push({ path: rel, reason: 'unsupported_format', detail: ext || 'no extension' }); continue; }
+    supported.push({ abs, rel, ext });
+  }
+  if (supported.length > maxFiles) {
+    throw new PreflightError('too_many_candidates', `${supported.length} candidate files exceed the ${maxFiles} limit`, { count: supported.length, limit: maxFiles });
+  }
+  const byDigest = new Map();
+  const documents = [];
+  const duplicates = [];
+  let totalBytes = 0;
+  const seen = new Set();
+  for (const item of supported) {
+    if (seen.has(item.abs)) continue;
+    seen.add(item.abs);
+    let bytes;
+    try { bytes = statSync(item.abs).size; } catch { skipped.push({ path: item.rel, reason: 'unreadable' }); continue; }
+    if (bytes > MAX_FILE_BYTES) { skipped.push({ path: item.rel, reason: 'too_large', detail: `${bytes} bytes` }); continue; }
+    const raw = readFileSync(item.abs);
+    const digest = sha256(raw);
+    if (byDigest.has(digest)) { duplicates.push({ path: item.rel, duplicateOf: byDigest.get(digest) }); continue; }
+    byDigest.set(digest, item.rel);
+    let text;
+    try { text = extract(item.abs, item.ext); } catch (err) {
+      skipped.push({ path: item.rel, reason: err.code === 'ENOENT' ? 'missing_tool' : 'unreadable', detail: err.message });
+      continue;
+    }
+    if (!text.trim()) { skipped.push({ path: item.rel, reason: 'empty_text' }); continue; }
+    documents.push({ path: item.rel, absPath: item.abs, format: item.ext.slice(1), bytes, sha256: digest, text, chars: text.length });
+    totalBytes += bytes;
+  }
+  if (totalBytes > maxSourceBytes) {
+    throw new PreflightError('source_too_large', `sources exceed ${maxSourceBytes} bytes`, { totalBytes, limit: maxSourceBytes });
+  }
+  const estimatedTokens = documents.reduce((n, d) => n + Math.ceil(d.chars * 1.0), 0);
+  return { inputPath: input, root, inputKind: st.isFile() ? 'file' : 'directory', documents, duplicates, skipped, totalBytes, totalChars: documents.reduce((n, d) => n + d.chars, 0), estimatedTokens, truncated: false };
+}
+
+export function extract(abs, ext) {
+  if (EXTRACTORS[ext] === 'text') {
+    const buf = readFileSync(abs);
+    try { return new TextDecoder('utf-8', { fatal: true }).decode(buf).replace(/^\uFEFF/, ''); }
+    catch { const e = new Error('not valid UTF-8'); e.code = 'EENCODING'; throw e; }
+  }
+  if (EXTRACTORS[ext] === 'pdf') {
+    return execFileSync('pdftotext', ['-layout', abs, '-'], { timeout: EXTRACT_TIMEOUT_MS, maxBuffer: 32 * 1024 * 1024 }).toString('utf8');
+  }
+  if (EXTRACTORS[ext] === 'docx') {
+    const xml = execFileSync('unzip', ['-p', abs, 'word/document.xml'], { timeout: EXTRACT_TIMEOUT_MS, maxBuffer: 32 * 1024 * 1024 }).toString('utf8');
+    return xml
+      .replace(/<w:tab[^>]*\/>/g, '\t')
+      .replace(/<\/w:p>/g, '\n')
+      .replace(/<[^>]+>/g, '')
+      .replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&').replace(/&quot;/g, '"').replace(/&apos;/g, "'")
+      .replace(/\n{3,}/g, '\n\n').trim();
+  }
+  throw new Error(`unsupported: ${ext}`);
+}
+
+export function truncateDocuments(documents, maxDocumentChars = 60_000, maxTotalChars = 80_000) {
+  let total = 0;
+  let anyTruncated = false;
+  const docs = [];
+  for (const d of documents) {
+    let text = d.text;
+    let truncated = false;
+    if (text.length > maxDocumentChars) {
+      let cut = text.lastIndexOf('\n', maxDocumentChars);
+      if (cut < maxDocumentChars * 0.5) cut = maxDocumentChars;
+      const omitted = text.length - cut;
+      text = `${text.slice(0, cut)}\n␃ truncated at ${cut} characters; ${omitted} characters and the remainder were not reviewed`;
+      truncated = true;
+    }
+    if (total + text.length > maxTotalChars) {
+      throw new PreflightError('over_budget', `context exceeds ${maxTotalChars} characters`, { needed: total + text.length, limit: maxTotalChars, document: d.path });
+    }
+    total += text.length;
+    if (truncated) anyTruncated = true;
+    docs.push({ ...d, text, chars: text.length, truncated });
+  }
+  return { documents: docs, totalChars: total, truncated: anyTruncated };
+}
+
+export function snapshot(target) {
+  const st = statSync(target);
+  const files = st.isFile() ? [target] : [];
+  if (st.isDirectory()) {
+    const walk = (dir) => {
+      for (const name of readdirSync(dir).sort()) {
+        const p = join(dir, name);
+        const ls = lstatSync(p);
+        if (ls.isSymbolicLink()) continue;
+        if (ls.isDirectory()) walk(p); else if (ls.isFile()) files.push(p);
+      }
+    };
+    walk(target);
+  }
+  return files.map((abs) => {
+    const s = statSync(abs);
+    return { path: relative(st.isFile() ? dirname(target) : target, abs), type: 'file', mode: s.mode & 0o777, size: s.size, mtimeMs: s.mtimeMs, sha256: sha256(readFileSync(abs)) };
+  });
+}
+
+export function compareSnapshots(before, after) {
+  const map = new Map(before.map((e) => [e.path, e]));
+  const changed = [];
+  for (const e of after) {
+    const b = map.get(e.path);
+    if (!b) changed.push({ path: e.path, kind: 'added' });
+    else if (b.sha256 !== e.sha256) changed.push({ path: e.path, kind: 'changed' });
+    else if (b.mode !== e.mode) changed.push({ path: e.path, kind: 'mode' });
+    map.delete(e.path);
+  }
+  for (const p of map.keys()) changed.push({ path: p, kind: 'deleted' });
+  return changed;
+}
+
+export { realpathSync };

package/src/findings.js

@@ -0,0 +1,112 @@
+import { findingIdentity, normalize } from './citations.js';
+
+export const ROLE_ORDER = ['ambiguity', 'completeness', 'testability', 'consistency', 'scope', 'feasibility'];
+export const SEVERITY_RANK = { blocker: 0, major: 1, minor: 2 };
+
+export class InvalidFinding extends Error {}
+
+export function validateFinding(raw) {
+  if (!raw || typeof raw !== 'object') throw new InvalidFinding('finding is not an object');
+  if (!(raw.severity in SEVERITY_RANK)) throw new InvalidFinding(`bad severity: ${raw.severity}`);
+  if (raw.evidenceKind && !['quoted', 'absent'].includes(raw.evidenceKind)) throw new InvalidFinding(`bad evidenceKind: ${raw.evidenceKind}`);
+  if (!Array.isArray(raw.citations) || raw.citations.length === 0) throw new InvalidFinding('finding needs a citation');
+  for (const c of raw.citations) {
+    if (!c || typeof c.document !== 'string' || typeof c.quote !== 'string') throw new InvalidFinding('citation needs document and quote');
+    if (normalize(c.quote).replace(/\s/g, '').length < 8) throw new InvalidFinding('quote too short');
+  }
+  if (typeof raw.explanation !== 'string') throw new InvalidFinding('explanation required');
+  return {
+    severity: raw.severity,
+    evidenceKind: raw.evidenceKind ?? 'quoted',
+    citations: raw.citations.map((c) => ({ document: c.document, quote: c.quote, section: c.section ?? null, lineHint: c.lineHint ?? null })),
+    explanation: raw.explanation,
+    suggestion: typeof raw.suggestion === 'string' ? raw.suggestion : '',
+  };
+}
+
+const HANGUL = /[\uAC00-\uD7A3\u1100-\u11FF\u3130-\u318F]/g;
+const LATIN = /[A-Za-z]/g;
+
+export function languageClass(text) {
+  const s = String(text ?? '');
+  const letters = (s.match(/[A-Za-z\uAC00-\uD7A3\u1100-\u11FF\u3130-\u318F]/g) ?? []).length;
+  if (!letters) return 'mixed';
+  const hangul = (s.match(HANGUL) ?? []).length;
+  const latin = (s.match(LATIN) ?? []).length;
+  if (hangul / letters >= 0.5) return 'ko';
+  if (hangul / letters < 0.1 && latin >= 20) return 'latin';
+  return 'mixed';
+}
+
+export function referenceLanguage(finding, docsByPath) {
+  const counts = { ko: 0, latin: 0, mixed: 0 };
+  for (const c of finding.citations) {
+    const doc = docsByPath.get(c.document);
+    if (doc) counts[languageClass(doc.text.slice(0, 2000))] += 1;
+  }
+  const best = Math.max(counts.ko, counts.latin, counts.mixed);
+  if (counts.ko === best) return 'ko';
+  if (counts.latin === best) return 'latin';
+  return 'mixed';
+}
+
+export function mergeFindings(contributions, docsByPath) {
+  const groups = new Map();
+  for (const item of contributions) {
+    const base = {
+      severity: item.severity,
+      evidenceKind: item.evidenceKind ?? 'quoted',
+      citations: item.citations,
+      locatorState: item.locatorState ?? 'unlocated',
+    };
+    const identity = findingIdentity(base);
+    if (!groups.has(identity)) groups.set(identity, { identity, ...base, contributions: [] });
+    const g = groups.get(identity);
+    if (SEVERITY_RANK[item.severity] < SEVERITY_RANK[g.severity]) g.severity = item.severity;
+    const ref = referenceLanguage(item, docsByPath);
+    const lang = languageClass(item.explanation);
+    g.contributions.push({
+      role: item.role,
+      severity: item.severity,
+      explanation: item.explanation,
+      suggestion: item.suggestion ?? '',
+      languageMismatch: ref !== 'mixed' && lang !== 'mixed' && ref !== lang && item.explanation.replace(/\s/g, '').length >= 10,
+    });
+  }
+  const list = [...groups.values()];
+  const firstRole = (f) => Math.min(...f.contributions.map((c) => ROLE_ORDER.indexOf(c.role)).filter((n) => n >= 0));
+  const firstCitation = (f) => [...f.citations].sort((a, b) => a.document.localeCompare(b.document) || (a.lineStart ?? Infinity) - (b.lineStart ?? Infinity))[0];
+  list.sort((a, b) => {
+    const s = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
+    if (s) return s;
+    const r = firstRole(a) - firstRole(b);
+    if (r) return r;
+    const ca = firstCitation(a); const cb = firstCitation(b);
+    const d = String(ca?.document ?? '').localeCompare(String(cb?.document ?? ''));
+    if (d) return d;
+    const l = (ca?.lineStart ?? Number.MAX_SAFE_INTEGER) - (cb?.lineStart ?? Number.MAX_SAFE_INTEGER);
+    if (l) return l;
+    return a.identity.localeCompare(b.identity);
+  });
+  list.forEach((f, i) => {
+    f.id = `F-${String(i + 1).padStart(3, '0')}`;
+    f.contributions.sort((a, b) => (ROLE_ORDER.indexOf(a.role) - ROLE_ORDER.indexOf(b.role))
+      || SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity]
+      || a.explanation.localeCompare(b.explanation));
+    f.roles = ROLE_ORDER.filter((r) => f.contributions.some((c) => c.role === r));
+    delete f.identity;
+  });
+  return list;
+}
+
+export function countsFor(findings, reviewers) {
+  const locatedCitations = findings.reduce((n, f) => n + f.citations.filter((c) => c.status === 'located').length, 0);
+  const anchorCitations = findings.reduce((n, f) => n + f.citations.filter((c) => c.status === 'anchor_located').length, 0);
+  const ambiguousCitations = findings.reduce((n, f) => n + f.citations.filter((c) => c.status === 'ambiguous').length, 0);
+  const unlocatedCitations = findings.reduce((n, f) => n + f.citations.filter((c) => c.status === 'not_located').length, 0);
+  const bySeverity = { blocker: 0, major: 0, minor: 0 };
+  for (const f of findings) bySeverity[f.severity] += 1;
+  const byLocator = { located: 0, anchor_only: 0, ambiguous: 0, partial: 0, unlocated: 0 };
+  for (const f of findings) byLocator[f.locatorState] = (byLocator[f.locatorState] ?? 0) + 1;
+  return { locatedCitations, anchorCitations, ambiguousCitations, unlocatedCitations, findingsBySeverity: { ...bySeverity, total: findings.length }, findingsByLocatorState: byLocator, reviewers: reviewers.length };
+}