scripts/release/generate-changelog.mjs
GitHub#!/usr/bin/env node
import { execFileSync } from "node:child_process";
import { readFileSync, writeFileSync } from "node:fs";
import { resolve } from "node:path";
import { fileURLToPath } from "node:url";
const defaultTypes = new Set(["feat", "fix", "perf"]);
const typeTitles = new Map([
["feat", "Features"],
["fix", "Bug Fixes"],
["perf", "Performance"],
["docs", "Documentation"],
["test", "Tests"],
["refactor", "Refactoring"],
["ci", "Continuous Integration"],
["build", "Build System"],
["chore", "Chores"],
["revert", "Reverts"],
["other", "Other Changes"],
]);
const typeOrder = ["feat", "fix", "perf", "docs", "test", "refactor", "ci", "build", "chore", "revert", "other"];
export function parseArgs(argv) {
const options = {
from: null,
to: "HEAD",
version: null,
date: new Date().toISOString().slice(0, 10),
repoUrl: null,
includeInternal: false,
skips: new Set(),
output: null,
prepend: null,
help: false,
};
for (let i = 0; i < argv.length; i += 1) {
const arg = argv[i];
if (arg === "--from") {
options.from = readValue(argv, ++i, arg);
} else if (arg === "--to") {
options.to = readValue(argv, ++i, arg);
} else if (arg === "--version") {
options.version = readValue(argv, ++i, arg).replace(/^v/, "");
} else if (arg === "--date") {
options.date = readValue(argv, ++i, arg);
} else if (arg === "--repo") {
options.repoUrl = readValue(argv, ++i, arg).replace(/\/$/, "");
} else if (arg === "--include-internal") {
options.includeInternal = true;
} else if (arg === "--skip") {
options.skips.add(readValue(argv, ++i, arg));
} else if (arg === "--output") {
options.output = readValue(argv, ++i, arg);
} else if (arg === "--prepend") {
options.prepend = readValue(argv, ++i, arg);
} else if (arg === "--help" || arg === "-h") {
options.help = true;
} else {
throw new Error(`unknown option: ${arg}`);
}
}
if (!options.help && !options.version) {
throw new Error("--version is required");
}
return options;
}
export function parseGitLog(output) {
if (!output.trim()) {
return [];
}
return output
.split("\x1e")
.filter((entry) => entry.trim())
.map((entry) => {
const [hash, shortHash, subject, body = ""] = entry.trim().split("\x00");
return parseCommit({ hash, shortHash, subject, body });
});
}
export function parseCommit(commit) {
const match = /^(?<type>[a-z]+)(?:\((?<scope>[^)]+)\))?(?<breaking>!)?:\s+(?<description>.+)$/.exec(
commit.subject,
);
const breaking = Boolean(match?.groups?.breaking) || /\n?BREAKING[ -]CHANGE:/i.test(commit.body ?? "");
if (!match) {
return {
...commit,
type: "other",
scope: null,
description: commit.subject,
breaking,
};
}
return {
...commit,
type: match.groups.type,
scope: match.groups.scope ?? null,
description: match.groups.description,
breaking,
};
}
export function filterCommits(commits, { includeInternal = false } = {}) {
const typeFiltered = includeInternal
? commits
: commits.filter((commit) => defaultTypes.has(commit.type) || commit.type === "other" || commit.breaking);
return typeFiltered;
}
export function skipCommits(commits, skips = new Set()) {
if (skips.size === 0) {
return commits;
}
return commits.filter(
(commit) => ![commit.hash, commit.shortHash].some((hash) => [...skips].some((skip) => hash.startsWith(skip))),
);
}
export function formatChangelog({ version, date, from, to = `v${version}`, repoUrl, commits }) {
const lines = [];
const versionRef = `v${version}`;
const heading = repoUrl
? `## [${version}](${repoUrl}/compare/${from}...${versionRef}) (${date})`
: `## ${version} (${date})`;
lines.push(heading);
lines.push("");
const breaking = commits.filter((commit) => commit.breaking);
if (breaking.length > 0) {
lines.push("### Breaking Changes");
lines.push("");
for (const commit of breaking) {
lines.push(formatBullet(commit, repoUrl));
}
lines.push("");
}
for (const type of typeOrder) {
const typed = commits.filter((commit) => commit.type === type && !commit.breaking);
if (typed.length === 0) {
continue;
}
lines.push(`### ${typeTitles.get(type) ?? type}`);
lines.push("");
for (const commit of typed) {
lines.push(formatBullet(commit, repoUrl));
}
lines.push("");
}
const unknownTypes = [...new Set(commits.map((commit) => commit.type))]
.filter((type) => !typeOrder.includes(type))
.sort();
for (const type of unknownTypes) {
const typed = commits.filter((commit) => commit.type === type && !commit.breaking);
if (typed.length === 0) {
continue;
}
lines.push(`### ${typeTitles.get(type) ?? titleCase(type)}`);
lines.push("");
for (const commit of typed) {
lines.push(formatBullet(commit, repoUrl));
}
lines.push("");
}
if (lines.at(-1) === "") {
lines.pop();
}
return `${lines.join("\n")}\n`;
}
export function prependChangelog(existing, entry, { version = null } = {}) {
const normalizedEntry = entry.trimEnd();
const deduped = version ? removeVersionEntry(existing, version) : existing;
const lines = deduped.split(/\r?\n/);
const firstBodyLine = lines.findIndex((line, index) => index > 0 && line.trim() !== "");
if (lines[0]?.startsWith("# ") && firstBodyLine !== -1) {
const header = lines.slice(0, firstBodyLine).join("\n").trimEnd();
const rest = lines.slice(firstBodyLine).join("\n").trimStart();
return `${header}\n\n${normalizedEntry}\n\n${rest}`;
}
if (lines[0]?.startsWith("# ")) {
return `${deduped.trimEnd()}\n\n${normalizedEntry}\n`;
}
return `${normalizedEntry}\n\n${deduped.trimStart()}`;
}
function removeVersionEntry(changelog, version) {
const escaped = escapeRegex(version);
const heading = String.raw`## (?:\[` + escaped + String.raw`\]|` + escaped + String.raw`)(?:\([^)]*\))? \([^)]*\)`;
return changelog.replace(new RegExp(String.raw`\n?${heading}[\s\S]*?(?=\n## |\s*$)`), "\n");
}
function escapeRegex(value) {
return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
}
export function normalizeRepoUrl(remote) {
const trimmed = remote.trim().replace(/\.git$/, "");
const sshMatch = /^git@([^:]+):(.+)$/.exec(trimmed);
if (sshMatch) {
return `https://${sshMatch[1]}/${sshMatch[2]}`;
}
return trimmed;
}
function formatBullet(commit, repoUrl) {
const scope = commit.scope ? `**${commit.scope}:** ` : "";
const description = `${scope}${commit.description}`;
if (!repoUrl) {
return `* ${description} (${commit.shortHash})`;
}
return `* ${description} ([${commit.shortHash}](${repoUrl}/commit/${commit.hash}))`;
}
function titleCase(value) {
return value
.split("-")
.map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`)
.join(" ");
}
function readValue(argv, index, flag) {
const value = argv[index];
if (!value || value.startsWith("-")) {
throw new Error(`${flag} requires a value`);
}
return value;
}
function git(args) {
return execFileSync("git", args, { encoding: "utf8" });
}
function latestTag() {
return git(["describe", "--tags", "--abbrev=0"]).trim();
}
function currentRepoUrl() {
return normalizeRepoUrl(git(["config", "--get", "remote.origin.url"]));
}
function gitLog({ from, to }) {
const range = `${from}..${to}`;
return git(["log", "--no-merges", "--format=%H%x00%h%x00%s%x00%b%x1e", range]);
}
export function usage() {
return `Usage:
node scripts/release/generate-changelog.mjs --version <version> [--from <tag>] [--to <ref>] [--date YYYY-MM-DD]
Options:
--from <tag> Previous release tag. Defaults to latest reachable tag.
--to <ref> Release head. Defaults to HEAD.
--repo <url> Repository URL for compare and commit links. Defaults to origin.
--include-internal Include docs, tests, refactors, chores, CI, and build commits.
--skip <hash> Omit a superseded commit. Can be repeated.
--output <path> Write generated Markdown to a file instead of stdout.
--prepend <path> Insert generated Markdown after the changelog title.
`;
}
function isMain() {
return process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
}
if (isMain()) {
try {
const options = parseArgs(process.argv.slice(2));
if (options.help) {
process.stdout.write(usage());
} else {
const from = options.from ?? latestTag();
const repoUrl = options.repoUrl ?? currentRepoUrl();
const commits = skipCommits(filterCommits(parseGitLog(gitLog({ from, to: options.to })), options), options.skips);
const markdown = formatChangelog({
version: options.version,
date: options.date,
from,
to: options.to,
repoUrl,
commits,
});
if (options.output) {
writeFileSync(options.output, markdown);
} else if (options.prepend) {
const path = resolve(options.prepend);
writeFileSync(path, prependChangelog(readFileSync(path, "utf8"), markdown, { version: options.version }));
} else {
process.stdout.write(markdown);
}
}
} catch (error) {
console.error(error.message);
console.error("");
console.error(usage());
process.exitCode = 1;
}
}