breakage 0.8.5 → 0.9.1

package/src/breakage.ts

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

package/src/breakage.x.ts

@@ -1,9 +1,8 @@
 #!/usr/bin/env node
 
+import path from "node:path"
 import { inspect } from "node:util"
 
-import { type } from "arktype"
-import type { OptionsGroup } from "comline"
 import {
 	cli,
 	completionResponse,
@@ -18,28 +17,36 @@ import {
 } from "comline"
 import logger from "takua"
 
-import type { BreakageOptions } from "./breakage.ts"
-import { breakage, breakagePrelude } from "./breakage.ts"
 import {
 	defaultConfig,
-	npmCheckManual,
-	npmTestManual,
-	runNpmCli,
-} from "./npm/cli.ts"
+	configPath,
+	resolveConfig,
+	configSchema,
+	configFields,
+} from "./config.ts"
+import { breakage, breakagePrelude } from "./breakage.ts"
+import { errorMessage } from "./task.ts"
+import { npmCheckManual, npmTestManual, runNpmCli } from "./npm/cli.ts"
+import {
+	npmPlanManual,
+	npmExecuteManual,
+	npmVerifyManual,
+	runNpmMatrixCli,
+} from "./npm/matrix-cli.ts"
+
+// Either command spelling can override the other spelling in a config file.
+const commandOverrides = new Set<`test` | `testCommand`>()
 
 const BREAKAGE_MANUAL = options(
 	`Check for breaking changes in a package.`,
-	type({
-		"tagPattern?": `string`,
-		"baselineFile?": `string`,
-		testPattern: `string`,
-		testCommand: `string`,
-		certifyCommand: `string`,
-		"baseDirname?": `string`,
-		"verbose?": `boolean`,
-	}),
+	configSchema,
 	{
+		release: { configOnly: true },
+		npm: { configOnly: true },
+		npmMatrix: { configOnly: true },
+		out: { configOnly: true },
 		tagPattern: {
+			schema: configFields.tagPattern,
 			aliases: [`tag-pattern`],
 			completion: { repeatable: false },
 			flag: `g`,
@@ -48,6 +55,7 @@ const BREAKAGE_MANUAL = options(
 			example: `--tagPattern="my-library"`,
 		},
 		baselineFile: {
+			schema: configFields.baselineFile,
 			aliases: [`baseline-file`],
 			completion: { repeatable: false, fileSystem: `files` },
 			required: false,
@@ -55,30 +63,41 @@ const BREAKAGE_MANUAL = options(
 			example: `--baseline-file=.breakage/baseline.json`,
 		},
 		testPattern: {
+			schema: configFields.testPattern,
 			aliases: [`test-pattern`, `pattern`],
 			completion: { repeatable: false },
 			flag: `p`,
-			required: true,
+			required: false,
 			description: `The pattern to match test files that test the public API of the library.`,
 			example: `--pattern="*__public.test.ts"`,
 		},
 		testCommand: {
+			parse: (value) => {
+				commandOverrides.add(`testCommand`)
+				return value
+			},
+			schema: configFields.testCommand,
 			aliases: [`test-command`],
 			completion: { repeatable: false },
 			flag: `t`,
-			required: true,
+			required: false,
 			description: `Complete bash command that runs the tests for the library's public API.`,
 			example: `--testCommand="npm run test"`,
 		},
-		certifyCommand: {
-			aliases: [`certify-command`],
+		test: {
+			parse: (value) => {
+				commandOverrides.add(`test`)
+				return value
+			},
+			schema: configFields.test,
 			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`,
+			required: false,
+			description: `Shell command running the restored public contracts.`,
+			example: `--test="npm run test:public"`,
 		},
 		baseDirname: {
+			parse: (value) => path.resolve(value),
+			schema: configFields.baseDirname,
 			aliases: [`base-dir`, `base-dirname`],
 			completion: { repeatable: false, fileSystem: `directories` },
 			flag: `d`,
@@ -87,6 +106,7 @@ const BREAKAGE_MANUAL = options(
 			example: `--baseDirname=./packages/my-package`,
 		},
 		verbose: {
+			schema: configFields.verbose,
 			completion: { repeatable: false },
 			flag: `v`,
 			required: false,
@@ -95,20 +115,11 @@ const BREAKAGE_MANUAL = options(
 			parse: parseBooleanOption,
 		},
 	},
-) satisfies OptionsGroup<BreakageOptions>
+)
 
 const PRELUDE_MANUAL = options(
 	`Resolve and fetch the release baseline for a cacheable compatibility check.`,
-	type({
-		"tagPattern?": `string`,
-		"baseDirname?": `string`,
-		"out?": `string`,
-		"testPattern?": `string`,
-		"testCommand?": `string`,
-		"certifyCommand?": `string`,
-		"baselineFile?": `string`,
-		"verbose?": `boolean`,
-	}),
+	configSchema,
 	{
 		...BREAKAGE_MANUAL.optionConfigs,
 		testPattern: {
@@ -119,11 +130,8 @@ const PRELUDE_MANUAL = options(
 			...BREAKAGE_MANUAL.optionConfigs.testCommand,
 			required: false,
 		},
-		certifyCommand: {
-			...BREAKAGE_MANUAL.optionConfigs.certifyCommand,
-			required: false,
-		},
 		out: {
+			schema: configFields.out,
 			completion: { repeatable: false, fileSystem: `files` },
 			required: false,
 			description: `Gitignored snapshot path relative to the base directory (default: .breakage/baseline.json).`,
@@ -132,30 +140,27 @@ const PRELUDE_MANUAL = options(
 	},
 )
 
-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`,
-		},
-	},
-)
-
+let loadedConfigPath: string | undefined
 const parse = cli(
 	{
 		cliName: `breakage`,
+		discoverConfigPath: (segments: readonly string[]) => {
+			if (segments[0] === `help` || segments[0] === `npm`) return undefined
+			const explicit = segments[0] === `prelude` ? segments[1] : segments[0]
+			loadedConfigPath = configPath(
+				explicit ?? defaultConfig(process.cwd()),
+				explicit !== undefined,
+			)
+			return loadedConfigPath
+		},
 		routes: optional({
 			help: null,
-			schema: null,
 			npm: optional({
 				help: null,
 				check: null,
+				plan: null,
+				execute: required({ $id: null }),
+				verify: null,
 				test: optional({ $peer: required({ $range: null }) }),
 			}),
 			prelude: optional({ $configPath: null }),
@@ -165,10 +170,12 @@ const parse = cli(
 			"": BREAKAGE_MANUAL,
 			$configPath: BREAKAGE_MANUAL,
 			help: noOptions(`Show usage.`),
-			schema: SCHEMA_MANUAL,
 			npm: noOptions(`Show npm compatibility commands.`),
 			"npm/help": noOptions(`Show npm compatibility commands.`),
 			"npm/check": npmCheckManual,
+			"npm/plan": npmPlanManual,
+			"npm/execute/$id": npmExecuteManual,
+			"npm/verify": npmVerifyManual,
 			"npm/test": npmTestManual,
 			"npm/test/$peer/$range": npmTestManual,
 			prelude: PRELUDE_MANUAL,
@@ -178,15 +185,6 @@ const parse = cli(
 			$configPath: { fileSystem: `files` },
 			"prelude/$configPath": { fileSystem: `files` },
 		},
-		discoverConfigPath: (args: readonly string[]) => {
-			if (args[0] === `help` || args[0] === `schema` || args[0] === `npm`) {
-				return
-			}
-			const configPath =
-				(args[0] === `prelude` ? args[1] : args[0]) ??
-				defaultConfig(process.cwd())
-			return configPath
-		},
 	},
 	{
 		info: (message, ...data) => logger.info(`breakage`, message, data),
@@ -198,74 +196,123 @@ const completion = await completionResponse(parse.definition, process.argv)
 if (completion !== undefined) {
 	process.stdout.write(completion)
 } else {
-	const { inputs, warnings, writeJsonSchema } = parse(process.argv)
-	logWarnings(warnings)
+	try {
+		const { inputs, warnings } = await parse.async(process.argv)
+		logWarnings(warnings)
+		if (
+			process.argv
+				.slice(2)
+				.some((arg) =>
+					/^(?:--certifyCommand|--certify-command|-c)(?:=|$)/.test(arg),
+				)
+		)
+			throw new Error(
+				`certifyCommand was removed. Configure release.resolveDelta and release.policy instead.`,
+			)
 
-	switch (inputs.case) {
-		case `npm`:
-		case `npm/help`:
-		case `help`:
-			console.log(help(parse.definition))
-			break
-		case `npm/check`:
-			process.exitCode = await runNpmCli(`check`, inputs.opts)
-			break
-		case `npm/test`:
-			process.exitCode = await runNpmCli(`test`, inputs.opts)
-			break
-		case `npm/test/$peer/$range`:
-			process.exitCode = await runNpmCli(`test`, inputs.opts, inputs.params)
-			break
-		case `schema`:
-			{
-				const { outdir } = inputs.opts
-				writeJsonSchema(outdir ?? `.`)
-				process.stdout.write(`📝 Wrote json.schema.`)
-			}
-			break
-		case `prelude`:
-		case `prelude/$configPath`: {
-			const baseline = await breakagePrelude({
-				...inputs.opts,
-				out: inputs.opts.out ?? `.breakage/baseline.json`,
-			})
-			process.stdout.write(`Pinned ${baseline.ref} at ${baseline.commit}.\n`)
-			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)
+		switch (inputs.case) {
+			case `npm`:
+			case `npm/help`:
+			case `help`:
+				console.log(help(parse.definition))
+				break
+			case `npm/check`:
+				process.exitCode = await runNpmCli(`check`, inputs.opts)
+				break
+			case `npm/plan`:
+				process.exitCode = await runNpmMatrixCli(`plan`, inputs.opts)
+				break
+			case `npm/execute/$id`:
+				process.exitCode = await runNpmMatrixCli(
+					`execute`,
+					inputs.opts,
+					inputs.params.id,
+				)
+				break
+			case `npm/verify`:
+				process.exitCode = await runNpmMatrixCli(`verify`, inputs.opts)
+				break
+			case `npm/test`:
+				process.exitCode = await runNpmCli(`test`, inputs.opts)
+				break
+			case `npm/test/$peer/$range`:
+				process.exitCode = await runNpmCli(`test`, inputs.opts, inputs.params)
+				break
+			case `prelude`:
+			case `prelude/$configPath`: {
+				const config = resolveConfig(inputs.opts, loadedConfigPath)
+				const baseline = await breakagePrelude({
+					...config,
+					out: config.out ?? `.breakage/baseline.json`,
+				})
+				process.stdout.write(`Pinned ${baseline.ref} at ${baseline.commit}.\n`)
+				break
 			}
-			if (`breakingChangesFound` in returnValue) {
-				if (returnValue.breakingChangesFound) {
-					if (returnValue.breakingChangesCertified) {
-						process.stdout.write(
-							`👷 Breaking changes were found and certified.`,
-						)
-						process.exit(0)
+			case ``:
+			case `$configPath`: {
+				const merged = resolveConfig(inputs.opts, loadedConfigPath)
+				if (
+					commandOverrides.has(`testCommand`) &&
+					!commandOverrides.has(`test`)
+				)
+					delete merged.test
+				if (
+					commandOverrides.has(`test`) &&
+					!commandOverrides.has(`testCommand`)
+				)
+					delete merged.testCommand
+				if (!merged.testPattern)
+					throw new Error(`required arguments were not provided: testPattern.`)
+				const { returnValue } = await encapsulate(
+					() =>
+						breakage({
+							...merged,
+							testPattern: merged.testPattern!,
+						}),
+					{
+						console: true,
+						stdout: true,
+					},
+				)
+				if (`release` in returnValue && returnValue.release) {
+					const { previousVersion, version, delta, breaking } =
+						returnValue.release
+					process.stdout.write(
+						`Release: ${previousVersion} → ${version} (${delta}; ${breaking ? `breaking` : `compatible`}).\n`,
+					)
+				}
+				if (`testResult` in returnValue && returnValue.breakingChangesFound) {
+					process.stdout.write(returnValue.testResult)
+				}
+				if (`breakingChangesFound` in returnValue) {
+					if (returnValue.breakingChangesFound) {
+						if (returnValue.release?.breaking) {
+							process.stdout.write(
+								`👷 Breaking changes are covered by the breaking release.`,
+							)
+							process.exit(0)
+						} else {
+							process.stdout.write(
+								`❌ Breaking changes require a breaking release.`,
+							)
+							process.exit(1)
+						}
 					} else {
-						process.stdout.write(
-							`❌ Breaking changes were found, but not certified.`,
-						)
-						process.exit(1)
+						process.stdout.write(`✅ No breaking changes were found.`)
+						process.exit(0)
 					}
 				} else {
-					process.stdout.write(`✅ No breaking changes were found.`)
-					process.exit(0)
+					process.stdout.write(
+						`💥 Breakage failed to determine breaking changes.` +
+							`\n` +
+							inspect(returnValue),
+					)
+					process.exit(2)
 				}
-			} else {
-				process.stdout.write(
-					`💥 Breakage failed to determine breaking changes.` +
-						`\n` +
-						inspect(returnValue),
-				)
-				process.exit(2)
 			}
 		}
+	} catch (error) {
+		process.stderr.write(`Breakage setup error: ${errorMessage(error)}\n`)
+		process.exitCode = 2
 	}
 }