breakage 0.8.5 → 0.9.0

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) {
@@ -297,24 +292,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

package/src/npm/cli.ts

@@ -1,30 +1,37 @@
-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
+}
 type CheckOptions = CommonOptions & { coverageOnly?: boolean | undefined }
 type TestOptions = CommonOptions & { representative?: string | undefined }
 
 const common = {
+	release: configOptions.optionConfigs.release,
+	npm: configOptions.optionConfigs.npm,
 	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 +41,17 @@ 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`),
+	}),
 	{
 		...common,
 		coverageOnly: {
+			schema: type(`boolean`),
 			aliases: [`coverage-only`],
 			required: false,
 			description: `Audit coverage and support changes without executing assertions.`,
@@ -53,10 +67,13 @@ export const npmTestManual: OptionsGroup<TestOptions> = options(
 		"config?": `string`,
 		"json?": `boolean`,
 		"representative?": `string`,
+		"release?": configOptions.optionsSchema.get(`release`),
+		"npm?": configOptions.optionsSchema.get(`npm`),
 	}),
 	{
 		...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 +82,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 +89,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,
 		}
 	}

package/src/npm/release.ts

@@ -3,38 +3,22 @@ import path from "node:path"
 import semver from "semver"
 import { simpleGit } from "simple-git"
 
+import { resolveReleaseDelta, type ReleaseDeltaContext } from "../release.ts"
 import { readBaseline } from "../baseline.ts"
 import { withDirectoryLock } from "../directory-lock.ts"
 import { latestReleaseTag } from "../release-tag.ts"
 import { validatePeerRanges } from "./config.ts"
 import type { Manifest } from "./manifest.ts"
-import { normalizeWorkspacePeers, parseManifest, record } from "./manifest.ts"
-import type {
-	NpmConfig,
-	ReleaseContext,
-	ReleaseIntent,
-	SupportChange,
-} from "./types.ts"
+import { normalizeWorkspacePeers, parseManifest } from "./manifest.ts"
+import type { NpmConfig, SupportChange } from "./types.ts"
 
-export async function intent(
+export async function releaseVersion(
 	config: NpmConfig,
-	context: ReleaseContext,
-): Promise<ReleaseIntent> {
-	if (!config.releaseIntent) return { status: `none` }
-	const result: unknown = 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 }
+	context: ReleaseDeltaContext,
+): Promise<string | undefined> {
+	return config.release
+		? (await resolveReleaseDelta(config.release, context))?.version
+		: undefined
 }
 
 /**

package/src/npm/types.ts

@@ -1,12 +1,4 @@
-export type ReleaseIntent =
-	| { status: `none` }
-	| { status: `release`; version: string }
-
-export type ReleaseContext = {
-	packageName: string
-	packageDirectory: string
-	currentVersion: string
-}
+import type { VersionDelta } from "../release.ts"
 
 export type SupportChange = {
 	peer: string
@@ -15,40 +7,8 @@ export type SupportChange = {
 	current: string | null
 }
 
-export type ReleaseEvidence = {
-	version: string
-	delta: string
-}
-
-export type NpmSuite = {
-	/** Package-relative globs; preserve relative paths inside the stage. */
-	files: string[]
-	/** Run once; 1 means assertion failure, other nonzero codes mean setup failure. */
-	command: string
-}
-
-export type NpmConfig = {
-	packageDirectory?: string
-	artifact: string
-	representatives: string | string[]
-	lockfile: string
-	prepareCommand: string
-	installCommand?: string
-	suites: Record<string, NpmSuite>
-	/** Currently declared local peers must support and exercise each planned release. */
-	localPeers?: Record<string, { directory: string; artifact: string }>
-	baseline:
-		| { firstRelease: true }
-		| { tagPattern?: string; baselineFile?: string }
-	releaseIntent?: (
-		context: ReleaseContext,
-	) => ReleaseIntent | Promise<ReleaseIntent>
-	certifyBreaking?: (context: {
-		previousVersion: string
-		release: ReleaseEvidence
-		changes: SupportChange[]
-	}) => boolean | Promise<boolean>
-}
+export type NpmSuite = typeof import("./config.ts").npmSuiteSchema.infer
+export type NpmConfig = typeof import("./config.ts").npmConfigSchema.infer
 
 export type NpmTestSelection =
 	| { peer: string; range: string }
@@ -90,14 +50,14 @@ export type NpmReport = {
 	support: {
 		status:
 			| `unchanged`
-			| `certified`
+			| `breaking-release`
 			| `end-of-support`
 			| `first-release`
 			| `not-checked`
 			| `setup-error`
 		changes: SupportChange[]
 		previousVersion?: string
-		release?: ReleaseEvidence
+		release?: VersionDelta
 		error?: string
 	}
 	errors: string[]

package/src/release.ts

@@ -0,0 +1,153 @@
+// cspell:words premajor preminor prepatch
+import semver from "semver"
+import { type } from "arktype"
+
+export type ReleaseDeltaContext = {
+	packageName: string
+	packageDirectory: string
+	currentVersion: string
+	/** The selected historical release, when checking compatibility. */
+	baseline?: { version: string; ref?: string; commit?: string }
+}
+export type VersionTransition = {
+	previousVersion: string
+	version: string
+	delta:
+		| `major`
+		| `premajor`
+		| `minor`
+		| `preminor`
+		| `patch`
+		| `prepatch`
+		| `prerelease`
+		| `release`
+		| `none`
+}
+export type ReleaseDeltaResolver = (
+	context: ReleaseDeltaContext,
+) => VersionTransition | undefined | Promise<VersionTransition | undefined>
+export type VersionDelta = VersionTransition & { breaking: boolean }
+export type SemverPolicyOptions = { beforeV1?: `major` | `minor` | `patch` }
+export type ReleasePolicyFunction = (delta: VersionTransition) => boolean
+export type ReleasePolicy = ReleasePolicyFunction
+export const releaseSchema = type({
+	"+": `reject`,
+	"resolveDelta?": type(`Function`).as<ReleaseDeltaResolver>(),
+	"policy?": type(`Function`).as<ReleasePolicy>(),
+})
+export type ReleaseConfig = typeof releaseSchema.infer
+
+/** Choose which version increments permit breaking changes. Prerelease-only increments do not. */
+export function semverPolicy({
+	beforeV1 = `major`,
+}: SemverPolicyOptions = {}): ReleasePolicyFunction {
+	if (![`major`, `minor`, `patch`].includes(beforeV1))
+		throw new Error(`Invalid beforeV1 policy.`)
+	return ({ previousVersion, version }) => {
+		const previous = new semver.SemVer(previousVersion)
+		const next = new semver.SemVer(version)
+		if (next.major > previous.major) return true
+		if (previous.major !== 0 || beforeV1 === `major`) return false
+		return (
+			next.minor > previous.minor ||
+			(beforeV1 === `patch` && next.patch > previous.patch)
+		)
+	}
+}
+
+/** Describe a version transition without deciding whether it permits breakage. */
+export function versionTransition(
+	previousVersion: string,
+	version: string,
+): VersionTransition {
+	if (!semver.valid(previousVersion) || !semver.valid(version))
+		throw new Error(`Expected exact semantic versions.`)
+	return {
+		previousVersion,
+		version,
+		delta: semver.diff(previousVersion, version) ?? `none`,
+	}
+}
+
+/** Pure comparison; equal and older versions never permit breaking changes. */
+export function versionDelta(
+	previousVersion: string,
+	version: string,
+	policy: ReleasePolicy = semverPolicy(),
+): VersionDelta {
+	const evidence = versionTransition(previousVersion, version)
+	const breaking = semver.gt(version, previousVersion)
+		? policy(evidence)
+		: false
+	if (typeof breaking !== `boolean`)
+		throw new Error(`Release policy must return a boolean.`)
+	return { ...evidence, breaking }
+}
+
+export function validateRelease(
+	value: unknown,
+): asserts value is ReleaseConfig {
+	if (typeof value !== `object` || value === null || Array.isArray(value))
+		throw new Error(`release must be an object.`)
+	if (`version` in value)
+		throw new Error(
+			`release.version was removed. Use release.resolveDelta to return a version transition.`,
+		)
+	releaseSchema.assert(value)
+}
+
+/** Resolve and validate release evidence; policy is applied separately. */
+export async function resolveReleaseDelta(
+	config: ReleaseConfig,
+	context: ReleaseDeltaContext,
+): Promise<VersionTransition | undefined> {
+	validateRelease(config)
+	const transition = config.resolveDelta
+		? await config.resolveDelta(context)
+		: versionTransition(
+				context.baseline?.version ?? context.currentVersion,
+				context.currentVersion,
+			)
+	if (transition === undefined) return undefined
+	if (
+		typeof transition !== `object` ||
+		transition === null ||
+		Array.isArray(transition) ||
+		typeof transition.previousVersion !== `string` ||
+		!semver.valid(transition.previousVersion) ||
+		typeof transition.version !== `string` ||
+		!semver.valid(transition.version) ||
+		!semver.valid(context.currentVersion) ||
+		semver.lt(transition.version, context.currentVersion)
+	)
+		throw new Error(
+			`Invalid release transition for ${context.packageName}; expected exact versions and a current/newer target.`,
+		)
+	if (
+		context.baseline &&
+		transition.previousVersion !== context.baseline.version
+	)
+		throw new Error(
+			`Release transition for ${context.packageName} does not match the selected baseline.`,
+		)
+	const evidence = versionTransition(
+		transition.previousVersion,
+		transition.version,
+	)
+	if (transition.delta !== evidence.delta)
+		throw new Error(
+			`Release transition for ${context.packageName} has an inconsistent semver delta.`,
+		)
+	// Only evidence crosses this boundary; resolver-supplied policy decisions are ignored.
+	return evidence
+}
+
+/** Removed hooks must fail explicitly, including in untyped configurations. */
+export function rejectCertificationOptions(value: object): void {
+	for (const key of [`certifyCommand`, `releaseIntent`, `certifyBreaking`]) {
+		if (key in value)
+			throw new Error(
+				`${key} was removed. Use release.resolveDelta and release.policy instead.`,
+			)
+	}
+}

package/src/{npm/command.ts → task.ts}

@@ -8,6 +8,8 @@ export async function command(
 	commandLine: string,
 	cwd: string,
 ): Promise<CommandResult> {
+	if (typeof commandLine !== `string` || !commandLine.trim())
+		throw new Error(`Commands must be nonempty shell strings.`)
 	return await new Promise((resolve, reject) => {
 		const child = spawn(commandLine, {
 			cwd,