breakage 0.8.5 → 0.9.0

package/dist/{breakage-B7dJsgcu.js → breakage-DIY49fzP.js}

@@ -1,15 +1,125 @@
+import { a as validateRelease, n as releaseSchema, o as versionDelta, r as resolveReleaseDelta, t as rejectCertificationOptions } from "./release-BsdIDT4g.js";
 import { createRequire } from "node:module";
-import { exec, spawn } from "node:child_process";
 import path from "node:path";
 import { minimatch } from "minimatch";
 import { simpleGit } from "simple-git";
 import logger from "takua";
-import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
 import * as fs from "node:fs/promises";
 import { chmod, copyFile, lstat, mkdir, readFile, readdir, realpath, rename, rm, rmdir, writeFile } from "node:fs/promises";
-import { setTimeout } from "node:timers/promises";
 import semver from "semver";
-//#region src/directory-lock.ts
+import { type } from "arktype";
+import { randomUUID } from "node:crypto";
+import { setTimeout } from "node:timers/promises";
+import { existsSync } from "node:fs";
+import { cli, options } from "comline";
+// src/task.ts
+/** Capture output per environment so parallel runs cannot interleave their reports. */
+async function command(commandLine, cwd) {
+	if (typeof commandLine !== `string` || !commandLine.trim()) throw new Error(`Commands must be nonempty shell strings.`);
+	return await new Promise((resolve, reject) => {
+		const child = spawn(commandLine, {
+			cwd,
+			shell: true,
+			env: {
+				...process.env,
+				NODE_PATH: ``,
+				PATH: [
+					path.join(cwd, `node_modules/.bin`),
+					path.join(cwd, `../node_modules/.bin`),
+					process.env.PATH
+				].join(path.delimiter)
+			},
+			stdio: [
+				`ignore`,
+				`pipe`,
+				`pipe`
+			]
+		});
+		let output = ``;
+		const collect = (chunk) => {
+			output = (output + chunk.toString()).slice(-1e6);
+		};
+		child.stdout.on(`data`, collect);
+		child.stderr.on(`data`, collect);
+		child.on(`error`, reject);
+		child.on(`close`, (code, signal) => resolve({
+			code: signal ? 2 : code ?? 2,
+			output
+		}));
+	});
+}
+async function prepare(commandLine, cwd) {
+	const result = await command(commandLine, cwd);
+	if (result.code !== 0) throw new Error(`Command failed (${result.code}) in ${cwd}: ${commandLine}\n${result.output}`);
+}
+function errorMessage(error) {
+	return error instanceof Error ? `${error.message}${error.cause ? `\n${errorMessage(error.cause)}` : ``}` : String(error);
+}
+// src/npm/manifest.ts
+function record(value) {
+	return typeof value === `object` && value !== null && !Array.isArray(value);
+}
+function packageName(value) {
+	return /^(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/.test(value);
+}
+function parseManifest(value, label) {
+	if (!record(value) || typeof value.name !== `string` || !packageName(value.name) || typeof value.version !== `string` || !semver.valid(value.version)) throw new Error(`Invalid package identity in ${label}.`);
+	if (value.peerDependenciesMeta !== void 0 && (!record(value.peerDependenciesMeta) || Object.values(value.peerDependenciesMeta).some((entry) => !record(entry) || entry.optional !== void 0 && typeof entry.optional !== `boolean`))) throw new Error(`Invalid peerDependenciesMeta in ${label}.`);
+	for (const field of [
+		`dependencies`,
+		`optionalDependencies`,
+		`devDependencies`,
+		`peerDependencies`
+	]) {
+		const entries = value[field];
+		if (entries !== void 0 && (!record(entries) || Object.entries(entries).some(([name, spec]) => !packageName(name) || typeof spec !== `string`))) throw new Error(`Invalid ${field} in ${label}.`);
+	}
+	if (value.breakage !== void 0 && (!record(value.breakage) || value.breakage.candidates !== void 0 && (!Array.isArray(value.breakage.candidates) || value.breakage.candidates.some((name) => typeof name !== `string` || !packageName(name))))) throw new Error(`Invalid candidate peers in ${label}.`);
+	return value;
+}
+async function readManifest(filename) {
+	return parseManifest(JSON.parse(await readFile(filename, `utf8`)), filename);
+}
+/** Current support is authored explicitly; only historical shorthand is resolved. */
+async function normalizeWorkspacePeers(manifest, versionAtBaseline) {
+	if (!manifest.peerDependencies) return manifest;
+	const entries = await Promise.all(Object.entries(manifest.peerDependencies).map(async ([peer, range]) => {
+		if (!range.startsWith(`workspace:`)) return [peer, range];
+		const requested = range.slice(`workspace:`.length);
+		if ([
+			``,
+			`*`,
+			`^`,
+			`~`
+		].includes(requested)) {
+			if (!versionAtBaseline) throw new Error(`Moving workspace peer range ${peer}: ${range} in ${manifest.name}. Declare explicit support eras, for example ^1.0.0 || ^2.0.0, so local version changes cannot change the support promise.`);
+			const version = await versionAtBaseline(peer);
+			if (!semver.valid(version)) throw new Error(`Invalid historical workspace version for ${peer}: ${version}.`);
+			return [peer, `${requested === `^` || requested === `~` ? requested : ``}${version}`];
+		}
+		try {
+			eras(requested);
+		} catch {
+			throw new Error(`Unsupported workspace peer range for ${peer}: ${range}.`);
+		}
+		return [peer, requested];
+	}));
+	return {
+		...manifest,
+		peerDependencies: Object.fromEntries(entries)
+	};
+}
+function eras(range) {
+	const parts = range.split(`||`).map((part) => part.trim());
+	if (parts.some((part) => !part || semver.validRange(part) === null)) throw new Error(`Invalid peer range: ${range}.`);
+	return parts;
+}
+/** Previews only represent an explicitly enrolled exact preview. */
+function matches(version, range) {
+	return eras(range).some((era) => semver.prerelease(version) ? semver.valid(era.replace(/^=\s*/, ``)) === semver.valid(version) : semver.satisfies(version, era));
+}
+// src/directory-lock.ts
 async function withDirectoryLock(lock, action, waitForCleanup = false) {
 	const deadline = Date.now() + 6e4;
 	for (;;) try {
@@ -26,8 +136,7 @@ async function withDirectoryLock(lock, action, waitForCleanup = false) {
 		await rmdir(lock);
 	}
 }
-//#endregion
-//#region src/release-tag.ts
+// src/release-tag.ts
 function compareInteger(a, b) {
 	return a.length - b.length || (a > b ? 1 : a < b ? -1 : 0);
 }
@@ -69,8 +178,7 @@ function latestReleaseTag(remoteTags, tagPattern) {
 	}
 	return latest?.ref;
 }
-//#endregion
-//#region src/baseline.ts
+// src/baseline.ts
 const objectId = /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/;
 function isBaseline(value) {
 	if (typeof value !== `object` || value === null) return false;
@@ -149,8 +257,7 @@ async function readBaseline(git, filename, { tagPattern }) {
 		throw new Error(`Missing, invalid, or unusable baseline ${filename}. Run breakage prelude again.`, { cause });
 	}
 }
-//#endregion
-//#region src/test-file-state.ts
+// src/test-file-state.ts
 function isActiveCheck(value) {
 	if (typeof value !== `object` || value === null) return false;
 	const record = value;
@@ -293,127 +400,48 @@ async function withTestFileState(git, baseDirname, action) {
 		});
 	});
 }
-//#endregion
-//#region src/npm/command.ts
-/** Capture output per environment so parallel runs cannot interleave their reports. */
-async function command(commandLine, cwd) {
-	return await new Promise((resolve, reject) => {
-		const child = spawn(commandLine, {
-			cwd,
-			shell: true,
-			env: {
-				...process.env,
-				NODE_PATH: ``,
-				PATH: [
-					path.join(cwd, `node_modules/.bin`),
-					path.join(cwd, `../node_modules/.bin`),
-					process.env.PATH
-				].join(path.delimiter)
-			},
-			stdio: [
-				`ignore`,
-				`pipe`,
-				`pipe`
-			]
-		});
-		let output = ``;
-		const collect = (chunk) => {
-			output = (output + chunk.toString()).slice(-1e6);
-		};
-		child.stdout.on(`data`, collect);
-		child.stderr.on(`data`, collect);
-		child.on(`error`, reject);
-		child.on(`close`, (code, signal) => resolve({
-			code: signal ? 2 : code ?? 2,
-			output
-		}));
-	});
-}
-async function prepare(commandLine, cwd) {
-	const result = await command(commandLine, cwd);
-	if (result.code !== 0) throw new Error(`Command failed (${result.code}) in ${cwd}: ${commandLine}\n${result.output}`);
-}
-function errorMessage(error) {
-	return error instanceof Error ? `${error.message}${error.cause ? `\n${errorMessage(error.cause)}` : ``}` : String(error);
-}
-//#endregion
-//#region src/npm/manifest.ts
-function record(value) {
-	return typeof value === `object` && value !== null && !Array.isArray(value);
-}
-function packageName(value) {
-	return /^(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/.test(value);
-}
-function parseManifest(value, label) {
-	if (!record(value) || typeof value.name !== `string` || !packageName(value.name) || typeof value.version !== `string` || !semver.valid(value.version)) throw new Error(`Invalid package identity in ${label}.`);
-	if (value.peerDependenciesMeta !== void 0 && (!record(value.peerDependenciesMeta) || Object.values(value.peerDependenciesMeta).some((entry) => !record(entry) || entry.optional !== void 0 && typeof entry.optional !== `boolean`))) throw new Error(`Invalid peerDependenciesMeta in ${label}.`);
-	for (const field of [
-		`dependencies`,
-		`optionalDependencies`,
-		`devDependencies`,
-		`peerDependencies`
-	]) {
-		const entries = value[field];
-		if (entries !== void 0 && (!record(entries) || Object.entries(entries).some(([name, spec]) => !packageName(name) || typeof spec !== `string`))) throw new Error(`Invalid ${field} in ${label}.`);
-	}
-	if (value.breakage !== void 0 && (!record(value.breakage) || value.breakage.candidates !== void 0 && (!Array.isArray(value.breakage.candidates) || value.breakage.candidates.some((name) => typeof name !== `string` || !packageName(name))))) throw new Error(`Invalid candidate peers in ${label}.`);
-	return value;
-}
-async function readManifest(filename) {
-	return parseManifest(JSON.parse(await readFile(filename, `utf8`)), filename);
-}
-/** Current support is authored explicitly; only historical shorthand is resolved. */
-async function normalizeWorkspacePeers(manifest, versionAtBaseline) {
-	if (!manifest.peerDependencies) return manifest;
-	const entries = await Promise.all(Object.entries(manifest.peerDependencies).map(async ([peer, range]) => {
-		if (!range.startsWith(`workspace:`)) return [peer, range];
-		const requested = range.slice(`workspace:`.length);
-		if ([
-			``,
-			`*`,
-			`^`,
-			`~`
-		].includes(requested)) {
-			if (!versionAtBaseline) throw new Error(`Moving workspace peer range ${peer}: ${range} in ${manifest.name}. Declare explicit support eras, for example ^1.0.0 || ^2.0.0, so local version changes cannot change the support promise.`);
-			const version = await versionAtBaseline(peer);
-			if (!semver.valid(version)) throw new Error(`Invalid historical workspace version for ${peer}: ${version}.`);
-			return [peer, `${requested === `^` || requested === `~` ? requested : ``}${version}`];
-		}
-		try {
-			eras(requested);
-		} catch {
-			throw new Error(`Unsupported workspace peer range for ${peer}: ${range}.`);
-		}
-		return [peer, requested];
-	}));
-	return {
-		...manifest,
-		peerDependencies: Object.fromEntries(entries)
-	};
-}
-function eras(range) {
-	const parts = range.split(`||`).map((part) => part.trim());
-	if (parts.some((part) => !part || semver.validRange(part) === null)) throw new Error(`Invalid peer range: ${range}.`);
-	return parts;
-}
-/** Previews only represent an explicitly enrolled exact preview. */
-function matches(version, range) {
-	return eras(range).some((era) => semver.prerelease(version) ? semver.valid(era.replace(/^=\s*/, ``)) === semver.valid(version) : semver.satisfies(version, era));
-}
-//#endregion
-//#region src/npm/config.ts
+// src/npm/config.ts
+const npmSuiteSchema = type({
+	"+": `reject`,
+	files: `string[]`,
+	command: `string`
+});
+const npmConfigSchema = type({
+	"+": `reject`,
+	"release?": releaseSchema,
+	"packageDirectory?": `string`,
+	artifact: `string`,
+	representatives: `string | string[]`,
+	lockfile: `string`,
+	prepareCommand: `string`,
+	"installCommand?": `string`,
+	suites: { "[string]": npmSuiteSchema },
+	"localPeers?": { "[string]": {
+		"+": `reject`,
+		directory: `string`,
+		artifact: `string`
+	} },
+	baseline: type({
+		"+": `reject`,
+		firstRelease: `true`
+	}).or({
+		"+": `reject`,
+		"tagPattern?": `string`,
+		"baselineFile?": `string`
+	})
+});
 function nonempty(value) {
 	return typeof value === `string` && value.trim().length > 0;
 }
 function validateConfig(value) {
 	if (!record(value)) throw new Error(`Configuration must have an npm object.`);
-	for (const key of [
-		`artifact`,
-		`lockfile`,
-		`prepareCommand`
-	]) if (!nonempty(value[key])) throw new Error(`npm.${key} must be a nonempty string.`);
+	rejectCertificationOptions(value);
+	npmConfigSchema.assert(value);
+	for (const key of [`artifact`, `lockfile`]) if (!nonempty(value[key])) throw new Error(`npm.${key} must be a nonempty string.`);
 	if (path.isAbsolute(value.lockfile) || value.lockfile.split(/[\\/]/).includes(`..`)) throw new Error(`npm.lockfile must stay inside each representative.`);
-	for (const key of [`packageDirectory`, `installCommand`]) if (value[key] !== void 0 && !nonempty(value[key])) throw new Error(`Invalid npm.${key}.`);
+	if (!nonempty(value.prepareCommand)) throw new Error(`npm.prepareCommand must be a nonempty shell command string.`);
+	if (value.installCommand !== void 0 && !nonempty(value.installCommand)) throw new Error(`Invalid npm.installCommand.`);
+	for (const key of [`packageDirectory`]) if (value[key] !== void 0 && !nonempty(value[key])) throw new Error(`Invalid npm.${key}.`);
 	const globs = typeof value.representatives === `string` ? [value.representatives] : value.representatives;
 	if (!Array.isArray(globs) || !globs.length || globs.some((glob) => !nonempty(glob))) throw new Error(`npm.representatives must contain directory globs.`);
 	if (!record(value.suites) || !Object.keys(value.suites).length) throw new Error(`Configure at least one npm peer suite.`);
@@ -423,23 +451,96 @@ function validateConfig(value) {
 		if (!record(value.localPeers)) throw new Error(`Invalid npm.localPeers.`);
 		for (const [peer, local] of Object.entries(value.localPeers)) if (!packageName(peer) || !record(local) || !nonempty(local.directory) || !nonempty(local.artifact)) throw new Error(`Invalid local peer ${peer}.`);
 	}
-	for (const hook of [`releaseIntent`, `certifyBreaking`]) if (value[hook] !== void 0 && typeof value[hook] !== `function`) throw new Error(`npm.${hook} must be a function.`);
 }
 function validatePeerRanges(peers) {
 	for (const range of Object.values(peers)) eras(range);
 }
-//#endregion
-//#region src/npm/release.ts
-async function intent(config, context) {
-	if (!config.releaseIntent) return { status: `none` };
-	const result = await config.releaseIntent(context);
-	if (record(result) && result.status === `none`) return { status: `none` };
-	if (!record(result) || result.status !== `release` || typeof result.version !== `string` || !semver.valid(result.version) || semver.lt(result.version, context.currentVersion)) throw new Error(`Invalid release intent for ${context.packageName}; expected none or a current/newer exact version.`);
+// src/config.ts
+const configFields = {
+	tagPattern: type(`string`),
+	baselineFile: type(`string`),
+	testPattern: type(`string`),
+	testCommand: type(`string`),
+	test: type(`string`),
+	baseDirname: type(`string`),
+	verbose: type(`boolean`),
+	out: type(`string`)
+};
+const configSchema = type({
+	"+": `reject`,
+	"tagPattern?": configFields.tagPattern.or(`undefined`),
+	"baselineFile?": configFields.baselineFile.or(`undefined`),
+	"testPattern?": configFields.testPattern,
+	"testCommand?": configFields.testCommand,
+	"test?": configFields.test,
+	"baseDirname?": configFields.baseDirname,
+	"verbose?": configFields.verbose.or(`undefined`),
+	"out?": configFields.out,
+	"release?": releaseSchema,
+	"npm?": npmConfigSchema
+});
+/** The complete config, with no fields exposed to argv by this loader. */
+const configOptions = options(`Breakage configuration`, configSchema, {
+	tagPattern: { configOnly: true },
+	baselineFile: { configOnly: true },
+	testPattern: { configOnly: true },
+	testCommand: { configOnly: true },
+	test: { configOnly: true },
+	baseDirname: { configOnly: true },
+	verbose: { configOnly: true },
+	out: { configOnly: true },
+	release: { configOnly: true },
+	npm: { configOnly: true }
+});
+/** Share the root release model with npm checks unless they supply their own. */
+function defineConfig(config) {
+	if (config && typeof config === `object`) {
+		rejectCertificationOptions(config);
+		if (config.npm) rejectCertificationOptions(config.npm);
+		if (config.release !== void 0) validateRelease(config.release);
+		if (config.npm?.release !== void 0) validateRelease(config.npm.release);
+	}
+	configSchema.assert(config);
 	return {
-		status: `release`,
-		version: result.version
+		...config,
+		...config.npm ? { npm: {
+			...config.npm,
+			...config.release && config.npm.release === void 0 ? { release: config.release } : {}
+		} } : {}
 	};
 }
+function defaultConfig(directory) {
+	const filename = path.join(directory, `breakage.config.ts`);
+	if (!existsSync(filename) && existsSync(path.join(directory, `breakage.config.json`))) throw new Error(`JSON configuration was removed. Migrate breakage.config.json to breakage.config.ts.`);
+	return filename;
+}
+/** Comline ignores absent discovered files; explicit paths must exist. */
+function configPath(filename, required = true) {
+	const absolute = path.resolve(filename);
+	if (path.extname(absolute) !== `.ts`) throw new Error(`Configuration must be a .ts module with a default export; JSON configuration was removed.`);
+	if (required && !existsSync(absolute)) throw new Error(`Configuration file does not exist: ${absolute}`);
+	return absolute;
+}
+/** Apply application semantics after Comline validates and merges configuration. */
+function resolveConfig(config, filename) {
+	return {
+		...defineConfig(config),
+		baseDirname: path.resolve(filename ? path.dirname(filename) : process.cwd(), config.baseDirname ?? `.`)
+	};
+}
+/** Use Comline's module loading and full-schema validation for programmatic and npm consumers. */
+async function loadConfig(filename) {
+	const absolute = configPath(filename);
+	return resolveConfig((await cli({
+		cliName: `breakage`,
+		routeOptions: { "": configOptions },
+		discoverConfigPath: () => absolute
+	}).async([process.execPath, `breakage`])).inputs.opts, absolute);
+}
+// src/npm/release.ts
+async function releaseVersion(config, context) {
+	return config.release ? (await resolveReleaseDelta(config.release, context))?.version : void 0;
+}
 /**
 * Compare the union, including adjacent alternatives. semver.subset compares each
 * conjunction to a single conjunction and cannot prove coverage by their union.
@@ -518,8 +619,7 @@ async function previousManifest(config, directory) {
 		return historical.version;
 	});
 }
-//#endregion
-//#region src/npm/environment.ts
+// src/npm/environment.ts
 function within(parent, child) {
 	const relative = path.relative(parent, child);
 	return relative === `` || !relative.startsWith(`..${path.sep}`) && relative !== `..` && !path.isAbsolute(relative);
@@ -624,13 +724,13 @@ async function maySelectEnvironment(config, base, directory, packageManifest, se
 		const packageDirectory = path.resolve(base, local.directory);
 		const current = await readManifest(path.join(packageDirectory, `package.json`));
 		if (current.name !== peer) throw new Error(`Local peer identity mismatch for ${peer}.`);
-		const release = await intent(config, {
+		const release = await releaseVersion(config, {
 			packageName: peer,
 			packageDirectory,
 			currentVersion: current.version
 		});
-		if (release.status === `none`) throw new Error(`Candidate ${peer} has no certified release intent.`);
-		return matches(release.version, range);
+		if (release === void 0) throw new Error(`Candidate ${peer} has no release version.`);
+		return matches(release, range);
 	}
 	const declared = declarations[peer];
 	return declared !== void 0 && matches(declared, range);
@@ -652,17 +752,17 @@ async function prepareEnvironment(config, base, directory, stage, packageManifes
 		const localManifest = await normalizeWorkspacePeers(await readManifest(path.join(localDirectory, `package.json`)));
 		if (localManifest.name !== peer) throw new Error(`Local peer identity mismatch for ${peer}.`);
 		validatePeerRanges(localManifest.peerDependencies ?? {});
-		const evidence = await intent(config, {
+		const evidence = await releaseVersion(config, {
 			packageName: peer,
 			packageDirectory: localDirectory,
 			currentVersion: localManifest.version
 		});
-		if (evidence.status === `none`) throw new Error(`Candidate ${peer} has no certified release intent.`);
+		if (evidence === void 0) throw new Error(`Candidate ${peer} has no release version.`);
 		candidates[peer] = {
 			directory: localDirectory,
 			artifact: path.resolve(base, local.artifact),
 			currentVersion: localManifest.version,
-			version: evidence.version,
+			version: evidence,
 			manifest: localManifest
 		};
 	}
@@ -866,8 +966,7 @@ async function verifyResolution(manifest, environment) {
 		} else pending.push(await resolvePackage(directory, dependency, installation));
 	}
 }
-//#endregion
-//#region src/npm/check.ts
+// src/npm/check.ts
 async function checkSupport(config, base, manifest) {
 	try {
 		const previous = await previousManifest(config, base);
@@ -882,29 +981,20 @@ async function checkSupport(config, base, manifest) {
 			previousVersion: previous.version,
 			changes
 		};
-		const evidence = await intent(config, {
+		const evidence = config.release ? await resolveReleaseDelta(config.release, {
 			packageName: manifest.name,
 			packageDirectory: base,
-			currentVersion: manifest.version
-		});
-		if (evidence.status === `none`) return {
+			currentVersion: manifest.version,
+			baseline: { version: previous.version }
+		}) : void 0;
+		if (evidence === void 0) return {
 			status: `end-of-support`,
 			previousVersion: previous.version,
 			changes
 		};
-		if (!semver.gt(evidence.version, previous.version)) throw new Error(`The intended release must be newer than baseline ${previous.version}.`);
-		const release = {
-			version: evidence.version,
-			delta: semver.diff(previous.version, evidence.version) ?? `none`
-		};
-		const certified = config.certifyBreaking ? await config.certifyBreaking({
-			previousVersion: previous.version,
-			release,
-			changes
-		}) : false;
-		if (typeof certified !== `boolean`) throw new Error(`certifyBreaking must return a boolean.`);
+		const release = versionDelta(evidence.previousVersion, evidence.version, config.release?.policy);
 		return {
-			status: certified ? `certified` : `end-of-support`,
+			status: release.breaking ? `breaking-release` : `end-of-support`,
 			previousVersion: previous.version,
 			changes,
 			release
@@ -925,14 +1015,14 @@ async function checkLocalReleases(config, base, manifest, representatives) {
 			const directory = path.resolve(base, local.directory);
 			const current = await readManifest(path.join(directory, `package.json`));
 			if (current.name !== peer) throw new Error(`Local peer identity mismatch for ${peer}.`);
-			const release = await intent(config, {
+			const release = await releaseVersion(config, {
 				packageName: peer,
 				packageDirectory: directory,
 				currentVersion: current.version
 			});
-			if (release.status === `none`) return [];
-			if (!matches(release.version, range)) return [`Declared support for ${peer}: ${range} does not include its planned local release ${release.version}. Update the peer range to include the intended version.`];
-			if (!representatives.some((result) => result.peers[peer]?.source === `candidate` && result.peers[peer]?.version === release.version && result.suites.some((suite) => suite.peer === peer))) return [`No coordinated representative covers planned local peer ${peer}@${release.version}. Enroll ${peer} with breakage.candidates and configure its relationship suite.`];
+			if (release === void 0) return [];
+			if (!matches(release, range)) return [`Declared support for ${peer}: ${range} does not include its planned local release ${release}. Update the peer range to include the intended version.`];
+			if (!representatives.some((result) => result.peers[peer]?.source === `candidate` && result.peers[peer]?.version === release && result.suites.some((suite) => suite.peer === peer))) return [`No coordinated representative covers planned local peer ${peer}@${release}. Enroll ${peer} with breakage.candidates and configure its relationship suite.`];
 			return [];
 		} catch (error) {
 			return [`Cannot inspect planned local release for ${peer}: ${errorMessage(error)}`];
@@ -1028,17 +1118,25 @@ async function run(config, baseDirectory, coverageOnly, selection) {
 			eras(selection.range);
 		}
 		const releases = /* @__PURE__ */ new Map();
-		const configuredHook = config.releaseIntent;
+		const resolveDelta = (context) => {
+			const key = JSON.stringify([
+				context.packageDirectory,
+				context.currentVersion,
+				context.baseline
+			]);
+			let pending = releases.get(key);
+			if (!pending) {
+				pending = resolveReleaseDelta(config.release, context);
+				releases.set(key, pending);
+			}
+			return pending;
+		};
 		const effective = {
 			...config,
-			releaseIntent: (context) => {
-				let pending = releases.get(context.packageDirectory);
-				if (!pending) {
-					pending = Promise.resolve().then(() => configuredHook ? configuredHook(context) : { status: `none` });
-					releases.set(context.packageDirectory, pending);
-				}
-				return pending;
-			}
+			...config.release ? { release: {
+				...config.release,
+				resolveDelta
+			} } : {}
 		};
 		const directories = await discover(config, base);
 		const [support, representatives] = await Promise.all([selection ? Promise.resolve(report.support) : checkSupport(effective, base, manifest), Promise.all(directories.map((directory) => runRepresentative(effective, base, manifest, directory, coverageOnly, selection)))]);
@@ -1090,9 +1188,14 @@ function formatNpmReport(report) {
 	if (report.mode === `coverage-only`) lines.push(`Coverage audit only; compatibility assertions were not executed.`);
 	return `${lines.join(`\n`)}\n`;
 }
-//#endregion
-//#region src/breakage.ts
-async function breakage({ tagPattern, baselineFile, testPattern, testCommand, certifyCommand, baseDirname = process.cwd(), verbose = false }) {
+// src/breakage.ts
+async function breakage(options) {
+	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 !== void 0 && testCommand !== void 0) 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 !== void 0) validateRelease(release);
 	let mark;
 	let logMarks;
 	if (verbose) {
@@ -1163,6 +1266,24 @@ async function breakage({ tagPattern, baselineFile, testPattern, testCommand, ce
 	mark?.(`listed all files checked into git`);
 	const productionTestFiles = productionFiles.filter((file) => minimatch(file, testPattern));
 	mark?.(`filtered to public test files`);
+	let releaseEvidence;
+	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$1,
+				commit: releaseCommit
+			}
+		});
+		if (transition !== void 0) releaseEvidence = versionDelta(transition.previousVersion, transition.version, release.policy);
+	}
 	const prepared = await withTestFileState(git, baseDirname, async (state) => {
 		if (!await state.isClean()) return {
 			summary: `The git repository must be clean to run this command.`,
@@ -1186,50 +1307,43 @@ async function breakage({ tagPattern, baselineFile, testPattern, testCommand, ce
 	if (prepared.summary !== void 0) return prepared;
 	const { restore } = prepared;
 	try {
-		const noBreakingChangesDetected = await new Promise((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$1,
-					testsWereFound: true,
-					testsFound: productionTestFiles,
-					breakingChangesFound: false
-				});
-				else reject(stderr);
-			});
-		});
-		mark?.(`passed tests`);
-		return noBreakingChangesDetected;
-	} catch (thrown) {
-		mark?.(`failed tests`);
-		return await new Promise((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$1,
-					testsWereFound: true,
-					testsFound: productionTestFiles,
-					breakingChangesFound: true,
-					testResult: thrown,
-					breakingChangesCertified: wereCertified,
-					certificationStdout: stdout,
-					certificationStderr: stderr
-				});
-			});
-		});
+		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,
+			lastReleaseFound: true,
+			lastReleaseTag: latestReleaseTag$1,
+			testsWereFound: true,
+			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`);
 		logMarks?.();
 	}
 }
-//#endregion
-export { validateConfig as a, breakagePrelude as c, npmTest as i, formatNpmReport as n, record as o, npmCheck as r, errorMessage as s, breakage as t };
+export { configFields as a, configSchema as c, loadConfig as d, resolveConfig as f, errorMessage as h, npmTest as i, defaultConfig as l, breakagePrelude as m, formatNpmReport as n, configOptions as o, validateConfig as p, npmCheck as r, configPath as s, breakage as t, defineConfig as u };
 
-//# sourceMappingURL=breakage-B7dJsgcu.js.map
+//# sourceMappingURL=breakage-DIY49fzP.js.map