breakage 0.8.4 → 0.9.0

package/src/npm/manifest.ts

@@ -0,0 +1,134 @@
+import { readFile } from "node:fs/promises"
+
+import semver from "semver"
+
+export type Manifest = {
+	name: string
+	version: string
+	type?: string
+	dependencies?: Record<string, string>
+	optionalDependencies?: Record<string, string>
+	devDependencies?: Record<string, string>
+	peerDependencies?: Record<string, string>
+	peerDependenciesMeta?: Record<string, { optional?: boolean }>
+	breakage?: { candidates?: string[] }
+}
+
+export function record(value: unknown): value is Record<string, unknown> {
+	return typeof value === `object` && value !== null && !Array.isArray(value)
+}
+
+export function packageName(value: string): boolean {
+	return /^(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/.test(value)
+}
+
+export function parseManifest(value: unknown, label: string): Manifest {
+	if (
+		!record(value) ||
+		typeof value.name !== `string` ||
+		!packageName(value.name) ||
+		typeof value.version !== `string` ||
+		!semver.valid(value.version)
+	) {
+		throw new Error(`Invalid package identity in ${label}.`)
+	}
+	if (
+		value.peerDependenciesMeta !== undefined &&
+		(!record(value.peerDependenciesMeta) ||
+			Object.values(value.peerDependenciesMeta).some(
+				(entry) =>
+					!record(entry) ||
+					(entry.optional !== undefined && typeof entry.optional !== `boolean`),
+			))
+	) {
+		throw new Error(`Invalid peerDependenciesMeta in ${label}.`)
+	}
+	for (const field of [
+		`dependencies`,
+		`optionalDependencies`,
+		`devDependencies`,
+		`peerDependencies`,
+	] as const) {
+		const entries = value[field]
+		if (
+			entries !== undefined &&
+			(!record(entries) ||
+				Object.entries(entries).some(
+					([name, spec]) => !packageName(name) || typeof spec !== `string`,
+				))
+		) {
+			throw new Error(`Invalid ${field} in ${label}.`)
+		}
+	}
+	if (
+		value.breakage !== undefined &&
+		(!record(value.breakage) ||
+			(value.breakage.candidates !== undefined &&
+				(!Array.isArray(value.breakage.candidates) ||
+					value.breakage.candidates.some(
+						(name: unknown) => typeof name !== `string` || !packageName(name),
+					))))
+	) {
+		throw new Error(`Invalid candidate peers in ${label}.`)
+	}
+	return value as Manifest
+}
+
+export async function readManifest(filename: string): Promise<Manifest> {
+	return parseManifest(JSON.parse(await readFile(filename, `utf8`)), filename)
+}
+
+/** Current support is authored explicitly; only historical shorthand is resolved. */
+export async function normalizeWorkspacePeers(
+	manifest: Manifest,
+	versionAtBaseline?: (peer: string) => Promise<string>,
+): Promise<Manifest> {
+	if (!manifest.peerDependencies) return manifest
+	const entries = await Promise.all(
+		Object.entries(manifest.peerDependencies).map(async ([peer, range]) => {
+			if (!range.startsWith(`workspace:`)) return [peer, range] as const
+			const requested = range.slice(`workspace:`.length)
+			if ([``, `*`, `^`, `~`].includes(requested)) {
+				if (!versionAtBaseline)
+					throw new Error(
+						`Moving workspace peer range ${peer}: ${range} in ${manifest.name}. Declare explicit support eras, for example ^1.0.0 || ^2.0.0, so local version changes cannot change the support promise.`,
+					)
+				const version = await versionAtBaseline(peer)
+				if (!semver.valid(version))
+					throw new Error(
+						`Invalid historical workspace version for ${peer}: ${version}.`,
+					)
+				return [
+					peer,
+					`${requested === `^` || requested === `~` ? requested : ``}${version}`,
+				] as const
+			}
+			try {
+				eras(requested)
+			} catch {
+				throw new Error(
+					`Unsupported workspace peer range for ${peer}: ${range}.`,
+				)
+			}
+			return [peer, requested] as const
+		}),
+	)
+	return { ...manifest, peerDependencies: Object.fromEntries(entries) }
+}
+
+export function eras(range: string): string[] {
+	const parts = range.split(`||`).map((part) => part.trim())
+	if (parts.some((part) => !part || semver.validRange(part) === null)) {
+		throw new Error(`Invalid peer range: ${range}.`)
+	}
+	return parts
+}
+
+/** Previews only represent an explicitly enrolled exact preview. */
+export function matches(version: string, range: string): boolean {
+	return eras(range).some((era) =>
+		semver.prerelease(version)
+			? semver.valid(era.replace(/^=\s*/, ``)) === semver.valid(version)
+			: semver.satisfies(version, era),
+	)
+}

package/src/npm/release.ts

@@ -0,0 +1,173 @@
+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 } from "./manifest.ts"
+import type { NpmConfig, SupportChange } from "./types.ts"
+
+export async function releaseVersion(
+	config: NpmConfig,
+	context: ReleaseDeltaContext,
+): Promise<string | undefined> {
+	return config.release
+		? (await resolveReleaseDelta(config.release, context))?.version
+		: undefined
+}
+
+/**
+ * Compare the union, including adjacent alternatives. semver.subset compares each
+ * conjunction to a single conjunction and cannot prove coverage by their union.
+ * Membership can change only at comparator boundaries or prerelease tuple gates.
+ */
+export function includesRange(current: string, previous: string): boolean {
+	const ranges = [new semver.Range(previous), new semver.Range(current)]
+	const samples = new Set<string>([`0.0.0`, `0.0.0-0`])
+	for (const range of ranges) {
+		for (const conjunction of range.set) {
+			for (const comparator of conjunction) {
+				const version = comparator.semver
+				if (typeof version === `symbol`) continue
+				const base = `${version.major}.${version.minor}.${version.patch}`
+				samples.add(version.version)
+				samples.add(base)
+				samples.add(`${base}-0`)
+				// The immediate successor in a prerelease sequence appends numeric zero.
+				if (version.prerelease.length) samples.add(`${version.version}.0`)
+				// Stable versions are discrete; the next patch starts another tuple gate.
+				const next = semver.inc(base, `patch`)
+				if (next) {
+					samples.add(next)
+					samples.add(`${next}-0`)
+				}
+			}
+		}
+	}
+	return [...samples].every(
+		(version) =>
+			!semver.satisfies(version, previous) ||
+			semver.satisfies(version, current),
+	)
+}
+
+export function supportChanges(
+	previous: Manifest,
+	current: Manifest,
+): SupportChange[] {
+	const before = previous.peerDependencies ?? {}
+	const after = current.peerDependencies ?? {}
+	validatePeerRanges(before)
+	validatePeerRanges(after)
+	return Object.entries(after).flatMap(([peer, range]) => {
+		const old = before[peer]
+		const wasOptional = previous.peerDependenciesMeta?.[peer]?.optional === true
+		const isOptional = current.peerDependenciesMeta?.[peer]?.optional === true
+		// Absence scenarios are not generated, but making an optional peer required
+		// still changes the installation contract for existing consumers.
+		return (old === undefined && isOptional) ||
+			(old !== undefined &&
+				includesRange(range, old) &&
+				!(wasOptional && !isOptional))
+			? []
+			: [
+					{
+						peer,
+						reason:
+							old === undefined || (wasOptional && !isOptional)
+								? (`required-peer` as const)
+								: (`narrowed-range` as const),
+						previous: old ?? null,
+						current: range,
+					},
+				]
+	})
+}
+
+export async function previousManifest(
+	config: NpmConfig,
+	directory: string,
+): Promise<Manifest | undefined> {
+	if (`firstRelease` in config.baseline) return undefined
+	const git = simpleGit(directory)
+	let commit: string
+	if (config.baseline.baselineFile) {
+		commit = (
+			await readBaseline(
+				git,
+				path.resolve(directory, config.baseline.baselineFile),
+				config.baseline,
+			)
+		).commit
+	} else {
+		const tags = await git.listRemote([`--tags`, `origin`])
+		const ref = latestReleaseTag(tags, config.baseline.tagPattern)
+		if (!ref)
+			throw new Error(
+				`No npm release baseline found; configure a tag pattern or explicitly declare firstRelease.`,
+			)
+		const refs = new Map(
+			tags
+				.trim()
+				.split(`\n`)
+				.map((line) => {
+					const [sha, name] = line.split(`\t`)
+					return [name, sha]
+				}),
+		)
+		const resolved = refs.get(`${ref}^{}`) ?? refs.get(ref)
+		if (!resolved || !/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(resolved))
+			throw new Error(`Invalid release commit for ${ref}.`)
+		commit = resolved
+		const common = await git.revparse([
+			`--path-format=absolute`,
+			`--git-common-dir`,
+		])
+		await withDirectoryLock(path.join(common, `breakage-fetch.lock`), () =>
+			git.fetch([`origin`, commit, `--no-tags`, `--no-write-fetch-head`]),
+		)
+	}
+	const prefix = await git.revparse([`--show-prefix`])
+	const manifest = parseManifest(
+		JSON.parse(await git.show([`${commit}:${prefix}package.json`])),
+		`release ${commit}`,
+	)
+	return await normalizeWorkspacePeers(manifest, async (peer) => {
+		const local = config.localPeers?.[peer]
+		if (!local)
+			throw new Error(
+				`Historical workspace peer ${peer} needs a localPeers directory to resolve release ${commit}.`,
+			)
+		const root = await git.revparse([`--show-toplevel`])
+		const relative = path.relative(
+			root,
+			path.resolve(directory, local.directory),
+		)
+		if (
+			relative === `..` ||
+			relative.startsWith(`..${path.sep}`) ||
+			path.isAbsolute(relative)
+		)
+			throw new Error(
+				`Historical workspace peer ${peer} escapes the release repository.`,
+			)
+		const filename = path
+			.join(relative, `package.json`)
+			.split(path.sep)
+			.join(`/`)
+		const historical = parseManifest(
+			JSON.parse(await git.show([`${commit}:${filename}`])),
+			`release ${commit}:${filename}`,
+		)
+		if (historical.name !== peer)
+			throw new Error(
+				`Historical workspace peer identity mismatch for ${peer}.`,
+			)
+		return historical.version
+	})
+}

package/src/npm/types.ts

@@ -0,0 +1,64 @@
+import type { VersionDelta } from "../release.ts"
+
+export type SupportChange = {
+	peer: string
+	reason: `narrowed-range` | `required-peer`
+	previous: string | null
+	current: string | null
+}
+
+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 }
+	| { representative: string }
+
+export type NpmPeerEvidence = {
+	version: string
+	path: string
+	source: `installed` | `candidate`
+	archiveVersion?: string
+}
+
+export type NpmSuiteResult = {
+	peer: string
+	status: `passed` | `compatibility-failure` | `setup-error` | `not-run`
+	output?: string
+}
+
+export type NpmRepresentativeResult = {
+	path: string
+	status:
+		| `passed`
+		| `audited`
+		| `skipped`
+		| `compatibility-failure`
+		| `setup-error`
+	peers: Record<string, NpmPeerEvidence>
+	suites: NpmSuiteResult[]
+	warnings: string[]
+	error?: string
+}
+
+export type NpmReport = {
+	package: { name: string; version: string }
+	mode: `check` | `coverage-only` | `test`
+	exitCode: 0 | 1 | 2
+	representatives: NpmRepresentativeResult[]
+	coverage: { peer: string; era: string; representatives: string[] }[]
+	support: {
+		status:
+			| `unchanged`
+			| `breaking-release`
+			| `end-of-support`
+			| `first-release`
+			| `not-checked`
+			| `setup-error`
+		changes: SupportChange[]
+		previousVersion?: string
+		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/task.ts

@@ -0,0 +1,54 @@
+import { spawn } from "node:child_process"
+import path from "node:path"
+
+export type CommandResult = { code: number; output: string }
+
+/** Capture output per environment so parallel runs cannot interleave their reports. */
+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,
+			shell: true,
+			env: {
+				...process.env,
+				NODE_PATH: ``,
+				PATH: [
+					path.join(cwd, `node_modules/.bin`),
+					path.join(cwd, `../node_modules/.bin`),
+					process.env.PATH,
+				].join(path.delimiter),
+			},
+			stdio: [`ignore`, `pipe`, `pipe`],
+		})
+		let output = ``
+		const collect = (chunk: Buffer): void => {
+			// Bound diagnostics without interrupting a command that emits lots of output.
+			output = (output + chunk.toString()).slice(-1_000_000)
+		}
+		child.stdout.on(`data`, collect)
+		child.stderr.on(`data`, collect)
+		child.on(`error`, reject)
+		child.on(`close`, (code, signal) =>
+			resolve({ code: signal ? 2 : (code ?? 2), output }),
+		)
+	})
+}
+
+export async function prepare(commandLine: string, cwd: string): Promise<void> {
+	const result = await command(commandLine, cwd)
+	if (result.code !== 0)
+		throw new Error(
+			`Command failed (${result.code}) in ${cwd}: ${commandLine}\n${result.output}`,
+		)
+}
+
+export function errorMessage(error: unknown): string {
+	return error instanceof Error
+		? `${error.message}${error.cause ? `\n${errorMessage(error.cause)}` : ``}`
+		: String(error)
+}