Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(release): validate frozen checkpoint versions and breaking notes
N0zoM1z060825fb44751
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.mdindex 289bca2c4..b53258601 100644--- a/.github/pull_request_template.md+++ b/.github/pull_request_template.md@@ -59,6 +59,10 @@ relevant real-provider or platform workflow, or explain why it was unavailable.limits, security/privacy/containment implications, and meaningful proof gaps. -->- Breaking changes or migration steps:+ <!-- For ! / BREAKING CHANGE: show a previously valid call/configuration,+ its new behavior and migration, and why compatibility/deprecation cannot+ preserve it. Compatible fixes/additions should use patch/minor semantics.+ See docs/releasing.md. -->- Real Hopper/Ghidra, browser, or OS coverage:- Package or release metadata impact:- Security, privacy, process, or containment review:diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex b1f0f0033..04e385404 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -84,6 +84,32 @@ jobs:exit 1fi+ - name: Check out release controller and Git history+ uses: actions/checkout@v6+ with:+ ref: ${{ github.sha }}+ fetch-depth: 0+ persist-credentials: false++ - name: Set up Node.js for checkpoint validation+ uses: actions/setup-node@v6+ with:+ node-version-file: .nvmrc+ package-manager-cache: false++ - name: Install checkpoint validation dependencies+ run: npm ci++ - name: Validate checkpoint version and ancestry before release creation+ env:+ RELEASE_PHASE: ${{ inputs.phase }}+ RELEASE_BRANCH: ${{ inputs.release_branch }}+ SOURCE_SHA: ${{ steps.branch.outputs.sha }}+ run: >-+ node scripts/verify-release-checkpoint.mjs+ --phase "$RELEASE_PHASE" --release-branch "$RELEASE_BRANCH"+ --source-sha "$SOURCE_SHA"+- uses: googleapis/release-please-action@v4id: releasewith:@@ -116,6 +142,7 @@ jobs:uses: actions/checkout@v6with:ref: ${{ fromJSON(steps.release.outputs.pr).headBranchName }}+ fetch-depth: 0persist-credentials: false- name: Set up Node.js for generated documentation@@ -129,6 +156,16 @@ jobs:if: inputs.phase == 'prepare' && steps.release.outputs.prs_created == 'true'run: npm ci+ - name: Validate prepared release version and migration notes+ if: inputs.phase == 'prepare' && steps.release.outputs.prs_created == 'true'+ env:+ RELEASE_BRANCH: ${{ inputs.release_branch }}+ SOURCE_SHA: ${{ steps.branch.outputs.sha }}+ run: >-+ node scripts/verify-release-checkpoint.mjs+ --phase prepare --stage candidate --release-branch "$RELEASE_BRANCH"+ --source-sha "$SOURCE_SHA"+- name: Regenerate release documentationif: inputs.phase == 'prepare' && steps.release.outputs.prs_created == 'true'run: npm run docs:generatediff --git a/docs/releasing.md b/docs/releasing.mdindex b42189f45..922208caf 100644--- a/docs/releasing.md+++ b/docs/releasing.md@@ -11,6 +11,32 @@ breaking changes. Record the full source SHA and create `release/VERSION` atthat commit. The version is a maintainer choice; Release Please's proposedversion must agree before publication.+`release/VERSION` also sets the expected version for the workflow. Use an exact+SemVer such as `release/6.1.0` or `release/6.1.0-rc.1`, without build metadata.+The checkpoint validator rejects a candidate whose package, lockfile, manifest,+registry metadata or changelog disagrees with that version before creating a tag.++### Compatibility and version selection++REA uses the default SemVer strategy: compatible fixes increment patch;+compatible capabilities increment minor; incompatible public behavior increments+major. Adding tools, internal refactoring and correcting behavior outside the+supported contract do not by themselves require a major release.++The supported public surface includes documented CLI commands/options, MCP tool+names and input/result contracts, saved evidence formats and supported runtime+requirements. Before adding `!` or a `BREAKING CHANGE` footer, a PR must identify+a previously valid call or configuration that will fail or change meaning,+explain why compatibility cannot be preserved, and give its migration. Prefer+optional additions, compatibility adapters and a documented deprecation period;+group deliberate removals into a planned major release. Maintainers review this+impact before merging; the bot parses markers and cannot infer compatibility.++For example, adding an optional inspection tool is a minor change. Rejecting a+relative MCP path previously accepted by the public contract is breaking;+rejecting an input that the existing contract already prohibited is a fix.+Changing the version number alone does not restore compatibility.+For example, after selecting a reviewed commit for 5.0.0:```bash@@ -48,6 +74,22 @@ normalization, then approve that head's blocked runs from the PR page. Updatesto the bot branch can create new approval-required runs; approval of an olderhead does not verify the normalized candidate. Wait for the final head's CI.+The validator reads the actual ancestry range from the published baseline tag+to the selected checkpoint, including visible first-parent Conventional Commits.+This matters after merging a side-branch release back into a newer main:+Release Please's chronological history cutoff can omit unreleased mainline+commits. Unreleased breaking markers require a major increment and references+in the new release's breaking-change migration section. Other omitted entries+are reported for review. Historical notes from an older release cannot satisfy+the new release's migration check. This audits declared markers and references;+it does not prove API compatibility or the quality of a migration explanation.++If preparation reports a mismatch or omitted breaking changes, inspect the+recorded ancestry report, correct the release PR's version artifacts and notes,+regenerate documentation, and review/test its final head. Do not repeatedly+prepare over manual corrections. Publication independently checks the merged+candidate again before Release Please can create a tag.+Review the candidate's version, notes, generated metadata, and packagecontents. Wait for the candidate's CI and relevant real-provider checks.Routine local iterations need focused checks; CI owns full deterministicdiff --git a/scripts/lib/release-checkpoint.mjs b/scripts/lib/release-checkpoint.mjsnew file mode 100644index 000000000..af42178c3--- /dev/null+++ b/scripts/lib/release-checkpoint.mjs@@ -0,0 +1,320 @@+import { gt, major, valid } from "semver";+import { z } from "zod";++const shaSchema = z.string().regex(/^[a-f0-9]{40}$/u);+const versionSchema = z.object({ version: z.string() });+const manifestSchema = z.object({ ".": z.string() });+const sectionsSchema = z.object({+ "changelog-sections": z.array(+ z.object({ type: z.string(), hidden: z.boolean().optional() }),+ ),+});++function releaseVersion(value, location) {+ if (valid(value) !== value || value.includes("+")) {+ throw new Error(+ `${location} must contain an exact SemVer without build metadata: ${value}`,+ );+ }+ return value;+}++async function readJson(git, sha, path, schema) {+ const text = await git(["show", `${sha}:${path}`]);+ let value;+ try {+ value = JSON.parse(text);+ } catch (error) {+ if (error instanceof SyntaxError) {+ throw new Error(`${path}@${sha} contains invalid JSON: ${error.message}`);+ }+ throw error;+ }+ const parsed = schema.safeParse(value);+ if (!parsed.success) {+ throw new Error(`${path}@${sha} is malformed: ${parsed.error.message}`);+ }+ return parsed.data;+}++function readCommits(text) {+ if (text.length === 0) return [];+ const fields = text.split("\0");+ if (fields.pop() !== "" || fields.length % 3 !== 0) {+ throw new Error("Git returned malformed checkpoint history records.");+ }+ const commits = [];+ for (let index = 0; index < fields.length; index += 3) {+ const sha = shaSchema.parse(fields[index]);+ const subject = z.string().parse(fields[index + 1]);+ const body = z.string().parse(fields[index + 2]);+ const type = /^([a-z]+)(?:\([^)]*\))?!?: /u.exec(subject)?.[1];+ commits.push({+ sha,+ subject,+ type,+ breaking:+ /^[a-z]+(?:\([^)]*\))?!: /u.test(subject) ||+ /^BREAKING(?: CHANGE|-CHANGE):\s*\S/mu.test(body),+ });+ }+ return commits;+}++function referencesCommit(text, commit) {+ if (text.includes(commit.sha.slice(0, 7))) return true;+ const pullRequest = /\(#(\d+)\)$/u.exec(commit.subject)?.[1];+ return (+ pullRequest !== undefined &&+ new RegExp(`#${pullRequest}(?!\\d)`, "u").test(text)+ );+}++function releaseNotes(text, expectedVersion) {+ const headings = Array.from(text.matchAll(/^## \[([^\]]+)\].*$/gmu));+ const first = headings[0];+ if (first?.[1] !== expectedVersion || first.index === undefined) {+ throw new Error(`CHANGELOG.md must start with release ${expectedVersion}.`);+ }+ return text.slice(first.index, headings[1]?.index ?? text.length);+}++function breakingSection(notes) {+ const heading = /^### [^\n]*BREAKING CHANGES[^\n]*\n/imu.exec(notes);+ if (heading === null) return "";+ const body = notes.slice(heading.index + heading[0].length);+ const end = body.search(/^### /mu);+ return end < 0 ? body : body.slice(0, end);+}++async function requireAncestor(git, ancestor, descendant, description) {+ try {+ await git(["merge-base", "--is-ancestor", ancestor, descendant]);+ } catch (error) {+ const failure = z.object({ code: z.literal(1) }).safeParse(error);+ if (!failure.success) throw error;+ throw new Error(+ `${description}: ${ancestor} is not an ancestor of ${descendant}. Sync the released tag into main before cutting a checkpoint, and prepare candidates from that frozen source.`,+ );+ }+}++async function resolveBaseline(git, tag) {+ try {+ return shaSchema.parse(+ (await git(["rev-parse", "--verify", `${tag}^{commit}`])).trim(),+ );+ } catch (error) {+ const failure = z.object({ code: z.literal(128) }).safeParse(error);+ if (!failure.success) throw error;+ throw new Error(+ `Published baseline ${tag} is unavailable. Fetch release tags and finish the previous release sync before preparing this checkpoint. ${error instanceof Error ? error.message : String(error)}`,+ );+ }+}++async function validateCandidate(git, sha, version, commits) {+ const versions = [+ [+ "package.json",+ (await readJson(git, sha, "package.json", versionSchema)).version,+ ],+ [+ ".release-please-manifest.json",+ (+ await readJson(+ git,+ sha,+ ".release-please-manifest.json",+ manifestSchema,+ )+ )["."],+ ],+ ];+ const lock = await readJson(+ git,+ sha,+ "package-lock.json",+ versionSchema.extend({+ packages: z.object({ "": versionSchema }),+ }),+ );+ versions.push(+ ["package-lock.json", lock.version],+ ["package-lock.json packages.root", lock.packages[""].version],+ );+ const server = await readJson(+ git,+ sha,+ "server.json",+ versionSchema.extend({+ packages: z.array(+ z.object({ identifier: z.string(), version: z.string() }),+ ),+ }),+ );+ const npmPackage = server.packages.find(+ (entry) => entry.identifier === "rea-agents",+ );+ if (npmPackage === undefined)+ throw new Error("server.json is missing the rea-agents package.");+ versions.push(+ ["server.json", server.version],+ ["server.json rea-agents package", npmPackage.version],+ );+ const catalog = await readJson(+ git,+ sha,+ "docs/product-catalog.json",+ z.object({ package: versionSchema }),+ );+ versions.push(["docs/product-catalog.json", catalog.package.version]);+ const generated = await git([+ "show",+ `${sha}:src/generatedPackageMetadata.ts`,+ ]);+ const generatedVersions = Array.from(+ generated.matchAll(/^\s+version: "([^"]+)"/gmu),+ );+ if (generatedVersions.length !== 1)+ throw new Error(+ "Generated package metadata must declare one literal version.",+ );+ versions.push(["src/generatedPackageMetadata.ts", generatedVersions[0]?.[1]]);+ for (const [location, actual] of versions) {+ if (actual !== version) {+ throw new Error(+ `${location}@${sha} declares ${actual}; release branch requires ${version}.`,+ );+ }+ }+ const notes = releaseNotes(+ await git(["show", `${sha}:CHANGELOG.md`]),+ version,+ );+ const breakingNotes = breakingSection(notes);+ const missingBreaking = commits.filter(+ (commit) => commit.breaking && !referencesCommit(breakingNotes, commit),+ );+ if (missingBreaking.length > 0) {+ throw new Error(+ `Release ${version} migration notes omit unreleased breaking changes: ${missingBreaking.map((commit) => `${commit.sha} ${commit.subject}`).join("; ")}`,+ );+ }+ return commits.filter((commit) => !referencesCommit(notes, commit));+}++/** Validate a recorded checkpoint and optional candidate using exact Git ancestry. */+export async function inspectReleaseCheckpoint(git, options) {+ const { phase, stage, releaseBranch, sourceSha, candidateSha } = z+ .object({+ phase: z.enum(["prepare", "publish"]),+ stage: z.enum(["source", "candidate"]),+ releaseBranch: z.string().startsWith("release/"),+ sourceSha: shaSchema,+ candidateSha: shaSchema.optional(),+ })+ .parse(options);+ const expectedVersion = releaseVersion(+ releaseBranch.slice("release/".length),+ "release/VERSION",+ );+ if (phase === "publish" && stage === "candidate") {+ throw new Error(+ "Publish validates its merged source SHA; candidate stage applies only to prepare.",+ );+ }+ const applicationSha =+ phase === "publish"+ ? shaSchema.parse((await git(["rev-parse", `${sourceSha}^1`])).trim())+ : sourceSha;+ const manifest = await readJson(+ git,+ applicationSha,+ ".release-please-manifest.json",+ manifestSchema,+ );+ const baselineVersion = releaseVersion(+ manifest["."],+ "published baseline manifest",+ );+ const sourcePackage = await readJson(+ git,+ applicationSha,+ "package.json",+ versionSchema,+ );+ if (sourcePackage.version !== baselineVersion) {+ throw new Error(+ `Source package ${sourcePackage.version} and release baseline ${baselineVersion} disagree.`,+ );+ }+ if (!gt(expectedVersion, baselineVersion)) {+ throw new Error(+ `Expected release ${expectedVersion} must advance published baseline ${baselineVersion}.`,+ );+ }+ const baselineTag = `refs/tags/rea-agents-${baselineVersion}`;+ const baselineSha = await resolveBaseline(git, baselineTag);+ await requireAncestor(+ git,+ baselineSha,+ applicationSha,+ "Published baseline is outside the checkpoint ancestry",+ );+ const configuration = await readJson(+ git,+ applicationSha,+ "release-please-config.json",+ sectionsSchema,+ );+ const visibleTypes = new Set(+ configuration["changelog-sections"]+ .filter((section) => !section.hidden)+ .map((section) => section.type),+ );+ const commits = readCommits(+ await git([+ "log",+ "--first-parent",+ "-z",+ "--format=%H%x00%s%x00%B",+ `${baselineSha}..${applicationSha}`,+ ]),+ ).filter((commit) => commit.breaking || visibleTypes.has(commit.type));+ const breaking = commits.filter((commit) => commit.breaking);+ if (+ breaking.length > 0 &&+ major(baselineVersion) > 0 &&+ major(expectedVersion) <= major(baselineVersion)+ ) {+ throw new Error(+ `Expected release ${expectedVersion} contains unreleased breaking markers since ${baselineVersion}: ${breaking.map((commit) => `${commit.sha} ${commit.subject}`).join("; ")}. Review compatibility or select a major version.`,+ );+ }+ let snapshot = phase === "publish" ? sourceSha : candidateSha;+ if (stage === "candidate" && snapshot === undefined) {+ snapshot = shaSchema.parse((await git(["rev-parse", "HEAD"])).trim());+ }+ if (phase === "publish" || stage === "candidate") {+ await requireAncestor(+ git,+ applicationSha,+ snapshot,+ "Candidate is outside the selected checkpoint ancestry",+ );+ }+ const missingNotes =+ phase === "publish" || stage === "candidate"+ ? await validateCandidate(git, snapshot, expectedVersion, commits)+ : [];+ return {+ expectedVersion,+ baselineVersion,+ baselineSha,+ sourceSha,+ applicationSha,+ commits,+ missingNotes,+ };+}diff --git a/scripts/verify-release-checkpoint.mjs b/scripts/verify-release-checkpoint.mjsnew file mode 100644index 000000000..e8ce6329e--- /dev/null+++ b/scripts/verify-release-checkpoint.mjs@@ -0,0 +1,44 @@+#!/usr/bin/env node+import { execFile } from "node:child_process";+import { parseArgs, promisify } from "node:util";+import { inspectReleaseCheckpoint } from "./lib/release-checkpoint.mjs";++const execFileAsync = promisify(execFile);++async function git(args) {+ const result = await execFileAsync("git", args, {+ encoding: "utf8",+ maxBuffer: 16 * 1024 * 1024,+ });+ return result.stdout;+}++async function main() {+ const { values } = parseArgs({+ options: {+ phase: { type: "string" },+ stage: { type: "string", default: "source" },+ "release-branch": { type: "string" },+ "source-sha": { type: "string" },+ },+ });+ const report = await inspectReleaseCheckpoint(git, {+ phase: values.phase,+ stage: values.stage,+ releaseBranch: values["release-branch"],+ sourceSha: values["source-sha"],+ });+ process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);+ if (report.missingNotes.length > 0) {+ process.stderr.write(+ `Review ${report.missingNotes.length} additional unreleased mainline entries missing from these release notes; see the ancestry report above.\n`,+ );+ }+}++await main().catch((error) => {+ process.stderr.write(+ `Release checkpoint validation failed: ${error instanceof Error ? error.message : String(error)}\n`,+ );+ process.exitCode = 1;+});diff --git a/tests/boundary/filesystem/releaseCheckpoint.test.ts b/tests/boundary/filesystem/releaseCheckpoint.test.tsnew file mode 100644index 000000000..107b30b00--- /dev/null+++ b/tests/boundary/filesystem/releaseCheckpoint.test.ts@@ -0,0 +1,471 @@+import { execFile } from "node:child_process";+import { mkdir, readFile, writeFile } from "node:fs/promises";+import { join } from "node:path";+import { fileURLToPath } from "node:url";+import { promisify } from "node:util";+import { expect, it } from "vitest";+import { z } from "zod";+import { parse } from "yaml";+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";++const execFileAsync = promisify(execFile);+const verifier = fileURLToPath(+ new URL("../../../scripts/verify-release-checkpoint.mjs", import.meta.url),+);++async function git(+ directory: string,+ args: string[],+ date = "2026-01-04T00:00:00Z",+) {+ const result = await execFileAsync(+ "git",+ [+ "-c",+ "user.name=REA fixture",+ "-c",+ "[email protected]",+ "-c",+ "commit.gpgsign=false",+ "-c",+ `core.hooksPath=${join(directory, "no-hooks")}`,+ ...args,+ ],+ {+ cwd: directory,+ env: { ...process.env, GIT_AUTHOR_DATE: date, GIT_COMMITTER_DATE: date },+ },+ );+ return result.stdout.trim();+}++async function metadata(directory: string, version: string, notes: string) {+ await mkdir(join(directory, "docs"), { recursive: true });+ await mkdir(join(directory, "src"), { recursive: true });+ const files = {+ "package.json": { name: "rea-agents", version },+ "package-lock.json": { version, packages: { "": { version } } },+ ".release-please-manifest.json": { ".": version },+ "server.json": {+ version,+ packages: [{ identifier: "rea-agents", version }],+ },+ "docs/product-catalog.json": { package: { version } },+ "release-please-config.json": {+ "changelog-sections": [+ { type: "feat", hidden: false },+ { type: "fix", hidden: false },+ { type: "chore", hidden: true },+ ],+ },+ };+ for (const [name, value] of Object.entries(files)) {+ await writeFile(join(directory, name), JSON.stringify(value));+ }+ await writeFile(+ join(directory, "src/generatedPackageMetadata.ts"),+ `export const METADATA = {\n version: "${version}",\n};\n`,+ );+ await writeFile(+ join(directory, "CHANGELOG.md"),+ `# Changelog\n\n## [${version}]\n\n${notes}\n`,+ );+}++async function fixture(+ subject = "fix(contracts)!: require absolute paths (#948)",+ footer = "",+) {+ const directory = await createTestTempDirectory("rea-release-ancestry-");+ await git(directory, ["init", "--initial-branch=main"]);+ await metadata(directory, "4.0.0", "Initial release");+ await git(directory, ["add", "."]);+ await git(directory, ["commit", "-m", "chore: seed"], "2026-01-01T00:00:00Z");+ await git(directory, ["switch", "-c", "release/5.0.0"]);+ await metadata(directory, "5.0.0", "Previous release");+ await git(directory, ["add", "."]);+ await git(+ directory,+ ["commit", "-m", "chore: release 5.0.0"],+ "2026-01-03T00:00:00Z",+ );+ const releasedSha = await git(directory, ["rev-parse", "HEAD"]);+ await git(directory, ["tag", "rea-agents-5.0.0"]);+ await git(directory, ["switch", "main"]);+ await writeFile(+ join(directory, "behavior.txt"),+ "Unreleased mainline behavior\n",+ );+ await git(directory, ["add", "."]);+ await git(+ directory,+ ["commit", "-m", subject, "-m", footer],+ "2026-01-02T00:00:00Z",+ );+ const changedSha = await git(directory, ["rev-parse", "HEAD"]);+ await git(directory, [+ "merge",+ "--no-ff",+ "release/5.0.0",+ "-m",+ "chore: sync published baseline",+ ]);+ const sourceSha = await git(directory, ["rev-parse", "HEAD"]);+ return { directory, sourceSha, changedSha, releasedSha };+}++type Fixture = Awaited<ReturnType<typeof fixture>>;++async function candidate(+ f: Fixture,+ version: string,+ notes = "### ⚠ BREAKING CHANGES\n\n* MCP callers must use absolute paths; CLI paths remain compatible. See #948.",+) {+ await metadata(f.directory, version, notes);+ await git(f.directory, ["add", "."]);+ await git(+ f.directory,+ ["commit", "-m", `chore: release ${version}`],+ "2026-01-05T00:00:00Z",+ );+ return git(f.directory, ["rev-parse", "HEAD"]);+}++function verify(+ f: Pick<Fixture, "directory" | "sourceSha">,+ version = "6.0.0",+ phase = "prepare",+ stage = "candidate",+) {+ return execFileAsync(+ process.execPath,+ [+ verifier,+ "--phase",+ phase,+ "--stage",+ stage,+ "--release-branch",+ `release/${version}`,+ "--source-sha",+ f.sourceSha,+ ],+ { cwd: f.directory },+ );+}++const reportSchema = z.object({+ expectedVersion: z.string(),+ baselineVersion: z.string(),+ applicationSha: z.string(),+ commits: z.array(+ z.object({ sha: z.string(), subject: z.string(), breaking: z.boolean() }),+ ),+ missingNotes: z.array(+ z.object({+ sha: z.string(),+ subject: z.string(),+ type: z.string().optional(),+ breaking: z.boolean(),+ }),+ ),+});++it("retains an unreleased breaking commit hidden by the side-branch chronological cutoff", async () => {+ const f = await fixture();+ const walk = (+ await git(f.directory, ["log", "--format=%H", f.sourceSha])+ ).split("\n");+ expect(walk.slice(0, walk.indexOf(f.releasedSha))).not.toContain(+ f.changedSha,+ );+ await candidate(f, "6.0.0");+ const result = await verify(f);+ const report = reportSchema.parse(JSON.parse(result.stdout));+ expect(report).toMatchObject({+ expectedVersion: "6.0.0",+ baselineVersion: "5.0.0",+ missingNotes: [],+ });+ expect(report.commits).toContainEqual({+ sha: f.changedSha,+ subject: "fix(contracts)!: require absolute paths (#948)",+ breaking: true,+ });+});++it("rejects a wrong bot version before publication", async () => {+ const f = await fixture();+ await candidate(f, "5.1.0");+ await expect(verify(f)).rejects.toMatchObject({+ code: 1,+ stderr: expect.stringContaining(+ "declares 5.1.0; release branch requires 6.0.0",+ ),+ });+});++it("rejects a requested minor that omits the breaking ancestry", async () => {+ const f = await fixture();+ await expect(verify(f, "5.1.0", "prepare", "source")).rejects.toMatchObject({+ code: 1,+ stderr: expect.stringContaining("contains unreleased breaking markers"),+ });+});++it("cannot satisfy migration references with notes retained from an older release", async () => {+ const f = await fixture();+ await candidate(+ f,+ "6.0.0",+ "### Features\n\nNew tool\n\n## [5.0.0]\n\n### ⚠ BREAKING CHANGES\n\nSee #948.",+ );+ await expect(verify(f)).rejects.toMatchObject({+ code: 1,+ stderr: expect.stringContaining(+ "migration notes omit unreleased breaking changes",+ ),+ });+});++it("recognizes a BREAKING CHANGE footer without a bang in the subject", async () => {+ const f = await fixture(+ "fix(contracts): change path inputs (#948)",+ "BREAKING CHANGE: relative MCP paths are rejected",+ );+ await expect(verify(f, "5.1.0", "prepare", "source")).rejects.toMatchObject({+ code: 1,+ stderr: expect.stringContaining("contains unreleased breaking markers"),+ });+});++it.each([+ { subject: "fix: correct supported output", version: "5.0.1" },+ { subject: "feat: add an optional inspection", version: "5.1.0" },+])(+ "accepts compatible $version without a major increment",+ async ({ subject, version }) => {+ const f = await fixture(subject);+ await candidate(f, version, `### Changes\n\n${f.changedSha} ${subject}`);+ const report = reportSchema.parse(+ JSON.parse((await verify(f, version)).stdout),+ );+ expect(report.expectedVersion).toBe(version);+ expect(report.commits.every((entry) => !entry.breaking)).toBe(true);+ },+);++it("accepts an exact prerelease version", async () => {+ const f = await fixture();+ await candidate(f, "6.0.0-rc.1");+ await expect(verify(f, "6.0.0-rc.1")).resolves.toMatchObject({ stderr: "" });+});++it.each(["6.01.0", "6.0", "not-a-version", "6.0.0+build"])(+ "rejects invalid release version %s",+ async (version) => {+ const directory = await createTestTempDirectory(+ "rea-release-invalid-version-",+ );+ await expect(+ verify(+ { directory, sourceSha: "1".repeat(40) },+ version,+ "prepare",+ "source",+ ),+ ).rejects.toMatchObject({+ code: 1,+ stderr: expect.stringContaining("must contain an exact SemVer"),+ });+ },+);++it("validates candidate options before inspecting the working directory", async () => {+ const directory = await createTestTempDirectory(+ "rea-release-invalid-candidate-",+ );+ await git(directory, ["init", "--initial-branch=main"]);+ await expect(+ verify({ directory, sourceSha: "1".repeat(40) }, "not-a-version"),+ ).rejects.toMatchObject({+ code: 1,+ stderr: expect.stringContaining("must contain an exact SemVer"),+ });+});++it.each([+ "package-lock.json",+ "server.json",+ "docs/product-catalog.json",+ "src/generatedPackageMetadata.ts",+])("rejects inconsistent version metadata in %s", async (path) => {+ const f = await fixture();+ await candidate(f, "6.0.0");+ await writeFile(+ join(f.directory, path),+ path.endsWith(".ts")+ ? 'export const METADATA = {\n version: "5.1.0",\n};\n'+ : JSON.stringify(+ path === "package-lock.json"+ ? { version: "6.0.0", packages: { "": { version: "5.1.0" } } }+ : path === "server.json"+ ? {+ version: "6.0.0",+ packages: [{ identifier: "rea-agents", version: "5.1.0" }],+ }+ : { package: { version: "5.1.0" } },+ ),+ );+ await git(f.directory, ["add", "."]);+ await git(f.directory, ["commit", "-m", "chore: inconsistent metadata"]);+ await expect(verify(f)).rejects.toMatchObject({+ code: 1,+ stderr: expect.stringContaining(+ "declares 5.1.0; release branch requires 6.0.0",+ ),+ });+});++it("checks a publish merge using its pre-release first parent baseline", async () => {+ const f = await fixture();+ const sourceSha = await candidate(f, "6.0.0");+ const report = reportSchema.parse(+ JSON.parse(+ (await verify({ ...f, sourceSha }, "6.0.0", "publish", "source")).stdout,+ ),+ );+ expect(report.applicationSha).toBe(f.sourceSha);+ expect(report.baselineVersion).toBe("5.0.0");+});++it("reports other omitted entries for review without inventing a breaking change", async () => {+ const f = await fixture("fix: improve diagnostics");+ await candidate(f, "5.0.1", "### Bug Fixes\n\nUpdated diagnostics");+ const result = await verify(f, "5.0.1");+ expect(reportSchema.parse(JSON.parse(result.stdout)).missingNotes).toEqual([+ {+ sha: f.changedSha,+ subject: "fix: improve diagnostics",+ type: "fix",+ breaking: false,+ },+ ]);+ expect(result.stderr).toContain("additional unreleased mainline entries");+});++it("reports a missing published tag with recovery advice", async () => {+ const f = await fixture();+ await git(f.directory, ["tag", "-d", "rea-agents-5.0.0"]);+ await expect(verify(f, "6.0.0", "prepare", "source")).rejects.toMatchObject({+ code: 1,+ stderr: expect.stringContaining("Fetch release tags"),+ });+});++it("rejects a published baseline outside the selected ancestry", async () => {+ const f = await fixture();+ const next = await candidate(f, "6.0.0");+ await git(f.directory, ["tag", "-f", "rea-agents-5.0.0", next]);+ await expect(verify(f, "6.0.0", "prepare", "source")).rejects.toMatchObject({+ code: 1,+ stderr: expect.stringContaining(+ "Published baseline is outside the checkpoint ancestry",+ ),+ });+});++it("reports malformed candidate JSON with the exact metadata path", async () => {+ const f = await fixture();+ await candidate(f, "6.0.0");+ await writeFile(join(f.directory, "server.json"), "{");+ await git(f.directory, ["add", "."]);+ await git(f.directory, ["commit", "-m", "chore: invalid metadata"]);+ await expect(verify(f)).rejects.toMatchObject({+ code: 1,+ stderr: expect.stringMatching(/server\.json@.*contains invalid JSON/u),+ });+});++it("rejects a candidate from a different source even when versions and notes match", async () => {+ const f = await fixture();+ await git(f.directory, ["switch", "release/5.0.0"]);+ await candidate(f, "6.0.0");+ await expect(verify(f)).rejects.toMatchObject({+ code: 1,+ stderr: expect.stringContaining(+ "Candidate is outside the selected checkpoint ancestry",+ ),+ });+});++it.skipIf(process.platform === "win32").each([true, false])(+ "the actual publish preflight admits the next action only for valid metadata (%s)",+ async (valid) => {+ const f = await fixture();+ const sourceSha = await candidate(f, valid ? "6.0.0" : "5.1.0");+ const workflow = z+ .object({+ jobs: z.object({+ "release-please": z.object({+ steps: z.array(+ z.object({+ name: z.string().optional(),+ run: z.string().optional(),+ }),+ ),+ }),+ }),+ })+ .parse(+ parse(+ await readFile(+ new URL("../../../.github/workflows/release.yml", import.meta.url),+ "utf8",+ ),+ ),+ );+ const command = z+ .string()+ .parse(+ workflow.jobs["release-please"].steps.find(+ (step) =>+ step.name ===+ "Validate checkpoint version and ancestry before release creation",+ )?.run,+ );+ const marker = join(f.directory, "next-release-action");+ const execution = execFileAsync(+ "bash",+ [+ "-e",+ "-o",+ "pipefail",+ "-c",+ `${command}\ntouch "$NEXT_RELEASE_ACTION_MARKER"`,+ ],+ {+ cwd: fileURLToPath(new URL("../../../", import.meta.url)),+ env: {+ ...process.env,+ GIT_DIR: join(f.directory, ".git"),+ GIT_WORK_TREE: f.directory,+ RELEASE_PHASE: "publish",+ RELEASE_BRANCH: "release/6.0.0",+ SOURCE_SHA: sourceSha,+ NEXT_RELEASE_ACTION_MARKER: marker,+ },+ },+ );+ if (valid) {+ await expect(execution).resolves.toMatchObject({ stderr: "" });+ expect(await readFile(marker, "utf8")).toBe("");+ } else {+ await expect(execution).rejects.toMatchObject({+ code: 1,+ stderr: expect.stringContaining("release branch requires 6.0.0"),+ });+ await expect(readFile(marker)).rejects.toMatchObject({ code: "ENOENT" });+ }+ },+);diff --git a/tests/boundary/filesystem/releaseWorkflow.test.ts b/tests/boundary/filesystem/releaseWorkflow.test.tsindex dcacdde57..7385c3e4f 100644--- a/tests/boundary/filesystem/releaseWorkflow.test.ts+++ b/tests/boundary/filesystem/releaseWorkflow.test.ts@@ -43,6 +43,43 @@ async function readReleaseWorkflow() {);}+it("validates the source before release creation and the prepared candidate before generation", async () => {+ const steps = (await readReleaseWorkflow()).jobs["release-please"].steps;+ const source = steps.findIndex(+ (step) =>+ step.name ===+ "Validate checkpoint version and ancestry before release creation",+ );+ const action = steps.findIndex((step) =>+ step.uses?.startsWith("googleapis/release-please-action@"),+ );+ const candidate = steps.findIndex(+ (step) =>+ step.name === "Validate prepared release version and migration notes",+ );+ const generation = steps.findIndex(+ (step) => step.name === "Regenerate release documentation",+ );+ expect(source).toBeGreaterThanOrEqual(0);+ expect(source).toBeLessThan(action);+ expect(steps[source]?.if).toBeUndefined();+ expect(steps[source]?.run).toContain("--source-sha");+ expect(candidate).toBeGreaterThan(action);+ expect(candidate).toBeLessThan(generation);+ expect(steps[candidate]?.if).toBe(+ "inputs.phase == 'prepare' && steps.release.outputs.prs_created == 'true'",+ );+ expect(steps[candidate]?.run).toContain("--stage candidate");+ for (const name of [+ "Check out release controller and Git history",+ "Check out release pull request",+ ]) {+ expect(+ steps.find((step) => step.name === name)?.with?.["fetch-depth"],+ ).toBe(0);+ }+});+it("requires explicit release preparation or publication instead of main pushes", async () => {const workflow = await readReleaseWorkflow();expect(Object.keys(workflow.on)).toEqual(["workflow_dispatch"]);@@ -90,6 +127,13 @@ it.skipIf(process.platform === "win32").each([expect(actionIndex).toBeGreaterThanOrEqual(0);const commands = steps.slice(0, actionIndex)+ .filter((step) =>+ [+ "Validate release selection",+ "Resolve release branch tip",+ "Require the publish dispatch to match the branch tip",+ ].includes(step.name ?? ""),+ ).filter((step) =>step.if === undefined ||