vouchington-tooling 0.0.2 → 0.0.4

package/README.md

@@ -16,6 +16,7 @@ vouchington runner-port-policy
 vouchington runner-port-policy --file ./policy.json
 vouchington runner-port-policy --reserved 2200
 vouchington with-host-lock --name expensive-build --timeout-seconds 60 -- make build
+vouchington gha-runtime-audit --pr-workflow CI --push-workflow '/^Main CI \\(.+\\)$/'
 ```
 
 Host-lock environment:
@@ -35,4 +36,7 @@ import {
   listenOnRunnerUnreservedEphemeralPort,
   runnerPortPolicy,
 } from 'vouchington-tooling/runner-port-policy'
+import { initSqlAst, extractCreateTableMetadata } from 'vouchington-tooling/sql-ast'
+import { splitSqlStatements, stripSqlComments } from 'vouchington-tooling/sql-scanner'
+import { auditCiJobRuntime } from 'vouchington-tooling/gha-runtime-audit'
 ```

package/dist/cli/commands/gha-runtime-audit.d.mts

@@ -0,0 +1,3 @@
+import { type GhApiExecutor } from '../../gha-runtime-audit/index.mts';
+import type { ParsedGhaRuntimeAudit } from '../parse-gha-runtime-audit.mts';
+export declare function runGhaRuntimeAudit(parsed: ParsedGhaRuntimeAudit, execute?: GhApiExecutor, env?: NodeJS.ProcessEnv): Promise<number>;

package/dist/cli/commands/gha-runtime-audit.mjs

@@ -0,0 +1,23 @@
+import { execFileSync } from 'node:child_process';
+import { auditCiJobRuntime } from '../../gha-runtime-audit/index.mjs';
+/* v8 ignore next 10 -- live `gh api` adapter */
+function defaultGhApiExecutor() {
+    return async (request) => JSON.parse(execFileSync('gh', ['api', request.endpoint, '--jq', request.jq], {
+        encoding: 'utf8',
+        maxBuffer: 16 * 1024 * 1024,
+    }));
+}
+export async function runGhaRuntimeAudit(parsed, execute = defaultGhApiExecutor(), env = process.env) {
+    const repository = parsed.repository ?? env['GITHUB_REPOSITORY'];
+    if (!repository) {
+        process.stderr.write('vouchington: --repository or GITHUB_REPOSITORY is required\n');
+        return 2;
+    }
+    const result = await auditCiJobRuntime(execute, {
+        repository,
+        workflows: parsed.workflows,
+        ...(parsed.branch === undefined ? {} : { branch: parsed.branch }),
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return 0;
+}

package/dist/cli/index.d.mts

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-export declare function runCli(argv?: readonly string[]): number;
+export declare function runCli(argv?: readonly string[]): number | Promise<number>;
 export declare function isMainModule(metaUrl: string, argv1: string | undefined): boolean;

package/dist/cli/index.mjs

@@ -3,6 +3,7 @@ import { readFileSync, realpathSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { readPackageVersion } from '../package-version.mjs';
+import { runGhaRuntimeAudit } from './commands/gha-runtime-audit.mjs';
 import { runRunnerPortPolicy } from './commands/runner-port-policy.mjs';
 import { runWithHostLock } from './commands/with-host-lock.mjs';
 import { parseCli } from './parse.mjs';
@@ -24,6 +25,8 @@ export function runCli(argv = process.argv) {
             return runRunnerPortPolicy(parsed);
         case 'with-host-lock':
             return runWithHostLock(parsed.args);
+        case 'gha-runtime-audit':
+            return runGhaRuntimeAudit(parsed);
     }
 }
 function readInstalledVersion() {
@@ -39,7 +42,17 @@ export function isMainModule(metaUrl, argv1) {
         return metaUrl === pathToFileURL(resolve(argv1)).href;
     }
 }
-/* v8 ignore next 3 */
+/* v8 ignore next 8 */
 if (isMainModule(import.meta.url, process.argv[1])) {
-    process.exitCode = runCli();
+    const result = runCli();
+    if (typeof result === 'number')
+        process.exitCode = result;
+    else {
+        result.then((code) => {
+            process.exitCode = code;
+        }, (error) => {
+            process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+            process.exitCode = 1;
+        });
+    }
 }

package/dist/cli/parse-gha-runtime-audit.d.mts

@@ -0,0 +1,13 @@
+import { type RuntimeAuditWorkflowFilter } from '../gha-runtime-audit/scope.mts';
+export type ParsedGhaRuntimeAudit = {
+    kind: 'gha-runtime-audit';
+    repository?: string;
+    branch?: string;
+    workflows: RuntimeAuditWorkflowFilter[];
+};
+export declare function parseGhaRuntimeAudit(args: readonly string[]): ParsedGhaRuntimeAudit | {
+    kind: 'help';
+} | {
+    kind: 'error';
+    message: string;
+};

package/dist/cli/parse-gha-runtime-audit.mjs

@@ -0,0 +1,44 @@
+import { parseWorkflowNameMatch, } from '../gha-runtime-audit/scope.mjs';
+export function parseGhaRuntimeAudit(args) {
+    let repository;
+    let branch;
+    const workflows = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const flag = args[index];
+        if (flag === '--help' || flag === '-h')
+            return { kind: 'help' };
+        if (flag === '--repository' ||
+            flag === '--pr-workflow' ||
+            flag === '--push-workflow' ||
+            flag === '--branch') {
+            const value = args[index + 1];
+            if (value === undefined)
+                return { kind: 'error', message: `${flag} requires a value` };
+            index += 1;
+            if (flag === '--repository')
+                repository = value;
+            else if (flag === '--branch')
+                branch = value;
+            else {
+                workflows.push({
+                    name: parseWorkflowNameMatch(value),
+                    event: flag === '--pr-workflow' ? 'pull_request' : 'push',
+                });
+            }
+            continue;
+        }
+        return { kind: 'error', message: `unknown gha-runtime-audit option: ${flag}` };
+    }
+    if (workflows.length === 0) {
+        return {
+            kind: 'error',
+            message: 'gha-runtime-audit requires --pr-workflow or --push-workflow',
+        };
+    }
+    return {
+        kind: 'gha-runtime-audit',
+        workflows,
+        ...(repository === undefined ? {} : { repository }),
+        ...(branch === undefined ? {} : { branch }),
+    };
+}

package/dist/cli/parse.d.mts

@@ -1,3 +1,4 @@
+import { type ParsedGhaRuntimeAudit } from './parse-gha-runtime-audit.mts';
 export type ParsedCli = {
     kind: 'help';
 } | {
@@ -12,5 +13,5 @@ export type ParsedCli = {
 } | {
     kind: 'with-host-lock';
     args: string[];
-};
+} | ParsedGhaRuntimeAudit;
 export declare function parseCli(argv: readonly string[]): ParsedCli;

package/dist/cli/parse.mjs

@@ -1,3 +1,4 @@
+import { parseGhaRuntimeAudit } from './parse-gha-runtime-audit.mjs';
 export function parseCli(argv) {
     const args = argv.slice(2);
     if (args.length === 0 || args[0] === '--help' || args[0] === '-h')
@@ -9,6 +10,8 @@ export function parseCli(argv) {
         return parseRunnerPortPolicy(rest);
     if (command === 'with-host-lock')
         return { kind: 'with-host-lock', args: rest };
+    if (command === 'gha-runtime-audit')
+        return parseGhaRuntimeAudit(rest);
     return { kind: 'error', message: `unknown command: ${command}` };
 }
 function parseRunnerPortPolicy(args) {

package/dist/cli/usage.d.mts

@@ -1,2 +1,2 @@
-export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n";
+export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit    Audit successful GitHub Actions job runtimes\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n";
 export declare function printUsage(stream?: NodeJS.WritableStream): void;

package/dist/cli/usage.mjs

@@ -3,6 +3,7 @@ export const USAGE = `Usage: vouchington <command> [options]
 Commands:
   runner-port-policy   Print or validate a runner port policy
   with-host-lock       Run a command under a host-wide lock
+  gha-runtime-audit    Audit successful GitHub Actions job runtimes
 
 Options:
   -h, --help       Show this help
@@ -21,6 +22,12 @@ with-host-lock
   [--failure-diagnostics <absolute-script>]
   [--on-acquire-timeout fail|run-unlocked]
   -- <command> [args...]
+
+gha-runtime-audit
+  [--repository owner/name]   Default GITHUB_REPOSITORY
+  [--branch main]
+  --pr-workflow <name|/regex/>     Repeatable
+  --push-workflow <name|/regex/>   Repeatable
 `;
 export function printUsage(stream = process.stdout) {
     stream.write(USAGE);

package/dist/gha-runtime-audit/audit.d.mts

@@ -0,0 +1,3 @@
+import { type GhApiExecutor, type RuntimeAuditResult } from './model.mts';
+import { type RuntimeAuditOptions } from './scope.mts';
+export declare function auditCiJobRuntime(execute: GhApiExecutor, options: RuntimeAuditOptions): Promise<RuntimeAuditResult>;

package/dist/gha-runtime-audit/audit.mjs

@@ -0,0 +1,106 @@
+import { parseArray, parseObject, parseRun, parseSample, parseWorkflow, } from './model.mjs';
+import { buildRuntimeResults } from './results.mjs';
+import { isRunInScope, isSelectedWorkflow, matchingWorkflowFilter, resolveRuntimeAuditOptions, } from './scope.mjs';
+async function discoverWorkflows(execute, options) {
+    const selected = [];
+    for (let page = 1;; page += 1) {
+        const response = parseObject(await execute({
+            endpoint: `/repos/${options.repository}/actions/workflows?per_page=100&page=${page}`,
+            jq: '{workflows: [.workflows[] | {id, name, state}]}',
+        }), 'workflows response must be an object');
+        const pageWorkflows = parseArray(response['workflows'], 'workflows must be an array');
+        for (const value of pageWorkflows) {
+            const workflow = parseWorkflow(value);
+            if (isSelectedWorkflow(workflow, options.workflows))
+                selected.push(workflow);
+        }
+        if (pageWorkflows.length < 100)
+            break;
+    }
+    return selected.toSorted((a, b) => a.name.localeCompare(b.name) || a.id - b.id);
+}
+function runsQuery(filter, branch) {
+    if (filter.event === 'push')
+        return `event=push&branch=${encodeURIComponent(branch)}`;
+    return 'event=pull_request';
+}
+async function recentRuns(execute, workflow, options) {
+    const selected = [];
+    const filter = matchingWorkflowFilter(workflow.name, options.workflows);
+    /* v8 ignore next */
+    if (!filter)
+        return selected;
+    const query = runsQuery(filter, options.branch);
+    for (let page = 1;; page += 1) {
+        const response = parseObject(await execute({
+            endpoint: `/repos/${options.repository}/actions/workflows/${workflow.id}/runs?${query}&status=completed&per_page=100&page=${page}`,
+            jq: '{workflow_runs: [.workflow_runs[] | {id, name, event, conclusion, created_at, html_url, head_branch, pull_requests: [(.pull_requests // [])[] | {base: {ref: .base.ref}}]}]}',
+        }), 'workflow runs response must be an object');
+        const pageRuns = parseArray(response['workflow_runs'], 'workflow_runs must be an array');
+        const inScope = [];
+        for (const value of pageRuns) {
+            const run = parseRun(value);
+            if (isRunInScope(run, filter, options.branch))
+                inScope.push(run);
+        }
+        inScope.sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt) || b.id - a.id);
+        for (const run of inScope) {
+            if (selected.length === options.recentCompletedRunHorizon)
+                break;
+            selected.push(run);
+        }
+        if (selected.length === options.recentCompletedRunHorizon || pageRuns.length < 100)
+            break;
+    }
+    return selected;
+}
+async function collectRunSamples(execute, options, run, samplesByKey) {
+    for (let page = 1;; page += 1) {
+        const response = parseObject(await execute({
+            endpoint: `/repos/${options.repository}/actions/runs/${run.id}/jobs?filter=latest&per_page=100&page=${page}`,
+            jq: '{jobs: [.jobs[] | {id, name, started_at, completed_at, conclusion, html_url}]}',
+        }), `jobs response for run ${run.id} must be an object`);
+        const jobs = parseArray(response['jobs'], `jobs for run ${run.id} must be an array`);
+        for (const value of jobs) {
+            const parsed = parseSample(value, run);
+            if (!parsed)
+                continue;
+            const key = `${run.name} / ${parsed.name}`;
+            const entry = samplesByKey.get(key) ?? {
+                workflow: run.name,
+                job: parsed.name,
+                samples: [],
+            };
+            if (entry.samples.length < options.sampleLimit)
+                entry.samples.push(parsed.sample);
+            samplesByKey.set(key, entry);
+        }
+        if (jobs.length < 100)
+            break;
+    }
+}
+export async function auditCiJobRuntime(execute, options) {
+    const resolved = resolveRuntimeAuditOptions(options);
+    const samplesByKey = new Map();
+    const seenRunIds = new Set();
+    for (const workflow of await discoverWorkflows(execute, resolved)) {
+        for (const run of await recentRuns(execute, workflow, resolved)) {
+            if (seenRunIds.has(run.id))
+                continue;
+            seenRunIds.add(run.id);
+            await collectRunSamples(execute, resolved, run, samplesByKey);
+        }
+    }
+    const results = buildRuntimeResults(samplesByKey, resolved);
+    return {
+        scope: {
+            repository: resolved.repository,
+            sampleLimit: resolved.sampleLimit,
+            recentCompletedRunHorizon: resolved.recentCompletedRunHorizon,
+            medianThresholdSeconds: resolved.medianThresholdSeconds,
+            hardCeilingSeconds: resolved.hardCeilingSeconds,
+            branch: resolved.branch,
+        },
+        ...results,
+    };
+}

package/dist/gha-runtime-audit/index.d.mts

@@ -0,0 +1,5 @@
+export { auditCiJobRuntime } from './audit.mts';
+export { violationOrder } from './results.mts';
+export type { GhApiExecutor, GhApiRequest, RuntimeAuditResult, RuntimeJobResult, RuntimeSample, RuntimeViolationReason, } from './model.mts';
+export { parseWorkflowNameMatch } from './scope.mts';
+export type { RuntimeAuditOptions, RuntimeAuditWorkflowFilter } from './scope.mts';

package/dist/gha-runtime-audit/index.mjs

@@ -0,0 +1,3 @@
+export { auditCiJobRuntime } from './audit.mjs';
+export { violationOrder } from './results.mjs';
+export { parseWorkflowNameMatch } from './scope.mjs';

package/dist/gha-runtime-audit/index.test-helpers.d.mts

@@ -0,0 +1,14 @@
+import type { GhApiExecutor } from './model.mts';
+import type { RuntimeAuditOptions } from './scope.mts';
+export type FixtureJob = {
+    id: number;
+    name: string;
+    started_at: string;
+    completed_at: string;
+    conclusion: 'success' | 'failure';
+    html_url: string;
+};
+export declare const exampleAuditOptions: Omit<RuntimeAuditOptions, 'repository'>;
+export declare function makeJob(runId: number, name: string, seconds: number, queueMinutes?: number, conclusion?: FixtureJob['conclusion']): FixtureJob;
+export declare function makeExecutor(runs: unknown[], jobsByRun: Readonly<Record<number, FixtureJob[]>>): GhApiExecutor;
+export declare function makeRun(id: number, name: string, event: 'pull_request' | 'push', branch?: string, conclusion?: string, createdAt?: string, headBranch?: string | null): unknown;

package/dist/gha-runtime-audit/index.test-helpers.mjs

@@ -0,0 +1,63 @@
+export const exampleAuditOptions = {
+    workflows: [
+        { name: 'CI', event: 'pull_request' },
+        { name: /^Main CI \(.+\)$/, event: 'push' },
+    ],
+};
+export function makeJob(runId, name, seconds, queueMinutes = 0, conclusion = 'success') {
+    const started = new Date(Date.UTC(2026, 0, runId, 0, queueMinutes));
+    return {
+        id: runId * 10,
+        name,
+        started_at: started.toISOString(),
+        completed_at: new Date(started.getTime() + seconds * 1000).toISOString(),
+        conclusion,
+        html_url: `https://github.test/jobs/${runId}`,
+    };
+}
+export function makeExecutor(runs, jobsByRun) {
+    return async (request) => {
+        const { endpoint } = request;
+        if (endpoint.includes('/actions/workflows?')) {
+            return {
+                workflows: endpoint.includes('page=1')
+                    ? [
+                        { id: 1, name: 'CI', state: 'active' },
+                        { id: 2, name: 'Main CI (web)', state: 'active' },
+                        { id: 3, name: 'Other', state: 'active' },
+                    ]
+                    : [],
+            };
+        }
+        if (endpoint.includes('/actions/workflows/1/runs?')) {
+            return {
+                workflow_runs: endpoint.includes('page=1')
+                    ? runs.filter((run) => run.name === 'CI')
+                    : [],
+            };
+        }
+        if (endpoint.includes('/actions/workflows/2/runs?')) {
+            return {
+                workflow_runs: endpoint.includes('page=1')
+                    ? runs.filter((run) => run.name === 'Main CI (web)')
+                    : [],
+            };
+        }
+        const match = endpoint.match(/\/actions\/runs\/(\d+)\/jobs/);
+        if (!match)
+            throw new Error(`Unexpected endpoint: ${endpoint}`);
+        return { jobs: jobsByRun[Number(match[1])] };
+    };
+}
+export function makeRun(id, name, event, branch = 'main', conclusion = 'success', createdAt = new Date(Date.UTC(2026, 0, id)).toISOString(), headBranch = branch) {
+    return {
+        id,
+        name,
+        event,
+        conclusion,
+        created_at: createdAt,
+        html_url: `https://github.test/runs/${id}`,
+        head_branch: headBranch,
+        pull_requests: event === 'pull_request' ? [{ base: { ref: branch } }] : [],
+    };
+}

package/dist/gha-runtime-audit/model.d.mts

@@ -0,0 +1,60 @@
+export interface GhApiRequest {
+    endpoint: string;
+    jq: string;
+}
+export type GhApiExecutor = (request: GhApiRequest) => Promise<unknown>;
+export interface WorkflowRecord {
+    id: number;
+    name: string;
+    state: string;
+}
+export interface RunRecord {
+    id: number;
+    name: string;
+    event: string;
+    conclusion: string;
+    createdAt: string;
+    url: string;
+    headBranch: string | null;
+    pullRequestBaseBranches: string[];
+}
+export interface RuntimeSample {
+    runId: number;
+    runUrl: string;
+    jobId: number;
+    jobUrl: string;
+    startedAt: string;
+    completedAt: string;
+    durationSeconds: number;
+}
+export type RuntimeViolationReason = 'sample-at-or-above-hard-ceiling' | 'five-sample-median-above-threshold';
+export interface RuntimeJobResult {
+    key: string;
+    workflow: string;
+    job: string;
+    sampleCount: number;
+    medianSeconds: number | null;
+    maximumSeconds: number;
+    reasons: RuntimeViolationReason[];
+    samples: RuntimeSample[];
+}
+export interface RuntimeAuditResult {
+    scope: {
+        repository: string;
+        sampleLimit: number;
+        recentCompletedRunHorizon: number;
+        medianThresholdSeconds: number;
+        hardCeilingSeconds: number;
+        branch: string;
+    };
+    jobs: RuntimeJobResult[];
+    violations: RuntimeJobResult[];
+}
+export declare function parseObject(value: unknown, detail: string): Record<string, unknown>;
+export declare function parseArray(value: unknown, detail: string): unknown[];
+export declare function parseRun(value: unknown): RunRecord;
+export declare function parseWorkflow(value: unknown): WorkflowRecord;
+export declare function parseSample(value: unknown, run: RunRecord): {
+    name: string;
+    sample: RuntimeSample;
+} | null;

package/dist/gha-runtime-audit/model.mjs

@@ -0,0 +1,83 @@
+function malformed(detail) {
+    throw new Error(`Malformed GitHub API data: ${detail}`);
+}
+export function parseObject(value, detail) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        malformed(detail);
+    return value;
+}
+function parseString(value, detail) {
+    if (typeof value !== 'string' || value.length === 0)
+        malformed(detail);
+    return value;
+}
+function parseNumber(value, detail) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0)
+        malformed(detail);
+    return value;
+}
+export function parseArray(value, detail) {
+    if (!Array.isArray(value))
+        malformed(detail);
+    return value;
+}
+function parseTimestamp(value, detail) {
+    const timestamp = parseString(value, `${detail} must be a non-empty string`);
+    if (!Number.isFinite(Date.parse(timestamp)))
+        malformed(`${detail} must be an ISO timestamp`);
+    return timestamp;
+}
+export function parseRun(value) {
+    const run = parseObject(value, 'workflow run must be an object');
+    const pullRequests = parseArray(run['pull_requests'], 'workflow run pull_requests must be an array');
+    const pullRequestBaseBranches = [];
+    for (const [index, entry] of pullRequests.entries()) {
+        const pullRequest = parseObject(entry, `pull_requests[${index}] must be an object`);
+        const base = parseObject(pullRequest['base'], `pull_requests[${index}].base must be an object`);
+        pullRequestBaseBranches.push(parseString(base['ref'], `pull_requests[${index}].base.ref must be a string`));
+    }
+    return {
+        id: parseNumber(run['id'], 'workflow run id must be a positive integer'),
+        name: parseString(run['name'], 'workflow run name must be a non-empty string'),
+        event: parseString(run['event'], 'workflow run event must be a non-empty string'),
+        conclusion: parseString(run['conclusion'], 'workflow run conclusion must be a non-empty string'),
+        createdAt: parseTimestamp(run['created_at'], 'workflow run created_at'),
+        url: parseString(run['html_url'], 'workflow run html_url must be a non-empty string'),
+        headBranch: run['head_branch'] === null
+            ? null
+            : parseString(run['head_branch'], 'workflow run head_branch'),
+        pullRequestBaseBranches,
+    };
+}
+export function parseWorkflow(value) {
+    const workflow = parseObject(value, 'workflow must be an object');
+    return {
+        id: parseNumber(workflow['id'], 'workflow id must be a positive integer'),
+        name: parseString(workflow['name'], 'workflow name must be a non-empty string'),
+        state: parseString(workflow['state'], 'workflow state must be a non-empty string'),
+    };
+}
+export function parseSample(value, run) {
+    const job = parseObject(value, `job in run ${run.id} must be an object`);
+    const conclusion = parseString(job['conclusion'], `job in run ${run.id} conclusion must be a string`);
+    if (conclusion !== 'success')
+        return null;
+    const startedAt = parseTimestamp(job['started_at'], `job in run ${run.id} started_at`);
+    const completedAt = parseTimestamp(job['completed_at'], `job in run ${run.id} completed_at`);
+    const durationSeconds = (Date.parse(completedAt) - Date.parse(startedAt)) / 1000;
+    if (!Number.isFinite(durationSeconds) || durationSeconds < 0) {
+        malformed(`job in run ${run.id} has an invalid execution interval`);
+    }
+    return {
+        name: parseString(job['name'], `job in run ${run.id} name must be a non-empty string`),
+        sample: {
+            runId: run.id,
+            runUrl: run.url,
+            jobId: parseNumber(job['id'], `job in run ${run.id} id must be a positive integer`),
+            jobUrl: parseString(job['html_url'], `job in run ${run.id} html_url must be a string`),
+            startedAt,
+            completedAt,
+            durationSeconds,
+        },
+    };
+}

package/dist/gha-runtime-audit/results.d.mts

@@ -0,0 +1,15 @@
+import type { RuntimeJobResult, RuntimeSample } from './model.mts';
+export interface RuntimeSamplesByJob {
+    workflow: string;
+    job: string;
+    samples: RuntimeSample[];
+}
+export type RuntimeThresholds = {
+    medianThresholdSeconds: number;
+    hardCeilingSeconds: number;
+};
+export declare function violationOrder(a: RuntimeJobResult, b: RuntimeJobResult): number;
+export declare function buildRuntimeResults(samplesByKey: ReadonlyMap<string, RuntimeSamplesByJob>, thresholds: RuntimeThresholds): {
+    jobs: RuntimeJobResult[];
+    violations: RuntimeJobResult[];
+};

package/dist/gha-runtime-audit/results.mjs

@@ -0,0 +1,48 @@
+function summarize(entry, thresholds) {
+    const durations = [];
+    for (const sample of entry.samples)
+        durations.push(sample.durationSeconds);
+    durations.sort((a, b) => a - b);
+    const medianSeconds = durations.length === 5 ? durations[2] : null;
+    const reasons = [];
+    if (durations.some((duration) => duration >= thresholds.hardCeilingSeconds)) {
+        reasons.push('sample-at-or-above-hard-ceiling');
+    }
+    if (medianSeconds !== null && medianSeconds > thresholds.medianThresholdSeconds) {
+        reasons.push('five-sample-median-above-threshold');
+    }
+    return {
+        key: `${entry.workflow} / ${entry.job}`,
+        workflow: entry.workflow,
+        job: entry.job,
+        sampleCount: entry.samples.length,
+        medianSeconds,
+        maximumSeconds: Math.max(...durations),
+        reasons,
+        samples: entry.samples,
+    };
+}
+export function violationOrder(a, b) {
+    const aHard = a.reasons.includes('sample-at-or-above-hard-ceiling');
+    const bHard = b.reasons.includes('sample-at-or-above-hard-ceiling');
+    if (aHard && !bHard)
+        return -1;
+    if (!aHard && bHard)
+        return 1;
+    const aScore = aHard ? a.maximumSeconds : a.medianSeconds;
+    const bScore = bHard ? b.maximumSeconds : b.medianSeconds;
+    return bScore - aScore || a.key.localeCompare(b.key);
+}
+export function buildRuntimeResults(samplesByKey, thresholds) {
+    const jobs = [];
+    for (const entry of samplesByKey.values())
+        jobs.push(summarize(entry, thresholds));
+    jobs.sort((a, b) => a.key.localeCompare(b.key));
+    const violations = [];
+    for (const job of jobs) {
+        if (job.reasons.length > 0)
+            violations.push(job);
+    }
+    violations.sort(violationOrder);
+    return { jobs, violations };
+}

package/dist/gha-runtime-audit/scope.d.mts

@@ -0,0 +1,29 @@
+import type { RunRecord, WorkflowRecord } from './model.mts';
+export type WorkflowNameMatch = string | RegExp;
+export type RuntimeAuditWorkflowFilter = {
+    name: WorkflowNameMatch;
+    event: 'pull_request' | 'push';
+};
+export type RuntimeAuditOptions = {
+    repository: string;
+    workflows: RuntimeAuditWorkflowFilter[];
+    branch?: string;
+    sampleLimit?: number;
+    recentCompletedRunHorizon?: number;
+    medianThresholdSeconds?: number;
+    hardCeilingSeconds?: number;
+};
+export type ResolvedRuntimeAuditOptions = {
+    repository: string;
+    workflows: RuntimeAuditWorkflowFilter[];
+    branch: string;
+    sampleLimit: number;
+    recentCompletedRunHorizon: number;
+    medianThresholdSeconds: number;
+    hardCeilingSeconds: number;
+};
+export declare function parseWorkflowNameMatch(value: string): WorkflowNameMatch;
+export declare function resolveRuntimeAuditOptions(options: RuntimeAuditOptions): ResolvedRuntimeAuditOptions;
+export declare function matchingWorkflowFilter(name: string, filters: readonly RuntimeAuditWorkflowFilter[]): RuntimeAuditWorkflowFilter | undefined;
+export declare function isSelectedWorkflow(workflow: WorkflowRecord, filters: readonly RuntimeAuditWorkflowFilter[]): boolean;
+export declare function isRunInScope(run: RunRecord, filter: RuntimeAuditWorkflowFilter, branch: string): boolean;