safegres 1.22.0 → 1.23.0

package/README.md

@@ -442,6 +442,13 @@ job summary, annotations and a sticky PR comment:
           upload-sarif: true     # code scanning (needs security-events: write)
 ```
 
+On a pull request it also measures the delta for you: it picks the base branch's most recent run
+that *is* a sane comparison — succeeded, younger than 48 hours, and audited a commit in this
+branch's merge-base history — downloads its report, and names the run it chose in the summary and
+the comment (`actions: read`). "The last successful run" is not that: an unvalidated `gh run list
+--limit 1` once handed a PR a 13.6-day-old baseline and billed it for ~150 merges it never
+contained. Nothing qualifying is not a failure — no deltas, a line saying why, gates unchanged.
+
 It exposes `security-score`, `security-grade` and `perf-score` as step outputs — on a failing run
 too, which is when they get read. Everything else stays in the config file; see
 **[docs/reporting.md](https://github.com/constructive-io/constructive/blob/main/packages/safegres/docs/reporting.md#the-action)**.
@@ -781,6 +788,7 @@ safegres lint           # alias for audit, for a package.json script
 safegres perf           # audit + the performance dimension (= audit --perf)
 safegres doctor         # diagnose config, parser, connection, catalog visibility, exposure
 safegres eval           # grade the auditor against a corpus with known answers
+safegres baseline       # CI: pick the report this run's delta is measured against
 safegres print-config   # the resolved effective config (--explain for per-key provenance)
 ```
 
@@ -792,6 +800,7 @@ safegres print-config   # the resolved effective config (--explain for per-key p
 | Scope | `--schemas`, `--exclude-schemas`, `--roles`, `--exclude-roles`, `--ignore-extensions`, `--audit-extension-owned` |
 | Performance | `--perf`, `--stats`, `--explain`, `--perf-baseline <f>`, `--write-perf-baseline <f>`, `--fail-on-new-perf` |
 | Reporting | `--format pretty\|json\|json-pretty\|markdown\|sarif`, `--out <dir>`, `--sarif-sources <dir>`, `--summary`/`-q`, `--verbose`, `--compare <f>`, `--compare-ref <label>`, `--write-snapshot <f>` |
+| Delta provenance | `--compare-sha <sha>`, `--compare-run-id <id>`, `--compare-run-url <url>`, `--compare-age <age>`, `--compare-skipped <why>` |
 | Call graph | `--call-graph`, `--baseline <f>`, `--write-baseline <f>`, `--fail-on-new-boundaries` |
 | Gating | `--fail-on <severity>`, `--fail-on-score <n>`, `--fail-on-grade <g>`, `--fail-on-perf-score`, `--fail-on-perf-grade`, `--report-only` |
 | Misc | `--skip-ast`, `--no-color`, `--help`, `--version` |

package/ci/baseline.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Which report a delta is measured against — chosen, validated, explained.
+ *
+ * A comparison is only as trustworthy as the artifact it subtracts, and CI
+ * picking that artifact is where it goes wrong. The shape everyone writes is a
+ * one-row query for the base branch's last successful run:
+ *
+ *   gh run list --workflow ci.yaml --branch main --status success --limit 1
+ *
+ * `--limit 1` is `per_page=1`, so one API row decides the baseline with nothing
+ * checking it and nothing printing which row it was. Observed cost, on the PR
+ * this module was written for: that query answered with a `main` run 13.6 days
+ * and ~150 successful runs stale, and a PR touching no SQL at all was reported
+ * as `Δ vs main: ▼ −0.8, findings 2877 → 3323` — every merge since. A finished,
+ * correct run existed; the artifacts had not expired. An unvalidated answer was
+ * simply trusted.
+ *
+ * The fix is not a cleverer query. This takes several candidates and picks the
+ * newest that survives three questions:
+ *
+ *   1. did it succeed, and is its report artifact still downloadable?
+ *   2. is it younger than `maxAgeMs`?
+ *   3. is its head commit an ancestor of this branch's merge base with the base?
+ *
+ * (3) is what makes the delta mean "what this branch did": a baseline from the
+ * tip of the base branch *after* the branch point charges the branch for merges
+ * it never contained, and one from rewritten or unrelated history is not
+ * comparable at all. (2) catches a stale baseline that is a legitimate ancestor.
+ *
+ * No acceptable candidate is not a failure — it is a report with no deltas and
+ * a stated reason (`--compare-skipped`). The absolute grade gate and the perf
+ * ratchet never read the comparison, so they still apply.
+ *
+ * This module is pure and provider-agnostic: ancestry and artifact download
+ * arrive as callbacks, which is what makes the decision testable without a
+ * network. `./github` supplies them from GitHub Actions.
+ */
+/** One run of the base branch, as a provider lists them (newest first). */
+export interface BaselineCandidate {
+    /** Provider's id for the run, as it appears in a URL. */
+    runId: string;
+    /** Commit the run audited. */
+    headSha: string;
+    /** ISO 8601. When the run finished, or started if that is all there is. */
+    finishedAt: string;
+    /** `success` qualifies; anything else (including in-progress) does not. */
+    conclusion: string | null;
+}
+export interface SelectBaselineOptions {
+    /** The branch point this comparison must be relative to. */
+    mergeBaseSha: string;
+    /** Is `sha` in the merge base's history? */
+    isAncestor: (sha: string) => boolean;
+    /** Fetch a candidate's report; null when the artifact is gone. */
+    download: (candidate: BaselineCandidate) => string | null;
+    now?: number;
+    maxAgeMs?: number;
+}
+export interface RejectedCandidate {
+    runId: string;
+    headSha: string;
+    reason: string;
+}
+export interface ChosenBaseline extends BaselineCandidate {
+    /** Age at selection time, in milliseconds. */
+    ageMs: number;
+    /** Path to the downloaded report. */
+    path: string;
+}
+export interface BaselineSelection {
+    chosen: ChosenBaseline | null;
+    rejected: RejectedCandidate[];
+    /** One line for the job summary when `chosen` is null. */
+    reason: string | null;
+}
+/**
+ * How stale a baseline may be by default: 48 hours.
+ *
+ * The window has to be wider than the gap between two base-branch runs, or a
+ * branch loses its delta for no reason. Those runs are per merge, so the gap is
+ * activity rather than a schedule: on the repository this was measured against,
+ * `main` averaged well under an hour between successful runs on a working day
+ * and went ~24 hours over a weekend. 48 hours clears the widest observed quiet
+ * stretch with room to spare, while still being a *comparison* — anything older
+ * describes a schema several merges removed from the branch point.
+ */
+export declare const MAX_BASELINE_AGE_MS: number;
+/**
+ * How many runs to consider by default.
+ *
+ * More than one on principle — trusting a single row is the bug — and enough
+ * that an in-progress tip, a cancelled run and a couple of expired artifacts
+ * can all be skipped without falling out of the age window. Beyond ~20 the
+ * candidates are older than the window anyway, so they cost a request to
+ * reject.
+ */
+export declare const CANDIDATE_LIMIT = 20;
+/**
+ * The newest candidate that is a sane comparison, and why the others were not.
+ *
+ * `isAncestor` and `download` are I/O in CI and stubs in tests, and are only
+ * asked about a candidate that already passed the cheap checks.
+ */
+export declare function selectBaseline(candidates: BaselineCandidate[], options: SelectBaselineOptions): BaselineSelection;

package/ci/baseline.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * Which report a delta is measured against — chosen, validated, explained.
+ *
+ * A comparison is only as trustworthy as the artifact it subtracts, and CI
+ * picking that artifact is where it goes wrong. The shape everyone writes is a
+ * one-row query for the base branch's last successful run:
+ *
+ *   gh run list --workflow ci.yaml --branch main --status success --limit 1
+ *
+ * `--limit 1` is `per_page=1`, so one API row decides the baseline with nothing
+ * checking it and nothing printing which row it was. Observed cost, on the PR
+ * this module was written for: that query answered with a `main` run 13.6 days
+ * and ~150 successful runs stale, and a PR touching no SQL at all was reported
+ * as `Δ vs main: ▼ −0.8, findings 2877 → 3323` — every merge since. A finished,
+ * correct run existed; the artifacts had not expired. An unvalidated answer was
+ * simply trusted.
+ *
+ * The fix is not a cleverer query. This takes several candidates and picks the
+ * newest that survives three questions:
+ *
+ *   1. did it succeed, and is its report artifact still downloadable?
+ *   2. is it younger than `maxAgeMs`?
+ *   3. is its head commit an ancestor of this branch's merge base with the base?
+ *
+ * (3) is what makes the delta mean "what this branch did": a baseline from the
+ * tip of the base branch *after* the branch point charges the branch for merges
+ * it never contained, and one from rewritten or unrelated history is not
+ * comparable at all. (2) catches a stale baseline that is a legitimate ancestor.
+ *
+ * No acceptable candidate is not a failure — it is a report with no deltas and
+ * a stated reason (`--compare-skipped`). The absolute grade gate and the perf
+ * ratchet never read the comparison, so they still apply.
+ *
+ * This module is pure and provider-agnostic: ancestry and artifact download
+ * arrive as callbacks, which is what makes the decision testable without a
+ * network. `./github` supplies them from GitHub Actions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CANDIDATE_LIMIT = exports.MAX_BASELINE_AGE_MS = void 0;
+exports.selectBaseline = selectBaseline;
+const compare_1 = require("../report/compare");
+/**
+ * How stale a baseline may be by default: 48 hours.
+ *
+ * The window has to be wider than the gap between two base-branch runs, or a
+ * branch loses its delta for no reason. Those runs are per merge, so the gap is
+ * activity rather than a schedule: on the repository this was measured against,
+ * `main` averaged well under an hour between successful runs on a working day
+ * and went ~24 hours over a weekend. 48 hours clears the widest observed quiet
+ * stretch with room to spare, while still being a *comparison* — anything older
+ * describes a schema several merges removed from the branch point.
+ */
+exports.MAX_BASELINE_AGE_MS = 48 * 60 * 60 * 1000;
+/**
+ * How many runs to consider by default.
+ *
+ * More than one on principle — trusting a single row is the bug — and enough
+ * that an in-progress tip, a cancelled run and a couple of expired artifacts
+ * can all be skipped without falling out of the age window. Beyond ~20 the
+ * candidates are older than the window anyway, so they cost a request to
+ * reject.
+ */
+exports.CANDIDATE_LIMIT = 20;
+const short = (sha) => (sha || '').slice(0, 9);
+/**
+ * The newest candidate that is a sane comparison, and why the others were not.
+ *
+ * `isAncestor` and `download` are I/O in CI and stubs in tests, and are only
+ * asked about a candidate that already passed the cheap checks.
+ */
+function selectBaseline(candidates, options) {
+    const { mergeBaseSha, isAncestor, download, now = Date.now(), maxAgeMs = exports.MAX_BASELINE_AGE_MS } = options;
+    const rejected = [];
+    const reject = (run, why) => {
+        rejected.push({ runId: run.runId, headSha: run.headSha, reason: why });
+    };
+    for (const run of candidates) {
+        if (run.conclusion !== 'success') {
+            reject(run, `conclusion ${run.conclusion || 'pending'}`);
+            continue;
+        }
+        const ageMs = now - Date.parse(run.finishedAt);
+        if (!(ageMs >= 0)) {
+            reject(run, `unreadable timestamp ${run.finishedAt}`);
+            continue;
+        }
+        if (ageMs > maxAgeMs) {
+            reject(run, `${(0, compare_1.formatAge)(ageMs)} old, older than the ${(0, compare_1.formatAge)(maxAgeMs)} window`);
+            continue;
+        }
+        if (!isAncestor(run.headSha)) {
+            reject(run, `${short(run.headSha)} is not an ancestor of merge base ${short(mergeBaseSha)}`);
+            continue;
+        }
+        const path = download(run);
+        if (!path) {
+            reject(run, 'no downloadable report artifact');
+            continue;
+        }
+        return { chosen: { ...run, ageMs, path }, rejected, reason: null };
+    }
+    return {
+        chosen: null,
+        rejected,
+        reason: candidates.length > 0
+            ? `no run within ${(0, compare_1.formatAge)(maxAgeMs)} whose head is an ancestor of merge base `
+                + `${short(mergeBaseSha)} (${rejected.length} candidate(s) rejected)`
+            : 'no runs to compare against'
+    };
+}

package/ci/github.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The GitHub Actions half of baseline selection: run discovery, merge base,
+ * artifact download. Everything provider-shaped lives here, so `./baseline`
+ * stays a pure decision and the report layer never learns what a workflow run
+ * is.
+ *
+ * The I/O goes through the `gh` CLI, which every GitHub-hosted runner has and
+ * which already handles pagination, auth from `GITHUB_TOKEN`, and unzipping an
+ * artifact. Reaching the API needs `permissions: actions: read`.
+ */
+import { type BaselineSelection } from './baseline';
+export interface GithubBaselineOptions {
+    /** `owner/repo`. Default `$GITHUB_REPOSITORY`. */
+    repo?: string;
+    /** Branch whose runs are candidates — the PR's base. Default from the event. */
+    base?: string;
+    /** The branch tip to find the merge base of. Default from the event. */
+    headSha?: string;
+    /** Workflow file whose runs produced the reports. Default the current one. */
+    workflow?: string;
+    /** Artifact holding `safegres.json`. Default `safegres-reports`. */
+    artifact?: string;
+    /** Where to unpack it. Default `previous`. */
+    dir?: string;
+    maxAgeMs?: number;
+    candidateLimit?: number;
+    now?: number;
+    /** Where the selection log goes. Default stdout. */
+    log?: (line: string) => void;
+}
+/** What the caller needs to turn a selection into `safegres audit` flags. */
+export interface GithubBaselineResult extends BaselineSelection {
+    base: string;
+    mergeBaseSha: string;
+    /** `https://github.com/<repo>/actions/runs/<id>`, when one was chosen. */
+    runUrl?: string;
+    /** Pre-formatted age of the chosen run. */
+    age?: string;
+}
+/**
+ * Select a baseline report from the base branch's recent runs.
+ *
+ * Throws only on a broken invocation (no repository, no PR context, `gh`
+ * missing). A candidate that cannot be used is rejected, not fatal: the caller
+ * renders the report without deltas and says why.
+ */
+export declare function selectGithubBaseline(options?: GithubBaselineOptions): GithubBaselineResult;

package/ci/github.js

@@ -0,0 +1,197 @@
+"use strict";
+/**
+ * The GitHub Actions half of baseline selection: run discovery, merge base,
+ * artifact download. Everything provider-shaped lives here, so `./baseline`
+ * stays a pure decision and the report layer never learns what a workflow run
+ * is.
+ *
+ * The I/O goes through the `gh` CLI, which every GitHub-hosted runner has and
+ * which already handles pagination, auth from `GITHUB_TOKEN`, and unzipping an
+ * artifact. Reaching the API needs `permissions: actions: read`.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectGithubBaseline = selectGithubBaseline;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const compare_1 = require("../report/compare");
+const baseline_1 = require("./baseline");
+const short = (sha) => sha.slice(0, 9);
+const gh = (args) => (0, child_process_1.execFileSync)('gh', args, { encoding: 'utf8' });
+/**
+ * `gh run` needs `-R` explicitly: the workspace may be an unpacked artifact
+ * with no `.git` for it to infer the repository from. `gh api` carries the
+ * repository in the path and rejects the flag.
+ */
+const ghRun = (repo, args) => gh(['run', ...args, '-R', repo]);
+/** The workflow file of the run this is called from, e.g. `run-tests.yaml`. */
+function currentWorkflow() {
+    const ref = process.env.GITHUB_WORKFLOW_REF; // owner/repo/.github/workflows/x.yml@refs/…
+    if (!ref)
+        return undefined;
+    const file = ref.split('@')[0].split('/').pop();
+    return file || undefined;
+}
+/** The PR's head sha, from the event payload the runner wrote to disk. */
+function eventHeadSha() {
+    const file = process.env.GITHUB_EVENT_PATH;
+    if (!file || !fs.existsSync(file))
+        return undefined;
+    const event = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return event.pull_request?.head?.sha;
+}
+function eventBaseRef() {
+    const file = process.env.GITHUB_EVENT_PATH;
+    if (!file || !fs.existsSync(file))
+        return undefined;
+    const event = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return event.pull_request?.base?.ref ?? process.env.GITHUB_BASE_REF;
+}
+/**
+ * The path, if it holds a report a delta can be measured against — an artifact
+ * that exists but is truncated or from an incompatible version would otherwise
+ * fail the audit at compare time, which is the one thing a baseline lookup must
+ * never do.
+ */
+function readableReport(file, log) {
+    if (!fs.existsSync(file)) {
+        log(`artifact holds no ${path.basename(file)}`);
+        return null;
+    }
+    try {
+        const report = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (report.summary === undefined)
+            throw new Error('no summary');
+        return file;
+    }
+    catch (err) {
+        log(`unusable report — ${err.message}`);
+        return null;
+    }
+}
+/**
+ * Select a baseline report from the base branch's recent runs.
+ *
+ * Throws only on a broken invocation (no repository, no PR context, `gh`
+ * missing). A candidate that cannot be used is rejected, not fatal: the caller
+ * renders the report without deltas and says why.
+ */
+function selectGithubBaseline(options = {}) {
+    const log = options.log ?? ((line) => console.log(line));
+    const repo = options.repo ?? process.env.GITHUB_REPOSITORY;
+    const base = options.base ?? eventBaseRef();
+    const headSha = options.headSha ?? eventHeadSha() ?? process.env.GITHUB_SHA;
+    const workflow = options.workflow ?? currentWorkflow();
+    const artifact = options.artifact ?? 'safegres-reports';
+    const dir = path.resolve(options.dir ?? 'previous');
+    if (!repo)
+        throw new Error('GITHUB_REPOSITORY is not set: pass --repo owner/repo');
+    if (!base)
+        throw new Error('no base branch: pass --base (this is a pull-request-only feature)');
+    if (!headSha)
+        throw new Error('no head commit: pass --head <sha>');
+    if (!workflow)
+        throw new Error('no workflow: pass --workflow <file.yaml>');
+    // The branch point, from the API rather than `git merge-base`: the audit job
+    // may not have checked the repository out, and a shallow clone has no history.
+    const mergeBaseSha = JSON.parse(gh(['api', `repos/${repo}/compare/${base}...${headSha}`])).merge_base_commit.sha;
+    log(`merge base with ${base}: ${short(mergeBaseSha)}`);
+    const runs = JSON.parse(ghRun(repo, [
+        'list',
+        '--workflow',
+        workflow,
+        '--branch',
+        base,
+        '--limit',
+        String(options.candidateLimit ?? baseline_1.CANDIDATE_LIMIT),
+        '--json',
+        'databaseId,headSha,createdAt,updatedAt,conclusion'
+    ]));
+    const candidates = runs.map((r) => ({
+        runId: String(r.databaseId),
+        headSha: r.headSha,
+        // `updatedAt` is when the run concluded; `createdAt` until GitHub records it.
+        finishedAt: r.updatedAt || r.createdAt,
+        conclusion: r.conclusion
+    }));
+    const ancestry = new Map();
+    const isAncestor = (sha) => {
+        if (!ancestry.has(sha)) {
+            // `ahead` = the merge base is ahead of the candidate, i.e. the candidate
+            // is in its history; `identical` = the baseline *is* the branch point, the
+            // ideal case. `behind`/`diverged` are the ones to refuse.
+            const status = JSON.parse(gh(['api', `repos/${repo}/compare/${sha}...${mergeBaseSha}`])).status;
+            ancestry.set(sha, status === 'ahead' || status === 'identical');
+        }
+        return ancestry.get(sha) === true;
+    };
+    const download = (run) => {
+        // Emptied first: successive candidates unpack into the same directory, and a
+        // leftover report from a rejected one would make the next candidate look
+        // usable and put the wrong run's numbers in the delta.
+        fs.rmSync(dir, { recursive: true, force: true });
+        try {
+            ghRun(repo, ['download', run.runId, '-n', artifact, '-D', dir]);
+        }
+        catch (err) {
+            // The one ignorable failure here: an expired or never-uploaded artifact is
+            // a rejected candidate, not a broken job. Anything else (auth, network)
+            // fails the same way on the next candidate and surfaces as "no baseline".
+            log(`  ${run.runId}: artifact download failed — ${String(err.message).trim()}`);
+            return null;
+        }
+        return readableReport(path.join(dir, 'safegres.json'), (why) => log(`  ${run.runId}: ${why}`));
+    };
+    const selection = (0, baseline_1.selectBaseline)(candidates, {
+        mergeBaseSha,
+        isAncestor,
+        download,
+        ...(options.now !== undefined && { now: options.now }),
+        maxAgeMs: options.maxAgeMs ?? baseline_1.MAX_BASELINE_AGE_MS
+    });
+    for (const r of selection.rejected) {
+        log(`rejected ${r.runId} (${short(r.headSha)}): ${r.reason}`);
+    }
+    if (!selection.chosen) {
+        log(`no comparison baseline: ${selection.reason}`);
+        return { ...selection, base, mergeBaseSha };
+    }
+    const age = (0, compare_1.formatAge)(selection.chosen.ageMs);
+    const runUrl = `${process.env.GITHUB_SERVER_URL ?? 'https://github.com'}/${repo}/actions/runs/${selection.chosen.runId}`;
+    log(`baseline: run ${selection.chosen.runId} ${base}@${short(selection.chosen.headSha)}, `
+        + `${age} old (${selection.chosen.finishedAt})`);
+    return { ...selection, base, mergeBaseSha, runUrl, age };
+}

package/cli/audit.js

@@ -139,6 +139,14 @@ Comparison with a previous run (what changed, not just what is):
                            snapshot written by --write-snapshot
   --compare-ref <label>    How to name the previous run in the report
                            (e.g. "main", a commit sha). Default "previous run"
+  --compare-sha <sha>      Commit the previous run was produced from
+  --compare-run-id <id>    CI run that produced it
+  --compare-run-url <url>  Link to that run
+  --compare-age <age>      How old it is, pre-formatted ("10.2 hours").
+                           Defaults to the age of its generatedAt
+  --compare-skipped <why>  There is no baseline and this is the reason, shown
+                           in place of the delta so an absent delta does not
+                           read as "nothing changed"
   --write-snapshot <file>  Write the aggregate slice of this run (scores,
                            counts, per-rule counts) for a later --compare,
                            when keeping the whole report is too much
@@ -325,8 +333,14 @@ exports.default = async (argv, _prompter, _options) => {
         }
         if (typeof argv['compare-ref'] === 'string')
             previous.ref = argv['compare-ref'];
+        const provenance = baselineProvenance(argv);
+        if (provenance)
+            previous.provenance = { ...previous.provenance, ...provenance };
         report.comparison = (0, compare_1.compareReports)(previous, report);
     }
+    else if (typeof argv['compare-skipped'] === 'string' && argv['compare-skipped'] !== '') {
+        report.comparisonSkipped = argv['compare-skipped'];
+    }
     if (callGraphBaseline !== undefined && report.callGraph) {
         let raw;
         try {
@@ -516,6 +530,21 @@ exports.default = async (argv, _prompter, _options) => {
     if (failed)
         log.warn('--report-only: gates failed, exiting 0');
 };
+/**
+ * Where the baseline came from, as the provider reported it. A provider is
+ * whatever chose the file — a CI adapter, a script, a person — so every field
+ * is optional and none of them mean anything to safegres beyond being printed.
+ */
+function baselineProvenance(argv) {
+    const str = (flag) => typeof argv[flag] === 'string' && argv[flag] !== '' ? argv[flag] : undefined;
+    const provenance = {
+        ...(str('compare-sha') && { sha: str('compare-sha') }),
+        ...(str('compare-run-id') && { runId: str('compare-run-id') }),
+        ...(str('compare-run-url') && { runUrl: str('compare-run-url') }),
+        ...(str('compare-age') && { age: str('compare-age') })
+    };
+    return Object.keys(provenance).length > 0 ? provenance : undefined;
+}
 /** Write an output file, creating its directory: CI should not have to mkdir. */
 function writeOut(file, contents) {
     fs.mkdirSync(path.dirname(path.resolve(file)), { recursive: true });

package/cli/baseline.d.ts

@@ -0,0 +1,3 @@
+import { CLIOptions, Inquirerer, ParsedArgs } from 'inquirerer';
+declare const _default: (argv: ParsedArgs, _prompter: Inquirerer, _options: CLIOptions) => Promise<void>;
+export default _default;

package/cli/baseline.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const logger_1 = require("@pgpmjs/logger");
+const fs_1 = require("fs");
+const baseline_1 = require("../ci/baseline");
+const github_1 = require("../ci/github");
+const log = new logger_1.Logger('safegres');
+const usage = `
+safegres baseline — choose the report a delta is measured against
+
+  safegres baseline --provider github [OPTIONS]
+
+Finds the base branch's most recent run that is a sane comparison — succeeded,
+young enough, and audited a commit in this branch's merge-base history — and
+downloads its report. When nothing qualifies it says why and exits 0: the audit
+then runs with no deltas, and the absolute gates still apply.
+
+The result is written to $GITHUB_OUTPUT when the runner provides one, as
+compare / compare-ref / compare-sha / compare-run-id / compare-run-url /
+compare-age / compare-skipped — the same names \`safegres audit\` takes as
+flags, so the next step is \`--compare "\${{ steps.<id>.outputs.compare }}"\`.
+
+Options:
+  --provider <name>        Where the runs live. Only "github" today
+  --repo <owner/repo>      Default $GITHUB_REPOSITORY
+  --base <ref>             Base branch whose runs are candidates
+                           (default: the pull request's base)
+  --head <sha>             Branch tip to take the merge base of
+                           (default: the pull request's head)
+  --workflow <file>        Workflow file that produced the reports
+                           (default: the workflow this runs in)
+  --artifact <name>        Artifact holding safegres.json
+                           (default: safegres-reports)
+  --dir <dir>              Where to unpack it (default: previous)
+  --max-age-hours <n>      Staleness limit (default: ${baseline_1.MAX_BASELINE_AGE_MS / 3600000})
+  --candidates <n>         Runs to consider (default: ${baseline_1.CANDIDATE_LIMIT})
+  --json                   Print the selection as JSON
+  --help, -h               Show this help message
+
+Needs \`permissions: actions: read\` to list runs and download artifacts.
+`;
+/** `key=value` into a GitHub Actions file, or stdout when running locally. */
+function emit(file, key, value) {
+    const line = `${key}=${value}`;
+    if (file)
+        (0, fs_1.appendFileSync)(file, `${line}\n`);
+    else
+        process.stdout.write(`(${key}) ${value}\n`);
+}
+function publish(result) {
+    const file = process.env.GITHUB_OUTPUT;
+    if (result.chosen) {
+        emit(file, 'compare', result.chosen.path);
+        emit(file, 'compare-ref', result.base);
+        emit(file, 'compare-sha', result.chosen.headSha);
+        emit(file, 'compare-run-id', result.chosen.runId);
+        if (result.runUrl)
+            emit(file, 'compare-run-url', result.runUrl);
+        if (result.age)
+            emit(file, 'compare-age', result.age);
+    }
+    else {
+        emit(file, 'compare-skipped', result.reason ?? 'no baseline');
+    }
+}
+exports.default = async (argv, _prompter, _options) => {
+    if (argv.help || argv.h) {
+        process.stdout.write(usage);
+        return;
+    }
+    const provider = typeof argv.provider === 'string' ? argv.provider : 'github';
+    if (provider !== 'github') {
+        log.error(`unknown --provider ${provider} (only "github" is implemented)`);
+        process.exit(2);
+    }
+    const hours = Number(argv['max-age-hours']);
+    const candidates = Number(argv.candidates);
+    let result;
+    try {
+        result = (0, github_1.selectGithubBaseline)({
+            ...(typeof argv.repo === 'string' && { repo: argv.repo }),
+            ...(typeof argv.base === 'string' && { base: argv.base }),
+            ...(typeof argv.head === 'string' && { headSha: argv.head }),
+            ...(typeof argv.workflow === 'string' && { workflow: argv.workflow }),
+            ...(typeof argv.artifact === 'string' && { artifact: argv.artifact }),
+            ...(typeof argv.dir === 'string' && { dir: argv.dir }),
+            ...(Number.isFinite(hours) && hours > 0 && { maxAgeMs: hours * 3600000 }),
+            ...(Number.isFinite(candidates) && candidates > 0 && { candidateLimit: candidates })
+        });
+    }
+    catch (err) {
+        // Fail-soft, loudly: a missing PR context, a token without `actions: read`
+        // or a `gh` that is not installed must not fail an audit that is perfectly
+        // able to run without deltas — but the reason travels into the report as
+        // the skip message rather than being swallowed.
+        const message = err.message.trim();
+        log.error(`no comparison baseline: ${message}`);
+        publish({ chosen: null, rejected: [], reason: message, base: '', mergeBaseSha: '' });
+        return;
+    }
+    publish(result);
+    if (argv.json === true)
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+};