@portll/cobolwork 0.0.1 → 0.2.76

package/lib/diff.mjs

@@ -0,0 +1,344 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve, sep } from 'node:path';
+import { parseSource } from './parser.mjs';
+import { inScope, isProgram, readSource, relPath } from './sources.mjs';
+import { scanAll } from './scan.mjs';
+import { FLOW_MODEL, SCHEMA_VERSION, TOOL_VERSION } from './version.mjs';
+// A diff finding is located by program rather than by line, so it orders on its own key. The text
+// comparison underneath it is the shared one.
+import { byText, evidenceMap } from './kernel/findings.mjs';
+import { directoryTree } from './kernel/source-tree.mjs';
+import { printable } from './kernel/printable.mjs';
+import { loadSite, SITE_FILE } from './site.mjs';
+import { loadBaseline, BASELINE_FILE, SUPPRESSING } from './baseline.mjs';
+
+// What a change REACHES, not what it edits. A one-line copybook edit rewrites the record layout of
+// every program that COPYs it while leaving each of those programs' own source untouched, so a
+// reviewer reading the diff sees one file and ships forty. This compares the two trees the way the
+// compiler would see them: per program, every field's size and offset, every call and transfer
+// target, and every security finding.
+export const DIFF_RULES = {
+  'diff-interface-layout-changed': { sev: 'high', evidence: 'change', cwe: 'CWE-1284', text: 'A record this program passes to or receives from another program changed size or position' },
+  'diff-layout-changed-unedited-program': { sev: 'med', evidence: 'change', cwe: 'CWE-1284', text: 'Fields in this program changed size or position although its own source did not change' },
+  'diff-layout-changed': { sev: 'low', evidence: 'change', cwe: 'CWE-1284', text: 'Fields in this program changed size or position' },
+  'diff-new-dynamic-call': { sev: 'high', evidence: 'change', cwe: 'CWE-470', text: 'The change adds a call or transfer whose target is a variable' },
+  'diff-new-call-target': { sev: 'med', evidence: 'change', cwe: 'CWE-470', text: 'The change makes this program call or transfer to a program it did not before' },
+};
+
+const MAX_LISTED = 8;
+
+// A reviewed repository's .git/config can name commands; with fsmonitor off and plumbing only, git runs none.
+const GIT_ENV = { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0' };
+const git = (repo, args, opts = {}) => spawnSync('git', ['-c', 'core.fsmonitor=false', '-C', repo, ...args], { env: GIT_ENV, maxBuffer: 256 * 1024 * 1024, ...opts });
+const refused = (what, ref, why) => Object.assign(new Error(`${what} ${ref} failed: ${why}`), { code: 'EDIFFREF' });
+
+function treeOf(repo, ref) {
+  if (!ref || String(ref).startsWith('-')) throw refused('git rev-parse', ref, 'a revision cannot be empty or start with "-"');
+  const r = git(repo, ['rev-parse', '--verify', '--quiet', '--end-of-options', `${ref}^{tree}`], { encoding: 'utf8' });
+  const oid = String(r.stdout || '').trim();
+  if (r.status !== 0 || !/^[0-9a-f]{40}([0-9a-f]{24})?$/.test(oid)) throw refused('git rev-parse', ref, String(r.stderr || '').trim() || 'not a revision');
+  return oid;
+}
+
+// A tree path as a file under `dir`, or null if a part is empty, climbs, names a drive or stream, or is .git.
+function placeIn(dir, path) {
+  const parts = path.split('/');
+  if (parts.some((p) => !p || p === '.' || p === '..' || /[\\:\0]/.test(p) || p.toLowerCase() === '.git')) return null;
+  const to = resolve(dir, ...parts);
+  return to.startsWith(dir + sep) ? to : null;
+}
+
+// The revision as committed: blobs as stored, with no filter or line-ending conversion; links and submodules left out.
+function materialise(repo, ref) {
+  const tree = treeOf(repo, ref);
+  const listed = git(repo, ['ls-tree', '-r', '-z', '--full-tree', tree]);
+  if (listed.status !== 0) throw refused('git ls-tree', ref, String(listed.stderr || '').trim() || `exit ${listed.status}`);
+  const blobs = [];
+  for (const entry of listed.stdout.toString('utf8').split('\0')) {
+    const m = /^(\d{6}) blob ([0-9a-f]+)\t(.+)$/s.exec(entry);
+    if (m && m[1] !== '120000') blobs.push({ oid: m[2], path: m[3] });
+  }
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), 'cobolwork-diff-')));
+  try {
+    for (let i = 0; i < blobs.length; i += 500) {
+      const batch = blobs.slice(i, i + 500);
+      const r = git(repo, ['cat-file', '--batch'], { input: batch.map((b) => b.oid).join('\n') + '\n' });
+      if (r.status !== 0) throw refused('git cat-file', ref, String(r.stderr || '').trim() || `exit ${r.status}`);
+      let at = 0;
+      for (const b of batch) {
+        const nl = r.stdout.indexOf(0x0a, at);
+        const head = r.stdout.toString('utf8', at, nl).split(' ');
+        if (head[1] !== 'blob') throw refused('git cat-file', ref, `${b.oid} is ${head[1] || 'missing'}`);
+        const size = Number(head[2]);
+        const to = placeIn(dir, b.path);
+        if (to) {
+          mkdirSync(dirname(to), { recursive: true });
+          writeFileSync(to, r.stdout.subarray(nl + 1, nl + 1 + size));
+        }
+        at = nl + 1 + size + 1;
+      }
+    }
+  } catch (e) {
+    rmSync(dir, { recursive: true, force: true });
+    throw e;
+  }
+  return dir;
+}
+
+// Whether two revisions of one file say the same thing. Compared as raw bytes instead, a program
+// nobody edited reads as edited whenever the two sides were written under different line-ending
+// rules: on Windows git checks the base out through core.autocrlf as CRLF while the working tree
+// under review is already CRLF, or the reverse once a revision is materialised. Pinning the
+// checkout would only move the mismatch to the other side, so the comparison forgives the one
+// difference a checkout can introduce, and nothing else: whitespace a person actually typed
+// still counts as an edit, on every platform.
+const norm = (t) => t.split('\r\n').join('\n');
+const sameSource = (a, b) => norm(a) === norm(b);
+
+const qualified = (it) => { const names = []; for (let x = it; x; x = x.parent) names.unshift(x.name); return names.join('.'); };
+
+// A program that cannot be read or parsed is named in `unread`, never dropped: dropped, it would
+// read as removed from the tree, and every change inside it would go unreported.
+function facts(root, opts = {}) {
+  // Each side of a diff is its own tree: the base is a revision materialised into a temporary
+  // directory, the head is the working tree, and they are walked separately.
+  //
+  // This used to build its own parse options with systemDirs: [], where every other caller passed
+  // the caller's. Nobody decided that - it is what five copies of one object literal do. The
+  // consequence was that diff could not resolve a system copybook that scan could, so a layout
+  // change inside one was invisible to the command whose whole job is what a change reaches. Both
+  // sides now take the same configuration, which for a caller that passes no systemDirs is
+  // exactly the old behaviour.
+  const tree = directoryTree(root, opts);
+  const idx = tree.index;
+  const out = new Map();
+  out.unread = [];
+  for (const f of tree.list().filter(isProgram).filter(inScope(opts))) {
+    let src;
+    try { src = readSource(f).text; } catch (e) { out.unread.push(`${relPath(root, f)}: ${e.code || e.name}`); continue; }
+    if (!/PROCEDURE\s+DIVISION|PROGRAM-ID/i.test(src)) continue;
+    let r;
+    try {
+      r = tree.parse(f, src);
+    } catch (e) { out.unread.push(`${relPath(root, f)}: ${e.code || e.name}`); continue; }
+    const file = relPath(root, f);
+    for (const p of r.programs) {
+      const items = new Map();
+      for (const it of p.items) {
+        if (!it.name || it.name === 'FILLER' || it.level === 88 || it.level === 66 || it.level === 78) continue;
+        items.set(qualified(it), { size: it.size, offset: it.offset, from: it.file ? relPath(root, it.file) : file, section: it.section, level: it.level });
+      }
+      const calls = new Set();
+      const dynamic = new Set();
+      for (const c of p.calls) (c.kind === 'L' ? calls : dynamic).add(c.kind === 'L' ? String(c.name).toUpperCase() : `CALL ${c.name}`);
+      const commareas = new Set();
+      for (const e of p.execs) {
+        if (e.kind !== 'CICS') continue;
+        const words = e.toks.filter(t => t.t === 'word').map(t => t.u);
+        if (words[0] === 'RETURN') { const rc = e.toks.findIndex(t => t.t === 'word' && t.u === 'COMMAREA'); const ra = rc >= 0 ? e.toks.slice(rc + 1).find(t => t.t === 'word') : null; if (ra) commareas.add(ra.u); continue; }
+        if (!['LINK', 'XCTL', 'START'].includes(words[0])) continue;
+        const at = e.toks.findIndex(t => t.t === 'word' && (t.u === 'PROGRAM' || t.u === 'TRANSID'));
+        const target = at >= 0 ? e.toks.slice(at + 1).find(t => t.t === 'lit' || t.t === 'word') : null;
+        if (target && target.t === 'lit') calls.add(String(target.v).trim().toUpperCase());
+        else if (target) dynamic.add(`EXEC CICS ${words[0]} ${target.u}`);
+        const ca = e.toks.findIndex(t => t.t === 'word' && t.u === 'COMMAREA');
+        const arg = ca >= 0 ? e.toks.slice(ca + 1).find(t => t.t === 'word') : null;
+        if (arg) commareas.add(arg.u);
+      }
+      const using = new Set(p.calls.flatMap(c => c.using.filter(a => a.word).map(a => a.word)));
+      const copied = new Set(r.copies.filter((c) => c.status === 'resolved' && c.path).map((c) => relPath(root, c.path)));
+      out.set(`${file}#${p.id}`, { id: p.id, file, text: src, items, calls, dynamic, commareas, using, copied });
+    }
+  }
+  return out;
+}
+
+// The key a finding keeps across two trees: its fingerprint, which never includes its line. The
+// fallback, for a report stamped by nothing, is the coarser key this used before there was one:
+// under it, fixing one finding and adding another of the same rule in the same program read as no
+// change at all.
+const findingKey = (f) => f.fingerprint || [f.rule, f.path, f.program || '', f.name || ''].join('|');
+
+function countByKey(findings) {
+  const m = new Map();
+  for (const f of findings) m.set(findingKey(f), (m.get(findingKey(f)) || 0) + 1);
+  return m;
+}
+
+export function diffTrees(baseRoot, headRoot, opts = {}) {
+  // The allow list describes the working tree, so it never applies to a revision checked out into
+  // a temporary directory: applied there it would match nothing and the base would read as empty.
+  const baseOpts = { ...opts, allow: null };
+  const base = facts(baseRoot, baseOpts);
+  const head = facts(headRoot, opts);
+  const findings = [];
+  const reach = { programsCompared: 0, programsAdded: 0, programsRemoved: 0, programsWithLayoutChange: 0, reachedOnlyThroughCopybooks: 0, copybooksImplicated: new Set() };
+
+  for (const [key, h] of head) {
+    const b = base.get(key);
+    if (!b) { reach.programsAdded++; continue; }
+    reach.programsCompared++;
+    const changed = [];
+    for (const [name, now] of h.items) {
+      const was = b.items.get(name);
+      if (!was) continue;
+      if (was.size !== now.size || was.offset !== now.offset) changed.push({ name, was, now });
+    }
+    if (changed.length) {
+      reach.programsWithLayoutChange++;
+      const unedited = sameSource(b.text, h.text);
+      if (unedited) reach.reachedOnlyThroughCopybooks++;
+      for (const c of changed) if (c.now.from !== h.file) reach.copybooksImplicated.add(c.now.from);
+      // An interface record is one another program also reads: the linkage section, a CICS
+      // communication area, or an argument passed on a CALL. A size change there is a mismatch
+      // between two programs unless both were rebuilt against the same copybook.
+      // A field inside a record passed by name crosses the boundary too, so any segment of its
+      // qualified name counts, not only the record's own.
+      const passed = new Set([...h.commareas, ...h.using]);
+      const iface = changed.filter(c => c.now.section === 'LINKAGE' || c.name.split('.').some(seg => passed.has(seg)));
+      const rule = iface.length ? 'diff-interface-layout-changed' : unedited ? 'diff-layout-changed-unedited-program' : 'diff-layout-changed';
+      const listed = (iface.length ? iface : changed).slice(0, MAX_LISTED)
+        .map(c => `${c.name} ${c.was.size}→${c.now.size} bytes${c.was.offset !== c.now.offset ? ` at offset ${c.was.offset}→${c.now.offset}` : ''}${c.now.from !== h.file ? ` (from ${c.now.from})` : ''}`);
+      findings.push({ rule, path: h.file, line: 1, program: h.id,
+        detail: `${changed.length} field(s) changed${unedited ? ' although this program\'s source is unchanged' : ''}: ${listed.join('; ')}${changed.length > MAX_LISTED ? '; …' : ''}` });
+    }
+    for (const d of h.dynamic) if (!b.dynamic.has(d)) findings.push({ rule: 'diff-new-dynamic-call', path: h.file, line: 1, program: h.id, detail: `${d} is new in this change` });
+    const added = [...h.calls].filter(c => !b.calls.has(c));
+    if (added.length) findings.push({ rule: 'diff-new-call-target', path: h.file, line: 1, program: h.id, detail: `now calls or transfers to ${added.sort().join(', ')}` });
+  }
+  const unreadHead = new Set(head.unread.map(u => u.split(': ')[0]));
+  for (const [key, b] of base) if (!head.has(key) && !unreadHead.has(b.file)) reach.programsRemoved++;
+
+  const listing = { listSinks: opts.listSinks === true, listSources: opts.listSources === true };
+  const shared = { only: opts.only, fullTrace: opts.fullTrace, systemDirs: opts.systemDirs || [], ...listing };
+  const before = scanAll(baseRoot, shared);
+  const after = scanAll(headRoot, { ...shared, allow: opts.allow });
+  // A file neither tree could read cannot be compared. Its findings are neither introduced nor
+  // resolved, and calling them resolved would report a scan failure as a fix.
+  const unreadable = new Set([...base.unread, ...head.unread].map(u => u.split(': ')[0]));
+  const comparable = (f) => !unreadable.has(f.path);
+  const beforeCounts = countByKey(before.findings.filter(comparable));
+  const afterCounts = countByKey(after.findings.filter(comparable));
+  const seenIntroduced = new Map();
+  const introduced = after.findings.filter(comparable).filter((f) => {
+    const k = findingKey(f);
+    const n = (seenIntroduced.get(k) || 0) + 1;
+    seenIntroduced.set(k, n);
+    return n > (beforeCounts.get(k) || 0);
+  });
+  const seenResolved = new Map();
+  const resolved = before.findings.filter(comparable).filter((f) => {
+    const k = findingKey(f);
+    const n = (seenResolved.get(k) || 0) + 1;
+    seenResolved.set(k, n);
+    return n > (afterCounts.get(k) || 0);
+  });
+  const uncomparable = [...new Set([...before.findings, ...after.findings].filter(f => !comparable(f)).map(f => f.path))];
+  const configurationChanged = configurationChanges(baseRoot, headRoot);
+
+  for (const f of findings) { const m = DIFF_RULES[f.rule]; f.sev = m.sev; f.cwe = m.cwe; f.evidence = m.evidence; }
+  findings.sort((a, b) => byText(a.rule, b.rule) || byText(a.path, b.path) || byText(String(a.program), String(b.program)));
+  const byRule = {};
+  for (const f of findings) byRule[f.rule] = (byRule[f.rule] || 0) + 1;
+  const res = {
+    tool: 'cobolwork-diff',
+    schemaVersion: SCHEMA_VERSION,
+    summary: {
+      flowModel: FLOW_MODEL,
+      toolVersion: TOOL_VERSION,
+      findings: findings.length, byRule,
+      introduced: introduced.length, resolved: resolved.length,
+      ...reach, copybooksImplicated: [...reach.copybooksImplicated].sort(),
+      unread: { base: base.unread, head: head.unread, findingsNotCompared: uncomparable },
+      ...(configurationChanged.length ? { configurationChanged } : {}),
+      coverageIncomplete: !!(before.summary.coverageIncomplete || after.summary.coverageIncomplete || base.unread.length || head.unread.length),
+      nosrc: head.size === 0 && base.size === 0,
+    },
+    findings,
+    introduced,
+    resolved,
+    ruleText: Object.fromEntries(Object.entries(DIFF_RULES).map(([k, v]) => [k, v.text])),
+    ruleEvidence: evidenceMap(DIFF_RULES),
+  };
+  // Both scans and both sides' programs, for a caller that judges the change; never printed.
+  if (opts.keepScans) Object.defineProperty(res, 'scans', { value: { before, after, base, head }, enumerable: false });
+  return res;
+}
+
+// Site-file and baseline changes, which move findings between introduced and resolved with no source changed.
+const SITE_LISTS = ['productionQualifiers', 'productionJobPaths', 'nonProductionJobPaths', 'systemNames', 'vendorPacks',
+  'internalReaderDds', 'internalReaderQueues', 'compilerOptions', 'apfLibraries', 'restrictedDatasets', 'surrogateUsers'];
+
+function siteChange(baseRoot, headRoot) {
+  const was = existsSync(join(baseRoot, SITE_FILE));
+  const now = existsSync(join(headRoot, SITE_FILE));
+  if (!was && !now) return null;
+  if (!now) return { file: SITE_FILE, change: 'removed, so the rules that need it do not run' };
+  const b = loadSite(baseRoot);
+  const h = loadSite(headRoot);
+  const parts = was ? [] : ['added'];
+  for (const k of SITE_LISTS) {
+    const gone = b[k].filter((x) => !h[k].includes(x)).map((x) => `-${x}`);
+    const came = h[k].filter((x) => !b[k].includes(x)).map((x) => `+${x}`);
+    if (gone.length || came.length) parts.push(`${k} ${[...gone, ...came].join(' ')}`);
+  }
+  if (b.allowUnvalidatedPacks !== h.allowUnvalidatedPacks) parts.push(`allowUnvalidatedPacks ${h.allowUnvalidatedPacks}`);
+  if (JSON.stringify(b.runtimeVersions) !== JSON.stringify(h.runtimeVersions)) parts.push('runtimeVersions');
+  if (h.problems.length && h.problems.join() !== b.problems.join()) parts.push(`now reports: ${h.problems[0]}`);
+  return parts.length ? { file: SITE_FILE, change: printable(parts.join('; '), 400) } : null;
+}
+
+export const configurationChanges = (baseRoot, headRoot) =>
+  [siteChange(baseRoot, headRoot), baselineChange(baseRoot, headRoot)].filter(Boolean);
+
+function baselineChange(baseRoot, headRoot) {
+  const was = existsSync(join(baseRoot, BASELINE_FILE));
+  const now = existsSync(join(headRoot, BASELINE_FILE));
+  if (!was && !now) return null;
+  const held = (root, there) => new Map((there ? loadBaseline(root)?.entries || [] : []).map((e) => [`${e.fingerprint}|${e.rule}`, e]));
+  const b = held(baseRoot, was);
+  const h = held(headRoot, now);
+  const added = [...h.keys()].filter((k) => !b.has(k));
+  const suppressing = added.filter((k) => SUPPRESSING.includes(h.get(k).action)).length;
+  const removed = [...b.keys()].filter((k) => !h.has(k)).length;
+  const changed = [...h.keys()].filter((k) => b.has(k) && JSON.stringify(b.get(k)) !== JSON.stringify(h.get(k))).length;
+  if (!added.length && !removed && !changed && was === now) return null;
+  return { file: BASELINE_FILE, change: `${was ? (now ? 'edited' : 'removed') : 'added'}: ${added.length} entr${added.length === 1 ? 'y' : 'ies'} added, ${suppressing} of them suppressing; ${removed} removed; ${changed} changed` };
+}
+
+// The files git would show in a commit: tracked, plus untracked ones that are not ignored. A
+// working tree also holds build output and vendored copies that no revision contains, and comparing
+// those against a revision reports a change in a file nobody changed.
+function gitScope(repo) {
+  const r = git(repo, ['ls-files', '--cached', '--others', '--exclude-standard', '-z'], { encoding: 'utf8' });
+  if (r.status !== 0) throw Object.assign(new Error(`git ls-files failed: ${String(r.stderr || '').trim()}`), { code: 'EDIFFREF' });
+  return new Set(r.stdout.split('\0').filter(Boolean).map(p => resolve(repo, p)));
+}
+
+export const WORKING_TREE = 'working tree, tracked and untracked files git does not ignore';
+
+// Calls fn(baseDir, headDir, opts) with both revisions on disk, the head being the working tree when
+// headRef is null, and removes what it materialised however fn ends.
+export function withRefs(repo, baseRef, headRef, opts, fn) {
+  const baseDir = materialise(repo, baseRef);
+  let headDir = null;
+  try {
+    headDir = headRef ? materialise(repo, headRef) : repo;
+    return fn(baseDir, headDir, headRef ? opts : { ...opts, allow: gitScope(repo) });
+  } finally {
+    rmSync(baseDir, { recursive: true, force: true });
+    if (headRef && headDir) rmSync(headDir, { recursive: true, force: true });
+  }
+}
+
+export function diffRefs(repo, baseRef, headRef = null, opts = {}) {
+  return withRefs(repo, baseRef, headRef, opts, (baseDir, headDir, scoped) => {
+    const res = diffTrees(baseDir, headDir, scoped);
+    res.summary.base = baseRef;
+    res.summary.head = headRef || WORKING_TREE;
+    return res;
+  });
+}

package/lib/explain.mjs

@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { resolve, relative, sep, dirname } from 'node:path';
+import { realpathSync } from 'node:fs';
+import { readSource, isProgram, isCopybook, isJcl } from './sources.mjs';
+import { parseFile, buildFileIndex, detectFormat } from './parser.mjs';
+import { EVIDENCE } from './kernel/findings.mjs';
+import { REGISTRY } from './kernel/registry.mjs';
+import { WHO_ACTS } from './tui/model.mjs';
+
+const HIDDEN_RULES = new Set(Object.keys(REGISTRY.find((s) => s.name === 'hidden').rules));
+
+// The columns quoted: COBOL's indicator and program text, JCL's statement field, or the whole line.
+function codeArea(line, kind, format) {
+  if (kind === 'cobol' && format === 'fixed') return { text: line.slice(6, 72), seq: line.slice(0, 6), rest: line.slice(72) };
+  if (kind === 'cobol' && format === 'variable') return { text: line.slice(6, 250), seq: line.slice(0, 6), rest: line.slice(250) };
+  if (kind === 'jcl') return { text: line.slice(0, 72), seq: '', rest: line.slice(72) };
+  return { text: line, seq: '', rest: '' };
+}
+
+const NOTE = 'This packet contains source text from the files it names. A cobolwork report never does: '
+  + 'treat the packet as you would the source, and do not store or send it where the source may not go.';
+
+function contained(root, rel) {
+  const base = resolve(root);
+  const abs = resolve(base, rel);
+  if (abs !== base && !abs.startsWith(base + sep)) return { why: 'the path resolves outside the root' };
+  let real;
+  try { real = realpathSync(abs); } catch { return { why: 'the file is not there' }; }
+  const realBase = realpathSync(base);
+  if (real !== realBase && !real.startsWith(realBase + sep)) return { why: 'the path is a link that leads outside the root' };
+  return { abs };
+}
+
+// A hop's location: from `via` ("MOVE at pos/P1.cbl:9"), else the related entry for its file.
+function hopAt(hop, finding) {
+  const m = /\bat (.+):(\d+)$/.exec(hop.via || '');
+  if (m) return { path: m[1], line: Number(m[2]) };
+  const rel = (finding.related || []).find((r) => r.path === hop.file);
+  return rel ? { path: rel.path, line: rel.line } : { path: hop.file, line: null };
+}
+
+export function explainFinding(report, fingerprint, { root }) {
+  const active = report.findings.filter((f) => f.fingerprint === fingerprint);
+  // A baseline moves a judged finding out of `findings` into `suppressed`. Explain still reaches it,
+  // and the packet carries the judgement rather than showing it as live.
+  const matches = active.length ? active : (report.suppressed || []).filter((f) => f.fingerprint === fingerprint);
+  if (!matches.length) return null;
+  const f = matches[0];
+  const files = new Map();
+  const unread = [];
+  const kindOf = (abs) => (isJcl(abs) ? 'jcl' : isProgram(abs) || isCopybook(abs) ? 'cobol' : null);
+  const fileOf = (path) => {
+    if (!path) return null;
+    if (files.has(path)) return files.get(path);
+    const c = contained(root, path);
+    let file = null;
+    if (!c.abs) unread.push({ path, why: c.why });
+    else if (!kindOf(c.abs)) unread.push({ path, why: 'not a source file cobolwork reads' });
+    else {
+      try {
+        const text = readSource(c.abs).text;
+        file = { kind: kindOf(c.abs), format: detectFormat(text), lines: text.split(/\r?\n/) };
+      } catch (e) { unread.push({ path, why: `it could not be read: ${e.message}` }); }
+    }
+    files.set(path, file);
+    return file;
+  };
+  const flagged = new Map();
+  for (const x of [...report.findings, ...(report.suppressed || [])]) {
+    if (HIDDEN_RULES.has(x.rule) && x.path && x.line) flagged.set(`${x.path}:${x.line}`, x.rule);
+  }
+  const quote = (path, line) => {
+    const withheld = flagged.get(`${path}:${line}`);
+    if (withheld) return { code: null, withheld };
+    const file = fileOf(path);
+    if (!file || !(line > 0 && line <= file.lines.length)) return { code: null };
+    const area = codeArea(file.lines[line - 1], file.kind, file.format);
+    const dropped = area.rest.trim() !== '' || /[^\d\s]/.test(area.seq);
+    return { code: area.text.trimEnd(), ...(dropped ? { dropped } : {}) };
+  };
+
+  const hops = (f.trace || []).map((h, i) => {
+    if (h.elided) return { n: i + 1, elided: h.elided, via: h.via };
+    const at = hopAt(h, f);
+    return { n: i + 1, program: h.program, item: h.item, file: h.file, via: h.via, path: at.path, line: at.line, ...quote(at.path, at.line) };
+  });
+
+  const parsed = new Map();
+  let index = null;
+  const programIn = (file, id) => {
+    if (!parsed.has(file)) {
+      const c = contained(root, file);
+      let r = null;
+      if (c.abs && kindOf(c.abs) === 'cobol') {
+        index ??= buildFileIndex(resolve(root));
+        try {
+          r = parseFile(c.abs, { format: 'auto', copyFormat: 'auto', fileIndex: index.index, includeDirs: index.copyDirs, mainDir: dirname(c.abs) });
+        } catch { r = null; }
+      }
+      parsed.set(file, r);
+    }
+    const r = parsed.get(file);
+    return r && r.programs.find((p) => String(p.id).toUpperCase() === String(id).toUpperCase());
+  };
+  const declarations = [];
+  const seen = new Set();
+  const subjects = [...hops.filter((h) => h.item), ...(f.guard ? [{ program: f.guard.program, item: f.guard.item, file: f.guard.file }] : [])];
+  for (const h of subjects) {
+    const key = `${h.program}.${h.item}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const p = programIn(h.file, h.program);
+    const it = p && p.items.find((x) => String(x.name).toUpperCase() === String(h.item).toUpperCase());
+    if (!it) continue;
+    declarations.push({
+      program: h.program, item: h.item, level: it.level, picture: it.picture, usage: it.usage, size: it.size,
+      offset: it.offset, section: it.section, occurs: it.occurs, redefines: it.redefines,
+      path: it.file ? relative(resolve(root), resolve(it.file)).split(sep).join('/') : h.file,
+      line: it.line,
+    });
+  }
+
+  return {
+    tool: 'cobolwork-explain',
+    carriesSource: true,
+    note: NOTE,
+    fingerprint,
+    shared: matches.length,
+    ...(f.suppressed ? { suppressed: f.suppressed } : {}),
+    finding: {
+      rule: f.rule, sev: f.sev, ...(f.guardedFrom ? { guardedFrom: f.guardedFrom } : {}), cwe: f.cwe,
+      evidence: f.evidence, claim: EVIDENCE[f.evidence] || null, whoActs: WHO_ACTS[f.evidence] || null,
+      // What the finding lets someone do and the standard fix, from the finding if it carries its
+      // own (a site-gated rule that became a defect), else the rule's, else null for an info kind.
+      impact: f.impact ?? report.ruleImpact?.[f.rule] ?? null, remedy: f.remedy ?? report.ruleRemedy?.[f.rule] ?? null,
+      program: f.program, path: f.path, line: f.line, crossProgram: !!f.crossProgram, detail: f.detail,
+    },
+    hops,
+    sink: { path: f.path, line: f.line, ...quote(f.path, f.line) },
+    guard: f.guard ? { ...f.guard, ...quote(f.guard.file, f.guard.line) } : null,
+    related: (f.related || []).map((r) => ({ ...r, ...quote(r.path, r.line) })),
+    declarations,
+    unread,
+  };
+}