@secureport/core 2.3.0 → 2.3.1

package/src/report/markdown.ts

@@ -5,6 +5,7 @@ import type { Snapshot, SnapshotIssue } from '../snapshot.js';
 import {
   buildReportModel,
   type EvidenceVerbosity,
+  timelineFor,
   VERDICT_LABELS,
   type ReportModel,
   type ReportOptions,
@@ -166,6 +167,20 @@ export function issueRow(entry: SnapshotIssue): string {
   return `| ${cell(issue.title)} | ${issue.effectiveSeverity} | \`${cell(location)}\` | ${entry.change.replace('_', ' ')} | ${entry.daysOpen} | ${entry.slaStatus.replace('_', ' ')} |`;
 }
 
+/**
+ * An issue's remediation chronology, as a single table cell.
+ *
+ * Exported for the same reason {@link issueRow} is: the streaming renderer
+ * formats a row the moment it sees it, and needs the identical rendering of
+ * {@link timelineFor}'s events — a second join-and-escape is a second one
+ * free to drift.
+ */
+export function timelineCell(entry: SnapshotIssue): string {
+  return timelineFor(entry)
+    .map((event) => cell(event.statement))
+    .join(' · ');
+}
+
 /** The Retest body: the difference between two runs, and nothing else. */
 function retestBody(model: ReportModel): string[] {
   // `buildReportModel` refuses to build a retest without one.
@@ -228,13 +243,13 @@ function retestBody(model: ReportModel): string[] {
   lines.push(
     '## Issue by issue',
     '',
-    '| Issue | Severity | Verdict | Location | Open for |',
+    '| Issue | Severity | Verdict | Location | Timeline |',
     '| --- | --- | --- | --- | --- |',
     ...retest.entries.map((entry) => {
       const { issue } = entry.issue;
       const location =
         issue.parameter === undefined ? issue.location : `${issue.location} (${issue.parameter})`;
-      return `| ${cell(issue.title)} | ${issue.effectiveSeverity} | ${VERDICT_LABELS[entry.verdict]} | \`${cell(location)}\` | ${entry.issue.daysOpen} days |`;
+      return `| ${cell(issue.title)} | ${issue.effectiveSeverity} | ${VERDICT_LABELS[entry.verdict]} | \`${cell(location)}\` | ${timelineCell(entry.issue)} |`;
     }),
     '',
   );
@@ -343,6 +358,27 @@ function executiveBody(model: ReportModel): string[] {
   return lines;
 }
 
+/**
+ * "What this report does not establish" — every kind but the Attestation
+ * Letter, which states its limits inline as part of the formal statement
+ * itself (`attestationBody`) rather than as a separate section (B109).
+ *
+ * Placed immediately before the suppressed appendix in every caller, which is
+ * also where the streaming Markdown renderer (`stream.ts`) is forced to put
+ * it: `describeLimitations` needs the suppressed count and the omitted-below-
+ * floor count, both fold-dependent and only known once the issue cursor is
+ * drained. The array renderer has no such constraint but uses the same
+ * position, so the two cannot drift apart on placement.
+ */
+function limitationsSection(model: ReportModel): string[] {
+  return [
+    '## What this report does not establish',
+    '',
+    ...model.limitations.map((l) => `- ${l}`),
+    '',
+  ];
+}
+
 /** The Attestation Letter body: a formal statement, with its limits stated. */
 function attestationBody(model: ReportModel): string[] {
   const { snapshot } = model;
@@ -482,12 +518,22 @@ export function renderMarkdown(snapshot: Snapshot, options: ReportOptions): stri
   lines.push(...changeSummary(model), '');
 
   if (model.kind === 'exec') {
-    lines.push(...executiveBody(model), ...suppressedAppendix(snapshot), '');
+    lines.push(
+      ...executiveBody(model),
+      ...limitationsSection(model),
+      ...suppressedAppendix(snapshot),
+      '',
+    );
     return withContents(lines, model);
   }
 
   if (model.kind === 'retest') {
-    lines.push(...retestBody(model), ...suppressedAppendix(snapshot), '');
+    lines.push(
+      ...retestBody(model),
+      ...limitationsSection(model),
+      ...suppressedAppendix(snapshot),
+      '',
+    );
     return withContents(lines, model);
   }
 
@@ -524,10 +570,12 @@ export function renderMarkdown(snapshot: Snapshot, options: ReportOptions): stri
     lines.push('');
   }
 
-  // Printed here, beside the section it is about, rather than left to the
-  // limitations list — which only the Attestation Letter renders (B109). A
-  // floor that removed issues from this section and said so nowhere the reader
-  // will look is the quiet form of the over-claim §7 exists to stop.
+  // Printed here too, beside the section it is about, even though it also
+  // appears in `limitationsSection` below (B109). A reader looking at a short
+  // Findings section learns why it is short at the point of confusion rather
+  // than having to find the register at the end; the register entry is what
+  // keeps the disclosure surviving there once the reader has moved past this
+  // section. Two honest statements, not a duplicate to trim.
   if (model.omitted !== undefined) lines.push(`_${model.omitted.statement}_`, '');
 
   if (model.resolved.length > 0) {
@@ -546,6 +594,6 @@ export function renderMarkdown(snapshot: Snapshot, options: ReportOptions): stri
     );
   }
 
-  lines.push(...suppressedAppendix(snapshot), '');
+  lines.push(...limitationsSection(model), ...suppressedAppendix(snapshot), '');
   return withContents(lines, model);
 }

package/src/report/model.ts

@@ -277,6 +277,10 @@ export interface TestingBasis {
  * The issues are still open, still counted and still the target's problem;
  * only the pages describing them are gone. That distinction is the reason this
  * is reported at all rather than silently applied.
+ *
+ * **Never set for a `retest` report.** Its own per-issue table lists every
+ * carried issue regardless of the floor (7.9a) — a floor changes nothing a
+ * reader sees, so there is nothing to disclose.
  */
 export interface OmittedIssues {
   /** How many outstanding issues were left out. Never `0` — the field is absent instead. */
@@ -545,6 +549,120 @@ export function verdictFor(entry: SnapshotIssue): RetestVerdict {
   return entry.findings.length > 0 ? 'still_present' : 'not_retested';
 }
 
+// What kind of moment a `TimelineEvent` records. Four of the five are things
+// that already happened, in the order they happened. `deadline` is not: it is
+// a standing obligation that can be in the future, and `timelineFor` never
+// sorts it in among the other four — see that function's own doc comment for
+// why. Not exported: nothing outside this module names the union, only the
+// `kind` field it types.
+type TimelineEventKind = 'opened' | 'resolved' | 'returned' | 'last_seen' | 'deadline';
+
+/** One moment in an issue's remediation history, worded ready to print. */
+export interface TimelineEvent {
+  /** What kind of moment this is. */
+  readonly kind: TimelineEventKind;
+
+  /** When it happened, or — for `deadline` alone — when it is due. */
+  readonly at: Date;
+
+  /**
+   * One sentence, ready to print, so no two renderers word it differently.
+   *
+   * `deadline`'s wording follows {@link SnapshotIssue.slaStatus}, never a
+   * second comparison of `at` against `now` — `slaStatus` is already the
+   * derived answer to "is this overdue", and a fresh comparison here would be
+   * a second one free to disagree.
+   */
+  readonly statement: string;
+}
+
+/**
+ * An issue's remediation chronology, derived only from dates already on
+ * {@link Issue} — no `issue_events` read, no migration.
+ *
+ * Exported for the same reason {@link verdictFor} is: it is per-issue and
+ * needs nothing but the one entry, which is exactly what the streaming
+ * Markdown renderer can offer it a row at a time.
+ *
+ * **`deadline` is appended last, unconditionally — never sorted in among the
+ * other four.** Those four are things that already happened; a remediation
+ * deadline is a standing obligation, not an event, and it can be in the past
+ * (breached) or the future (within the window). Sorting it by `at` would let
+ * a breached deadline land in the middle of the chronology, worded as though
+ * it were a fact that occurred between two sightings — this function's
+ * version of the mistake `not_retested` exists to stop: reporting something
+ * that has not happened as though it had.
+ *
+ * **No `deadline` event for a resolved issue**, even one whose `slaDueAt` has
+ * passed. A deadline is a claim about outstanding remediation; printing
+ * "overdue since …" beside a `fixed` verdict would report finished work as
+ * work still owed — the same dishonesty from the other direction. None
+ * either when {@link Issue.slaDueAt} is `null` (an `advisory` under
+ * {@link DEFAULT_SLA_POLICY}), since there is no deadline to state.
+ */
+export function timelineFor(entry: SnapshotIssue): readonly TimelineEvent[] {
+  const { issue } = entry;
+  const events: TimelineEvent[] = [
+    {
+      kind: 'opened',
+      at: issue.firstSeen,
+      statement: `opened ${formatIsoDate(issue.firstSeen)} (${entry.daysOpen} days)`,
+    },
+  ];
+
+  if (issue.resolvedAt !== undefined) {
+    events.push({
+      kind: 'resolved',
+      at: issue.resolvedAt,
+      statement: `resolved ${formatIsoDate(issue.resolvedAt)}`,
+    });
+  }
+  if (issue.reopenedAt !== undefined) {
+    events.push({
+      kind: 'returned',
+      at: issue.reopenedAt,
+      statement: `returned ${formatIsoDate(issue.reopenedAt)}`,
+    });
+  }
+
+  // Deduplicated by exact timestamp: `reconcile()` sets `firstSeen` and
+  // `lastSeen` to the same instant when it creates an issue, and an issue
+  // that regressed this run has `reopenedAt === lastSeen` — without this
+  // check the same moment would print twice under two different names.
+  if (!events.some((e) => e.at.getTime() === issue.lastSeen.getTime())) {
+    events.push({
+      kind: 'last_seen',
+      at: issue.lastSeen,
+      statement: `last seen ${formatIsoDate(issue.lastSeen)}`,
+    });
+  }
+
+  // Sorted, not pushed in field-declaration order: `lastSeen` is the last
+  // time the issue was *detected*, which for a resolved issue predates
+  // `resolvedAt` — the date reconciliation stopped seeing it and started
+  // counting misses, not the date it stopped existing. Pushing in the order
+  // above would print "resolved … last seen …" backwards.
+  events.sort((a, b) => a.at.getTime() - b.at.getTime());
+
+  if (issue.slaDueAt !== null && issue.status !== 'resolved') {
+    const due = formatIsoDate(issue.slaDueAt);
+    const statement =
+      entry.slaStatus === 'breached'
+        ? `overdue since ${due}`
+        : entry.slaStatus === 'due_soon'
+          ? `due ${due} (due soon)`
+          : `due ${due}`;
+    events.push({ kind: 'deadline', at: issue.slaDueAt, statement });
+  }
+
+  return events;
+}
+
+/** A date, printed the same way everywhere in this module. */
+function formatIsoDate(date: Date): string {
+  return date.toISOString().slice(0, 10);
+}
+
 /**
  * Works out what a report cannot establish, from the run rather than a
  * template.
@@ -784,7 +902,11 @@ export function buildReportModel(snapshot: Snapshot, options: ReportOptions): Re
     }
 
     if (SEVERITY_ORDER.indexOf(severity) > floorAt) {
-      omittedBelowFloor++;
+      // B208: `retest`'s own table lists every carried issue regardless of
+      // the floor (7.9a) — nothing is actually left out of the document for
+      // this kind, so counting it here would make `limitations` state an
+      // omission the very next section contradicts.
+      if (options.kind !== 'retest') omittedBelowFloor++;
       continue;
     }
 

package/src/report/stream.ts

@@ -2,7 +2,7 @@ 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 } from './markdown.js';
+import { cell, formatDate, issueDetail, issueRow, timelineCell } from './markdown.js';
 import {
   brandingProblem,
   describeBasis,
@@ -263,8 +263,9 @@ export async function* renderJsonStream(
  * (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 — into a closing
- * `## Summary` section, written once both cursors are exhausted.
+ * 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
@@ -284,6 +285,16 @@ export async function* renderJsonStream(
  * 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
@@ -464,7 +475,7 @@ export async function* renderMarkdownStream(
         yield [
           '## Issue by issue',
           '',
-          '| Issue | Severity | Verdict | Location | Open for |',
+          '| Issue | Severity | Verdict | Location | Timeline |',
           '| --- | --- | --- | --- | --- |',
         ].join('\n') + '\n';
         openedFindings = true;
@@ -472,7 +483,7 @@ export async function* renderMarkdownStream(
       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)}\` | ${entry.daysOpen} days |\n`;
+      yield `| ${cell(issue.title)} | ${issue.effectiveSeverity} | ${VERDICT_LABELS[verdict as RetestVerdict]} | \`${cell(location)}\` | ${timelineCell(entry)} |\n`;
       continue;
     }
 
@@ -615,6 +626,20 @@ export async function* renderMarkdownStream(
       );
     }
   }
+
+  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';
 }