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

package/README.md

@@ -166,6 +166,29 @@ Nothing is cached. The token is returned to the caller, which owns its lifetime
 
 `options` are all injectable seams: `fetch`, `now`, `readPrivateKey`, and a `timeoutMs` per request (five seconds by default). Tests substitute the first three; production passes at most a timeout.
 
+### Vitest suite profiling
+
+```ts
+import { runVitestProfile } from "@patronage/factory-ci";
+
+const profile = await runVitestProfile({
+  cwd: packageRoot,
+  gitDirectory: repositoryRoot,
+  maxWorkers: 4,
+  outputPath: "/abs/path/profile.json",
+  samples: 3,
+  slowLimit: 20,
+});
+```
+
+`runVitestProfile(options, dependencies?)` takes N **serial** Vitest runs at one worker count and writes a machine-readable profile after every sample: per-file and per-test timings sorted slowest first, duration statistics across samples, and the machine the samples ran on. Samples never overlap — concurrent runs would measure CPU and I/O contention instead of the worker count under test — and the profile is rewritten after each one, so a run that goes red at sample three still leaves two usable measurements on disk. A failed sample throws `VitestProfileError`, which carries the `exitCode` a caller should exit with.
+
+The **environment capture is the reason this is shared**. The #640 runner comparison only resolved because each sample recorded its `cpuModel`: 4-CPU samples that were indistinguishable by label split into two non-overlapping populations, AMD at 15.3–16.2s and Intel at 24.6–24.9s. `captureVitestProfileEnvironment({ cwd, gitDirectory? })` records CPU model and count, available parallelism, total memory, arch, platform, OS release, Node version, the **consumer's** Vitest version (resolved from `cwd`, never this package's), and the Git head and dirtiness. Git failures and an unresolvable Vitest degrade to `null` / `"unknown"` rather than throwing: an artifact from a tarball checkout is still a measurement.
+
+`normalizeVitestProfileSample(report, input)` folds one Vitest `--reporter=json` document into a sample; a missing report yields `reportAvailable: false` instead of nothing. `writeVitestProfile(path, profile)` is the atomic write — a partial file must never be readable as a complete measurement. Every emitted document carries `schemaVersion: VITEST_PROFILE_SCHEMA_VERSION` and `tool: VITEST_PROFILE_TOOL` so artifacts from different repositories are comparable and self-identifying.
+
+**Everything a repository decides stays with the repository**: worker counts, sample counts, slow-list length, output-path conventions, runner labels, artifact upload, and console output. `onSampleStart` / `onSampleComplete` hand the caller each sample so it can print whatever it prints; this package logs nothing. `stdio` for the Vitest child is the caller's too — `"inherit"` by default, so a caller whose own stdout is structured passes `"ignore"`. A reporting hook is a console, not a control: if `onSampleStart` or `onSampleComplete` throws, the sample still runs and the `VitestProfileError` still wins, and the hook's error surfaces only when the sample was otherwise green. `samples` below one is refused outright — it would resolve green having measured nothing and written no artifact. `now`, `runSample`, and `writeResult` are injectable seams for tests.
+
 ### Published-package contract
 
 The tests pack the actual tarball, extract it into a throwaway external consumer, import the built package root without the workspace's `development` condition, assert the exact runtime exports, and exercise the workflow and stage interfaces. This catches source-only successes, stale or missing `dist/`, exports-map mistakes, and accidental tarball growth before the attended release check.

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { StdioOptions } from "node:child_process";
+
 //#region src/actions.d.ts
 /**
  * The GitHub Actions this family's workflow generators use, pinned to full
@@ -415,6 +417,34 @@ interface ProofReuseCommand {
  * must refuse instead.
  */
 declare const proofReuseRequiredCommands: (commands: readonly ProofReuseCommand[]) => readonly string[] | undefined;
+/**
+ * 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.
+ */
+declare const resolveProofReuseCommands: (catalog: readonly ProofReuseCommand[], names: readonly string[], selectionLabel?: string) => readonly ProofReuseCommand[];
 interface FactoryProofGateOptions {
   /**
    * The profile command objects this guarded surface selected. A consumer with
@@ -510,6 +540,216 @@ declare const proofReuseCoverage: ({
 /** `proofReuseCoverage`, as a build failure. */
 declare const assertProofReuseCoverage: (input: ProofReuseCoverageInput) => ProofReuseCoverageReport;
 //#endregion
+//#region src/vitest-profile.d.ts
+/** Schema version of the emitted profile document. */
+declare const VITEST_PROFILE_SCHEMA_VERSION = 1;
+/** `tool` discriminator every emitted profile carries. */
+declare const VITEST_PROFILE_TOOL = "factory-ci-vitest-profile";
+/** Per-assertion status as Vitest's JSON reporter spells it. */
+type VitestTestStatus = "disabled" | "failed" | "passed" | "pending" | "skipped" | "todo";
+/** The subset of Vitest's `--reporter=json` document this module reads. */
+interface VitestJsonReport {
+  numFailedTests: number;
+  numPassedTests: number;
+  numPendingTests: number;
+  numTodoTests: number;
+  numTotalTests: number;
+  numTotalTestSuites: number;
+  success: boolean;
+  testResults: {
+    assertionResults: {
+      duration?: number | null;
+      fullName: string;
+      status: VitestTestStatus;
+    }[];
+    endTime: number;
+    name: string;
+    startTime: number;
+    status: "failed" | "passed";
+  }[];
+}
+/** Duration statistics over one population of samples, in milliseconds. */
+interface VitestProfileDurationSummary {
+  maximum: number;
+  mean: number;
+  median: number;
+  minimum: number;
+}
+/**
+ * The machine a sample ran on, plus the commit it measured. `cpuModel` is the
+ * field that makes two runs comparable at all: hosted runner pools mix silicon
+ * behind one label.
+ */
+interface VitestProfileEnvironment {
+  arch: string;
+  availableParallelism: number;
+  cpuCount: number;
+  cpuModel: string | null;
+  gitDirty: boolean | null;
+  gitHead: string | null;
+  node: string;
+  osRelease: string;
+  platform: string;
+  totalMemoryBytes: number;
+  vitest: string;
+}
+/** One complete Vitest run inside a profile. */
+interface VitestProfileSample {
+  counts: {
+    failed: number;
+    passed: number;
+    pending: number;
+    suites: number;
+    tests: number;
+    todo: number;
+  } | null;
+  durationMs: number;
+  endedAt: string;
+  exitCode: number;
+  failure: string | null;
+  files: {
+    durationMs: number;
+    path: string;
+    status: "failed" | "passed";
+  }[];
+  reportAvailable: boolean;
+  sample: number;
+  startedAt: string;
+  tests: {
+    durationMs: number;
+    file: string;
+    name: string;
+    status: VitestTestStatus;
+  }[];
+}
+/** The emitted profile document. */
+interface VitestProfile {
+  command: string[];
+  endedAt: string;
+  environment: VitestProfileEnvironment;
+  options: {
+    maxWorkers: number;
+    samples: number;
+    slowLimit: number;
+  };
+  rawReportDirectory: string;
+  runs: VitestProfileSample[];
+  schemaVersion: typeof VITEST_PROFILE_SCHEMA_VERSION;
+  startedAt: string;
+  summary: {
+    durationMs: VitestProfileDurationSummary;
+    slowFiles: {
+      durationMs: VitestProfileDurationSummary;
+      path: string;
+      samples: number;
+    }[];
+    slowTests: {
+      durationMs: VitestProfileDurationSummary;
+      file: string;
+      name: string;
+      samples: number;
+    }[];
+  };
+  tool: typeof VITEST_PROFILE_TOOL;
+}
+/** What a caller must decide before a profile can run. */
+interface VitestProfileOptions {
+  /** Directory Vitest runs in; file paths are recorded relative to it. */
+  cwd: string;
+  /** Directory whose Git state is recorded. Defaults to `cwd`. */
+  gitDirectory?: string;
+  /** Vitest `--maxWorkers` for every sample. */
+  maxWorkers: number;
+  /** Absolute path of the profile document to write. */
+  outputPath: string;
+  /** Called before each sample starts. */
+  onSampleStart?: (input: {
+    maxWorkers: number;
+    sample: number;
+    samples: number;
+  }) => void;
+  /** Called after each sample is normalized and persisted. */
+  onSampleComplete?: (input: {
+    result: VitestProfileSample;
+    sample: number;
+    samples: number;
+  }) => void;
+  /** How many serial runs to take. */
+  samples: number;
+  /** How many slow files and slow tests to keep in the summary. */
+  slowLimit: number;
+  /**
+   * `stdio` for the Vitest child. Defaults to `"inherit"`, which is what a
+   * caller printing progress to a terminal wants; a caller whose own stdout is
+   * structured passes `"ignore"` to silence the run.
+   */
+  stdio?: StdioOptions;
+}
+/** Outcome of one Vitest invocation, as `runSample` reports it. */
+interface VitestProfileSampleExecution {
+  durationMs: number;
+  exitCode: number;
+  failure?: string | null;
+  report: VitestJsonReport | null;
+}
+/** Injectable seams; production passes none of them. */
+interface VitestProfileDependencies {
+  now?: () => Date;
+  runSample?: (input: {
+    cwd: string;
+    maxWorkers: number;
+    reportPath: string;
+    sample: number;
+    stdio: StdioOptions;
+  }) => Promise<VitestProfileSampleExecution>;
+  writeResult?: (outputPath: string, profile: VitestProfile) => Promise<void>;
+}
+/**
+ * A sample failed. The partial profile is already on disk; `exitCode` is the
+ * status a caller should exit with.
+ */
+declare class VitestProfileError extends Error {
+  readonly exitCode: number;
+  constructor(message: string, exitCode: number);
+}
+/**
+ * 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.
+ */
+declare const normalizeVitestProfileSample: (report: VitestJsonReport | null, input: {
+  cwd: string;
+  durationMs: number;
+  endedAt: Date;
+  exitCode: number;
+  failure?: string | null;
+  sample: number;
+  startedAt: Date;
+}) => VitestProfileSample;
+/**
+ * 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.
+ */
+declare const captureVitestProfileEnvironment: (options: {
+  cwd: string;
+  gitDirectory?: string;
+}) => Promise<VitestProfileEnvironment>;
+/**
+ * Write a profile document atomically: a partial file must never be readable
+ * as a complete measurement, and the profile is rewritten after every sample.
+ */
+declare const writeVitestProfile: (outputPath: string, profile: VitestProfile) => Promise<void>;
+/**
+ * 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.
+ */
+declare const runVitestProfile: (options: VitestProfileOptions, dependencies?: VitestProfileDependencies) => Promise<VitestProfile>;
+//#endregion
 //#region src/workflow-shell-lint.d.ts
 /**
  * Parse-check the shell embedded in generated workflow YAML (#376).
@@ -561,4 +801,4 @@ declare const assertWorkflowShellParses: (yaml: string, options: {
   readonly source: string;
 }) => void;
 //#endregion
-export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, 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, type FactoryProofGateOptions, type FactoryProofGateReason, type FactoryProofGateStep, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, GitHubApiError, type GithubAppCredentials, type GithubAppTokenOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type ProofReuseCommand, type ProofReuseCoverageInput, type ProofReuseCoverageReport, type SetupNodeStepOptions, type WorkflowShellParseFailure, type WorkflowStep, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, executeAlchemyEntry, factoryProofGateScript, factoryProofGateStep, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, parseLocalPreviewStage, proofReuseCoverage, proofReuseRequiredCommands, workflowRunBlocks, workflowShellParseFailures };
+export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, 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, type FactoryProofGateOptions, type FactoryProofGateReason, type FactoryProofGateStep, type FactoryWorkflowArtifact, type FactoryWorkflowOptions, type FactoryWorkflowSetupOptions, GitHubApiError, type GithubAppCredentials, type GithubAppTokenOptions, type InstallStepOptions, type LocalPreviewStage, type LocalPreviewStageOptions, NODE_PNPM_ACTION_FAMILY_NODE24, type NodePnpmActionFamily, type ParseLocalPreviewStageExpected, type ParsedLocalPreviewStage, type PinnedAction, type ProofReuseCommand, type ProofReuseCoverageInput, type ProofReuseCoverageReport, type SetupNodeStepOptions, 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, type WorkflowShellParseFailure, type WorkflowStep, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryProofGateScript, factoryProofGateStep, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, proofReuseCoverage, proofReuseRequiredCommands, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };