breakage 0.8.3 → 0.8.5

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,189 @@
+import path from "node:path"
+
+import semver from "semver"
+import { simpleGit } from "simple-git"
+
+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"
+
+export async function intent(
+	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 }
+}
+
+/**
+ * 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,104 @@
+export type ReleaseIntent =
+	| { status: `none` }
+	| { status: `release`; version: string }
+
+export type ReleaseContext = {
+	packageName: string
+	packageDirectory: string
+	currentVersion: string
+}
+
+export type SupportChange = {
+	peer: string
+	reason: `narrowed-range` | `required-peer`
+	previous: string | null
+	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 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`
+			| `certified`
+			| `end-of-support`
+			| `first-release`
+			| `not-checked`
+			| `setup-error`
+		changes: SupportChange[]
+		previousVersion?: string
+		release?: ReleaseEvidence
+		error?: string
+	}
+	errors: string[]
+}