vouchington-tooling 0.19.2 → 0.21.0

package/dist/dependency-license-policy/collect.mjs

@@ -1,10 +1,13 @@
-import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { withAuditSignalCleanup } from './audit-signals.mjs';
+import { ensurePrivateLicenseAuditStore, licenseAuditStoreDirectory } from './audit-store.mjs';
+import { executePnpm } from './execute-pnpm.mjs';
 import { parsePnpmLicenseReport } from './report.mjs';
 import { preparePnpmLicenseAuditWorkspace } from './workspace.mjs';
 const DEFAULT_OPTIONS = {
-    execute: spawnSync,
+    ensureStore: ensurePrivateLicenseAuditStore,
+    execute: executePnpm,
     prepareWorkspace: preparePnpmLicenseAuditWorkspace,
     readFile: readFileSync,
 };
@@ -19,22 +22,17 @@ function assertCommandSucceeded(label, result) {
     }
 }
 /** Collects licenses for every platform represented in a pnpm lockfile. */
-export function collectPnpmLicenseReport(repoRoot, options = {}) {
-    const { execute, prepareWorkspace, readFile } = { ...DEFAULT_OPTIONS, ...options };
-    const lockfilePath = join(repoRoot, 'pnpm-lock.yaml');
-    const workspacePath = join(repoRoot, 'pnpm-workspace.yaml');
-    const auditWorkspace = prepareWorkspace(repoRoot, readFile(lockfilePath, 'utf8'), readFile(workspacePath, 'utf8'));
-    try {
-        const storeConfig = `--config.store-dir=${join(auditWorkspace.cwd, '.pnpm-store')}`;
-        const fetchResult = execute('pnpm', [storeConfig, 'fetch', '--ignore-scripts'], {
-            cwd: auditWorkspace.cwd,
-            encoding: 'utf8',
-        });
+export async function collectPnpmLicenseReport(repoRoot, options = {}) {
+    const { ensureStore, execute, prepareWorkspace, readFile } = { ...DEFAULT_OPTIONS, ...options };
+    const auditWorkspace = prepareWorkspace(repoRoot, readFile(join(repoRoot, 'pnpm-lock.yaml'), 'utf8'), readFile(join(repoRoot, 'pnpm-workspace.yaml'), 'utf8'));
+    const storeDir = options.storeDir ?? licenseAuditStoreDirectory();
+    return withAuditSignalCleanup(auditWorkspace.cleanup, async (signal) => {
+        ensureStore(storeDir);
+        const storeConfig = `--config.store-dir=${storeDir}`;
+        const commandOptions = { cwd: auditWorkspace.cwd, encoding: 'utf8', signal };
+        const fetchResult = await execute('pnpm', [storeConfig, 'fetch', '--ignore-scripts'], commandOptions);
         assertCommandSucceeded('pnpm fetch', fetchResult);
-        const result = execute('pnpm', [storeConfig, 'licenses', 'list', '--json'], {
-            cwd: auditWorkspace.cwd,
-            encoding: 'utf8',
-        });
+        const result = await execute('pnpm', [storeConfig, 'licenses', 'list', '--json'], commandOptions);
         assertCommandSucceeded('pnpm licenses list --json', result);
         try {
             return parsePnpmLicenseReport(JSON.parse(result.stdout));
@@ -44,8 +42,5 @@ export function collectPnpmLicenseReport(repoRoot, options = {}) {
                 cause: error,
             });
         }
-    }
-    finally {
-        auditWorkspace.cleanup();
-    }
+    });
 }

package/dist/dependency-license-policy/execute-pnpm.d.mts

@@ -0,0 +1,10 @@
+import type { Readable } from 'node:stream';
+import type { PnpmExecutor } from './types.mts';
+export declare function signalFromAbort(signal: AbortSignal): NodeJS.Signals;
+export declare function stopChildProcess(child: {
+    kill: (signal?: NodeJS.Signals) => boolean;
+    pid?: number | undefined;
+}, signal: NodeJS.Signals): void;
+export declare function collectChildStream(stream: Readable | null, chunks: string[], onOverflow: () => void): void;
+/** Runs pnpm in its own process group so a signal can reach it and its children. */
+export declare const executePnpm: PnpmExecutor;

package/dist/dependency-license-policy/execute-pnpm.mjs

@@ -0,0 +1,83 @@
+import { spawn } from 'node:child_process';
+const MAX_BUFFER_BYTES = 1024 * 1024;
+export function signalFromAbort(signal) {
+    if (signal.reason === 'SIGINT' || signal.reason === 'SIGTERM' || signal.reason === 'SIGHUP') {
+        return signal.reason;
+    }
+    return 'SIGTERM';
+}
+export function stopChildProcess(child, signal) {
+    if (child.pid === undefined) {
+        child.kill(signal);
+        return;
+    }
+    try {
+        process.kill(-child.pid, signal);
+    }
+    catch {
+        child.kill(signal);
+    }
+}
+export function collectChildStream(stream, chunks, onOverflow) {
+    if (stream === null)
+        throw new Error('license audit child is missing a stdio pipe');
+    stream.setEncoding('utf8');
+    stream.on('data', (chunk) => {
+        chunks.push(chunk);
+        if (Buffer.byteLength(chunks.join('')) > MAX_BUFFER_BYTES)
+            onOverflow();
+    });
+}
+function finishOnce(settle) {
+    let settled = false;
+    return (result) => {
+        if (settled)
+            return;
+        settled = true;
+        settle(result);
+    };
+}
+/** Runs pnpm in its own process group so a signal can reach it and its children. */
+export const executePnpm = (command, args, options) => new Promise((resolve) => {
+    const child = spawn(command, args, {
+        cwd: options.cwd,
+        detached: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const stdout = [];
+    const stderr = [];
+    let overflow = false;
+    const stop = () => {
+        stopChildProcess(child, overflow ? 'SIGKILL' : signalFromAbort(options.signal));
+    };
+    if (options.signal.aborted)
+        stop();
+    else
+        options.signal.addEventListener('abort', stop, { once: true });
+    const markOverflow = () => {
+        overflow = true;
+        stop();
+    };
+    collectChildStream(child.stdout, stdout, markOverflow);
+    collectChildStream(child.stderr, stderr, markOverflow);
+    const finish = finishOnce((result) => {
+        options.signal.removeEventListener('abort', stop);
+        resolve(result);
+    });
+    child.once('error', (error) => {
+        finish({ error, status: null, stderr: stderr.join(''), stdout: stdout.join('') });
+    });
+    child.once('close', (status) => {
+        const result = { status, stderr: stderr.join(''), stdout: stdout.join('') };
+        if (!overflow) {
+            finish(result);
+            return;
+        }
+        finish({
+            ...result,
+            error: Object.assign(new Error('child output maxBuffer exceeded'), {
+                code: 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER',
+            }),
+        });
+    });
+});

package/dist/dependency-license-policy/types.d.mts

@@ -4,15 +4,17 @@ export interface PnpmLicenseReportEntry {
 }
 /** Shape emitted by `pnpm licenses list --json`. */
 export type PnpmLicenseReport = Record<string, PnpmLicenseReportEntry[]>;
-export type PnpmExecutor = (command: string, args: string[], options: {
-    cwd: string;
-    encoding: 'utf8';
-}) => {
-    error?: Error;
-    status: number | null;
-    stderr: string;
-    stdout: string;
-};
+export interface PnpmCommandResult {
+    readonly error?: Error;
+    readonly status: number | null;
+    readonly stderr: string;
+    readonly stdout: string;
+}
+export type PnpmExecutor = (command: string, args: readonly string[], options: {
+    readonly cwd: string;
+    readonly encoding: 'utf8';
+    readonly signal: AbortSignal;
+}) => PnpmCommandResult | Promise<PnpmCommandResult>;
 export interface DependencyLicenseAllowlistEntry {
     /** Exact SPDX atom allowed by this entry. */
     readonly licenseId: string;

package/dist/dependency-license-policy/workspace.d.mts

@@ -1,3 +1,4 @@
+import { type LicenseAuditWorkspaceOptions } from './audit-directory.mts';
 export interface PnpmLicenseAuditWorkspace {
     readonly cleanup: () => void;
     readonly cwd: string;
@@ -19,4 +20,5 @@ export declare function renderPnpmLicenseAuditFiles(lockfileSource: string, work
     lockfile: string;
     workspace: string;
 }): PnpmLicenseAuditFiles;
-export declare function preparePnpmLicenseAuditWorkspace(repoRoot: string, lockfileSource: string, workspaceSource: string): PnpmLicenseAuditWorkspace;
+export declare function licenseAuditParentDirectory(directory?: string): string;
+export declare function preparePnpmLicenseAuditWorkspace(repoRoot: string, lockfileSource: string, workspaceSource: string, options?: LicenseAuditWorkspaceOptions): PnpmLicenseAuditWorkspace;

package/dist/dependency-license-policy/workspace.mjs

@@ -1,7 +1,8 @@
-import { copyFileSync, existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdtempSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { isMap, parseDocument, stringify as stringifyYaml } from 'yaml';
+import { LICENSE_AUDIT_DIRECTORY_PREFIX, reclaimStaleLicenseAuditDirectories, removeAuditDirectory, writeAuditPid, } from './audit-directory.mjs';
 const PLATFORM_KEYS = ['os', 'cpu', 'libc'];
 function parseYamlDocument(source, path) {
     const document = parseDocument(source);
@@ -71,9 +72,15 @@ export function renderPnpmLicenseAuditFiles(lockfileSource, workspaceSource, pat
         workspace: stringifyYaml({ ...workspace, packages: [], supportedArchitectures }),
     };
 }
-export function preparePnpmLicenseAuditWorkspace(repoRoot, lockfileSource, workspaceSource) {
-    const auditRoot = mkdtempSync(join(tmpdir(), 'dependency-license-audit-'));
+export function licenseAuditParentDirectory(directory) {
+    return directory ?? tmpdir();
+}
+export function preparePnpmLicenseAuditWorkspace(repoRoot, lockfileSource, workspaceSource, options = {}) {
+    const directory = licenseAuditParentDirectory(options.directory);
+    reclaimStaleLicenseAuditDirectories(directory, options);
+    const auditRoot = mkdtempSync(join(directory, LICENSE_AUDIT_DIRECTORY_PREFIX));
     try {
+        writeAuditPid(auditRoot, options.pid);
         copyFileSync(join(repoRoot, 'package.json'), join(auditRoot, 'package.json'));
         const npmrc = join(repoRoot, '.npmrc');
         if (existsSync(npmrc))
@@ -86,11 +93,11 @@ export function preparePnpmLicenseAuditWorkspace(repoRoot, lockfileSource, works
         writeFileSync(join(auditRoot, 'pnpm-workspace.yaml'), files.workspace, 'utf8');
     }
     catch (error) {
-        rmSync(auditRoot, { force: true, recursive: true });
+        removeAuditDirectory(auditRoot);
         throw error;
     }
     return {
         cwd: auditRoot,
-        cleanup: () => rmSync(auditRoot, { force: true, recursive: true }),
+        cleanup: () => removeAuditDirectory(auditRoot),
     };
 }

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

@@ -1,5 +1,6 @@
 import { parseArray, parseObject, parseRun, parseSample, parseWorkflow, } from './model.mjs';
-import { buildRuntimeResults } from './results.mjs';
+import { buildFamilyResults } from './family.mjs';
+import { buildRuntimeResults, violationOrder } from './results.mjs';
 import { isRunInScope, isSelectedWorkflow, matchingWorkflowFilter, resolveRuntimeAuditOptions, } from './scope.mjs';
 async function discoverWorkflows(execute, options) {
     const selected = [];
@@ -58,7 +59,7 @@ 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}]}',
+            jq: '{jobs: [.jobs[] | {id, name, started_at, completed_at, conclusion, html_url, steps: [(.steps // [])[] | {name, started_at, completed_at}]}]}',
         }), `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) {
@@ -91,16 +92,23 @@ export async function auditCiJobRuntime(execute, options) {
             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,
+            medianFloorSeconds: resolved.medianFloorSeconds,
             hardCeilingSeconds: resolved.hardCeilingSeconds,
             branch: resolved.branch,
         },
-        ...results,
+        ...combineResults(samplesByKey, resolved),
     };
 }
+function combineResults(samplesByKey, resolved) {
+    const perJob = buildRuntimeResults(samplesByKey, resolved);
+    const jobs = [...perJob.jobs, ...buildFamilyResults(samplesByKey, resolved)].sort((left, right) => left.key.localeCompare(right.key));
+    const violations = jobs.filter((job) => job.reasons.length > 0);
+    violations.sort(violationOrder);
+    return { jobs, violations };
+}

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

@@ -0,0 +1,7 @@
+import type { RuntimeJobResult } from './model.mts';
+import type { RuntimeSamplesByJob } from './results.mts';
+export type FamilyThresholds = {
+    medianFloorSeconds: number | null;
+    medianThresholdSeconds: number;
+};
+export declare function buildFamilyResults(samplesByKey: ReadonlyMap<string, RuntimeSamplesByJob>, thresholds: FamilyThresholds): RuntimeJobResult[];

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

@@ -0,0 +1,79 @@
+const SETUP_STEP = /checkout|setup-|action-setup|cache|install|download|^post /i;
+export function buildFamilyResults(samplesByKey, thresholds) {
+    if (thresholds.medianFloorSeconds === null)
+        return [];
+    const families = new Map();
+    for (const entry of samplesByKey.values()) {
+        const family = entry.job.replace(/ \([^)]*\)$/, '');
+        const key = `${entry.workflow} / ${family}`;
+        const bucket = families.get(key) ?? {
+            workflow: entry.workflow,
+            family,
+            jobs: new Set(),
+            samples: [],
+        };
+        bucket.jobs.add(entry.job);
+        for (const sample of entry.samples)
+            bucket.samples.push(sample);
+        families.set(key, bucket);
+    }
+    const results = [];
+    for (const [key, bucket] of families) {
+        if (bucket.jobs.size < 2)
+            continue;
+        results.push(familyResult(key, bucket, thresholds.medianFloorSeconds, thresholds));
+    }
+    return results;
+}
+function familyResult(key, bucket, floorSeconds, thresholds) {
+    const durations = bucket.samples.map((sample) => sample.durationSeconds);
+    const medianSeconds = medianDuration(durations);
+    const belowFloor = medianSeconds < floorSeconds;
+    const reasons = [];
+    if (belowFloor)
+        reasons.push('family-median-below-floor');
+    return {
+        key,
+        workflow: bucket.workflow,
+        job: bucket.family,
+        sampleCount: bucket.samples.length,
+        medianSeconds,
+        maximumSeconds: Math.max(...durations),
+        reasons,
+        samples: bucket.samples,
+        shardCount: bucket.jobs.size,
+        setupShare: setupShare(bucket.samples),
+        ...(belowFloor
+            ? {
+                suggestedShardCount: suggestedShardCount(bucket.jobs.size, medianSeconds, thresholds.medianThresholdSeconds),
+            }
+            : {}),
+    };
+}
+function medianDuration(durations) {
+    const sorted = [...durations].sort((left, right) => left - right);
+    const mid = Math.floor(sorted.length / 2);
+    if (sorted.length % 2 === 1)
+        return sorted[mid];
+    return (sorted[mid - 1] + sorted[mid]) / 2;
+}
+function setupShare(samples) {
+    let setupSeconds = 0;
+    let totalSeconds = 0;
+    for (const sample of samples) {
+        for (const step of sample.steps ?? []) {
+            totalSeconds += step.durationSeconds;
+            if (isSetupStep(step.name))
+                setupSeconds += step.durationSeconds;
+        }
+    }
+    if (totalSeconds === 0)
+        return null;
+    return setupSeconds / totalSeconds;
+}
+function isSetupStep(name) {
+    return SETUP_STEP.test(name);
+}
+function suggestedShardCount(shardCount, medianSeconds, medianCeilingSeconds) {
+    return Math.max(1, Math.round((shardCount * medianSeconds) / medianCeilingSeconds));
+}

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

@@ -7,6 +7,11 @@ export type FixtureJob = {
     completed_at: string;
     conclusion: 'success' | 'failure';
     html_url: string;
+    steps?: Array<{
+        name: string;
+        started_at: string | null;
+        completed_at: string | null;
+    }>;
 };
 export declare const exampleAuditOptions: Omit<RuntimeAuditOptions, 'repository'>;
 export declare function makeJob(runId: number, name: string, seconds: number, queueMinutes?: number, conclusion?: FixtureJob['conclusion']): FixtureJob;

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

@@ -18,6 +18,10 @@ export interface RunRecord {
     headBranch: string | null;
     pullRequestBaseBranches: string[];
 }
+interface RuntimeStepSample {
+    name: string;
+    durationSeconds: number;
+}
 export interface RuntimeSample {
     runId: number;
     runUrl: string;
@@ -26,8 +30,9 @@ export interface RuntimeSample {
     startedAt: string;
     completedAt: string;
     durationSeconds: number;
+    steps?: RuntimeStepSample[];
 }
-export type RuntimeViolationReason = 'sample-at-or-above-hard-ceiling' | 'five-sample-median-above-threshold';
+export type RuntimeViolationReason = 'sample-at-or-above-hard-ceiling' | 'five-sample-median-above-threshold' | 'family-median-below-floor';
 export interface RuntimeJobResult {
     key: string;
     workflow: string;
@@ -37,6 +42,9 @@ export interface RuntimeJobResult {
     maximumSeconds: number;
     reasons: RuntimeViolationReason[];
     samples: RuntimeSample[];
+    shardCount?: number;
+    setupShare?: number | null;
+    suggestedShardCount?: number;
 }
 export interface RuntimeAuditResult {
     scope: {
@@ -44,6 +52,7 @@ export interface RuntimeAuditResult {
         sampleLimit: number;
         recentCompletedRunHorizon: number;
         medianThresholdSeconds: number;
+        medianFloorSeconds: number | null;
         hardCeilingSeconds: number;
         branch: string;
     };
@@ -58,3 +67,4 @@ export declare function parseSample(value: unknown, run: RunRecord): {
     name: string;
     sample: RuntimeSample;
 } | null;
+export {};

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

@@ -78,6 +78,32 @@ export function parseSample(value, run) {
             startedAt,
             completedAt,
             durationSeconds,
+            ...jobSteps(job['steps'], run.id),
         },
     };
 }
+function jobSteps(value, runId) {
+    if (value === undefined)
+        return {};
+    const steps = parseArray(value, `job in run ${runId} steps must be an array`);
+    const parsed = [];
+    for (const [index, entry] of steps.entries()) {
+        const step = readStep(entry, runId, index);
+        if (step)
+            parsed.push(step);
+    }
+    return { steps: parsed };
+}
+function readStep(value, runId, index) {
+    const detail = `job in run ${runId} steps[${index}]`;
+    const step = parseObject(value, `${detail} must be an object`);
+    const name = parseString(step['name'], `${detail}.name must be a non-empty string`);
+    if (step['started_at'] == null || step['completed_at'] == null)
+        return undefined;
+    const startedAt = parseTimestamp(step['started_at'], `${detail}.started_at`);
+    const completedAt = parseTimestamp(step['completed_at'], `${detail}.completed_at`);
+    const durationSeconds = (Date.parse(completedAt) - Date.parse(startedAt)) / 1000;
+    if (durationSeconds < 0)
+        malformed(`${detail} has an invalid execution interval`);
+    return { name, durationSeconds };
+}

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

@@ -11,6 +11,7 @@ export type RuntimeAuditOptions = {
     sampleLimit?: number;
     recentCompletedRunHorizon?: number;
     medianThresholdSeconds?: number;
+    medianFloorSeconds?: number;
     hardCeilingSeconds?: number;
 };
 export type ResolvedRuntimeAuditOptions = {
@@ -20,6 +21,7 @@ export type ResolvedRuntimeAuditOptions = {
     sampleLimit: number;
     recentCompletedRunHorizon: number;
     medianThresholdSeconds: number;
+    medianFloorSeconds: number | null;
     hardCeilingSeconds: number;
 };
 export declare function parseWorkflowNameMatch(value: string): WorkflowNameMatch;

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

@@ -14,16 +14,31 @@ export function resolveRuntimeAuditOptions(options) {
     if (options.workflows.length === 0) {
         throw new Error('At least one workflow filter is required');
     }
+    const medianThresholdSeconds = options.medianThresholdSeconds ?? 360;
+    const medianFloorSeconds = options.medianFloorSeconds ?? null;
+    assertPositiveInteger(medianThresholdSeconds, 'median ceiling');
+    if (medianFloorSeconds !== null) {
+        assertPositiveInteger(medianFloorSeconds, 'median floor');
+        if (medianFloorSeconds >= medianThresholdSeconds) {
+            throw new Error('median floor must be below the median ceiling');
+        }
+    }
     return {
         repository: options.repository,
         workflows: options.workflows,
         branch: options.branch ?? 'main',
         sampleLimit: options.sampleLimit ?? 5,
         recentCompletedRunHorizon: options.recentCompletedRunHorizon ?? 10,
-        medianThresholdSeconds: options.medianThresholdSeconds ?? 360,
+        medianThresholdSeconds,
+        medianFloorSeconds,
         hardCeilingSeconds: options.hardCeilingSeconds ?? 600,
     };
 }
+function assertPositiveInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`${label} must be a positive integer`);
+    }
+}
 export function matchingWorkflowFilter(name, filters) {
     return filters.find((filter) => matchesWorkflowName(name, filter.name));
 }

package/dist/pnpm-install/support.mjs

@@ -2,7 +2,7 @@ import { readFile, realpath } from 'node:fs/promises';
 import path from 'node:path';
 const commonInstallArgs = [
     '--prefer-offline',
-    '--prod=false',
+    '--no-prod',
     '--config.disallow-workspace-cycles=false',
 ];
 export const baseInstallArgs = ['install', '--frozen-lockfile', ...commonInstallArgs];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.19.2",
+  "version": "0.21.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {