@patronage/factory-ci 0.2.1 → 1.0.0-alpha.13

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
@@ -52,6 +54,21 @@ declare const NODE_PNPM_ACTION_FAMILY_NODE24: {
   };
 };
 //#endregion
+//#region src/candidate-lifecycle.d.ts
+/**
+ * Pull-request events that can create or refresh a Factory candidate run.
+ *
+ * GitHub's draft boolean remains the lifecycle authority: these triggers make
+ * a run visible, while `factoryCandidateOrPushCondition` keeps substantive
+ * jobs idle until the pull request is a candidate.
+ */
+declare const FACTORY_CANDIDATE_PULL_REQUEST_TYPES: readonly ["opened", "synchronize", "reopened", "ready_for_review"];
+/**
+ * Build a GitHub Actions job condition for candidate PRs and merge-target
+ * pushes. The caller owns triggers, jobs, runners, permissions, and topology.
+ */
+declare const factoryCandidateOrPushCondition: (candidateCondition?: string) => string;
+//#endregion
 //#region src/bundle-alchemy-entry.d.ts
 interface BundleAlchemyEntryOptions {
   /** The Alchemy entry to bundle, e.g. `alchemy.run.ts`. */
@@ -60,6 +77,18 @@ interface BundleAlchemyEntryOptions {
   readonly outfile: string;
   /** esbuild's working directory; also the base for relative paths. */
   readonly absWorkingDir?: string;
+  /**
+   * Import specifiers to rewrite before resolution, passed straight to
+   * esbuild's `alias`. Substitution happens before the `packages` and
+   * `external` decisions, so an aliased bare specifier is inlined even under
+   * `packages: "external"`. Values are resolved the way esbuild resolves any
+   * import, so give absolute paths or package names — which aliases a repo
+   * needs is the consumer's policy and this package bakes in none. A key on
+   * `alchemy`, `effect`, or a subpath of either is rejected outright, and the
+   * finished bundle is checked for files from those packages however they were
+   * reached.
+   */
+  readonly alias?: Readonly<Record<string, string>>;
   /**
    * `"external"` (default) leaves every bare import outside the entry's own
    * source graph to Node's resolver at run time — the entry's TypeScript is
@@ -134,12 +163,17 @@ declare const localPreviewStage: (options: LocalPreviewStageOptions) => LocalPre
 //#endregion
 //#region src/factory-workflow.d.ts
 interface WorkflowStep {
+  readonly continueOnError?: boolean;
+  readonly env?: Readonly<Record<string, string>>;
+  readonly id?: string;
+  readonly if?: string;
   readonly name: string;
   readonly uses?: string;
   readonly with?: Readonly<Record<string, string>>;
   readonly run?: string;
 }
 interface CheckoutStepOptions {
+  readonly fetchDepth?: number;
   readonly name?: string;
   readonly ref?: string;
 }
@@ -194,6 +228,59 @@ interface FactoryWorkflowArtifact<Additional extends Readonly<Record<string, Pin
  */
 declare const factoryWorkflow: <const Additional extends Readonly<Record<string, PinnedAction>> = Record<never, never>>(options: FactoryWorkflowOptions<Additional>) => FactoryWorkflowArtifact<Additional>;
 //#endregion
+//#region src/github-app-token.d.ts
+/**
+ * What a consumer must know to mint: the app id, where the private key is, and
+ * — when it has been recorded — which installation to mint against.
+ *
+ * `installationId` is optional because the installation is discoverable from
+ * the repository. `privateKeyPath` is a path rather than key material so no
+ * consumer has to hold a secret in memory to call this, and so the key-path
+ * convention stays the consumer's.
+ */
+interface GithubAppCredentials {
+  appId: number | string;
+  installationId?: number;
+  privateKeyPath: string;
+}
+/** Carries the HTTP status so a caller can tell a retryable failure apart. */
+declare class GitHubApiError extends Error {
+  readonly status: number;
+  constructor(status: number, statusText: string);
+}
+interface GithubAppTokenOptions {
+  /** Injectable `fetch` (tests, or a caller with its own instrumented one). */
+  fetch?: typeof fetch;
+  /** Wall clock in milliseconds; only the JWT's validity window uses it. */
+  now?: () => number;
+  /** Injectable key read, so a caller can hold the PEM itself if it must. */
+  readPrivateKey?: (privateKeyPath: string) => Buffer | string;
+  /** Per-request timeout; defaults to five seconds. */
+  timeoutMs?: number;
+}
+/**
+ * The signed app JWT GitHub accepts as `Authorization: Bearer` for the App
+ * endpoints. `iss` is stringified because GitHub accepts either spelling and a
+ * numeric app id must not depend on JSON's number formatting.
+ *
+ * The signature is produced from the key on disk and returned; the key
+ * material itself never leaves this call.
+ */
+declare const githubAppJwt: (credentials: GithubAppCredentials, options?: Pick<GithubAppTokenOptions, "now" | "readPrivateKey">) => string;
+/**
+ * Mint an installation access token for one repository.
+ *
+ * When the credentials omit `installationId`, the installation is discovered
+ * from the repository first — the same call every consumer had written for
+ * itself. Nothing is cached: the token is returned to the caller and this
+ * module keeps no copy.
+ */
+declare const mintInstallationToken: (input: {
+  credentials: GithubAppCredentials;
+  owner: string;
+  repo: string;
+}, options?: GithubAppTokenOptions) => Promise<string>;
+//#endregion
 //#region src/execute-alchemy-entry.d.ts
 interface ExecuteAlchemyEntryOptions {
   /**
@@ -257,6 +344,13 @@ declare const FACTORY_PROOF_GATE_CHECK_NAME = "patronage-factory/pr-verify";
 declare const FACTORY_PROOF_GATE_APP_ID = "4314840";
 /** Step id the guard condition refers to. */
 declare const FACTORY_PROOF_GATE_STEP_ID = "factory-proof";
+/**
+ * Human-visible name of the gate step as the Actions jobs API serves it. A
+ * read-only run analyzer (`psf ci:analyze`, #647) matches on this name to
+ * classify a run as proof-reuse versus full fallback, so it is exported from
+ * exactly the module that writes it — matching on a re-typed copy would drift.
+ */
+declare const FACTORY_PROOF_GATE_STEP_NAME = "Check for factory proof of this head";
 /**
  * The shell the gate runs under, and it is a correctness requirement rather
  * than a preference.
@@ -294,6 +388,8 @@ declare const FACTORY_PROOF_GATE_REASON_OUTPUT = "reason";
  * proof that executed every command the surface requires is reusable.
  */
 declare const FACTORY_PROOF_GATE_MODE_OUTPUT = "mode";
+/** Exact Checks API URL of the proof generation selected by the gate. */
+declare const FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT = "source-check-url";
 /**
  * Guard for every step the gate protects. Deliberately `!= 'true'` and not
  * `== 'false'`: an unset, empty, or garbled output must run the suite.
@@ -314,7 +410,8 @@ declare const FACTORY_PROOF_GATE_IF = "github.event_name == 'pull_request'";
  * - `pending`    the newest generation had not completed when this job read it
  * - `failed`     the newest generation records no pass
  * - `unreadable` it passed but carries no binding for this repository and head
- * - `incomplete` it passed but did not execute every required command
+ * - `incomplete` its executed plus stamp-authorized released commands do not
+ *                cover every required command
  * - `ambiguous`  two newest generations share the greatest start time
  * - `error`      the gate could not reach a decision (fail open)
  *
@@ -350,6 +447,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
@@ -445,4 +570,399 @@ declare const proofReuseCoverage: ({
 /** `proofReuseCoverage`, as a build failure. */
 declare const assertProofReuseCoverage: (input: ProofReuseCoverageInput) => ProofReuseCoverageReport;
 //#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, 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 WorkflowStep, assertProofReuseCoverage, bundleAlchemyEntry, executeAlchemyEntry, factoryProofGateScript, factoryProofGateStep, factoryWorkflow, isLocalPreviewStage, localPreviewStage, parseLocalPreviewStage, proofReuseCoverage, proofReuseRequiredCommands };
+//#region src/proof-reuse-presentation.d.ts
+/** Generic timing and presentation steps around the proof-reuse gate (#652). */
+declare const FACTORY_PROOF_TIMING_STEP_ID = "ci-timing";
+declare const FACTORY_PROOF_TIMING_START_STEP_NAME = "Start CI timing";
+declare const FACTORY_PROOF_TIMING_SUMMARY_STEP_NAME = "Record proof-reuse timing";
+interface FactoryProofReusePresentationOptions {
+  /** Human-readable name of the guarded suite. */
+  readonly surface: string;
+}
+interface FactoryProofTimingStartStep {
+  readonly continueOnError: true;
+  readonly id: typeof FACTORY_PROOF_TIMING_STEP_ID;
+  readonly name: typeof FACTORY_PROOF_TIMING_START_STEP_NAME;
+  readonly run: string;
+}
+declare const factoryProofTimingStartStep: () => FactoryProofTimingStartStep;
+declare const factoryProofReuseSummaryScript: ({
+  surface
+}: FactoryProofReusePresentationOptions) => string;
+interface FactoryProofReuseSummaryStep {
+  readonly continueOnError: true;
+  readonly env: Readonly<Record<string, string>>;
+  readonly if: "always()";
+  readonly name: typeof FACTORY_PROOF_TIMING_SUMMARY_STEP_NAME;
+  readonly run: string;
+}
+declare const factoryProofReuseSummaryStep: (options: FactoryProofReusePresentationOptions) => FactoryProofReuseSummaryStep;
+//#endregion
+//#region src/production-impact-workflow.d.ts
+declare const FACTORY_PRODUCTION_IMPACT_STEP_ID = "production_impact";
+declare const FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT = "decision";
+declare const FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT = "basis";
+declare const FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT = "unsubscribed_paths";
+/** Stable GitHub-output key for one declared target. */
+declare const productionImpactTargetOutput: (targetName: string) => string;
+interface FactoryProductionImpactWorkflowOptions {
+  readonly after?: string;
+  readonly before?: string;
+  readonly cli?: string;
+  readonly profilePath?: string;
+  readonly targets: readonly string[];
+}
+interface FactoryProductionImpactWorkflow {
+  /** Outputs for a caller-owned decision job that subsequent jobs may consume. */
+  readonly decisionJobOutputs: Readonly<Record<string, string>>;
+  readonly decisionStep: WorkflowStep;
+  /** A fail-open condition: only an explicit usable withdrawal skips work. */
+  readonly demandedIf: (targetName: string, decisionJob?: string) => string;
+  readonly targetOutputs: Readonly<Record<string, string>>;
+}
+/**
+ * Generate the small factory-owned decision seam for a consumer production
+ * workflow. Consumers retain jobs, deploy commands, credentials, topology,
+ * and convergence checks; this artifact supplies only the decision step and
+ * per-target withdrawal conditions.
+ */
+declare const factoryProductionImpactWorkflow: (options: FactoryProductionImpactWorkflowOptions) => FactoryProductionImpactWorkflow;
+//#endregion
+//#region src/push-identity-workflow.d.ts
+declare const FACTORY_PUSH_IDENTITY_SCHEMA_VERSION = 1;
+declare const FACTORY_PUSH_IDENTITY_ARTIFACT_PREFIX = "factory-push-identity";
+declare const FACTORY_PUSH_IDENTITY_RECORD_STEP_ID = "factory_push_identity_record";
+declare const FACTORY_PUSH_IDENTITY_LOOKUP_STEP_ID = "factory_push_identity_lookup";
+declare const FACTORY_PUSH_IDENTITY_DOWNLOAD_STEP_ID = "factory_push_identity_download";
+declare const FACTORY_PUSH_IDENTITY_CHECKOUT_STEP_ID = "factory_push_identity_checkout";
+declare const FACTORY_PUSH_IDENTITY_VALIDATE_STEP_ID = "factory_push_identity";
+/** Versioned document uploaded by a push-triggered verification run. */
+interface FactoryPushIdentityEnvelope {
+  readonly after: string;
+  readonly before: string;
+  readonly repository: string;
+  readonly runId: string;
+  readonly schemaVersion: typeof FACTORY_PUSH_IDENTITY_SCHEMA_VERSION;
+}
+type FactoryPushIdentityDisposition = "refused" | "usable";
+interface FactoryPushIdentityProducerOptions {
+  /** Explicit caller-owned upload-artifact pin from its workflow artifact. */
+  readonly uploadArtifact: PinnedAction;
+  /** Optional consumer trigger policy combined with the required push event. */
+  readonly if?: string;
+}
+interface FactoryPushIdentityProducer {
+  readonly artifactName: string;
+  readonly steps: readonly WorkflowStep[];
+}
+/**
+ * Record and upload the exact push-event identity without changing the Verify
+ * result when transport is unavailable. Place these steps after verification.
+ */
+declare const factoryPushIdentityProducer: (options: FactoryPushIdentityProducerOptions) => FactoryPushIdentityProducer;
+interface FactoryPushIdentityConsumer {
+  /** Job outputs suitable for a caller-owned decision job and telemetry. */
+  readonly outputs: Readonly<Record<"after" | "before" | "disposition" | "provenance" | "reason", string>>;
+  readonly requiredPermissions: Readonly<{
+    actions: "read";
+    contents: "read";
+  }>;
+  readonly steps: readonly WorkflowStep[];
+  /** Run classification only when exact identity transport is usable. */
+  readonly usableIf: string;
+}
+interface FactoryPushIdentityConsumerOptions {
+  /** Explicit caller-owned checkout pin from its action family. */
+  readonly checkout: PinnedAction;
+  /** Explicit caller-owned download-artifact pin from its workflow artifact. */
+  readonly downloadArtifact: PinnedAction;
+}
+/**
+ * Download and validate identity from exactly the triggering workflow run in
+ * the current repository. Every failure becomes a typed refusal; consumers
+ * retain deploy policy, credentials, commands, topology, and convergence.
+ */
+declare const factoryPushIdentityConsumer: (options: FactoryPushIdentityConsumerOptions) => FactoryPushIdentityConsumer;
+//#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/vitest-profile-reader.d.ts
+/**
+ * Outcome of reading one candidate document. `unrecognized` carries the first
+ * reason the document failed — an analyzer reports it verbatim rather than
+ * treating an unreadable profile as an empty one.
+ */
+type VitestProfileReadResult = {
+  kind: "profile";
+  profile: VitestProfile;
+} | {
+  kind: "unrecognized";
+  reason: string;
+};
+/**
+ * Check one parsed JSON document against the profile contract the writer
+ * emits. Returns the typed profile on success and the first mismatch reason
+ * otherwise — never a partially-usable value.
+ */
+declare const readVitestProfileDocument: (value: unknown) => VitestProfileReadResult;
+//#endregion
+//#region src/workflow-shell-lint.d.ts
+/**
+ * Parse-check the shell embedded in generated workflow YAML (#376).
+ *
+ * The generated-workflow lint validates YAML shape. It never parses the shell
+ * inside a `run:` block, so a script that cannot execute at all — a stray
+ * `fi`, an unclosed quote, a `then` with no `if` — passes every local check
+ * and only fails when the runner reaches it. That is not hypothetical:
+ * paitronage#1090 shipped a stray `fi` into a generated workflow and made
+ * every automated preview destroy a parse-time no-op for five days.
+ *
+ * `bash -n` is the whole control: it parses without executing. It lives here,
+ * once, rather than as a contract test in each consumer, because a guard
+ * copied per repository is a guard that exists in some of them.
+ */
+/** One `run:` block that bash refuses to parse. */
+interface WorkflowShellParseFailure {
+  /** The step's `name:` when the YAML carried one. */
+  readonly step?: string;
+  /** The script as bash saw it, expressions already neutralized. */
+  readonly script: string;
+  /** What bash said. */
+  readonly stderr: string;
+}
+/** A `run:` block lifted out of generated YAML, with its step's `shell:`. */
+interface RunBlock {
+  readonly script: string;
+  readonly shell?: string;
+  readonly step?: string;
+}
+/**
+ * Every `run:` block in a generated workflow, paired with the `shell:` its
+ * step declares.
+ *
+ * Deliberately a scanner over the emitted text and not a YAML parse: this
+ * package takes no dependency it does not need, and the emitted shape is one
+ * generator's output, not arbitrary YAML. It reads both block scalars
+ * (`run: |-`) and inline scripts.
+ */
+declare const workflowRunBlocks: (yaml: string) => RunBlock[];
+/** Every `run:` block its interpreter refuses to parse. Empty means sound. */
+declare const workflowShellParseFailures: (yaml: string) => WorkflowShellParseFailure[];
+/**
+ * Fail the generated-workflow lint when any embedded `run:` block is not
+ * parseable bash. Call it on the YAML a generator is about to write, so the
+ * defect is caught at generation rather than by the runner.
+ */
+declare const assertWorkflowShellParses: (yaml: string, options: {
+  readonly source: string;
+}) => void;
+//#endregion
+export { type BundleAlchemyEntryOptions, type CheckoutStepOptions, type ExecuteAlchemyEntryOptions, type ExecuteAlchemyEntryResult, FACTORY_CANDIDATE_PULL_REQUEST_TYPES, FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT, FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT, FACTORY_PRODUCTION_IMPACT_STEP_ID, FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT, 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_SOURCE_URL_OUTPUT, FACTORY_PROOF_GATE_STEP_ID, FACTORY_PROOF_GATE_STEP_NAME, FACTORY_PROOF_TIMING_START_STEP_NAME, FACTORY_PROOF_TIMING_STEP_ID, FACTORY_PROOF_TIMING_SUMMARY_STEP_NAME, FACTORY_PUSH_IDENTITY_ARTIFACT_PREFIX, FACTORY_PUSH_IDENTITY_CHECKOUT_STEP_ID, FACTORY_PUSH_IDENTITY_DOWNLOAD_STEP_ID, FACTORY_PUSH_IDENTITY_LOOKUP_STEP_ID, FACTORY_PUSH_IDENTITY_RECORD_STEP_ID, FACTORY_PUSH_IDENTITY_SCHEMA_VERSION, FACTORY_PUSH_IDENTITY_VALIDATE_STEP_ID, type FactoryProductionImpactWorkflow, type FactoryProductionImpactWorkflowOptions, type FactoryProofGateOptions, type FactoryProofGateReason, type FactoryProofGateStep, type FactoryProofReusePresentationOptions, type FactoryProofReuseSummaryStep, type FactoryProofTimingStartStep, type FactoryPushIdentityConsumer, type FactoryPushIdentityConsumerOptions, type FactoryPushIdentityDisposition, type FactoryPushIdentityEnvelope, type FactoryPushIdentityProducer, type FactoryPushIdentityProducerOptions, 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 VitestProfileReadResult, type VitestProfileSample, type VitestProfileSampleExecution, type VitestTestStatus, type WorkflowShellParseFailure, type WorkflowStep, assertProofReuseCoverage, assertWorkflowShellParses, bundleAlchemyEntry, captureVitestProfileEnvironment, executeAlchemyEntry, factoryCandidateOrPushCondition, factoryProductionImpactWorkflow, factoryProofGateScript, factoryProofGateStep, factoryProofReuseSummaryScript, factoryProofReuseSummaryStep, factoryProofTimingStartStep, factoryPushIdentityConsumer, factoryPushIdentityProducer, factoryWorkflow, githubAppJwt, isLocalPreviewStage, localPreviewStage, mintInstallationToken, normalizeVitestProfileSample, parseLocalPreviewStage, productionImpactTargetOutput, proofReuseCoverage, proofReuseRequiredCommands, readVitestProfileDocument, resolveProofReuseCommands, runVitestProfile, workflowRunBlocks, workflowShellParseFailures, writeVitestProfile };