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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patronage/factory-ci",
-  "version": "0.2.1",
+  "version": "1.0.0-alpha.13",
   "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,22 +22,20 @@
   "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"
   },
   "devDependencies": {
     "@types/node": "24.13.3",
+    "@vitest/coverage-v8": "4.1.10",
     "oxfmt": "0.59.0",
     "oxlint": "1.74.0",
     "tsdown": "0.21.10",
@@ -56,6 +54,8 @@
     "prefix": "bash ../scripts/ensure-worktree-bootstrap.sh",
     "fix": "ultracite fix",
     "pretest": "bash ../scripts/ensure-worktree-bootstrap.sh",
+    "precoverage": "bash ../scripts/ensure-worktree-bootstrap.sh",
+    "coverage": "vitest run --coverage",
     "test": "vitest run",
     "pretypecheck": "bash ../scripts/ensure-worktree-bootstrap.sh",
     "typecheck": "tsc --noEmit"

package/src/bundle-alchemy-entry.ts

@@ -10,6 +10,79 @@ import { build } from "esbuild";
  */
 const ALCHEMY_EXTERNALS = ["alchemy", "alchemy/*", "effect", "effect/*"];
 
+/**
+ * The package names behind `ALCHEMY_EXTERNALS`, derived rather than restated so
+ * a future external can never be guarded by only one of two lists.
+ */
+const RESERVED_ALIAS_PACKAGES = [
+  ...new Set(
+    ALCHEMY_EXTERNALS.map((external) =>
+      external.replace(/\/\*$/u, "").toLowerCase()
+    )
+  ),
+];
+
+const reservedAliasKey = (key: string): string | undefined =>
+  RESERVED_ALIAS_PACKAGES.find(
+    (name) => key === name || key.startsWith(`${name}/`)
+  );
+
+/**
+ * Refuse an alias *key* that is itself a reserved package or one of its
+ * subpaths. esbuild substitutes aliases before it decides what is external, so
+ * such a key defeats `external` outright. Keys are compared, never resolved,
+ * which is what makes string matching sound here.
+ */
+const assertAliasKeysAreAdmissible = (
+  alias: Readonly<Record<string, string>>
+): void => {
+  for (const key of Object.keys(alias)) {
+    const reserved = reservedAliasKey(key);
+    if (reserved) {
+      throw new Error(
+        `bundleAlchemyEntry cannot alias "${key}": ${reserved} must stay external because its identity is shared with the consumer's runtime, and esbuild applies aliases before external matching. Point the consumer's own resolution at one copy instead.`
+      );
+    }
+  }
+};
+
+/**
+ * Whether a bundled input lives inside a reserved package.
+ *
+ * Metafile inputs are paths esbuild resolved and normalized itself, so
+ * comparing whole segments here answers what was *bundled* rather than how the
+ * config was spelled. Segments are compared case-insensitively: on a
+ * case-insensitive filesystem `node_modules/Effect/…` resolves to the real
+ * package and the metafile keeps the caller's spelling.
+ */
+const isReservedInput = (input: string): boolean => {
+  const segments = input.toLowerCase().split(/[/\\]+/u);
+  return segments.some(
+    (segment, position) =>
+      position > 0 &&
+      segments[position - 1] === "node_modules" &&
+      RESERVED_ALIAS_PACKAGES.includes(segment)
+  );
+};
+
+/**
+ * Assert the externals contract against the bundle esbuild actually produced.
+ *
+ * Checking alias *values* instead was unsound by construction: `..` segments,
+ * symlinks, and every other spelling of the same file each need another string
+ * rule, and the scanner loses. The metafile records the inputs after esbuild's
+ * own resolution and normalization, so one check closes the whole class —
+ * whatever route reached an identity-sensitive package, it shows up here.
+ */
+const assertNoReservedInputs = (inputs: readonly string[]): void => {
+  const offenders = inputs.filter(isReservedInput);
+  if (offenders.length > 0) {
+    throw new Error(
+      `bundleAlchemyEntry refused a bundle carrying a second copy of an identity-sensitive package: ${offenders.join(", ")}. Those packages must resolve from the consumer's runtime, so nothing may pull their files into the bundle — an alias that re-exports them by bare specifier stays external and is fine.`
+    );
+  }
+};
+
 export interface BundleAlchemyEntryOptions {
   /** The Alchemy entry to bundle, e.g. `alchemy.run.ts`. */
   readonly entry: string;
@@ -17,6 +90,18 @@ export 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
@@ -49,6 +134,10 @@ export interface BundleAlchemyEntryOptions {
 export const bundleAlchemyEntry = async (
   options: BundleAlchemyEntryOptions
 ): Promise<string> => {
+  if (options.alias) {
+    assertAliasKeysAreAdmissible(options.alias);
+  }
+
   const root = options.absWorkingDir
     ? path.resolve(options.absWorkingDir)
     : process.cwd();
@@ -56,21 +145,25 @@ export const bundleAlchemyEntry = async (
 
   await mkdir(path.dirname(outfile), { recursive: true });
 
-  await build({
+  const result = await build({
     absWorkingDir: root,
     bundle: true,
     entryPoints: [path.resolve(root, options.entry)],
     external: ALCHEMY_EXTERNALS,
     format: "esm",
+    metafile: true,
     outfile,
     packages: options.packages ?? "external",
     platform: "node",
     sourcemap: options.sourcemap ?? false,
     target: options.target ?? "node24",
+    ...(options.alias ? { alias: { ...options.alias } } : {}),
     ...(options.tsconfig
       ? { tsconfig: path.resolve(root, options.tsconfig) }
       : {}),
   });
 
+  assertNoReservedInputs(Object.keys(result.metafile.inputs));
+
   return outfile;
 };

package/src/candidate-lifecycle.ts

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+export const FACTORY_CANDIDATE_PULL_REQUEST_TYPES = Object.freeze([
+  "opened",
+  "synchronize",
+  "reopened",
+  "ready_for_review",
+] as const);
+
+/**
+ * Build a GitHub Actions job condition for candidate PRs and merge-target
+ * pushes. The caller owns triggers, jobs, runners, permissions, and topology.
+ */
+export const factoryCandidateOrPushCondition = (
+  candidateCondition?: string
+): string => {
+  const candidate = [
+    "github.event_name == 'pull_request'",
+    "github.event.pull_request.draft != true",
+    ...(candidateCondition ? [candidateCondition] : []),
+  ].join(" && ");
+
+  return ["github.event_name == 'push'", `(${candidate})`].join(" || ");
+};

package/src/factory-workflow.ts

@@ -1,10 +1,13 @@
 import type { NodePnpmActionFamily, PinnedAction } from "./actions.ts";
+import { assertPinnedAction } from "./pinned-action.ts";
 
-const PINNED_ACTION_PATTERN = /^[\w.-]+\/[\w.-]+@[0-9a-f]{40}$/u;
-const ACTION_TAG_PATTERN = /^v\d+(?:\.\d+){0,2}$/u;
 const RESERVED_ACTION_NAMES = new Set(["checkout", "setupNode", "setupPnpm"]);
 
 export 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>>;
@@ -12,6 +15,7 @@ export interface WorkflowStep {
 }
 
 export interface CheckoutStepOptions {
+  readonly fetchDepth?: number;
   readonly name?: string;
   readonly ref?: string;
 }
@@ -76,31 +80,6 @@ const assertSingleLine = (name: string, value: string): void => {
   }
 };
 
-const actionRepository = (action: PinnedAction): string =>
-  action.uses.slice(0, action.uses.indexOf("@"));
-
-const assertPinnedAction = (
-  name: string,
-  action: PinnedAction,
-  expectedRepository?: string
-): void => {
-  if (!PINNED_ACTION_PATTERN.test(action.uses)) {
-    throw new Error(
-      `${name} must use owner/repository@<40-character commit SHA>, got "${action.uses}".`
-    );
-  }
-  if (expectedRepository && actionRepository(action) !== expectedRepository) {
-    throw new Error(
-      `${name} must pin ${expectedRepository}, got ${actionRepository(action)}.`
-    );
-  }
-  if (!ACTION_TAG_PATTERN.test(action.tag)) {
-    throw new Error(
-      `${name} tag must be vN, vN.N, or vN.N.N, got "${action.tag}".`
-    );
-  }
-};
-
 const usesStep = (
   fallbackName: string,
   action: PinnedAction
@@ -129,6 +108,25 @@ const assertAdditionalActions = (
   }
 };
 
+const checkoutInputs = (
+  checkout: CheckoutStepOptions | undefined
+): Readonly<Record<string, string>> | undefined => {
+  if (checkout === undefined) {
+    return undefined;
+  }
+  const inputs: Record<string, string> = {};
+  if (checkout.fetchDepth !== undefined) {
+    if (!Number.isSafeInteger(checkout.fetchDepth) || checkout.fetchDepth < 0) {
+      throw new Error("checkout.fetchDepth must be a non-negative integer.");
+    }
+    inputs["fetch-depth"] = String(checkout.fetchDepth);
+  }
+  if (checkout.ref) {
+    inputs.ref = checkout.ref;
+  }
+  return Object.keys(inputs).length > 0 ? inputs : undefined;
+};
+
 const setupSteps = (
   family: NodePnpmActionFamily,
   setup: FactoryWorkflowSetupOptions = {}
@@ -141,11 +139,12 @@ const setupSteps = (
   }
 
   const { checkout, setupNode } = setup;
+  const checkoutWith = checkoutInputs(checkout);
   return Object.freeze([
     {
       name: checkout?.name ?? "Checkout",
       uses: family.checkout.uses,
-      ...(checkout?.ref ? { with: { ref: checkout.ref } } : {}),
+      ...(checkoutWith ? { with: checkoutWith } : {}),
     },
     usesStep("Setup pnpm", family.setupPnpm),
     {

package/src/github-app-token.ts

@@ -0,0 +1,162 @@
+import { createSign } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+/**
+ * Minting a GitHub App installation token: the RS256 app JWT, the optional
+ * installation lookup, and the token exchange (#617).
+ *
+ * Two projects had grown the same three steps independently — the factory's
+ * check-run publisher and paitronage's proof-comment publisher — which is the
+ * admitted-on-repetition bar. Only the *mechanism* lives here. Where the
+ * private key comes from, how the app id is configured, and what the token is
+ * then used for stay with each consumer: this module is handed credentials and
+ * returns a token.
+ */
+
+/** The default request budget, matching the factory's other GitHub writes. */
+const DEFAULT_TIMEOUT_MS = 5000;
+
+/** Nine-minute JWT lifetime, backdated a minute against runner clock skew. */
+const JWT_BACKDATE_SECONDS = 60;
+const JWT_LIFETIME_SECONDS = 600;
+
+/**
+ * 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.
+ */
+export interface GithubAppCredentials {
+  appId: number | string;
+  installationId?: number;
+  privateKeyPath: string;
+}
+
+/** Carries the HTTP status so a caller can tell a retryable failure apart. */
+export class GitHubApiError extends Error {
+  readonly status: number;
+
+  constructor(status: number, statusText: string) {
+    super(`GitHub API ${status} ${statusText}`);
+    this.name = "GitHubApiError";
+    this.status = status;
+  }
+}
+
+export 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;
+}
+
+const base64url = (value: Buffer | string): string =>
+  Buffer.from(value).toString("base64url");
+
+/**
+ * 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.
+ */
+export const githubAppJwt = (
+  credentials: GithubAppCredentials,
+  options: Pick<GithubAppTokenOptions, "now" | "readPrivateKey"> = {}
+): string => {
+  const nowMs = (options.now ?? Date.now)();
+  const issuedAt = Math.floor(nowMs / 1000) - JWT_BACKDATE_SECONDS;
+  const header = base64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+  const payload = base64url(
+    JSON.stringify({
+      exp: issuedAt + JWT_LIFETIME_SECONDS,
+      iat: issuedAt,
+      iss: String(credentials.appId),
+    })
+  );
+  const unsigned = `${header}.${payload}`;
+  const readKey = options.readPrivateKey ?? readFileSync;
+  const signer = createSign("RSA-SHA256");
+  signer.update(unsigned);
+  signer.end();
+  return `${unsigned}.${signer.sign(readKey(credentials.privateKeyPath), "base64url")}`;
+};
+
+const githubAppJson = async (
+  request: typeof fetch,
+  url: string,
+  jwt: string,
+  method: "GET" | "POST",
+  timeoutMs: number
+): Promise<Record<string, unknown>> => {
+  const response = await request(url, {
+    headers: {
+      Accept: "application/vnd.github+json",
+      Authorization: `Bearer ${jwt}`,
+      "X-GitHub-Api-Version": "2022-11-28",
+    },
+    method,
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!response.ok) {
+    throw new GitHubApiError(response.status, response.statusText);
+  }
+  return (await response.json()) as Record<string, unknown>;
+};
+
+/**
+ * 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.
+ */
+export const mintInstallationToken = async (
+  input: {
+    credentials: GithubAppCredentials;
+    owner: string;
+    repo: string;
+  },
+  options: GithubAppTokenOptions = {}
+): Promise<string> => {
+  const { credentials } = input;
+  const request = options.fetch ?? fetch;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const jwt = githubAppJwt(credentials, options);
+
+  let { installationId } = credentials;
+  if (installationId === undefined) {
+    const installation = await githubAppJson(
+      request,
+      `https://api.github.com/repos/${input.owner}/${input.repo}/installation`,
+      jwt,
+      "GET",
+      timeoutMs
+    );
+    if (typeof installation.id !== "number") {
+      throw new TypeError("GitHub App installation response omitted id");
+    }
+    installationId = installation.id;
+  }
+
+  const minted = await githubAppJson(
+    request,
+    `https://api.github.com/app/installations/${installationId}/access_tokens`,
+    jwt,
+    "POST",
+    timeoutMs
+  );
+  if (typeof minted.token !== "string") {
+    throw new TypeError("GitHub App token response omitted token");
+  }
+  return minted.token;
+};

package/src/index.ts

@@ -13,6 +13,10 @@ export {
   type NodePnpmActionFamily,
   type PinnedAction,
 } from "./actions.ts";
+export {
+  FACTORY_CANDIDATE_PULL_REQUEST_TYPES,
+  factoryCandidateOrPushCondition,
+} from "./candidate-lifecycle.ts";
 export {
   bundleAlchemyEntry,
   type BundleAlchemyEntryOptions,
@@ -36,6 +40,13 @@ export {
   type SetupNodeStepOptions,
   type WorkflowStep,
 } from "./factory-workflow.ts";
+export {
+  GitHubApiError,
+  type GithubAppCredentials,
+  githubAppJwt,
+  type GithubAppTokenOptions,
+  mintInstallationToken,
+} from "./github-app-token.ts";
 export {
   type ExecuteAlchemyEntryOptions,
   type ExecuteAlchemyEntryResult,
@@ -52,7 +63,9 @@ export {
   FACTORY_PROOF_GATE_REASON_OUTPUT,
   FACTORY_PROOF_GATE_REASONS,
   FACTORY_PROOF_GATE_SHELL,
+  FACTORY_PROOF_GATE_SOURCE_URL_OUTPUT,
   FACTORY_PROOF_GATE_STEP_ID,
+  FACTORY_PROOF_GATE_STEP_NAME,
   type FactoryProofGateOptions,
   type FactoryProofGateReason,
   factoryProofGateScript,
@@ -63,4 +76,71 @@ export {
   type ProofReuseCoverageInput,
   type ProofReuseCoverageReport,
   proofReuseRequiredCommands,
+  resolveProofReuseCommands,
 } from "./proof-reuse-gate.ts";
+export {
+  type FactoryProofReusePresentationOptions,
+  type FactoryProofReuseSummaryStep,
+  type FactoryProofTimingStartStep,
+  FACTORY_PROOF_TIMING_START_STEP_NAME,
+  FACTORY_PROOF_TIMING_STEP_ID,
+  FACTORY_PROOF_TIMING_SUMMARY_STEP_NAME,
+  factoryProofReuseSummaryScript,
+  factoryProofReuseSummaryStep,
+  factoryProofTimingStartStep,
+} from "./proof-reuse-presentation.ts";
+export {
+  FACTORY_PRODUCTION_IMPACT_BASIS_OUTPUT,
+  FACTORY_PRODUCTION_IMPACT_DECISION_OUTPUT,
+  FACTORY_PRODUCTION_IMPACT_STEP_ID,
+  FACTORY_PRODUCTION_IMPACT_UNSUBSCRIBED_OUTPUT,
+  type FactoryProductionImpactWorkflow,
+  type FactoryProductionImpactWorkflowOptions,
+  factoryProductionImpactWorkflow,
+  productionImpactTargetOutput,
+} from "./production-impact-workflow.ts";
+export {
+  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 FactoryPushIdentityConsumer,
+  type FactoryPushIdentityConsumerOptions,
+  type FactoryPushIdentityDisposition,
+  type FactoryPushIdentityEnvelope,
+  factoryPushIdentityConsumer,
+  type FactoryPushIdentityProducer,
+  type FactoryPushIdentityProducerOptions,
+  factoryPushIdentityProducer,
+} from "./push-identity-workflow.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 {
+  readVitestProfileDocument,
+  type VitestProfileReadResult,
+} from "./vitest-profile-reader.ts";
+export {
+  assertWorkflowShellParses,
+  workflowRunBlocks,
+  type WorkflowShellParseFailure,
+  workflowShellParseFailures,
+} from "./workflow-shell-lint.ts";

package/src/pinned-action.ts

@@ -0,0 +1,30 @@
+import type { PinnedAction } from "./actions.ts";
+
+const PINNED_ACTION_PATTERN = /^[\w.-]+\/[\w.-]+@[0-9a-f]{40}$/u;
+const ACTION_TAG_PATTERN = /^v\d+(?:\.\d+){0,2}$/u;
+
+const actionRepository = (action: PinnedAction): string =>
+  action.uses.slice(0, action.uses.indexOf("@"));
+
+/** Shared validator for every action pin emitted by factory-ci helpers. */
+export const assertPinnedAction = (
+  name: string,
+  action: PinnedAction,
+  expectedRepository?: string
+): void => {
+  if (!PINNED_ACTION_PATTERN.test(action.uses)) {
+    throw new Error(
+      `${name} must use owner/repository@<40-character commit SHA>, got "${action.uses}".`
+    );
+  }
+  if (expectedRepository && actionRepository(action) !== expectedRepository) {
+    throw new Error(
+      `${name} must pin ${expectedRepository}, got ${actionRepository(action)}.`
+    );
+  }
+  if (!ACTION_TAG_PATTERN.test(action.tag)) {
+    throw new Error(
+      `${name} tag must be vN, vN.N, or vN.N.N, got "${action.tag}".`
+    );
+  }
+};