@secureport/core 0.2.1 → 0.3.0

package/dist/severity.d.ts

@@ -0,0 +1,191 @@
+/**
+ * How urgent an issue is.
+ *
+ * Five levels, ordered most to least urgent. `advisory` is the bottom of the
+ * scale rather than a separate "informational" category: it carries a weight of
+ * zero in the exposure score and no SLA, but it is still an issue, still
+ * tracked across runs, and still appears in reports.
+ *
+ * @see {@link SEVERITY_ORDER} for comparing two severities.
+ * @see {@link SEVERITY_WEIGHTS} for the exposure-score weights.
+ */
+export type Severity = 'critical' | 'high' | 'medium' | 'low' | 'advisory';
+/**
+ * Every {@link Severity}, most urgent first.
+ *
+ * Iteration order is part of the contract: report sections, severity
+ * breakdowns and count tables all render in this order, so a reader sees the
+ * same shape everywhere.
+ */
+export declare const SEVERITY_ORDER: readonly ["critical", "high", "medium", "low", "advisory"];
+/**
+ * Rank of a {@link Severity}, where a **higher number is more urgent**.
+ *
+ * Use this to compare severities rather than comparing the strings, which sort
+ * alphabetically and would put `advisory` above `critical`.
+ *
+ * @param severity - The severity to rank.
+ * @returns `4` for `critical` down to `0` for `advisory`.
+ *
+ * @example
+ * ```ts
+ * severityRank(finding.detectedSeverity) > severityRank(issue.severityAtIgnore);
+ * ```
+ */
+export declare function severityRank(severity: Severity): number;
+/**
+ * Exposure-score weight for each {@link Severity}.
+ *
+ * `exposure_score = Σ over open issues of weight × min(daysOpen, 90)`.
+ *
+ * `advisory` weighs nothing, so advisories never inflate the number — they are
+ * tracked and reported, but they do not represent exposure.
+ *
+ * These weights are **placeholders** until ten design partners have looked at
+ * the number, and are stated as such in `00-DOMAIN.md` §8. Treat a change to
+ * them as a change to a published contract.
+ */
+export declare const SEVERITY_WEIGHTS: Readonly<Record<Severity, number>>;
+/**
+ * Why a finding was given the severity it has.
+ *
+ * Recorded on every finding because auditors ask, and because a severity with
+ * no provenance is not evidence. Listed here in precedence order — an earlier
+ * source wins over a later one:
+ *
+ * 1. `explicit` — stated by the scanner or the operator for this exact finding.
+ * 2. `cvss` — derived from a CVSS base score via {@link severityFromCvss}.
+ * 3. `engine_default` — the engine's own rating for the rule that fired.
+ * 4. `advisory` — taken from a published advisory for the associated CVE.
+ *
+ * Note the unfortunate collision: `advisory` is both the lowest
+ * {@link Severity} and the least-preferred severity *source*. They are
+ * unrelated — a finding can be `critical` from an `advisory` source. The names
+ * come from `00-DOMAIN.md` §3 and are kept so code and document agree.
+ */
+export type SeveritySource = 'explicit' | 'cvss' | 'engine_default' | 'advisory';
+/**
+ * Every {@link SeveritySource}, most authoritative first.
+ *
+ * The order is the precedence rule: when two sources offer a severity for the
+ * same finding, the one appearing earlier here wins.
+ */
+export declare const SEVERITY_SOURCE_PRECEDENCE: readonly ["explicit", "cvss", "engine_default", "advisory"];
+/**
+ * Maps a CVSS base score to a {@link Severity}.
+ *
+ * Uses the CVSS v3.1 qualitative severity rating scale unchanged, so a score
+ * rated "High" by any other tool is rated `high` here. The one adaptation is
+ * at the bottom: CVSS calls `0.0` "None", and this model has no "none", so it
+ * becomes `advisory`.
+ *
+ * | CVSS score  | CVSS rating | {@link Severity} |
+ * | ----------- | ----------- | ---------------- |
+ * | 9.0 – 10.0  | Critical    | `critical`       |
+ * | 7.0 – 8.9   | High        | `high`           |
+ * | 4.0 – 6.9   | Medium      | `medium`         |
+ * | 0.1 – 3.9   | Low         | `low`            |
+ * | 0.0         | None        | `advisory`       |
+ *
+ * @param score - A CVSS base score between 0 and 10.
+ * @returns The corresponding severity.
+ * @throws RangeError If `score` is outside 0–10 or is not a number. A score
+ * that cannot be mapped is a data problem worth surfacing, not something to
+ * silently round into `advisory`.
+ *
+ * @example
+ * ```ts
+ * severityFromCvss(9.8); // 'critical'
+ * severityFromCvss(0);   // 'advisory'
+ * ```
+ */
+export declare function severityFromCvss(score: number): Severity;
+/**
+ * How long each severity may stay open before it breaches, and how long before
+ * breaching an issue starts warning.
+ *
+ * A policy rather than a constant because remediation windows are a customer
+ * agreement, not a property of the domain: a payments company and a hobby
+ * project do not owe the same turnaround on a `high`.
+ *
+ * @see {@link DEFAULT_SLA_POLICY} for the shipped default.
+ */
+export interface SlaPolicy {
+    /**
+     * Days allowed to remediate an issue of each severity, from `firstSeen`.
+     *
+     * `null` means no deadline applies — the issue is tracked and reported, but
+     * it can never be "due" or "breached". `advisory` is `null` by default.
+     */
+    readonly durationDays: Readonly<Record<Severity, number | null>>;
+    /**
+     * How many days before the deadline an issue starts reporting `due_soon`.
+     *
+     * Exists so a report can distinguish "you have time" from "this is about to
+     * breach" without the reader doing arithmetic.
+     */
+    readonly dueSoonDays: number;
+}
+/**
+ * The default remediation windows.
+ *
+ * Chosen to be defensible rather than derived: they line up with the windows
+ * most vulnerability-management programmes already run, so a customer can
+ * adopt them without an argument and override them without a migration.
+ *
+ * `advisory` has no deadline at all. Giving a zero-weight severity a due date
+ * would manufacture breaches out of things nobody agreed to fix.
+ *
+ * | Severity   | Window   |
+ * | ---------- | -------- |
+ * | `critical` | 7 days   |
+ * | `high`     | 30 days  |
+ * | `medium`   | 90 days  |
+ * | `low`      | 180 days |
+ * | `advisory` | none     |
+ *
+ * **These are defaults, not the domain.** `00-DOMAIN.md` says only that
+ * `sla_due_at` is "derived from effective severity"; the numbers are this
+ * package's opinion and are meant to be replaced by an org's own policy.
+ */
+export declare const DEFAULT_SLA_POLICY: SlaPolicy;
+/**
+ * Where an issue stands against its remediation deadline.
+ *
+ * - `within` — inside the window, and not close enough to warn about.
+ * - `due_soon` — inside the window but within {@link SlaPolicy.dueSoonDays}.
+ * - `breached` — past the deadline.
+ *
+ * An issue with no deadline (see {@link DEFAULT_SLA_POLICY}) is always
+ * `within`: it cannot breach something it was never given.
+ */
+export type SlaStatus = 'within' | 'due_soon' | 'breached';
+/**
+ * When an issue of this severity, first seen at this moment, is due.
+ *
+ * Pure: the deadline is computed from the arguments alone, so the same inputs
+ * always give the same answer and a test needs no control over the clock.
+ *
+ * @param severity - The issue's **effective** severity, not its detected one —
+ * an override is a deliberate statement about how urgent something is, and the
+ * deadline should follow it.
+ * @param firstSeen - When the issue was first seen. Never the current run:
+ * `first_seen` is never reset, so neither is the deadline (invariant 4).
+ * @param policy - The remediation windows to apply.
+ * @returns The deadline, or `null` where the severity has no window.
+ */
+export declare function slaDueAt(severity: Severity, firstSeen: Date, policy?: SlaPolicy): Date | null;
+/**
+ * Where an issue stands against a deadline, as of a given moment.
+ *
+ * Pure, and takes `now` explicitly rather than reading the clock, so a report
+ * rendered for a past run reports the status *as of that run* rather than as of
+ * today.
+ *
+ * @param dueAt - The deadline from {@link slaDueAt}, or `null` for no deadline.
+ * @param now - The moment to evaluate against.
+ * @param policy - Supplies the `due_soon` window.
+ * @returns The status. Always `within` when `dueAt` is `null`.
+ */
+export declare function slaStatus(dueAt: Date | null, now: Date, policy?: SlaPolicy): SlaStatus;
+//# sourceMappingURL=severity.d.ts.map

package/dist/severity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"severity.d.ts","sourceRoot":"","sources":["../src/severity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,UAAU,CAAC;AAE3E;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,4DAA6D,CAAC;AAEzF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAEvD;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAM9D,CAAC;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,MAAM,GAAG,gBAAgB,GAAG,UAAU,CAAC;AAEjF;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,6DAK7B,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CASxD;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;IAEjE;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAS/B,CAAC;AAEH;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;AAE3D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,IAAI,EACf,MAAM,GAAE,SAA8B,GACrC,IAAI,GAAG,IAAI,CAIb;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,IAAI,GAAG,IAAI,EAClB,GAAG,EAAE,IAAI,EACT,MAAM,GAAE,SAA8B,GACrC,SAAS,CAKX"}

package/dist/severity.js

@@ -0,0 +1,171 @@
+/**
+ * Every {@link Severity}, most urgent first.
+ *
+ * Iteration order is part of the contract: report sections, severity
+ * breakdowns and count tables all render in this order, so a reader sees the
+ * same shape everywhere.
+ */
+export const SEVERITY_ORDER = ['critical', 'high', 'medium', 'low', 'advisory'];
+/**
+ * Rank of a {@link Severity}, where a **higher number is more urgent**.
+ *
+ * Use this to compare severities rather than comparing the strings, which sort
+ * alphabetically and would put `advisory` above `critical`.
+ *
+ * @param severity - The severity to rank.
+ * @returns `4` for `critical` down to `0` for `advisory`.
+ *
+ * @example
+ * ```ts
+ * severityRank(finding.detectedSeverity) > severityRank(issue.severityAtIgnore);
+ * ```
+ */
+export function severityRank(severity) {
+    return SEVERITY_ORDER.length - 1 - SEVERITY_ORDER.indexOf(severity);
+}
+/**
+ * Exposure-score weight for each {@link Severity}.
+ *
+ * `exposure_score = Σ over open issues of weight × min(daysOpen, 90)`.
+ *
+ * `advisory` weighs nothing, so advisories never inflate the number — they are
+ * tracked and reported, but they do not represent exposure.
+ *
+ * These weights are **placeholders** until ten design partners have looked at
+ * the number, and are stated as such in `00-DOMAIN.md` §8. Treat a change to
+ * them as a change to a published contract.
+ */
+export const SEVERITY_WEIGHTS = Object.freeze({
+    critical: 10,
+    high: 5,
+    medium: 2,
+    low: 1,
+    advisory: 0,
+});
+/**
+ * Every {@link SeveritySource}, most authoritative first.
+ *
+ * The order is the precedence rule: when two sources offer a severity for the
+ * same finding, the one appearing earlier here wins.
+ */
+export const SEVERITY_SOURCE_PRECEDENCE = [
+    'explicit',
+    'cvss',
+    'engine_default',
+    'advisory',
+];
+/**
+ * Maps a CVSS base score to a {@link Severity}.
+ *
+ * Uses the CVSS v3.1 qualitative severity rating scale unchanged, so a score
+ * rated "High" by any other tool is rated `high` here. The one adaptation is
+ * at the bottom: CVSS calls `0.0` "None", and this model has no "none", so it
+ * becomes `advisory`.
+ *
+ * | CVSS score  | CVSS rating | {@link Severity} |
+ * | ----------- | ----------- | ---------------- |
+ * | 9.0 – 10.0  | Critical    | `critical`       |
+ * | 7.0 – 8.9   | High        | `high`           |
+ * | 4.0 – 6.9   | Medium      | `medium`         |
+ * | 0.1 – 3.9   | Low         | `low`            |
+ * | 0.0         | None        | `advisory`       |
+ *
+ * @param score - A CVSS base score between 0 and 10.
+ * @returns The corresponding severity.
+ * @throws RangeError If `score` is outside 0–10 or is not a number. A score
+ * that cannot be mapped is a data problem worth surfacing, not something to
+ * silently round into `advisory`.
+ *
+ * @example
+ * ```ts
+ * severityFromCvss(9.8); // 'critical'
+ * severityFromCvss(0);   // 'advisory'
+ * ```
+ */
+export function severityFromCvss(score) {
+    if (!Number.isFinite(score) || score < 0 || score > 10) {
+        throw new RangeError(`CVSS score must be between 0 and 10, received ${String(score)}`);
+    }
+    if (score >= 9)
+        return 'critical';
+    if (score >= 7)
+        return 'high';
+    if (score >= 4)
+        return 'medium';
+    if (score > 0)
+        return 'low';
+    return 'advisory';
+}
+/**
+ * The default remediation windows.
+ *
+ * Chosen to be defensible rather than derived: they line up with the windows
+ * most vulnerability-management programmes already run, so a customer can
+ * adopt them without an argument and override them without a migration.
+ *
+ * `advisory` has no deadline at all. Giving a zero-weight severity a due date
+ * would manufacture breaches out of things nobody agreed to fix.
+ *
+ * | Severity   | Window   |
+ * | ---------- | -------- |
+ * | `critical` | 7 days   |
+ * | `high`     | 30 days  |
+ * | `medium`   | 90 days  |
+ * | `low`      | 180 days |
+ * | `advisory` | none     |
+ *
+ * **These are defaults, not the domain.** `00-DOMAIN.md` says only that
+ * `sla_due_at` is "derived from effective severity"; the numbers are this
+ * package's opinion and are meant to be replaced by an org's own policy.
+ */
+export const DEFAULT_SLA_POLICY = Object.freeze({
+    durationDays: Object.freeze({
+        critical: 7,
+        high: 30,
+        medium: 90,
+        low: 180,
+        advisory: null,
+    }),
+    dueSoonDays: 7,
+});
+/**
+ * When an issue of this severity, first seen at this moment, is due.
+ *
+ * Pure: the deadline is computed from the arguments alone, so the same inputs
+ * always give the same answer and a test needs no control over the clock.
+ *
+ * @param severity - The issue's **effective** severity, not its detected one —
+ * an override is a deliberate statement about how urgent something is, and the
+ * deadline should follow it.
+ * @param firstSeen - When the issue was first seen. Never the current run:
+ * `first_seen` is never reset, so neither is the deadline (invariant 4).
+ * @param policy - The remediation windows to apply.
+ * @returns The deadline, or `null` where the severity has no window.
+ */
+export function slaDueAt(severity, firstSeen, policy = DEFAULT_SLA_POLICY) {
+    const days = policy.durationDays[severity];
+    if (days === null)
+        return null;
+    return new Date(firstSeen.getTime() + days * 24 * 60 * 60 * 1000);
+}
+/**
+ * Where an issue stands against a deadline, as of a given moment.
+ *
+ * Pure, and takes `now` explicitly rather than reading the clock, so a report
+ * rendered for a past run reports the status *as of that run* rather than as of
+ * today.
+ *
+ * @param dueAt - The deadline from {@link slaDueAt}, or `null` for no deadline.
+ * @param now - The moment to evaluate against.
+ * @param policy - Supplies the `due_soon` window.
+ * @returns The status. Always `within` when `dueAt` is `null`.
+ */
+export function slaStatus(dueAt, now, policy = DEFAULT_SLA_POLICY) {
+    if (dueAt === null)
+        return 'within';
+    if (now.getTime() > dueAt.getTime())
+        return 'breached';
+    const warnFrom = dueAt.getTime() - policy.dueSoonDays * 24 * 60 * 60 * 1000;
+    return now.getTime() >= warnFrom ? 'due_soon' : 'within';
+}
+//# sourceMappingURL=severity.js.map

package/dist/severity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"severity.js","sourceRoot":"","sources":["../src/severity.ts"],"names":[],"mappings":"AAaA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAU,CAAC;AAEzF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,YAAY,CAAC,QAAkB;IAC7C,OAAO,cAAc,CAAC,MAAM,GAAG,CAAC,GAAG,cAAc,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAuC,MAAM,CAAC,MAAM,CAAC;IAChF,QAAQ,EAAE,EAAE;IACZ,IAAI,EAAE,CAAC;IACP,MAAM,EAAE,CAAC;IACT,GAAG,EAAE,CAAC;IACN,QAAQ,EAAE,CAAC;CACZ,CAAC,CAAC;AAqBH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,UAAU;IACV,MAAM;IACN,gBAAgB;IAChB,UAAU;CACF,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,EAAE,EAAE,CAAC;QACvD,MAAM,IAAI,UAAU,CAAC,iDAAiD,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACzF,CAAC;IACD,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,UAAU,CAAC;IAClC,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,MAAM,CAAC;IAC9B,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,QAAQ,CAAC;IAChC,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5B,OAAO,UAAU,CAAC;AACpB,CAAC;AA8BD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAc,MAAM,CAAC,MAAM,CAAC;IACzD,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC;QAC1B,QAAQ,EAAE,CAAC;QACX,IAAI,EAAE,EAAE;QACR,MAAM,EAAE,EAAE;QACV,GAAG,EAAE,GAAG;QACR,QAAQ,EAAE,IAAI;KACf,CAAC;IACF,WAAW,EAAE,CAAC;CACf,CAAC,CAAC;AAcH;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,QAAQ,CACtB,QAAkB,EAClB,SAAe,EACf,SAAoB,kBAAkB;IAEtC,MAAM,IAAI,GAAG,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC3C,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;AACpE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CACvB,KAAkB,EAClB,GAAS,EACT,SAAoB,kBAAkB;IAEtC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,QAAQ,CAAC;IACpC,IAAI,GAAG,CAAC,OAAO,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE;QAAE,OAAO,UAAU,CAAC;IACvD,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,EAAE,GAAG,MAAM,CAAC,WAAW,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAC5E,OAAO,GAAG,CAAC,OAAO,EAAE,IAAI,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC3D,CAAC"}

package/dist/snapshot-builder.d.ts

@@ -0,0 +1,70 @@
+import type { Finding } from './finding.js';
+import type { Run } from './run.js';
+import type { Snapshot, Target } from './snapshot.js';
+import { type SlaPolicy } from './severity.js';
+/**
+ * Everything needed to turn a run's findings into a report-ready snapshot.
+ */
+export interface BuildSnapshotInput {
+    /** The system under test. */
+    readonly target: Target;
+    /** The run being reported on. */
+    readonly run: Run;
+    /** The findings it produced. */
+    readonly findings: readonly Finding[];
+    /**
+     * The previous snapshot, if there is one.
+     *
+     * **This is what makes a retest work with no account and no database.** The
+     * prior snapshot carries the issues, so a second run can tell what is new,
+     * what is still open, what got fixed and what came back — from a JSON file on
+     * disk. Parse it with {@link parseSnapshot}.
+     */
+    readonly previous?: Snapshot;
+    /** The moment being reported at. */
+    readonly now: Date;
+    /** Supplies ids for issues and events. */
+    readonly newId: () => string;
+    /** Remediation windows. */
+    readonly slaPolicy?: SlaPolicy;
+    /** Consecutive covering misses before an issue resolves. */
+    readonly autoResolveThreshold?: number;
+    /** How long the run took. */
+    readonly durationMs?: number;
+}
+/**
+ * Builds the {@link Snapshot} a report renders from.
+ *
+ * Runs {@link reconcile} over the previous snapshot's issues and this run's
+ * findings, then works out what changed for each issue and precomputes the
+ * things a template would otherwise each derive slightly differently —
+ * `daysOpen`, `slaStatus`, and which findings are the evidence.
+ *
+ * **Two runs on disk are enough.** No account, no database: the previous
+ * snapshot is the state, and this function is the only thing that has to
+ * understand it. That is the whole bring-your-own-findings path.
+ *
+ * Suppressed issues are separated out into {@link Snapshot.suppressed} and do
+ * not appear in {@link Snapshot.issues}, so a template cannot count an accepted
+ * risk as an open one (invariant 7).
+ *
+ * @param input - The run, its findings, and optionally the previous snapshot.
+ * @returns A snapshot, ready to render.
+ */
+export declare function buildSnapshot(input: BuildSnapshotInput): Snapshot;
+/**
+ * Parses a snapshot written to disk, restoring the `Date` objects JSON lost.
+ *
+ * `JSON.stringify` turns every date into a string and `JSON.parse` leaves it as
+ * one, so a snapshot round-tripped through a file is **not** a `Snapshot` — its
+ * dates are strings wearing the type. Everything that then compares or
+ * subtracts them silently produces nonsense rather than failing.
+ *
+ * Use this rather than `JSON.parse` for any snapshot read back from disk.
+ *
+ * @param json - The contents of a snapshot file.
+ * @returns The snapshot, with dates revived.
+ * @throws SyntaxError If the text is not valid JSON.
+ */
+export declare function parseSnapshot(json: string): Snapshot;
+//# sourceMappingURL=snapshot-builder.d.ts.map

package/dist/snapshot-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-builder.d.ts","sourceRoot":"","sources":["../src/snapshot-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,KAAK,EAAe,QAAQ,EAAkC,MAAM,EAAE,MAAM,eAAe,CAAC;AACnG,OAAO,EAAiC,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAG9E;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAElB,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAEtC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAE7B,oCAAoC;IACpC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;IAEnB,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,MAAM,CAAC;IAE7B,2BAA2B;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAE/B,4DAA4D;IAC5D,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAEvC,6BAA6B;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAuBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,QAAQ,CAyEjE;AAiBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAQpD"}

package/dist/snapshot-builder.js

@@ -0,0 +1,148 @@
+import { DEFAULT_SLA_POLICY, slaStatus } from './severity.js';
+import { reconcile } from './reconcile.js';
+/**
+ * The key a finding and an issue share when they are the same issue.
+ *
+ * Mirrors the one reconciliation uses, including the version: a fingerprint
+ * means nothing without the algorithm that produced it. The separator is an
+ * escape rather than a literal control character — writing it as a raw byte has
+ * now put an invisible NUL into two source files, and `scripts/check-text.sh`
+ * exists because nothing else noticed.
+ */
+function issueKey(of) {
+    return `${of.fingerprintVersion}\u0000${of.fingerprint}`;
+}
+/** Whole days between two moments, floored. */
+function daysBetween(from, to) {
+    return Math.max(0, Math.floor((to.getTime() - from.getTime()) / 86_400_000));
+}
+/**
+ * Builds the {@link Snapshot} a report renders from.
+ *
+ * Runs {@link reconcile} over the previous snapshot's issues and this run's
+ * findings, then works out what changed for each issue and precomputes the
+ * things a template would otherwise each derive slightly differently —
+ * `daysOpen`, `slaStatus`, and which findings are the evidence.
+ *
+ * **Two runs on disk are enough.** No account, no database: the previous
+ * snapshot is the state, and this function is the only thing that has to
+ * understand it. That is the whole bring-your-own-findings path.
+ *
+ * Suppressed issues are separated out into {@link Snapshot.suppressed} and do
+ * not appear in {@link Snapshot.issues}, so a template cannot count an accepted
+ * risk as an open one (invariant 7).
+ *
+ * @param input - The run, its findings, and optionally the previous snapshot.
+ * @returns A snapshot, ready to render.
+ */
+export function buildSnapshot(input) {
+    const slaPolicy = input.slaPolicy ?? DEFAULT_SLA_POLICY;
+    const priorIssues = [
+        ...(input.previous?.issues.map((i) => i.issue) ?? []),
+        ...(input.previous?.suppressed.map((s) => s.issue) ?? []),
+    ];
+    const priorById = new Map(priorIssues.map((i) => [i.id, i]));
+    const { issues, summary } = reconcile({
+        issues: priorIssues,
+        findings: input.findings,
+        run: input.run,
+        now: input.now,
+        newId: input.newId,
+        slaPolicy,
+        ...(input.autoResolveThreshold === undefined
+            ? {}
+            : { autoResolveThreshold: input.autoResolveThreshold }),
+        ...(input.durationMs === undefined ? {} : { durationMs: input.durationMs }),
+    });
+    // Evidence, grouped by the issue it belongs to.
+    const byFingerprint = new Map();
+    for (const finding of input.findings) {
+        const key = issueKey(finding);
+        const existing = byFingerprint.get(key);
+        if (existing)
+            existing.push(finding);
+        else
+            byFingerprint.set(key, [finding]);
+    }
+    const reported = [];
+    const suppressed = [];
+    for (const issue of issues) {
+        if (issue.status === 'ignored') {
+            suppressed.push({
+                issue,
+                reason: issue.ignoreReason ?? 'accepted_risk',
+                comment: issue.ignoreComment ?? '',
+                ignoredBy: issue.ignoredBy ?? 'unknown',
+                ignoredAt: issue.lastSeen,
+                ...(issue.ignoreExpiresAt === undefined ? {} : { expiresAt: issue.ignoreExpiresAt }),
+                severityAtIgnore: issue.severityAtIgnore ?? issue.effectiveSeverity,
+            });
+            continue;
+        }
+        const prior = priorById.get(issue.id);
+        let change;
+        if (prior === undefined)
+            change = 'new';
+        else if (issue.status === 'resolved')
+            change = 'resolved';
+        else if (issue.status === 'regressed' && prior.status !== 'regressed')
+            change = 'regressed';
+        else
+            change = 'still_open';
+        reported.push({
+            issue,
+            change,
+            // From firstSeen, which is never reset, so a regression does not make a
+            // year-old problem look new.
+            daysOpen: daysBetween(issue.firstSeen, input.now),
+            slaStatus: slaStatus(issue.slaDueAt ?? null, input.now, slaPolicy),
+            findings: byFingerprint.get(issueKey(issue)) ?? [],
+        });
+    }
+    return {
+        run: summary,
+        ...(input.previous === undefined ? {} : { baseline: input.previous.run }),
+        target: input.target,
+        issues: reported,
+        suppressed,
+    };
+}
+/** Every field in the snapshot tree that JSON turns into a string. */
+const DATE_FIELDS = new Set([
+    'createdAt',
+    'firstSeen',
+    'lastSeen',
+    'resolvedAt',
+    'reopenedAt',
+    'slaDueAt',
+    'severityOverriddenAt',
+    'ignoreExpiresAt',
+    'ignoredAt',
+    'startedAt',
+    'finishedAt',
+]);
+/**
+ * Parses a snapshot written to disk, restoring the `Date` objects JSON lost.
+ *
+ * `JSON.stringify` turns every date into a string and `JSON.parse` leaves it as
+ * one, so a snapshot round-tripped through a file is **not** a `Snapshot` — its
+ * dates are strings wearing the type. Everything that then compares or
+ * subtracts them silently produces nonsense rather than failing.
+ *
+ * Use this rather than `JSON.parse` for any snapshot read back from disk.
+ *
+ * @param json - The contents of a snapshot file.
+ * @returns The snapshot, with dates revived.
+ * @throws SyntaxError If the text is not valid JSON.
+ */
+export function parseSnapshot(json) {
+    return JSON.parse(json, (key, value) => {
+        if (DATE_FIELDS.has(key) && typeof value === 'string') {
+            const parsed = new Date(value);
+            if (!Number.isNaN(parsed.getTime()))
+                return parsed;
+        }
+        return value;
+    });
+}
+//# sourceMappingURL=snapshot-builder.js.map

package/dist/snapshot-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-builder.js","sourceRoot":"","sources":["../src/snapshot-builder.ts"],"names":[],"mappings":"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"}