breakage 0.8.4 → 0.9.0

package/npm.md

@@ -0,0 +1,236 @@
+# npm peer compatibility
+
+Use `breakage npm` to test a packed package against the peer versions you declare. This is an optional npm-specific feature. The ordinary public check and its four adoption conditions remain the same; keep that check required alongside peer compatibility.
+
+Consider an integration with `"atom.io": "^1 || ^2"`. Its current workspace tests may pass against an edited core, even if only the integration will ship. Representative environments let it prove compatibility with actual released versions. An explicitly registered candidate environment can additionally prove conditional compatibility with a core release your release plan identifies.
+
+The npm commands require Node 22.18 or newer (including native erasable TypeScript for `.ts` configuration), Git, and your installation/test tools. They run on the filesystem, inside complete representative directories. They do not publish packages.
+
+## Declare support deliberately
+
+Current candidates must declare explicit peer support eras, for example `"atom.io": "^0.53.3 || ^0.54.0"`. Moving workspace shorthand (`workspace:`, `workspace:*`, `workspace:^`, and `workspace:~`) is rejected, including in coordinated peer candidates. With `workspace:^`, advancing the local core from `0.53.3` to `0.54.0` silently changes the published support range and drops the previous era. Keep that decision explicit and test the versions you promise to support.
+
+A fixed declaration such as `workspace:^0.53.3` is accepted and compared as `^0.53.3`, matching its packed form. Ordinary semver ranges and optional peers retain their meaning. Workspace aliases and relative paths are unsupported. Current source manifests are never rewritten by this normalization.
+
+Older releases may have used moving shorthand. For the baseline comparison, register that peer's directory in `localPeers`; Breakage reads its version from the same historical commit as the integration manifest. For example, historical `workspace:^` becomes `^0.53.3` when that commit's peer version is `0.53.3`, even if today's checkout or release plan says `0.54.0`. Missing historical evidence is a setup error. The configured directory must exist at the baseline commit; automatic tracking across package moves is unsupported.
+
+After removing a peer requirement, you may retain its historical registration even if its directory has been deleted from the current checkout. Breakage still checks existing registered directories for workspace-source leaks. A broken directory link remains an error.
+
+## Start with released peers
+
+In the integration package, create complete environments for the peer formulations you want to exercise. For example, `peer-environments/core-1/package.json`:
+
+```json
+{
+	"name": "core-1-contracts",
+	"version": "1.0.0",
+	"private": true,
+	"type": "module",
+	"dependencies": { "atom.io": "1.12.0", "react": "19.0.0" }
+}
+```
+
+Pin every dependency in an environment manifest to an exact version: `"host": "1.0.0"` and `"host": "2.1.4"` are valid; `"host": "^1"` and `"host": "^1 || ^2"` are setup errors. This applies to all entries in `dependencies`, `devDependencies`, `optionalDependencies`, and `peerDependencies`, including test runners and helpers. Exact prerelease and build versions are allowed. Ranges, wildcards, tags, aliases, workspace protocols, and file or URL specifiers are rejected before installation. The integration's own `peerDependencies` still express its supported eras with ranges. Enroll coordinated local releases through `breakage.candidates`; their resolved intended versions supply the exact identities, and any accompanying dependency pins must match those versions.
+
+Choose real published versions appropriate for your package. Install once and commit this directory's manifest and lock file. Add any test runner and helpers it needs to its own development dependencies with exact pins. Give each additional formulation its own directory and lock file. Every required peer of the integration must be present; several coupled peers share one environment. Include all intended representatives in the glob, including multiple representatives of the same era.
+
+Ignore the disposable execution directories in your repository:
+
+```gitignore
+peer-environments/*/test/
+node_modules/
+artifacts/
+```
+
+Build and pack the integration before checking. `npm pack --ignore-scripts --pack-destination artifacts` creates an archive with a versioned filename; configure `artifact` to that file or have your build copy it to a stable path. Breakage checks the installed archive's name, version, and peer declarations against the current manifest. Repository preparation owns making the archive current, including generated files and runtime version constants.
+
+Write current contracts that import the package and its peers by consumer package names. Keep fixtures and explicit runner configuration under the package directory. The command runs in `peer-environments/<name>/test/`, with those selected paths copied intact. Avoid source aliases, workspace-relative imports, and runner configurations that walk back to workspace source. A Node test runner contract might look like:
+
+```ts
+import { test } from "node:test"
+import { strict as assert } from "node:assert"
+import { createIntegration } from "my-integration"
+import { createStore } from "atom.io"
+
+test("the integration uses a consumer's store", () => {
+	const store = createStore()
+	const integration = createIntegration(store)
+	assert.equal(integration.store, store)
+})
+```
+
+Use your actual public API and meaningful assertions. A suite must fail when no tests execute. Exit 1 denotes assertions failing; other nonzero exits denote setup failure. If your runner reports infrastructure errors as 1 too, wrap it to distinguish setup from assertions. Breakage separately classifies failures in preparation, artifact installation, coverage, and resolution as setup failures.
+
+Create `breakage.config.ts`:
+
+```ts
+import type { NpmConfig } from "breakage"
+
+export default {
+	npm: {
+		artifact: "artifacts/integration.tgz",
+		representatives: "peer-environments/*",
+		lockfile: "package-lock.json",
+		prepareCommand: "npm ci --ignore-scripts --workspaces=false",
+		suites: {
+			"atom.io": {
+				files: ["contracts/core/**/*.ts", "fixtures/**/*"],
+				command: "node --test contracts/core/*.test.ts",
+			},
+		},
+		localPeers: {
+			"atom.io": {
+				directory: "../atom.io",
+				artifact: "../atom.io/artifacts/core.tgz",
+			},
+		},
+		baseline: { tagPattern: "refs/tags/my-integration@" },
+	} satisfies NpmConfig,
+}
+```
+
+Every file glob must select at least one regular file. Remove the fixture glob if you have no fixtures. `packageDirectory` defaults to the config file's directory; all npm paths resolve from that package directory. Glob discovery uses paths as labels and installed versions as evidence. Register local peer directories in `localPeers`; each declared local peer must have a suite, and its planned upcoming releases must be supported and exercised by a coordinated representative. External peer suites are an explicit opt-in. No matrix is inferred from registry metadata.
+
+The previous manifest comes from the newest matching release tag. An existing core `baselineFile` may pin a fetched release. For a package's first publication, explicitly use `baseline: { firstRelease: true }` and remove that exception after publishing; missing baseline evidence never silently passes.
+
+Run the package check or a focused test:
+
+```sh
+breakage npm check
+breakage npm check --coverage-only
+breakage npm test atom.io 1
+breakage npm test --representative peer-environments/core-1
+breakage npm check --config ./breakage.config.ts --json
+```
+
+All matching representatives run. Every explicit `||` era needs coverage. Preview versions cover only an exact preview alternative, not stable ranges or other previews. Build metadata does not affect range matching, including exact preview selection; installed versions must still match their complete environment pins. Released representatives outside declared support warn; excluding a planned local release fails the release check. Focused requests can intentionally explore versions outside declared support. An audit reports declarations and release-policy findings without claiming assertions passed. Exit statuses are 0 for successful requested work, 1 for compatibility or unapproved support failures, and 2 for setup or coverage errors.
+
+Focused peer/range requests validate manifest pins and skip versions outside the requested range before acquiring stages or preparing dependencies. Coordinated candidates are selected by their resolved intended versions, and exact-preview selection follows the same rules as coverage. Excluded environments need no lockfile or available stage. Disjoint requests for the same peer can run independently in one checkout without parsing lock files. Requests that select the same environment still contend for its stage, including requests for different peers in a coupled environment. Selected installations retain all frozen-input, identity, and compatibility checks.
+
+## Coordinated releases
+
+Create a separate representative that explicitly names candidate peers. Leave an unpublished peer out of the frozen dependency list:
+
+```json
+{
+	"name": "core-next-contracts",
+	"version": "1.0.0",
+	"private": true,
+	"type": "module",
+	"dependencies": { "react": "19.0.0" },
+	"breakage": { "candidates": ["atom.io"] }
+}
+```
+
+Set `release.resolveDelta` to a synchronous/asynchronous resolver receiving `packageName`, `packageDirectory`, and `currentVersion`. For Changesets, use the optional helper:
+
+```ts
+import { changesetsReleaseDelta } from "breakage/changesets"
+import { semverPolicy } from "breakage"
+
+const release = {
+	resolveDelta: changesetsReleaseDelta(),
+	policy: semverPolicy({ beforeV1: "minor" }),
+}
+```
+
+Assign this object to `npm.release`, or share it at the top level with `defineConfig`. A custom resolver returns `{ previousVersion, version, delta }` or `undefined`; errors must throw. Missing intent blocks that candidate environment. Inspection errors and invalid evidence are setup errors, not absent intent. Both transition versions must be exact, the target must be at least the current workspace version, and the delta must match the versions. Candidate identity uses the transition's `version`; no breaking-change policy is applied to candidate enrollment. The candidate archive may have its workspace version or the intended version. Breakage reports both versions. If they differ, it substitutes the intended version in the installed peer's disposable manifest using a fresh file and atomic replacement, preserving shared cache files, other environments, the archive, and the workspace. Archives already carrying their intended version need no substitution.
+
+That substitution simulates release metadata; it does not rebuild the package or change version constants embedded in executable code. Your build owns those constants. To exercise the final version metadata directly, supply a peer archive already built with the resolved intended version.
+
+Both `npm check` and its coverage-only audit inspect each currently declared `localPeers` package's release intent, even if you omitted its candidate environment. A resolved intended version must be included in the integration's peer range and covered by a coordinated representative. Missing either fails with exit 2; an installed peer at the same version does not substitute for testing the local candidate. Optional local peers have the same obligation when declared. Resolver errors and invalid evidence fail setup. Resolvers are evaluated once per package and baseline context per invocation, and must return that package's own release intent.
+
+For a core still labeled `0.53.3` with a planned `0.54.0` release, an integration declaring only `^0.53.3` fails. Adding `|| ^0.54.0` is recommended when retaining the older era. Admission uses version membership: `0.54.0`, `*`, and other ranges containing that version qualify too. Exact-preview enrollment, coverage of other declared eras, and breaking release evidence for dropping old support still apply. Your delta resolver supplies the intended transition before a versioning PR is merged; Breakage does not infer it from an open PR.
+
+Candidate results are conditional on publication. They can cover a new era, but cannot excuse an incompatible released version that the integration still advertises. Unreleased local edits with no release intent create no new coordination obligation. Registering a currently declared local peer means the integration must accommodate its planned releases. Registrations retained only for historical resolution do not impose this obligation after the peer declaration is removed. The repository owns publication order.
+
+Every coordinated candidate must also accept the representative's peer versions in its own normalized `peerDependencies`. For example, a candidate declaring `minimatch: ^8` cannot be approved alongside Minimatch 9, even if the integration declares `^9` and its assertions pass. Both full checks and coverage audits reject that conflict before candidate installation with exit 2, identifying the candidate, required range, and observed version. The representative must supply required peers needed only by a coordinated candidate too; these additional identities do not require separate integration suites. Absent optional peers are allowed, but present optional peers must satisfy their ranges. Another coordinated peer contributes its resolved intended version; a peer on the integration itself uses the integration's current archive version.
+
+Focused `npm test` commands remain available for exploration before advertising an upcoming version. They warn about coordinated candidates' incompatible peer ranges and still execute, while missing required peers remain setup errors. They check release intent for the selected candidate environments but do not audit every planned local release; require the full check or coverage audit as part of the release gate.
+
+## Shared release configuration
+
+Use `defineConfig` to share a release resolver and policy with public checks:
+
+```ts
+import { defineConfig, semverPolicy } from "breakage"
+import { changesetsReleaseDelta } from "breakage/changesets"
+
+export default defineConfig({
+	testPattern: "tests/public/**/*",
+	test: "npm run test:public",
+	release: {
+		resolveDelta: changesetsReleaseDelta(),
+		policy: semverPolicy({ beforeV1: "minor" }),
+	},
+	npm: {
+		artifact: "artifacts/integration.tgz",
+		representatives: "peer-environments/*",
+		lockfile: "package-lock.json",
+		prepareCommand: "npm ci --ignore-scripts --workspaces=false",
+		suites: {
+			"atom.io": {
+				files: ["contracts/core/**/*.ts"],
+				command: "node --test contracts/core/*.test.ts",
+			},
+		},
+		baseline: { tagPattern: "refs/tags/my-integration@" },
+	},
+})
+```
+
+`defineConfig` inherits the top-level `release` into `npm.release`; an explicit `npm.release` overrides it. Programmatic callers can pass the resulting `config.npm` to `npmCheck` or `npmTest`. Both npm and public CLI commands use the same config loader. npm paths remain relative to the config file's directory, or to `npm.packageDirectory` resolved from it.
+
+`npm.release.resolveDelta` replaces `releaseIntent` and returns `{ previousVersion, version, delta }` or `undefined`. Resolution is cached per package and baseline context for each npm invocation. Support checks supply `baseline: { version }` from the integration's historical manifest; Breakage rejects a transition whose `previousVersion` disagrees with that baseline. Local-peer candidate checks have no historical baseline and use the transition's target version for candidate identity and coordination obligations. `changesetsReleaseDelta()` is a factory that returns the resolver, comparing the supplied baseline (or current manifest) with the planned version before Changesets versioning and the manifest version afterward. Because the manifest fallback also supplies a target for an unchanged registered local peer, using it opts those peers into candidate coverage too. A custom resolver can return `undefined` for packages that should have no local release intent. See the [release configuration guide](README.md#typescript-configuration-and-release-intent) for optional Changesets dependencies and standalone helpers.
+
+`npm.release.policy` replaces `certifyBreaking`. The default requires a major increment; `semverPolicy({ beforeV1: "minor" })` permits pre-1.0 minor increments too. Missing evidence or a compatible version delta leaves a support drop unapproved. Invalid evidence and resolver/policy errors fail setup. Compatibility failures against still-declared peers remain failures even when the integration has a breaking release. The old `releaseIntent` and `certifyBreaking` hooks are removed and fail with migration guidance. Policies must be functions and receive `{ previousVersion, version, delta }`.
+
+`prepareCommand`, `installCommand`, and each suite's `command` are nonempty shell strings. Preparation runs in the representative directory; installation and suites run in its disposable `test/` directory. Breakage captures stdout and stderr for reporting. All nonzero preparation/installation results fail setup; suite exit 1 denotes incompatibility and other nonzero exits denote setup failure. Functions are reserved for the release-delta resolver and policy.
+
+## Removing support
+
+`npm check` compares semantic version sets with the previous release. Narrowing a supported range, adding a new required peer, or making an optional peer required produces an end-of-support finding. Equivalent range rewrites do not. Removing a peer requirement entirely relaxes consumer constraints. Preview support is compared too. Optional-peer absence testing is deferred; making an existing optional peer required is still detected as an installation-contract change.
+
+The shared `release` model accepts intentional support changes when the integration has a breaking version delta against its previous release. Reports use support status `breaking-release` and include `{ previousVersion, version, delta, breaking }` in `support.release`. Missing intent or a compatible delta leaves support changes unapproved. Resolver or policy exceptions fail setup. Public checks use the same release model; compatibility failures against still-declared peers always remain failures.
+
+## Installation, isolation, and recovery
+
+`prepareCommand` runs in each representative and must install from its frozen lock file. For another package manager, set `lockfile` and this command accordingly, keeping the environment independent of workspace package substitution. Breakage requires unchanged manifest/lock bytes and checks direct installed identities. An existing installation that changes peer versions during frozen preparation is reported as stale; rerun after reviewing the updated installation. The configured package manager establishes lock consistency; Breakage does not reimplement its lock format.
+
+Installed peers may come from `dependencies`, `devDependencies`, or `optionalDependencies`. An optional dependency overrides a required dependency of the same name. When present, it supplies peer evidence and runs its selected relationship suite normally. When genuinely absent, it supplies no evidence: a required peer still fails, while an optional peer may be omitted. Broken installed links and missing manifests remain errors. Optional-peer absence coverage is not required.
+
+A representative must not declare conflicting development and runtime requirements for the same dependency. For example, `dependencies.host: "1.0.0"` together with `devDependencies.host: "2.0.0"` is a setup error before installation. Remove the duplicate or give both declarations the same specifier. The same rule applies when the runtime declaration is optional.
+
+Runtime dependencies must resolve through the representative or its test installation. Explicit package-store links remain supported, including dependencies alongside the linked package in its nearest `node_modules` namespace. Finding a dependency only in an unrelated ancestor installation is a setup error, even if it is optional and would make the assertions pass. Breakage checks this before and after execution.
+
+The ignored `test/` directory is also the ownership lock. An existing directory is rejected without deleting it. Independent environments execute concurrently, while two runs cannot own the same environment. On normal completion or failure, Breakage removes only the stage it created. After a killed process, confirm its commands have stopped, inspect the remaining stage, and remove it before retrying.
+
+The default candidate install runs npm with `--prefix . --workspaces=false --ignore-scripts --legacy-peer-deps --package-lock=false --no-audit --no-fund`. It installs the archive's runtime dependencies without automatically installing peers. `installCommand` may replace this with a repository-specific equivalent operating on the generated consumer manifest. It must leave the candidates physically inside the stage. A native dependency that needs a lifecycle build requires an intentional command override.
+
+Tests, candidate packages, and their runtime dependencies must resolve the same physical configured peer instances. Breakage rejects shadow copies and workspace-source peer links, including links to configured local packages. pnpm-style store links into dependency installations are permitted. These checks establish installed package identity, not registry integrity attestation. Package-manager layout, runner aliases, and module loaders remain relevant: preserve consumer resolution and test your actual runner setup.
+
+## CI and caching
+
+Keep the existing public check as `test:breakage` and add the npm check to that release gate, or use `test:breakage:npm` for a separate required job. Preparation must build and pack every participating candidate. A developer-owned matrix can run one configured representative per job, plus an audit job:
+
+```yaml
+jobs:
+  npm-audit:
+    steps:
+      # Checkout, install tools/dependencies, and prepare release evidence first.
+      - run: breakage npm check --coverage-only
+  npm-contracts:
+    strategy:
+      fail-fast: false
+      matrix:
+        representative: [peer-environments/core-1, peer-environments/core-2]
+    steps:
+      # Checkout, install tools/dependencies, and build/pack candidates first.
+      - run: breakage npm test --representative "${{ matrix.representative }}"
+```
+
+This is a job excerpt: add your runner, checkout, setup, and working directory. Require the audit, all matrix jobs, and the public check before release. Updating the authored representative list requires updating the required matrix. Breakage neither generates workflows nor aggregates cross-job receipts.
+
+Start uncached. A correct cache key includes candidate/peer archives, suite files, representative manifests and lock files, observed installation identities, configuration and imported helpers, baseline, release-plan inputs, and command/environment/toolchain inputs. Unknown dynamic input means the check stays uncached. There is no new npm prelude or mandatory execution plan.
+
+Programmatic consumers can import `npmCheck`, `npmTest`, `formatNpmReport`, and their exported types from `breakage`. Both check functions return a structured `NpmReport` with `exitCode`, coverage, support findings, and independent representative/suite results; `mode` distinguishes audit from execution.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakage",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "description": "Run yesterday’s tests against tomorrow’s release.",
   "homepage": "https://github.com/jeremybanka/breakage#readme",
   "bugs": "https://github.com/jeremybanka/breakage/issues",
@@ -15,38 +15,78 @@
     "email": "hello@jeremybanka.com"
   },
   "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/breakage.d.ts",
+      "default": "./dist/breakage.js"
+    },
+    "./changesets": {
+      "types": "./dist/changesets.d.ts",
+      "default": "./dist/changesets.js"
+    },
+    "./*": "./*"
+  },
   "main": "dist/breakage.js",
   "types": "dist/breakage.d.ts",
   "bin": {
     "breakage": "./dist/breakage.x.js"
   },
   "files": [
+    "npm.md",
     "dist",
     "src"
   ],
   "dependencies": {
-    "arktype": "2.2.8",
-    "comline": "0.9.0",
+    "arktype": "2.2.9",
+    "comline": "0.9.3",
     "minimatch": "10.2.6",
+    "semver": "7.8.5",
     "simple-git": "4.0.2",
     "takua": "0.2.3"
   },
   "devDependencies": {
-    "@types/bun": "npm:bun-types@1.4.3",
+    "@changesets/assemble-release-plan": "7.0.0",
+    "@changesets/config": "4.0.1",
+    "@changesets/pre": "3.0.0",
+    "@changesets/read": "1.0.1",
+    "@manypkg/get-packages": "3.1.0",
+    "@types/bun": "npm:bun-types@1.4.4",
+    "@types/semver": "7.8.0",
     "typescript": "7.0.2"
   },
+  "peerDependencies": {
+    "@changesets/assemble-release-plan": "^7.0.0",
+    "@changesets/config": "^4.0.1",
+    "@changesets/pre": "^3.0.0",
+    "@changesets/read": "^1.0.1",
+    "@manypkg/get-packages": "^3.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@changesets/assemble-release-plan": {
+      "optional": true
+    },
+    "@changesets/config": {
+      "optional": true
+    },
+    "@changesets/pre": {
+      "optional": true
+    },
+    "@changesets/read": {
+      "optional": true
+    },
+    "@manypkg/get-packages": {
+      "optional": true
+    }
+  },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "vp pack && pnpm run schema",
-    "check": "pnpm run check:tsc",
-    "check:tsc": "tsc --noEmit",
+    "build": "vp pack",
+    "check": "vp run -w check",
     "postversion": "dprint fmt package.json",
-    "schema": "bun src/breakage.x.ts --outdir=dist -- schema",
-    "pretest": "pnpm run build",
-    "test": "BREAKAGE_CLI_ENTRYPOINT=./src/breakage.x.ts bun test -- ./__tests__ ./tests/public",
+    "test": "vp run test:run",
     "test:public": "BREAKAGE_CLI_ENTRYPOINT=./src/breakage.x.ts bun test -- ./tests/public",
-    "test:watch": "BREAKAGE_CLI_ENTRYPOINT=./src/breakage.x.ts bun test --watch -- ./__tests__ ./tests/public"
+    "test:watch": "vp run test:run --watch"
   }
 }

package/src/breakage.ts

@@ -1,4 +1,3 @@
-import { exec } from "node:child_process"
 import path from "node:path"
 
 import { minimatch } from "minimatch"
@@ -6,26 +5,69 @@ import { simpleGit } from "simple-git"
 import type { Chronicle } from "takua"
 import logger from "takua"
 
+import { command, errorMessage } from "./task.ts"
+import { readManifest, parseManifest } from "./npm/manifest.ts"
+import {
+	resolveReleaseDelta,
+	versionDelta,
+	validateRelease,
+	rejectCertificationOptions,
+} from "./release.ts"
+import type { ReleaseConfig, VersionDelta } from "./release.ts"
 import { readBaseline } from "./baseline.ts"
 import { withDirectoryLock } from "./directory-lock.ts"
 import { latestReleaseTag as selectLatestReleaseTag } from "./release-tag.ts"
 import { withTestFileState } from "./test-file-state.ts"
 
+export { defineConfig, loadConfig } from "./config.ts"
+export type { BreakageConfig } from "./config.ts"
+export {
+	semverPolicy,
+	versionTransition,
+	versionDelta,
+	resolveReleaseDelta,
+} from "./release.ts"
+export type {
+	ReleaseConfig,
+	ReleasePolicy,
+	ReleasePolicyFunction,
+	SemverPolicyOptions,
+	VersionTransition,
+	ReleaseDeltaResolver,
+	ReleaseDeltaContext,
+	VersionDelta,
+} from "./release.ts"
+export type { CommandResult } from "./task.ts"
+
 export type { BreakageBaseline, BreakagePreludeOptions } from "./baseline.ts"
 export { breakagePrelude } from "./baseline.ts"
+export { formatNpmReport, npmCheck, npmTest } from "./npm/check.ts"
+export type {
+	NpmConfig,
+	NpmPeerEvidence,
+	NpmReport,
+	NpmRepresentativeResult,
+	NpmSuite,
+	NpmSuiteResult,
+	NpmTestSelection,
+	SupportChange,
+} from "./npm/types.ts"
 
 export type BreakageOptions = {
 	tagPattern?: string | undefined
 	baselineFile?: string | undefined
 	testPattern: string
-	testCommand: string
-	certifyCommand: string
+	testCommand?: string
+	/** Shell command. Do not combine with testCommand. */
+	test?: string
+	release?: ReleaseConfig
 	baseDirname?: string
 	verbose?: boolean | undefined
 }
 
 export type BreakageOutcome =
 	| { gitWasClean: false }
+	| { gitWasClean: true; setupError: string }
 	| {
 			gitWasClean: true
 			lastReleaseFound: false
@@ -43,6 +85,7 @@ export type BreakageOutcome =
 			testsWereFound: true
 			testsFound: string[]
 			breakingChangesFound: false
+			release?: VersionDelta
 	  }
 	| {
 			gitWasClean: true
@@ -52,20 +95,35 @@ export type BreakageOutcome =
 			testsFound: string[]
 			breakingChangesFound: true
 			testResult: string
-			breakingChangesCertified: boolean
-			certificationStdout: string
-			certificationStderr: string
+			release?: VersionDelta
 	  }
 
-export async function breakage({
-	tagPattern,
-	baselineFile,
-	testPattern,
-	testCommand,
-	certifyCommand,
-	baseDirname = process.cwd(),
-	verbose = false,
-}: BreakageOptions): Promise<BreakageOutcome & { summary: string }> {
+export async function breakage(
+	options: BreakageOptions,
+): Promise<BreakageOutcome & { summary: string }> {
+	rejectCertificationOptions(options)
+	const {
+		tagPattern,
+		baselineFile,
+		testPattern,
+		testCommand,
+		test,
+		release,
+		baseDirname = process.cwd(),
+		verbose = false,
+	} = options
+	if (!testPattern || (!test && !testCommand))
+		throw new Error(
+			`required arguments were not provided: testPattern and test or testCommand.`,
+		)
+	if (test !== undefined && testCommand !== undefined)
+		throw new Error(`Choose test or testCommand, not both.`)
+	if (
+		typeof (test ?? testCommand) !== `string` ||
+		!(test ?? testCommand)!.trim()
+	)
+		throw new Error(`test must be a nonempty shell command string.`)
+	if (release !== undefined) validateRelease(release)
 	let mark: Chronicle[`mark`] | undefined
 	let logMarks: Chronicle[`logMarks`] | undefined
 	if (verbose) {
@@ -167,6 +225,34 @@ export async function breakage({
 	)
 	mark?.(`filtered to public test files`)
 
+	let releaseEvidence: VersionDelta | undefined
+	if (release) {
+		const current = await readManifest(path.join(baseDirname, `package.json`))
+		const prefix = await git.revparse([`--show-prefix`])
+		const previous = parseManifest(
+			JSON.parse(await git.show([`${releaseCommit}:${prefix}package.json`])),
+			`baseline`,
+		)
+		if (previous.name !== current.name)
+			throw new Error(`Release baseline belongs to another package.`)
+		const transition = await resolveReleaseDelta(release, {
+			packageName: current.name,
+			packageDirectory: path.resolve(baseDirname),
+			currentVersion: current.version,
+			baseline: {
+				version: previous.version,
+				ref: latestReleaseTag,
+				commit: releaseCommit,
+			},
+		})
+		if (transition !== undefined)
+			releaseEvidence = versionDelta(
+				transition.previousVersion,
+				transition.version,
+				release.policy,
+			)
+	}
+
 	const prepared = await withTestFileState(git, baseDirname, async (state) => {
 		if (!(await state.isClean())) {
 			return {
@@ -192,61 +278,41 @@ export async function breakage({
 	const { restore } = prepared
 
 	try {
-		const noBreakingChangesDetected = await new Promise<
-			BreakageOutcome & { summary: string }
-		>((resolve, reject) => {
-			const result = exec(
-				testCommand,
-				{ cwd: baseDirname },
-				(_, __, stderr) => {
-					if (result.exitCode === 0) {
-						resolve({
-							summary: `No breaking changes were detected.`,
-							gitWasClean: true,
-							lastReleaseFound: true,
-							lastReleaseTag: latestReleaseTag,
-							testsWereFound: true,
-							testsFound: productionTestFiles,
-							breakingChangesFound: false,
-						})
-					} else {
-						reject(stderr)
-					}
-				},
-			)
-		})
-		mark?.(`passed tests`)
-		return noBreakingChangesDetected
-	} catch (thrown) {
-		mark?.(`failed tests`)
-		const breakingChangesCertified = await new Promise<
-			BreakageOutcome & { summary: string }
-		>((resolve) => {
-			const result = exec(
-				certifyCommand,
-				{ cwd: baseDirname },
-				(_, stdout, stderr) => {
-					const wereCertified = result.exitCode === 0
-					mark?.(`${wereCertified ? `passed` : `failed`} certification`)
-					resolve({
-						summary: wereCertified
-							? `Breaking changes were found and certified.`
-							: `Breaking changes were found, but not certified.`,
-						gitWasClean: true,
-						lastReleaseFound: true,
-						lastReleaseTag: latestReleaseTag,
-						testsWereFound: true,
-						testsFound: productionTestFiles,
-						breakingChangesFound: true,
-						testResult: thrown as string,
-						breakingChangesCertified: wereCertified,
-						certificationStdout: stdout,
-						certificationStderr: stderr,
-					})
-				},
-			)
-		})
-		return breakingChangesCertified
+		const result = await command(test ?? testCommand!, baseDirname)
+		if (result.code > 1)
+			return {
+				gitWasClean: true,
+				setupError: result.output,
+				summary: `Public test setup failed (${result.code}).`,
+			}
+		const common = {
+			gitWasClean: true as const,
+			lastReleaseFound: true as const,
+			lastReleaseTag: latestReleaseTag,
+			testsWereFound: true as const,
+			testsFound: productionTestFiles,
+			...(releaseEvidence ? { release: releaseEvidence } : {}),
+		}
+		if (result.code === 0)
+			return {
+				...common,
+				breakingChangesFound: false,
+				summary: `No breaking changes were detected.`,
+			}
+		return {
+			...common,
+			breakingChangesFound: true,
+			testResult: result.output,
+			summary: releaseEvidence?.breaking
+				? `Breaking changes are covered by release ${releaseEvidence.previousVersion} → ${releaseEvidence.version}.`
+				: `Breaking changes require a breaking release.`,
+		}
+	} catch (error) {
+		return {
+			gitWasClean: true,
+			setupError: errorMessage(error),
+			summary: `Public test setup failed: ${errorMessage(error)}`,
+		}
 	} finally {
 		await restore()
 		mark?.(`restored original public tests`)