breakage 0.0.0-stage → 0.0.0

package/dist/breakage.$configPath.schema.json

@@ -0,0 +1,30 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"additionalProperties": false,
+	"type": "object",
+	"properties": {
+		"certifyCommand": {
+			"type": "string"
+		},
+		"testCommand": {
+			"type": "string"
+		},
+		"testPattern": {
+			"type": "string"
+		},
+		"baseDirname": {
+			"type": "string"
+		},
+		"tagPattern": {
+			"type": "string"
+		},
+		"verbose": {
+			"type": "boolean"
+		}
+	},
+	"required": [
+		"certifyCommand",
+		"testCommand",
+		"testPattern"
+	]
+}

package/dist/breakage.d.ts

@@ -0,0 +1,43 @@
+//#region src/breakage.d.ts
+export type BreakageOptions = {
+  tagPattern?: string | undefined;
+  testPattern: string;
+  testCommand: string;
+  certifyCommand: string;
+  baseDirname?: string;
+  verbose?: boolean | undefined;
+};
+export type BreakageOutcome = {
+  gitWasClean: false;
+} | {
+  gitWasClean: true;
+  lastReleaseFound: false;
+} | {
+  gitWasClean: true;
+  lastReleaseFound: true;
+  lastReleaseTag: string;
+  testsWereFound: false;
+} | {
+  gitWasClean: true;
+  lastReleaseFound: true;
+  lastReleaseTag: string;
+  testsWereFound: true;
+  testsFound: string[];
+  breakingChangesFound: false;
+} | {
+  gitWasClean: true;
+  lastReleaseFound: true;
+  lastReleaseTag: string;
+  testsWereFound: true;
+  testsFound: string[];
+  breakingChangesFound: true;
+  testResult: string;
+  breakingChangesCertified: boolean;
+  certificationStdout: string;
+  certificationStderr: string;
+};
+export declare function breakage({ tagPattern, testPattern, testCommand, certifyCommand, baseDirname, verbose }: BreakageOptions): Promise<BreakageOutcome & {
+  summary: string;
+}>;
+//#endregion
+//# sourceMappingURL=breakage.d.ts.map

package/dist/breakage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"breakage.d.ts","names":[],"sources":["../src/breakage.ts"],"mappings":";YAYY;EACX;EACA;EACA;EACA;EACA;EACA;;YAGW;EACP;;EAEF;EACA;;EAGA;EACA;EACA;EACA;;EAGA;EACA;EACA;EACA;EACA;EACA;;EAGA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;wBAGmB,WACrB,YACA,aACA,aACA,gBACA,aACA,WACE,kBAAkB,QAAQ;EAAoB"}

package/dist/breakage.help.schema.json

@@ -0,0 +1,6 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"additionalProperties": false,
+	"type": "object",
+	"properties": {}
+}

package/dist/breakage.js

@@ -0,0 +1 @@
+export { t as breakage } from "./breakage-D_nc-zEK.js";

package/dist/breakage.main.schema.json

@@ -0,0 +1,30 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"additionalProperties": false,
+	"type": "object",
+	"properties": {
+		"certifyCommand": {
+			"type": "string"
+		},
+		"testCommand": {
+			"type": "string"
+		},
+		"testPattern": {
+			"type": "string"
+		},
+		"baseDirname": {
+			"type": "string"
+		},
+		"tagPattern": {
+			"type": "string"
+		},
+		"verbose": {
+			"type": "boolean"
+		}
+	},
+	"required": [
+		"certifyCommand",
+		"testCommand",
+		"testPattern"
+	]
+}

package/dist/breakage.schema.schema.json

@@ -0,0 +1,10 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"additionalProperties": false,
+	"type": "object",
+	"properties": {
+		"outdir": {
+			"type": "string"
+		}
+	}
+}

package/dist/breakage.x.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+import { t as breakage } from "./breakage-D_nc-zEK.js";
+import * as path$1 from "node:path";
+import logger from "takua";
+import { inspect } from "node:util";
+import { type } from "arktype";
+import { cli, completionResponse, encapsulate, help, logWarnings, noOptions, optional, options, parseBooleanOption } from "comline";
+//#region src/breakage.x.ts
+const BREAKAGE_MANUAL = options(`Check for breaking changes in a package.`, type({
+	"tagPattern?": `string`,
+	testPattern: `string`,
+	testCommand: `string`,
+	certifyCommand: `string`,
+	"baseDirname?": `string`,
+	"verbose?": `boolean`
+}), {
+	tagPattern: {
+		aliases: [`tag-pattern`],
+		completion: { repeatable: false },
+		flag: `g`,
+		required: false,
+		description: `RegExp which, if found matched to a git tag, will be considered a release tag for your library.`,
+		example: `--tagPattern="my-library"`
+	},
+	testPattern: {
+		aliases: [`test-pattern`, `pattern`],
+		completion: { repeatable: false },
+		flag: `p`,
+		required: true,
+		description: `The pattern to match test files that test the public API of the library.`,
+		example: `--pattern="*__public.test.ts"`
+	},
+	testCommand: {
+		aliases: [`test-command`],
+		completion: { repeatable: false },
+		flag: `t`,
+		required: true,
+		description: `Complete bash command that runs the tests for the library's public API.`,
+		example: `--testCommand="npm run test"`
+	},
+	certifyCommand: {
+		aliases: [`certify-command`],
+		completion: { repeatable: false },
+		flag: `c`,
+		required: true,
+		description: `Complete bash command that determines whether a major version bump for your package is indicated in the workspace. Exit code 0 indicates that a major version bump is indicated, and exit code 1 indicates that no major version bump is indicated.`,
+		example: `--certifyCommand=\tsx scripts/certify-major-version-bump.node`
+	},
+	baseDirname: {
+		aliases: [`base-dir`, `base-dirname`],
+		completion: {
+			repeatable: false,
+			fileSystem: `directories`
+		},
+		flag: `d`,
+		required: false,
+		description: `The base directory to run the command from.`,
+		example: `--baseDirname=./packages/my-package`
+	},
+	verbose: {
+		completion: { repeatable: false },
+		flag: `v`,
+		required: false,
+		description: `Prints out more information about the process.`,
+		example: `--verbose`,
+		parse: parseBooleanOption
+	}
+});
+const SCHEMA_MANUAL = options(`Create a copy of the schema for configuring breakage.`, type({ "outdir?": `string` }), { outdir: {
+	aliases: [`out-dir`],
+	completion: {
+		repeatable: false,
+		fileSystem: `directories`
+	},
+	flag: `o`,
+	required: false,
+	description: `Directory to write the schema to.`,
+	example: `--outdir=./dist`
+} });
+const parse = cli({
+	cliName: `breakage`,
+	routes: optional({
+		help: null,
+		schema: null,
+		$configPath: null
+	}),
+	routeOptions: {
+		"": BREAKAGE_MANUAL,
+		$configPath: BREAKAGE_MANUAL,
+		help: noOptions(`Show usage.`),
+		schema: SCHEMA_MANUAL
+	},
+	positionalCompletions: { $configPath: { fileSystem: `files` } },
+	discoverConfigPath: (args) => {
+		if (args[0] === `help` || args[0] === `schema`) return;
+		return args[0] ?? path$1.join(process.cwd(), `breakage.config.json`);
+	}
+}, {
+	info: (message, ...data) => logger.info(`breakage`, message, data),
+	error: (message, ...data) => logger.error(`breakage`, message, data)
+});
+const completion = await completionResponse(parse.definition, process.argv);
+if (completion !== void 0) process.stdout.write(completion);
+else {
+	const { inputs, warnings, writeJsonSchema } = parse(process.argv);
+	logWarnings(warnings);
+	switch (inputs.case) {
+		case `help`:
+			console.log(help(parse.definition));
+			break;
+		case `schema`:
+			{
+				const { outdir } = inputs.opts;
+				writeJsonSchema(outdir ?? `.`);
+				process.stdout.write(`📝 Wrote json.schema.`);
+			}
+			break;
+		case ``:
+		case `$configPath`: {
+			const { returnValue } = await encapsulate(() => breakage(inputs.opts), {
+				console: true,
+				stdout: true
+			});
+			if (`testResult` in returnValue && returnValue.breakingChangesFound) process.stdout.write(returnValue.testResult);
+			if (`breakingChangesFound` in returnValue) {
+				if (returnValue.breakingChangesFound) {
+					if (returnValue.breakingChangesCertified) {
+						process.stdout.write(`👷 Breaking changes were found and certified.`);
+						process.exit(0);
+					} else {
+						process.stdout.write(`❌ Breaking changes were found, but not certified.`);
+						process.exit(1);
+					}
+				} else {
+					process.stdout.write(`✅ No breaking changes were found.`);
+					process.exit(0);
+				}
+			} else {
+				process.stdout.write("💥 Breakage failed to determine breaking changes.\n" + inspect(returnValue));
+				process.exit(2);
+			}
+		}
+	}
+}
+//#endregion
+export {};
+
+//# sourceMappingURL=breakage.x.js.map

package/dist/breakage.x.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"breakage.x.js","names":["path"],"sources":["../src/breakage.x.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport * as path from \"node:path\"\nimport { inspect } from \"node:util\"\n\nimport { type } from \"arktype\"\nimport type { OptionsGroup } from \"comline\"\nimport {\n\tcli,\n\tcompletionResponse,\n\tencapsulate,\n\thelp,\n\tlogWarnings,\n\tnoOptions,\n\toptional,\n\toptions,\n\tparseBooleanOption,\n} from \"comline\"\nimport logger from \"takua\"\n\nimport type { BreakageOptions } from \"./breakage.ts\"\nimport { breakage } from \"./breakage.ts\"\n\nconst BREAKAGE_MANUAL = options(\n\t`Check for breaking changes in a package.`,\n\ttype({\n\t\t\"tagPattern?\": `string`,\n\t\ttestPattern: `string`,\n\t\ttestCommand: `string`,\n\t\tcertifyCommand: `string`,\n\t\t\"baseDirname?\": `string`,\n\t\t\"verbose?\": `boolean`,\n\t}),\n\t{\n\t\ttagPattern: {\n\t\t\taliases: [`tag-pattern`],\n\t\t\tcompletion: { repeatable: false },\n\t\t\tflag: `g`,\n\t\t\trequired: false,\n\t\t\tdescription: `RegExp which, if found matched to a git tag, will be considered a release tag for your library.`,\n\t\t\texample: `--tagPattern=\"my-library\"`,\n\t\t},\n\t\ttestPattern: {\n\t\t\taliases: [`test-pattern`, `pattern`],\n\t\t\tcompletion: { repeatable: false },\n\t\t\tflag: `p`,\n\t\t\trequired: true,\n\t\t\tdescription: `The pattern to match test files that test the public API of the library.`,\n\t\t\texample: `--pattern=\"*__public.test.ts\"`,\n\t\t},\n\t\ttestCommand: {\n\t\t\taliases: [`test-command`],\n\t\t\tcompletion: { repeatable: false },\n\t\t\tflag: `t`,\n\t\t\trequired: true,\n\t\t\tdescription: `Complete bash command that runs the tests for the library's public API.`,\n\t\t\texample: `--testCommand=\"npm run test\"`,\n\t\t},\n\t\tcertifyCommand: {\n\t\t\taliases: [`certify-command`],\n\t\t\tcompletion: { repeatable: false },\n\t\t\tflag: `c`,\n\t\t\trequired: true,\n\t\t\tdescription: `Complete bash command that determines whether a major version bump for your package is indicated in the workspace. Exit code 0 indicates that a major version bump is indicated, and exit code 1 indicates that no major version bump is indicated.`,\n\t\t\texample: `--certifyCommand=\\tsx scripts/certify-major-version-bump.node`,\n\t\t},\n\t\tbaseDirname: {\n\t\t\taliases: [`base-dir`, `base-dirname`],\n\t\t\tcompletion: { repeatable: false, fileSystem: `directories` },\n\t\t\tflag: `d`,\n\t\t\trequired: false,\n\t\t\tdescription: `The base directory to run the command from.`,\n\t\t\texample: `--baseDirname=./packages/my-package`,\n\t\t},\n\t\tverbose: {\n\t\t\tcompletion: { repeatable: false },\n\t\t\tflag: `v`,\n\t\t\trequired: false,\n\t\t\tdescription: `Prints out more information about the process.`,\n\t\t\texample: `--verbose`,\n\t\t\tparse: parseBooleanOption,\n\t\t},\n\t},\n) satisfies OptionsGroup<BreakageOptions>\n\nconst SCHEMA_MANUAL = options(\n\t`Create a copy of the schema for configuring breakage.`,\n\ttype({ \"outdir?\": `string` }),\n\t{\n\t\toutdir: {\n\t\t\taliases: [`out-dir`],\n\t\t\tcompletion: { repeatable: false, fileSystem: `directories` },\n\t\t\tflag: `o`,\n\t\t\trequired: false,\n\t\t\tdescription: `Directory to write the schema to.`,\n\t\t\texample: `--outdir=./dist`,\n\t\t},\n\t},\n)\n\nconst parse = cli(\n\t{\n\t\tcliName: `breakage`,\n\t\troutes: optional({ help: null, schema: null, $configPath: null }),\n\t\trouteOptions: {\n\t\t\t\"\": BREAKAGE_MANUAL,\n\t\t\t$configPath: BREAKAGE_MANUAL,\n\t\t\thelp: noOptions(`Show usage.`),\n\t\t\tschema: SCHEMA_MANUAL,\n\t\t},\n\t\tpositionalCompletions: { $configPath: { fileSystem: `files` } },\n\t\tdiscoverConfigPath: (args: readonly string[]) => {\n\t\t\tif (args[0] === `help` || args[0] === `schema`) {\n\t\t\t\treturn\n\t\t\t}\n\t\t\tconst configPath =\n\t\t\t\targs[0] ?? path.join(process.cwd(), `breakage.config.json`)\n\t\t\treturn configPath\n\t\t},\n\t},\n\t{\n\t\tinfo: (message, ...data) => logger.info(`breakage`, message, data),\n\t\terror: (message, ...data) => logger.error(`breakage`, message, data),\n\t},\n)\n\nconst completion = await completionResponse(parse.definition, process.argv)\nif (completion !== undefined) {\n\tprocess.stdout.write(completion)\n} else {\n\tconst { inputs, warnings, writeJsonSchema } = parse(process.argv)\n\tlogWarnings(warnings)\n\n\tswitch (inputs.case) {\n\t\tcase `help`:\n\t\t\tconsole.log(help(parse.definition))\n\t\t\tbreak\n\t\tcase `schema`:\n\t\t\t{\n\t\t\t\tconst { outdir } = inputs.opts\n\t\t\t\twriteJsonSchema(outdir ?? `.`)\n\t\t\t\tprocess.stdout.write(`📝 Wrote json.schema.`)\n\t\t\t}\n\t\t\tbreak\n\t\tcase ``:\n\t\tcase `$configPath`: {\n\t\t\tconst { returnValue } = await encapsulate(() => breakage(inputs.opts), {\n\t\t\t\tconsole: true,\n\t\t\t\tstdout: true,\n\t\t\t})\n\t\t\tif (`testResult` in returnValue && returnValue.breakingChangesFound) {\n\t\t\t\tprocess.stdout.write(returnValue.testResult)\n\t\t\t}\n\t\t\tif (`breakingChangesFound` in returnValue) {\n\t\t\t\tif (returnValue.breakingChangesFound) {\n\t\t\t\t\tif (returnValue.breakingChangesCertified) {\n\t\t\t\t\t\tprocess.stdout.write(\n\t\t\t\t\t\t\t`👷 Breaking changes were found and certified.`,\n\t\t\t\t\t\t)\n\t\t\t\t\t\tprocess.exit(0)\n\t\t\t\t\t} else {\n\t\t\t\t\t\tprocess.stdout.write(\n\t\t\t\t\t\t\t`❌ Breaking changes were found, but not certified.`,\n\t\t\t\t\t\t)\n\t\t\t\t\t\tprocess.exit(1)\n\t\t\t\t\t}\n\t\t\t\t} else {\n\t\t\t\t\tprocess.stdout.write(`✅ No breaking changes were found.`)\n\t\t\t\t\tprocess.exit(0)\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tprocess.stdout.write(\n\t\t\t\t\t`💥 Breakage failed to determine breaking changes.` +\n\t\t\t\t\t\t`\\n` +\n\t\t\t\t\t\tinspect(returnValue),\n\t\t\t\t)\n\t\t\t\tprocess.exit(2)\n\t\t\t}\n\t\t}\n\t}\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,52 @@
 {
-  "name": "breakage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "breakage",
+	"version": "0.0.0",
+	"description": "Run yesterday’s tests against tomorrow’s release.",
+	"homepage": "https://github.com/jeremybanka/breakage#readme",
+	"bugs": "https://github.com/jeremybanka/breakage/issues",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/jeremybanka/breakage.git",
+		"directory": "packages/breakage"
+	},
+	"license": "MPL-2.0",
+	"author": {
+		"name": "Jeremy Banka",
+		"email": "hello@jeremybanka.com"
+	},
+	"type": "module",
+	"main": "dist/breakage.js",
+	"types": "dist/breakage.d.ts",
+	"bin": {
+		"breakage": "./dist/breakage.x.js"
+	},
+	"files": [
+		"dist",
+		"src"
+	],
+	"scripts": {
+		"build": "tsdown && pnpm run schema",
+		"check": "pnpm run check:tsc",
+		"check:tsc": "tsc --noEmit",
+		"postversion": "dprint fmt package.json",
+		"schema": "bun src/breakage.x.ts --outdir=dist -- schema",
+		"pretest": "pnpm run build",
+		"test": "bun test -- ./__tests__",
+		"test:watch": "bun test --watch -- ./__tests__"
+	},
+	"dependencies": {
+		"arktype": "2.2.7",
+		"comline": "0.9.0",
+		"minimatch": "10.2.6",
+		"simple-git": "4.0.2",
+		"takua": "0.2.3"
+	},
+	"devDependencies": {
+		"@types/bun": "npm:bun-types@1.4.2",
+		"tsdown": "0.23.0",
+		"typescript": "7.0.2"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/src/breakage.ts

@@ -0,0 +1,238 @@
+import { exec } from "node:child_process"
+import path from "node:path"
+
+import { minimatch } from "minimatch"
+import { simpleGit } from "simple-git"
+import type { Chronicle } from "takua"
+import logger from "takua"
+
+import { withDirectoryLock } from "./directory-lock.ts"
+import { latestReleaseTag as selectLatestReleaseTag } from "./release-tag.ts"
+import { withTestFileState } from "./test-file-state.ts"
+
+export type BreakageOptions = {
+	tagPattern?: string | undefined
+	testPattern: string
+	testCommand: string
+	certifyCommand: string
+	baseDirname?: string
+	verbose?: boolean | undefined
+}
+
+export type BreakageOutcome =
+	| { gitWasClean: false }
+	| {
+			gitWasClean: true
+			lastReleaseFound: false
+	  }
+	| {
+			gitWasClean: true
+			lastReleaseFound: true
+			lastReleaseTag: string
+			testsWereFound: false
+	  }
+	| {
+			gitWasClean: true
+			lastReleaseFound: true
+			lastReleaseTag: string
+			testsWereFound: true
+			testsFound: string[]
+			breakingChangesFound: false
+	  }
+	| {
+			gitWasClean: true
+			lastReleaseFound: true
+			lastReleaseTag: string
+			testsWereFound: true
+			testsFound: string[]
+			breakingChangesFound: true
+			testResult: string
+			breakingChangesCertified: boolean
+			certificationStdout: string
+			certificationStderr: string
+	  }
+
+export async function breakage({
+	tagPattern,
+	testPattern,
+	testCommand,
+	certifyCommand,
+	baseDirname = process.cwd(),
+	verbose = false,
+}: BreakageOptions): Promise<BreakageOutcome & { summary: string }> {
+	let mark: Chronicle[`mark`] | undefined
+	let logMarks: Chronicle[`logMarks`] | undefined
+	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,
+		}
+	}
+	const tagsRemote = await git.listRemote([`--tags`, `origin`])
+
+	mark?.(`list remote tags`)
+	const latestReleaseTag = selectLatestReleaseTag(tagsRemote, tagPattern)
+	mark?.(`found latest release tag`)
+	if (!latestReleaseTag) {
+		return {
+			summary: `No tags found matching the pattern "${tagPattern}".`,
+			gitWasClean: true,
+			lastReleaseFound: false,
+		} as const
+	}
+	const commonGitDirectory = await git.revparse([
+		`--path-format=absolute`,
+		`--git-common-dir`,
+	])
+	await withDirectoryLock(
+		path.join(commonGitDirectory, `breakage-fetch.lock`),
+		() =>
+			git.fetch([
+				`origin`,
+				`${latestReleaseTag}:${latestReleaseTag}`,
+				`--no-tags`,
+				`--no-write-fetch-head`,
+			]),
+	)
+
+	mark?.(`fetched latest release tag`)
+
+	let productionFiles: string[]
+	try {
+		productionFiles = (
+			await git.raw([`ls-tree`, `-r`, `--name-only`, `-z`, latestReleaseTag])
+		)
+			.split(`\0`)
+			.filter(Boolean)
+	} catch (thrown) {
+		mark?.(`failed to list production files`)
+		const message =
+			thrown instanceof Error
+				? thrown.message
+				: typeof thrown === `string`
+					? thrown
+					: undefined
+		const summary = `Failed to list production files${
+			message ? `: ${message}` : `.`
+		}`
+		return {
+			summary,
+			gitWasClean: true,
+			lastReleaseFound: true,
+			lastReleaseTag: latestReleaseTag,
+			testsWereFound: false,
+		} as const
+	}
+	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,
+			} as const
+		}
+
+		if (productionTestFiles.length === 0) {
+			return {
+				summary: `No tests were found matching the pattern "${testPattern}".`,
+				gitWasClean: true,
+				lastReleaseFound: true,
+				lastReleaseTag: latestReleaseTag,
+				testsWereFound: false,
+			} as const
+		}
+		const restore = await state.replaceTests(
+			latestReleaseTag,
+			productionTestFiles,
+		)
+		mark?.(`restored public tests from latest release tag`)
+		return { latestReleaseTag, productionTestFiles, restore }
+	})
+	if (prepared.summary !== undefined) return prepared
+	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
+	} finally {
+		await restore()
+		mark?.(`restored original public tests`)
+		logMarks?.()
+	}
+}