changelog-machine 1.1.0 → 2.0.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,166 @@
-<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 |
+| `--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.
+
+## Changelog format
+
+```md
+# Changelog
+
+## v2.0.0
+
+[compare changes](https://github.com/example/project/compare/v1.0.0...v2.0.0)
+
+### Enhancements
+
+- **icons:** Add new icons ([#42](https://github.com/example/project/pull/42))
+
+### Contributors
+
+- Philipp Kief
 ```
 
-### Command overview
+- 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.
 
-| COMMAND     | ALIAS | DESCRIPTION                    |
-| ----------- | ----- | ------------------------------ |
-| `--config`  | `-c`  | Path to the configuration file |
-| `--version` | `-v`  | Print version                  |
-| `--help`    | `-h`  | Print command instructions     |
+Use `--full` to apply formatting changes to older sections.
 
-### Configuration file
+## Incremental updates
 
-The configuration file can be configured like this:
+The newest documented tag is the update boundary. Only newer commit ranges are
+loaded; older sections stay untouched. Unchanged files are not rewritten.
 
-```json
-{
-  "title": "Changelog",
-  "description": "Some description text",
-  "repositoryUrl": "https://github.com/PKief/vscode-material-icon-theme",
-  "blacklistPattern": "Release|^\\d+\\.\\d+\\.\\d+$",
-  "filePath": "CHANGELOG.md"
-}
+- 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.
+
+Shallow clone? Run `git fetch --unshallow --tags` first.
+
+## Contributor profiles
+
+```sh
+changelog-machine --resolve-contributors
 ```
 
-More detailed description of the config:
+Adds verified profile links next to Git author names. Network access is **opt-in**.
 
-| 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                 |                                                                                                    |
+| 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 | — |
 
-## Example output
+Unresolved users fall back to Git author names, never emails. Email-only names
+become `Unknown contributor`. No username guessing or email searches.
 
-The following commit summary is printed into the CHANGELOG.md file and can look like this:
+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.
 
-#### [v4.12.1](https://github.com/PKief/vscode-material-icon-theme/compare/v4.12.1...HEAD)
+## Version bumps
 
-> February 5, 2022
+The highest-impact commit since the latest release wins:
 
-- 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)
+| Commit | Bump |
+| --- | --- |
+| `!`, `BREAKING CHANGE:`, or `BREAKING-CHANGE:` | Major, even on `0.x` |
+| `feat:` | Minor |
+| `fix:` or `perf:` | Patch |
+| Other types | None |
 
-## Programmatic use
+- Updates `package.json`, an existing npm lockfile (versions 1–3), and the changelog with `## v<next-version>`. No Git tag is needed to prepare that section; the CLI does not create one.
+- Leaves dependency versions unchanged.
+- Requires the latest tag to match the package version; repeated bumps fail.
+- Without tags, analyzes all commits against the current package version.
+- Prerelease promotion, Yarn/pnpm lockfiles, and workspaces are unsupported.
+- `--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.
 
-The tool can be imported as module into existing JavaScript or TypeScript code. Therefor it is necessary to install it via npm or yarn:
+Files are staged first and replaced atomically per file—not as a multi-file transaction.
 
-NPM:
+## API
 
-```
-npm install --save-dev changelog-machine
+```ts
+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 });
 ```
 
-Yarn:
+Also exports `parseCommit`, `recommendedBump`, `planVersion`, and TypeScript types.
+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.
 
-```
-yarn add --dev changelog-machine
-```
+**ESM-only.** Replaces the old `printMarkdown` API and JSON configuration; requires a major release.
 
-The module can be imported like this:
+## Development and publishing
 
-```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',
-});
+```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;
+}

package/lib/cli/files.d.ts

@@ -0,0 +1,5 @@
+export type FilePlan = {
+    path: string;
+    content: string;
+};
+export declare function apply(files: FilePlan[]): Promise<void>;