breakage 0.8.4 → 0.8.5

package/dist/breakage-B7dJsgcu.js

@@ -0,0 +1,1235 @@
+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 * 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
+async function withDirectoryLock(lock, action, waitForCleanup = false) {
+	const deadline = Date.now() + 6e4;
+	for (;;) try {
+		await mkdir(lock);
+		break;
+	} catch (thrown) {
+		if (thrown.code !== `EEXIST`) throw thrown;
+		if (!waitForCleanup && Date.now() >= deadline) throw new Error(`Timed out waiting for ${lock}. Check for an interrupted operation before removing this lock.`);
+		await setTimeout(20);
+	}
+	try {
+		return await action();
+	} finally {
+		await rmdir(lock);
+	}
+}
+//#endregion
+//#region src/release-tag.ts
+function compareInteger(a, b) {
+	return a.length - b.length || (a > b ? 1 : a < b ? -1 : 0);
+}
+function compareRelease(a, b) {
+	for (let index = 0; index < 3; index++) {
+		const difference = compareInteger(a.core[index], b.core[index]);
+		if (difference) return difference;
+	}
+	if (!a.prerelease.length || !b.prerelease.length) return Number(!a.prerelease.length) - Number(!b.prerelease.length);
+	for (let index = 0; index < Math.min(a.prerelease.length, b.prerelease.length); index++) {
+		const left = a.prerelease[index];
+		const right = b.prerelease[index];
+		const leftNumeric = /^\d+$/.test(left);
+		const rightNumeric = /^\d+$/.test(right);
+		const difference = leftNumeric && rightNumeric ? compareInteger(left, right) : leftNumeric !== rightNumeric ? Number(rightNumeric) - Number(leftNumeric) : left > right ? 1 : left < right ? -1 : 0;
+		if (difference) return difference;
+	}
+	return a.prerelease.length - b.prerelease.length;
+}
+function latestReleaseTag(remoteTags, tagPattern) {
+	const pattern = tagPattern ? new RegExp(tagPattern) : void 0;
+	let latest;
+	for (const line of remoteTags.split(`\n`)) {
+		if (pattern && !pattern.test(line)) continue;
+		const ref = line.split(`\t`)[1]?.replace(/\^\{\}$/, ``);
+		if (!ref?.startsWith(`refs/tags/`)) continue;
+		const name = ref.slice(`refs/tags/`.length);
+		const version = name.slice(name.lastIndexOf(`@`) + 1);
+		const match = /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(version);
+		if (!match) continue;
+		const prerelease = match[4]?.split(`.`) ?? [];
+		if (prerelease.some((identifier) => /^0\d+$/.test(identifier))) continue;
+		const release = {
+			ref,
+			core: match.slice(1, 4),
+			prerelease
+		};
+		if (!latest || compareRelease(release, latest) > 0) latest = release;
+	}
+	return latest?.ref;
+}
+//#endregion
+//#region src/baseline.ts
+const objectId = /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/;
+function isBaseline(value) {
+	if (typeof value !== `object` || value === null) return false;
+	const record = value;
+	return record.version === 1 && (record.tagPattern === null || typeof record.tagPattern === `string`) && typeof record.packageDirectory === `string` && typeof record.ref === `string` && record.ref.startsWith(`refs/tags/`) && typeof record.commit === `string` && objectId.test(record.commit);
+}
+/** Resolve and fetch a release without running tests or changing the worktree. */
+async function breakagePrelude({ out, tagPattern, baseDirname = process.cwd() }) {
+	const filename = path.resolve(baseDirname, out);
+	const temporaryPath = `${filename}.${randomUUID()}.tmp`;
+	let canInvalidate = false;
+	try {
+		const git = simpleGit(baseDirname);
+		if (!(await git.raw([
+			`check-ignore`,
+			`--`,
+			filename
+		])).trim()) throw new Error(`Baseline output must be gitignored: ${filename}.`);
+		canInvalidate = true;
+		const remoteTags = await git.listRemote([`--tags`, `origin`]);
+		const ref = latestReleaseTag(remoteTags, tagPattern);
+		if (!ref) throw new Error(`No tags found matching the pattern "${tagPattern}".`);
+		const refs = new Map(remoteTags.trim().split(`\n`).map((line) => {
+			const [sha, name] = line.split(`\t`);
+			return [name, sha];
+		}));
+		const commit = refs.get(`${ref}^{}`) ?? refs.get(ref);
+		if (!commit || !objectId.test(commit)) throw new Error(`Could not resolve the release commit for ${ref}.`);
+		const commonGitDirectory = await git.revparse([`--path-format=absolute`, `--git-common-dir`]);
+		await withDirectoryLock(path.join(commonGitDirectory, `breakage-fetch.lock`), () => git.fetch([
+			`origin`,
+			commit,
+			`--no-tags`,
+			`--no-write-fetch-head`
+		]));
+		if ((await git.raw([
+			`cat-file`,
+			`-t`,
+			commit
+		])).trim() !== `commit`) throw new Error(`Release ${ref} does not resolve to a commit.`);
+		const baseline = {
+			version: 1,
+			tagPattern: tagPattern ?? null,
+			packageDirectory: await git.revparse([`--show-prefix`]),
+			ref,
+			commit
+		};
+		await mkdir(path.dirname(filename), { recursive: true });
+		await writeFile(temporaryPath, `${JSON.stringify(baseline, null, 2)}\n`, { flag: `wx` });
+		await rename(temporaryPath, filename);
+		return baseline;
+	} catch (cause) {
+		if (canInvalidate) await rm(filename, { force: true });
+		throw new Error(`Failed to prepare baseline ${filename}.`, { cause });
+	} finally {
+		await rm(temporaryPath, { force: true });
+	}
+}
+async function readBaseline(git, filename, { tagPattern }) {
+	try {
+		const baseline = JSON.parse(await readFile(filename, `utf8`));
+		if (!isBaseline(baseline)) throw new Error(`Invalid baseline fields.`);
+		if (baseline.tagPattern !== (tagPattern ?? null) || baseline.packageDirectory !== await git.revparse([`--show-prefix`])) throw new Error(`Baseline belongs to a different package or tag pattern.`);
+		if ((await git.raw([
+			`check-ref-format`,
+			`--normalize`,
+			baseline.ref
+		])).trim() !== baseline.ref) throw new Error(`Invalid release ref.`);
+		if ((await git.raw([
+			`cat-file`,
+			`-t`,
+			baseline.commit
+		])).trim() !== `commit`) throw new Error(`Pinned object is not a locally available commit.`);
+		return baseline;
+	} catch (cause) {
+		throw new Error(`Missing, invalid, or unusable baseline ${filename}. Run breakage prelude again.`, { cause });
+	}
+}
+//#endregion
+//#region src/test-file-state.ts
+function isActiveCheck(value) {
+	if (typeof value !== `object` || value === null) return false;
+	const record = value;
+	return typeof record.pid === `number` && Number.isSafeInteger(record.pid) && record.pid > 0 && typeof record.head === `string` && /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(record.head) && (record.recoveryRequired === void 0 || typeof record.recoveryRequired === `boolean`) && Array.isArray(record.paths) && record.paths.length > 0 && record.paths.every((file) => typeof file === `string` && !path.isAbsolute(file) && !path.win32.isAbsolute(file) && file.split(`/`).every((part) => part !== `` && part !== `.` && part !== `..`));
+}
+async function readRecoveryRecord(recordPath) {
+	try {
+		const record = JSON.parse(await readFile(recordPath, `utf8`));
+		if (!isActiveCheck(record)) throw new TypeError(`Invalid recovery record fields`);
+		return record;
+	} catch (cause) {
+		throw new Error(`A breakage run needs recovery. The record ${recordPath} is unreadable or invalid. Verify no check is running and recover its test files before removing this record.`, { cause });
+	}
+}
+async function writeRecoveryRecord(recordPath, record) {
+	const temporaryPath = `${recordPath}.${randomUUID()}.tmp`;
+	try {
+		await writeFile(temporaryPath, JSON.stringify(record), { flag: `wx` });
+		await rename(temporaryPath, recordPath);
+	} finally {
+		await rm(temporaryPath, { force: true });
+	}
+}
+function assertContained(root, filename) {
+	const relative = path.relative(root, filename);
+	if (relative === `..` || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new Error(`Cannot replace tests outside the worktree: ${filename}.`);
+}
+async function validateParents(root, filenames) {
+	const checked = /* @__PURE__ */ new Set();
+	for (const filename of filenames) {
+		assertContained(root, filename);
+		for (let parent = path.dirname(filename);; parent = path.dirname(parent)) {
+			if (checked.has(parent)) break;
+			const stats = await lstat(parent).catch((thrown) => {
+				if (thrown.code !== `ENOENT`) throw thrown;
+			});
+			if (stats && !stats.isDirectory()) throw new Error(`Cannot replace tests through ${parent}.`);
+			checked.add(parent);
+			if (parent === root) break;
+		}
+	}
+}
+async function withTestFileState(git, baseDirname, action) {
+	const root = await realpath(await git.revparse([`--show-toplevel`]));
+	baseDirname = await realpath(baseDirname);
+	assertContained(root, baseDirname);
+	const stateDirectory = path.join(await git.revparse([`--absolute-git-dir`]), `breakage`);
+	await mkdir(stateDirectory, { recursive: true });
+	const lock = path.join(stateDirectory, `lock`);
+	return withDirectoryLock(lock, async () => {
+		const activeChecks = [];
+		for (const entry of await readdir(stateDirectory)) {
+			if (!entry.endsWith(`.json`)) continue;
+			const recordPath = path.join(stateDirectory, entry);
+			const record = await readRecoveryRecord(recordPath);
+			let interrupted = record.recoveryRequired;
+			try {
+				process.kill(record.pid, 0);
+			} catch (thrown) {
+				if (thrown.code !== `EPERM`) interrupted = true;
+			}
+			if (interrupted) throw new Error(`A breakage run needs recovery. Restore the test paths recorded in ${recordPath} before removing that record.`);
+			activeChecks.push(record);
+		}
+		const activePaths = activeChecks.flatMap((record) => record.paths);
+		return action({
+			isClean: async () => !await simpleGit(root).raw([
+				`--no-optional-locks`,
+				`status`,
+				`--porcelain`,
+				`--untracked-files=all`,
+				`--`,
+				`.`,
+				...activePaths.map((file) => `:(top,literal,exclude)${file}`)
+			]),
+			replaceTests: async (release, files) => {
+				const paths = files.map((file) => path.relative(root, path.resolve(baseDirname, file)).split(path.sep).join(`/`));
+				for (const file of paths) if (activePaths.some((active) => file === active || file.startsWith(`${active}/`) || active.startsWith(`${file}/`))) throw new Error(`Another breakage run is using ${file}. Concurrent checks must use disjoint test paths.`);
+				const head = await git.revparse([`HEAD`]);
+				const currentFiles = new Set((await git.raw([
+					`ls-tree`,
+					`-r`,
+					`--name-only`,
+					`-z`,
+					head
+				])).split(`\0`).filter(Boolean));
+				const existing = files.filter((file) => currentFiles.has(file));
+				const absent = files.filter((file) => !currentFiles.has(file));
+				const modes = /* @__PURE__ */ new Map();
+				const filenames = files.map((file) => path.resolve(baseDirname, file));
+				await validateParents(root, filenames);
+				for (const file of files) {
+					const filename = path.resolve(baseDirname, file);
+					const stats = await lstat(filename).catch((thrown) => {
+						if (thrown.code !== `ENOENT`) throw thrown;
+					});
+					if (!currentFiles.has(file) && stats) throw new Error(`Cannot overwrite the existing untracked path ${filename}.`);
+					if (stats?.isFile()) modes.set(filename, stats.mode);
+				}
+				const recordPath = path.join(stateDirectory, `${randomUUID()}.json`);
+				const record = {
+					pid: process.pid,
+					paths,
+					head
+				};
+				await writeRecoveryRecord(recordPath, record);
+				const restore = async () => {
+					await writeRecoveryRecord(recordPath, {
+						...record,
+						recoveryRequired: true
+					});
+					await validateParents(root, filenames);
+					if (existing.length) await git.raw([
+						`--literal-pathspecs`,
+						`restore`,
+						`--source=${head}`,
+						`--worktree`,
+						`--`,
+						...existing
+					]);
+					for (const file of absent) await rm(path.resolve(baseDirname, file), { force: true });
+					for (const [filename, mode] of modes) await chmod(filename, mode);
+					await rm(recordPath);
+				};
+				try {
+					await git.raw([
+						`--literal-pathspecs`,
+						`restore`,
+						`--source=${release}`,
+						`--worktree`,
+						`--`,
+						...files
+					]);
+				} catch (thrown) {
+					await restore();
+					throw thrown;
+				}
+				return () => withDirectoryLock(lock, restore, true);
+			}
+		});
+	});
+}
+//#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
+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.`);
+	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}.`);
+	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.`);
+	for (const [peer, suite] of Object.entries(value.suites)) if (!packageName(peer) || !record(suite) || !nonempty(suite.command) || !Array.isArray(suite.files) || !suite.files.length || suite.files.some((file) => !nonempty(file))) throw new Error(`Invalid npm suite for ${peer}.`);
+	if (!record(value.baseline) || (`firstRelease` in value.baseline ? value.baseline.firstRelease !== true || Object.keys(value.baseline).length !== 1 : Object.entries(value.baseline).some(([key, item]) => ![`tagPattern`, `baselineFile`].includes(key) || !nonempty(item)))) throw new Error(`Configure npm.baseline with tagPattern/baselineFile or { firstRelease: true }.`);
+	if (value.localPeers !== void 0) {
+		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.`);
+	return {
+		status: `release`,
+		version: result.version
+	};
+}
+/**
+* Compare the union, including adjacent alternatives. semver.subset compares each
+* conjunction to a single conjunction and cannot prove coverage by their union.
+* Membership can change only at comparator boundaries or prerelease tuple gates.
+*/
+function includesRange(current, previous) {
+	const ranges = [new semver.Range(previous), new semver.Range(current)];
+	const samples = /* @__PURE__ */ new Set([`0.0.0`, `0.0.0-0`]);
+	for (const range of ranges) for (const conjunction of range.set) for (const comparator of conjunction) {
+		const version = comparator.semver;
+		if (typeof version === `symbol`) continue;
+		const base = `${version.major}.${version.minor}.${version.patch}`;
+		samples.add(version.version);
+		samples.add(base);
+		samples.add(`${base}-0`);
+		if (version.prerelease.length) samples.add(`${version.version}.0`);
+		const next = semver.inc(base, `patch`);
+		if (next) {
+			samples.add(next);
+			samples.add(`${next}-0`);
+		}
+	}
+	return [...samples].every((version) => !semver.satisfies(version, previous) || semver.satisfies(version, current));
+}
+function supportChanges(previous, current) {
+	const before = previous.peerDependencies ?? {};
+	const after = current.peerDependencies ?? {};
+	validatePeerRanges(before);
+	validatePeerRanges(after);
+	return Object.entries(after).flatMap(([peer, range]) => {
+		const old = before[peer];
+		const wasOptional = previous.peerDependenciesMeta?.[peer]?.optional === true;
+		const isOptional = current.peerDependenciesMeta?.[peer]?.optional === true;
+		return old === void 0 && isOptional || old !== void 0 && includesRange(range, old) && !(wasOptional && !isOptional) ? [] : [{
+			peer,
+			reason: old === void 0 || wasOptional && !isOptional ? `required-peer` : `narrowed-range`,
+			previous: old ?? null,
+			current: range
+		}];
+	});
+}
+async function previousManifest(config, directory) {
+	if (`firstRelease` in config.baseline) return void 0;
+	const git = simpleGit(directory);
+	let commit;
+	if (config.baseline.baselineFile) commit = (await readBaseline(git, path.resolve(directory, config.baseline.baselineFile), config.baseline)).commit;
+	else {
+		const tags = await git.listRemote([`--tags`, `origin`]);
+		const ref = latestReleaseTag(tags, config.baseline.tagPattern);
+		if (!ref) throw new Error(`No npm release baseline found; configure a tag pattern or explicitly declare firstRelease.`);
+		const refs = new Map(tags.trim().split(`\n`).map((line) => {
+			const [sha, name] = line.split(`\t`);
+			return [name, sha];
+		}));
+		const resolved = refs.get(`${ref}^{}`) ?? refs.get(ref);
+		if (!resolved || !/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(resolved)) throw new Error(`Invalid release commit for ${ref}.`);
+		commit = resolved;
+		const common = await git.revparse([`--path-format=absolute`, `--git-common-dir`]);
+		await withDirectoryLock(path.join(common, `breakage-fetch.lock`), () => git.fetch([
+			`origin`,
+			commit,
+			`--no-tags`,
+			`--no-write-fetch-head`
+		]));
+	}
+	const prefix = await git.revparse([`--show-prefix`]);
+	return await normalizeWorkspacePeers(parseManifest(JSON.parse(await git.show([`${commit}:${prefix}package.json`])), `release ${commit}`), async (peer) => {
+		const local = config.localPeers?.[peer];
+		if (!local) throw new Error(`Historical workspace peer ${peer} needs a localPeers directory to resolve release ${commit}.`);
+		const root = await git.revparse([`--show-toplevel`]);
+		const relative = path.relative(root, path.resolve(directory, local.directory));
+		if (relative === `..` || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) throw new Error(`Historical workspace peer ${peer} escapes the release repository.`);
+		const filename = path.join(relative, `package.json`).split(path.sep).join(`/`);
+		const historical = parseManifest(JSON.parse(await git.show([`${commit}:${filename}`])), `release ${commit}:${filename}`);
+		if (historical.name !== peer) throw new Error(`Historical workspace peer identity mismatch for ${peer}.`);
+		return historical.version;
+	});
+}
+//#endregion
+//#region src/npm/environment.ts
+function within(parent, child) {
+	const relative = path.relative(parent, child);
+	return relative === `` || !relative.startsWith(`..${path.sep}`) && relative !== `..` && !path.isAbsolute(relative);
+}
+async function exists(filename) {
+	try {
+		await lstat(filename);
+		return true;
+	} catch (error) {
+		if (error.code === `ENOENT`) return false;
+		throw error;
+	}
+}
+async function discover(config, base) {
+	const found = /* @__PURE__ */ new Set();
+	for await (const name of fs.glob(config.representatives, {
+		cwd: base,
+		exclude: [
+			`**/node_modules/**`,
+			`**/test/**`,
+			`**/.git/**`
+		]
+	})) {
+		const directory = path.resolve(base, name);
+		if (!(await lstat(directory)).isDirectory()) throw new Error(`Representative is not a directory: ${name}.`);
+		found.add(directory);
+	}
+	if (!found.size) throw new Error(`No representative directories matched the configured globs.`);
+	return [...found].sort();
+}
+/** A freshly created ignored stage is also the exclusive ownership lock. */
+async function withStage(directory, action) {
+	const stage = path.join(directory, `test`);
+	const git = simpleGit(directory);
+	const root = await git.revparse([`--show-toplevel`]);
+	if (!within(await realpath(root), await realpath(directory))) throw new Error(`Representative escapes the repository: ${directory}.`);
+	if (!(await git.raw([
+		`check-ignore`,
+		`--`,
+		`${stage}/`
+	])).trim() || (await git.raw([
+		`ls-files`,
+		`--`,
+		stage
+	])).trim()) throw new Error(`Representative test/ must be gitignored and contain no tracked files: ${stage}.`);
+	try {
+		await mkdir(stage);
+	} catch (cause) {
+		throw new Error(`Cannot own ${stage}; another run or preexisting files may be present. Remove it only after checking ownership.`, { cause });
+	}
+	try {
+		return await action(stage);
+	} finally {
+		await rm(stage, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+async function installed(directory, peer) {
+	const location = path.join(directory, `node_modules`, peer);
+	const physical = await realpath(location);
+	if (!physical.split(path.sep).includes(`node_modules`)) throw new Error(`Peer ${peer} resolves to workspace source: ${physical}.`);
+	const manifest = await readManifest(path.join(physical, `package.json`));
+	if (manifest.name !== peer) throw new Error(`Expected ${peer}, found ${manifest.name} in ${location}.`);
+	return {
+		version: manifest.version,
+		path: physical,
+		source: `installed`
+	};
+}
+function representativeDeclarations(manifest) {
+	for (const field of [
+		`dependencies`,
+		`devDependencies`,
+		`optionalDependencies`,
+		`peerDependencies`
+	]) for (const [name, specifier] of Object.entries(manifest[field] ?? {})) {
+		const version = semver.parse(specifier);
+		const exact = version && `${version.version}${version.build.length ? `+${version.build.join(`.`)}` : ``}`;
+		if (!exact || specifier !== exact) throw new Error(`Representative ${manifest.name} must pin ${field}.${name} to an exact version, such as 1.0.0; received ${JSON.stringify(specifier)}. Declare support ranges in the package under test, and use breakage.candidates for coordinated local releases.`);
+	}
+	for (const [peer, development] of Object.entries(manifest.devDependencies ?? {})) for (const field of [`dependencies`, `optionalDependencies`]) {
+		const runtime = manifest[field]?.[peer];
+		if (runtime !== void 0 && runtime !== development) throw new Error(`Conflicting representative declarations for ${peer}: devDependencies has ${development}, but ${field} has ${runtime}. Use one consistent requirement.`);
+	}
+	return {
+		...manifest.devDependencies,
+		...manifest.dependencies,
+		...manifest.optionalDependencies
+	};
+}
+/** Select exact pins without acquiring or preparing their stages. */
+async function maySelectEnvironment(config, base, directory, packageManifest, selection) {
+	const manifest = await readManifest(path.join(directory, `package.json`));
+	const declarations = representativeDeclarations(manifest);
+	const { peer, range } = selection;
+	if (peer === packageManifest.name) return matches(packageManifest.version, range);
+	if (manifest.breakage?.candidates?.includes(peer)) {
+		const local = config.localPeers?.[peer];
+		if (!local) throw new Error(`Candidate ${peer} has no localPeers configuration.`);
+		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, {
+			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);
+	}
+	const declared = declarations[peer];
+	return declared !== void 0 && matches(declared, range);
+}
+async function prepareEnvironment(config, base, directory, stage, packageManifest) {
+	const peerNames = Object.keys(packageManifest.peerDependencies ?? {});
+	const filename = path.join(directory, `package.json`);
+	const lockfile = path.join(directory, config.lockfile);
+	for (const input of [filename, lockfile]) if (!(await lstat(input)).isFile() || !within(directory, await realpath(input))) throw new Error(`Installation inputs must be regular files inside the representative: ${input}.`);
+	const inputs = await Promise.all([readFile(filename), readFile(lockfile)]);
+	const manifest = await readManifest(filename);
+	const declarations = representativeDeclarations(manifest);
+	const candidates = {};
+	for (const peer of manifest.breakage?.candidates ?? []) {
+		if (!peerNames.includes(peer)) throw new Error(`Candidate ${peer} is not a declared peer of the package under test.`);
+		const local = config.localPeers?.[peer];
+		if (!local) throw new Error(`Candidate ${peer} has no localPeers configuration.`);
+		const localDirectory = path.resolve(base, local.directory);
+		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, {
+			packageName: peer,
+			packageDirectory: localDirectory,
+			currentVersion: localManifest.version
+		});
+		if (evidence.status === `none`) throw new Error(`Candidate ${peer} has no certified release intent.`);
+		candidates[peer] = {
+			directory: localDirectory,
+			artifact: path.resolve(base, local.artifact),
+			currentVersion: localManifest.version,
+			version: evidence.version,
+			manifest: localManifest
+		};
+	}
+	const relevant = [.../* @__PURE__ */ new Set([...peerNames, ...Object.values(candidates).flatMap((candidate) => Object.keys(candidate.manifest.peerDependencies ?? {}))])].filter((peer) => peer === packageManifest.name || declarations[peer] !== void 0 || candidates[peer] !== void 0);
+	const before = {};
+	for (const peer of relevant) if (peer !== packageManifest.name && !candidates[peer] && await exists(path.join(directory, `node_modules`, peer))) before[peer] = (await installed(directory, peer)).version;
+	const preparation = await prepare(config.prepareCommand, directory).then(() => ({ ok: true }), (error) => ({
+		ok: false,
+		error
+	}));
+	const after = await Promise.all([filename, lockfile].map((input) => readFile(input).catch(() => Buffer.alloc(0))));
+	if (inputs.some((input, index) => !input.equals(after[index]))) {
+		await Promise.all([filename, lockfile].map(async (input, index) => {
+			await rm(input, { force: true });
+			await writeFile(input, inputs[index], { flag: `wx` });
+		}));
+		throw new Error(`Frozen preparation changed the manifest or lockfile in ${directory}; restored the original inputs.`, { cause: preparation.ok ? void 0 : preparation.error });
+	}
+	if (!preparation.ok) throw preparation.error;
+	const peers = {};
+	for (const peer of relevant) {
+		const candidate = candidates[peer];
+		const staged = candidate !== void 0 || peer === packageManifest.name;
+		if (!staged && Object.hasOwn(manifest.optionalDependencies ?? {}, peer) && !await exists(path.join(directory, `node_modules`, peer))) continue;
+		const evidence = staged ? {
+			version: candidate?.version ?? packageManifest.version,
+			path: path.join(stage, `node_modules`, peer),
+			source: `candidate`
+		} : await installed(directory, peer);
+		const specifier = declarations[peer];
+		if (!(staged && specifier === void 0) && evidence.version !== specifier) throw new Error(`Representative ${peer}@${evidence.version} does not match its manifest pin ${specifier ?? `(missing)`}.`);
+		if (before[peer] && before[peer] !== evidence.version) throw new Error(`Stale installed ${peer}: frozen preparation changed ${before[peer]} to ${evidence.version}.`);
+		for (const [localPeer, local] of Object.entries(config.localPeers ?? {})) {
+			if (staged) continue;
+			const localDirectory = path.resolve(base, local.directory);
+			if (!peerNames.includes(localPeer) && !relevant.includes(localPeer) && !await exists(localDirectory)) continue;
+			if (within(await realpath(localDirectory), evidence.path)) throw new Error(`Released peer ${peer} resolves into a local workspace package.`);
+		}
+		peers[peer] = evidence;
+	}
+	return {
+		directory,
+		stage,
+		manifest,
+		peers,
+		candidates
+	};
+}
+/** Validate the complete coordinated formulation before an audit or execution. */
+function checkCandidatePeers(environment, focused) {
+	const conflicts = [];
+	for (const [name, candidate] of Object.entries(environment.candidates)) for (const [peer, range] of Object.entries(candidate.manifest.peerDependencies ?? {})) {
+		const evidence = environment.peers[peer];
+		if (!evidence) {
+			if (candidate.manifest.peerDependenciesMeta?.[peer]?.optional) continue;
+			throw new Error(`Complete representative is missing required peer ${peer}: ${range} of coordinated candidate ${name}@${candidate.version}.`);
+		}
+		if (!semver.satisfies(evidence.version, range)) conflicts.push(`Coordinated candidate ${name}@${candidate.version} requires ${peer}: ${range}, but the representative provides ${peer}@${evidence.version}.`);
+	}
+	if (conflicts.length && !focused) throw new Error(conflicts.join(`\n`));
+	return conflicts.map((conflict) => `${conflict} Running focused exploration outside declared support.`);
+}
+async function copySuite(base, stage, suite) {
+	for (const pattern of suite.files) {
+		if (path.isAbsolute(pattern) || pattern.split(/[\\/]/).includes(`..`)) throw new Error(`Suite pattern must stay inside the package: ${pattern}.`);
+		let count = 0;
+		for await (const filename of fs.glob(pattern, {
+			cwd: base,
+			exclude: [
+				`**/node_modules/**`,
+				`**/.git/**`,
+				path.relative(base, stage),
+				`${path.relative(base, stage)}/**`
+			]
+		})) {
+			const source = path.resolve(base, filename);
+			const stat = await lstat(source);
+			if (stat.isDirectory()) continue;
+			if (!stat.isFile() || !within(await realpath(base), await realpath(source))) throw new Error(`Suite inputs must be regular package files: ${filename}.`);
+			let segment = base;
+			for (const part of filename.split(path.sep)) {
+				segment = path.join(segment, part);
+				if ((await lstat(segment)).isSymbolicLink()) throw new Error(`Suite inputs cannot follow symlinks: ${filename}.`);
+			}
+			if ([
+				`package.json`,
+				`package-lock.json`,
+				`npm-shrinkwrap.json`,
+				`.npmrc`
+			].includes(filename) || filename.split(path.sep).includes(`node_modules`)) throw new Error(`Suite input collides with the consumer installation: ${filename}.`);
+			const destination = path.resolve(stage, filename);
+			if (!within(stage, destination)) throw new Error(`Suite path escapes its stage: ${filename}.`);
+			await mkdir(path.dirname(destination), { recursive: true });
+			await copyFile(source, destination);
+			count++;
+		}
+		if (!count) throw new Error(`Suite pattern matched no files: ${pattern}.`);
+	}
+}
+async function findPackage(from, name, installation) {
+	const origin = await realpath(from);
+	const parts = origin.split(path.sep);
+	const modules = parts.lastIndexOf(`node_modules`);
+	const boundary = within(installation, origin) ? installation : modules < 0 ? origin : parts.slice(0, modules + 1).join(path.sep);
+	const lookup = createRequire(path.join(origin, `__breakage_probe__.ts`)).resolve.paths(name) ?? [];
+	for (const directory of lookup) {
+		const location = path.join(directory, name);
+		if (await exists(location)) {
+			if (!within(installation, directory) && !within(boundary, directory)) throw new Error(`Dependency ${name} resolves outside the representative installation: ${location}.`);
+			return await realpath(location);
+		}
+	}
+}
+async function resolvePackage(from, name, installation) {
+	const location = await findPackage(from, name, installation);
+	if (location !== void 0) return location;
+	throw new Error(`Cannot resolve ${name} from ${from}.`);
+}
+async function stageCandidate(config, base, manifest, environment, suites) {
+	const { stage, candidates } = environment;
+	const artifacts = {
+		[manifest.name]: path.resolve(base, config.artifact),
+		...Object.fromEntries(Object.entries(candidates).map(([name, entry]) => [name, entry.artifact]))
+	};
+	if (candidates[manifest.name]) throw new Error(`The package under test cannot also be its own candidate peer.`);
+	for (const artifact of Object.values(artifacts)) if (!(await lstat(artifact)).isFile()) throw new Error(`Candidate artifact must be a packed file: ${artifact}.`);
+	await writeFile(path.join(stage, `package.json`), JSON.stringify({
+		name: `breakage-consumer`,
+		version: `0.0.0`,
+		private: true,
+		type: environment.manifest.type ?? `module`,
+		dependencies: Object.fromEntries(Object.entries(artifacts).map(([name, artifact]) => [name, `file:${artifact}`]))
+	}));
+	await prepare(config.installCommand ?? `npm install --prefix . --workspaces=false --ignore-scripts --legacy-peer-deps --package-lock=false --no-audit --no-fund`, stage);
+	for (const [name] of Object.entries(artifacts)) {
+		const directory = path.join(stage, `node_modules`, name);
+		if (!within(stage, await realpath(directory))) throw new Error(`Candidate ${name} must be installed inside the test stage.`);
+		const filename = path.join(directory, `package.json`);
+		const packed = await readManifest(filename);
+		const candidate = candidates[name];
+		if (packed.name !== name || (candidate ? ![candidate.currentVersion, candidate.version].includes(packed.version) : packed.version !== manifest.version)) throw new Error(`Candidate archive identity/version mismatch for ${name}@${packed.version}.`);
+		const expectedManifest = candidate?.manifest ?? manifest;
+		if (Object.keys({
+			...packed.peerDependencies,
+			...expectedManifest.peerDependencies
+		}).some((peer) => packed.peerDependencies?.[peer] !== expectedManifest.peerDependencies?.[peer] || Boolean(packed.peerDependenciesMeta?.[peer]?.optional) !== Boolean(expectedManifest.peerDependenciesMeta?.[peer]?.optional))) throw new Error(`Candidate archive has stale peer declarations; rebuild and pack ${name}.`);
+		if (candidate) {
+			const evidence = environment.peers[name];
+			if (evidence) evidence.archiveVersion = packed.version;
+			if (packed.version !== candidate.version) {
+				const raw = JSON.parse(await readFile(filename, `utf8`));
+				const temporary = path.join(path.dirname(filename), `.breakage-${randomUUID()}.json`);
+				await writeFile(temporary, JSON.stringify({
+					...raw,
+					version: candidate.version
+				}), { flag: `wx` });
+				try {
+					await rename(temporary, filename);
+				} finally {
+					await rm(temporary, { force: true });
+				}
+			}
+		}
+	}
+	for (const suite of suites) await copySuite(base, stage, suite);
+	await verifyResolution(manifest, environment);
+}
+async function verifyResolution(manifest, environment) {
+	const { stage, peers } = environment;
+	const installation = await realpath(environment.directory);
+	const packages = [manifest.name, ...Object.keys(environment.candidates)];
+	for (const [peer, evidence] of Object.entries(peers)) {
+		const expected = await realpath(evidence.path);
+		if (await resolvePackage(stage, peer, installation) !== expected) throw new Error(`Tests resolve a shadow copy of ${peer}.`);
+		for (const name of packages) {
+			if (name === peer) continue;
+			if (await resolvePackage(path.join(stage, `node_modules`, name), peer, installation) !== expected) throw new Error(`Candidate ${name} resolves a different instance of ${peer} than its tests.`);
+		}
+		const actual = await readManifest(path.join(expected, `package.json`));
+		if (actual.name !== peer || actual.version !== evidence.version) throw new Error(`Peer identity changed during execution: ${peer}.`);
+	}
+	const visited = /* @__PURE__ */ new Set();
+	const pending = packages.map((name) => path.join(stage, `node_modules`, name));
+	while (pending.length) {
+		const directory = await realpath(pending.pop());
+		if (visited.has(directory)) continue;
+		if (!directory.split(path.sep).includes(`node_modules`)) throw new Error(`Runtime dependency resolves to workspace source: ${directory}.`);
+		visited.add(directory);
+		const installedManifest = await readManifest(path.join(directory, `package.json`));
+		for (const peer of Object.keys(installedManifest.peerDependencies ?? {})) {
+			const evidence = peers[peer];
+			if (evidence && await resolvePackage(directory, peer, installation) !== await realpath(evidence.path)) throw new Error(`Runtime dependency ${installedManifest.name} resolves a different instance of ${peer}.`);
+		}
+		const optional = installedManifest.optionalDependencies ?? {};
+		for (const dependency of Object.keys({
+			...installedManifest.dependencies,
+			...optional
+		})) if (Object.hasOwn(optional, dependency)) {
+			const location = await findPackage(directory, dependency, installation);
+			if (location !== void 0) pending.push(location);
+		} else pending.push(await resolvePackage(directory, dependency, installation));
+	}
+}
+//#endregion
+//#region src/npm/check.ts
+async function checkSupport(config, base, manifest) {
+	try {
+		const previous = await previousManifest(config, base);
+		if (!previous) return {
+			status: `first-release`,
+			changes: []
+		};
+		if (previous.name !== manifest.name) throw new Error(`Release baseline belongs to ${previous.name}, not ${manifest.name}.`);
+		const changes = supportChanges(previous, manifest);
+		if (!changes.length) return {
+			status: `unchanged`,
+			previousVersion: previous.version,
+			changes
+		};
+		const evidence = await intent(config, {
+			packageName: manifest.name,
+			packageDirectory: base,
+			currentVersion: manifest.version
+		});
+		if (evidence.status === `none`) 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.`);
+		return {
+			status: certified ? `certified` : `end-of-support`,
+			previousVersion: previous.version,
+			changes,
+			release
+		};
+	} catch (error) {
+		return {
+			status: `setup-error`,
+			changes: [],
+			error: errorMessage(error)
+		};
+	}
+}
+async function checkLocalReleases(config, base, manifest, representatives) {
+	return (await Promise.all(Object.entries(config.localPeers ?? {}).map(async ([peer, local]) => {
+		const range = manifest.peerDependencies?.[peer];
+		if (range === void 0) return [];
+		try {
+			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, {
+				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.`];
+			return [];
+		} catch (error) {
+			return [`Cannot inspect planned local release for ${peer}: ${errorMessage(error)}`];
+		}
+	}))).flat();
+}
+async function runRepresentative(config, base, manifest, directory, coverageOnly, selection) {
+	const result = {
+		path: path.relative(base, directory).split(path.sep).join(`/`),
+		status: `skipped`,
+		peers: {},
+		suites: [],
+		warnings: []
+	};
+	if (selection && `representative` in selection && path.resolve(base, selection.representative) !== directory) return result;
+	try {
+		if (selection && `peer` in selection && !await maySelectEnvironment(config, base, directory, manifest, selection)) return result;
+		return await withStage(directory, async (stage) => {
+			const environment = await prepareEnvironment(config, base, directory, stage, manifest);
+			result.peers = environment.peers;
+			for (const peer of Object.keys(manifest.peerDependencies ?? {})) if (!result.peers[peer] && !manifest.peerDependenciesMeta?.[peer]?.optional) throw new Error(`Complete representative is missing required peer ${peer}.`);
+			for (const [peer, evidence] of Object.entries(result.peers)) {
+				const range = manifest.peerDependencies?.[peer];
+				if (range !== void 0 && !matches(evidence.version, range)) result.warnings.push(`${peer}@${evidence.version} is outside declared support.`);
+			}
+			if (selection && `peer` in selection && (!result.peers[selection.peer] || !matches(result.peers[selection.peer].version, selection.range))) return result;
+			const peers = Object.keys(config.suites).filter((peer) => {
+				const evidence = result.peers[peer];
+				if (!evidence) return false;
+				if (selection && `peer` in selection) return peer === selection.peer;
+				if (selection && `representative` in selection) return true;
+				return matches(evidence.version, manifest.peerDependencies[peer]);
+			});
+			result.suites = peers.map((peer) => ({
+				peer,
+				status: `not-run`
+			}));
+			if (!peers.length) return result;
+			result.warnings.push(...checkCandidatePeers(environment, !!selection));
+			if (coverageOnly) {
+				result.status = `audited`;
+				return result;
+			}
+			await stageCandidate(config, base, manifest, environment, peers.map((peer) => config.suites[peer]));
+			for (const suite of result.suites) try {
+				await verifyResolution(manifest, environment);
+				const execution = await command(config.suites[suite.peer].command, stage);
+				await verifyResolution(manifest, environment);
+				suite.status = execution.code === 0 ? `passed` : execution.code === 1 ? `compatibility-failure` : `setup-error`;
+				if (execution.output) suite.output = execution.output;
+			} catch (error) {
+				suite.status = `setup-error`;
+				suite.output = errorMessage(error);
+			}
+			result.status = result.suites.some((suite) => suite.status === `setup-error`) ? `setup-error` : result.suites.some((suite) => suite.status === `compatibility-failure`) ? `compatibility-failure` : `passed`;
+			return result;
+		});
+	} catch (error) {
+		result.status = `setup-error`;
+		result.error = errorMessage(error);
+		return result;
+	}
+}
+async function run(config, baseDirectory, coverageOnly, selection) {
+	const report = {
+		package: {
+			name: `(unresolved)`,
+			version: `(unresolved)`
+		},
+		mode: selection ? `test` : coverageOnly ? `coverage-only` : `check`,
+		exitCode: 0,
+		representatives: [],
+		coverage: [],
+		support: {
+			status: `not-checked`,
+			changes: []
+		},
+		errors: []
+	};
+	try {
+		validateConfig(config);
+		const base = path.resolve(baseDirectory, config.packageDirectory ?? `.`);
+		const manifest = await normalizeWorkspacePeers(await readManifest(path.join(base, `package.json`)));
+		report.package = {
+			name: manifest.name,
+			version: manifest.version
+		};
+		validatePeerRanges(manifest.peerDependencies ?? {});
+		for (const peer of Object.keys(config.suites)) if (!manifest.peerDependencies?.[peer]) throw new Error(`Suite ${peer} has no peerDependencies declaration.`);
+		for (const peer of Object.keys(config.localPeers ?? {})) if (manifest.peerDependencies?.[peer] && !config.suites[peer]) throw new Error(`Declared local peer ${peer} needs a relationship suite.`);
+		if (selection && `peer` in selection) {
+			if (!config.suites[selection.peer]) throw new Error(`No relationship suite configured for ${selection.peer}.`);
+			eras(selection.range);
+		}
+		const releases = /* @__PURE__ */ new Map();
+		const configuredHook = config.releaseIntent;
+		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;
+			}
+		};
+		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)))]);
+		report.support = support;
+		report.representatives = representatives;
+		if (!selection) {
+			report.errors.push(...await checkLocalReleases(effective, base, manifest, representatives));
+			for (const peer of Object.keys(config.suites)) for (const era of eras(manifest.peerDependencies[peer])) {
+				const matching = representatives.filter((representative) => representative.peers[peer] && matches(representative.peers[peer].version, era)).map((representative) => representative.path);
+				report.coverage.push({
+					peer,
+					era,
+					representatives: matching
+				});
+				if (!matching.length) report.errors.push(`No representative covers ${peer}: ${era}.`);
+			}
+		} else if (!representatives.some((representative) => representative.suites.length > 0)) report.errors.push(`No representative matched the requested test selection.`);
+		if (support.status === `setup-error` || report.errors.length || representatives.some((result) => result.status === `setup-error`)) report.exitCode = 2;
+		else if (support.status === `end-of-support` || representatives.some((result) => result.status === `compatibility-failure`)) report.exitCode = 1;
+	} catch (error) {
+		report.errors.push(errorMessage(error));
+		report.exitCode = 2;
+	}
+	return report;
+}
+async function npmCheck(config, options = {}) {
+	return await run(config, options.baseDirectory ?? process.cwd(), options.coverageOnly ?? false);
+}
+async function npmTest(config, selection, options = {}) {
+	return await run(config, options.baseDirectory ?? process.cwd(), false, selection);
+}
+function formatNpmReport(report) {
+	const lines = [`${report.package.name}@${report.package.version} — npm ${report.mode}`];
+	for (const result of report.representatives) {
+		lines.push(`${result.path}: ${result.status}`);
+		for (const [peer, evidence] of Object.entries(result.peers)) lines.push(`  ${peer}@${evidence.version}${evidence.source === `candidate` ? ` (conditional on publication)` : ` (installed)`}`);
+		for (const suite of result.suites) {
+			lines.push(`  ${suite.peer}: ${suite.status}`);
+			if (suite.status !== `passed` && suite.output) lines.push(suite.output);
+		}
+		for (const warning of result.warnings) lines.push(`  Warning: ${warning}`);
+		if (result.error) lines.push(`  ${result.error}`);
+	}
+	lines.push(`Support: ${report.support.status}`);
+	for (const change of report.support.changes) lines.push(`  ${change.peer}: ${change.previous ?? `(unrestricted)`} → ${change.current ?? `(unrestricted)`} (${change.reason})`);
+	if (report.support.release) lines.push(`  Intended release: ${report.support.release.version} (${report.support.release.delta})`);
+	if (report.support.error) lines.push(report.support.error);
+	lines.push(...report.errors);
+	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 }) {
+	let mark;
+	let logMarks;
+	if (verbose) {
+		const chronicle = logger.makeChronicle();
+		mark = chronicle.mark;
+		logMarks = chronicle.logMarks;
+	}
+	mark?.(`breakage`);
+	const git = simpleGit(baseDirname);
+	mark?.(`spawn git`);
+	const isGitRepo = await git.checkIsRepo();
+	mark?.(`is git repository`);
+	if (!isGitRepo) return {
+		summary: `The git repository must be clean to run this command.`,
+		gitWasClean: false
+	};
+	if (!await withTestFileState(git, baseDirname, (state) => state.isClean())) return {
+		summary: `The git repository must be clean to run this command.`,
+		gitWasClean: false
+	};
+	let latestReleaseTag$1;
+	let releaseCommit;
+	if (baselineFile !== void 0) {
+		const baseline = await readBaseline(git, path.resolve(baseDirname, baselineFile), { tagPattern });
+		latestReleaseTag$1 = baseline.ref;
+		releaseCommit = baseline.commit;
+		mark?.(`read pinned release baseline`);
+	} else {
+		const tagsRemote = await git.listRemote([`--tags`, `origin`]);
+		mark?.(`list remote tags`);
+		latestReleaseTag$1 = latestReleaseTag(tagsRemote, tagPattern);
+		mark?.(`found latest release tag`);
+		if (!latestReleaseTag$1) return {
+			summary: `No tags found matching the pattern "${tagPattern}".`,
+			gitWasClean: true,
+			lastReleaseFound: false
+		};
+		const commonGitDirectory = await git.revparse([`--path-format=absolute`, `--git-common-dir`]);
+		await withDirectoryLock(path.join(commonGitDirectory, `breakage-fetch.lock`), () => git.fetch([
+			`origin`,
+			`${latestReleaseTag$1}:${latestReleaseTag$1}`,
+			`--no-tags`,
+			`--no-write-fetch-head`
+		]));
+		releaseCommit = await git.revparse([`${latestReleaseTag$1}^{commit}`]);
+		mark?.(`fetched latest release tag`);
+	}
+	let productionFiles;
+	try {
+		productionFiles = (await git.raw([
+			`ls-tree`,
+			`-r`,
+			`--name-only`,
+			`-z`,
+			releaseCommit
+		])).split(`\0`).filter(Boolean);
+	} catch (thrown) {
+		mark?.(`failed to list production files`);
+		const message = thrown instanceof Error ? thrown.message : typeof thrown === `string` ? thrown : void 0;
+		return {
+			summary: `Failed to list production files${message ? `: ${message}` : `.`}`,
+			gitWasClean: true,
+			lastReleaseFound: true,
+			lastReleaseTag: latestReleaseTag$1,
+			testsWereFound: false
+		};
+	}
+	mark?.(`listed all files checked into git`);
+	const productionTestFiles = productionFiles.filter((file) => minimatch(file, testPattern));
+	mark?.(`filtered to public test files`);
+	const prepared = await withTestFileState(git, baseDirname, async (state) => {
+		if (!await state.isClean()) return {
+			summary: `The git repository must be clean to run this command.`,
+			gitWasClean: false
+		};
+		if (productionTestFiles.length === 0) return {
+			summary: `No tests were found matching the pattern "${testPattern}".`,
+			gitWasClean: true,
+			lastReleaseFound: true,
+			lastReleaseTag: latestReleaseTag$1,
+			testsWereFound: false
+		};
+		const restore = await state.replaceTests(releaseCommit, productionTestFiles);
+		mark?.(`restored public tests from latest release tag`);
+		return {
+			latestReleaseTag: latestReleaseTag$1,
+			productionTestFiles,
+			restore
+		};
+	});
+	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
+				});
+			});
+		});
+	} 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 };
+
+//# sourceMappingURL=breakage-B7dJsgcu.js.map