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>
This commit is contained in:
ShuaixinHuangandmorluto authored and GitHub committed 2026-11-19 14:46:31 +00:00
1 parent 1b172f1e02
commit ff1d06ecb0
10 files changed
+302 -59

No files matched your search

+103
View File
@@ -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",
+1
View File
@@ -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",
+4 -5
View File
@@ -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) {
+47
View File
@@ -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 })),
};
}
+6 -4
View File
@@ -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 };
}
+39 -46
View File
@@ -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 })),
),
},
};
}
+5 -3
View File
@@ -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" });
}
@@ -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)",
@@ -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"),
});
});
@@ -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),