@portll/cobolwork 0.0.1 → 0.2.75

package/lib/revision.json

@@ -0,0 +1 @@
+{"commit":"b74e3baeadbf548f73f45b0de0212b0579793d3c","tag":"v0.2.75"}

package/lib/revision.mjs

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Which commit a report was made by, and which commit it read: summary.toolRevision and
+// summary.revision, each { commit, dirty }. A scanned repository is untrusted, and its .git/config
+// can name commands that porcelain runs - `git status` runs clean filters and fsmonitor - so only
+// plumbing that lists objects and files runs here, and whether the tree differs from HEAD is decided
+// by hashing its files in process.
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { existsSync, lstatSync, readFileSync, readlinkSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const GIT_ENV = { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0' };
+const git = (dir, args) => spawnSync('git', ['-c', 'core.fsmonitor=false', '-C', dir, ...args], { env: GIT_ENV, maxBuffer: 256 << 20 });
+// Past this many tracked files the comparison is not made, and dirty is null rather than a guess.
+const MAX_TRACKED = 50000;
+
+const nulSplit = (buf) => buf.toString('utf8').split('\0').filter(Boolean);
+
+// The object id git would give these bytes as a blob.
+const blobId = (bytes, format) => createHash(format).update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+
+// { commit, dirty } for the repository `dir` is in, over `paths` under it when given, or null
+// outside a repository. dirty is true when a tracked file under `dir` differs from HEAD or is gone,
+// or a file git does not ignore is untracked; null when there were too many files to compare. A
+// checkout that converts line endings reads as dirty, which errs the safe way.
+export function revisionOf(dir, { paths = [] } = {}) {
+  const head = git(dir, ['rev-parse', '--verify', '-q', 'HEAD']);
+  if (head.status !== 0) return null;
+  const commit = head.stdout.toString().trim();
+  const fmt = git(dir, ['rev-parse', '--show-object-format']);
+  const format = fmt.status === 0 && fmt.stdout.toString().trim() === 'sha256' ? 'sha256' : 'sha1';
+  const scope = paths.length ? ['--', ...paths] : [];
+  const listed = git(dir, ['ls-tree', '-r', '-z', 'HEAD', ...scope]);
+  if (listed.status !== 0) return { commit, dirty: null };
+  const entries = nulSplit(listed.stdout);
+  if (entries.length > MAX_TRACKED) return { commit, dirty: null };
+  for (const entry of entries) {
+    const tab = entry.indexOf('\t');
+    const [mode, type, id] = entry.slice(0, tab).split(' ');
+    const rel = entry.slice(tab + 1);
+    if (type !== 'blob') continue;
+    const file = join(dir, rel);
+    let st;
+    try { st = lstatSync(file); } catch { return { commit, dirty: true }; }
+    const bytes = mode === '120000'
+      ? (st.isSymbolicLink() ? Buffer.from(readlinkSync(file)) : null)
+      : (st.isFile() ? readFileSync(file) : null);
+    if (!bytes || blobId(bytes, format) !== id) return { commit, dirty: true };
+  }
+  const untracked = git(dir, ['ls-files', '-z', '--others', '--exclude-standard', ...scope]);
+  if (untracked.status !== 0) return { commit, dirty: null };
+  return { commit, dirty: nulSplit(untracked.stdout).length > 0 };
+}
+
+// { commit, dirty: false } for a named revision, which is a commit and nothing on disk; null if it
+// does not resolve.
+export function commitAt(dir, ref) {
+  if (!ref || String(ref).startsWith('-')) return null;
+  const r = git(dir, ['rev-parse', '--verify', '-q', `${ref}^{commit}`]);
+  return r.status === 0 ? { commit: r.stdout.toString().trim(), dirty: false } : null;
+}
+
+const PACKAGE_ROOT = fileURLToPath(new URL('..', import.meta.url));
+// What decides a report: the code, the rules it loads and the schemas it names.
+export const SHIPPED = ['bin', 'lib', 'rules', 'schema', 'package.json'];
+export const PACKED_REVISION = join(PACKAGE_ROOT, 'lib', 'revision.json');
+
+// Whether this cobolwork is its own checkout, not a package installed somewhere inside another
+// repository, whose HEAD would say nothing about this code.
+function isOwnCheckout() {
+  const top = git(PACKAGE_ROOT, ['rev-parse', '--show-toplevel']);
+  if (top.status !== 0) return false;
+  try { return realpathSync(top.stdout.toString().trim()) === realpathSync(PACKAGE_ROOT); } catch { return false; }
+}
+
+// The revision this cobolwork runs from: read from the checkout it runs in, over the files that
+// decide what it reports, or stamped into a packed release by diag/stamp-revision.mjs.
+export function toolRevision() {
+  if (isOwnCheckout()) {
+    const r = revisionOf(PACKAGE_ROOT, { paths: SHIPPED });
+    return r ? { ...r, from: 'checkout' } : null;
+  }
+  if (!existsSync(PACKED_REVISION)) return null;
+  try {
+    const r = JSON.parse(readFileSync(PACKED_REVISION, 'utf8'));
+    return { commit: r.commit, dirty: false, ...(r.tag ? { tag: r.tag } : {}), from: 'release' };
+  } catch { return null; }
+}

package/lib/sarif.mjs

@@ -0,0 +1,222 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// The report as SARIF 2.1.0.
+//
+// SARIF already models nearly everything this project invented separately, and this file used to
+// translate rather than project. Three corrections:
+//
+//   a rule set is a toolComponent. SARIF has first-class support for a tool made of several
+//   components - `tool.driver` plus `tool.extensions[]` - each with its own rules and its own
+//   notifications. That is exactly what a cobolwork rule set is, and modelling it means a consumer
+//   can tell which analysis produced a result without parsing its id.
+//
+//   files nobody read are notifications. `invocations[].toolExecutionNotifications` is the
+//   standard place for "the tool could not read these", and it is where the sentence lib/memory.mjs
+//   composes belongs. It used to go into a property bag no SARIF consumer reads.
+//
+//   a set that could not run is a configuration notification. `toolConfigurationNotifications`
+//   says the tool was not told enough, which is a different claim from having read less than it
+//   meant to, and the two call for different actions from different people.
+//
+// What SARIF cannot say is coverage as a ratio with a denominator: "read 8,000 of 12,000, stopped
+// on a memory reserve". That quadruple travels in a namespaced property bag. It does NOT travel
+// there alone: `coverageIncomplete` is this project's distinguishing promise - a finding count over
+// source nobody read is not a clean result - so the verdict stays where nobody can miss it, in
+// `executionSuccessful` and as a flat property, and the property bag carries the detail.
+import { REGISTRY, ALL_RULES } from './kernel/registry.mjs';
+import { stoppedBecause } from './kernel/memory.mjs';
+import { FINGERPRINT_VERSION } from './kernel/identity.mjs';
+import { DIFF_RULES } from './diff.mjs';
+
+const LEVEL = { crit: 'error', high: 'error', med: 'warning', low: 'note', info: 'note' };
+
+// Locations are URI references: each segment is encoded, lone surrogates from Windows names replaced first.
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+const uriOf = (p) => String(p).split('/').map((seg) => encodeURIComponent(seg.replace(LONE_SURROGATE, '\uFFFD'))).join('/');
+// Square brackets in a SARIF message are link syntax, and a finding's text can quote the tree.
+const textOf = (s) => (typeof s === 'string' ? s.replace(/[[\]]/g, '\\$&') : s);
+// SARIF's three levels fold critical into high and info into low, so the severity also travels as
+// the number GitHub code scanning ranks by. Info is coverage and context, which rank as nothing.
+const SECURITY_SEVERITY = { crit: '9.5', high: '8.0', med: '5.5', low: '3.0' };
+const DECLARED = new Map([...Object.entries(ALL_RULES), ...Object.entries(DIFF_RULES)].map(([id, r]) => [id, r.sev]));
+
+// Which rule set declares each rule. Rules with no set - diff's, and the credential pack's - stay
+// on the driver, because they are not produced by a rule set.
+const SET_OF = new Map();
+for (const s of REGISTRY) for (const id of Object.keys(s.rules)) SET_OF.set(id, s.name);
+
+// SARIF's level cannot say what kind of claim a result is, so evidence rides in the property bags.
+const descriptorFor = (report) => (id) => {
+  const properties = {
+    ...(report.ruleCwe?.[id] ? { cwe: report.ruleCwe[id] } : {}),
+    ...(report.ruleEvidence?.[id] ? { evidence: report.ruleEvidence[id] } : {}),
+    ...(SECURITY_SEVERITY[DECLARED.get(id)] ? { 'security-severity': SECURITY_SEVERITY[DECLARED.get(id)] } : {}),
+  };
+  return {
+    id,
+    shortDescription: { text: report.ruleText?.[id] || id },
+    // What the construct lets someone do, and the standard fix - the same for every result of the
+    // rule. `help` is where GitHub code scanning shows a recommendation.
+    ...(report.ruleImpact?.[id] ? { fullDescription: { text: textOf(report.ruleImpact[id]) } } : {}),
+    ...(report.ruleRemedy?.[id] ? { help: { text: textOf(report.ruleRemedy[id]) } } : {}),
+    ...(Object.keys(properties).length ? { properties } : {}),
+  };
+};
+
+function notifications(report) {
+  const bySet = report.summary?.bySet || {};
+  const execution = [];
+  const configuration = [];
+
+  for (const [set, s] of Object.entries(bySet)) {
+    const shortfall = (s.filesNotRead || 0) + (s.filesUnreadable || 0) + (s.filesUnparsed || 0);
+    if (!shortfall) continue;
+    execution.push({
+      descriptor: { id: 'cobolwork/files-not-read' },
+      level: 'warning',
+      message: {
+        text: s.notRead
+          || `${set}: ${shortfall} file(s) did not contribute to this run`
+            + (s.stoppedBy ? `, because ${stoppedBecause(s.stoppedBy)}` : ''),
+      },
+      properties: {
+        set,
+        ...(s.filesNotRead ? { filesNotRead: s.filesNotRead } : {}),
+        ...(s.filesUnreadable ? { filesUnreadable: s.filesUnreadable } : {}),
+        ...(s.filesUnparsed ? { filesUnparsed: s.filesUnparsed } : {}),
+        ...(s.stoppedBy ? { stoppedBy: s.stoppedBy } : {}),
+        ...(s.unreadable?.length ? { unreadable: s.unreadable } : {}),
+        ...(s.unparsed?.length ? { unparsed: s.unparsed } : {}),
+      },
+    });
+  }
+
+  // A set that could not run at all, as distinct from one that ran and read less than the tree.
+  const named = new Set(execution.map((n) => n.properties.set));
+  for (const { set, kind, why } of report.summary?.setsIncomplete || []) {
+    if (named.has(set)) continue;
+    if (kind === 'coverage') {
+      execution.push({
+        descriptor: { id: 'cobolwork/read-in-part' },
+        level: 'warning',
+        message: { text: textOf(`${set}: ${why}`) },
+        properties: { set },
+      });
+      continue;
+    }
+    configuration.push({
+      descriptor: { id: 'cobolwork/rule-set-did-not-run' },
+      level: 'warning',
+      message: { text: textOf(`${set}: ${why}`) },
+      properties: { set },
+    });
+  }
+  // A diff whose two sides were scanned under different configuration.
+  for (const { file, change } of report.summary?.configurationChanged || []) {
+    configuration.push({
+      descriptor: { id: 'cobolwork/configuration-changed' },
+      level: 'warning',
+      message: { text: textOf(`${file} ${change}`) },
+      properties: { file },
+    });
+  }
+  return { execution, configuration };
+}
+
+export function toSarif(report, { toolVersion = '0.1.0' } = {}) {
+  const describe = descriptorFor(report);
+  // A suppressed finding is still a result, marked as one a person judged, so its rule is described.
+  const suppressed = report.suppressed || [];
+  const present = [...new Set([...report.findings, ...suppressed].map((f) => f.rule))].sort();
+
+  // One component per rule set that produced anything, in registry order so two runs of the same
+  // tree compare.
+  const sets = REGISTRY.map((s) => s.name).filter((name) => present.some((id) => SET_OF.get(id) === name));
+  const extensions = sets.map((name) => ({
+    name: `cobolwork-${name}`,
+    version: toolVersion,
+    rules: present.filter((id) => SET_OF.get(id) === name).map(describe),
+  }));
+  const indexOfSet = new Map(sets.map((name, i) => [name, i]));
+
+  // Anything no rule set declares belongs to the driver: diff's rules, and the credential pack's.
+  const driverRules = present.filter((id) => !SET_OF.has(id)).map(describe);
+
+  const { execution, configuration } = notifications(report);
+  const s = report.summary || {};
+
+  return {
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    version: '2.1.0',
+    runs: [{
+      tool: {
+        driver: {
+          name: 'cobolwork',
+          version: toolVersion,
+          informationUri: 'https://github.com/Portll/cobolwork',
+          rules: driverRules,
+        },
+        ...(extensions.length ? { extensions } : {}),
+      },
+      invocations: [{
+        // The verdict, where a consumer that reads nothing else will still see it.
+        executionSuccessful: s.nosrc !== true,
+        exitCode: 0,
+        ...(execution.length ? { toolExecutionNotifications: execution } : {}),
+        ...(configuration.length ? { toolConfigurationNotifications: configuration } : {}),
+        properties: {
+          ...(s.filesScanned === undefined ? {} : { filesScanned: s.filesScanned }),
+          ...(s.coverageIncomplete === undefined ? {} : { coverageIncomplete: s.coverageIncomplete }),
+          ...(s.copiesMissing ? { copiesMissing: s.copiesMissing } : {}),
+          ...(s.filesUnreadable ? { filesUnreadable: s.filesUnreadable } : {}),
+          ...(s.advisoryFeeds ? { 'cobolwork/advisoryFeeds': s.advisoryFeeds } : {}),
+          ...(s.advisoryCoverage ? { 'cobolwork/advisoryCoverage': s.advisoryCoverage } : {}),
+          ...(s.toolRevision !== undefined ? { 'cobolwork/toolRevision': s.toolRevision } : {}),
+          ...(s.revision !== undefined ? { 'cobolwork/revision': s.revision } : {}),
+          // The part SARIF has no vocabulary for. Namespaced so it cannot be mistaken for
+          // standard fields, and documented in schema/cobolwork-coverage.schema.json.
+          'cobolwork/coverage': {
+            coverageIncomplete: s.coverageIncomplete === true,
+            filesScanned: s.filesScanned ?? null,
+            ...(s.bySet ? { bySet: s.bySet } : {}),
+            ...(s.setsIncomplete?.length ? { setsIncomplete: s.setsIncomplete } : {}),
+          },
+        },
+      }],
+      results: [...report.findings, ...suppressed].map((f) => {
+        const set = SET_OF.get(f.rule);
+        const component = set !== undefined ? indexOfSet.get(set) : undefined;
+        const within = component === undefined ? null : extensions[component].rules.findIndex((r) => r.id === f.rule);
+        return {
+          ruleId: f.rule,
+          // Which component declares this rule. A consumer that resolves ruleId against the driver
+          // still works; one that follows the reference learns which analysis produced the result.
+          ...(within != null && within >= 0
+            ? { rule: { id: f.rule, index: within, toolComponent: { index: component } } }
+            : {}),
+          level: LEVEL[f.sev] || 'warning',
+          message: { text: textOf(f.detail) },
+          // The whole identity, computed by the tool, so it is both the fingerprint and the one
+          // partial fingerprint a result-management system needs to track it.
+          ...(f.fingerprint ? {
+            fingerprints: { [FINGERPRINT_VERSION]: f.fingerprint },
+            partialFingerprints: { [FINGERPRINT_VERSION]: f.fingerprint },
+          } : {}),
+          // Per result: an info pack rule is context under a rule id that is a construct, and a
+          // checked path is a step below what its rule declares.
+          ...(f.evidence || f.sev ? { properties: {
+            ...(f.evidence ? { evidence: f.evidence } : {}),
+            ...(f.sev ? { severity: f.sev } : {}),
+            ...(SECURITY_SEVERITY[f.sev] ? { 'security-severity': SECURITY_SEVERITY[f.sev] } : {}),
+            ...(f.guard ? { guard: f.guard, guardedFrom: f.guardedFrom } : {}),
+            // Who can drive the finding and what it runs as, when the estate declared the facts.
+            ...(f.reach ? { reach: f.reach } : {}),
+            ...(f.effect ? { effect: f.effect } : {}),
+          } } : {}),
+          locations: [{ physicalLocation: { artifactLocation: { uri: uriOf(f.path), uriBaseId: '%SRCROOT%' }, region: { startLine: f.line || 1 } } }],
+          ...(f.related ? { relatedLocations: f.related.map((r) => ({ physicalLocation: { artifactLocation: { uri: uriOf(r.path), uriBaseId: '%SRCROOT%' }, region: { startLine: r.line || 1 } }, message: { text: textOf(r.detail) } })) } : {}),
+          ...(f.suppressed ? { suppressions: [{ kind: 'external', status: 'accepted', justification: `${f.suppressed.action} by ${f.suppressed.who} until ${f.suppressed.expires}: ${f.suppressed.reason}` }] } : {}),
+        };
+      }),
+    }],
+  };
+}

package/lib/scan.mjs

@@ -0,0 +1,272 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { join } from 'node:path';
+import { sortFindings, tally, evidenceMap, EVIDENCE } from './kernel/findings.mjs';
+import { directoryTree } from './kernel/source-tree.mjs';
+import { REGISTRY, RULE_SETS, ALL_RULES, reportKey } from './kernel/registry.mjs';
+import { inventory } from './inventory.mjs';
+import { stoppedBecause } from './kernel/memory.mjs';
+import { complianceMap, FRAMEWORKS_LOADED, FRAMEWORKS_UNLOADED } from './compliance.mjs';
+import { stampFingerprints, FINGERPRINT_VERSION } from './kernel/identity.mjs';
+import { report } from './kernel/ruleset.mjs';
+import { printable } from './kernel/printable.mjs';
+import { rollup } from './sets/flow.mjs';
+import { loadSite } from './site.mjs';
+import { reachFeedPaths, loadReachFeed, reachResolver, stampReach, stampEffect } from './reach.mjs';
+
+import { FLOW_MODEL, SCHEMA_VERSION, TOOL_VERSION } from './version.mjs';
+
+export { SCHEMA_VERSION };
+
+export { ALL_RULES, RULE_SETS };
+
+// One report for every rule set, in the shape a consumer can read without knowing which set a
+// finding came from. filesScanned and coverageIncomplete travel with it: a scan of a tree whose
+// copybooks are missing has read less than it appears to have read, and must say so.
+// With several repositories, each is scanned on its own and the reports are merged: program and
+// copybook names are only unique within a repository, so one graph over all of them would link a
+// CALL in one to a same-named program in another and report copybooks in different repositories as
+// shadowing each other.
+// The repository prefix is joined the same way every other report path is built: with a forward
+// slash. path.join would use the platform separator here and rewrite the separators already in the
+// path, so one file would print two ways depending on whether --repos was passed.
+const underRepo = (repo, p) => (repo ? `${repo}/${p}` : p);
+
+// Frameworks that did not load; a reason can quote the unparsed file.
+const COMPLIANCE_UNLOADED = FRAMEWORKS_UNLOADED.map((f) => ({ id: f.id, why: printable(f.why) }));
+
+function scanEach(root, opts) {
+  const reports = opts.repos.map(repo => ({ repo, r: scanAll(join(root, repo), { ...opts, repos: null, repoName: repo }) }));
+  const findings = [];
+  const checked = [];
+  const prefixed = (repo, f) => ({ ...f, path: underRepo(repo, f.path), ...(f.related ? { related: f.related.map(x => ({ ...x, path: underRepo(repo, x.path) })) } : {}) });
+  for (const { repo, r } of reports) {
+    for (const f of r.findings) findings.push(prefixed(repo, f));
+    for (const f of r.checked || []) checked.push(prefixed(repo, f));
+  }
+  sortFindings(findings);
+  const shared = reports.reduce((n, { r }) => n + (r.summary.identity?.shared || 0), 0);
+  const sum = (k) => reports.reduce((n, { r }) => n + (r.summary[k] || 0), 0);
+  const byRule = tally(findings);
+  const bySeverity = {};
+  for (const f of findings) bySeverity[f.sev] = (bySeverity[f.sev] || 0) + 1;
+  const byEvidence = {};
+  for (const f of findings) byEvidence[f.evidence] = (byEvidence[f.evidence] || 0) + 1;
+  const perRepo = Object.fromEntries(reports.map(({ repo, r }) => [repo, { findings: r.summary.findings, filesScanned: r.summary.filesScanned, coverageIncomplete: r.summary.coverageIncomplete, nosrc: r.summary.nosrc }]));
+  const filesScanned = sum('filesScanned');
+  return {
+    tool: 'cobolwork',
+    schemaVersion: SCHEMA_VERSION,
+    summary: {
+      findings: findings.length, byRule, bySeverity, byEvidence, repos: reports.length, perRepo,
+      filesScanned, programs: sum('programs'), programFiles: sum('programFiles'), copybookFiles: sum('copybookFiles'),
+      jclFiles: sum('jclFiles'), copiesMissing: sum('copiesMissing'), filesUnreadable: sum('filesUnreadable'),
+      filesEbcdic: sum('filesEbcdic'), filesOverBudget: sum('filesOverBudget'), crossProgram: sum('crossProgram'),
+      ruleSets: opts.only || RULE_SETS, nosrc: filesScanned === 0,
+      coverageIncomplete: reports.some(({ r }) => r.summary.coverageIncomplete),
+      identity: { version: FINGERPRINT_VERSION, shared },
+      ...(reports[0]?.r.summary.advisoryFeeds ? { advisoryFeeds: reports[0].r.summary.advisoryFeeds } : {}),
+      ...(reports[0]?.r.summary.advisoryCoverage ? { advisoryCoverage: reports[0].r.summary.advisoryCoverage } : {}),
+      // The schema has no repository field for a set, so the repository leads the reason.
+      setsIncomplete: reports.flatMap(({ repo, r }) => (r.summary.setsIncomplete || []).map((x) => ({ ...x, why: `${repo}: ${x.why}` }))),
+    },
+    findings,
+    ...(checked.length ? { checked } : {}),
+    ruleText: Object.fromEntries(Object.entries(ALL_RULES).map(([k, v]) => [k, v.text])),
+    ruleCwe: Object.fromEntries(Object.entries(ALL_RULES).filter(([, v]) => v.cwe).map(([k, v]) => [k, v.cwe])),
+    ruleEvidence: evidenceMap(ALL_RULES),
+    ruleImpact: Object.fromEntries(Object.entries(ALL_RULES).filter(([, v]) => v.impact).map(([k, v]) => [k, v.impact])),
+    ruleRemedy: Object.fromEntries(Object.entries(ALL_RULES).filter(([, v]) => v.remedy).map(([k, v]) => [k, v.remedy])),
+    evidence: EVIDENCE,
+    // Which clause each rule bears on, and what the mapping does not claim. A reader who takes
+    // this to an auditor needs both halves.
+    ruleCompliance: complianceMap(Object.keys(ALL_RULES)),
+    compliance: FRAMEWORKS_LOADED,
+    ...(COMPLIANCE_UNLOADED.length ? { complianceUnloaded: COMPLIANCE_UNLOADED } : {}),
+  };
+}
+
+// A set that throws is reported as not having run, and the other sets' findings stand.
+function runSet(set, root, o) {
+  try { return set.scan(root, o); } catch (e) {
+    return report(set.name, { rules: set.rules, findings: [], stats: {
+      coverageIncomplete: true,
+      notRead: `the rule set stopped on an error and reported nothing: ${printable(e?.message ?? e)}`,
+    } });
+  }
+}
+
+export function scanAll(root, opts = {}) {
+  if (opts.repos && opts.repos.length > 1) return scanEach(root, opts);
+  const only = opts.only || RULE_SETS;
+  // One walk of the tree for the whole scan. Every rule set used to call buildFileIndex(root) for
+  // itself, so a scan read every directory entry and resolved every symlink nine times over, and
+  // added a tenth walk each time a rule set was added.
+  const tree = opts.tree || directoryTree(root, opts);
+  const o = { ...opts, tree };
+  const inv = inventory(root, o);
+  // One loop over the registry, in its order. A set that is not registered cannot run, and
+  // cannot report a silent zero on its own behalf either.
+  const parts = REGISTRY.filter((set) => only.includes(set.name)).map((set) => runSet(set, root, o));
+
+  const flowPart = parts.find(p => p.tool === 'cobolwork-flow');
+  const overBudget = flowPart ? flowPart.summary.filesOverBudget || 0 : 0;
+  // Each rule set reads a different slice of the tree: the hidden-content rules read JCL and
+  // copybooks that no program-based set does. The count that decides whether anything was examined
+  // is the widest of them, so a JCL-only tree is scanned rather than reported as holding nothing.
+  const bySet = { inventory: { filesScanned: inv.summary.filesScanned, filesUnreadable: inv.summary.filesUnreadable } };
+  // A rule set's own tool name is what keys its counts. When one was renamed and this map was not,
+  // that set's counts landed under the key `undefined` in every report. Refusing a name with no key
+  // means the next rename fails a test instead of shipping.
+  for (const p of parts) {
+    const name = reportKey(p.tool);
+    const s = p.summary;
+    // What each set read, and what it did not. The projection used to copy three keys, so the
+    // sentence lib/memory.mjs composes when a scan stops early - which files, and why - was written
+    // and then discarded here. A report that says coverage is incomplete without saying where is a
+    // report that cannot be acted on.
+    bySet[name] = {
+      filesScanned: s.filesScanned || 0,
+      filesUnreadable: s.filesUnreadable || 0,
+      ...(s.filesBinary ? { filesBinary: s.filesBinary } : {}),
+      ...(s.filesNotRead ? { filesNotRead: s.filesNotRead } : {}),
+      ...(s.filesUnparsed ? { filesUnparsed: s.filesUnparsed } : {}),
+      ...(s.stoppedBy ? { stoppedBy: s.stoppedBy } : {}),
+      ...(s.unreadable?.length ? { unreadable: s.unreadable } : {}),
+      ...(s.unparsed?.length ? { unparsed: s.unparsed } : {}),
+      ...(s.notRead ? { notRead: s.notRead } : {}),
+    };
+  }
+  const filesRead = Math.max(...Object.values(bySet).map(x => x.filesScanned));
+  const unreadInSomeSet = Object.values(bySet).some(x => x.filesUnreadable > 0);
+  // Severity and CWE arrive already on the finding, stamped by the set whose table declares the
+  // rule. This used to impute both here, defaulting an unrecognised rule id to 'med', which meant
+  // a set called on its own returned findings with no severity at all and a typo became a medium
+  // finding nobody had written.
+  const findings = [];
+  // A finding any set places in a program is reached by whatever starts that program, which only
+  // the flow set knows.
+  const startedBy = parts.find((p) => p.tool === 'cobolwork-flow')?.startedBy || {};
+  for (const p of parts) for (const f of p.findings) findings.push(!f.startedBy && f.program && startedBy[f.program] ? { ...f, startedBy: startedBy[f.program] } : { ...f });
+  sortFindings(findings);
+  const identity = stampFingerprints(findings, { root, repo: opts.repoName || '' });
+  // Routes a check stops keep their identity too, so a finding a fix clears can be found again here.
+  const checked = parts.find((p) => p.tool === 'cobolwork-flow')?.checked || [];
+  stampFingerprints(checked, { root, repo: opts.repoName || '' });
+
+  // Who can reach a finding: whether the transactions and jobs that start it are open to any user
+  // or restricted, from the estate's own facts - a brought COBOLWORK_REACH extract, or the
+  // open/restricted keys in cobolwork.site.json - never from the source. Undeclared until it says.
+  const site = loadSite(root, opts.site || null);
+  const reachFeeds = reachFeedPaths(opts).map((p) => loadReachFeed(p, { root }));
+  const reach = reachResolver({ feeds: reachFeeds, site });
+  const withEntries = findings.some((f) => (f.startedBy || []).length);
+  const byReach = reach.declared ? stampReach(findings, reach) : null;
+  const byEffect = reach.effectDeclared ? stampEffect(findings, reach) : null;
+  // A rule that escalates only under elevated authority takes its higher severity where the estate
+  // says the entry that reaches it runs privileged.
+  for (const f of findings) {
+    const raise = ALL_RULES[f.rule]?.whenPrivileged;
+    if (raise && f.effect === 'privileged') f.sev = raise;
+  }
+
+  const byRule = tally(findings);
+  const bySeverity = {};
+  for (const f of findings) bySeverity[f.sev] = (bySeverity[f.sev] || 0) + 1;
+  const byEvidence = {};
+  for (const f of findings) byEvidence[f.evidence] = (byEvidence[f.evidence] || 0) + 1;
+
+  const report = {
+    tool: 'cobolwork',
+    schemaVersion: SCHEMA_VERSION,
+    summary: {
+      findings: findings.length,
+      byRule,
+      bySeverity,
+      byEvidence,
+      filesScanned: filesRead,
+      bySet,
+      programs: inv.summary.programs,
+      programFiles: inv.summary.programFiles,
+      copybookFiles: inv.summary.copybookFiles,
+      jclFiles: inv.summary.jclFiles,
+      copiesMissing: inv.summary.copiesMissing,
+      filesUnreadable: inv.summary.filesUnreadable,
+      cicsPrograms: parts.find(p => p.tool === 'cobolwork-cics')?.summary.cicsPrograms ?? null,
+      // A customer's own advisory extract changes what a clean advisory result means, so a scan
+      // that used one says which.
+      ...(parts.find(p => p.tool === 'cobolwork-build')?.summary.advisoryFeeds ? { advisoryFeeds: parts.find(p => p.tool === 'cobolwork-build').summary.advisoryFeeds } : {}),
+      // Which products the advisory rules searched, so a scan with no advisory finding says which
+      // products that silence covers.
+      ...(parts.find(p => p.tool === 'cobolwork-build')?.summary.advisoryCoverage ? { advisoryCoverage: parts.find(p => p.tool === 'cobolwork-build').summary.advisoryCoverage } : {}),
+      crossProgram: parts.find(p => p.tool === 'cobolwork-flow')?.summary.crossProgram ?? 0,
+      ...(parts.find(p => p.tool === 'cobolwork-flow')?.summary.entryPoints?.roots ? rollup(findings) : {}),
+      // Reach annotates, it does not re-rank: severity is urgency, reach is who can drive it. When
+      // no fact is declared, the report says so rather than reading as a clean bill.
+      ...(byReach ? { byReach } : {}),
+      ...(byEffect ? { byEffect } : {}),
+      ...(reachFeeds.some(f => !f.problem) ? { reachFeeds: reachFeeds.filter(f => !f.problem).map(f => ({ file: f.file, extract: f.extract, retrieved: f.retrieved })) } : {}),
+      ...(reachFeeds.some(f => f.problem) ? { reachFeedProblems: reachFeeds.filter(f => f.problem).map(f => `${f.file}: ${f.problem}`) } : {}),
+      ...(!reach.declared && withEntries ? { reachNote: 'no reachability facts declared, so no finding was judged reachable: name open/restricted transactions and jobs in cobolwork.site.json, or bring a COBOLWORK_REACH extract' } : {}),
+      ...(!reach.effectDeclared && withEntries ? { effectNote: 'no authority facts declared, so no finding was judged to run privileged: name privilegedTransactions/privilegedJobs in cobolwork.site.json, or bring them in the COBOLWORK_REACH extract' } : {}),
+      ruleSets: only,
+      // Which flow model produced these rows, and which cobolwork. A finding that appears or
+      // disappears between two reports is attributable to the model rather than to the code scanned.
+      flowModel: FLOW_MODEL,
+      toolVersion: TOOL_VERSION,
+      // How a finding is known across runs, and how many shared an identity with another.
+      identity,
+      filesEbcdic: inv.summary.filesEbcdic,
+      nosrc: filesRead === 0,
+      // Files past the data-flow memory budget were not read by the flow rules. Named, and counted
+      // as incomplete coverage, so a partial scan of a very large repository never reads as whole.
+      filesOverBudget: overBudget,
+      coverageIncomplete: inv.summary.coverageIncomplete || overBudget > 0 || unreadInSomeSet ||
+        parts.some(p => p.summary.coverageIncomplete),
+      // A rule set that could not run for want of configuration, as distinct from content that
+      // could not be read. Named per set, because "recon did not run" and "a copybook is missing"
+      // call for different actions from different people.
+      // Keyed off both flags. setIncomplete means a set could not run for want of configuration;
+      // coverageIncomplete means it ran and did not reach everything. Keying off the first alone
+      // meant a set that stopped on the memory reserve set the report's coverage flag and then
+      // appeared nowhere in the list of which sets fell short. `kind` says which of the two it is.
+      setsIncomplete: parts.filter(p => p.summary.setIncomplete || p.summary.coverageIncomplete)
+        .map(p => {
+          const s = p.summary;
+          const kind = s.coverageIncomplete ? 'coverage' : 'configuration';
+          const coverageWhy = s.notRead || s.readInPart
+            || (s.filesNotRead ? `${s.filesNotRead} file(s) were not read` : null)
+            || (s.filesUnreadable ? `${s.filesUnreadable} file(s) could not be read` : null)
+            || (s.programsUnread?.length ? `${s.programsUnread.length} program(s) could not be read, so a step running one reads as unresolved` : null)
+            // flow can stop after reading every file, with nothing unread to count
+            || (s.stoppedBy ? `${s.filesScanned || 0} file(s) were read, and the analysis stopped because ${stoppedBecause(s.stoppedBy)}` : null);
+          const configurationWhy = s.notLooked?.[0] || s.packsRefused?.[0]?.why || s.packCaveats?.[0] || s.problems?.[0];
+          return {
+            set: reportKey(p.tool),
+            kind,
+            why: (kind === 'coverage' ? coverageWhy || configurationWhy : configurationWhy || coverageWhy)
+              || 'the rule set did not fully run',
+          };
+        }),
+    },
+    inventory: {
+      formats: inv.summary.formats, missingCopybooks: inv.missingCopybooks, unreadable: inv.unreadable,
+      refusedCopies: inv.refusedCopies, ebcdic: inv.ebcdic, symlinks: inv.summary.symlinks, dirsUnreadable: inv.summary.dirsUnreadable,
+    },
+    findings,
+    ...(checked.length ? { checked } : {}),
+    ruleText: Object.fromEntries(Object.entries(ALL_RULES).map(([k, v]) => [k, v.text])),
+    ruleCwe: Object.fromEntries(Object.entries(ALL_RULES).filter(([, v]) => v.cwe).map(([k, v]) => [k, v.cwe])),
+    ruleEvidence: evidenceMap(ALL_RULES),
+    ruleImpact: Object.fromEntries(Object.entries(ALL_RULES).filter(([, v]) => v.impact).map(([k, v]) => [k, v.impact])),
+    ruleRemedy: Object.fromEntries(Object.entries(ALL_RULES).filter(([, v]) => v.remedy).map(([k, v]) => [k, v.remedy])),
+    evidence: EVIDENCE,
+    // Which clause each rule bears on, and what the mapping does not claim. A reader who takes
+    // this to an auditor needs both halves.
+    ruleCompliance: complianceMap(Object.keys(ALL_RULES)),
+    compliance: FRAMEWORKS_LOADED,
+    ...(COMPLIANCE_UNLOADED.length ? { complianceUnloaded: COMPLIANCE_UNLOADED } : {}),
+  };
+  const listed = flowPart?.listed;
+  if (listed) Object.defineProperty(report, 'listed', { value: listed, enumerable: false });
+  return report;
+}