From ff1d06ecb09ce0da4fc2cd812b7b41ae6dad95c3 Mon Sep 17 00:00:00 2001 From: ShuaixinHuang <1836656514@qq.com> Date: Thu, 19 Nov 2026 22:46:31 +0800 Subject: [PATCH] fix(release): keep credit examples inside Markdown fences (#12239) * fix(release): keep credit examples inside Markdown fences * fix(release): share fenced Markdown boundaries * fix(release): parse nested Markdown fences and headings --------- Co-authored-by: morluto <76467478+morluto@users.noreply.github.com> --- package-lock.json | 103 ++++++++++++++++++ package.json | 1 + scripts/lib/release-checkpoint.mjs | 9 +- scripts/lib/release-markdown.mjs | 47 ++++++++ scripts/lib/release-notes-publication.mjs | 10 +- scripts/lib/release-notes.mjs | 85 +++++++-------- scripts/release-notes.mjs | 8 +- .../filesystem/releaseCheckpoint.test.ts | 25 +++++ .../boundary/filesystem/releaseNotes.test.ts | 71 ++++++++++++ .../filesystem/releaseProposal.test.ts | 2 +- 10 files changed, 302 insertions(+), 59 deletions(-) create mode 100644 scripts/lib/release-markdown.mjs diff --git a/package-lock.json b/package-lock.json index 0e7270847f..32633f8fe8 100644 --- a/package-lock.json +++ b/package-lock.json @@ -72,6 +72,7 @@ "jscpd": "5.0.12", "knip": "6.39.0", "lint-staged": "16.4.0", + "markdown-it": "15.0.3", "oxfmt": "0.72.0", "oxlint": "1.87.0", "oxlint-tsgolint": "7.0.2005", @@ -9245,6 +9246,26 @@ "dev": true, "license": "MIT" }, + "node_modules/linkify-it": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-6.1.0.tgz", + "integrity": "sha512-wJ/TwpSDTLepCrQoYWYIExIKg5Zchex2Nn5yk2mFnB+6PtdkHtyLx742md9csRjjOnGkKIS/RrbY7l8D6gT9Vw==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/puzrin" + }, + { + "type": "github", + "url": "https://github.com/sponsors/markdown-it" + } + ], + "license": "MIT", + "dependencies": { + "uc.micro": "^3.0.0" + } + }, "node_modules/lint-staged": { "version": "16.4.0", "resolved": "https://registry.npmjs.org/lint-staged/-/lint-staged-16.4.0.tgz", @@ -9459,6 +9480,64 @@ "dev": true, "license": "MIT" }, + "node_modules/markdown-it": { + "version": "15.0.3", + "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-15.0.3.tgz", + "integrity": "sha512-+Az7Ojz3iRGu8KYMvJ6xVhvrxP3eE+vEtJX75Ow88XBpcQNV/0lGX5ZynIIBftREo4DC2jsveAMDaeltmm8QvQ==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/puzrin" + }, + { + "type": "github", + "url": "https://github.com/sponsors/markdown-it" + } + ], + "license": "MIT", + "dependencies": { + "argparse": "^3.0.3", + "entities": "^8.1.0", + "linkify-it": "^6.1.0", + "mdurl": "^2.1.0", + "punycode.js": "^2.3.1", + "uc.micro": "^3.0.0" + }, + "bin": { + "markdown-it": "bin/markdown-it.mjs" + } + }, + "node_modules/markdown-it/node_modules/argparse": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-3.0.4.tgz", + "integrity": "sha512-fwWK3Zq22l4XJJjx5mcBHGikIk+hJqO+32dPm0Jur7+rtG5x1scOjSfdT9ZKeWHPpsya/l0HHK4tDImBkTrtvA==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/puzrin" + }, + { + "type": "github", + "url": "https://github.com/sponsors/nodeca" + } + ], + "license": "PSF-2.0" + }, + "node_modules/markdown-it/node_modules/entities": { + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/entities/-/entities-8.1.0.tgz", + "integrity": "sha512-kxL7msIffSuh9aaFAMD7rxAIuTRMAHMeBtgHW2yUdWw732ZNh4MehkF2gdjvtdmikkaIP9bFDDJOPlsvm7avrA==", + "dev": true, + "license": "BSD-2-Clause", + "engines": { + "node": ">=20.19.0" + }, + "funding": { + "url": "https://github.com/fb55/entities?sponsor=1" + } + }, "node_modules/math-intrinsics": { "version": "1.1.0", "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz", @@ -9490,6 +9569,13 @@ "url": "https://opencollective.com/unified" } }, + "node_modules/mdurl": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-2.1.0.tgz", + "integrity": "sha512-1+HBaOx0zi/dQWht8rNv9MYf9qqpqL/kxI0hXImU6Y547zM6Sni8BQibt7ifgMcYtQg41ao3Ivd6cnSM86inpg==", + "dev": true, + "license": "MIT" + }, "node_modules/meow": { "version": "8.1.2", "resolved": "https://registry.npmjs.org/meow/-/meow-8.1.2.tgz", @@ -10705,6 +10791,16 @@ "once": "^1.3.1" } }, + "node_modules/punycode.js": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz", + "integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, "node_modules/pure-rand": { "version": "8.4.2", "resolved": "https://registry.npmjs.org/pure-rand/-/pure-rand-8.4.2.tgz", @@ -12258,6 +12354,13 @@ "node": ">=14.17" } }, + "node_modules/uc.micro": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-3.0.0.tgz", + "integrity": "sha512-U3PppEkleoTnIfi8BozMx3yju3qc/L6SwqWo2Sw+54PX+PX0q9I+r1Um5HCmqD7n9VDX5/v3vQH/AjA6deDdtw==", + "dev": true, + "license": "MIT" + }, "node_modules/uglify-js": { "version": "3.19.3", "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-3.19.3.tgz", diff --git a/package.json b/package.json index 35f241e7a8..cc4cb923b1 100644 --- a/package.json +++ b/package.json @@ -441,6 +441,7 @@ "jscpd": "5.0.12", "knip": "6.39.0", "lint-staged": "16.4.0", + "markdown-it": "15.0.3", "oxfmt": "0.72.0", "oxlint": "1.87.0", "oxlint-tsgolint": "7.0.2005", diff --git a/scripts/lib/release-checkpoint.mjs b/scripts/lib/release-checkpoint.mjs index bc75ee730a..2456b1d7b9 100644 --- a/scripts/lib/release-checkpoint.mjs +++ b/scripts/lib/release-checkpoint.mjs @@ -1,5 +1,6 @@ import { gt, major, valid } from "semver"; import { z } from "zod"; +import { releaseSection } from "./release-markdown.mjs"; const shaSchema = z.string().regex(/^[a-f0-9]{40}$/u); const versionSchema = z.object({ version: z.string() }); @@ -139,12 +140,10 @@ function referencesCommit(text, commit) { } function releaseNotes(text, expectedVersion) { - const headings = Array.from(text.matchAll(/^## \[([^\]]+)\].*$/gmu)); - const first = headings[0]; - if (first?.[1] !== expectedVersion || first.index === undefined) { + const section = releaseSection(text, expectedVersion); + if (section === undefined) throw new Error(`CHANGELOG.md must start with release ${expectedVersion}.`); - } - return text.slice(first.index, headings[1]?.index ?? text.length); + return section.lines.map(({ line }) => line).join("\n"); } function breakingSection(notes) { diff --git a/scripts/lib/release-markdown.mjs b/scripts/lib/release-markdown.mjs new file mode 100644 index 0000000000..d8f9607bcd --- /dev/null +++ b/scripts/lib/release-markdown.mjs @@ -0,0 +1,47 @@ +import MarkdownIt from "markdown-it"; + +const parser = new MarkdownIt("commonmark"); +const nonProseBlocks = new Set(["fence", "code_block", "html_block"]); + +export function releaseSection(markdown, expectedVersion) { + // The parser maps block tokens to line intervals. Use the original lines + // to retain source offsets and publish the selected Markdown verbatim. + const lines = Array.from( + markdown.matchAll(/([^\r\n]*)(?:\r\n?|\n|$)/gu), + (match, index) => ({ line: match[1], offset: match.index, index }), + ); + + const excluded = new Set(); + let start; + let end = lines.length; + for (const { type, level, tag, map } of parser.parse(markdown, {})) { + if (!map) continue; + const [first, limit] = map; + if (nonProseBlocks.has(type)) { + for (let index = first; index < limit; index++) excluded.add(index); + continue; + } + if (type !== "heading_open" || level !== 0 || tag !== "h2") continue; + const version = /^## \[([^\]]+)\]/u.exec(lines[first].line)?.[1]; + if (version === undefined) continue; + if (start !== undefined) { + end = first; + break; + } + if (version !== expectedVersion) return undefined; + start = first; + } + + if (start === undefined) return undefined; + const sectionOffset = lines[start].offset; + return { + source: markdown.slice( + sectionOffset, + lines[end]?.offset ?? markdown.length, + ), + lines: lines + .slice(start, end) + .filter(({ index }) => !excluded.has(index)) + .map(({ line, offset }) => ({ line, offset: offset - sectionOffset })), + }; +} diff --git a/scripts/lib/release-notes-publication.mjs b/scripts/lib/release-notes-publication.mjs index 8be8b543c1..5e1ae5afe1 100644 --- a/scripts/lib/release-notes-publication.mjs +++ b/scripts/lib/release-notes-publication.mjs @@ -73,8 +73,10 @@ export async function verifyNotesPublication(run, options) { "Contribution inventory does not start at the published baseline tag", ); await verifyInventoryHistory(run, inventory, source); - return { - status: "verified", - ...verifyReleaseNotes(inventory, await read("CHANGELOG.md"), pr.body), - }; + const { report } = verifyReleaseNotes( + inventory, + await read("CHANGELOG.md"), + pr.body, + ); + return { status: "verified", ...report }; } diff --git a/scripts/lib/release-notes.mjs b/scripts/lib/release-notes.mjs index f1f1f411c8..f8abf4b0cd 100644 --- a/scripts/lib/release-notes.mjs +++ b/scripts/lib/release-notes.mjs @@ -1,6 +1,7 @@ import { createRequire } from "node:module"; import { valid } from "semver"; import { z } from "zod"; +import { releaseSection } from "./release-markdown.mjs"; const sha = z.string().regex(/^[a-f0-9]{40}$/u); const actor = z.object({ @@ -177,28 +178,11 @@ export function contributionSummary(raw) { return `Full contribution record: [${inventory.commits.length} commits and ${inventory.pullRequests.length} merged PR${inventory.pullRequests.length === 1 ? "" : "s"}](https://github.com/${inventory.repository}/blob/rea-agents-${inventory.version}/docs/releases/${inventory.version}.contributions.json).\n`; } -export function selectedReleaseNotes(text, version) { - const headings = [...text.matchAll(/^## \[([^\]]+)\].*$/gmu)]; - if (headings[0]?.[1] !== version) +function readReleaseSection(text, version) { + const section = releaseSection(text, version); + if (section === undefined) throw new Error(`Notes must start with release [${version}]`); - return text - .slice(headings[0].index, headings[1]?.index ?? text.length) - .trim(); -} - -// Notes have one Markdown list item per line; fenced examples are never credit sources. -function proseBullets(text) { - let fence; - return text.split("\n").filter((line) => { - const marker = /^\s*(`{3,}|~{3,})/u.exec(line)?.[1]; - if (marker) { - if (!fence) fence = marker; - else if (marker[0] === fence[0] && marker.length >= fence.length) - fence = undefined; - return false; - } - return !fence && /^[-*] /u.test(line); - }); + return section; } function bulletPrs(bullet, repository) { @@ -281,7 +265,8 @@ function verifyEditorialCredits(inventory, prose) { const errors = []; const requiredByContext = new Map(); const thankedByContext = new Map(); - for (const bullet of proseBullets(prose)) { + for (const bullet of prose) { + if (!/^[-*] /u.test(bullet)) continue; const references = bulletPrs(bullet, inventory.repository); const start = bullet.indexOf("Thanks "); const thanked = new Set( @@ -317,9 +302,27 @@ function verifyEditorialCredits(inventory, prose) { return errors; } +function editorialReleaseLines(notes, lines, inventory) { + const record = contributionRecord(inventory).trim(); + const summary = contributionSummary(inventory).trim(); + const summaryOffset = notes.length - summary.length; + const expected = notes.endsWith(summary) ? summary : record; + const contributionStart = + expected === summary + ? lines.find(({ offset }) => offset === summaryOffset) + : lines.find(({ line }) => line === "### Complete contribution record"); + const start = contributionStart?.offset; + if (start === undefined || notes.slice(start).trim() !== expected) + throw new Error( + "Contribution record differs from inventory; regenerate it with release-notes record", + ); + return lines.filter(({ offset }) => offset < start).map(({ line }) => line); +} + export function verifyReleaseNotes(raw, text, body) { const inventory = releaseInventorySchema.parse(raw); - const notes = selectedReleaseNotes(text, inventory.version); + const { source, lines } = readReleaseSection(text, inventory.version); + const notes = source.trim(); // Release Please's inline issue/PR body limit (pull-request-overflow-handler). if (notes.length > 65_536 || (body !== undefined && body.length > 65_536)) throw new Error( @@ -329,23 +332,10 @@ export function verifyReleaseNotes(raw, text, body) { throw new Error( "Release notes exceed GitHub's body budget; shorten prose without dropping credit", ); - const record = contributionRecord(inventory).trim(); - const summary = contributionSummary(inventory).trim(); - const start = notes.endsWith(summary) - ? notes.length - summary.length - : notes.indexOf("### Complete contribution record"); - if ( - start < 0 || - (notes.slice(start).trim() !== record && - notes.slice(start).trim() !== summary) - ) - throw new Error( - "Contribution record differs from inventory; regenerate it with release-notes record", - ); - const prose = notes.slice(0, start); + const prose = editorialReleaseLines(notes, lines, inventory); const errors = verifyEditorialCredits(inventory, prose); for (const heading of ["Highlights", "Changes", "Fixes"]) - if (!prose.includes(`### ${heading}\n`)) + if (!prose.includes(`### ${heading}`)) errors.push(`Missing ${heading} section`); if (body !== undefined) { // Use the publisher's parser: finding a heading alone does not establish @@ -366,14 +356,17 @@ export function verifyReleaseNotes(raw, text, body) { } if (errors.length) throw new Error(errors.join("\n")); return { - version: inventory.version, - pullRequests: inventory.pullRequests.length, - commits: inventory.commits.length, - unresolvedAuthors: inventory.commits.flatMap((item) => - item.authors - .filter((identity) => identity.user === null) - .map((identity) => ({ sha: item.sha, ...identity })), - ), + notes, + report: { + version: inventory.version, + pullRequests: inventory.pullRequests.length, + commits: inventory.commits.length, + unresolvedAuthors: inventory.commits.flatMap((item) => + item.authors + .filter((identity) => identity.user === null) + .map((identity) => ({ sha: item.sha, ...identity })), + ), + }, }; } diff --git a/scripts/release-notes.mjs b/scripts/release-notes.mjs index 3eea0e529f..f486a6e3fc 100644 --- a/scripts/release-notes.mjs +++ b/scripts/release-notes.mjs @@ -9,7 +9,6 @@ import { contributionSummary, readReleaseHistory, releaseInventorySchema, - selectedReleaseNotes, verifyInventoryHistory, verifyReleaseNotes, } from "./lib/release-notes.mjs"; @@ -119,7 +118,11 @@ async function main() { const body = values["pr-body"] ? await readFile(values["pr-body"], "utf8") : undefined; - const report = verifyReleaseNotes(inventory, notes, body); + const { notes: rendered, report } = verifyReleaseNotes( + inventory, + notes, + body, + ); if (command === "check") { process.stdout.write(`${JSON.stringify(report, null, 2)}\n`); return; @@ -128,7 +131,6 @@ async function main() { throw new Error( "render requires --output (an existing file is never overwritten)", ); - const rendered = selectedReleaseNotes(notes, inventory.version); await writeFile(values.output, `${rendered}\n`, { flag: "wx" }); } diff --git a/tests/boundary/filesystem/releaseCheckpoint.test.ts b/tests/boundary/filesystem/releaseCheckpoint.test.ts index 3ea82dee40..478b82b094 100644 --- a/tests/boundary/filesystem/releaseCheckpoint.test.ts +++ b/tests/boundary/filesystem/releaseCheckpoint.test.ts @@ -510,6 +510,31 @@ it("cannot satisfy migration references with notes retained from an older releas }); }); +it("allows release examples with a release heading before genuine migration notes", async () => { + const f = await fixture(); + await candidate( + f, + "6.0.0", + "- ~~~markdown\n ## [5.0.0]\n ~~~\n\n### ⚠ BREAKING CHANGES\n\nSee #948.", + ); + await expect(verify(f)).resolves.toMatchObject({ stderr: "" }); +}); + +it("requires genuine migration notes outside a fenced Markdown example", async () => { + const f = await fixture(); + await candidate( + f, + "6.0.0", + "### Features\n\n~~~markdown\n### ⚠ BREAKING CHANGES\n\nSee #948.\n~~~", + ); + 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)", diff --git a/tests/boundary/filesystem/releaseNotes.test.ts b/tests/boundary/filesystem/releaseNotes.test.ts index dc4b141297..763e995775 100644 --- a/tests/boundary/filesystem/releaseNotes.test.ts +++ b/tests/boundary/filesystem/releaseNotes.test.ts @@ -334,6 +334,7 @@ it("inventories side branches and paginated credits, then checks and renders syn pullRequests: 1, unresolvedAuthors: [{ name: "Unknown", user: null }], }); + expect(JSON.parse(report.stdout)).not.toHaveProperty("notes"); const output = join(f.directory, "rendered.md"); await f.invoke(["render", "--manifest", f.manifest, "--output", output]); expect(await readFile(output, "utf8")).toBe(f.notes.trim() + "\n"); @@ -770,3 +771,73 @@ it.each(pluginMarketplaces)( }); }, ); + +it.each([ + { + container: "root", + example: [ + "~~~markdown", + "~~~not a closing fence", + "## [example]", + "- Example issue #999.", + "~~~~", + ], + }, + { + container: "list", + example: [ + "- ~~~markdown", + " ## [example]", + " - Example issue #999.", + " ~~~", + ], + }, + { + container: "quoted list", + example: [ + "> - ~~~markdown", + "> ## [example]", + "> - Example issue #999.", + "> ~~~", + ], + }, +])( + "keeps release credit examples inside a $container fence", + async ({ example }) => { + const f = await fixture(); + const block = example.join("\n"); + const notes = f.notes.replace( + "### Changes\n", + `### Changes\n\n${block}\n\n`, + ); + const changelog = `${notes.trimEnd()}\n\n## [6.3.0]\n\n- Historical issue #999.\n`; + const body = join(f.directory, "release-body.md"); + await writeFile(join(f.directory, "CHANGELOG.md"), changelog); + await writeFile(body, releaseBody(notes)); + await f.invoke(["check", "--manifest", f.manifest, "--pr-body", body]); + + await writeFile( + join(f.directory, "CHANGELOG.md"), + changelog.replace(block, `${block}\n\n- Real issue #999.`), + ); + await expect( + f.invoke(["check", "--manifest", f.manifest]), + ).rejects.toMatchObject({ + stderr: expect.stringContaining("Unknown release reference #999"), + }); + }, +); + +it("requires editorial headings in release prose outside code fences", async () => { + const f = await fixture(); + const notes = f.notes.replace( + "### Changes\n", + "~~~markdown\n### Changes\n~~~\n", + ); + await writeFile(join(f.directory, "CHANGELOG.md"), notes); + await expect( + f.invoke(["check", "--manifest", f.manifest]), + ).rejects.toMatchObject({ + stderr: expect.stringContaining("Missing Changes section"), + }); +}); diff --git a/tests/boundary/filesystem/releaseProposal.test.ts b/tests/boundary/filesystem/releaseProposal.test.ts index e42b7f3c9c..98d16a7074 100644 --- a/tests/boundary/filesystem/releaseProposal.test.ts +++ b/tests/boundary/filesystem/releaseProposal.test.ts @@ -1187,7 +1187,7 @@ const releasePatchFixture = async (outsideProject = false) => { project, source, ); - for (const dependency of ["semver", "zod"]) + for (const dependency of ["markdown-it", "semver", "zod"]) await symlink( dirname(require.resolve(`${dependency}/package.json`)), join(dependencies, dependency),