breakage 0.8.4 → 0.9.0

package/src/breakage.x.ts

@@ -1,10 +1,8 @@
 #!/usr/bin/env node
 
-import * as path from "node:path"
+import path from "node:path"
 import { inspect } from "node:util"
 
-import { type } from "arktype"
-import type { OptionsGroup } from "comline"
 import {
 	cli,
 	completionResponse,
@@ -15,25 +13,33 @@ import {
 	optional,
 	options,
 	parseBooleanOption,
+	required,
 } from "comline"
 import logger from "takua"
 
-import type { BreakageOptions } from "./breakage.ts"
+import {
+	defaultConfig,
+	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"
+
+// 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 },
+		out: { configOnly: true },
 		tagPattern: {
+			schema: configFields.tagPattern,
 			aliases: [`tag-pattern`],
 			completion: { repeatable: false },
 			flag: `g`,
@@ -42,6 +48,7 @@ const BREAKAGE_MANUAL = options(
 			example: `--tagPattern="my-library"`,
 		},
 		baselineFile: {
+			schema: configFields.baselineFile,
 			aliases: [`baseline-file`],
 			completion: { repeatable: false, fileSystem: `files` },
 			required: false,
@@ -49,30 +56,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`,
@@ -81,6 +99,7 @@ const BREAKAGE_MANUAL = options(
 			example: `--baseDirname=./packages/my-package`,
 		},
 		verbose: {
+			schema: configFields.verbose,
 			completion: { repeatable: false },
 			flag: `v`,
 			required: false,
@@ -89,20 +108,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: {
@@ -113,11 +123,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).`,
@@ -126,27 +133,26 @@ 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,
+				test: optional({ $peer: required({ $range: null }) }),
+			}),
 			prelude: optional({ $configPath: null }),
 			$configPath: null,
 		}),
@@ -154,7 +160,11 @@ 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/test": npmTestManual,
+			"npm/test/$peer/$range": npmTestManual,
 			prelude: PRELUDE_MANUAL,
 			"prelude/$configPath": PRELUDE_MANUAL,
 		},
@@ -162,15 +172,6 @@ const parse = cli(
 			$configPath: { fileSystem: `files` },
 			"prelude/$configPath": { fileSystem: `files` },
 		},
-		discoverConfigPath: (args: readonly string[]) => {
-			if (args[0] === `help` || args[0] === `schema`) {
-				return
-			}
-			const configPath =
-				(args[0] === `prelude` ? args[1] : args[0]) ??
-				path.join(process.cwd(), `breakage.config.json`)
-			return configPath
-		},
 	},
 	{
 		info: (message, ...data) => logger.info(`breakage`, message, data),
@@ -182,63 +183,110 @@ 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 `help`:
-			console.log(help(parse.definition))
-			break
-		case `schema`:
-			{
-				const { outdir } = inputs.opts
-				writeJsonSchema(outdir ?? `.`)
-				process.stdout.write(`📝 Wrote json.schema.`)
+		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 `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
 			}
-			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)
-			}
-			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
 	}
 }

package/src/changesets.ts

@@ -0,0 +1,51 @@
+import { assembleReleasePlan } from "@changesets/assemble-release-plan"
+import { readConfig } from "@changesets/config"
+import { readPreState } from "@changesets/pre"
+import { readChangesets } from "@changesets/read"
+import { getPackages } from "@manypkg/get-packages"
+
+import {
+	versionTransition,
+	type ReleaseDeltaContext,
+	type VersionTransition,
+} from "./release.ts"
+
+/** Read the actual Changesets plan, including dependent bumps and prerelease state. */
+export async function readChangesetsReleasePlan(
+	directory: string = process.cwd(),
+): Promise<ReadonlyMap<string, string>> {
+	const packages = await getPackages(directory)
+	const root = packages.rootDir
+	const { config, errors } = await readConfig(root, packages)
+	if (errors) throw new Error(errors.join(`\n`))
+	const [changesets, preState] = await Promise.all([
+		readChangesets(root),
+		readPreState(root),
+	])
+	const plan = assembleReleasePlan(changesets, packages, config, preState)
+	return new Map(
+		plan.releases.flatMap(({ name, newVersion }) =>
+			newVersion === undefined ? [] : [[name, newVersion] as const],
+		),
+	)
+}
+
+/** Compare the selected baseline (or current manifest) with the planned or versioned release. */
+export function changesetsReleaseDelta({
+	directory,
+}: { directory?: string } = {}): (
+	context: ReleaseDeltaContext,
+) => Promise<VersionTransition> {
+	return async ({
+		packageName,
+		packageDirectory,
+		currentVersion,
+		baseline,
+	}) => {
+		const version =
+			(await readChangesetsReleasePlan(directory ?? packageDirectory)).get(
+				packageName,
+			) ?? currentVersion
+		return versionTransition(baseline?.version ?? currentVersion, version)
+	}
+}

package/src/config.ts

@@ -0,0 +1,128 @@
+import { existsSync } from "node:fs"
+import path from "node:path"
+
+import { type } from "arktype"
+import { cli, options, type ConfigInput } from "comline"
+
+import { npmConfigSchema } from "./npm/config.ts"
+import {
+	releaseSchema,
+	validateRelease,
+	rejectCertificationOptions,
+} from "./release.ts"
+
+// Reuse these field schemas for CLI metadata even though hooks cannot become JSON Schema.
+export const configFields = {
+	tagPattern: type(`string`),
+	baselineFile: type(`string`),
+	testPattern: type(`string`),
+	testCommand: type(`string`),
+	test: type(`string`),
+	baseDirname: type(`string`),
+	verbose: type(`boolean`),
+	out: type(`string`),
+}
+export const configSchema = type({
+	"+": `reject`,
+	"tagPattern?": configFields.tagPattern.or(`undefined`),
+	"baselineFile?": configFields.baselineFile.or(`undefined`),
+	"testPattern?": configFields.testPattern,
+	"testCommand?": configFields.testCommand,
+	"test?": configFields.test,
+	"baseDirname?": configFields.baseDirname,
+	"verbose?": configFields.verbose.or(`undefined`),
+	"out?": configFields.out,
+	"release?": releaseSchema,
+	"npm?": npmConfigSchema,
+})
+
+/** The complete config, with no fields exposed to argv by this loader. */
+export const configOptions = options(`Breakage configuration`, configSchema, {
+	tagPattern: { configOnly: true },
+	baselineFile: { configOnly: true },
+	testPattern: { configOnly: true },
+	testCommand: { configOnly: true },
+	test: { configOnly: true },
+	baseDirname: { configOnly: true },
+	verbose: { configOnly: true },
+	out: { configOnly: true },
+	release: { configOnly: true },
+	npm: { configOnly: true },
+})
+export type BreakageConfig = ConfigInput<typeof configOptions>
+
+/** Share the root release model with npm checks unless they supply their own. */
+export function defineConfig(config: BreakageConfig): BreakageConfig {
+	if (config && typeof config === `object`) {
+		rejectCertificationOptions(config)
+		if (config.npm) rejectCertificationOptions(config.npm)
+		if (config.release !== undefined) validateRelease(config.release)
+		if (config.npm?.release !== undefined) validateRelease(config.npm.release)
+	}
+	configSchema.assert(config)
+	return {
+		...config,
+		...(config.npm
+			? {
+					npm: {
+						...config.npm,
+						...(config.release && config.npm.release === undefined
+							? { release: config.release }
+							: {}),
+					},
+				}
+			: {}),
+	}
+}
+
+export function defaultConfig(directory: string): string {
+	const filename = path.join(directory, `breakage.config.ts`)
+	if (
+		!existsSync(filename) &&
+		existsSync(path.join(directory, `breakage.config.json`))
+	)
+		throw new Error(
+			`JSON configuration was removed. Migrate breakage.config.json to breakage.config.ts.`,
+		)
+	return filename
+}
+
+/** Comline ignores absent discovered files; explicit paths must exist. */
+export function configPath(filename: string, required = true): string {
+	const absolute = path.resolve(filename)
+	if (path.extname(absolute) !== `.ts`)
+		throw new Error(
+			`Configuration must be a .ts module with a default export; JSON configuration was removed.`,
+		)
+	if (required && !existsSync(absolute))
+		throw new Error(`Configuration file does not exist: ${absolute}`)
+	return absolute
+}
+
+/** Apply application semantics after Comline validates and merges configuration. */
+export function resolveConfig(
+	config: BreakageConfig,
+	filename?: string,
+): BreakageConfig {
+	return {
+		...defineConfig(config),
+		baseDirname: path.resolve(
+			filename ? path.dirname(filename) : process.cwd(),
+			config.baseDirname ?? `.`,
+		),
+	}
+}
+
+/** Use Comline's module loading and full-schema validation for programmatic and npm consumers. */
+export async function loadConfig(filename: string): Promise<BreakageConfig> {
+	const absolute = configPath(filename)
+	const parse = cli({
+		cliName: `breakage`,
+		routeOptions: { "": configOptions },
+		discoverConfigPath: () => absolute,
+	})
+	return resolveConfig(
+		(await parse.async([process.execPath, `breakage`])).inputs.opts,
+		absolute,
+	)
+}