changelog-machine 1.1.0 → 2.1.0

package/LICENSE.md

@@ -1,5 +1,5 @@
 The MIT License (MIT)
-Copyright (c) 2022 Philipp Kief
+Copyright (c) 2026 Philipp Kief
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/README.md

@@ -1,108 +1,182 @@
-<h1 align="center">
-  <br>
-    <img src="https://github.com/PKief/changelog-machine/raw/main/logo.png" alt="logo" width="200">
-  <br><br>
-  Changelog Machine
-  <br>
-  <br>
-</h1>
+# Changelog Machine
 
-<h4 align="center">Generate a changelog based on Git commit messages and tags.</h4>
+Conventional changelogs and version bumps, with **zero production dependencies**.
+Requires **Node 24+** and **Git**.
 
-## Getting started
+## Quick start
 
-The tool can be executed with this command:
+Run inside your repository:
 
-```
-npx changelog-machine
+```sh
+npx changelog-machine                 # Create or update CHANGELOG.md
+npx changelog-machine --dry-run       # Preview changes
+npx changelog-machine --full          # Rebuild from scratch
+npx changelog-machine --bump --dry-run # Preview the next version
+npx changelog-machine --bump           # Update package metadata and release changelog
 ```
 
-It will generate a file called CHANGELOG.md in the root directory of the project.
+- **Default:** add newer releases, refresh `Unreleased`, preserve older sections.
+- **Missing file:** generate the entire history.
+- **`--full`:** replace all content, including manual edits.
+- No automatic Git fetches, commits, tags, pushes, or publishing.
 
-## Configuration
+## Options
 
-The generation of the changelog can be configured via a config file.
+| Option | Purpose |
+| --- | --- |
+| `--full` | Rebuild the entire changelog |
+| `--bump` | Infer and apply a version bump |
+| `--bump-command <command>` | Override the metadata update command; requires `--bump` and `{version}` |
+| `--dry-run` | Preview without writing |
+| `--output <path>` | Set the changelog destination |
+| `--repo-url <url>` | Override repository links with an HTTPS URL |
+| `--resolve-contributors` | Look up verified contributor profiles |
+| `--include-non-conventional` | Include other commits under Other Changes |
+| `--help`, `-h` | Show usage |
+| `--version`, `-v` | Show the tool version |
 
-```
-npx changelog-machine --config changelog.config.json
-```
+Long operations show progress in interactive terminals. Redirected output stays clean.
 
-### Command overview
+## Changelog format
 
-| COMMAND     | ALIAS | DESCRIPTION                    |
-| ----------- | ----- | ------------------------------ |
-| `--config`  | `-c`  | Path to the configuration file |
-| `--version` | `-v`  | Print version                  |
-| `--help`    | `-h`  | Print command instructions     |
+```md
+# Changelog
 
-### Configuration file
+## v2.0.0
 
-The configuration file can be configured like this:
+[compare changes](https://github.com/example/project/compare/v1.0.0...v2.0.0)
 
-```json
-{
-  "title": "Changelog",
-  "description": "Some description text",
-  "repositoryUrl": "https://github.com/PKief/vscode-material-icon-theme",
-  "blacklistPattern": "Release|^\\d+\\.\\d+\\.\\d+$",
-  "filePath": "CHANGELOG.md"
-}
-```
+### Enhancements
 
-More detailed description of the config:
+- **icons:** Add new icons ([#42](https://github.com/example/project/pull/42))
 
-| CONFIG             | DESCRIPTION                                     | DEFAULT                                                                                            |
-| ------------------ | ----------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `title`            | Title of the changelog                          | "Changelog"                                                                                        |
-| `description`      | Description under the title                     | "All notable changes to this project will be documented in this file. Dates are displayed in UTC." |
-| `filePath`         | Path of the output file                         | "CHANGELOG.md"                                                                                     |
-| `repositoryUrl`    | Links to the repository for further information |                                                                                                    |
-| `blacklistPattern` | Regex to remove commit messages                 |                                                                                                    |
+### Contributors
 
-## Example output
+- Philipp Kief
+```
 
-The following commit summary is printed into the CHANGELOG.md file and can look like this:
+- Releases: **newest first**. Commits within categories: **oldest first**.
+- Messages start uppercase; scopes and Markdown are preserved.
+- Separate sections for breaking changes, features, fixes, and other commit types.
+- Release bookkeeping commits are excluded; merge commits are skipped.
+- GitHub, GitLab, and Bitbucket links are supported.
+- Contributor names honor `.mailmap`; recognizable emails are redacted.
 
-#### [v4.12.1](https://github.com/PKief/vscode-material-icon-theme/compare/v4.12.1...HEAD)
+Use `--full` to apply formatting changes to older sections.
 
-> February 5, 2022
+## Incremental updates
 
-- Update release commit message [`3167316`](https://github.com/PKief/vscode-material-icon-theme/commit/3167316)
-- Update release workflow [`7f2520d`](https://github.com/PKief/vscode-material-icon-theme/commit/7f2520d)
-- Adjust preview script for folder icons [`6a00111`](https://github.com/PKief/vscode-material-icon-theme/commit/6a00111)
-- Fix compare link [`fa45abf`](https://github.com/PKief/vscode-material-icon-theme/commit/fa45abf)
-- Filter out release commits [`e3468ca`](https://github.com/PKief/vscode-material-icon-theme/commit/e3468ca)
+The newest documented tag is the update boundary. Only newer commit ranges are
+loaded; older sections stay untouched. Unchanged files are not rewritten.
 
-## Programmatic use
+- Supports `1.2.3` / `v1.2.3` tags, including prereleases and build metadata.
+- Uses Git ancestry, not tag dates; avoids quadratic tag comparisons.
+- Requires `# Changelog` and `## <tag>` / `## Unreleased` headings.
+- Invalid formatting, ambiguous tags, or missing boundaries fail safely.
+- Does not backfill gaps between older documented releases.
+- Historical emails remain untouched; `--full` redacts generated history.
 
-The tool can be imported as module into existing JavaScript or TypeScript code. Therefor it is necessary to install it via npm or yarn:
+Shallow clone? Run `git fetch --unshallow --tags` first.
 
-NPM:
+## Contributor profiles
 
-```
-npm install --save-dev changelog-machine
+```sh
+changelog-machine --resolve-contributors
 ```
 
-Yarn:
+Adds verified profile links next to Git author names. Network access is **opt-in**.
 
+| Provider | Resolution | Optional token |
+| --- | --- | --- |
+| GitHub | Associated commit author | `GH_TOKEN` or `GITHUB_TOKEN` |
+| Bitbucket | Associated user | `BITBUCKET_TOKEN` (bearer token) |
+| GitLab | Git author name only | — |
+
+Unresolved users fall back to Git author names, never emails. Email-only names
+become `Unknown contributor`. No username guessing or email searches.
+
+Lookups are grouped by mailmapped author identity and cached within a run. One
+successful request covers all that author's commits; unresolved authors get at
+most two attempts. Requests use five-second timeouts and three concurrent workers.
+Rate limits stop queued requests with one warning; enriched results may vary.
+
+## Version bumps
+
+The highest-impact commit since the latest release wins:
+
+| Commit | Bump |
+| --- | --- |
+| `!`, `BREAKING CHANGE:`, or `BREAKING-CHANGE:` | Major, even on `0.x` |
+| `feat:` | Minor |
+| `fix:` or `perf:` | Patch |
+| Other types | None |
+
+- Calculates the exact next version, then runs `npm version <next-version> --no-git-tag-version --ignore-scripts` by default. npm owns `package.json` and its lockfiles; changelog-machine does not parse or restrict lockfile formats. npm must be available on `PATH` unless a custom command is supplied.
+- Writes the release changelog with `## v<next-version>` only after the command succeeds and `package.json` contains the planned version. No Git tag is needed to prepare that section.
+- The default command disables lifecycle scripts and Git commit/tag creation.
+- Requires the latest tag to match the package version; repeated bumps fail.
+- Without tags, analyzes all commits against the current package version.
+- Prerelease promotion and workspace version orchestration are unsupported. Non-npm metadata and lockfiles can be maintained by a custom command.
+- `--bump --full` rebuilds historical sections too. Without `--full`, older sections remain unchanged. `--output` also works with bumps; `--dry-run` previews without writing. No release-worthy commits means no file changes.
+- After a successful bump, commit and create the matching version tag before another incremental update or bump.
+
+### Custom package managers
+
+```sh
+changelog-machine --bump \
+  --bump-command='bun pm version {version} --no-git-tag-version --ignore-scripts'
 ```
-yarn add --dev changelog-machine
-```
 
-The module can be imported like this:
+Use `{version}` for the exact calculated version, not a relative bump such as `patch`. Every occurrence is replaced. Commands run in the repository directory through the system shell, with output sent to stderr. Shell syntax and executable availability depend on your platform.
+
+`--bump-command` is **trusted, arbitrary shell input**. You are responsible for making it update `package.json` and the relevant lockfiles without commits, tags, pushes, publishing, or lifecycle side effects. npm does not maintain Bun, pnpm, or Yarn lockfiles; use a command or wrapper script appropriate to your package manager. The tool verifies the resulting package version, but cannot verify arbitrary lockfile contents or prevent custom-command side effects.
+
+`--dry-run` prints the planned command to stderr and changelog to stdout without executing the command. No release-worthy commits means no command execution.
+
+Changelog destinations are validated and temporary files staged before executing the command. Command failures or version mismatches leave the existing changelog untouched. Metadata changes made by a command are **not rolled back**; inspect repository changes before retrying. A failure while replacing the staged changelog can also leave metadata updated without the changelog; updates are not a multi-file transaction.
+
+
+## API
 
 ```ts
-import { printMarkdown } from 'changelog-machine';
-
-// usage with default config
-printMarkdown();
-
-// usage with customizations
-printMarkdown({
-  filePath: './changelog/CHANGES.md',
-  description: 'List of changes',
-  title: 'All releases',
-  blacklistPattern: '^Release', // excludes all commits that start with "Release"
-  repositoryUrl: 'https://github.com/PKief/vscode-material-icon-theme',
-});
+import {
+  getReleases,
+  getRepositoryUrl,
+  renderMarkdown,
+  resolveContributors,
+} from 'changelog-machine';
+
+const releases = await getReleases();
+const repositoryUrl = await getRepositoryUrl();
+const markdown = renderMarkdown(releases, { repositoryUrl });
+
+// Optional network enrichment
+const contributors = await resolveContributors(
+  releases.flatMap(release => release.commits),
+  repositoryUrl,
+);
+const enriched = renderMarkdown(releases, { repositoryUrl, contributors });
 ```
+
+Also exports `parseCommit`, `recommendedBump`, `planVersion`, and TypeScript types. `planVersion` is read-only: it calculates `current`, `next`, and `bump`; its `files` array is now empty because metadata updates are delegated to a command.
+Pass a boundary tag to `getReleases(cwd, tag)` for incremental history.
+The API does not write files. Explicit GitLab profiles can be supplied to the renderer.
+
+**ESM-only.** Replaces the old `printMarkdown` API and JSON configuration; requires a major release.
+
+## Development and publishing
+
+```sh
+npm ci
+npm run build
+npm test
+npm run lint
+npm pack --dry-run
+```
+
+- Tests live beside source as `name.test.ts` and run directly with Node's native TypeScript support; no compiled test directory is needed.
+- `npm test` type-checks first, then runs Node's test runner. Node strips types but does not type-check.
+- Root TypeScript config covers source and tests; build config excludes tests. Source imports use `.js`, matching published output. A test-only Node loader resolves those imports to `.ts` while executing source directly.
+- TypeScript 7 is development-only; npm ships compiled JavaScript and types.
+- `package.json`'s `files` allowlist replaces `.npmignore`; `prepack` builds automatically.
+- Use **Actions → Release → Run workflow** on the default branch, or `gh workflow run release.yml --ref main`. No version input is needed: conventional commits determine the bump. The workflow updates package metadata and changelog, commits and pushes a version tag, publishes to npm, and creates a GitHub Release. With no release-worthy commits, it makes no changes. Requires npm trusted publishing configured for this repository and `release.yml`, plus permission for the workflow token to push to the default branch; branch-protection rules may block that push. Tag pushes no longer trigger publishing separately. If npm publication fails after the release commit/tag was pushed, recover manually rather than expecting another click to repeat the release.

package/bin/cli.js

@@ -1,2 +1,6 @@
 #!/usr/bin/env node
-require('../lib/cli/index.js');
+import { run } from '../lib/cli/index.js';
+run().catch(error => {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+});

package/lib/changelog/contributors.d.ts

@@ -0,0 +1,2 @@
+import type { Options, ParsedCommit } from '../types.js';
+export declare function contributorLines(commits: ParsedCommit[], options: Options): string[];

package/lib/changelog/contributors.js

@@ -0,0 +1,31 @@
+import { authorName } from '../contributors/privacy.js';
+import { validateProfile } from '../contributors/profile.js';
+import { plainText } from './text.js';
+function profileForCommit(commit, options) {
+    const profile = options.contributors?.[commit.hash];
+    if (!profile || !options.repositoryUrl)
+        return undefined;
+    try {
+        const host = new URL(options.repositoryUrl).hostname;
+        if (!['github.com', 'bitbucket.org', 'gitlab.com'].includes(host))
+            return undefined;
+        return validateProfile(profile.username, profile.url, host);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function contributorLines(commits, options) {
+    const contributors = new Map();
+    for (const commit of commits) {
+        const name = authorName(commit.name);
+        const profile = profileForCommit(commit, options);
+        const key = profile?.url ?? name;
+        const label = profile
+            ? `${plainText(name)} ([@${plainText(profile.username)}](${profile.url}))`
+            : plainText(name);
+        if (!contributors.has(key))
+            contributors.set(key, `- ${label}`);
+    }
+    return [...contributors.values()].sort();
+}

package/lib/changelog/links.d.ts

@@ -0,0 +1,31 @@
+import type { ParsedCommit } from '../types.js';
+declare const repositoryRoutes: {
+    'github.com': {
+        compare: string;
+        commit: string;
+        issue: string;
+        pullRequest: string;
+    };
+    'gitlab.com': {
+        compare: string;
+        commit: string;
+        issue: string;
+        pullRequest: string;
+    };
+    'bitbucket.org': {
+        compare: string;
+        commit: string;
+        issue: string;
+        pullRequest: string;
+    };
+};
+type RepositoryHost = keyof typeof repositoryRoutes;
+export type Repository = {
+    base: string;
+    host: RepositoryHost;
+};
+export declare function repositoryBase(value?: string): Repository | undefined;
+export declare function compareUrl(repository: Repository, baseTag: string, targetTag: string): string;
+export declare function linkIssueReferences(message: string, repository?: Repository): string;
+export declare function commitReference(commit: ParsedCommit, repository?: Repository): string;
+export {};

package/lib/changelog/links.js

@@ -0,0 +1,83 @@
+import { encodeCharacter, encodeSegment, plainText } from './text.js';
+const trailingSlashesPattern = /\/+$/;
+const gitSuffixPattern = /\.git$/;
+const urlUnsafeCharactersPattern = /[\s()<>\[\]]/g;
+const repositoryRoutes = {
+    'github.com': {
+        compare: '/compare/',
+        commit: '/commit/',
+        issue: '/issues/',
+        pullRequest: '/pull/',
+    },
+    'gitlab.com': {
+        compare: '/-/compare/',
+        commit: '/-/commit/',
+        issue: '/-/issues/',
+        pullRequest: '/-/merge_requests/',
+    },
+    'bitbucket.org': {
+        compare: '/branches/compare/',
+        commit: '/commits/',
+        issue: '/issues/',
+        pullRequest: '/pull-requests/',
+    },
+};
+export function repositoryBase(value) {
+    if (!value)
+        return undefined;
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'https:' && url.protocol !== 'http:')
+            return undefined;
+        if (url.username || url.password)
+            return undefined;
+        const host = url.hostname;
+        if (host !== 'github.com' &&
+            host !== 'gitlab.com' &&
+            host !== 'bitbucket.org')
+            return undefined;
+        url.search = '';
+        url.hash = '';
+        const base = url
+            .toString()
+            .replace(trailingSlashesPattern, '')
+            .replace(gitSuffixPattern, '')
+            .replace(urlUnsafeCharactersPattern, encodeCharacter);
+        return { base, host };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function compareUrl(repository, baseTag, targetTag) {
+    const base = encodeSegment(baseTag);
+    const target = encodeSegment(targetTag);
+    const comparison = repository.host === 'bitbucket.org'
+        ? `${target}..${base}`
+        : `${base}...${target}`;
+    return `${repository.base}${repositoryRoutes[repository.host].compare}${comparison}`;
+}
+const inlineCodePattern = /(`+)[\s\S]*?\1/;
+const markdownLinkPattern = /!?\[[^\]\n]*\]\([^\n]*?\)/;
+const plainUrlPattern = /https?:\/\/[^\s)]+/;
+const issueNumberPattern = /(?<![\w/#\\])#([1-9]\d*)\b/;
+const protectedMarkdownOrIssue = new RegExp([inlineCodePattern, markdownLinkPattern, plainUrlPattern, issueNumberPattern]
+    .map((pattern) => pattern.source)
+    .join('|'), 'g');
+export function linkIssueReferences(message, repository) {
+    if (!repository)
+        return message;
+    const issueUrl = `${repository.base}${repositoryRoutes[repository.host].issue}`;
+    return message.replace(protectedMarkdownOrIssue, (match, _code, issue) => issue ? `[#${issue}](${issueUrl}${issue})` : match);
+}
+export function commitReference(commit, repository) {
+    const label = commit.pr
+        ? `#${commit.pr}`
+        : plainText(commit.hash.slice(0, 8));
+    if (!repository)
+        return `(${label})`;
+    const routes = repositoryRoutes[repository.host];
+    const path = commit.pr ? routes.pullRequest : routes.commit;
+    const identifier = encodeSegment(commit.pr ?? commit.hash);
+    return `([${label}](${repository.base}${path}${identifier}))`;
+}

package/lib/changelog/render.d.ts

@@ -0,0 +1,2 @@
+import type { Options, Release } from '../types.js';
+export declare function renderMarkdown(releases: Release[], options?: Options): string;

package/lib/changelog/render.js

@@ -0,0 +1,69 @@
+import { parseCommit } from '../commits/parse.js';
+import { redactEmails } from '../contributors/privacy.js';
+import { contributorLines } from './contributors.js';
+import { commitReference, compareUrl, linkIssueReferences, repositoryBase, } from './links.js';
+import { capitalizeMessage, plainText, safeText } from './text.js';
+const groups = [
+    ['breaking', 'Breaking Changes'],
+    ['feat', 'Enhancements'],
+    ['fix', 'Fixes'],
+    ['perf', 'Performance'],
+    ['docs', 'Documentation'],
+    ['refactor', 'Refactors'],
+    ['test', 'Tests'],
+    ['build', 'Build'],
+    ['ci', 'CI'],
+    ['chore', 'Chores'],
+    ['revert', 'Reverts'],
+    ['other', 'Other Changes'],
+];
+const noteLineBreakPattern = /\r?\n/;
+function entry(commit, repository) {
+    const scope = commit.scope ? `**${plainText(commit.scope)}:** ` : '';
+    const reference = commitReference(commit, repository);
+    const lines = [
+        `- ${scope}${linkIssueReferences(safeText(capitalizeMessage(commit.description)), repository)} ${reference}`,
+    ];
+    for (const note of commit.breakingNotes) {
+        const parts = linkIssueReferences(safeText(capitalizeMessage(note)), repository).split(noteLineBreakPattern);
+        lines.push(`  - ${parts[0]}`, ...parts.slice(1).map((line) => `    ${line}`));
+    }
+    return lines;
+}
+export function renderMarkdown(releases, options = {}) {
+    const repository = repositoryBase(options.repositoryUrl);
+    const lines = ['# Changelog'];
+    for (const release of releases) {
+        lines.push('', `## ${plainText(release.tag)}`);
+        if (repository && release.previousTag) {
+            lines.push('', `[compare changes](${compareUrl(repository, release.previousTag, release.tag)})`);
+        }
+        const commits = release.commits
+            .map((commit) => parseCommit(commit, options.includeNonConventional))
+            .filter((commit) => commit !== undefined);
+        const grouped = new Map();
+        for (const commit of commits) {
+            const key = commit.breaking
+                ? 'breaking'
+                : groups.some(([type]) => type === commit.type)
+                    ? commit.type
+                    : 'other';
+            const list = grouped.get(key) ?? [];
+            list.push(commit);
+            grouped.set(key, list);
+        }
+        for (const [key, title] of groups) {
+            const entries = grouped.get(key);
+            if (!entries?.length)
+                continue;
+            lines.push('', `### ${title}`, '');
+            for (const commit of entries)
+                lines.push(...entry(commit, repository));
+        }
+        const contributors = contributorLines(commits, options);
+        if (contributors.length) {
+            lines.push('', '### Contributors', '', ...contributors);
+        }
+    }
+    return redactEmails(`${lines.join('\n')}\n`);
+}

package/lib/changelog/text.d.ts

@@ -0,0 +1,5 @@
+export declare function capitalizeMessage(value: string): string;
+export declare function safeText(value: string): string;
+export declare function plainText(value: string): string;
+export declare function encodeCharacter(character: string): string;
+export declare function encodeSegment(value: string): string;

package/lib/changelog/text.js

@@ -0,0 +1,23 @@
+const markdownPunctuationPattern = /[\\`*_{}\[\]()#!|]/g;
+const textLineBreakPattern = /[\r\n]+/g;
+const segmentUnsafeCharactersPattern = /[!'()*]/g;
+export function capitalizeMessage(value) {
+    return value.replace(/\p{L}/u, (letter) => letter.toUpperCase());
+}
+export function safeText(value) {
+    return value
+        .replaceAll('&', '&')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;');
+}
+export function plainText(value) {
+    return safeText(value)
+        .replace(markdownPunctuationPattern, '\\$&')
+        .replace(textLineBreakPattern, ' ');
+}
+export function encodeCharacter(character) {
+    return `%${character.charCodeAt(0).toString(16).toUpperCase()}`;
+}
+export function encodeSegment(value) {
+    return encodeURIComponent(value).replace(segmentUnsafeCharactersPattern, encodeCharacter);
+}

package/lib/changelog/update.d.ts

@@ -0,0 +1,7 @@
+export interface ExistingChangelog {
+    boundaryTag?: string;
+    prefix: string;
+    history: string;
+}
+export declare function parseChangelog(content: string): ExistingChangelog;
+export declare function mergeChangelog(existing: ExistingChangelog | undefined, generated: string): string;

package/lib/changelog/update.js

@@ -0,0 +1,119 @@
+import { isVersionTag } from '../git/tags.js';
+function headings(content) {
+    const result = [];
+    let offset = 0;
+    let fence;
+    for (const line of content.match(/[^\n]*(?:\n|$)/g) ?? []) {
+        if (!line)
+            continue;
+        const text = line.replace(/\r?\n$/, '');
+        const marker = text.match(/^ {0,3}(`{3,}|~{3,})/);
+        if (fence) {
+            if (marker &&
+                marker[1][0] === fence.character &&
+                marker[1].length >= fence.length) {
+                fence = undefined;
+            }
+        }
+        else if (marker) {
+            fence = { character: marker[1][0], length: marker[1].length };
+        }
+        else if (/^##(?:\s|$)/.test(text)) {
+            const heading = text.match(/^##\s+(.+?)\s*#*\s*$/);
+            result.push({ title: heading?.[1].trim() ?? '', start: offset });
+        }
+        offset += line.length;
+    }
+    return result;
+}
+function formatError(detail) {
+    return new Error(`Cannot update changelog: ${detail}. Use --full to regenerate it.`);
+}
+function removeSection(content, sectionHeadings, index) {
+    const start = sectionHeadings[index].start;
+    const end = sectionHeadings[index + 1]?.start ?? content.length;
+    return content.slice(0, start) + content.slice(end);
+}
+function validateTitle(content) {
+    if (!/^# Changelog(?:\r?\n|$)/.test(content)) {
+        throw formatError('expected a # Changelog title');
+    }
+}
+function validateSections(sectionHeadings) {
+    let foundRelease = false;
+    let foundUnreleased = false;
+    const tags = new Set();
+    for (const heading of sectionHeadings) {
+        if (heading.title === 'Unreleased') {
+            if (foundUnreleased)
+                throw formatError('duplicate Unreleased section');
+            if (foundRelease)
+                throw formatError('Unreleased section must precede tagged releases');
+            foundUnreleased = true;
+        }
+        else if (!isVersionTag(heading.title)) {
+            throw formatError(`unrecognized release heading "${heading.title}"`);
+        }
+        else {
+            if (tags.has(heading.title))
+                throw formatError(`duplicate release tag "${heading.title}"`);
+            tags.add(heading.title);
+            foundRelease = true;
+        }
+    }
+}
+function removeUnreleased(content, sectionHeadings) {
+    const index = sectionHeadings.findIndex((heading) => heading.title === 'Unreleased');
+    return index < 0 ? content : removeSection(content, sectionHeadings, index);
+}
+export function parseChangelog(content) {
+    validateTitle(content);
+    const sectionHeadings = headings(content);
+    validateSections(sectionHeadings);
+    const firstReleaseIndex = sectionHeadings.findIndex((heading) => isVersionTag(heading.title));
+    const firstRelease = sectionHeadings[firstReleaseIndex];
+    const prefixEnd = firstRelease?.start ?? content.length;
+    const prefix = removeUnreleased(content.slice(0, prefixEnd), sectionHeadings.filter((heading) => heading.start < prefixEnd));
+    if (!firstRelease)
+        return { prefix, history: '' };
+    return {
+        boundaryTag: firstRelease.title,
+        prefix,
+        history: content.slice(firstRelease.start),
+    };
+}
+function joinAtBoundary(left, right) {
+    if (!left)
+        return right;
+    if (!right)
+        return left;
+    return `${left.replace(/\n+$/, '')}\n\n${right.replace(/^\n+/, '')}`;
+}
+function generatedSections(content, sectionHeadings) {
+    const firstSection = sectionHeadings[0]?.start;
+    if (firstSection === undefined)
+        return '';
+    return content.slice(firstSection);
+}
+export function mergeChangelog(existing, generated) {
+    validateTitle(generated);
+    const generatedHeadings = headings(generated);
+    validateSections(generatedHeadings);
+    const parsed = parseChangelog(generated);
+    const generatedPrefix = generated.slice(0, generatedHeadings[0]?.start ?? generated.length);
+    const prefix = existing?.prefix ?? generatedPrefix;
+    let freshSections = generatedSections(generated, generatedHeadings);
+    if (existing?.boundaryTag) {
+        const duplicate = generatedHeadings.findIndex((heading) => heading.title === existing.boundaryTag);
+        if (duplicate >= 0) {
+            const firstSection = generatedHeadings[0]?.start;
+            freshSections =
+                firstSection === undefined ||
+                    generatedHeadings[duplicate].start <= firstSection
+                    ? ''
+                    : generated.slice(firstSection, generatedHeadings[duplicate].start);
+        }
+    }
+    const history = joinAtBoundary(freshSections, existing?.history ?? '');
+    return joinAtBoundary(prefix, history) || parsed.prefix;
+}