@secureport/core 2.2.0 → 2.3.1

package/src/report/stream.ts

@@ -0,0 +1,727 @@
+import type { RunSummary } from '../run.js';
+import { SEVERITY_ORDER } from '../severity.js';
+import type { Severity } from '../severity.js';
+import type { SnapshotIssue, SuppressedIssue, Target } from '../snapshot.js';
+import { cell, formatDate, issueDetail, issueRow, timelineCell } from './markdown.js';
+import {
+  brandingProblem,
+  describeBasis,
+  describeLimitations,
+  DEFAULT_TITLES,
+  resolveAttestor,
+  verdictFor,
+  VERDICT_LABELS,
+  type OmittedIssues,
+  type ReportOptions,
+  type RetestVerdict,
+} from './model.js';
+
+/**
+ * Everything a streaming machine-readable report needs that is not per-issue.
+ *
+ * **Deliberately not a {@link Snapshot}.** A `Snapshot`'s `issues` and
+ * `suppressed` are eagerly-materialised arrays — the right shape for PDF and
+ * HTML, which are queued, capped at 500 issues, and fully in memory before
+ * Chromium ever runs. The machine formats have no such cap, so their
+ * assembler must never hold every issue at once; a `ReportHeader` carries
+ * only the handful of fields that do not scale with issue count, and the
+ * issues themselves arrive as an `AsyncIterable`.
+ */
+export interface ReportHeader {
+  /** The run this report describes. */
+  readonly run: RunSummary;
+
+  /** What to compare against, for a retest. Absent for a first run. */
+  readonly baseline?: RunSummary;
+
+  /** The system under test. */
+  readonly target: Target;
+}
+
+/** How many issues a severity floor kept out of the streamed `issues` array. */
+interface FoldState {
+  includesManual: boolean;
+  breached: number;
+  omittedBelowFloor: number;
+  suppressedCount: number;
+  retestCounts?: Record<RetestVerdict, number>;
+}
+
+function newFoldState(hasBaseline: boolean): FoldState {
+  return {
+    includesManual: false,
+    breached: 0,
+    omittedBelowFloor: 0,
+    suppressedCount: 0,
+    ...(hasBaseline
+      ? { retestCounts: { fixed: 0, still_present: 0, returned: 0, not_retested: 0, new: 0 } }
+      : {}),
+  };
+}
+
+/** `"key":value`, both run through `JSON.stringify` so nothing is hand-escaped. */
+function field(key: string, value: unknown): string {
+  return `${JSON.stringify(key)}:${JSON.stringify(value)}`;
+}
+
+/**
+ * Open+regressed issues by severity, and their total — read straight off
+ * `RunSummary`, needing no pass over the issues at all.
+ *
+ * `new[sev] + stillOpen[sev] + regressed[sev]` is exactly what
+ * `buildReportModel` recomputes by iterating every issue, because every
+ * non-suppressed, non-resolved issue is counted into exactly one of those
+ * three buckets by `reconcile()` — verified equal on the shared fixture
+ * before either streaming renderer relied on it (`report-stream.test.ts`).
+ */
+function outstandingFrom(run: RunSummary): { by: Record<Severity, number>; total: number } {
+  const by: Record<Severity, number> = {
+    critical: run.new.critical + run.stillOpen.critical + run.regressed.critical,
+    high: run.new.high + run.stillOpen.high + run.regressed.high,
+    medium: run.new.medium + run.stillOpen.medium + run.regressed.medium,
+    low: run.new.low + run.stillOpen.low + run.regressed.low,
+    advisory: run.new.advisory + run.stillOpen.advisory + run.regressed.advisory,
+  };
+  return { by, total: SEVERITY_ORDER.reduce((sum, s) => sum + by[s], 0) };
+}
+
+/**
+ * What a severity floor kept out of a streamed document, from the count a
+ * fold over the issues accumulated — the same statement
+ * `buildReportModel` composes, but from a running total rather than a
+ * `filter().length`.
+ */
+function describeOmitted(count: number, floor: Severity | undefined): OmittedIssues | undefined {
+  if (count === 0 || floor === undefined) return undefined;
+  return {
+    count,
+    floor,
+    statement:
+      `${count} issue${count === 1 ? '' : 's'} below ${floor} severity ` +
+      `${count === 1 ? 'is' : 'are'} not listed individually in this document. ` +
+      `${count === 1 ? 'It remains' : 'They remain'} open and ` +
+      `${count === 1 ? 'is' : 'are'} included in every count above.`,
+  };
+}
+
+/**
+ * Renders a report as JSON, from a header and a cursor over its issues,
+ * rather than from a fully-assembled {@link Snapshot}.
+ *
+ * **This is the machine path's whole reason to exist (B124).** `renderJson`
+ * holds every issue in one array before `JSON.stringify` walks it — measured
+ * at 239 MiB for 25,000 issues — so memory scales with the result and three
+ * concurrent exports exhaust a 512 MiB instance. This function instead
+ * yields the document a fragment at a time: everything that does not depend
+ * on having seen every issue is emitted immediately, the `issues` and
+ * `suppressed` arrays are written one element per row as the cursors
+ * produce them, and the handful of fields that need a full pass —
+ * `basis.includesManual`, `breached`, `omitted`, the retest counts — are
+ * accumulated in a fold whose state is a few counters, never the issues
+ * themselves, and written once both cursors are exhausted. Concatenating
+ * every yielded chunk produces one JSON document; nothing here buffers it
+ * as a string first.
+ *
+ * **`sections` grouped by severity and the sorted `resolved` list do not
+ * exist here.** Both require holding the whole array to sort; this function
+ * instead trusts that `issues` and `suppressed` already arrive in the order
+ * the document should show them; a cursor-based caller supplies that with a
+ * SQL `ORDER BY`, not with an in-memory sort. `includeResolved` and
+ * `severityFloor` still apply, filtering rows out of the stream rather than
+ * out of an array.
+ *
+ * @param header - The run, its baseline, and the target. Never scales with
+ *   issue count.
+ * @param issues - Every issue in scope, most urgent first, in the order the
+ *   document should list them.
+ * @param suppressed - The accepted-risk register, in the order the appendix
+ *   should list it.
+ * @param options - Which report, attribution, and the render time.
+ * @returns Chunks of JSON text; concatenated, they are one document.
+ */
+export async function* renderJsonStream(
+  header: ReportHeader,
+  issues: AsyncIterable<SnapshotIssue>,
+  suppressed: AsyncIterable<SuppressedIssue>,
+  options: ReportOptions,
+): AsyncGenerator<string> {
+  const problem = brandingProblem(options.branding);
+  if (problem !== undefined) throw new TypeError(problem);
+
+  // Rendering a retest of nothing is the over-claim `describeLimitations`'s
+  // caller in `model.ts` also refuses — the document's whole content is a
+  // comparison, and one run does not have one.
+  if (options.kind === 'retest' && header.baseline === undefined) {
+    throw new TypeError('a retest report needs a baseline: pass `baseline` on the header');
+  }
+
+  const attestor = resolveAttestor(options);
+  const floor = options.severityFloor;
+  const floorAt = floor === undefined ? SEVERITY_ORDER.length : SEVERITY_ORDER.indexOf(floor);
+  const state = newFoldState(header.baseline !== undefined);
+
+  yield '{';
+  yield field('reportVersion', 1);
+  yield ',' + field('kind', options.kind);
+  yield ',' + field('title', options.title ?? DEFAULT_TITLES[options.kind]);
+  yield ',' + field('generatedAt', options.now.toISOString());
+  if (options.preparedBy !== undefined) yield ',' + field('preparedBy', options.preparedBy);
+  if (options.preparedFor !== undefined) yield ',' + field('preparedFor', options.preparedFor);
+  yield ',' + field('attestor', attestor);
+  yield ',"target":' + JSON.stringify(header.target);
+  yield ',"run":' + JSON.stringify(header.run);
+  if (header.baseline !== undefined) yield ',"baseline":' + JSON.stringify(header.baseline);
+
+  yield ',"issues":[';
+  let firstIssue = true;
+  for await (const entry of issues) {
+    if (entry.issue.origin === 'manual') state.includesManual = true;
+
+    const status = entry.issue.status;
+    if (status === 'open' || status === 'regressed') {
+      if (entry.slaStatus === 'breached') state.breached++;
+    }
+
+    let verdict: RetestVerdict | undefined;
+    if (state.retestCounts !== undefined) {
+      verdict = verdictFor(entry);
+      state.retestCounts[verdict]++;
+    }
+
+    // The floor decides what is *listed*, never what is *counted* — it was
+    // consulted above this line for exactly that reason, and it never
+    // applies to a resolved issue, which is filtered by `includeResolved`
+    // instead.
+    if (status === 'resolved') {
+      if (options.includeResolved === false) continue;
+    } else if (SEVERITY_ORDER.indexOf(entry.issue.effectiveSeverity) > floorAt) {
+      state.omittedBelowFloor++;
+      continue;
+    }
+
+    const row = verdict === undefined ? entry : { ...entry, retestVerdict: verdict };
+    yield (firstIssue ? '' : ',') + JSON.stringify(row);
+    firstIssue = false;
+  }
+  yield ']';
+
+  yield ',"suppressed":[';
+  let firstSuppressed = true;
+  for await (const entry of suppressed) {
+    state.suppressedCount++;
+    yield (firstSuppressed ? '' : ',') + JSON.stringify(entry);
+    firstSuppressed = false;
+  }
+  yield ']';
+
+  const basis = describeBasis(header.run.kind, header.run.engines, state.includesManual);
+  const omitted = describeOmitted(state.omittedBelowFloor, floor);
+  const limitations = describeLimitations(
+    header.run.coverage.paths,
+    header.run.createdAt,
+    basis,
+    state.suppressedCount,
+    omitted,
+  );
+
+  yield ',"basis":' + JSON.stringify(basis);
+  yield ',"limitations":' + JSON.stringify(limitations);
+
+  const outstanding = outstandingFrom(header.run);
+  yield ',"outstanding":' + JSON.stringify({ ...outstanding.by, total: outstanding.total });
+  yield ',' + field('exposureScore', header.run.exposureScore);
+  yield ',' + field('breached', state.breached);
+  if (omitted !== undefined) yield ',"omitted":' + JSON.stringify(omitted);
+
+  if (state.retestCounts !== undefined) {
+    const checkable =
+      state.retestCounts.fixed + state.retestCounts.still_present + state.retestCounts.returned;
+    yield ',"retest":' +
+      JSON.stringify({
+        counts: state.retestCounts,
+        fixRate: checkable === 0 ? null : state.retestCounts.fixed / checkable,
+      });
+  }
+
+  yield '}';
+}
+
+/**
+ * Renders a report as Markdown, from a header and a cursor over its issues,
+ * rather than from a fully-assembled {@link Snapshot}. The streaming sibling
+ * of {@link renderJsonStream} — see it for the memory argument, which applies
+ * here identically: `renderMarkdown` holds every issue in one array before
+ * formatting any of it.
+ *
+ * **The document is reordered relative to `renderMarkdown`, and that is
+ * forced rather than stylistic.** The array-based renderer opens with "Basis
+ * of testing" and a "What changed" line naming how many issues are past
+ * their remediation deadline — both need to know something about *every*
+ * issue (`basis.includesManual`, `breached`) before the first line can be
+ * printed, which a forward-only stream cannot offer without buffering
+ * everything first. So this function prints what it already knows up front
+ * (title, scope, the New/Still open/Regressed/Resolved/Suppressed table,
+ * which all read straight off `RunSummary`) and moves everything that needs
+ * a full pass — the basis statement, the remediation-deadline count, what a
+ * severity floor omitted, the retest verdict counts, and what the report
+ * does not establish (B109) — into a closing `## Summary` section, written
+ * once both cursors are exhausted.
+ *
+ * **`sections` grouped by severity do not exist here**, for the reason given
+ * in {@link renderJsonStream}: `issues` and `suppressed` are trusted to
+ * already arrive in the order the document should show them. For a `pen`
+ * report that means a severity sub-heading appears whenever the incoming
+ * severity changes, without the issue count that heading carries in
+ * `renderMarkdown` — the count is not known until the section ends. A
+ * `retest` report's per-issue table has no severity floor applied to it,
+ * matching `renderMarkdown`: the whole point of that table is showing what
+ * happened to every issue carried into the retest, not a curated subset.
+ *
+ * **`attest` buffers its suppressed list; nothing else buffers issues.** An
+ * Attestation Letter states counts and names nobody's individual issue, so
+ * it folds the whole `issues` cursor for those counts without printing a
+ * row — but it also prints the suppressed appendix *after* that letter body,
+ * by which point the `suppressed` cursor would already be exhausted. Holding
+ * that one list (the accepted-risk register, ordinarily a minority of the
+ * total) is the one deliberate exception to "never hold more than a row".
+ *
+ * **"What this report does not establish" (B109) lands in the closing
+ * `## Summary` section, after the Suppressed findings table rather than
+ * before it as in `renderMarkdown`.** `describeLimitations` needs
+ * `state.suppressedCount`, complete only once the `suppressed` cursor is
+ * drained — and that drain, and the table it produces, happen earlier in
+ * this stream than the summary does. The array renderer has no such
+ * ordering constraint and keeps limitations immediately before the
+ * appendix; forcing the same document order here would mean buffering the
+ * suppressed rows a second time for no reason `renderJsonStream` needs to.
+ *
+ * @param header - The run, its baseline, and the target. Never scales with
+ *   issue count.
+ * @param issues - Every issue in scope, most urgent first: open/regressed
+ *   before resolved, each group by severity then most-recently-seen first —
+ *   the order the document lists them in.
+ * @param suppressed - The accepted-risk register, in the order the appendix
+ *   should list it.
+ * @param options - Which report, attribution, and the render time.
+ * @returns Chunks of Markdown text; concatenated, they are one document.
+ */
+export async function* renderMarkdownStream(
+  header: ReportHeader,
+  issues: AsyncIterable<SnapshotIssue>,
+  suppressed: AsyncIterable<SuppressedIssue>,
+  options: ReportOptions,
+): AsyncGenerator<string> {
+  const problem = brandingProblem(options.branding);
+  if (problem !== undefined) throw new TypeError(problem);
+  if (options.kind === 'retest' && header.baseline === undefined) {
+    throw new TypeError('a retest report needs a baseline: pass `baseline` on the header');
+  }
+
+  const attestor = resolveAttestor(options);
+  const { target } = header;
+  const floor = options.severityFloor;
+  const floorAt = floor === undefined ? SEVERITY_ORDER.length : SEVERITY_ORDER.indexOf(floor);
+  const state = newFoldState(header.baseline !== undefined);
+  const outstanding = outstandingFrom(header.run);
+
+  const preamble: string[] = [];
+  if (options.branding?.watermark !== undefined) {
+    preamble.push(`**${options.branding.watermark}**`, '');
+  }
+  preamble.push(
+    `# ${options.title ?? DEFAULT_TITLES[options.kind]}`,
+    '',
+    `**${target.name}** — ${target.url}`,
+  );
+  if (options.coverPage === true) {
+    preamble.push(
+      '',
+      ...[
+        attestor,
+        ...(options.branding?.companyDetails ?? []),
+        ...(options.preparedFor === undefined ? [] : [`Prepared for ${options.preparedFor}`]),
+      ].map((line, i) => (i === 0 ? line : `_${line}_`)),
+    );
+  }
+  preamble.push('', '| | |', '| --- | --- |', `| Generated | ${formatDate(options.now)} |`);
+  preamble.push(`| Run | ${header.run.runId} (${header.run.trigger}) |`);
+  if (options.preparedFor !== undefined)
+    preamble.push(`| Prepared for | ${cell(options.preparedFor)} |`);
+  if (options.preparedBy !== undefined)
+    preamble.push(`| Prepared by | ${cell(options.preparedBy)} |`);
+  preamble.push('');
+  yield preamble.join('\n') + '\n';
+
+  if (options.kind === 'attest') {
+    // No per-row content: an Attestation Letter names counts, not issues. The
+    // whole `issues` cursor is folded for `state` and never printed; the
+    // suppressed one is folded *and* buffered, since it is printed after the
+    // letter body, by which point it would otherwise be exhausted.
+    let totalFound = 0;
+    for await (const entry of issues) {
+      totalFound++;
+      if (entry.issue.origin === 'manual') state.includesManual = true;
+      // An Attestation Letter never lists issues individually regardless of
+      // the floor, but `buildReportModel` still folds `omitted` into
+      // `limitations` whenever one is set, kind notwithstanding — matched
+      // here rather than silently diverging.
+      if (
+        entry.issue.status !== 'resolved' &&
+        SEVERITY_ORDER.indexOf(entry.issue.effectiveSeverity) > floorAt
+      ) {
+        state.omittedBelowFloor++;
+      }
+    }
+    const suppressedRows: SuppressedIssue[] = [];
+    for await (const entry of suppressed) {
+      totalFound++;
+      state.suppressedCount++;
+      suppressedRows.push(entry);
+    }
+    const basis = describeBasis(header.run.kind, header.run.engines, state.includesManual);
+
+    const letter: string[] = [
+      '## Statement',
+      '',
+      `${attestor} carried out security testing of **${target.name}**`,
+      `(${target.url}) on ${formatDate(header.run.createdAt)}.`,
+      '',
+      basis.statement,
+      '',
+      `The testing identified ${totalFound} issue${totalFound === 1 ? '' : 's'} in total, of which`,
+      `${outstanding.total} ${outstanding.total === 1 ? 'remains' : 'remain'} outstanding at the date of this letter:`,
+      '',
+      '| Severity | Outstanding |',
+      '| --- | --- |',
+      ...SEVERITY_ORDER.map((sev) => `| ${sev} | ${outstanding.by[sev]} |`),
+      '',
+      '## What this letter does not establish',
+      '',
+      ...describeLimitations(
+        header.run.coverage.paths,
+        header.run.createdAt,
+        basis,
+        state.suppressedCount,
+        describeOmitted(state.omittedBelowFloor, floor),
+      ).map((l) => `- ${l}`),
+      '',
+      '## Scope tested',
+      '',
+      ...header.run.coverage.paths.map((p) => `- \`${cell(p)}\``),
+      '',
+      '## Suppressed findings',
+      '',
+    ];
+    yield letter.join('\n') + '\n';
+    yield suppressedTable(suppressedRows);
+    return;
+  }
+
+  yield [
+    '## Scope',
+    '',
+    `This report covers only what the run exercised: ${header.run.coverage.paths.map((p) => `\`${cell(p)}\``).join(', ')}.`,
+    'Anything outside that was not tested and is not described here.',
+    '',
+  ].join('\n') + '\n';
+
+  const changeRows = SEVERITY_ORDER.map((severity) => {
+    const cells = [
+      severity,
+      header.run.new[severity],
+      header.run.stillOpen[severity],
+      header.run.regressed[severity],
+      header.run.resolved[severity],
+      header.run.ignored[severity],
+    ];
+    return `| ${cells.join(' | ')} |`;
+  });
+  yield [
+    '## What changed',
+    '',
+    header.baseline === undefined
+      ? '_First run against this target, so every issue is new._'
+      : `_Compared with the run of ${formatDate(header.baseline.createdAt)}._`,
+    '',
+    '| Severity | New | Still open | Regressed | Resolved | Suppressed |',
+    '| --- | --- | --- | --- | --- | --- |',
+    ...changeRows,
+    '',
+  ].join('\n') + '\n';
+
+  const notable: SnapshotIssue[] = [];
+  let openedFindings = false;
+  let lastSeverity: Severity | undefined;
+  let anyListed = false;
+  const resolvedRows: string[] = [];
+
+  for await (const entry of issues) {
+    if (entry.issue.origin === 'manual') state.includesManual = true;
+    const status = entry.issue.status;
+    if (status === 'open' || status === 'regressed') {
+      if (entry.slaStatus === 'breached') state.breached++;
+    }
+
+    let verdict: RetestVerdict | undefined;
+    if (state.retestCounts !== undefined) {
+      verdict = verdictFor(entry);
+      state.retestCounts[verdict]++;
+    }
+
+    if (options.kind === 'retest') {
+      // No severity floor and no `includeResolved` filter: every issue
+      // carried into the retest gets a row, matching `renderMarkdown`.
+      if (!openedFindings) {
+        yield [
+          '## Issue by issue',
+          '',
+          '| Issue | Severity | Verdict | Location | Timeline |',
+          '| --- | --- | --- | --- | --- |',
+        ].join('\n') + '\n';
+        openedFindings = true;
+      }
+      const { issue } = entry;
+      const location =
+        issue.parameter === undefined ? issue.location : `${issue.location} (${issue.parameter})`;
+      yield `| ${cell(issue.title)} | ${issue.effectiveSeverity} | ${VERDICT_LABELS[verdict as RetestVerdict]} | \`${cell(location)}\` | ${timelineCell(entry)} |\n`;
+      continue;
+    }
+
+    if (status === 'resolved') {
+      if (options.includeResolved === false) continue;
+      resolvedRows.push(
+        `| ${cell(entry.issue.title)} | ${entry.issue.effectiveSeverity} | \`${cell(entry.issue.location)}\` | ${entry.daysOpen} days |`,
+      );
+      continue;
+    }
+
+    if (SEVERITY_ORDER.indexOf(entry.issue.effectiveSeverity) > floorAt) {
+      state.omittedBelowFloor++;
+      continue;
+    }
+    anyListed = true;
+
+    if (options.kind === 'exec') {
+      if (['critical', 'high'].includes(entry.issue.effectiveSeverity) && notable.length < 10) {
+        notable.push(entry);
+      }
+      continue;
+    }
+
+    if (options.kind === 'pen') {
+      if (!openedFindings) {
+        yield '## Findings\n\n';
+        openedFindings = true;
+      }
+      if (entry.issue.effectiveSeverity !== lastSeverity) {
+        lastSeverity = entry.issue.effectiveSeverity;
+        yield `### ${lastSeverity}\n\n`;
+      }
+      yield issueDetail(entry, options.evidenceVerbosity ?? 'summary').join('\n') + '\n';
+    } else {
+      // `vap`, the tabulated presentation — the default for any kind not
+      // handled above.
+      if (!openedFindings) {
+        yield [
+          '## Findings',
+          '',
+          '| Issue | Severity | Location | Change | Days open | Remediation |',
+          '| --- | --- | --- | --- | --- | --- |',
+        ].join('\n') + '\n';
+        openedFindings = true;
+      }
+      yield issueRow(entry) + '\n';
+    }
+  }
+
+  if (options.kind === 'exec') {
+    yield executiveSummary(outstanding, state, notable).join('\n') + '\n';
+  } else if (options.kind !== 'retest') {
+    if (!anyListed) {
+      yield [
+        '## Findings',
+        '',
+        floor === undefined
+          ? '_No issues were found._'
+          : '_No issues at or above the reporting threshold were found._',
+        '',
+      ].join('\n') + '\n';
+    }
+    if (resolvedRows.length > 0) {
+      const n = resolvedRows.length;
+      yield [
+        '## Resolved since the last run',
+        '',
+        `${n} issue${n === 1 ? ' was' : 's were'} no longer detected by a run that covered ${n === 1 ? 'it' : 'them'}.`,
+        '',
+        '| Issue | Severity | Location | Open for |',
+        '| --- | --- | --- | --- |',
+        ...resolvedRows,
+        '',
+      ].join('\n') + '\n';
+    }
+  }
+
+  yield '## Suppressed findings\n\n';
+  yield suppressedTable(await drain(suppressed, state));
+
+  const basis = describeBasis(header.run.kind, header.run.engines, state.includesManual);
+  const summary: string[] = ['## Summary', '', '## Basis of testing', '', basis.statement, ''];
+  if (state.breached > 0) {
+    summary.push(
+      `**${state.breached} issue${state.breached === 1 ? '' : 's'} past ${state.breached === 1 ? 'its' : 'their'} remediation deadline.**`,
+      '',
+    );
+  }
+  const omitted = describeOmitted(state.omittedBelowFloor, floor);
+  if (omitted !== undefined) summary.push(omitted.statement, '');
+
+  if (options.kind === 'retest' && state.retestCounts !== undefined) {
+    const counts = state.retestCounts;
+    const carried = counts.fixed + counts.still_present + counts.returned + counts.not_retested;
+    const checkable = counts.fixed + counts.still_present + counts.returned;
+    const fixRate = checkable === 0 ? null : counts.fixed / checkable;
+    summary.push(
+      '## Retest verdict',
+      '',
+      carried === 0
+        ? 'No issues were carried into this retest.'
+        : `Of the ${carried} issue${carried === 1 ? '' : 's'} carried into this retest, ` +
+            `**${counts.fixed} ${counts.fixed === 1 ? 'is' : 'are'} confirmed fixed**, ` +
+            `${counts.still_present} ${counts.still_present === 1 ? 'is' : 'are'} still present, ` +
+            `${counts.returned} returned, and ${counts.not_retested} could not be retested.` +
+            (counts.new === 0
+              ? ''
+              : ` A further ${counts.new} ${counts.new === 1 ? 'issue was' : 'issues were'} found for the first time by this run.`),
+      '',
+    );
+    if (fixRate !== null) {
+      summary.push(
+        `${Math.round(fixRate * 100)}% of the issues this run could check are fixed.`,
+        '',
+      );
+    }
+    summary.push(
+      '| Verdict | Issues |',
+      '| --- | --- |',
+      ...(Object.keys(VERDICT_LABELS) as RetestVerdict[]).map(
+        (v) => `| ${VERDICT_LABELS[v]} | ${counts[v]} |`,
+      ),
+      '',
+    );
+    // **Its own heading, not just a sentence.** The array renderer gives this
+    // a `## Not retested` section because it is the part of a retest that
+    // stops a coverage gap reading as remediation; the first draft of this
+    // one kept the sentence and dropped the heading, which a test comparing
+    // the two formats caught.
+    if (counts.not_retested > 0) {
+      summary.push(
+        '## Not retested',
+        '',
+        `${counts.not_retested} issue${counts.not_retested === 1 ? '' : 's'} could not be retested by this run:`,
+        'the run did not cover where they were found, or has not missed them often enough to',
+        'call them resolved. **They are not fixed.** An issue nobody looked at is neither fixed',
+        'nor unfixed, and it is excluded from the percentage above rather than counted either way.',
+        '',
+      );
+    }
+  }
+
+  summary.push(
+    '## What this report does not establish',
+    '',
+    ...describeLimitations(
+      header.run.coverage.paths,
+      header.run.createdAt,
+      basis,
+      state.suppressedCount,
+      omitted,
+    ).map((l) => `- ${l}`),
+    '',
+  );
+
+  yield summary.join('\n') + '\n';
+}
+
+/** Reads the rest of an `AsyncIterable<SuppressedIssue>`, folding as it goes. */
+async function drain(
+  suppressed: AsyncIterable<SuppressedIssue>,
+  state: FoldState,
+): Promise<SuppressedIssue[]> {
+  const rows: SuppressedIssue[] = [];
+  for await (const entry of suppressed) {
+    state.suppressedCount++;
+    rows.push(entry);
+  }
+  return rows;
+}
+
+/** The suppressed-findings table. On by default, never optional (invariant 7). */
+function suppressedTable(rows: readonly SuppressedIssue[]): string {
+  if (rows.length === 0) return '_None._\n';
+  return (
+    [
+      'Accepted, out of scope or dismissed. Listed because an accepted risk that',
+      'nobody can see is not an accepted risk.',
+      '',
+      '| Issue | Severity when suppressed | Reason | By | Expires | Justification |',
+      '| --- | --- | --- | --- | --- | --- |',
+      ...rows.map(
+        (s) =>
+          `| ${cell(s.issue.title)} | ${s.severityAtIgnore} | ${s.reason.replace('_', ' ')} | ${cell(s.ignoredBy)} | ${
+            s.expiresAt === undefined ? 'never' : formatDate(s.expiresAt)
+          } | ${cell(s.comment)} |`,
+      ),
+    ].join('\n') + '\n'
+  );
+}
+
+/** The Executive Summary body, once the fold and the top-10 buffer are complete. */
+function executiveSummary(
+  outstanding: { by: Record<Severity, number>; total: number },
+  state: FoldState,
+  notable: readonly SnapshotIssue[],
+): string[] {
+  const headline =
+    outstanding.total === 0
+      ? 'Nothing is currently outstanding on this target.'
+      : `${outstanding.total} issue${outstanding.total === 1 ? '' : 's'} ${
+          outstanding.total === 1 ? 'is' : 'are'
+        } currently outstanding, of which ${outstanding.by.critical + outstanding.by.high} ` +
+        `${outstanding.by.critical + outstanding.by.high === 1 ? 'is' : 'are'} critical or high.`;
+
+  const lines = ['## Where things stand', '', headline, ''];
+  if (state.breached > 0) {
+    lines.push(
+      `**${state.breached} ${state.breached === 1 ? 'is' : 'are'} past the remediation deadline** ` +
+        'set by the severity policy.',
+      '',
+    );
+  }
+  lines.push(
+    '## Outstanding by severity',
+    '',
+    '| Severity | Outstanding |',
+    '| --- | --- |',
+    ...SEVERITY_ORDER.filter((sev) => outstanding.by[sev] > 0).map(
+      (sev) => `| ${sev} | ${outstanding.by[sev]} |`,
+    ),
+    '',
+  );
+  if (outstanding.total === 0) lines.push('_Nothing outstanding._', '');
+
+  if (notable.length > 0) {
+    lines.push(
+      '## What needs attention first',
+      '',
+      ...notable.map(
+        (entry) =>
+          `- **${entry.issue.effectiveSeverity}** — ${entry.issue.title} (open ${entry.daysOpen} days)`,
+      ),
+      '',
+      '_Full detail, including evidence, is in the accompanying technical report._',
+      '',
+    );
+  }
+  return lines;
+}