breakage 0.8.3 → 0.8.5

package/src/npm/check.ts

@@ -0,0 +1,448 @@
+import path from "node:path"
+
+import semver from "semver"
+
+import { command, errorMessage } from "./command.ts"
+import { validateConfig, validatePeerRanges } from "./config.ts"
+import {
+	checkCandidatePeers,
+	discover,
+	maySelectEnvironment,
+	prepareEnvironment,
+	stageCandidate,
+	verifyResolution,
+	withStage,
+} from "./environment.ts"
+import type { Manifest } from "./manifest.ts"
+import {
+	eras,
+	matches,
+	normalizeWorkspacePeers,
+	readManifest,
+} from "./manifest.ts"
+import { intent, previousManifest, supportChanges } from "./release.ts"
+import type {
+	NpmConfig,
+	NpmReport,
+	NpmRepresentativeResult,
+	NpmTestSelection,
+	ReleaseIntent,
+} from "./types.ts"
+
+async function checkSupport(
+	config: NpmConfig,
+	base: string,
+	manifest: Manifest,
+): Promise<NpmReport[`support`]> {
+	try {
+		const previous = await previousManifest(config, base)
+		if (!previous) return { status: `first-release`, changes: [] }
+		if (previous.name !== manifest.name)
+			throw new Error(
+				`Release baseline belongs to ${previous.name}, not ${manifest.name}.`,
+			)
+		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`)
+			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.`)
+		return {
+			status: certified ? `certified` : `end-of-support`,
+			previousVersion: previous.version,
+			changes,
+			release,
+		}
+	} catch (error) {
+		return { status: `setup-error`, changes: [], error: errorMessage(error) }
+	}
+}
+
+async function checkLocalReleases(
+	config: NpmConfig,
+	base: string,
+	manifest: Manifest,
+	representatives: NpmRepresentativeResult[],
+): Promise<string[]> {
+	const findings = await Promise.all(
+		Object.entries(config.localPeers ?? {}).map(async ([peer, local]) => {
+			const range = manifest.peerDependencies?.[peer]
+			// A registration may be retained solely to resolve an older baseline.
+			if (range === undefined) return []
+			try {
+				const directory = path.resolve(base, local.directory)
+				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, {
+					packageName: peer,
+					packageDirectory: directory,
+					currentVersion: current.version,
+				})
+				if (release.status === `none`) return []
+				if (!matches(release.version, 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.`,
+					]
+				if (
+					!representatives.some(
+						(result) =>
+							result.peers[peer]?.source === `candidate` &&
+							result.peers[peer]?.version === release.version &&
+							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.`,
+					]
+				return []
+			} catch (error) {
+				return [
+					`Cannot inspect planned local release for ${peer}: ${errorMessage(error)}`,
+				]
+			}
+		}),
+	)
+	return findings.flat()
+}
+
+async function runRepresentative(
+	config: NpmConfig,
+	base: string,
+	manifest: Manifest,
+	directory: string,
+	coverageOnly: boolean,
+	selection?: NpmTestSelection,
+): Promise<NpmRepresentativeResult> {
+	const label = path.relative(base, directory).split(path.sep).join(`/`)
+	const result: NpmRepresentativeResult = {
+		path: label,
+		status: `skipped`,
+		peers: {},
+		suites: [],
+		warnings: [],
+	}
+	if (
+		selection &&
+		`representative` in selection &&
+		path.resolve(base, selection.representative) !== directory
+	)
+		return result
+	try {
+		if (
+			selection &&
+			`peer` in selection &&
+			!(await maySelectEnvironment(
+				config,
+				base,
+				directory,
+				manifest,
+				selection,
+			))
+		)
+			return result
+		return await withStage(directory, async (stage) => {
+			const environment = await prepareEnvironment(
+				config,
+				base,
+				directory,
+				stage,
+				manifest,
+			)
+			result.peers = environment.peers
+			for (const peer of Object.keys(manifest.peerDependencies ?? {})) {
+				if (
+					!result.peers[peer] &&
+					!manifest.peerDependenciesMeta?.[peer]?.optional
+				)
+					throw new Error(
+						`Complete representative is missing required peer ${peer}.`,
+					)
+			}
+			for (const [peer, evidence] of Object.entries(result.peers)) {
+				const range = manifest.peerDependencies?.[peer]
+				if (range !== undefined && !matches(evidence.version, range))
+					result.warnings.push(
+						`${peer}@${evidence.version} is outside declared support.`,
+					)
+			}
+			if (
+				selection &&
+				`peer` in selection &&
+				(!result.peers[selection.peer] ||
+					!matches(result.peers[selection.peer]!.version, selection.range))
+			)
+				return result
+			const peers = Object.keys(config.suites).filter((peer) => {
+				const evidence = result.peers[peer]
+				if (!evidence) return false
+				if (selection && `peer` in selection) return peer === selection.peer
+				if (selection && `representative` in selection) return true
+				return matches(evidence.version, manifest.peerDependencies![peer]!)
+			})
+			result.suites = peers.map((peer) => ({ peer, status: `not-run` }))
+			if (!peers.length) return result
+			result.warnings.push(...checkCandidatePeers(environment, !!selection))
+			if (coverageOnly) {
+				result.status = `audited`
+				return result
+			}
+			await stageCandidate(
+				config,
+				base,
+				manifest,
+				environment,
+				peers.map((peer) => config.suites[peer]!),
+			)
+			for (const suite of result.suites) {
+				try {
+					await verifyResolution(manifest, environment)
+					const execution = await command(
+						config.suites[suite.peer]!.command,
+						stage,
+					)
+					await verifyResolution(manifest, environment)
+					suite.status =
+						execution.code === 0
+							? `passed`
+							: execution.code === 1
+								? `compatibility-failure`
+								: `setup-error`
+					if (execution.output) suite.output = execution.output
+				} catch (error) {
+					suite.status = `setup-error`
+					suite.output = errorMessage(error)
+				}
+			}
+			result.status = result.suites.some(
+				(suite) => suite.status === `setup-error`,
+			)
+				? `setup-error`
+				: result.suites.some(
+							(suite) => suite.status === `compatibility-failure`,
+					  )
+					? `compatibility-failure`
+					: `passed`
+			return result
+		})
+	} catch (error) {
+		result.status = `setup-error`
+		result.error = errorMessage(error)
+		return result
+	}
+}
+
+async function run(
+	config: NpmConfig,
+	baseDirectory: string,
+	coverageOnly: boolean,
+	selection?: NpmTestSelection,
+): Promise<NpmReport> {
+	const report: NpmReport = {
+		package: { name: `(unresolved)`, version: `(unresolved)` },
+		mode: selection ? `test` : coverageOnly ? `coverage-only` : `check`,
+		exitCode: 0,
+		representatives: [],
+		coverage: [],
+		support: { status: `not-checked`, changes: [] },
+		errors: [],
+	}
+	try {
+		validateConfig(config)
+		const base = path.resolve(baseDirectory, config.packageDirectory ?? `.`)
+		const manifest = await normalizeWorkspacePeers(
+			await readManifest(path.join(base, `package.json`)),
+		)
+		report.package = { name: manifest.name, version: manifest.version }
+		validatePeerRanges(manifest.peerDependencies ?? {})
+		for (const peer of Object.keys(config.suites)) {
+			if (!manifest.peerDependencies?.[peer])
+				throw new Error(`Suite ${peer} has no peerDependencies declaration.`)
+		}
+		for (const peer of Object.keys(config.localPeers ?? {})) {
+			if (manifest.peerDependencies?.[peer] && !config.suites[peer])
+				throw new Error(
+					`Declared local peer ${peer} needs a relationship suite.`,
+				)
+		}
+		if (selection && `peer` in selection) {
+			if (!config.suites[selection.peer])
+				throw new Error(
+					`No relationship suite configured for ${selection.peer}.`,
+				)
+			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
+		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
+			},
+		}
+		const directories = await discover(config, base)
+		const [support, representatives] = await Promise.all([
+			selection
+				? Promise.resolve(report.support)
+				: checkSupport(effective, base, manifest),
+			Promise.all(
+				directories.map((directory) =>
+					runRepresentative(
+						effective,
+						base,
+						manifest,
+						directory,
+						coverageOnly,
+						selection,
+					),
+				),
+			),
+		])
+		report.support = support
+		report.representatives = representatives
+		if (!selection) {
+			report.errors.push(
+				...(await checkLocalReleases(
+					effective,
+					base,
+					manifest,
+					representatives,
+				)),
+			)
+			for (const peer of Object.keys(config.suites)) {
+				for (const era of eras(manifest.peerDependencies![peer]!)) {
+					const matching = representatives
+						.filter(
+							(representative) =>
+								representative.peers[peer] &&
+								matches(representative.peers[peer]!.version, era),
+						)
+						.map((representative) => representative.path)
+					report.coverage.push({ peer, era, representatives: matching })
+					if (!matching.length)
+						report.errors.push(`No representative covers ${peer}: ${era}.`)
+				}
+			}
+		} else if (
+			!representatives.some(
+				(representative) => representative.suites.length > 0,
+			)
+		) {
+			report.errors.push(
+				`No representative matched the requested test selection.`,
+			)
+		}
+		if (
+			support.status === `setup-error` ||
+			report.errors.length ||
+			representatives.some((result) => result.status === `setup-error`)
+		)
+			report.exitCode = 2
+		else if (
+			support.status === `end-of-support` ||
+			representatives.some(
+				(result) => result.status === `compatibility-failure`,
+			)
+		)
+			report.exitCode = 1
+	} catch (error) {
+		report.errors.push(errorMessage(error))
+		report.exitCode = 2
+	}
+	return report
+}
+
+export async function npmCheck(
+	config: NpmConfig,
+	options: { baseDirectory?: string; coverageOnly?: boolean } = {},
+): Promise<NpmReport> {
+	return await run(
+		config,
+		options.baseDirectory ?? process.cwd(),
+		options.coverageOnly ?? false,
+	)
+}
+
+export async function npmTest(
+	config: NpmConfig,
+	selection: NpmTestSelection,
+	options: { baseDirectory?: string } = {},
+): Promise<NpmReport> {
+	return await run(
+		config,
+		options.baseDirectory ?? process.cwd(),
+		false,
+		selection,
+	)
+}
+
+export function formatNpmReport(report: NpmReport): string {
+	const lines = [
+		`${report.package.name}@${report.package.version} — npm ${report.mode}`,
+	]
+	for (const result of report.representatives) {
+		lines.push(`${result.path}: ${result.status}`)
+		for (const [peer, evidence] of Object.entries(result.peers)) {
+			lines.push(
+				`  ${peer}@${evidence.version}${evidence.source === `candidate` ? ` (conditional on publication)` : ` (installed)`}`,
+			)
+		}
+		for (const suite of result.suites) {
+			lines.push(`  ${suite.peer}: ${suite.status}`)
+			if (suite.status !== `passed` && suite.output) lines.push(suite.output)
+		}
+		for (const warning of result.warnings) lines.push(`  Warning: ${warning}`)
+		if (result.error) lines.push(`  ${result.error}`)
+	}
+	lines.push(`Support: ${report.support.status}`)
+	for (const change of report.support.changes)
+		lines.push(
+			`  ${change.peer}: ${change.previous ?? `(unrestricted)`} → ${change.current ?? `(unrestricted)`} (${change.reason})`,
+		)
+	if (report.support.release)
+		lines.push(
+			`  Intended release: ${report.support.release.version} (${report.support.release.delta})`,
+		)
+	if (report.support.error) lines.push(report.support.error)
+	lines.push(...report.errors)
+	if (report.mode === `coverage-only`)
+		lines.push(
+			`Coverage audit only; compatibility assertions were not executed.`,
+		)
+	return `${lines.join(`\n`)}\n`
+}

package/src/npm/cli.ts

@@ -0,0 +1,126 @@
+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 { formatNpmReport, npmCheck, npmTest } from "./check.ts"
+import { errorMessage } from "./command.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 CheckOptions = CommonOptions & { coverageOnly?: boolean | undefined }
+type TestOptions = CommonOptions & { representative?: string | undefined }
+
+const common = {
+	config: {
+		required: false,
+		description: `Configuration file (defaults to breakage.config.ts, then .json).`,
+		example: `--config ./breakage.config.ts`,
+		completion: { fileSystem: `files` as const, repeatable: false },
+	},
+	json: {
+		required: false,
+		description: `Emit the structured result.`,
+		example: `--json`,
+		parse: parseBooleanOption,
+	},
+}
+
+export const npmCheckManual: OptionsGroup<CheckOptions> = options(
+	`Check npm peer compatibility and changes in declared support.`,
+	type({ "config?": `string`, "json?": `boolean`, "coverageOnly?": `boolean` }),
+	{
+		...common,
+		coverageOnly: {
+			aliases: [`coverage-only`],
+			required: false,
+			description: `Audit coverage and support changes without executing assertions.`,
+			example: `--coverage-only`,
+			parse: parseBooleanOption,
+		},
+	},
+)
+
+export const npmTestManual: OptionsGroup<TestOptions> = options(
+	`Run current contracts in matching complete peer environments.`,
+	type({
+		"config?": `string`,
+		"json?": `boolean`,
+		"representative?": `string`,
+	}),
+	{
+		...common,
+		representative: {
+			required: false,
+			description: `Select an exact configured representative path relative to the package.`,
+			example: `--representative peer-environments/react-19`,
+			completion: { fileSystem: `directories`, repeatable: false },
+		},
+	},
+)
+
+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,
+	peerSelection?: { peer: string; range: string },
+): 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
+		validateConfig(config)
+		let selection: NpmTestSelection | undefined
+		if (action === `test`) {
+			if (peerSelection && opts.representative)
+				throw new Error(`Choose a peer range or a representative, not both.`)
+			selection =
+				peerSelection ??
+				(opts.representative
+					? { representative: opts.representative }
+					: undefined)
+			if (!selection)
+				throw new Error(
+					`Use npm test <peer> <range> or npm test --representative <path>.`,
+				)
+		}
+		const options = {
+			baseDirectory: path.dirname(filename),
+			coverageOnly: opts.coverageOnly ?? false,
+		}
+		const report = selection
+			? await npmTest(config, selection, options)
+			: await npmCheck(config, options)
+		process.stdout.write(
+			opts.json
+				? `${JSON.stringify(report, null, 2)}\n`
+				: formatNpmReport(report),
+		)
+		return report.exitCode
+	} catch (error) {
+		const message = errorMessage(error)
+		process.stdout.write(
+			opts.json
+				? `${JSON.stringify({ exitCode: 2, errors: [message] })}\n`
+				: `npm setup error: ${message}\n`,
+		)
+		return 2
+	}
+}

package/src/npm/command.ts

@@ -0,0 +1,52 @@
+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> {
+	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)
+}

package/src/npm/config.ts

@@ -0,0 +1,86 @@
+import path from "node:path"
+
+import { eras, packageName, record } from "./manifest.ts"
+import type { NpmConfig } from "./types.ts"
+
+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) {
+		if (!nonempty(value[key]))
+			throw new Error(`npm.${key} must be a nonempty string.`)
+	}
+	if (
+		path.isAbsolute(value.lockfile as string) ||
+		(value.lockfile as string).split(/[\\/]/).includes(`..`)
+	) {
+		throw new Error(`npm.lockfile must stay inside each representative.`)
+	}
+	for (const key of [`packageDirectory`, `installCommand`] as const) {
+		if (value[key] !== undefined && !nonempty(value[key]))
+			throw new Error(`Invalid npm.${key}.`)
+	}
+	const globs =
+		typeof value.representatives === `string`
+			? [value.representatives]
+			: value.representatives
+	if (
+		!Array.isArray(globs) ||
+		!globs.length ||
+		globs.some((glob: unknown) => !nonempty(glob))
+	) {
+		throw new Error(`npm.representatives must contain directory globs.`)
+	}
+	if (!record(value.suites) || !Object.keys(value.suites).length)
+		throw new Error(`Configure at least one npm peer suite.`)
+	for (const [peer, suite] of Object.entries(value.suites)) {
+		if (
+			!packageName(peer) ||
+			!record(suite) ||
+			!nonempty(suite.command) ||
+			!Array.isArray(suite.files) ||
+			!suite.files.length ||
+			suite.files.some((file: unknown) => !nonempty(file))
+		) {
+			throw new Error(`Invalid npm suite for ${peer}.`)
+		}
+	}
+	if (
+		!record(value.baseline) ||
+		(`firstRelease` in value.baseline
+			? value.baseline.firstRelease !== true ||
+				Object.keys(value.baseline).length !== 1
+			: Object.entries(value.baseline).some(
+					([key, item]) =>
+						![`tagPattern`, `baselineFile`].includes(key) || !nonempty(item),
+				))
+	) {
+		throw new Error(
+			`Configure npm.baseline with tagPattern/baselineFile or { firstRelease: true }.`,
+		)
+	}
+	if (value.localPeers !== undefined) {
+		if (!record(value.localPeers)) throw new Error(`Invalid npm.localPeers.`)
+		for (const [peer, local] of Object.entries(value.localPeers)) {
+			if (
+				!packageName(peer) ||
+				!record(local) ||
+				!nonempty(local.directory) ||
+				!nonempty(local.artifact)
+			) {
+				throw new Error(`Invalid local peer ${peer}.`)
+			}
+		}
+	}
+	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 {
+	for (const range of Object.values(peers)) eras(range)
+}