@safegres/test 0.0.1 → 1.30.7

package/pg/stats.js

@@ -0,0 +1,133 @@
+"use strict";
+/**
+ * Runtime statistics snapshot (`--stats`).
+ *
+ * Everything here reads the cumulative statistics views — `pg_stat_user_tables`,
+ * `pg_stat_user_indexes`, and (when installed) `pg_stat_statements`. Unlike the
+ * catalog checks, these numbers describe a *workload*: they are only as good as
+ * the traffic the database has seen since the counters were last reset, which is
+ * why the snapshot carries `statsReset` and why the checks take floors.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_STATEMENT_LIMIT = void 0;
+exports.introspectStats = introspectStats;
+const introspect_1 = require("./introspect");
+const DEFAULT_EXCLUDES = ['pg_catalog', 'information_schema', 'pg_toast'];
+/** Statements slower than this in aggregate are worth reporting at all. */
+exports.DEFAULT_STATEMENT_LIMIT = 20;
+async function introspectStats(exec, options = {}) {
+    const excludes = [...DEFAULT_EXCLUDES, ...(options.excludeSchemas ?? [])];
+    const schemaFilter = options.schemas && options.schemas.length > 0
+        ? `AND s.schemaname = ANY($1::text[])`
+        : `AND NOT (s.schemaname = ANY($2::text[]))`;
+    const extFilter = (0, introspect_1.extensionFilter)(options.extensions, 3);
+    // Every parameter is referenced (even when only one filters) so Postgres
+    // can infer their types — an unused $N errors out at bind time.
+    const sql = `
+    WITH _params AS (
+      SELECT
+        $1::text[] AS include_schemas,
+        $2::text[] AS exclude_schemas,
+        $3::text[] AS ignore_extensions
+    )
+    SELECT
+      s.schemaname                                      AS schema_name,
+      s.relname                                         AS table_name,
+      s.seq_scan                                        AS seq_scans,
+      s.seq_tup_read                                    AS seq_tuples_read,
+      COALESCE(s.idx_scan, 0)                           AS index_scans,
+      s.n_live_tup                                      AS live_tuples,
+      s.n_dead_tup                                      AS dead_tuples,
+      pg_relation_size(s.relid)                         AS size_bytes,
+      GREATEST(s.last_vacuum, s.last_autovacuum)        AS last_vacuum,
+      GREATEST(s.last_analyze, s.last_autoanalyze)      AS last_analyze,
+      COALESCE(
+        (SELECT jsonb_agg(jsonb_build_object(
+          'name', i.indexrelname,
+          'scans', COALESCE(i.idx_scan, 0),
+          'sizeBytes', pg_relation_size(i.indexrelid),
+          'unique', ix.indisunique,
+          'constraint', (con.oid IS NOT NULL)
+        ) ORDER BY i.indexrelname)
+         FROM pg_stat_user_indexes i
+         JOIN pg_index ix ON ix.indexrelid = i.indexrelid
+         LEFT JOIN pg_constraint con
+           ON con.conindid = i.indexrelid AND con.contype IN ('p', 'u', 'x')
+         WHERE i.relid = s.relid),
+        '[]'::jsonb
+      )                                                 AS indexes
+    FROM pg_stat_user_tables s
+    JOIN pg_class c ON c.oid = s.relid
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE true
+      ${schemaFilter}${extFilter}
+    ORDER BY s.schemaname, s.relname
+  `;
+    const { rows } = await exec.query(sql, [options.schemas ?? [], excludes, options.extensions?.ignore ?? []]);
+    const tables = rows.map((r) => ({
+        schema: r.schema_name,
+        name: r.table_name,
+        seqScans: num(r.seq_scans),
+        seqTuplesRead: num(r.seq_tuples_read),
+        indexScans: num(r.index_scans),
+        liveTuples: num(r.live_tuples),
+        deadTuples: num(r.dead_tuples),
+        sizeBytes: num(r.size_bytes),
+        lastVacuum: iso(r.last_vacuum),
+        lastAnalyze: iso(r.last_analyze),
+        indexes: r.indexes.map((i) => ({ ...i, scans: num(i.scans), sizeBytes: num(i.sizeBytes) }))
+    }));
+    const { rows: resetRows } = await exec.query(`SELECT stats_reset FROM pg_stat_database WHERE datname = current_database()`);
+    const resetRow = resetRows[0];
+    const snapshot = {
+        tables,
+        statsReset: iso(resetRow?.stats_reset ?? null)
+    };
+    const statements = await introspectStatements(exec, options.statementLimit);
+    if (typeof statements === 'string')
+        snapshot.statementsUnavailable = statements;
+    else
+        snapshot.statements = statements;
+    return snapshot;
+}
+/**
+ * Top statements by total execution time. Returns a reason string instead of
+ * rows when `pg_stat_statements` is not installed or not readable by the
+ * connected role — an optional extension is a normal state, not an error.
+ */
+async function introspectStatements(exec, limit = exports.DEFAULT_STATEMENT_LIMIT) {
+    const { rows: installedRows } = await exec.query(`SELECT EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'pg_stat_statements') AS present`);
+    if (!installedRows[0]?.present) {
+        return 'pg_stat_statements is not installed — statement-level findings (S4) were skipped';
+    }
+    try {
+        const { rows } = await exec.query(`SELECT
+         query,
+         calls,
+         total_exec_time AS total_time_ms,
+         mean_exec_time  AS mean_time_ms,
+         rows
+       FROM pg_stat_statements
+       ORDER BY total_exec_time DESC
+       LIMIT $1`, [limit]);
+        return rows.map((r) => ({
+            query: r.query,
+            calls: num(r.calls),
+            totalTimeMs: Number(r.total_time_ms),
+            meanTimeMs: Number(r.mean_time_ms),
+            rows: num(r.rows)
+        }));
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        return `pg_stat_statements is installed but unreadable (${message}) — S4 was skipped`;
+    }
+}
+function num(value) {
+    return typeof value === 'number' ? value : Number(value);
+}
+function iso(value) {
+    if (value === null || value === undefined)
+        return null;
+    return value instanceof Date ? value.toISOString() : String(value);
+}

package/pgpm-test.d.ts

@@ -0,0 +1,22 @@
+import { type AuditOptions } from './commands/audit';
+import type { SafegresConfig } from './config/types';
+import type { Report } from './types';
+export interface AuditPgpmWorkspaceOptions extends Omit<AuditOptions, 'config'> {
+    /**
+     * pgpm workspace or module directory to deploy. Defaults to the nearest
+     * pgpm module/workspace discovered from `process.cwd()`.
+     */
+    cwd?: string;
+    /** Explicit safegres config file (else discovered by walk-up from `cwd`). */
+    configFile?: string;
+    /** Built-in preset name (recommended|strict|constructive|minimal). */
+    preset?: string;
+    /** Pre-resolved config — skips discovery entirely. */
+    config?: SafegresConfig;
+}
+/**
+ * Deploy the pgpm workspace at `cwd` into an ephemeral test database, run
+ * `safegres audit` against it with the project's safegres config, tear the
+ * database down, and return the report.
+ */
+export declare function auditPgpmWorkspace(options?: AuditPgpmWorkspaceOptions): Promise<Report>;

package/pgpm-test.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.auditPgpmWorkspace = auditPgpmWorkspace;
+/**
+ * Test helper for pgpm projects: deploy the workspace into an ephemeral
+ * database (via pgsql-test) and audit it with the project's discovered
+ * safegres config.
+ *
+ * `pgsql-test` is an optional peer dependency — only needed when this
+ * entrypoint is imported.
+ *
+ * ```ts
+ * import { auditPgpmWorkspace } from 'safegres/pgpm-test';
+ *
+ * it('passes the security audit', async () => {
+ *   const report = await auditPgpmWorkspace();
+ *   expect(report.score.grade).toBe('A+');
+ * });
+ * ```
+ */
+const pgsql_test_1 = require("pgsql-test");
+const audit_1 = require("./commands/audit");
+const loader_1 = require("./config/loader");
+/**
+ * Deploy the pgpm workspace at `cwd` into an ephemeral test database, run
+ * `safegres audit` against it with the project's safegres config, tear the
+ * database down, and return the report.
+ */
+async function auditPgpmWorkspace(options = {}) {
+    const { cwd, configFile, preset, config: explicitConfig, ...auditOptions } = options;
+    const config = explicitConfig ?? (0, loader_1.loadConfig)({ cwd, configFile, preset }).config;
+    const { pg, teardown } = await (0, pgsql_test_1.getConnections)({}, [pgsql_test_1.seed.pgpm(cwd)]);
+    try {
+        return await (0, audit_1.audit)(pg.client, {
+            ...auditOptions,
+            config
+        });
+    }
+    finally {
+        await teardown();
+    }
+}

package/report/callgraph.d.ts

@@ -0,0 +1,9 @@
+import type { CallGraphDiff } from '../callgraph/baseline';
+import type { CallGraphReport } from '../callgraph/graph';
+export interface RenderCallGraphOptions {
+    color?: boolean;
+    /** Only the stats line — no checklist items. */
+    summary?: boolean;
+}
+export declare function renderCallGraph(cg: CallGraphReport, options?: RenderCallGraphOptions): string;
+export declare function renderCallGraphDiff(diff: CallGraphDiff, options?: RenderCallGraphOptions): string;

package/report/callgraph.js

@@ -0,0 +1,81 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderCallGraph = renderCallGraph;
+exports.renderCallGraphDiff = renderCallGraphDiff;
+const yanse_1 = __importDefault(require("yanse"));
+const baseline_1 = require("../callgraph/baseline");
+const CODE_META = {
+    CF1: { title: 'DEFINER without pinned search_path (provable — fix these)', paint: yanse_1.default.red },
+    CF2: { title: 'DEFINER executable by anonymous/PUBLIC (provable — confirm intent)', paint: yanse_1.default.red },
+    CG2: { title: 'RLS-bypass paths (RLS does not protect the table on this path)', paint: yanse_1.default.yellow },
+    CG3: { title: 'auth-context mutations (functions that change who you are)', paint: yanse_1.default.yellow },
+    CG1: { title: 'trust hops (execution crosses into SECURITY DEFINER)', paint: yanse_1.default.cyan },
+    CG4: { title: 'internal tables reached via DEFINER paths', paint: yanse_1.default.cyan },
+    CG5: { title: 'opaque nodes (static analysis ends here — audit manually)', paint: yanse_1.default.gray }
+};
+const CODE_ORDER = ['CF1', 'CF2', 'CG2', 'CG3', 'CG1', 'CG4', 'CG5'];
+function renderCallGraph(cg, options = {}) {
+    const color = options.color === true;
+    const paint = (p, s) => (color ? p(s) : s);
+    const s = cg.stats;
+    const lines = [
+        paint(yanse_1.default.bold, 'call graph — trust boundaries reachable from the exposed surface (unscored; human review)'),
+        `  ${s.entryPoints} entry point(s) → ${s.reachableFunctions} reachable function(s)`
+            + `  |  ${s.trustHops} trust hop(s)  ${s.rlsBypassPaths} RLS-bypass  `
+            + `${s.authContextMutations} auth-context  ${s.internalReach} internal-reach  ${s.opaqueNodes} opaque`
+    ];
+    if (options.summary || cg.checklist.length === 0) {
+        if (cg.checklist.length === 0)
+            lines.push('  no trust boundaries found.');
+        return lines.join('\n');
+    }
+    for (const code of CODE_ORDER) {
+        const items = cg.checklist.filter((i) => i.code === code);
+        if (items.length === 0)
+            continue;
+        const meta = CODE_META[code];
+        lines.push('', paint(meta.paint, `${code} — ${meta.title} (${items.length})`));
+        for (const item of items) {
+            lines.push(...renderItem(item));
+        }
+    }
+    return lines.join('\n');
+}
+function renderCallGraphDiff(diff, options = {}) {
+    const color = options.color === true;
+    const paint = (p, s) => (color ? p(s) : s);
+    if (diff.added.length === 0 && diff.removed.length === 0) {
+        return paint(yanse_1.default.green, 'baseline: no new trust boundaries.');
+    }
+    const lines = [];
+    if (diff.added.length > 0) {
+        lines.push(paint(yanse_1.default.red, `baseline: ${diff.added.length} NEW trust boundar${diff.added.length === 1 ? 'y' : 'ies'} — review and re-baseline to accept:`));
+        for (const item of diff.added) {
+            lines.push(`  + [${item.code}] ${item.table ? `${item.fn} → ${item.table}` : item.fn}`);
+            lines.push(`        ${item.message}`);
+            if (item.path.length > 1)
+                lines.push(`        via: ${item.path.join(' → ')}`);
+        }
+    }
+    if (diff.removed.length > 0) {
+        lines.push(paint(yanse_1.default.green, `baseline: ${diff.removed.length} boundar${diff.removed.length === 1 ? 'y' : 'ies'} resolved (no longer present) — re-baseline to prune:`));
+        for (const b of diff.removed) {
+            lines.push(`  - ${(0, baseline_1.boundaryKey)(b)}`);
+        }
+    }
+    return lines.join('\n');
+}
+function renderItem(item) {
+    const subject = item.table ? `${item.fn} → ${item.table}` : item.fn;
+    const out = [`  • ${subject}`, `      ${item.message}`];
+    if (item.path.length > 1) {
+        out.push(`      via: ${item.path.join(' → ')}`);
+    }
+    else if (item.entry !== item.fn) {
+        out.push(`      via: ${item.entry}`);
+    }
+    return out;
+}

package/report/compare.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Comparison against a previous run (`--compare <file>`).
+ *
+ * A report says what the database is; it never says what changed. In CI that
+ * is the only question a reviewer has — the PR comment reads "Performance 75.0
+ * (C)" whether the branch improved it by ten points or cost ten, and the
+ * numbers are only legible to someone who remembers yesterday's.
+ *
+ * The previous run is supplied as a file rather than inferred: a scanner has
+ * no memory and no business acquiring one, so CI decides what "previous" means
+ * (the artifact from the base branch, a committed scoreboard) and passes it in.
+ * Any `renderJson` output works as input, so nothing extra has to be produced
+ * for this to be usable — but `toSnapshot` exists for the case where a full
+ * report is too large to keep around, since only the aggregates are read.
+ */
+import type { Grade } from '../config/types';
+import type { Report, Severity, Summary } from '../types';
+/** The aggregate slice of a report that a comparison reads. */
+export interface ReportSnapshot {
+    /** safegres version that produced the run. */
+    version?: string;
+    generatedAt?: string;
+    /** Free-form label for the run — a git ref, a commit sha, "main". */
+    ref?: string;
+    /** Where the previous run came from, when CI knows. */
+    provenance?: BaselineProvenance;
+    summary: Summary;
+    security?: DimensionSnapshot;
+    perf?: DimensionSnapshot;
+}
+/**
+ * Which run the delta is measured against.
+ *
+ * `ref` alone renders as "Changes since main", which is what a stale baseline
+ * hides behind: it is true of a report produced an hour ago and of one produced
+ * a fortnight and 150 merges ago, and the reader cannot tell. Every field is a
+ * plain string a provider fills in, so this stays provider-agnostic — a run id
+ * and a run URL are as meaningful on GitLab or Buildkite as on GitHub Actions.
+ */
+export interface BaselineProvenance {
+    /** The commit the baseline report was produced from. */
+    sha?: string;
+    /** The CI run that produced it. */
+    runId?: string;
+    /** A link to that run. */
+    runUrl?: string;
+    /** Pre-formatted age ("10.2 hours"), when the provider measured it. */
+    age?: string;
+}
+export interface DimensionSnapshot {
+    value: number;
+    grade: Grade;
+    findings: number;
+    /** Finding count per rule code. */
+    rules: Record<string, number>;
+}
+export interface ScoreDelta {
+    before: number;
+    after: number;
+    /** `after - before`, rounded to one decimal. Positive is an improvement. */
+    delta: number;
+    gradeBefore: Grade;
+    gradeAfter: Grade;
+    /** Findings before → after. */
+    findingsBefore: number;
+    findingsAfter: number;
+}
+export interface RuleDelta {
+    code: string;
+    before: number;
+    after: number;
+    /** `after - before`. Positive means the rule fires more than it used to. */
+    delta: number;
+    dimension: 'security' | 'perf';
+    /**
+     * The previous run reported nothing for this code — a rule that did not
+     * exist in that version, or a dimension it never ran. Distinct from a real
+     * zero: `before: 0` means the rule ran and found nothing, and an increase
+     * off it is a regression; this means the movement is unknown, and rendering
+     * it as one is how a scanner upgrade comes out looking like a catastrophe.
+     */
+    unmeasuredBefore?: boolean;
+}
+export interface ReportComparison {
+    /** Where the previous numbers came from, for the reader. */
+    previous: {
+        ref?: string;
+        generatedAt?: string;
+        version?: string;
+        provenance?: BaselineProvenance;
+    };
+    security?: ScoreDelta;
+    perf?: ScoreDelta;
+    /** Severity counts, before → after. */
+    summary: Record<Severity, {
+        before: number;
+        after: number;
+        delta: number;
+    }>;
+    /** Rules whose finding count moved, largest regression first. */
+    rules: RuleDelta[];
+    /** Nothing moved: same scores, same counts, same rules. */
+    unchanged: boolean;
+}
+/** Reduce a report to the aggregates a comparison needs. */
+export declare function toSnapshot(report: Report, meta?: {
+    ref?: string;
+    provenance?: BaselineProvenance;
+}): ReportSnapshot;
+export declare function serializeSnapshot(snapshot: ReportSnapshot): string;
+/**
+ * Read a previous run from JSON. Accepts either a snapshot or a full report —
+ * the two are distinguished by the presence of `findings`, so CI can hand over
+ * whatever it already has on disk.
+ */
+export declare function parseSnapshot(json: string): ReportSnapshot;
+/** Diff a fresh report against a previous run. */
+export declare function compareReports(previous: ReportSnapshot, current: Report): ReportComparison;
+/**
+ * `+2.3` / `−1.4` / `0`, with a real minus sign. Rendering-only, but shared:
+ * the markdown and pretty renderers must not disagree about which direction a
+ * number moved.
+ */
+export declare function formatDelta(delta: number, digits?: number): string;
+/** `13.6 days` / `3.2 hours` / `41 minutes` — an age a human reads at a glance. */
+export declare function formatAge(ms: number): string;
+/**
+ * "main@af904c90d — [run 33373344814](…), 10.2 hours old" — the one line every
+ * renderer puts above a delta, so the job summary, the PR comment and the
+ * terminal cannot describe different baselines.
+ *
+ * The age falls back to `generatedAt` when the provider did not measure one:
+ * the report timestamp is what a scanner always has.
+ */
+export declare function describeBaseline(previous: ReportComparison['previous'], options?: {
+    link?: boolean;
+    now?: number;
+}): string;
+/**
+ * `main@af904c90d`, or just `main` when no commit is known — the short name of
+ * the baseline, for a place too narrow for the run and the age.
+ */
+export declare function baselineLabel(previous: ReportComparison['previous']): string;

package/report/compare.js

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * Comparison against a previous run (`--compare <file>`).
+ *
+ * A report says what the database is; it never says what changed. In CI that
+ * is the only question a reviewer has — the PR comment reads "Performance 75.0
+ * (C)" whether the branch improved it by ten points or cost ten, and the
+ * numbers are only legible to someone who remembers yesterday's.
+ *
+ * The previous run is supplied as a file rather than inferred: a scanner has
+ * no memory and no business acquiring one, so CI decides what "previous" means
+ * (the artifact from the base branch, a committed scoreboard) and passes it in.
+ * Any `renderJson` output works as input, so nothing extra has to be produced
+ * for this to be usable — but `toSnapshot` exists for the case where a full
+ * report is too large to keep around, since only the aggregates are read.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toSnapshot = toSnapshot;
+exports.serializeSnapshot = serializeSnapshot;
+exports.parseSnapshot = parseSnapshot;
+exports.compareReports = compareReports;
+exports.formatDelta = formatDelta;
+exports.formatAge = formatAge;
+exports.describeBaseline = describeBaseline;
+exports.baselineLabel = baselineLabel;
+const types_1 = require("../types");
+const SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'];
+function dimensionSnapshot(score, findings) {
+    if (!score)
+        return undefined;
+    const rules = {};
+    for (const d of score.deductions)
+        rules[d.code] = d.count;
+    return { value: score.value, grade: score.grade, findings, rules };
+}
+/** Reduce a report to the aggregates a comparison needs. */
+function toSnapshot(report, meta = {}) {
+    const perfFindings = report.perf?.findings.length ?? 0;
+    return {
+        version: report.version,
+        generatedAt: report.generatedAt,
+        ...(meta.ref !== undefined && { ref: meta.ref }),
+        ...(meta.provenance !== undefined && { provenance: meta.provenance }),
+        summary: report.summary,
+        ...(report.score && {
+            security: dimensionSnapshot(report.score, report.findings.length - perfFindings)
+        }),
+        ...(report.perf && { perf: dimensionSnapshot(report.perf.score, perfFindings) })
+    };
+}
+function serializeSnapshot(snapshot) {
+    return `${JSON.stringify(snapshot, null, 2)}\n`;
+}
+/**
+ * Read a previous run from JSON. Accepts either a snapshot or a full report —
+ * the two are distinguished by the presence of `findings`, so CI can hand over
+ * whatever it already has on disk.
+ */
+function parseSnapshot(json) {
+    const parsed = JSON.parse(json);
+    if (Array.isArray(parsed.findings))
+        return toSnapshot(parsed);
+    if (!parsed.summary) {
+        throw new Error('not a safegres report or snapshot: no "summary"');
+    }
+    return parsed;
+}
+function round(value) {
+    return Math.round(value * 10) / 10;
+}
+function scoreDelta(before, after) {
+    if (!before || !after)
+        return undefined;
+    return {
+        before: before.value,
+        after: after.value,
+        delta: round(after.value - before.value),
+        gradeBefore: before.grade,
+        gradeAfter: after.grade,
+        findingsBefore: before.findings,
+        findingsAfter: after.findings
+    };
+}
+function ruleDeltas(dimension, before, after) {
+    if (!before && !after)
+        return [];
+    const codes = new Set([
+        ...Object.keys(before?.rules ?? {}),
+        ...Object.keys(after?.rules ?? {})
+    ]);
+    const out = [];
+    for (const code of codes) {
+        const measured = before?.rules[code] !== undefined;
+        const b = before?.rules[code] ?? 0;
+        const a = after?.rules[code] ?? 0;
+        if (a === b)
+            continue;
+        out.push({
+            code,
+            before: b,
+            after: a,
+            delta: a - b,
+            dimension,
+            ...(measured ? {} : { unmeasuredBefore: true })
+        });
+    }
+    return out;
+}
+/** Diff a fresh report against a previous run. */
+function compareReports(previous, current) {
+    const now = toSnapshot(current);
+    const summary = {};
+    const prevSummary = previous.summary ?? (0, types_1.newSummary)();
+    for (const sev of SEVERITIES) {
+        const before = prevSummary[sev] ?? 0;
+        const after = now.summary[sev] ?? 0;
+        summary[sev] = { before, after, delta: after - before };
+    }
+    const rules = [
+        ...ruleDeltas('security', previous.security, now.security),
+        ...ruleDeltas('perf', previous.perf, now.perf)
+    ]
+        // Regressions first, then improvements; rules with no previous reading
+        // last, since they are not movement and should not lead the table.
+        .sort((a, b) => Number(a.unmeasuredBefore ?? false) - Number(b.unmeasuredBefore ?? false)
+        || b.delta - a.delta
+        || a.code.localeCompare(b.code));
+    const security = scoreDelta(previous.security, now.security);
+    const perf = scoreDelta(previous.perf, now.perf);
+    return {
+        previous: {
+            ...(previous.ref !== undefined && { ref: previous.ref }),
+            ...(previous.generatedAt !== undefined && { generatedAt: previous.generatedAt }),
+            ...(previous.version !== undefined && { version: previous.version }),
+            ...(previous.provenance !== undefined && { provenance: previous.provenance })
+        },
+        ...(security && { security }),
+        ...(perf && { perf }),
+        summary,
+        rules,
+        unchanged: rules.length === 0
+            && (security?.delta ?? 0) === 0
+            && (perf?.delta ?? 0) === 0
+            && SEVERITIES.every((sev) => summary[sev].delta === 0)
+    };
+}
+/**
+ * `+2.3` / `−1.4` / `0`, with a real minus sign. Rendering-only, but shared:
+ * the markdown and pretty renderers must not disagree about which direction a
+ * number moved.
+ */
+function formatDelta(delta, digits = 0) {
+    if (delta === 0)
+        return '0';
+    const magnitude = Math.abs(delta).toFixed(digits);
+    return delta > 0 ? `+${magnitude}` : `−${magnitude}`;
+}
+/** `13.6 days` / `3.2 hours` / `41 minutes` — an age a human reads at a glance. */
+function formatAge(ms) {
+    const minutes = ms / 60000;
+    if (minutes < 90) {
+        const rounded = Math.round(minutes);
+        return `${rounded} minute${rounded === 1 ? '' : 's'}`;
+    }
+    const hours = minutes / 60;
+    if (hours < 48)
+        return `${hours.toFixed(1)} hours`;
+    return `${(hours / 24).toFixed(1)} days`;
+}
+/**
+ * "main@af904c90d — [run 33373344814](…), 10.2 hours old" — the one line every
+ * renderer puts above a delta, so the job summary, the PR comment and the
+ * terminal cannot describe different baselines.
+ *
+ * The age falls back to `generatedAt` when the provider did not measure one:
+ * the report timestamp is what a scanner always has.
+ */
+function describeBaseline(previous, options = {}) {
+    const p = previous.provenance ?? {};
+    const label = baselineLabel(previous);
+    const parts = [];
+    if (p.runId) {
+        parts.push(p.runUrl && options.link !== false ? `[run ${p.runId}](${p.runUrl})` : `run ${p.runId}`);
+    }
+    const age = p.age ?? ageOf(previous.generatedAt, options.now);
+    if (age)
+        parts.push(`${age} old`);
+    const detail = parts.length > 0 ? ` — ${parts.join(', ')}` : '';
+    return `${label}${detail}`;
+}
+/**
+ * `main@af904c90d`, or just `main` when no commit is known — the short name of
+ * the baseline, for a place too narrow for the run and the age.
+ */
+function baselineLabel(previous) {
+    const sha = previous.provenance?.sha;
+    const ref = previous.ref ?? previous.generatedAt ?? 'the previous run';
+    return sha ? `${previous.ref ?? 'previous'}@${sha.slice(0, 9)}` : ref;
+}
+function ageOf(generatedAt, now = Date.now()) {
+    if (!generatedAt)
+        return undefined;
+    const ms = now - Date.parse(generatedAt);
+    return ms >= 0 ? formatAge(ms) : undefined;
+}