@safegres/test 0.0.1 → 1.30.7

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.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;