breakage 0.0.0-stage → 0.0.0

package/src/breakage.x.ts

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+
+import * as path from "node:path"
+import { inspect } from "node:util"
+
+import { type } from "arktype"
+import type { OptionsGroup } from "comline"
+import {
+	cli,
+	completionResponse,
+	encapsulate,
+	help,
+	logWarnings,
+	noOptions,
+	optional,
+	options,
+	parseBooleanOption,
+} from "comline"
+import logger from "takua"
+
+import type { BreakageOptions } from "./breakage.ts"
+import { breakage } from "./breakage.ts"
+
+const BREAKAGE_MANUAL = options(
+	`Check for breaking changes in a package.`,
+	type({
+		"tagPattern?": `string`,
+		testPattern: `string`,
+		testCommand: `string`,
+		certifyCommand: `string`,
+		"baseDirname?": `string`,
+		"verbose?": `boolean`,
+	}),
+	{
+		tagPattern: {
+			aliases: [`tag-pattern`],
+			completion: { repeatable: false },
+			flag: `g`,
+			required: false,
+			description: `RegExp which, if found matched to a git tag, will be considered a release tag for your library.`,
+			example: `--tagPattern="my-library"`,
+		},
+		testPattern: {
+			aliases: [`test-pattern`, `pattern`],
+			completion: { repeatable: false },
+			flag: `p`,
+			required: true,
+			description: `The pattern to match test files that test the public API of the library.`,
+			example: `--pattern="*__public.test.ts"`,
+		},
+		testCommand: {
+			aliases: [`test-command`],
+			completion: { repeatable: false },
+			flag: `t`,
+			required: true,
+			description: `Complete bash command that runs the tests for the library's public API.`,
+			example: `--testCommand="npm run test"`,
+		},
+		certifyCommand: {
+			aliases: [`certify-command`],
+			completion: { repeatable: false },
+			flag: `c`,
+			required: true,
+			description: `Complete bash command that determines whether a major version bump for your package is indicated in the workspace. Exit code 0 indicates that a major version bump is indicated, and exit code 1 indicates that no major version bump is indicated.`,
+			example: `--certifyCommand=\tsx scripts/certify-major-version-bump.node`,
+		},
+		baseDirname: {
+			aliases: [`base-dir`, `base-dirname`],
+			completion: { repeatable: false, fileSystem: `directories` },
+			flag: `d`,
+			required: false,
+			description: `The base directory to run the command from.`,
+			example: `--baseDirname=./packages/my-package`,
+		},
+		verbose: {
+			completion: { repeatable: false },
+			flag: `v`,
+			required: false,
+			description: `Prints out more information about the process.`,
+			example: `--verbose`,
+			parse: parseBooleanOption,
+		},
+	},
+) satisfies OptionsGroup<BreakageOptions>
+
+const SCHEMA_MANUAL = options(
+	`Create a copy of the schema for configuring breakage.`,
+	type({ "outdir?": `string` }),
+	{
+		outdir: {
+			aliases: [`out-dir`],
+			completion: { repeatable: false, fileSystem: `directories` },
+			flag: `o`,
+			required: false,
+			description: `Directory to write the schema to.`,
+			example: `--outdir=./dist`,
+		},
+	},
+)
+
+const parse = cli(
+	{
+		cliName: `breakage`,
+		routes: optional({ help: null, schema: null, $configPath: null }),
+		routeOptions: {
+			"": BREAKAGE_MANUAL,
+			$configPath: BREAKAGE_MANUAL,
+			help: noOptions(`Show usage.`),
+			schema: SCHEMA_MANUAL,
+		},
+		positionalCompletions: { $configPath: { fileSystem: `files` } },
+		discoverConfigPath: (args: readonly string[]) => {
+			if (args[0] === `help` || args[0] === `schema`) {
+				return
+			}
+			const configPath =
+				args[0] ?? path.join(process.cwd(), `breakage.config.json`)
+			return configPath
+		},
+	},
+	{
+		info: (message, ...data) => logger.info(`breakage`, message, data),
+		error: (message, ...data) => logger.error(`breakage`, message, data),
+	},
+)
+
+const completion = await completionResponse(parse.definition, process.argv)
+if (completion !== undefined) {
+	process.stdout.write(completion)
+} else {
+	const { inputs, warnings, writeJsonSchema } = parse(process.argv)
+	logWarnings(warnings)
+
+	switch (inputs.case) {
+		case `help`:
+			console.log(help(parse.definition))
+			break
+		case `schema`:
+			{
+				const { outdir } = inputs.opts
+				writeJsonSchema(outdir ?? `.`)
+				process.stdout.write(`📝 Wrote json.schema.`)
+			}
+			break
+		case ``:
+		case `$configPath`: {
+			const { returnValue } = await encapsulate(() => breakage(inputs.opts), {
+				console: true,
+				stdout: true,
+			})
+			if (`testResult` in returnValue && returnValue.breakingChangesFound) {
+				process.stdout.write(returnValue.testResult)
+			}
+			if (`breakingChangesFound` in returnValue) {
+				if (returnValue.breakingChangesFound) {
+					if (returnValue.breakingChangesCertified) {
+						process.stdout.write(
+							`👷 Breaking changes were found and certified.`,
+						)
+						process.exit(0)
+					} else {
+						process.stdout.write(
+							`❌ Breaking changes were found, but not certified.`,
+						)
+						process.exit(1)
+					}
+				} else {
+					process.stdout.write(`✅ No breaking changes were found.`)
+					process.exit(0)
+				}
+			} else {
+				process.stdout.write(
+					`💥 Breakage failed to determine breaking changes.` +
+						`\n` +
+						inspect(returnValue),
+				)
+				process.exit(2)
+			}
+		}
+	}
+}

package/src/directory-lock.ts

@@ -0,0 +1,29 @@
+import { mkdir, rmdir } from "node:fs/promises"
+import { setTimeout } from "node:timers/promises"
+
+export async function withDirectoryLock<T>(
+	lock: string,
+	action: () => Promise<T>,
+	waitForCleanup = false,
+): Promise<T> {
+	const deadline = Date.now() + 60_000
+	for (;;) {
+		try {
+			await mkdir(lock)
+			break
+		} catch (thrown) {
+			if ((thrown as NodeJS.ErrnoException).code !== `EEXIST`) throw thrown
+			if (!waitForCleanup && Date.now() >= deadline) {
+				throw new Error(
+					`Timed out waiting for ${lock}. Check for an interrupted operation before removing this lock.`,
+				)
+			}
+			await setTimeout(20)
+		}
+	}
+	try {
+		return await action()
+	} finally {
+		await rmdir(lock)
+	}
+}

package/src/release-tag.ts

@@ -0,0 +1,62 @@
+type Release = { ref: string; core: string[]; prerelease: string[] }
+
+function compareInteger(a: string, b: string): number {
+	return a.length - b.length || (a > b ? 1 : a < b ? -1 : 0)
+}
+
+function compareRelease(a: Release, b: Release): number {
+	for (let index = 0; index < 3; index++) {
+		const difference = compareInteger(a.core[index]!, b.core[index]!)
+		if (difference) return difference
+	}
+	if (!a.prerelease.length || !b.prerelease.length) {
+		return Number(!a.prerelease.length) - Number(!b.prerelease.length)
+	}
+	for (
+		let index = 0;
+		index < Math.min(a.prerelease.length, b.prerelease.length);
+		index++
+	) {
+		const left = a.prerelease[index]!
+		const right = b.prerelease[index]!
+		const leftNumeric = /^\d+$/.test(left)
+		const rightNumeric = /^\d+$/.test(right)
+		const difference =
+			leftNumeric && rightNumeric
+				? compareInteger(left, right)
+				: leftNumeric !== rightNumeric
+					? Number(rightNumeric) - Number(leftNumeric)
+					: left > right
+						? 1
+						: left < right
+							? -1
+							: 0
+		if (difference) return difference
+	}
+	return a.prerelease.length - b.prerelease.length
+}
+
+export function latestReleaseTag(
+	remoteTags: string,
+	tagPattern?: string,
+): string | undefined {
+	const pattern = tagPattern ? new RegExp(tagPattern) : undefined
+	let latest: Release | undefined
+	for (const line of remoteTags.split(`\n`)) {
+		if (pattern && !pattern.test(line)) continue
+		const ref = line.split(`\t`)[1]?.replace(/\^\{\}$/, ``)
+		if (!ref?.startsWith(`refs/tags/`)) continue
+		const name = ref.slice(`refs/tags/`.length)
+		const version = name.slice(name.lastIndexOf(`@`) + 1)
+		const match =
+			/^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(
+				version,
+			)
+		if (!match) continue
+		const prerelease = match[4]?.split(`.`) ?? []
+		if (prerelease.some((identifier) => /^0\d+$/.test(identifier))) continue
+		const release: Release = { ref, core: match.slice(1, 4), prerelease }
+		if (!latest || compareRelease(release, latest) > 0) latest = release
+	}
+	return latest?.ref
+}

package/src/test-file-state.ts

@@ -0,0 +1,252 @@
+import { randomUUID } from "node:crypto"
+import {
+	chmod,
+	lstat,
+	mkdir,
+	readdir,
+	readFile,
+	realpath,
+	rename,
+	rm,
+	writeFile,
+} from "node:fs/promises"
+import path from "node:path"
+
+import type { SimpleGit } from "simple-git"
+import { simpleGit } from "simple-git"
+
+import { withDirectoryLock } from "./directory-lock.ts"
+
+type ActiveCheck = {
+	pid: number
+	paths: string[]
+	head: string
+	recoveryRequired?: boolean
+}
+
+function isActiveCheck(value: unknown): value is ActiveCheck {
+	if (typeof value !== `object` || value === null) return false
+	const record = value as Partial<ActiveCheck>
+	return (
+		typeof record.pid === `number` &&
+		Number.isSafeInteger(record.pid) &&
+		record.pid > 0 &&
+		typeof record.head === `string` &&
+		/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(record.head) &&
+		(record.recoveryRequired === undefined ||
+			typeof record.recoveryRequired === `boolean`) &&
+		Array.isArray(record.paths) &&
+		record.paths.length > 0 &&
+		record.paths.every(
+			(file) =>
+				typeof file === `string` &&
+				!path.isAbsolute(file) &&
+				!path.win32.isAbsolute(file) &&
+				file
+					.split(`/`)
+					.every((part) => part !== `` && part !== `.` && part !== `..`),
+		)
+	)
+}
+
+async function readRecoveryRecord(recordPath: string): Promise<ActiveCheck> {
+	try {
+		const record: unknown = JSON.parse(await readFile(recordPath, `utf8`))
+		if (!isActiveCheck(record))
+			throw new TypeError(`Invalid recovery record fields`)
+		return record
+	} catch (cause) {
+		throw new Error(
+			`A breakage run needs recovery. The record ${recordPath} is unreadable or invalid. Verify no check is running and recover its test files before removing this record.`,
+			{ cause },
+		)
+	}
+}
+
+async function writeRecoveryRecord(
+	recordPath: string,
+	record: ActiveCheck,
+): Promise<void> {
+	const temporaryPath = `${recordPath}.${randomUUID()}.tmp`
+	try {
+		await writeFile(temporaryPath, JSON.stringify(record), { flag: `wx` })
+		await rename(temporaryPath, recordPath)
+	} finally {
+		await rm(temporaryPath, { force: true })
+	}
+}
+
+type TestFileState = {
+	isClean: () => Promise<boolean>
+	replaceTests: (
+		release: string,
+		files: string[],
+	) => Promise<() => Promise<void>>
+}
+
+function assertContained(root: string, filename: string): void {
+	const relative = path.relative(root, filename)
+	if (
+		relative === `..` ||
+		relative.startsWith(`..${path.sep}`) ||
+		path.isAbsolute(relative)
+	) {
+		throw new Error(`Cannot replace tests outside the worktree: ${filename}.`)
+	}
+}
+
+async function validateParents(
+	root: string,
+	filenames: string[],
+): Promise<void> {
+	const checked = new Set<string>()
+	for (const filename of filenames) {
+		assertContained(root, filename)
+		for (let parent = path.dirname(filename); ; parent = path.dirname(parent)) {
+			if (checked.has(parent)) break
+			const stats = await lstat(parent).catch(
+				(thrown: NodeJS.ErrnoException) => {
+					if (thrown.code !== `ENOENT`) throw thrown
+				},
+			)
+			if (stats && !stats.isDirectory())
+				throw new Error(`Cannot replace tests through ${parent}.`)
+			checked.add(parent)
+			if (parent === root) break
+		}
+	}
+}
+
+// This lock covers Git setup and restoration only. Commands run after it is released.
+export async function withTestFileState<T>(
+	git: SimpleGit,
+	baseDirname: string,
+	action: (state: TestFileState) => Promise<T>,
+): Promise<T> {
+	const root = await realpath(await git.revparse([`--show-toplevel`]))
+	baseDirname = await realpath(baseDirname)
+	assertContained(root, baseDirname)
+	const stateDirectory = path.join(
+		await git.revparse([`--absolute-git-dir`]),
+		`breakage`,
+	)
+	await mkdir(stateDirectory, { recursive: true })
+	const lock = path.join(stateDirectory, `lock`)
+	return withDirectoryLock(lock, async () => {
+		const activeChecks: ActiveCheck[] = []
+		for (const entry of await readdir(stateDirectory)) {
+			if (!entry.endsWith(`.json`)) continue
+			const recordPath = path.join(stateDirectory, entry)
+			const record = await readRecoveryRecord(recordPath)
+			let interrupted = record.recoveryRequired
+			try {
+				process.kill(record.pid, 0)
+			} catch (thrown) {
+				if ((thrown as NodeJS.ErrnoException).code !== `EPERM`)
+					interrupted = true
+			}
+			if (interrupted)
+				throw new Error(
+					`A breakage run needs recovery. Restore the test paths recorded in ${recordPath} before removing that record.`,
+				)
+			activeChecks.push(record)
+		}
+		const activePaths = activeChecks.flatMap((record) => record.paths)
+		return action({
+			isClean: async () =>
+				!(await simpleGit(root).raw([
+					`--no-optional-locks`,
+					`status`,
+					`--porcelain`,
+					`--untracked-files=all`,
+					`--`,
+					`.`,
+					...activePaths.map((file) => `:(top,literal,exclude)${file}`),
+				])),
+			replaceTests: async (release, files) => {
+				const paths = files.map((file) =>
+					path
+						.relative(root, path.resolve(baseDirname, file))
+						.split(path.sep)
+						.join(`/`),
+				)
+				for (const file of paths) {
+					if (
+						activePaths.some(
+							(active) =>
+								file === active ||
+								file.startsWith(`${active}/`) ||
+								active.startsWith(`${file}/`),
+						)
+					) {
+						throw new Error(
+							`Another breakage run is using ${file}. Concurrent checks must use disjoint test paths.`,
+						)
+					}
+				}
+				const head = await git.revparse([`HEAD`])
+				const currentFiles = new Set(
+					(await git.raw([`ls-tree`, `-r`, `--name-only`, `-z`, head]))
+						.split(`\0`)
+						.filter(Boolean),
+				)
+				const existing = files.filter((file) => currentFiles.has(file))
+				const absent = files.filter((file) => !currentFiles.has(file))
+				const modes = new Map<string, number>()
+				const filenames = files.map((file) => path.resolve(baseDirname, file))
+				await validateParents(root, filenames)
+				for (const file of files) {
+					const filename = path.resolve(baseDirname, file)
+
+					const stats = await lstat(filename).catch(
+						(thrown: NodeJS.ErrnoException) => {
+							if (thrown.code !== `ENOENT`) throw thrown
+						},
+					)
+					if (!currentFiles.has(file) && stats)
+						throw new Error(
+							`Cannot overwrite the existing untracked path ${filename}.`,
+						)
+					if (stats?.isFile()) modes.set(filename, stats.mode)
+				}
+				const recordPath = path.join(stateDirectory, `${randomUUID()}.json`)
+				const record: ActiveCheck = { pid: process.pid, paths, head }
+				await writeRecoveryRecord(recordPath, record)
+				const restore = async () => {
+					await writeRecoveryRecord(recordPath, {
+						...record,
+						recoveryRequired: true,
+					})
+					await validateParents(root, filenames)
+					if (existing.length)
+						await git.raw([
+							`--literal-pathspecs`,
+							`restore`,
+							`--source=${head}`,
+							`--worktree`,
+							`--`,
+							...existing,
+						])
+					for (const file of absent)
+						await rm(path.resolve(baseDirname, file), { force: true })
+					for (const [filename, mode] of modes) await chmod(filename, mode)
+					await rm(recordPath)
+				}
+				try {
+					await git.raw([
+						`--literal-pathspecs`,
+						`restore`,
+						`--source=${release}`,
+						`--worktree`,
+						`--`,
+						...files,
+					])
+				} catch (thrown) {
+					await restore()
+					throw thrown
+				}
+				return () => withDirectoryLock(lock, restore, true)
+			},
+		})
+	})
+}