@patronage/factory-ci 1.0.0-alpha.4 → 1.0.0-alpha.6

package/dist/index.js

@@ -1,10 +1,13 @@
 import { createRequire } from "node:module";
-import { mkdir } from "node:fs/promises";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { build } from "esbuild";
-import { createSign } from "node:crypto";
+import { createSign, randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
-import { execFileSync, spawnSync } from "node:child_process";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { once } from "node:events";
+import { arch, availableParallelism, cpus, platform, release, totalmem } from "node:os";
+import { performance } from "node:perf_hooks";
 //#region src/actions.ts
 /**
 * The canonical Node 24 family shared by factory-project workflows.
@@ -550,6 +553,44 @@ const proofReuseRequiredCommands = (commands) => {
 	return names.toSorted();
 };
 /**
+* Resolve command *identities* to their `ProofReuseCommand` objects (ADR
+* 0021).
+*
+* Selection by name is deliberately a consumer decision (proof-surfaces.ts in
+* software-factory-hq, the `paitronage:verify` filter in paitronage's
+* `verify.ts`): only the consumer knows which named commands a guarded
+* surface requires. What both of those implementations independently
+* hand-rolled is the same lookup — find each name in the profile's command
+* catalog, and refuse to silently shrink the required set when a name has no
+* entry. That lookup is what this function is: the mechanic, not the
+* selection.
+*
+* Throwing at generation time (rather than returning `undefined` or an empty
+* array) is deliberate: a name with no catalog entry is a mistake in the
+* generator source, not a runtime condition a consumer should have to check
+* for, and a required set that quietly loses an entry is exactly what makes a
+* passing proof trivially "covering".
+*
+* `selectionLabel` names the failure, nothing else: it is not part of the
+* selection this function resolves, only prose a consumer supplies for its
+* own thrown error (e.g. HQ's surface name, "core" or "docs"). The message
+* deliberately says "the profile's command catalog" rather than naming
+* `software-factory.profile.json`: a fleet-generic library must not assume
+* every consumer's catalog is that exact file, so this wording differs
+* on purpose from the HQ-local message it replaced.
+*/
+const resolveProofReuseCommands = (catalog, names, selectionLabel) => names.map((name) => {
+	const command = catalog.find((entry) => entry.name === name);
+	if (!command) {
+		const location = selectionLabel ? `Proof-reuse selection for the ${selectionLabel} surface names` : "Proof-reuse selection names";
+		throw new Error(`${location} "${name}", which the profile's command catalog does not define.`);
+	}
+	return {
+		command: command.command,
+		name: command.name
+	};
+});
+/**
 * jq program: every page of the Checks API result in, three sanitized lines
 * (`reason`, `mode`, missing commands) out.
 *
@@ -898,6 +939,328 @@ const assertProofReuseCoverage = (input) => {
 	throw new Error(`Proof-reuse coverage failed: the ${surface} surface ${problem}. Add the command to software-factory.profile.json (and to this surface's selection), or stop skipping it.`);
 };
 //#endregion
+//#region src/vitest-profile.ts
+/**
+* Vitest suite profiling — the measurement mechanics behind a CI runner
+* comparison (#640, #647).
+*
+* A profile is a machine-readable record of N serial Vitest runs at one worker
+* count, carrying per-file and per-test timings, aggregate duration statistics,
+* and the hardware the samples actually ran on. The hardware capture is the
+* point: the #640 Depot comparison only resolved because every sample recorded
+* its `cpuModel`, which split otherwise-identical 4-CPU runs into two
+* non-overlapping populations.
+*
+* Everything a repository decides stays with the repository: worker counts,
+* sample counts, output paths, runner labels, and which suite to run at all.
+* This module owns the schema, the report parsing, the environment capture, and
+* the atomic write.
+*/
+/** Schema version of the emitted profile document. */
+const VITEST_PROFILE_SCHEMA_VERSION = 1;
+/** `tool` discriminator every emitted profile carries. */
+const VITEST_PROFILE_TOOL = "factory-ci-vitest-profile";
+const RUN_TIMEOUT_MS = 15 * 6e4;
+const TERMINATION_GRACE_MS = 5e3;
+/**
+* A sample failed. The partial profile is already on disk; `exitCode` is the
+* status a caller should exit with.
+*/
+var VitestProfileError = class extends Error {
+	exitCode;
+	constructor(message, exitCode) {
+		super(message);
+		this.name = "VitestProfileError";
+		this.exitCode = exitCode;
+	}
+};
+const durationSummary = (durations) => {
+	const sorted = durations.toSorted((left, right) => left - right);
+	const middle = Math.floor(sorted.length / 2);
+	const median = sorted.length % 2 === 0 ? ((sorted[middle - 1] ?? 0) + (sorted[middle] ?? 0)) / 2 : sorted[middle] ?? 0;
+	return {
+		maximum: sorted.at(-1) ?? 0,
+		mean: durations.reduce((sum, value) => sum + value, 0) / durations.length,
+		median,
+		minimum: sorted[0] ?? 0
+	};
+};
+const relativePath = (cwd, file) => path.relative(cwd, file).split(path.sep).join("/");
+/**
+* Fold one Vitest JSON report into a profile sample: file and test timings,
+* both sorted slowest first, plus the run's counts. A missing report (crash,
+* timeout, unwritable output) yields a sample with `reportAvailable: false`
+* rather than nothing at all.
+*/
+const normalizeVitestProfileSample = (report, input) => {
+	const files = (report?.testResults ?? []).map((file) => ({
+		durationMs: Math.max(0, file.endTime - file.startTime),
+		path: relativePath(input.cwd, file.name),
+		status: file.status
+	})).toSorted((left, right) => right.durationMs - left.durationMs);
+	const tests = (report?.testResults ?? []).flatMap((file) => file.assertionResults.map((test) => ({
+		durationMs: Math.max(0, test.duration ?? 0),
+		file: relativePath(input.cwd, file.name),
+		name: test.fullName,
+		status: test.status
+	}))).toSorted((left, right) => right.durationMs - left.durationMs);
+	return {
+		counts: report ? {
+			failed: report.numFailedTests,
+			passed: report.numPassedTests,
+			pending: report.numPendingTests,
+			suites: report.numTotalTestSuites,
+			tests: report.numTotalTests,
+			todo: report.numTodoTests
+		} : null,
+		durationMs: input.durationMs,
+		endedAt: input.endedAt.toISOString(),
+		exitCode: input.exitCode,
+		failure: input.failure ?? null,
+		files,
+		reportAvailable: report !== null,
+		sample: input.sample,
+		startedAt: input.startedAt.toISOString(),
+		tests
+	};
+};
+const aggregateSlowFiles = (runs, limit) => {
+	const durations = /* @__PURE__ */ new Map();
+	for (const file of runs.flatMap((run) => run.files)) {
+		const recorded = durations.get(file.path) ?? [];
+		recorded.push(file.durationMs);
+		durations.set(file.path, recorded);
+	}
+	return [...durations].map(([filePath, values]) => ({
+		durationMs: durationSummary(values),
+		path: filePath,
+		samples: values.length
+	})).toSorted((left, right) => right.durationMs.median - left.durationMs.median).slice(0, limit);
+};
+const aggregateSlowTests = (runs, limit) => {
+	const timings = /* @__PURE__ */ new Map();
+	for (const test of runs.flatMap((run) => run.tests)) {
+		const key = `${test.file}\0${test.name}`;
+		const recorded = timings.get(key) ?? {
+			durations: [],
+			file: test.file,
+			name: test.name
+		};
+		recorded.durations.push(test.durationMs);
+		timings.set(key, recorded);
+	}
+	return [...timings.values()].map(({ durations, file, name }) => ({
+		durationMs: durationSummary(durations),
+		file,
+		name,
+		samples: durations.length
+	})).toSorted((left, right) => right.durationMs.median - left.durationMs.median).slice(0, limit);
+};
+const gitValue = (cwd, args) => {
+	try {
+		return execFileSync("git", args, {
+			cwd,
+			encoding: "utf-8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+	} catch {
+		return null;
+	}
+};
+const resolveVitestPackage = (cwd) => createRequire(path.join(path.resolve(cwd), "noop.js")).resolve("vitest/package.json");
+/**
+* Record the machine and commit a profile was taken on. Vitest's version is
+* resolved from `cwd`, so it is the consumer's Vitest and not this package's.
+* Git failures degrade to `null` — an artifact from a tarball checkout is still
+* a usable measurement.
+*/
+const captureVitestProfileEnvironment = async (options) => {
+	const gitDirectory = options.gitDirectory ?? options.cwd;
+	let vitestVersion = "unknown";
+	try {
+		vitestVersion = JSON.parse(await readFile(resolveVitestPackage(options.cwd), "utf-8")).version ?? "unknown";
+	} catch {
+		vitestVersion = "unknown";
+	}
+	const processors = cpus();
+	const status = gitValue(gitDirectory, ["status", "--porcelain"]);
+	return {
+		arch: arch(),
+		availableParallelism: availableParallelism(),
+		cpuCount: processors.length,
+		cpuModel: processors[0]?.model ?? null,
+		gitDirty: status === null ? null : status.length > 0,
+		gitHead: gitValue(gitDirectory, ["rev-parse", "HEAD"]),
+		node: process.version,
+		osRelease: release(),
+		platform: platform(),
+		totalMemoryBytes: totalmem(),
+		vitest: vitestVersion
+	};
+};
+const spawnVitest = async ({ cwd, maxWorkers, reportPath, stdio }) => {
+	const vitestCli = path.join(path.dirname(resolveVitestPackage(cwd)), "vitest.mjs");
+	const started = performance.now();
+	const child = spawn(process.execPath, [
+		vitestCli,
+		"run",
+		"--reporter=json",
+		`--outputFile=${reportPath}`,
+		`--maxWorkers=${maxWorkers}`
+	], {
+		cwd,
+		stdio
+	});
+	let timedOut = false;
+	let forceKillTimer;
+	const timeoutTimer = setTimeout(() => {
+		timedOut = true;
+		child.kill("SIGTERM");
+		forceKillTimer = setTimeout(() => {
+			child.kill("SIGKILL");
+		}, TERMINATION_GRACE_MS);
+	}, RUN_TIMEOUT_MS);
+	let exitCode = 0;
+	let failure = null;
+	try {
+		const [code, signal] = await once(child, "exit");
+		exitCode = code ?? (signal ? 1 : 0);
+	} catch (error) {
+		exitCode = 1;
+		failure = `Vitest could not start: ${error instanceof Error ? error.message : String(error)}`;
+	} finally {
+		clearTimeout(timeoutTimer);
+		if (forceKillTimer) clearTimeout(forceKillTimer);
+	}
+	if (timedOut) failure = `Vitest profile sample exceeded ${RUN_TIMEOUT_MS}ms and was terminated.`;
+	let report = null;
+	try {
+		report = JSON.parse(await readFile(reportPath, "utf-8"));
+	} catch (error) {
+		const reportFailure = `Vitest JSON report unavailable: ${error instanceof Error ? error.message : String(error)}`;
+		failure = failure ? `${failure} ${reportFailure}` : reportFailure;
+	}
+	return {
+		durationMs: Math.max(0, performance.now() - started),
+		exitCode: timedOut ? 1 : exitCode,
+		failure,
+		report
+	};
+};
+/**
+* Write a profile document atomically: a partial file must never be readable
+* as a complete measurement, and the profile is rewritten after every sample.
+*/
+const writeVitestProfile = async (outputPath, profile) => {
+	await mkdir(path.dirname(outputPath), { recursive: true });
+	const temporaryPath = `${outputPath}.tmp`;
+	await writeFile(temporaryPath, `${JSON.stringify(profile, null, 2)}\n`, "utf-8");
+	await rename(temporaryPath, outputPath);
+};
+/**
+* Take `samples` serial Vitest runs at one worker count and persist the profile
+* after each one. Samples never overlap: concurrent runs would measure CPU and
+* I/O contention instead of the worker count under test. A failing sample
+* throws `VitestProfileError` with the partial profile already written.
+*/
+const runVitestProfile = async (options, dependencies = {}) => {
+	if (!Number.isSafeInteger(options.samples) || options.samples < 1) throw new Error("runVitestProfile: samples must be a positive integer.");
+	const now = dependencies.now ?? (() => /* @__PURE__ */ new Date());
+	const runSample = dependencies.runSample ?? spawnVitest;
+	const writeResult = dependencies.writeResult ?? writeVitestProfile;
+	const startedAt = now();
+	const rawRoot = path.join(`${options.outputPath}.raw`, randomUUID());
+	await mkdir(rawRoot, { recursive: true });
+	const profile = {
+		command: [
+			"vitest",
+			"run",
+			"--reporter=json",
+			`--maxWorkers=${options.maxWorkers}`
+		],
+		endedAt: startedAt.toISOString(),
+		environment: await captureVitestProfileEnvironment({
+			cwd: options.cwd,
+			gitDirectory: options.gitDirectory
+		}),
+		options: {
+			maxWorkers: options.maxWorkers,
+			samples: options.samples,
+			slowLimit: options.slowLimit
+		},
+		rawReportDirectory: rawRoot,
+		runs: [],
+		schemaVersion: 1,
+		startedAt: startedAt.toISOString(),
+		summary: {
+			durationMs: {
+				maximum: 0,
+				mean: 0,
+				median: 0,
+				minimum: 0
+			},
+			slowFiles: [],
+			slowTests: []
+		},
+		tool: VITEST_PROFILE_TOOL
+	};
+	for (let sample = 1; sample <= options.samples; sample += 1) {
+		let hookFailure;
+		try {
+			options.onSampleStart?.({
+				maxWorkers: options.maxWorkers,
+				sample,
+				samples: options.samples
+			});
+		} catch (error) {
+			hookFailure = { error };
+		}
+		const sampleStartedAt = now();
+		const reportPath = path.join(rawRoot, `sample-${sample}.json`);
+		const execution = await runSample({
+			cwd: options.cwd,
+			maxWorkers: options.maxWorkers,
+			reportPath,
+			sample,
+			stdio: options.stdio ?? "inherit"
+		});
+		const sampleEndedAt = now();
+		const normalized = normalizeVitestProfileSample(execution.report, {
+			cwd: options.cwd,
+			durationMs: execution.durationMs,
+			endedAt: sampleEndedAt,
+			exitCode: execution.exitCode,
+			failure: execution.failure,
+			sample,
+			startedAt: sampleStartedAt
+		});
+		profile.runs.push(normalized);
+		profile.endedAt = sampleEndedAt.toISOString();
+		profile.summary = {
+			durationMs: durationSummary(profile.runs.map((run) => run.durationMs)),
+			slowFiles: aggregateSlowFiles(profile.runs, options.slowLimit),
+			slowTests: aggregateSlowTests(profile.runs, options.slowLimit)
+		};
+		await writeResult(options.outputPath, profile);
+		try {
+			options.onSampleComplete?.({
+				result: normalized,
+				sample,
+				samples: options.samples
+			});
+		} catch (error) {
+			hookFailure ??= { error };
+		}
+		if (execution.exitCode !== 0 || execution.report?.success !== true) throw new VitestProfileError(`Vitest profile sample ${sample} failed; partial results saved.`, execution.exitCode || 1);
+		if (hookFailure) throw hookFailure.error;
+	}
+	return profile;
+};
+//#endregion
 //#region src/workflow-shell-lint.ts
 const RUN_KEY = /^(?<indent>\s*)(?:-\s+)?run:(?<inline>.*)$/u;
 /**
@@ -1162,4 +1525,4 @@ const assertWorkflowShellParses = (yaml, options) => {
 	throw new Error(`${options.source} emits shell bash cannot parse; the runner would treat it as a no-op:\n${detail}`);
 };
 //#endregion
-export { FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_CHECK_NAME, FACTORY_PROOF_GATE_GUARD, FACTORY_PROOF_GATE_IF, FACTORY_PROOF_GATE_MODE_OUTPUT, FACTORY_PROOF_GATE_OUTPUT, FACTORY_PROOF_GATE_REASONS, FACTORY_PROOF_GATE_REASON_OUTPUT, FACTORY_PROOF_GATE_SHELL, FACTORY_PROOF_GATE_STEP_ID, GitHubApiError, NODE_PNPM_ACTION_FAMILY_NODE24, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, executeAlchemyEntry, factoryProofGateScript, factoryProofGateStep, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, parseLocalPreviewStage, proofReuseCoverage, proofReuseRequiredCommands, workflowRunBlocks, workflowShellParseFailures };
+export { FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_CHECK_NAME, FACTORY_PROOF_GATE_GUARD, FACTORY_PROOF_GATE_IF, FACTORY_PROOF_GATE_MODE_OUTPUT, FACTORY_PROOF_GATE_OUTPUT, FACTORY_PROOF_GATE_REASONS, FACTORY_PROOF_GATE_REASON_OUTPUT, FACTORY_PROOF_GATE_SHELL, FACTORY_PROOF_GATE_STEP_ID, GitHubApiError, NODE_PNPM_ACTION_FAMILY_NODE24, VITEST_PROFILE_SCHEMA_VERSION, VITEST_PROFILE_TOOL, VitestProfileError, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryProofGateScript, factoryProofGateStep, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, proofReuseCoverage, proofReuseRequiredCommands, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patronage/factory-ci",
-  "version": "1.0.0-alpha.4",
+  "version": "1.0.0-alpha.6",
   "description": "Deep CI and deploy building blocks for Patronage factory projects: workflow source artifacts, hosted diff classification, Alchemy entry execution, and disposable-stage semantics",
   "keywords": [
     "alchemy",
@@ -22,16 +22,13 @@
   "type": "module",
   "exports": {
     ".": {
-      "development": {
-        "types": "./src/index.ts",
-        "default": "./src/index.ts"
-      },
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     }
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "tag": "next"
   },
   "dependencies": {
     "esbuild": "0.28.1"

package/src/index.ts

@@ -70,7 +70,26 @@ export {
   type ProofReuseCoverageInput,
   type ProofReuseCoverageReport,
   proofReuseRequiredCommands,
+  resolveProofReuseCommands,
 } from "./proof-reuse-gate.ts";
+export {
+  captureVitestProfileEnvironment,
+  normalizeVitestProfileSample,
+  runVitestProfile,
+  VITEST_PROFILE_SCHEMA_VERSION,
+  VITEST_PROFILE_TOOL,
+  type VitestJsonReport,
+  type VitestProfile,
+  type VitestProfileDependencies,
+  type VitestProfileDurationSummary,
+  type VitestProfileEnvironment,
+  VitestProfileError,
+  type VitestProfileOptions,
+  type VitestProfileSample,
+  type VitestProfileSampleExecution,
+  type VitestTestStatus,
+  writeVitestProfile,
+} from "./vitest-profile.ts";
 export {
   assertWorkflowShellParses,
   workflowRunBlocks,

package/src/proof-reuse-gate.ts

@@ -215,6 +215,51 @@ export const proofReuseRequiredCommands = (
   return names.toSorted();
 };
 
+/**
+ * Resolve command *identities* to their `ProofReuseCommand` objects (ADR
+ * 0021).
+ *
+ * Selection by name is deliberately a consumer decision (proof-surfaces.ts in
+ * software-factory-hq, the `paitronage:verify` filter in paitronage's
+ * `verify.ts`): only the consumer knows which named commands a guarded
+ * surface requires. What both of those implementations independently
+ * hand-rolled is the same lookup — find each name in the profile's command
+ * catalog, and refuse to silently shrink the required set when a name has no
+ * entry. That lookup is what this function is: the mechanic, not the
+ * selection.
+ *
+ * Throwing at generation time (rather than returning `undefined` or an empty
+ * array) is deliberate: a name with no catalog entry is a mistake in the
+ * generator source, not a runtime condition a consumer should have to check
+ * for, and a required set that quietly loses an entry is exactly what makes a
+ * passing proof trivially "covering".
+ *
+ * `selectionLabel` names the failure, nothing else: it is not part of the
+ * selection this function resolves, only prose a consumer supplies for its
+ * own thrown error (e.g. HQ's surface name, "core" or "docs"). The message
+ * deliberately says "the profile's command catalog" rather than naming
+ * `software-factory.profile.json`: a fleet-generic library must not assume
+ * every consumer's catalog is that exact file, so this wording differs
+ * on purpose from the HQ-local message it replaced.
+ */
+export const resolveProofReuseCommands = (
+  catalog: readonly ProofReuseCommand[],
+  names: readonly string[],
+  selectionLabel?: string
+): readonly ProofReuseCommand[] =>
+  names.map((name) => {
+    const command = catalog.find((entry) => entry.name === name);
+    if (!command) {
+      const location = selectionLabel
+        ? `Proof-reuse selection for the ${selectionLabel} surface names`
+        : "Proof-reuse selection names";
+      throw new Error(
+        `${location} "${name}", which the profile's command catalog does not define.`
+      );
+    }
+    return { command: command.command, name: command.name };
+  });
+
 /**
  * jq program: every page of the Checks API result in, three sanitized lines
  * (`reason`, `mode`, missing commands) out.