breakage 0.8.5 → 0.9.0

package/npm.md

@@ -2,7 +2,7 @@
 
 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 certifies.
+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.
 
@@ -30,7 +30,7 @@ In the integration package, create complete environments for the peer formulatio
 }
 ```
 
-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 certified intended versions supply the exact identities, and any accompanying dependency pins must match those versions.
+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.
 
@@ -89,7 +89,7 @@ export default {
 }
 ```
 
-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 certified 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.
+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.
 
@@ -103,9 +103,9 @@ 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 uncertified support failures, and 2 for setup or coverage errors.
+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 certified 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.
+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
 
@@ -122,54 +122,76 @@ Create a separate representative that explicitly names candidate peers. Leave an
 }
 ```
 
-Add a typed `releaseIntent` callback to the npm configuration. This example reads a repository-owned JSON release plan; adapt it to Changesets or your release process. The function receives `packageName`, `packageDirectory`, and `currentVersion`, and may return synchronously or asynchronously:
+Set `release.resolveDelta` to a synchronous/asynchronous resolver receiving `packageName`, `packageDirectory`, and `currentVersion`. For Changesets, use the optional helper:
 
 ```ts
-import { readFile } from "node:fs/promises"
-import type { NpmConfig } from "breakage"
+import { changesetsReleaseDelta } from "breakage/changesets"
+import { semverPolicy } from "breakage"
 
-const releaseIntent: NonNullable<NpmConfig["releaseIntent"]> = async ({
-	packageName,
-}) => {
-	const plan = JSON.parse(
-		await readFile(new URL("./release-plan.json", import.meta.url), "utf8"),
-	)
-	const version = plan[packageName]
-	return version ? { status: "release", version } : { status: "none" }
+const release = {
+	resolveDelta: changesetsReleaseDelta(),
+	policy: semverPolicy({ beforeV1: "minor" }),
 }
 ```
 
-Missing intent blocks that candidate environment. Inspection errors and invalid evidence are setup errors, not absent intent. Intended versions must be exact and at least the current workspace version. 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.
+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 certified intended version.
+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 certified 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. Hook errors and invalid evidence fail setup. Hooks are evaluated once per package per invocation, and must return that package's own release intent.
+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 certification for dropping old support still apply. Your release hook supplies the intended version before a versioning PR is merged; Breakage does not infer it from an open PR.
+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 certified intended version; a peer on the integration itself uses the integration's current archive version.
+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.
 
-## 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.
+## Shared release configuration
 
-To accept intentional support changes, provide both release intent for the integration and an explicit breaking-release policy:
+Use `defineConfig` to share a release resolver and policy with public checks:
 
 ```ts
-const certifyBreaking: NonNullable<NpmConfig["certifyBreaking"]> = ({
-	previousVersion,
-	release,
-}) =>
-	previousVersion.startsWith("0.")
-		? release.delta === "minor" || release.delta === "major"
-		: release.delta === "major"
+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@" },
+	},
+})
 ```
 
-This callback also receives `changes`, with each peer's previous and current declaration. It must return a boolean; throwing fails setup. Public breakage is still handled by the ordinary public command's certification. Compatibility failures against still-declared peers cannot be certified away.
+`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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakage",
-  "version": "0.8.5",
+  "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,6 +15,17 @@
     "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": {
@@ -26,26 +37,54 @@
     "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 && vp run schema",
+    "build": "vp pack",
     "check": "vp run -w check",
     "postversion": "dprint fmt package.json",
-    "schema": "bun src/breakage.x.ts --outdir=dist -- schema",
     "test": "vp run test:run",
     "test:public": "BREAKAGE_CLI_ENTRYPOINT=./src/breakage.x.ts bun test -- ./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,11 +5,40 @@ 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"
@@ -22,9 +50,6 @@ export type {
 	NpmSuite,
 	NpmSuiteResult,
 	NpmTestSelection,
-	ReleaseContext,
-	ReleaseEvidence,
-	ReleaseIntent,
 	SupportChange,
 } from "./npm/types.ts"
 
@@ -32,14 +57,17 @@ 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
@@ -57,6 +85,7 @@ export type BreakageOutcome =
 			testsWereFound: true
 			testsFound: string[]
 			breakingChangesFound: false
+			release?: VersionDelta
 	  }
 	| {
 			gitWasClean: true
@@ -66,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) {
@@ -181,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 {
@@ -206,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`)