breakage 0.0.0 → 0.8.2

package/dist/breakage.x.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as breakage } from "./breakage-D_nc-zEK.js";
+import { n as breakagePrelude, t as breakage } from "./breakage-Dc4IldeW.js";
 import * as path$1 from "node:path";
 import logger from "takua";
 import { inspect } from "node:util";
@@ -8,6 +8,7 @@ import { cli, completionResponse, encapsulate, help, logWarnings, noOptions, opt
 //#region src/breakage.x.ts
 const BREAKAGE_MANUAL = options(`Check for breaking changes in a package.`, type({
 	"tagPattern?": `string`,
+	"baselineFile?": `string`,
 	testPattern: `string`,
 	testCommand: `string`,
 	certifyCommand: `string`,
@@ -22,6 +23,16 @@ const BREAKAGE_MANUAL = options(`Check for breaking changes in a package.`, type
 		description: `RegExp which, if found matched to a git tag, will be considered a release tag for your library.`,
 		example: `--tagPattern="my-library"`
 	},
+	baselineFile: {
+		aliases: [`baseline-file`],
+		completion: {
+			repeatable: false,
+			fileSystem: `files`
+		},
+		required: false,
+		description: `Use the exact locally fetched commit from a prelude snapshot instead of discovering remote tags.`,
+		example: `--baseline-file=.breakage/baseline.json`
+	},
 	testPattern: {
 		aliases: [`test-pattern`, `pattern`],
 		completion: { repeatable: false },
@@ -66,6 +77,39 @@ const BREAKAGE_MANUAL = options(`Check for breaking changes in a package.`, type
 		parse: parseBooleanOption
 	}
 });
+const PRELUDE_MANUAL = options(`Resolve and fetch the release baseline for a cacheable compatibility check.`, type({
+	"tagPattern?": `string`,
+	"baseDirname?": `string`,
+	"out?": `string`,
+	"testPattern?": `string`,
+	"testCommand?": `string`,
+	"certifyCommand?": `string`,
+	"baselineFile?": `string`,
+	"verbose?": `boolean`
+}), {
+	...BREAKAGE_MANUAL.optionConfigs,
+	testPattern: {
+		...BREAKAGE_MANUAL.optionConfigs.testPattern,
+		required: false
+	},
+	testCommand: {
+		...BREAKAGE_MANUAL.optionConfigs.testCommand,
+		required: false
+	},
+	certifyCommand: {
+		...BREAKAGE_MANUAL.optionConfigs.certifyCommand,
+		required: false
+	},
+	out: {
+		completion: {
+			repeatable: false,
+			fileSystem: `files`
+		},
+		required: false,
+		description: `Gitignored snapshot path relative to the base directory (default: .breakage/baseline.json).`,
+		example: `--out=.breakage/baseline.json`
+	}
+});
 const SCHEMA_MANUAL = options(`Create a copy of the schema for configuring breakage.`, type({ "outdir?": `string` }), { outdir: {
 	aliases: [`out-dir`],
 	completion: {
@@ -82,18 +126,24 @@ const parse = cli({
 	routes: optional({
 		help: null,
 		schema: null,
+		prelude: optional({ $configPath: null }),
 		$configPath: null
 	}),
 	routeOptions: {
 		"": BREAKAGE_MANUAL,
 		$configPath: BREAKAGE_MANUAL,
 		help: noOptions(`Show usage.`),
-		schema: SCHEMA_MANUAL
+		schema: SCHEMA_MANUAL,
+		prelude: PRELUDE_MANUAL,
+		"prelude/$configPath": PRELUDE_MANUAL
+	},
+	positionalCompletions: {
+		$configPath: { fileSystem: `files` },
+		"prelude/$configPath": { fileSystem: `files` }
 	},
-	positionalCompletions: { $configPath: { fileSystem: `files` } },
 	discoverConfigPath: (args) => {
 		if (args[0] === `help` || args[0] === `schema`) return;
-		return args[0] ?? path$1.join(process.cwd(), `breakage.config.json`);
+		return (args[0] === `prelude` ? args[1] : args[0]) ?? path$1.join(process.cwd(), `breakage.config.json`);
 	}
 }, {
 	info: (message, ...data) => logger.info(`breakage`, message, data),
@@ -115,6 +165,15 @@ else {
 				process.stdout.write(`📝 Wrote json.schema.`);
 			}
 			break;
+		case `prelude`:
+		case `prelude/$configPath`: {
+			const baseline = await breakagePrelude({
+				...inputs.opts,
+				out: inputs.opts.out ?? `.breakage/baseline.json`
+			});
+			process.stdout.write(`Pinned ${baseline.ref} at ${baseline.commit}.\n`);
+			break;
+		}
 		case ``:
 		case `$configPath`: {
 			const { returnValue } = await encapsulate(() => breakage(inputs.opts), {

package/dist/breakage.x.js.map

@@ -1 +1 @@
-{"version":3,"file":"breakage.x.js","names":["path"],"sources":["../src/breakage.x.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport * as path from \"node:path\"\nimport { inspect } from \"node:util\"\n\nimport { type } from \"arktype\"\nimport type { OptionsGroup } from \"comline\"\nimport {\n\tcli,\n\tcompletionResponse,\n\tencapsulate,\n\thelp,\n\tlogWarnings,\n\tnoOptions,\n\toptional,\n\toptions,\n\tparseBooleanOption,\n} from \"comline\"\nimport logger from \"takua\"\n\nimport type { BreakageOptions } from \"./breakage.ts\"\nimport { breakage } from \"./breakage.ts\"\n\nconst BREAKAGE_MANUAL = options(\n\t`Check for breaking changes in a package.`,\n\ttype({\n\t\t\"tagPattern?\": `string`,\n\t\ttestPattern: `string`,\n\t\ttestCommand: `string`,\n\t\tcertifyCommand: `string`,\n\t\t\"baseDirname?\": `string`,\n\t\t\"verbose?\": `boolean`,\n\t}),\n\t{\n\t\ttagPattern: {\n\t\t\taliases: [`tag-pattern`],\n\t\t\tcompletion: { repeatable: false },\n\t\t\tflag: `g`,\n\t\t\trequired: false,\n\t\t\tdescription: `RegExp which, if found matched to a git tag, will be considered a release tag for your library.`,\n\t\t\texample: `--tagPattern=\"my-library\"`,\n\t\t},\n\t\ttestPattern: {\n\t\t\taliases: [`test-pattern`, `pattern`],\n\t\t\tcompletion: { repeatable: false },\n\t\t\tflag: `p`,\n\t\t\trequired: true,\n\t\t\tdescription: `The pattern to match test files that test the public API of the library.`,\n\t\t\texample: `--pattern=\"*__public.test.ts\"`,\n\t\t},\n\t\ttestCommand: {\n\t\t\taliases: [`test-command`],\n\t\t\tcompletion: { repeatable: false },\n\t\t\tflag: `t`,\n\t\t\trequired: true,\n\t\t\tdescription: `Complete bash command that runs the tests for the library's public API.`,\n\t\t\texample: `--testCommand=\"npm run test\"`,\n\t\t},\n\t\tcertifyCommand: {\n\t\t\taliases: [`certify-command`],\n\t\t\tcompletion: { repeatable: false },\n\t\t\tflag: `c`,\n\t\t\trequired: true,\n\t\t\tdescription: `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.`,\n\t\t\texample: `--certifyCommand=\\tsx scripts/certify-major-version-bump.node`,\n\t\t},\n\t\tbaseDirname: {\n\t\t\taliases: [`base-dir`, `base-dirname`],\n\t\t\tcompletion: { repeatable: false, fileSystem: `directories` },\n\t\t\tflag: `d`,\n\t\t\trequired: false,\n\t\t\tdescription: `The base directory to run the command from.`,\n\t\t\texample: `--baseDirname=./packages/my-package`,\n\t\t},\n\t\tverbose: {\n\t\t\tcompletion: { repeatable: false },\n\t\t\tflag: `v`,\n\t\t\trequired: false,\n\t\t\tdescription: `Prints out more information about the process.`,\n\t\t\texample: `--verbose`,\n\t\t\tparse: parseBooleanOption,\n\t\t},\n\t},\n) satisfies OptionsGroup<BreakageOptions>\n\nconst SCHEMA_MANUAL = options(\n\t`Create a copy of the schema for configuring breakage.`,\n\ttype({ \"outdir?\": `string` }),\n\t{\n\t\toutdir: {\n\t\t\taliases: [`out-dir`],\n\t\t\tcompletion: { repeatable: false, fileSystem: `directories` },\n\t\t\tflag: `o`,\n\t\t\trequired: false,\n\t\t\tdescription: `Directory to write the schema to.`,\n\t\t\texample: `--outdir=./dist`,\n\t\t},\n\t},\n)\n\nconst parse = cli(\n\t{\n\t\tcliName: `breakage`,\n\t\troutes: optional({ help: null, schema: null, $configPath: null }),\n\t\trouteOptions: {\n\t\t\t\"\": BREAKAGE_MANUAL,\n\t\t\t$configPath: BREAKAGE_MANUAL,\n\t\t\thelp: noOptions(`Show usage.`),\n\t\t\tschema: SCHEMA_MANUAL,\n\t\t},\n\t\tpositionalCompletions: { $configPath: { fileSystem: `files` } },\n\t\tdiscoverConfigPath: (args: readonly string[]) => {\n\t\t\tif (args[0] === `help` || args[0] === `schema`) {\n\t\t\t\treturn\n\t\t\t}\n\t\t\tconst configPath =\n\t\t\t\targs[0] ?? path.join(process.cwd(), `breakage.config.json`)\n\t\t\treturn configPath\n\t\t},\n\t},\n\t{\n\t\tinfo: (message, ...data) => logger.info(`breakage`, message, data),\n\t\terror: (message, ...data) => logger.error(`breakage`, message, data),\n\t},\n)\n\nconst completion = await completionResponse(parse.definition, process.argv)\nif (completion !== undefined) {\n\tprocess.stdout.write(completion)\n} else {\n\tconst { inputs, warnings, writeJsonSchema } = parse(process.argv)\n\tlogWarnings(warnings)\n\n\tswitch (inputs.case) {\n\t\tcase `help`:\n\t\t\tconsole.log(help(parse.definition))\n\t\t\tbreak\n\t\tcase `schema`:\n\t\t\t{\n\t\t\t\tconst { outdir } = inputs.opts\n\t\t\t\twriteJsonSchema(outdir ?? `.`)\n\t\t\t\tprocess.stdout.write(`📝 Wrote json.schema.`)\n\t\t\t}\n\t\t\tbreak\n\t\tcase ``:\n\t\tcase `$configPath`: {\n\t\t\tconst { returnValue } = await encapsulate(() => breakage(inputs.opts), {\n\t\t\t\tconsole: true,\n\t\t\t\tstdout: true,\n\t\t\t})\n\t\t\tif (`testResult` in returnValue && returnValue.breakingChangesFound) {\n\t\t\t\tprocess.stdout.write(returnValue.testResult)\n\t\t\t}\n\t\t\tif (`breakingChangesFound` in returnValue) {\n\t\t\t\tif (returnValue.breakingChangesFound) {\n\t\t\t\t\tif (returnValue.breakingChangesCertified) {\n\t\t\t\t\t\tprocess.stdout.write(\n\t\t\t\t\t\t\t`👷 Breaking changes were found and certified.`,\n\t\t\t\t\t\t)\n\t\t\t\t\t\tprocess.exit(0)\n\t\t\t\t\t} else {\n\t\t\t\t\t\tprocess.stdout.write(\n\t\t\t\t\t\t\t`❌ Breaking changes were found, but not certified.`,\n\t\t\t\t\t\t)\n\t\t\t\t\t\tprocess.exit(1)\n\t\t\t\t\t}\n\t\t\t\t} else {\n\t\t\t\t\tprocess.stdout.write(`✅ No breaking changes were found.`)\n\t\t\t\t\tprocess.exit(0)\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tprocess.stdout.write(\n\t\t\t\t\t`💥 Breakage failed to determine breaking changes.` +\n\t\t\t\t\t\t`\\n` +\n\t\t\t\t\t\tinspect(returnValue),\n\t\t\t\t)\n\t\t\t\tprocess.exit(2)\n\t\t\t}\n\t\t}\n\t}\n}\n"],"mappings":"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"}
+{"version":3,"file":"breakage.x.js","names":["path"],"sources":["../src/breakage.x.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport * as path from \"node:path\"\nimport { inspect } from \"node:util\"\n\nimport { type } from \"arktype\"\nimport type { OptionsGroup } from \"comline\"\nimport {\n\tcli,\n\tcompletionResponse,\n\tencapsulate,\n\thelp,\n\tlogWarnings,\n\tnoOptions,\n\toptional,\n\toptions,\n\tparseBooleanOption,\n} from \"comline\"\nimport logger from \"takua\"\n\nimport type { BreakageOptions } from \"./breakage.ts\"\nimport { breakage, breakagePrelude } from \"./breakage.ts\"\n\nconst BREAKAGE_MANUAL = options(\n\t`Check for breaking changes in a package.`,\n\ttype({\n\t\t\"tagPattern?\": `string`,\n\t\t\"baselineFile?\": `string`,\n\t\ttestPattern: `string`,\n\t\ttestCommand: `string`,\n\t\tcertifyCommand: `string`,\n\t\t\"baseDirname?\": `string`,\n\t\t\"verbose?\": `boolean`,\n\t}),\n\t{\n\t\ttagPattern: {\n\t\t\taliases: [`tag-pattern`],\n\t\t\tcompletion: { repeatable: false },\n\t\t\tflag: `g`,\n\t\t\trequired: false,\n\t\t\tdescription: `RegExp which, if found matched to a git tag, will be considered a release tag for your library.`,\n\t\t\texample: `--tagPattern=\"my-library\"`,\n\t\t},\n\t\tbaselineFile: {\n\t\t\taliases: [`baseline-file`],\n\t\t\tcompletion: { repeatable: false, fileSystem: `files` },\n\t\t\trequired: false,\n\t\t\tdescription: `Use the exact locally fetched commit from a prelude snapshot instead of discovering remote tags.`,\n\t\t\texample: `--baseline-file=.breakage/baseline.json`,\n\t\t},\n\t\ttestPattern: {\n\t\t\taliases: [`test-pattern`, `pattern`],\n\t\t\tcompletion: { repeatable: false },\n\t\t\tflag: `p`,\n\t\t\trequired: true,\n\t\t\tdescription: `The pattern to match test files that test the public API of the library.`,\n\t\t\texample: `--pattern=\"*__public.test.ts\"`,\n\t\t},\n\t\ttestCommand: {\n\t\t\taliases: [`test-command`],\n\t\t\tcompletion: { repeatable: false },\n\t\t\tflag: `t`,\n\t\t\trequired: true,\n\t\t\tdescription: `Complete bash command that runs the tests for the library's public API.`,\n\t\t\texample: `--testCommand=\"npm run test\"`,\n\t\t},\n\t\tcertifyCommand: {\n\t\t\taliases: [`certify-command`],\n\t\t\tcompletion: { repeatable: false },\n\t\t\tflag: `c`,\n\t\t\trequired: true,\n\t\t\tdescription: `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.`,\n\t\t\texample: `--certifyCommand=\\tsx scripts/certify-major-version-bump.node`,\n\t\t},\n\t\tbaseDirname: {\n\t\t\taliases: [`base-dir`, `base-dirname`],\n\t\t\tcompletion: { repeatable: false, fileSystem: `directories` },\n\t\t\tflag: `d`,\n\t\t\trequired: false,\n\t\t\tdescription: `The base directory to run the command from.`,\n\t\t\texample: `--baseDirname=./packages/my-package`,\n\t\t},\n\t\tverbose: {\n\t\t\tcompletion: { repeatable: false },\n\t\t\tflag: `v`,\n\t\t\trequired: false,\n\t\t\tdescription: `Prints out more information about the process.`,\n\t\t\texample: `--verbose`,\n\t\t\tparse: parseBooleanOption,\n\t\t},\n\t},\n) satisfies OptionsGroup<BreakageOptions>\n\nconst PRELUDE_MANUAL = options(\n\t`Resolve and fetch the release baseline for a cacheable compatibility check.`,\n\ttype({\n\t\t\"tagPattern?\": `string`,\n\t\t\"baseDirname?\": `string`,\n\t\t\"out?\": `string`,\n\t\t\"testPattern?\": `string`,\n\t\t\"testCommand?\": `string`,\n\t\t\"certifyCommand?\": `string`,\n\t\t\"baselineFile?\": `string`,\n\t\t\"verbose?\": `boolean`,\n\t}),\n\t{\n\t\t...BREAKAGE_MANUAL.optionConfigs,\n\t\ttestPattern: {\n\t\t\t...BREAKAGE_MANUAL.optionConfigs.testPattern,\n\t\t\trequired: false,\n\t\t},\n\t\ttestCommand: {\n\t\t\t...BREAKAGE_MANUAL.optionConfigs.testCommand,\n\t\t\trequired: false,\n\t\t},\n\t\tcertifyCommand: {\n\t\t\t...BREAKAGE_MANUAL.optionConfigs.certifyCommand,\n\t\t\trequired: false,\n\t\t},\n\t\tout: {\n\t\t\tcompletion: { repeatable: false, fileSystem: `files` },\n\t\t\trequired: false,\n\t\t\tdescription: `Gitignored snapshot path relative to the base directory (default: .breakage/baseline.json).`,\n\t\t\texample: `--out=.breakage/baseline.json`,\n\t\t},\n\t},\n)\n\nconst SCHEMA_MANUAL = options(\n\t`Create a copy of the schema for configuring breakage.`,\n\ttype({ \"outdir?\": `string` }),\n\t{\n\t\toutdir: {\n\t\t\taliases: [`out-dir`],\n\t\t\tcompletion: { repeatable: false, fileSystem: `directories` },\n\t\t\tflag: `o`,\n\t\t\trequired: false,\n\t\t\tdescription: `Directory to write the schema to.`,\n\t\t\texample: `--outdir=./dist`,\n\t\t},\n\t},\n)\n\nconst parse = cli(\n\t{\n\t\tcliName: `breakage`,\n\t\troutes: optional({\n\t\t\thelp: null,\n\t\t\tschema: null,\n\t\t\tprelude: optional({ $configPath: null }),\n\t\t\t$configPath: null,\n\t\t}),\n\t\trouteOptions: {\n\t\t\t\"\": BREAKAGE_MANUAL,\n\t\t\t$configPath: BREAKAGE_MANUAL,\n\t\t\thelp: noOptions(`Show usage.`),\n\t\t\tschema: SCHEMA_MANUAL,\n\t\t\tprelude: PRELUDE_MANUAL,\n\t\t\t\"prelude/$configPath\": PRELUDE_MANUAL,\n\t\t},\n\t\tpositionalCompletions: {\n\t\t\t$configPath: { fileSystem: `files` },\n\t\t\t\"prelude/$configPath\": { fileSystem: `files` },\n\t\t},\n\t\tdiscoverConfigPath: (args: readonly string[]) => {\n\t\t\tif (args[0] === `help` || args[0] === `schema`) {\n\t\t\t\treturn\n\t\t\t}\n\t\t\tconst configPath =\n\t\t\t\t(args[0] === `prelude` ? args[1] : args[0]) ??\n\t\t\t\tpath.join(process.cwd(), `breakage.config.json`)\n\t\t\treturn configPath\n\t\t},\n\t},\n\t{\n\t\tinfo: (message, ...data) => logger.info(`breakage`, message, data),\n\t\terror: (message, ...data) => logger.error(`breakage`, message, data),\n\t},\n)\n\nconst completion = await completionResponse(parse.definition, process.argv)\nif (completion !== undefined) {\n\tprocess.stdout.write(completion)\n} else {\n\tconst { inputs, warnings, writeJsonSchema } = parse(process.argv)\n\tlogWarnings(warnings)\n\n\tswitch (inputs.case) {\n\t\tcase `help`:\n\t\t\tconsole.log(help(parse.definition))\n\t\t\tbreak\n\t\tcase `schema`:\n\t\t\t{\n\t\t\t\tconst { outdir } = inputs.opts\n\t\t\t\twriteJsonSchema(outdir ?? `.`)\n\t\t\t\tprocess.stdout.write(`📝 Wrote json.schema.`)\n\t\t\t}\n\t\t\tbreak\n\t\tcase `prelude`:\n\t\tcase `prelude/$configPath`: {\n\t\t\tconst baseline = await breakagePrelude({\n\t\t\t\t...inputs.opts,\n\t\t\t\tout: inputs.opts.out ?? `.breakage/baseline.json`,\n\t\t\t})\n\t\t\tprocess.stdout.write(`Pinned ${baseline.ref} at ${baseline.commit}.\\n`)\n\t\t\tbreak\n\t\t}\n\t\tcase ``:\n\t\tcase `$configPath`: {\n\t\t\tconst { returnValue } = await encapsulate(() => breakage(inputs.opts), {\n\t\t\t\tconsole: true,\n\t\t\t\tstdout: true,\n\t\t\t})\n\t\t\tif (`testResult` in returnValue && returnValue.breakingChangesFound) {\n\t\t\t\tprocess.stdout.write(returnValue.testResult)\n\t\t\t}\n\t\t\tif (`breakingChangesFound` in returnValue) {\n\t\t\t\tif (returnValue.breakingChangesFound) {\n\t\t\t\t\tif (returnValue.breakingChangesCertified) {\n\t\t\t\t\t\tprocess.stdout.write(\n\t\t\t\t\t\t\t`👷 Breaking changes were found and certified.`,\n\t\t\t\t\t\t)\n\t\t\t\t\t\tprocess.exit(0)\n\t\t\t\t\t} else {\n\t\t\t\t\t\tprocess.stdout.write(\n\t\t\t\t\t\t\t`❌ Breaking changes were found, but not certified.`,\n\t\t\t\t\t\t)\n\t\t\t\t\t\tprocess.exit(1)\n\t\t\t\t\t}\n\t\t\t\t} else {\n\t\t\t\t\tprocess.stdout.write(`✅ No breaking changes were found.`)\n\t\t\t\t\tprocess.exit(0)\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tprocess.stdout.write(\n\t\t\t\t\t`💥 Breakage failed to determine breaking changes.` +\n\t\t\t\t\t\t`\\n` +\n\t\t\t\t\t\tinspect(returnValue),\n\t\t\t\t)\n\t\t\t\tprocess.exit(2)\n\t\t\t}\n\t\t}\n\t}\n}\n"],"mappings":";;;;;;;;AAuBA,MAAM,kBAAkB,QACvB,4CACA,KAAK;CACJ,eAAe;CACf,iBAAiB;CACjB,aAAa;CACb,aAAa;CACb,gBAAgB;CAChB,gBAAgB;CAChB,YAAY;AACb,CAAC,GACD;CACC,YAAY;EACX,SAAS,CAAC,aAAa;EACvB,YAAY,EAAE,YAAY,MAAM;EAChC,MAAM;EACN,UAAU;EACV,aAAa;EACb,SAAS;CACV;CACA,cAAc;EACb,SAAS,CAAC,eAAe;EACzB,YAAY;GAAE,YAAY;GAAO,YAAY;EAAQ;EACrD,UAAU;EACV,aAAa;EACb,SAAS;CACV;CACA,aAAa;EACZ,SAAS,CAAC,gBAAgB,SAAS;EACnC,YAAY,EAAE,YAAY,MAAM;EAChC,MAAM;EACN,UAAU;EACV,aAAa;EACb,SAAS;CACV;CACA,aAAa;EACZ,SAAS,CAAC,cAAc;EACxB,YAAY,EAAE,YAAY,MAAM;EAChC,MAAM;EACN,UAAU;EACV,aAAa;EACb,SAAS;CACV;CACA,gBAAgB;EACf,SAAS,CAAC,iBAAiB;EAC3B,YAAY,EAAE,YAAY,MAAM;EAChC,MAAM;EACN,UAAU;EACV,aAAa;EACb,SAAS;CACV;CACA,aAAa;EACZ,SAAS,CAAC,YAAY,cAAc;EACpC,YAAY;GAAE,YAAY;GAAO,YAAY;EAAc;EAC3D,MAAM;EACN,UAAU;EACV,aAAa;EACb,SAAS;CACV;CACA,SAAS;EACR,YAAY,EAAE,YAAY,MAAM;EAChC,MAAM;EACN,UAAU;EACV,aAAa;EACb,SAAS;EACT,OAAO;CACR;AACD,CACD;AAEA,MAAM,iBAAiB,QACtB,+EACA,KAAK;CACJ,eAAe;CACf,gBAAgB;CAChB,QAAQ;CACR,gBAAgB;CAChB,gBAAgB;CAChB,mBAAmB;CACnB,iBAAiB;CACjB,YAAY;AACb,CAAC,GACD;CACC,GAAG,gBAAgB;CACnB,aAAa;EACZ,GAAG,gBAAgB,cAAc;EACjC,UAAU;CACX;CACA,aAAa;EACZ,GAAG,gBAAgB,cAAc;EACjC,UAAU;CACX;CACA,gBAAgB;EACf,GAAG,gBAAgB,cAAc;EACjC,UAAU;CACX;CACA,KAAK;EACJ,YAAY;GAAE,YAAY;GAAO,YAAY;EAAQ;EACrD,UAAU;EACV,aAAa;EACb,SAAS;CACV;AACD,CACD;AAEA,MAAM,gBAAgB,QACrB,yDACA,KAAK,EAAE,WAAW,SAAS,CAAC,GAC5B,EACC,QAAQ;CACP,SAAS,CAAC,SAAS;CACnB,YAAY;EAAE,YAAY;EAAO,YAAY;CAAc;CAC3D,MAAM;CACN,UAAU;CACV,aAAa;CACb,SAAS;AACV,EACD,CACD;AAEA,MAAM,QAAQ,IACb;CACC,SAAS;CACT,QAAQ,SAAS;EAChB,MAAM;EACN,QAAQ;EACR,SAAS,SAAS,EAAE,aAAa,KAAK,CAAC;EACvC,aAAa;CACd,CAAC;CACD,cAAc;EACb,IAAI;EACJ,aAAa;EACb,MAAM,UAAU,aAAa;EAC7B,QAAQ;EACR,SAAS;EACT,uBAAuB;CACxB;CACA,uBAAuB;EACtB,aAAa,EAAE,YAAY,QAAQ;EACnC,uBAAuB,EAAE,YAAY,QAAQ;CAC9C;CACA,qBAAqB,SAA4B;EAChD,IAAI,KAAK,OAAO,UAAU,KAAK,OAAO,UACrC;EAKD,QAFE,KAAK,OAAO,YAAY,KAAK,KAAK,KAAK,OACxCA,OAAK,KAAK,QAAQ,IAAI,GAAG,sBAAsB;CAEjD;AACD,GACA;CACC,OAAO,SAAS,GAAG,SAAS,OAAO,KAAK,YAAY,SAAS,IAAI;CACjE,QAAQ,SAAS,GAAG,SAAS,OAAO,MAAM,YAAY,SAAS,IAAI;AACpE,CACD;AAEA,MAAM,aAAa,MAAM,mBAAmB,MAAM,YAAY,QAAQ,IAAI;AAC1E,IAAI,eAAe,KAAA,GAClB,QAAQ,OAAO,MAAM,UAAU;KACzB;CACN,MAAM,EAAE,QAAQ,UAAU,oBAAoB,MAAM,QAAQ,IAAI;CAChE,YAAY,QAAQ;CAEpB,QAAQ,OAAO,MAAf;EACC,KAAK;GACJ,QAAQ,IAAI,KAAK,MAAM,UAAU,CAAC;GAClC;EACD,KAAK;GACJ;IACC,MAAM,EAAE,WAAW,OAAO;IAC1B,gBAAgB,UAAU,GAAG;IAC7B,QAAQ,OAAO,MAAM,uBAAuB;GAC7C;GACA;EACD,KAAK;EACL,KAAK,uBAAuB;GAC3B,MAAM,WAAW,MAAM,gBAAgB;IACtC,GAAG,OAAO;IACV,KAAK,OAAO,KAAK,OAAO;GACzB,CAAC;GACD,QAAQ,OAAO,MAAM,UAAU,SAAS,IAAI,MAAM,SAAS,OAAO,IAAI;GACtE;EACD;EACA,KAAK;EACL,KAAK,eAAe;GACnB,MAAM,EAAE,gBAAgB,MAAM,kBAAkB,SAAS,OAAO,IAAI,GAAG;IACtE,SAAS;IACT,QAAQ;GACT,CAAC;GACD,IAAI,gBAAgB,eAAe,YAAY,sBAC9C,QAAQ,OAAO,MAAM,YAAY,UAAU;GAE5C,IAAI,0BAA0B,aAAa;IAC1C,IAAI,YAAY,sBAAsB;KACrC,IAAI,YAAY,0BAA0B;MACzC,QAAQ,OAAO,MACd,+CACD;MACA,QAAQ,KAAK,CAAC;KACf,OAAO;MACN,QAAQ,OAAO,MACd,mDACD;MACA,QAAQ,KAAK,CAAC;KACf;IACD,OAAO;KACN,QAAQ,OAAO,MAAM,mCAAmC;KACxD,QAAQ,KAAK,CAAC;IACf;GACD,OAAO;IACN,QAAQ,OAAO,MACd,wDAEC,QAAQ,WAAW,CACrB;IACA,QAAQ,KAAK,CAAC;GACf;EACD;CACD;AACD"}

package/package.json

@@ -1,52 +1,51 @@
 {
-	"name": "breakage",
-	"version": "0.0.0",
-	"description": "Run yesterday’s tests against tomorrow’s release.",
-	"homepage": "https://github.com/jeremybanka/breakage#readme",
-	"bugs": "https://github.com/jeremybanka/breakage/issues",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/jeremybanka/breakage.git",
-		"directory": "packages/breakage"
-	},
-	"license": "MPL-2.0",
-	"author": {
-		"name": "Jeremy Banka",
-		"email": "hello@jeremybanka.com"
-	},
-	"type": "module",
-	"main": "dist/breakage.js",
-	"types": "dist/breakage.d.ts",
-	"bin": {
-		"breakage": "./dist/breakage.x.js"
-	},
-	"files": [
-		"dist",
-		"src"
-	],
-	"scripts": {
-		"build": "tsdown && pnpm run schema",
-		"check": "pnpm run check:tsc",
-		"check:tsc": "tsc --noEmit",
-		"postversion": "dprint fmt package.json",
-		"schema": "bun src/breakage.x.ts --outdir=dist -- schema",
-		"pretest": "pnpm run build",
-		"test": "bun test -- ./__tests__",
-		"test:watch": "bun test --watch -- ./__tests__"
-	},
-	"dependencies": {
-		"arktype": "2.2.7",
-		"comline": "0.9.0",
-		"minimatch": "10.2.6",
-		"simple-git": "4.0.2",
-		"takua": "0.2.3"
-	},
-	"devDependencies": {
-		"@types/bun": "npm:bun-types@1.4.2",
-		"tsdown": "0.23.0",
-		"typescript": "7.0.2"
-	},
-	"publishConfig": {
-		"access": "public"
-	}
-}
+  "name": "breakage",
+  "version": "0.8.2",
+  "description": "Run yesterday’s tests against tomorrow’s release.",
+  "homepage": "https://github.com/jeremybanka/breakage#readme",
+  "bugs": "https://github.com/jeremybanka/breakage/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeremybanka/breakage.git",
+    "directory": "packages/breakage"
+  },
+  "license": "MPL-2.0",
+  "author": {
+    "name": "Jeremy Banka",
+    "email": "hello@jeremybanka.com"
+  },
+  "type": "module",
+  "main": "dist/breakage.js",
+  "types": "dist/breakage.d.ts",
+  "bin": {
+    "breakage": "./dist/breakage.x.js"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "arktype": "2.2.8",
+    "comline": "0.9.0",
+    "minimatch": "10.2.6",
+    "simple-git": "4.0.2",
+    "takua": "0.2.3"
+  },
+  "devDependencies": {
+    "@types/bun": "npm:bun-types@1.4.3",
+    "typescript": "7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack && pnpm run schema",
+    "check": "pnpm run check:tsc",
+    "check:tsc": "tsc --noEmit",
+    "postversion": "dprint fmt package.json",
+    "schema": "bun src/breakage.x.ts --outdir=dist -- schema",
+    "pretest": "pnpm run build",
+    "test": "bun test -- ./__tests__",
+    "test:watch": "bun test --watch -- ./__tests__"
+  }
+}

package/src/baseline.ts

@@ -0,0 +1,143 @@
+import { randomUUID } from "node:crypto"
+import { mkdir, readFile, 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"
+import { latestReleaseTag } from "./release-tag.ts"
+
+export type BaselineOptions = {
+	tagPattern?: string | undefined
+	baseDirname?: string
+}
+
+export type BreakagePreludeOptions = BaselineOptions & { out: string }
+
+export type BreakageBaseline = {
+	version: 1
+	tagPattern: string | null
+	packageDirectory: string
+	ref: string
+	commit: string
+}
+
+const objectId = /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/
+
+function isBaseline(value: unknown): value is BreakageBaseline {
+	if (typeof value !== `object` || value === null) return false
+	const record = value as Partial<BreakageBaseline>
+	return (
+		record.version === 1 &&
+		(record.tagPattern === null || typeof record.tagPattern === `string`) &&
+		typeof record.packageDirectory === `string` &&
+		typeof record.ref === `string` &&
+		record.ref.startsWith(`refs/tags/`) &&
+		typeof record.commit === `string` &&
+		objectId.test(record.commit)
+	)
+}
+
+/** Resolve and fetch a release without running tests or changing the worktree. */
+export async function breakagePrelude({
+	out,
+	tagPattern,
+	baseDirname = process.cwd(),
+}: BreakagePreludeOptions): Promise<BreakageBaseline> {
+	const filename = path.resolve(baseDirname, out)
+	const temporaryPath = `${filename}.${randomUUID()}.tmp`
+	let canInvalidate = false
+	try {
+		const git = simpleGit(baseDirname)
+		// An ignored, untracked snapshot cannot make the compatibility check dirty.
+		if (!(await git.raw([`check-ignore`, `--`, filename])).trim()) {
+			throw new Error(`Baseline output must be gitignored: ${filename}.`)
+		}
+		canInvalidate = true
+		const remoteTags = await git.listRemote([`--tags`, `origin`])
+		const ref = latestReleaseTag(remoteTags, tagPattern)
+		if (!ref) {
+			throw new Error(`No tags found matching the pattern "${tagPattern}".`)
+		}
+		const refs = new Map(
+			remoteTags
+				.trim()
+				.split(`\n`)
+				.map((line) => {
+					const [sha, name] = line.split(`\t`)
+					return [name, sha]
+				}),
+		)
+		// ls-remote supplies the peeled commit for annotated tags.
+		const commit = refs.get(`${ref}^{}`) ?? refs.get(ref)
+		if (!commit || !objectId.test(commit)) {
+			throw new Error(`Could not resolve the release commit for ${ref}.`)
+		}
+		const commonGitDirectory = await git.revparse([
+			`--path-format=absolute`,
+			`--git-common-dir`,
+		])
+		await withDirectoryLock(
+			path.join(commonGitDirectory, `breakage-fetch.lock`),
+			() => git.fetch([`origin`, commit, `--no-tags`, `--no-write-fetch-head`]),
+		)
+		if ((await git.raw([`cat-file`, `-t`, commit])).trim() !== `commit`) {
+			throw new Error(`Release ${ref} does not resolve to a commit.`)
+		}
+		const baseline: BreakageBaseline = {
+			version: 1,
+			tagPattern: tagPattern ?? null,
+			packageDirectory: await git.revparse([`--show-prefix`]),
+			ref,
+			commit,
+		}
+		await mkdir(path.dirname(filename), { recursive: true })
+		await writeFile(temporaryPath, `${JSON.stringify(baseline, null, 2)}\n`, {
+			flag: `wx`,
+		})
+		await rename(temporaryPath, filename)
+		return baseline
+	} catch (cause) {
+		// A failed refresh must never leave an older snapshot available as fallback.
+		if (canInvalidate) await rm(filename, { force: true })
+		throw new Error(`Failed to prepare baseline ${filename}.`, { cause })
+	} finally {
+		await rm(temporaryPath, { force: true })
+	}
+}
+
+export async function readBaseline(
+	git: SimpleGit,
+	filename: string,
+	{ tagPattern }: BaselineOptions,
+): Promise<BreakageBaseline> {
+	try {
+		const baseline: unknown = JSON.parse(await readFile(filename, `utf8`))
+		if (!isBaseline(baseline)) throw new Error(`Invalid baseline fields.`)
+		if (
+			baseline.tagPattern !== (tagPattern ?? null) ||
+			baseline.packageDirectory !== (await git.revparse([`--show-prefix`]))
+		) {
+			throw new Error(`Baseline belongs to a different package or tag pattern.`)
+		}
+		if (
+			(
+				await git.raw([`check-ref-format`, `--normalize`, baseline.ref])
+			).trim() !== baseline.ref
+		) {
+			throw new Error(`Invalid release ref.`)
+		}
+		if (
+			(await git.raw([`cat-file`, `-t`, baseline.commit])).trim() !== `commit`
+		) {
+			throw new Error(`Pinned object is not a locally available commit.`)
+		}
+		return baseline
+	} catch (cause) {
+		throw new Error(
+			`Missing, invalid, or unusable baseline ${filename}. Run breakage prelude again.`,
+			{ cause },
+		)
+	}
+}

package/src/breakage.ts

@@ -6,12 +6,17 @@ import { simpleGit } from "simple-git"
 import type { Chronicle } from "takua"
 import logger from "takua"
 
+import { readBaseline } from "./baseline.ts"
 import { withDirectoryLock } from "./directory-lock.ts"
 import { latestReleaseTag as selectLatestReleaseTag } from "./release-tag.ts"
 import { withTestFileState } from "./test-file-state.ts"
 
+export type { BreakageBaseline, BreakagePreludeOptions } from "./baseline.ts"
+export { breakagePrelude } from "./baseline.ts"
+
 export type BreakageOptions = {
 	tagPattern?: string | undefined
+	baselineFile?: string | undefined
 	testPattern: string
 	testCommand: string
 	certifyCommand: string
@@ -54,6 +59,7 @@ export type BreakageOutcome =
 
 export async function breakage({
 	tagPattern,
+	baselineFile,
 	testPattern,
 	testCommand,
 	certifyCommand,
@@ -86,39 +92,53 @@ export async function breakage({
 			gitWasClean: false,
 		}
 	}
-	const tagsRemote = await git.listRemote([`--tags`, `origin`])
+	let latestReleaseTag: string | undefined
+	let releaseCommit: string
+	if (baselineFile !== undefined) {
+		const baseline = await readBaseline(
+			git,
+			path.resolve(baseDirname, baselineFile),
+			{ tagPattern },
+		)
+		latestReleaseTag = baseline.ref
+		releaseCommit = baseline.commit
+		mark?.(`read pinned release baseline`)
+	} else {
+		const tagsRemote = await git.listRemote([`--tags`, `origin`])
 
-	mark?.(`list remote tags`)
-	const latestReleaseTag = selectLatestReleaseTag(tagsRemote, tagPattern)
-	mark?.(`found latest release tag`)
-	if (!latestReleaseTag) {
-		return {
-			summary: `No tags found matching the pattern "${tagPattern}".`,
-			gitWasClean: true,
-			lastReleaseFound: false,
-		} as const
-	}
-	const commonGitDirectory = await git.revparse([
-		`--path-format=absolute`,
-		`--git-common-dir`,
-	])
-	await withDirectoryLock(
-		path.join(commonGitDirectory, `breakage-fetch.lock`),
-		() =>
-			git.fetch([
-				`origin`,
-				`${latestReleaseTag}:${latestReleaseTag}`,
-				`--no-tags`,
-				`--no-write-fetch-head`,
-			]),
-	)
+		mark?.(`list remote tags`)
+		latestReleaseTag = selectLatestReleaseTag(tagsRemote, tagPattern)
+		mark?.(`found latest release tag`)
+		if (!latestReleaseTag) {
+			return {
+				summary: `No tags found matching the pattern "${tagPattern}".`,
+				gitWasClean: true,
+				lastReleaseFound: false,
+			} as const
+		}
+		const commonGitDirectory = await git.revparse([
+			`--path-format=absolute`,
+			`--git-common-dir`,
+		])
+		await withDirectoryLock(
+			path.join(commonGitDirectory, `breakage-fetch.lock`),
+			() =>
+				git.fetch([
+					`origin`,
+					`${latestReleaseTag}:${latestReleaseTag}`,
+					`--no-tags`,
+					`--no-write-fetch-head`,
+				]),
+		)
 
-	mark?.(`fetched latest release tag`)
+		releaseCommit = await git.revparse([`${latestReleaseTag}^{commit}`])
+		mark?.(`fetched latest release tag`)
+	}
 
 	let productionFiles: string[]
 	try {
 		productionFiles = (
-			await git.raw([`ls-tree`, `-r`, `--name-only`, `-z`, latestReleaseTag])
+			await git.raw([`ls-tree`, `-r`, `--name-only`, `-z`, releaseCommit])
 		)
 			.split(`\0`)
 			.filter(Boolean)
@@ -164,10 +184,7 @@ export async function breakage({
 				testsWereFound: false,
 			} as const
 		}
-		const restore = await state.replaceTests(
-			latestReleaseTag,
-			productionTestFiles,
-		)
+		const restore = await state.replaceTests(releaseCommit, productionTestFiles)
 		mark?.(`restored public tests from latest release tag`)
 		return { latestReleaseTag, productionTestFiles, restore }
 	})

package/src/breakage.x.ts

@@ -19,12 +19,13 @@ import {
 import logger from "takua"
 
 import type { BreakageOptions } from "./breakage.ts"
-import { breakage } from "./breakage.ts"
+import { breakage, breakagePrelude } from "./breakage.ts"
 
 const BREAKAGE_MANUAL = options(
 	`Check for breaking changes in a package.`,
 	type({
 		"tagPattern?": `string`,
+		"baselineFile?": `string`,
 		testPattern: `string`,
 		testCommand: `string`,
 		certifyCommand: `string`,
@@ -40,6 +41,13 @@ const BREAKAGE_MANUAL = options(
 			description: `RegExp which, if found matched to a git tag, will be considered a release tag for your library.`,
 			example: `--tagPattern="my-library"`,
 		},
+		baselineFile: {
+			aliases: [`baseline-file`],
+			completion: { repeatable: false, fileSystem: `files` },
+			required: false,
+			description: `Use the exact locally fetched commit from a prelude snapshot instead of discovering remote tags.`,
+			example: `--baseline-file=.breakage/baseline.json`,
+		},
 		testPattern: {
 			aliases: [`test-pattern`, `pattern`],
 			completion: { repeatable: false },
@@ -83,6 +91,41 @@ const BREAKAGE_MANUAL = options(
 	},
 ) satisfies OptionsGroup<BreakageOptions>
 
+const PRELUDE_MANUAL = options(
+	`Resolve and fetch the release baseline for a cacheable compatibility check.`,
+	type({
+		"tagPattern?": `string`,
+		"baseDirname?": `string`,
+		"out?": `string`,
+		"testPattern?": `string`,
+		"testCommand?": `string`,
+		"certifyCommand?": `string`,
+		"baselineFile?": `string`,
+		"verbose?": `boolean`,
+	}),
+	{
+		...BREAKAGE_MANUAL.optionConfigs,
+		testPattern: {
+			...BREAKAGE_MANUAL.optionConfigs.testPattern,
+			required: false,
+		},
+		testCommand: {
+			...BREAKAGE_MANUAL.optionConfigs.testCommand,
+			required: false,
+		},
+		certifyCommand: {
+			...BREAKAGE_MANUAL.optionConfigs.certifyCommand,
+			required: false,
+		},
+		out: {
+			completion: { repeatable: false, fileSystem: `files` },
+			required: false,
+			description: `Gitignored snapshot path relative to the base directory (default: .breakage/baseline.json).`,
+			example: `--out=.breakage/baseline.json`,
+		},
+	},
+)
+
 const SCHEMA_MANUAL = options(
 	`Create a copy of the schema for configuring breakage.`,
 	type({ "outdir?": `string` }),
@@ -101,20 +144,31 @@ const SCHEMA_MANUAL = options(
 const parse = cli(
 	{
 		cliName: `breakage`,
-		routes: optional({ help: null, schema: null, $configPath: null }),
+		routes: optional({
+			help: null,
+			schema: null,
+			prelude: optional({ $configPath: null }),
+			$configPath: null,
+		}),
 		routeOptions: {
 			"": BREAKAGE_MANUAL,
 			$configPath: BREAKAGE_MANUAL,
 			help: noOptions(`Show usage.`),
 			schema: SCHEMA_MANUAL,
+			prelude: PRELUDE_MANUAL,
+			"prelude/$configPath": PRELUDE_MANUAL,
+		},
+		positionalCompletions: {
+			$configPath: { fileSystem: `files` },
+			"prelude/$configPath": { fileSystem: `files` },
 		},
-		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`)
+				(args[0] === `prelude` ? args[1] : args[0]) ??
+				path.join(process.cwd(), `breakage.config.json`)
 			return configPath
 		},
 	},
@@ -142,6 +196,15 @@ if (completion !== undefined) {
 				process.stdout.write(`📝 Wrote json.schema.`)
 			}
 			break
+		case `prelude`:
+		case `prelude/$configPath`: {
+			const baseline = await breakagePrelude({
+				...inputs.opts,
+				out: inputs.opts.out ?? `.breakage/baseline.json`,
+			})
+			process.stdout.write(`Pinned ${baseline.ref} at ${baseline.commit}.\n`)
+			break
+		}
 		case ``:
 		case `$configPath`: {
 			const { returnValue } = await encapsulate(() => breakage(inputs.opts), {