aronrepo 3.0.0 → 3.0.2

package/dist/index.js

@@ -20,7 +20,7 @@ function maxRelease(...releases) {
 *
 * Release notes list the groups in this order.
 */
-const commits = [
+const commits = Object.freeze([
 	{
 		type: "Bump",
 		scope: "Major",
@@ -139,12 +139,12 @@ const commits = [
 		release: false,
 		description: "Maintenance: development dependencies, lockfiles, metadata, agent guidance, and unpublished workspaces."
 	}
-];
+].map((commit) => Object.freeze(commit)));
 /**
 * Types from earlier Aronrepo versions. They still resolve in history so old
 * commits release as before, but `aronrepo check` rejects them in new commits.
 */
-const legacyCommits = [
+const legacyCommits = Object.freeze([
 	{
 		type: "Feat",
 		replacement: "Add"
@@ -161,7 +161,7 @@ const legacyCommits = [
 		type: "Misc",
 		replacement: "Chore"
 	}
-];
+].map((commit) => Object.freeze(commit)));
 const types = [...new Set(commits.map(({ type }) => type))];
 const legacyTypes = legacyCommits.map(({ type }) => type);
 const releaseCommits = commits.filter(({ release }) => release !== false);
@@ -186,6 +186,11 @@ const defaultReleasePathExcludes = [
 	"**/test/**",
 	"**/__tests__/**",
 	"**/*.{test,spec}.*",
+	"**/*.test-d.*",
+	"**/__snapshots__/**",
+	"**/__fixtures__/**",
+	"**/__mocks__/**",
+	"**/fixtures/**",
 	"**/benchmarks/**",
 	"**/examples/**",
 	"**/CHANGELOG.md",
@@ -198,17 +203,34 @@ function defineConfig(config) {
 function getReleasePolicy(config = {}) {
 	const mode = config.release?.mode ?? "explicit";
 	if (!releaseModes.includes(mode)) throw new Error(`Unknown Aronrepo release mode "${String(mode)}". Use one of: ${releaseModes.join(", ")}.`);
+	const paths = config.release?.paths;
+	if (paths !== void 0 && paths !== false) validateReleasePaths(paths);
 	return {
 		mode,
-		...config.release?.paths !== void 0 ? { paths: config.release.paths } : {}
+		...paths !== void 0 ? { paths } : {}
 	};
 }
+function validateReleasePaths(paths) {
+	const isGlobs = (value) => value === void 0 || Array.isArray(value) && value.every((glob) => typeof glob === "string");
+	if (typeof paths !== "object" || paths === null || Array.isArray(paths)) throw new Error("`release.paths` must be `false` or an object with `include` and `exclude` glob arrays.");
+	const { include, exclude } = paths;
+	if (!isGlobs(include)) throw new Error("`release.paths.include` must be an array of globs.");
+	if (!isGlobs(exclude)) throw new Error("`release.paths.exclude` must be an array of globs.");
+}
 const defaultReleasePolicy = { mode: defaultReleaseMode };
-/** Returns a matcher for release paths, or `undefined` when every path may release. */
+/**
+* Returns a matcher for release paths, or `undefined` when every path may release.
+* `include` defaults to every path; `!glob` entries in `include` exclude, as in
+* `package.json` `files`, instead of matching everything else.
+*/
 function createReleasePathMatcher(paths) {
-	if (!paths || !paths.include) return void 0;
-	const include = picomatch(paths.include.length ? paths.include : ["!**"], { dot: true });
-	const exclude = picomatch(paths.exclude ?? defaultReleasePathExcludes, { dot: true });
+	if (!paths) return void 0;
+	const globs = paths.include ?? ["**"];
+	const positive = globs.filter((glob) => !glob.startsWith("!"));
+	const negated = globs.filter((glob) => glob.startsWith("!")).map((glob) => glob.slice(1));
+	if (!positive.length) return () => false;
+	const include = picomatch(positive, { dot: true });
+	const exclude = picomatch([...paths.exclude ?? defaultReleasePathExcludes, ...negated], { dot: true });
 	return (file) => include(file) && !exclude(file);
 }
 /**
@@ -224,61 +246,92 @@ function capRelease(release, type, policy) {
 	if (policy.mode === "explicit" && type !== "Bump" && (release === "major" || release === "minor")) return "patch";
 	return release;
 }
-const headerPattern = /^([A-Z]\w*)(?:\(([0-9A-Z`_#~].*)\))?: ([0-9A-Z`_#~].*)$/;
-const breakingHeaderPattern = /^([A-Z]\w*)(?:\(([^)]*)\))?!: (.+)$/;
-const breakingNotePattern = /^BREAKING[ -]CHANGE:/m;
-const footerLinePattern = /^BREAKING[ -]CHANGE:/;
-const githubRevertPattern = /^Revert "([\s\S]+)"$/;
-const revertHashPattern = /This reverts commit ([0-9a-f]{7,40})/i;
+/**
+* The first character of a scope or summary: an uppercase letter, a letter
+* without case (such as CJK), a digit, or a code, issue, or emphasis marker.
+*/
+const startCharacter = String.raw`[\p{Lu}\p{Lt}\p{Lo}\p{Nd}\x60_#~]`;
+const startPattern = new RegExp(`^${startCharacter}`, "u");
+const headerPattern = new RegExp(String.raw`^([A-Z]\w*)(?:\((${startCharacter}[^)]*)\))?: (${startCharacter}.*)$`, "u");
+const breakingHeaderPattern = new RegExp(String.raw`^([A-Z]\w*)(?:\((${startCharacter}[^)]*)\))?!: (${startCharacter}.*)$`, "u");
+const footerStartPattern = /^BREAKING[ -]CHANGE:[ \t]*(.*)$/;
+const githubRevertPattern = /^(Revert|Reapply) "([\s\S]+)"(?: \(#\d+\))?$/;
+const revertHashPattern = /This reverts commit ([0-9a-f]{7,40})/gi;
+const fencePattern = /^\s*(```|~~~)/;
 const trailerPattern = /^[\w-]+: /;
-/** `BREAKING CHANGE:` footer texts; each runs until a blank line, another footer, or a git trailer. */
-function readBreakingNotes(lines) {
+/**
+* `BREAKING CHANGE:` footers outside code fences. Each runs, line breaks kept,
+* until another footer or a git trailer, as Conventional Commits footers do.
+*/
+function readBreakingFooters(lines) {
 	const notes = [];
+	const starts = [];
 	let current;
-	for (const line of lines) {
-		const start = /^BREAKING[ -]CHANGE:\s*(.*)$/.exec(line);
+	let fenced = false;
+	const finish = () => {
+		if (current) notes.push(current.join("\n").trim());
+		current = void 0;
+	};
+	lines.forEach((line, index) => {
+		if (fencePattern.test(line)) fenced = !fenced;
+		const start = fenced ? null : footerStartPattern.exec(line);
 		if (start) {
-			if (current) notes.push(current.join(" ").trim());
+			finish();
+			starts.push(index);
 			current = [start[1]];
-		} else if (current && line.trim() && !trailerPattern.test(line)) current.push(line.trim());
-		else if (current) {
-			notes.push(current.join(" ").trim());
-			current = void 0;
-		}
-	}
-	if (current) notes.push(current.join(" ").trim());
-	return notes.filter(Boolean);
+		} else if (current && !fenced && trailerPattern.test(line)) finish();
+		else if (current) current.push(line.trimEnd());
+	});
+	finish();
+	return {
+		starts,
+		notes: notes.filter(Boolean)
+	};
+}
+function parseHeader(header) {
+	const regular = headerPattern.exec(header);
+	const match = regular ?? breakingHeaderPattern.exec(header);
+	return match ? {
+		type: match[1],
+		scope: match[2],
+		subject: match[3],
+		breaking: !regular
+	} : void 0;
 }
 function parseCommit(message, hash) {
-	const [header = "", ...rest] = message.replace(/\r\n/g, "\n").trim().split("\n");
+	const [rawHeader = "", ...rest] = message.replace(/\r\n?/g, "\n").trim().split("\n");
+	const header = rawHeader.trimEnd();
 	const body = rest.join("\n").trim();
 	const parsed = {
 		header,
 		body,
 		...hash ? { hash } : {}
 	};
+	const footers = readBreakingFooters(rest);
 	const layout = [];
 	if (rest.length && rest[0].trim()) layout.push("body-leading-blank");
-	if (rest.some((line, index) => index > 0 && footerLinePattern.test(line) && rest[index - 1].trim())) layout.push("footer-leading-blank");
+	if (footers.starts.some((index) => index > 0 && rest[index - 1].trim())) layout.push("footer-leading-blank");
 	if (layout.length) parsed.layout = layout;
-	const breakingNotes = readBreakingNotes(rest);
-	if (breakingNotes.length) parsed.breakingNotes = breakingNotes;
-	const regular = headerPattern.exec(header);
-	const match = regular ?? breakingHeaderPattern.exec(header);
+	if (footers.notes.length) parsed.breakingNotes = footers.notes;
+	const match = parseHeader(header);
 	if (match) {
-		parsed.type = match[1];
-		if (match[2]) parsed.scope = match[2];
-		parsed.subject = match[3];
-		if (!regular) parsed.breaking = "header";
+		parsed.type = match.type;
+		if (match.scope) parsed.scope = match.scope;
+		parsed.subject = match.subject;
+		if (match.breaking) parsed.breaking = "header";
 	}
-	if (!parsed.breaking && breakingNotePattern.test(body)) parsed.breaking = "footer";
+	if (!parsed.breaking && footers.starts.length) parsed.breaking = "footer";
 	const githubRevert = githubRevertPattern.exec(header);
 	if (githubRevert || parsed.type === "Revert") {
-		const revertedHeader = githubRevert?.[1] ?? (parsed.subject && headerPattern.test(parsed.subject) ? parsed.subject : void 0);
-		const revertedHash = revertHashPattern.exec(body)?.[1];
+		const revertedHeader = githubRevert?.[2] ?? (parsed.subject && parseHeader(parsed.subject) ? parsed.subject : void 0);
+		const hashes = [...new Set([...body.matchAll(revertHashPattern)].map((found) => found[1].toLowerCase()))];
 		parsed.revert = {
 			...revertedHeader ? { header: revertedHeader } : {},
-			...revertedHash ? { hash: revertedHash } : {}
+			...hashes.length ? {
+				hash: hashes[0],
+				hashes
+			} : {},
+			...githubRevert?.[1] === "Reapply" ? { reapply: true } : {}
 		};
 	}
 	return parsed;
@@ -295,7 +348,7 @@ const nonReleaseAlternatives = [
 	"Example"
 ];
 function suggestNonReleaseHeader(commit) {
-	const subject = commit.subject ?? "";
+	const subject = (commit.subject ?? commit.header).replace(/\.+$/, "");
 	const scope = commit.scope ? `(${commit.scope})` : "";
 	switch (commit.type) {
 		case "Docs": return `Docs: ${subject}`;
@@ -303,17 +356,18 @@ function suggestNonReleaseHeader(commit) {
 		default: return `Chore${scope}: ${subject}`;
 	}
 }
-const looseHeaderPattern = /^(\w+)(?:\(([^)]*)\))?(!)?: ?(.*)$/;
-function diagnoseHeader(header) {
+const looseHeaderPattern = /^(\w+)(?:\(([^)]*)\))?(!)?:(\s*)(.*)$/;
+function diagnoseHeader(header, mode) {
 	const format = "Use `Type(Scope): Summary` or `Type: Summary` with an Aronrepo commit type.";
 	const match = looseHeaderPattern.exec(header);
 	if (!match) return format;
-	const [, type, scope, bang, subject] = match;
-	if (!/^[A-Z]/.test(type)) return `The type \`${type}\` must be PascalCase, such as \`${type[0].toUpperCase()}${type.slice(1)}\`. ${format}`;
-	if (bang) return `Aronrepo headers do not use \`!\`. ${format}`;
-	if (scope !== void 0 && !/^[0-9A-Z`_#~]/.test(scope)) return `The scope \`${scope}\` must start with an uppercase letter or digit. ${format}`;
+	const [, type, scope, bang, space, subject] = match;
+	if (!/^[A-Z]/.test(type)) return `The type \`${type}\` must be PascalCase, such as \`${normalizeType(`${type[0].toUpperCase()}${type.slice(1)}`)}\`. ${format}`;
+	if (bang && mode === "explicit") return `Aronrepo headers do not use \`!\` in explicit mode. ${format}`;
+	if (scope !== void 0 && !startPattern.test(scope)) return `The scope \`${scope}\` must start with an uppercase letter or digit. ${format}`;
+	if (space !== " ") return `Put exactly one space after the colon. ${format}`;
 	if (!subject) return `The summary is empty. ${format}`;
-	if (!/^[0-9A-Z`_#~]/.test(subject)) return `The summary must start with an uppercase letter or digit. ${format}`;
+	if (!startPattern.test(subject)) return `The summary must start with an uppercase letter, a digit, or a letter without case such as CJK. ${format}`;
 	return format;
 }
 function formatRelease(release) {
@@ -328,6 +382,7 @@ function resolveCommitRelease(input, policy = defaultReleasePolicy, options = {}
 		...commit.scope ? { scope: commit.scope } : {},
 		...commit.subject ? { subject: commit.subject } : {},
 		...commit.breakingNotes ? { breakingNotes: commit.breakingNotes } : {},
+		...commit.breaking ? { breaking: commit.breaking } : {},
 		release: false,
 		reasons: [],
 		violations: []
@@ -337,7 +392,7 @@ function resolveCommitRelease(input, policy = defaultReleasePolicy, options = {}
 		decision.reasons.push("Header does not follow `Type(Scope): Summary`; no release.");
 		decision.violations.push({
 			rule: "header-format",
-			message: diagnoseHeader(commit.header)
+			message: diagnoseHeader(commit.header, policy.mode)
 		});
 		return decision;
 	} else if (!types.includes(commit.type) && !legacyTypes.includes(commit.type)) {
@@ -348,13 +403,21 @@ function resolveCommitRelease(input, policy = defaultReleasePolicy, options = {}
 		});
 		return decision;
 	} else if (!findCommitRule(commit.type, commit.scope)) {
+		const scoped = commits.filter(({ type }) => type === commit.type).map(({ type, scope }) => `\`${type}(${scope})\``).join(", ");
 		decision.reasons.push(`\`${commit.type}${commit.scope ? `(${commit.scope})` : ""}\` is not an Aronrepo commit type; no release.`);
 		decision.violations.push({
 			rule: "unknown-type",
-			message: `\`${commit.type}\` needs a scope: ${commits.filter(({ type }) => type === commit.type).map(({ type, scope }) => `\`${type}(${scope})\``).join(", ")}.`
+			message: commit.scope ? `\`${commit.type}(${commit.scope})\` has an unknown scope. Use one of: ${scoped}.` : `\`${commit.type}\` needs a scope: ${scoped}.`
 		});
 		return decision;
 	}
+	const knownScope = commit.scope && commits.find(({ type, scope }) => type === normalizeType(commit.type) && scope && scope !== commit.scope && scope.toLowerCase() === commit.scope.toLowerCase())?.scope;
+	if (knownScope) decision.violations.push({
+		rule: "scope-case",
+		severity: "warning",
+		message: `\`${commit.type}(${commit.scope})\` is treated as \`${commit.type}\`. Write \`${commit.type}(${knownScope})\` for that rule.`,
+		suggestion: `${commit.type}(${knownScope}): ${commit.subject ?? ""}`
+	});
 	if (commit.subject?.endsWith(".")) decision.violations.push({
 		rule: "subject-full-stop",
 		message: "The summary must not end with a period.",
@@ -377,8 +440,15 @@ function resolveCommitRelease(input, policy = defaultReleasePolicy, options = {}
 	}
 	let release;
 	if (decision.type === "Revert" && commit.revert?.header) {
-		release = resolveCommitRelease(commit.revert.header, policy, options).release;
-		decision.reasons.push(`Reverts \`${commit.revert.header}\`, which releases ${formatRelease(release)}.`);
+		const reverted = resolveCommitRelease(commit.revert.header, policy, options);
+		const verb = commit.revert.reapply ? "Reapplies" : "Reverts";
+		if (reverted.type === "Bump" && reverted.release) {
+			release = "patch";
+			decision.reasons.push(`${verb} \`${commit.revert.header}\`; reverting a \`Bump\` releases patch.`);
+		} else {
+			release = reverted.release;
+			decision.reasons.push(`${verb} \`${commit.revert.header}\`, which releases ${formatRelease(release)}.`);
+		}
 	} else {
 		const rule = findCommitRule(decision.type, decision.scope);
 		release = capRelease(rule.release, decision.type, policy);
@@ -402,10 +472,16 @@ function resolveCommitRelease(input, policy = defaultReleasePolicy, options = {}
 	const isBump = decision.type === "Bump";
 	if (release && !isBump && options.files && options.isReleasePath) {
 		if (!options.files.filter(options.isReleasePath).length) {
+			const label = `\`${decision.type}${decision.scope ? `(${decision.scope})` : ""}\``;
+			const onlyBreaking = commit.type !== void 0 && findCommitRule(commit.type, commit.scope)?.release === false;
 			decision.reasons.push("No changed file ships in a published package; no release.");
-			decision.violations.push({
+			decision.violations.push(onlyBreaking ? {
+				rule: "release-paths",
+				message: `${label} releases ${formatRelease(release)} only because of its breaking marker, but the commit changes no release paths. Remove the breaking marker.`,
+				...commit.breaking === "header" ? { suggestion: commit.header.replace("!:", ":") } : {}
+			} : {
 				rule: "release-paths",
-				message: `\`${decision.type}${decision.scope ? `(${decision.scope})` : ""}\` releases ${formatRelease(release)}, but the commit changes no release paths. Use a non-release type: ${nonReleaseAlternatives.join(", ")}.`,
+				message: `${label} releases ${formatRelease(release)}, but the commit changes no release paths. Use a non-release type: ${nonReleaseAlternatives.join(", ")}.`,
 				suggestion: suggestNonReleaseHeader({
 					...commit,
 					type: decision.type
@@ -423,16 +499,27 @@ function resolveRelease(inputs, policy = defaultReleasePolicy, options = {}) {
 		...options,
 		...inputs[index].files ? { files: inputs[index].files } : {}
 	}));
-	parsed.forEach((commit, index) => {
-		const revertedHash = commit.revert?.hash;
-		if (!revertedHash) return;
-		const revertedIndex = parsed.findIndex((candidate) => candidate.hash?.startsWith(revertedHash) || candidate.hash && revertedHash.startsWith(candidate.hash));
-		if (revertedIndex === -1 || revertedIndex === index) return;
-		for (const [target, other] of [[index, revertedIndex], [revertedIndex, index]]) {
-			decisions[target].release = false;
-			decisions[target].reasons.push(`Cancelled by \`${parsed[other].header}\` in the same release.`);
+	const cancelled = /* @__PURE__ */ new Set();
+	const cancel = (target, other) => {
+		cancelled.add(target);
+		decisions[target].release = false;
+		decisions[target].reasons.push(`Cancelled by \`${parsed[other].header}\` in the same release.`);
+	};
+	for (let index = parsed.length - 1; index >= 0; index--) {
+		const hashes = parsed[index].revert?.hashes ?? [];
+		if (!hashes.length || cancelled.has(index)) continue;
+		const targets = hashes.map((revertedHash) => {
+			const matches = parsed.flatMap((candidate, candidateIndex) => candidateIndex < index && candidate.hash?.toLowerCase().startsWith(revertedHash) ? [candidateIndex] : []);
+			return matches.length === 1 && !cancelled.has(matches[0]) ? matches[0] : void 0;
+		});
+		for (const target of targets) if (target !== void 0) cancel(target, index);
+		if (targets.every((target) => target !== void 0)) {
+			const reverted = targets.map((target) => parsed[target].header).join("`, `");
+			cancelled.add(index);
+			decisions[index].release = false;
+			decisions[index].reasons.push(`Cancelled by \`${reverted}\` in the same release.`);
 		}
-	});
+	}
 	return {
 		release: maxRelease(...decisions.map(({ release }) => release)),
 		commits: decisions
@@ -570,7 +657,7 @@ function getReleaseTable(policy = defaultReleasePolicy) {
 		none: []
 	};
 	for (const { type, scope } of commits) rows[getReleaseType(type, scope, policy) || "none"].push(formatRule(type, scope));
-	if (policy.mode === "auto") rows.major.push("`BREAKING CHANGE:` footer");
+	if (policy.mode === "auto") rows.major.push("`BREAKING CHANGE:` footer", "`Type!:` header");
 	return rows;
 }
 const agentsBlockStart = "<!-- aronrepo:commit-policy:start -->";
@@ -578,7 +665,8 @@ const agentsBlockEnd = "<!-- aronrepo:commit-policy:end -->";
 /** Renders the generated commit policy block for AGENTS.md, including its markers. */
 function renderAgentsBlock(policy = defaultReleasePolicy, options = {}) {
 	const agent = getAgentCommitPolicy(policy, options);
-	const paths = options.releasePaths;
+	const paths = options.releasePaths ?? (policy.paths || void 0);
+	const excludes = paths ? paths.exclude ?? defaultReleasePathExcludes : [];
 	const typeRows = commits.map(({ type, scope, description }) => `| ${formatRule(type, scope)} | ${getReleaseType(type, scope, policy) || "none"} | ${description} |`);
 	return [
 		agentsBlockStart,
@@ -586,7 +674,7 @@ function renderAgentsBlock(policy = defaultReleasePolicy, options = {}) {
 		"",
 		"## Commit and Release Policy",
 		"",
-		`Release mode: **${policy.mode}**. ${policy.mode === "explicit" ? "Only the repository owner decides minor and major versions, with `Bump(Minor)` and `Bump(Major)` commits." : "`Add` releases minor versions, and `BREAKING CHANGE:` footers release major versions."}`,
+		`Release mode: **${policy.mode}**. ${policy.mode === "explicit" ? "Only the repository owner decides minor and major versions, with `Bump(Minor)` and `Bump(Major)` commits." : "`Add` releases minor versions, and `BREAKING CHANGE:` footers and `Type!:` headers release major versions."}`,
 		"",
 		"Commit headers and PR titles use `Type(Scope): Summary` or `Type: Summary`: a PascalCase type, an optional scope for the package or area, and a sentence-case summary without a trailing period.",
 		"",
@@ -613,13 +701,11 @@ function renderAgentsBlock(policy = defaultReleasePolicy, options = {}) {
 		"",
 		"### Release paths",
 		"",
-		...paths?.include ? [
+		...!paths ? ["Every path can release a version in this repository."] : paths.include?.length === 0 ? ["No path can release a version in this repository."] : [...paths.include ? [
 			"Only changes to these files can release a version:",
 			"",
-			...paths.include.map((glob) => `- \`${glob}\``),
-			"",
-			`Excluding: ${(paths.exclude ?? defaultReleasePathExcludes).map((glob) => `\`${glob}\``).join(", ")}.`
-		] : ["Every path can release a version in this repository."],
+			...paths.include.map((glob) => `- \`${glob}\``)
+		] : ["Every path can release a version, except the excluded ones."], ...excludes.length ? ["", `Excluding: ${excludes.map((glob) => `\`${glob}\``).join(", ")}.`] : []],
 		"",
 		"### Before handing off commits",
 		"",
@@ -711,34 +797,100 @@ function getNextVersion(channel, release, tags) {
 	const target = stable ? semver.inc(stable, release) : initialVersion;
 	if (!channel.prerelease) return target;
 	const previous = highest(channelVersions(reachable, channel.prerelease).filter((version) => !stable || semver.gt(version, stable)));
-	const core = previous && semver.gte(coreVersion(previous), target) ? coreVersion(previous) : target;
-	const numbers = channelVersions(versionsOf(tags.all), channel.prerelease).filter((version) => coreVersion(version) === core).map((version) => Number(semver.prerelease(version)?.[1] ?? 0));
+	let core = previous && semver.gte(coreVersion(previous), target) ? coreVersion(previous) : target;
+	const all = versionsOf(tags.all);
+	const released = highest(stableVersions(all));
+	if (released && semver.lte(core, released)) core = semver.inc(released, release);
+	const numbers = channelVersions(all, channel.prerelease).filter((version) => coreVersion(version) === core).map((version) => semver.prerelease(version)?.[1] ?? 0).filter((number) => Number.isInteger(number));
 	return `${core}-${channel.prerelease}.${Math.max(0, ...numbers) + 1}`;
 }
 // src/notes.ts
 const breakingTitle = "⚠ Breaking Changes";
 function groupOf(decision) {
-	if (decision.type === "Revert") return "Reverts";
 	return findCommitRule(decision.type, decision.scope)?.group;
 }
+/** Splits text into plain parts and CommonMark code spans: a backtick run closed by a run of the same length. */
+function splitCodeSpans(text) {
+	const parts = [];
+	let plain = "";
+	let index = 0;
+	while (index < text.length) {
+		if (text[index] === "\\" && text[index + 1] === "`") {
+			plain += text.slice(index, index + 2);
+			index += 2;
+			continue;
+		}
+		if (text[index] !== "`") {
+			plain += text[index++];
+			continue;
+		}
+		const run = /^`+/.exec(text.slice(index))[0];
+		const close = new RegExp(`(?<!\`)${run}(?!\`)`).exec(text.slice(index + run.length));
+		if (!close) {
+			plain += run;
+			index += run.length;
+			continue;
+		}
+		if (plain) parts.push({
+			code: false,
+			text: plain
+		});
+		plain = "";
+		const end = index + run.length + close.index + run.length;
+		parts.push({
+			code: true,
+			text: text.slice(index, end)
+		});
+		index = end;
+	}
+	if (plain) parts.push({
+		code: false,
+		text: plain
+	});
+	return parts;
+}
+/**
+* Keeps commit text from acting on GitHub outside code spans: `<` would start
+* HTML, as in `Array<string>`, and `@name` or `@scope/pkg` would notify a user
+* or team on every release.
+*/
+function escapeMarkdown(text) {
+	return splitCodeSpans(text).map(({ code, text: part }) => code ? part : part.replace(/</g, "&lt;").replace(/(^|[^\w`])(@[A-Za-z0-9][\w-]*(?:\/[\w.-]+)?)/g, "$1`$2`")).join("");
+}
+/** A list item; continuation lines are indented so they stay in the item. */
+function listItem(text) {
+	return `- ${text.split("\n").map((line, index) => index && line ? `  ${line}` : line).join("\n")}`;
+}
 function formatEntry(decision, repositoryUrl) {
-	const summary = decision.subject ?? decision.header;
-	const scope = decision.scope ? `**${decision.scope}:** ` : "";
+	const summary = escapeMarkdown(decision.subject ?? decision.header);
+	const scope = decision.scope ? `**${escapeMarkdown(decision.scope)}:** ` : "";
 	const hash = decision.hash ? decision.hash.slice(0, 7) : void 0;
 	return `- ${scope}${summary}${hash ? repositoryUrl ? ` ([${hash}](${repositoryUrl}/commit/${decision.hash}))` : ` (${hash})` : ""}`;
 }
+/** The page that lists every change of a release: the compare view, or the commits of a first release. */
+function getChangelogUrl(repositoryUrl, version, previousTag) {
+	const base = repositoryUrl.replace(/\/+$/, "");
+	const tag = `v${version.replace(/^v/, "")}`;
+	return previousTag ? `${base}/compare/${previousTag}...${tag}` : `${base}/commits/${tag}`;
+}
 /**
 * Markdown release notes. Only commits that release appear, grouped by type in
 * the order of the commit table; `BREAKING CHANGE:` footers of major releases
 * come first.
 */
 function renderReleaseNotes(options) {
-	const { version, previousTag, repositoryUrl } = options;
-	const tag = `v${version}`;
-	const lines = [`## ${repositoryUrl && previousTag ? `[${version}](${repositoryUrl}/compare/${previousTag}...${tag})` : version}${options.date ? ` (${options.date})` : ""}`];
+	const { previousTag } = options;
+	const version = options.version.replace(/^v/, "");
+	const repositoryUrl = options.repositoryUrl?.replace(/\/+$/, "");
+	const changelogUrl = repositoryUrl ? getChangelogUrl(repositoryUrl, version, previousTag) : void 0;
+	const sections = [];
 	const released = options.commits.filter(({ release }) => release);
-	const breaking = released.filter(({ release }) => release === "major").flatMap(({ breakingNotes }) => breakingNotes ?? []);
-	if (breaking.length) lines.push("", `### ${breakingTitle}`, "", ...breaking.map((note) => `- ${note}`));
+	const breaking = released.filter(({ release }) => release === "major").flatMap(({ breakingNotes, breaking: marker, subject }) => breakingNotes?.length ? breakingNotes : marker === "header" && subject ? [subject] : []);
+	if (breaking.length) sections.push([
+		`### ${breakingTitle}`,
+		"",
+		...breaking.map((note) => listItem(escapeMarkdown(note)))
+	]);
 	const groups = /* @__PURE__ */ new Map();
 	for (const decision of released) {
 		const group = groupOf(decision);
@@ -749,11 +901,19 @@ function renderReleaseNotes(options) {
 		const entries = groups.get(group);
 		if (!entries) continue;
 		const sorted = [...entries].sort((a, b) => (a.scope ?? "").localeCompare(b.scope ?? "", "en") || (a.subject ?? a.header).localeCompare(b.subject ?? b.header, "en"));
-		lines.push("", `### ${group}`, "", ...sorted.map((decision) => formatEntry(decision, repositoryUrl)));
+		sections.push([
+			`### ${group}`,
+			"",
+			...sorted.map((decision) => formatEntry(decision, repositoryUrl))
+		]);
 	}
-	if (!breaking.length && !groups.size) lines.push("", "No changes to published packages.");
-	return `${lines.join("\n")}\n`;
-}
-export { agentCommitPolicy, agentsBlockEnd, agentsBlockStart, commits, compareRelease, createReleasePathMatcher, defaultReleaseMode, defaultReleasePathExcludes, defaultReleasePolicy, defineConfig, findCommitRule, getAgentCommitPolicy, getBaseTag, getLatestStableVersion, getNextVersion, getReleaseChannel, getReleasePolicy, getReleaseTable, getReleaseType, headerPattern, initialVersion, legacyCommits, legacyTypes, maxRelease, nonReleaseAlternatives, nonReleaseCommits, nonReleaseTypes, normalizeType, parseCommit, parseVersionTag, prereleaseChannels, releaseBranches, releaseCommits, releaseGroups, releaseLevels, releaseModes, releaseTypes, renderAgentsBlock, renderReleaseNotes, resolveCommitRelease, resolveRelease, toVersionTag, types };
+	if (!sections.length) sections.push([released.length ? "Version bump only; no other changes to published packages." : "No changes to published packages."]);
+	if (options.heading) {
+		const title = changelogUrl ? `[${version}](${changelogUrl})` : version;
+		sections.unshift([`## ${title}${options.date ? ` (${options.date})` : ""}`]);
+	} else if (changelogUrl) sections.push([`**Full Changelog**: ${changelogUrl}`]);
+	return `${sections.map((section) => section.join("\n")).join("\n\n")}\n`;
+}
+export { agentCommitPolicy, agentsBlockEnd, agentsBlockStart, commits, compareRelease, createReleasePathMatcher, defaultReleaseMode, defaultReleasePathExcludes, defaultReleasePolicy, defineConfig, findCommitRule, getAgentCommitPolicy, getBaseTag, getChangelogUrl, getLatestStableVersion, getNextVersion, getReleaseChannel, getReleasePolicy, getReleaseTable, getReleaseType, headerPattern, initialVersion, legacyCommits, legacyTypes, maxRelease, nonReleaseAlternatives, nonReleaseCommits, nonReleaseTypes, normalizeType, parseCommit, parseVersionTag, prereleaseChannels, releaseBranches, releaseCommits, releaseGroups, releaseLevels, releaseModes, releaseTypes, renderAgentsBlock, renderReleaseNotes, resolveCommitRelease, resolveRelease, toVersionTag, types };
 
 //# sourceMappingURL=index.js.map