breakage 0.8.5 → 0.9.1

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,131 @@
+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 { npmMatrixConfigSchema } from "./npm/matrix-model.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,
+	"npmMatrix?": npmMatrixConfigSchema,
+})
+
+/** 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 },
+	npmMatrix: { 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,
+	)
+}

package/src/npm/check.ts

@@ -1,8 +1,12 @@
 import path from "node:path"
 
-import semver from "semver"
-
-import { command, errorMessage } from "./command.ts"
+import {
+	resolveReleaseDelta,
+	versionDelta,
+	type ReleaseDeltaContext,
+	type VersionTransition,
+} from "../release.ts"
+import { command, errorMessage } from "../task.ts"
 import { validateConfig, validatePeerRanges } from "./config.ts"
 import {
 	checkCandidatePeers,
@@ -20,13 +24,12 @@ import {
 	normalizeWorkspacePeers,
 	readManifest,
 } from "./manifest.ts"
-import { intent, previousManifest, supportChanges } from "./release.ts"
+import { releaseVersion, previousManifest, supportChanges } from "./release.ts"
 import type {
 	NpmConfig,
 	NpmReport,
 	NpmRepresentativeResult,
 	NpmTestSelection,
-	ReleaseIntent,
 } from "./types.ts"
 
 async function checkSupport(
@@ -44,36 +47,28 @@ async function checkSupport(
 		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`)
+		const evidence = config.release
+			? await resolveReleaseDelta(config.release, {
+					packageName: manifest.name,
+					packageDirectory: base,
+					currentVersion: manifest.version,
+					baseline: { version: previous.version },
+				})
+			: undefined
+		if (evidence === undefined)
 			return {
 				status: `end-of-support`,
 				previousVersion: previous.version,
 				changes,
 			}
-		if (!semver.gt(evidence.version, previous.version))
-			throw new Error(
-				`The intended release must be newer than baseline ${previous.version}.`,
-			)
-		const release = {
-			version: evidence.version,
-			delta: semver.diff(previous.version, evidence.version) ?? `none`,
-		}
-		const certified = config.certifyBreaking
-			? await config.certifyBreaking({
-					previousVersion: previous.version,
-					release,
-					changes,
-				})
-			: false
-		if (typeof certified !== `boolean`)
-			throw new Error(`certifyBreaking must return a boolean.`)
+		const release = versionDelta(
+			evidence.previousVersion,
+			evidence.version,
+			config.release?.policy,
+		)
+
 		return {
-			status: certified ? `certified` : `end-of-support`,
+			status: release.breaking ? `breaking-release` : `end-of-support`,
 			previousVersion: previous.version,
 			changes,
 			release,
@@ -99,26 +94,26 @@ async function checkLocalReleases(
 				const current = await readManifest(path.join(directory, `package.json`))
 				if (current.name !== peer)
 					throw new Error(`Local peer identity mismatch for ${peer}.`)
-				const release = await intent(config, {
+				const release = await releaseVersion(config, {
 					packageName: peer,
 					packageDirectory: directory,
 					currentVersion: current.version,
 				})
-				if (release.status === `none`) return []
-				if (!matches(release.version, range))
+				if (release === undefined) return []
+				if (!matches(release, 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.`,
+						`Declared support for ${peer}: ${range} does not include its planned local release ${release}. Update the peer range to include the intended version.`,
 					]
 				if (
 					!representatives.some(
 						(result) =>
 							result.peers[peer]?.source === `candidate` &&
-							result.peers[peer]?.version === release.version &&
+							result.peers[peer]?.version === release &&
 							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.`,
+						`No coordinated representative covers planned local peer ${peer}@${release}. Enroll ${peer} with breakage.candidates and configure its relationship suite.`,
 					]
 				return []
 			} catch (error) {
@@ -138,6 +133,7 @@ async function runRepresentative(
 	directory: string,
 	coverageOnly: boolean,
 	selection?: NpmTestSelection,
+	plannedSuites?: readonly string[],
 ): Promise<NpmRepresentativeResult> {
 	const label = path.relative(base, directory).split(path.sep).join(`/`)
 	const result: NpmRepresentativeResult = {
@@ -201,6 +197,7 @@ async function runRepresentative(
 			const peers = Object.keys(config.suites).filter((peer) => {
 				const evidence = result.peers[peer]
 				if (!evidence) return false
+				if (plannedSuites !== undefined) return plannedSuites.includes(peer)
 				if (selection && `peer` in selection) return peer === selection.peer
 				if (selection && `representative` in selection) return true
 				return matches(evidence.version, manifest.peerDependencies![peer]!)
@@ -262,6 +259,7 @@ async function run(
 	baseDirectory: string,
 	coverageOnly: boolean,
 	selection?: NpmTestSelection,
+	plannedSuites?: readonly string[],
 ): Promise<NpmReport> {
 	const report: NpmReport = {
 		package: { name: `(unresolved)`, version: `(unresolved)` },
@@ -297,24 +295,30 @@ async function run(
 				)
 			eras(selection.range)
 		}
-		// One piece of release evidence per package per invocation, including failures.
-		const releases = new Map<string, Promise<ReleaseIntent>>()
-		const configuredHook = config.releaseIntent
+		// One piece of release evidence per package and baseline per invocation, including failures.
+		const releases = new Map<string, Promise<VersionTransition | undefined>>()
+		const resolveDelta = (
+			context: ReleaseDeltaContext,
+		): Promise<VersionTransition | undefined> => {
+			const key = JSON.stringify([
+				context.packageDirectory,
+				context.currentVersion,
+				context.baseline,
+			])
+			let pending = releases.get(key)
+			if (!pending) {
+				pending = resolveReleaseDelta(config.release!, context)
+				releases.set(key, pending)
+			}
+			return pending
+		}
 		const effective: NpmConfig = {
 			...config,
-			releaseIntent: (context) => {
-				let pending = releases.get(context.packageDirectory)
-				if (!pending) {
-					pending = Promise.resolve().then(() =>
-						configuredHook
-							? configuredHook(context)
-							: ({ status: `none` } as const),
-					)
-					releases.set(context.packageDirectory, pending)
-				}
-				return pending
-			},
+			...(config.release
+				? { release: { ...config.release, resolveDelta } }
+				: {}),
 		}
+
 		const directories = await discover(config, base)
 		const [support, representatives] = await Promise.all([
 			selection
@@ -329,6 +333,7 @@ async function run(
 						directory,
 						coverageOnly,
 						selection,
+						plannedSuites,
 					),
 				),
 			),
@@ -411,6 +416,21 @@ export async function npmTest(
 	)
 }
 
+/** Internal matrix entrypoint: keep the full config for validation and peer identity checks. */
+export async function npmTestPlanned(
+	config: NpmConfig,
+	selection: { representative: string; suites: readonly string[] },
+	options: { baseDirectory?: string } = {},
+): Promise<NpmReport> {
+	return await run(
+		config,
+		options.baseDirectory ?? process.cwd(),
+		false,
+		{ representative: selection.representative },
+		selection.suites,
+	)
+}
+
 export function formatNpmReport(report: NpmReport): string {
 	const lines = [
 		`${report.package.name}@${report.package.version} — npm ${report.mode}`,

package/src/npm/cli.ts

@@ -1,30 +1,39 @@
-import { existsSync } from "node:fs"
-import { readFile } from "node:fs/promises"
 import path from "node:path"
-import { pathToFileURL } from "node:url"
 
 import { type } from "arktype"
 import type { OptionsGroup } from "comline"
 import { options, parseBooleanOption } from "comline"
 
+import { configOptions, defaultConfig, loadConfig } from "../config.ts"
+
 import { formatNpmReport, npmCheck, npmTest } from "./check.ts"
-import { errorMessage } from "./command.ts"
+import { errorMessage } from "../task.ts"
 import { validateConfig } from "./config.ts"
-import { record } from "./manifest.ts"
 import type { NpmTestSelection } from "./types.ts"
 
-type CommonOptions = { config?: string | undefined; json?: boolean | undefined }
+type CommonOptions = {
+	config?: string | undefined
+	json?: boolean | undefined
+	release?: import("../release.ts").ReleaseConfig
+	npm?: import("./types.ts").NpmConfig
+	npmMatrix?: import("./matrix-model.ts").NpmMatrixConfig
+}
 type CheckOptions = CommonOptions & { coverageOnly?: boolean | undefined }
 type TestOptions = CommonOptions & { representative?: string | undefined }
 
 const common = {
+	release: configOptions.optionConfigs.release,
+	npm: configOptions.optionConfigs.npm,
+	npmMatrix: configOptions.optionConfigs.npmMatrix,
 	config: {
+		schema: type(`string`),
 		required: false,
-		description: `Configuration file (defaults to breakage.config.ts, then .json).`,
+		description: `Configuration file (defaults to breakage.config.ts).`,
 		example: `--config ./breakage.config.ts`,
 		completion: { fileSystem: `files` as const, repeatable: false },
 	},
 	json: {
+		schema: type(`boolean`),
 		required: false,
 		description: `Emit the structured result.`,
 		example: `--json`,
@@ -34,10 +43,18 @@ const common = {
 
 export const npmCheckManual: OptionsGroup<CheckOptions> = options(
 	`Check npm peer compatibility and changes in declared support.`,
-	type({ "config?": `string`, "json?": `boolean`, "coverageOnly?": `boolean` }),
+	type({
+		"config?": `string`,
+		"json?": `boolean`,
+		"coverageOnly?": `boolean`,
+		"release?": configOptions.optionsSchema.get(`release`),
+		"npm?": configOptions.optionsSchema.get(`npm`),
+		"npmMatrix?": configOptions.optionsSchema.get(`npmMatrix`),
+	}),
 	{
 		...common,
 		coverageOnly: {
+			schema: type(`boolean`),
 			aliases: [`coverage-only`],
 			required: false,
 			description: `Audit coverage and support changes without executing assertions.`,
@@ -53,10 +70,14 @@ export const npmTestManual: OptionsGroup<TestOptions> = options(
 		"config?": `string`,
 		"json?": `boolean`,
 		"representative?": `string`,
+		"release?": configOptions.optionsSchema.get(`release`),
+		"npm?": configOptions.optionsSchema.get(`npm`),
+		"npmMatrix?": configOptions.optionsSchema.get(`npmMatrix`),
 	}),
 	{
 		...common,
 		representative: {
+			schema: type(`string`),
 			required: false,
 			description: `Select an exact configured representative path relative to the package.`,
 			example: `--representative peer-environments/react-19`,
@@ -65,15 +86,6 @@ export const npmTestManual: OptionsGroup<TestOptions> = options(
 	},
 )
 
-export function defaultConfig(directory: string): string {
-	return path.join(
-		directory,
-		existsSync(path.join(directory, `breakage.config.ts`))
-			? `breakage.config.ts`
-			: `breakage.config.json`,
-	)
-}
-
 export async function runNpmCli(
 	action: `check` | `test`,
 	opts: CheckOptions & TestOptions,
@@ -81,11 +93,7 @@ export async function runNpmCli(
 ): Promise<number> {
 	try {
 		const filename = path.resolve(opts.config ?? defaultConfig(process.cwd()))
-		const loaded: unknown = filename.endsWith(`.json`)
-			? JSON.parse(await readFile(filename, `utf8`))
-			: ((await import(pathToFileURL(filename).href)) as { default: unknown })
-					.default
-		const config = record(loaded) ? loaded.npm : undefined
+		const config = (await loadConfig(filename)).npm
 		validateConfig(config)
 		let selection: NpmTestSelection | undefined
 		if (action === `test`) {

package/src/npm/config.ts

@@ -1,15 +1,45 @@
 import path from "node:path"
+import { type } from "arktype"
+
+import { releaseSchema, rejectCertificationOptions } from "../release.ts"
 
 import { eras, packageName, record } from "./manifest.ts"
 import type { NpmConfig } from "./types.ts"
 
+export const npmSuiteSchema = type({
+	"+": `reject`,
+	files: `string[]`,
+	command: `string`,
+})
+export const npmConfigSchema = type({
+	"+": `reject`,
+	"release?": releaseSchema,
+	"packageDirectory?": `string`,
+	artifact: `string`,
+	representatives: `string | string[]`,
+	lockfile: `string`,
+	prepareCommand: `string`,
+	"installCommand?": `string`,
+	suites: { "[string]": npmSuiteSchema },
+	"localPeers?": {
+		"[string]": { "+": `reject`, directory: `string`, artifact: `string` },
+	},
+	baseline: type({ "+": `reject`, firstRelease: `true` }).or({
+		"+": `reject`,
+		"tagPattern?": `string`,
+		"baselineFile?": `string`,
+	}),
+})
+
 function nonempty(value: unknown): value is string {
 	return typeof value === `string` && value.trim().length > 0
 }
 
 export function validateConfig(value: unknown): asserts value is NpmConfig {
 	if (!record(value)) throw new Error(`Configuration must have an npm object.`)
-	for (const key of [`artifact`, `lockfile`, `prepareCommand`] as const) {
+	rejectCertificationOptions(value)
+	npmConfigSchema.assert(value)
+	for (const key of [`artifact`, `lockfile`] as const) {
 		if (!nonempty(value[key]))
 			throw new Error(`npm.${key} must be a nonempty string.`)
 	}
@@ -19,7 +49,13 @@ export function validateConfig(value: unknown): asserts value is NpmConfig {
 	) {
 		throw new Error(`npm.lockfile must stay inside each representative.`)
 	}
-	for (const key of [`packageDirectory`, `installCommand`] as const) {
+	if (!nonempty(value.prepareCommand))
+		throw new Error(
+			`npm.prepareCommand must be a nonempty shell command string.`,
+		)
+	if (value.installCommand !== undefined && !nonempty(value.installCommand))
+		throw new Error(`Invalid npm.installCommand.`)
+	for (const key of [`packageDirectory`] as const) {
 		if (value[key] !== undefined && !nonempty(value[key]))
 			throw new Error(`Invalid npm.${key}.`)
 	}
@@ -75,10 +111,6 @@ export function validateConfig(value: unknown): asserts value is NpmConfig {
 			}
 		}
 	}
-	for (const hook of [`releaseIntent`, `certifyBreaking`] as const) {
-		if (value[hook] !== undefined && typeof value[hook] !== `function`)
-			throw new Error(`npm.${hook} must be a function.`)
-	}
 }
 
 export function validatePeerRanges(peers: Record<string, string>): void {

package/src/npm/environment.ts

@@ -16,11 +16,11 @@ import path from "node:path"
 import semver from "semver"
 import { simpleGit } from "simple-git"
 
-import { prepare } from "./command.ts"
+import { prepare } from "../task.ts"
 import { validatePeerRanges } from "./config.ts"
 import type { Manifest } from "./manifest.ts"
 import { matches, normalizeWorkspacePeers, readManifest } from "./manifest.ts"
-import { intent } from "./release.ts"
+import { releaseVersion } from "./release.ts"
 import type { NpmConfig, NpmPeerEvidence, NpmSuite } from "./types.ts"
 
 export type Environment = {
@@ -192,14 +192,14 @@ export async function maySelectEnvironment(
 		)
 		if (current.name !== peer)
 			throw new Error(`Local peer identity mismatch for ${peer}.`)
-		const release = await intent(config, {
+		const release = await releaseVersion(config, {
 			packageName: peer,
 			packageDirectory,
 			currentVersion: current.version,
 		})
-		if (release.status === `none`)
-			throw new Error(`Candidate ${peer} has no certified release intent.`)
-		return matches(release.version, range)
+		if (release === undefined)
+			throw new Error(`Candidate ${peer} has no release version.`)
+		return matches(release, range)
 	}
 	const declared = declarations[peer]
 	return declared !== undefined && matches(declared, range)
@@ -243,18 +243,18 @@ export async function prepareEnvironment(
 		if (localManifest.name !== peer)
 			throw new Error(`Local peer identity mismatch for ${peer}.`)
 		validatePeerRanges(localManifest.peerDependencies ?? {})
-		const evidence = await intent(config, {
+		const evidence = await releaseVersion(config, {
 			packageName: peer,
 			packageDirectory: localDirectory,
 			currentVersion: localManifest.version,
 		})
-		if (evidence.status === `none`)
-			throw new Error(`Candidate ${peer} has no certified release intent.`)
+		if (evidence === undefined)
+			throw new Error(`Candidate ${peer} has no release version.`)
 		candidates[peer] = {
 			directory: localDirectory,
 			artifact: path.resolve(base, local.artifact),
 			currentVersion: localManifest.version,
-			version: evidence.version,
+			version: evidence,
 			manifest: localManifest,
 		}
 	}