changelog-machine 1.1.0 → 2.1.0

package/lib/cli/files.d.ts

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

package/lib/cli/files.js

@@ -0,0 +1,37 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+async function fileMode(path) {
+    try {
+        const info = await stat(path);
+        if (!info.isFile())
+            throw new Error(`Not a regular file: ${path}`);
+        return info.mode;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        return undefined;
+    }
+}
+export async function apply(files, beforeReplace) {
+    const staged = [];
+    try {
+        for (const file of files) {
+            await mkdir(dirname(file.path), { recursive: true });
+            const mode = await fileMode(file.path);
+            const temporary = `${file.path}.${randomUUID()}.tmp`;
+            staged.push({ path: file.path, temporary });
+            await writeFile(temporary, file.content, { flag: 'wx', mode });
+        }
+        // Validate and stage changelog destinations before running a mutating command.
+        await beforeReplace?.();
+        for (const file of staged)
+            await rename(file.temporary, file.path);
+    }
+    finally {
+        await Promise.all(staged.map((file) => rm(file.temporary, { force: true })));
+    }
+    for (const file of files)
+        console.error(`Updated ${file.path}`);
+}

package/lib/cli/index.d.ts

@@ -1 +1 @@
-export {};
+export declare function run(args?: string[]): Promise<void>;

package/lib/cli/index.js

@@ -1,43 +1,72 @@
-"use strict";
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const minimist_1 = __importDefault(require("minimist"));
-const default_1 = require("../core/default");
-const printHelp_1 = require("./commands/printHelp");
-const printMarkdown_1 = require("./commands/printMarkdown");
-const printVersion_1 = require("./commands/printVersion");
-const options_1 = require("./config/options");
-const readConfigFile_1 = require("./config/readConfigFile");
-const async_1 = require("../core/async");
-const run = () => __awaiter(void 0, void 0, void 0, function* () {
-    if (!(0, async_1.checkPackageJsonExists)()) {
-        console.error('Error: package.json does not exist.');
-        process.exit(1);
+import { readFile } from 'node:fs/promises';
+import { parseChangelog } from '../changelog/update.js';
+import { getLatestReleaseTag, getReleases } from '../git/history.js';
+import { defaultBumpCommand, formatBumpCommand, runBumpCommand, } from '../version/command.js';
+import { apply } from './files.js';
+import { parseFlags, showInformation } from './options.js';
+import { changelogPath, planBump, planChangelog } from './plans.js';
+import { withProgress } from './progress.js';
+async function readChangelog(path) {
+    try {
+        return await readFile(path, 'utf8');
     }
-    const args = (0, minimist_1.default)(process.argv.slice(2), options_1.flags);
-    if (args.version) {
-        (0, printVersion_1.printVersion)();
-        return;
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
     }
-    if (args.help) {
-        (0, printHelp_1.printHelp)();
+}
+async function readExistingChangelog(flags, cwd) {
+    const existing = flags.full
+        ? undefined
+        : await readChangelog(changelogPath(flags, cwd));
+    // Only regenerate history newer than the latest documented release.
+    const boundary = existing === undefined ? undefined : parseChangelog(existing).boundaryTag;
+    return { existing, boundary };
+}
+async function prepareBump(flags, cwd) {
+    if (!flags.bump)
+        return undefined;
+    const tag = await getLatestReleaseTag(cwd);
+    return planBump(await getReleases(cwd, tag), cwd, tag);
+}
+function promoteUnreleased(releases, next, boundary) {
+    if (!next)
+        return releases;
+    // Incremental history may expose the previous tag only through Unreleased.
+    const latestTag = releases.find((release) => release.tag !== 'Unreleased')?.tag ??
+        releases.find((release) => release.tag === 'Unreleased')?.previousTag ??
+        boundary;
+    return releases.map((release) => release.tag === 'Unreleased'
+        ? { ...release, tag: `v${next}`, previousTag: latestTag }
+        : release);
+}
+async function prepareFiles(flags, cwd, existing, boundary, bump) {
+    const releases = await withProgress('Reading Git releases', () => getReleases(cwd, boundary));
+    return [
+        ...(bump?.files ?? []),
+        ...(await planChangelog(promoteUnreleased(releases, bump?.next, boundary), flags, cwd, existing)),
+    ];
+}
+async function applyOrPreview(files, flags, cwd, next) {
+    if (flags['dry-run']) {
+        if (next) {
+            console.error(`Would run: ${formatBumpCommand(flags['bump-command'] ?? defaultBumpCommand, next)}`);
+        }
         return;
     }
-    let config = default_1.defaultConfig;
-    if (args.config) {
-        config = Object.assign(Object.assign({}, default_1.defaultConfig), (yield (0, readConfigFile_1.readConfigFile)(args.config)));
-    }
-    yield (0, printMarkdown_1.printMarkdown)(config);
-});
-run();
+    // Stage the changelog first; update metadata before replacing it.
+    await apply(files, next ? () => runBumpCommand(next, cwd, flags['bump-command']) : undefined);
+}
+export async function run(args = process.argv.slice(2)) {
+    const flags = parseFlags(args);
+    if (await showInformation(flags))
+        return;
+    const cwd = process.cwd();
+    const { existing, boundary } = await readExistingChangelog(flags, cwd);
+    const bump = await prepareBump(flags, cwd);
+    if (flags.bump && !bump?.next)
+        return;
+    const files = await prepareFiles(flags, cwd, existing, boundary, bump);
+    await applyOrPreview(files, flags, cwd, bump?.next);
+}

package/lib/cli/options.d.ts

@@ -0,0 +1,14 @@
+export type Flags = ReturnType<typeof parseFlags>;
+export declare function parseFlags(args: string[]): {
+    full?: boolean | undefined;
+    bump?: boolean | undefined;
+    'bump-command'?: string | undefined;
+    'dry-run'?: boolean | undefined;
+    output?: string | undefined;
+    'repo-url'?: string | undefined;
+    'resolve-contributors'?: boolean | undefined;
+    'include-non-conventional'?: boolean | undefined;
+    help?: boolean | undefined;
+    version?: boolean | undefined;
+};
+export declare function showInformation(flags: Flags): Promise<boolean>;

package/lib/cli/options.js

@@ -0,0 +1,57 @@
+import { readFile } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+import { validateBumpCommand } from '../version/command.js';
+const help = `Usage: changelog-machine [options]
+
+Updates missing releases and refreshes Unreleased in CHANGELOG.md by default.
+Creates a complete changelog when the file does not exist.
+
+  --full                      Replace the entire CHANGELOG.md from Git history
+  --bump                      Infer version; update package metadata and changelog
+  --bump-command <command>    Trusted shell command containing {version} (requires --bump)
+  --dry-run                   Preview without writing any files
+  --output <path>              Changelog destination (default: CHANGELOG.md)
+  --repo-url <url>             Repository URL for links
+  --resolve-contributors      Look up verified hosting profiles (uses network)
+  --include-non-conventional  Include other commits under Other Changes
+  --help                      Show help
+  --version                   Show this tool's version
+
+Requires Node 24+ and Git. Never fetches, commits, tags, pushes or publishes.
+`;
+export function parseFlags(args) {
+    const flags = parseArgs({
+        args,
+        options: {
+            full: { type: 'boolean' },
+            bump: { type: 'boolean' },
+            'bump-command': { type: 'string' },
+            'dry-run': { type: 'boolean' },
+            output: { type: 'string' },
+            'repo-url': { type: 'string' },
+            'resolve-contributors': { type: 'boolean' },
+            'include-non-conventional': { type: 'boolean' },
+            help: { type: 'boolean', short: 'h' },
+            version: { type: 'boolean', short: 'v' },
+        },
+        allowPositionals: false,
+    }).values;
+    if (flags['bump-command'] !== undefined) {
+        if (!flags.bump)
+            throw new Error('--bump-command requires --bump');
+        validateBumpCommand(flags['bump-command']);
+    }
+    return flags;
+}
+export async function showInformation(flags) {
+    if (flags.help) {
+        process.stdout.write(help);
+        return true;
+    }
+    if (flags.version) {
+        const pkg = JSON.parse(await readFile(new URL('../../package.json', import.meta.url), 'utf8'));
+        console.log(pkg.version);
+        return true;
+    }
+    return false;
+}

package/lib/cli/plans.d.ts

@@ -0,0 +1,7 @@
+import type { Release } from '../types.js';
+import type { VersionPlan } from '../version/plan.js';
+import type { FilePlan } from './files.js';
+import type { Flags } from './options.js';
+export declare function planBump(releases: Release[], cwd: string, latestTag?: string): Promise<VersionPlan>;
+export declare function changelogPath(flags: Flags, cwd: string): string;
+export declare function planChangelog(releases: Release[], flags: Flags, cwd: string, existing?: string): Promise<FilePlan[]>;

package/lib/cli/plans.js

@@ -0,0 +1,67 @@
+import { resolve } from 'node:path';
+import { renderMarkdown } from '../changelog/render.js';
+import { mergeChangelog, parseChangelog } from '../changelog/update.js';
+import { parseCommit } from '../commits/parse.js';
+import { resolveContributors } from '../contributors/resolve.js';
+import { getRepositoryUrl } from '../git/remote.js';
+import { planVersion } from '../version/plan.js';
+import { withProgress } from './progress.js';
+export async function planBump(releases, cwd, latestTag) {
+    const unreleased = releases.find((release) => release.tag === 'Unreleased');
+    const plan = await planVersion(unreleased?.commits ?? [], latestTag, cwd);
+    console.error(plan.next
+        ? `${plan.current} → ${plan.next} (${plan.bump})`
+        : `No version bump (${plan.current})`);
+    return plan;
+}
+async function repositoryUrl(flags, cwd) {
+    const repository = flags['repo-url'] ?? (await getRepositoryUrl(cwd));
+    if (repository) {
+        const url = new URL(repository);
+        if (url.protocol !== 'https:' ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash) {
+            throw new Error('--repo-url must be an HTTPS repository URL without credentials, query or fragment');
+        }
+    }
+    return repository;
+}
+function changelogReleases(releases, flags) {
+    return releases.filter((release) => {
+        if (release.tag !== 'Unreleased')
+            return true;
+        return release.commits.some((commit) => parseCommit(commit, flags['include-non-conventional']));
+    });
+}
+export function changelogPath(flags, cwd) {
+    const path = resolve(cwd, flags.output ?? 'CHANGELOG.md');
+    if (['package.json', 'package-lock.json', 'npm-shrinkwrap.json'].some((name) => path === resolve(cwd, name))) {
+        throw new Error('Changelog output must not overwrite package metadata');
+    }
+    return path;
+}
+export async function planChangelog(releases, flags, cwd, existing) {
+    const selectedReleases = changelogReleases(releases, flags);
+    const url = await repositoryUrl(flags, cwd);
+    const commits = selectedReleases
+        .flatMap((release) => release.commits)
+        .filter((commit) => parseCommit(commit, flags['include-non-conventional']));
+    const contributors = flags['resolve-contributors']
+        ? await withProgress('Resolving contributor profiles', (update) => resolveContributors(commits, url, (progress) => update(`Contributors: ${progress.completed}/${progress.total} checked, ${progress.resolved} resolved, ${progress.requests} requests`)))
+        : undefined;
+    const markdown = renderMarkdown(selectedReleases, {
+        repositoryUrl: url,
+        contributors,
+        includeNonConventional: flags['include-non-conventional'],
+    });
+    const updated = mergeChangelog(existing === undefined ? undefined : parseChangelog(existing), markdown);
+    if (flags['dry-run']) {
+        process.stdout.write(updated);
+        return [];
+    }
+    return updated === existing
+        ? []
+        : [{ path: changelogPath(flags, cwd), content: updated }];
+}

package/lib/cli/progress.d.ts

@@ -0,0 +1,2 @@
+import type { WriteStream } from 'node:tty';
+export declare function withProgress<T>(label: string, task: (update: (label: string) => void) => Promise<T>, output?: WriteStream): Promise<T>;

package/lib/cli/progress.js

@@ -0,0 +1,37 @@
+import { clearLine, cursorTo } from 'node:readline';
+const frames = ['|', '/', '-', '\\'];
+const refreshIntervalMs = 100;
+const displayDelayMs = 200;
+export async function withProgress(label, task, output = process.stderr) {
+    if (!output.isTTY)
+        return task(() => { });
+    const update = (message) => {
+        label = message;
+    };
+    let frame = 0;
+    let visible = false;
+    let animation;
+    const render = () => {
+        cursorTo(output, 0);
+        clearLine(output, 0);
+        output.write(`${frames[frame++ % frames.length]} ${label}`);
+        visible = true;
+    };
+    const delay = setTimeout(() => {
+        render();
+        animation = setInterval(render, refreshIntervalMs);
+        animation.unref();
+    }, displayDelayMs);
+    delay.unref();
+    try {
+        return await task(update);
+    }
+    finally {
+        clearTimeout(delay);
+        clearInterval(animation);
+        if (visible) {
+            cursorTo(output, 0);
+            clearLine(output, 0);
+        }
+    }
+}

package/lib/commits/parse.d.ts

@@ -0,0 +1,3 @@
+import type { Commit, ParsedCommit } from '../types.js';
+export declare function parseCommit(commit: Commit, includeNonConventional?: boolean): ParsedCommit | undefined;
+export declare function recommendedBump(commits: Commit[]): 'major' | 'minor' | 'patch' | undefined;

package/lib/commits/parse.js

@@ -0,0 +1,87 @@
+import { isVersionTag } from '../git/tags.js';
+const conventionalHeaderPattern = /^([A-Za-z][A-Za-z0-9-]*)(?:\(([^()\r\n]+)\))?(!)?:\s+(.+)$/;
+const breakingNotePattern = /^BREAKING[ -]CHANGE:\s*(.*)$/;
+const breakingFooterPattern = /^BREAKING[ -]CHANGE:/m;
+const footerTokenPattern = /^[A-Za-z][A-Za-z0-9-]*/;
+const footerSeparatorPattern = /^(?::\s|\s+#)/;
+const pullRequestSuffixPattern = /\s+\(#(\d+)\)$/;
+const lineBreakPattern = /\r?\n/;
+function isFooter(line) {
+    const token = footerTokenPattern.exec(line);
+    return Boolean(token && footerSeparatorPattern.test(line.slice(token[0].length)));
+}
+function breakingNotes(body) {
+    const notes = [];
+    let noteLines;
+    const finishNote = () => {
+        if (noteLines) {
+            const note = noteLines.join('\n').trim();
+            if (note)
+                notes.push(note);
+        }
+        noteLines = undefined;
+    };
+    for (const line of body.split(lineBreakPattern)) {
+        const breakingMatch = breakingNotePattern.exec(line);
+        if (breakingMatch) {
+            finishNote();
+            noteLines = [breakingMatch[1]];
+        }
+        else if (isFooter(line)) {
+            finishNote();
+        }
+        else if (noteLines) {
+            noteLines.push(line);
+        }
+    }
+    finishNote();
+    return notes;
+}
+function isReleaseCommit(type, scope, description) {
+    const version = description.startsWith('release ')
+        ? description.slice('release '.length)
+        : description;
+    const releaseType = type === 'release';
+    const releaseChore = type === 'chore' &&
+        (scope === 'release' || description.startsWith('release '));
+    return (releaseType || releaseChore) && isVersionTag(version);
+}
+export function parseCommit(commit, includeNonConventional = false) {
+    const headerMatch = conventionalHeaderPattern.exec(commit.subject.trim());
+    if (!headerMatch && !includeNonConventional)
+        return undefined;
+    let description = headerMatch ? headerMatch[4] : commit.subject.trim();
+    const pullRequestMatch = pullRequestSuffixPattern.exec(description);
+    if (pullRequestMatch)
+        description = description.slice(0, pullRequestMatch.index).trimEnd();
+    if (headerMatch &&
+        isReleaseCommit(headerMatch[1].toLowerCase(), headerMatch[2]?.toLowerCase(), description))
+        return undefined;
+    const notes = breakingNotes(commit.body);
+    return {
+        ...commit,
+        type: headerMatch ? headerMatch[1].toLowerCase() : 'other',
+        ...(headerMatch?.[2] ? { scope: headerMatch[2] } : {}),
+        description,
+        breaking: Boolean(headerMatch?.[3]) ||
+            notes.length > 0 ||
+            breakingFooterPattern.test(commit.body),
+        breakingNotes: notes,
+        ...(pullRequestMatch ? { pr: pullRequestMatch[1] } : {}),
+    };
+}
+export function recommendedBump(commits) {
+    let bump;
+    for (const commit of commits) {
+        const parsed = parseCommit(commit);
+        if (!parsed)
+            continue;
+        if (parsed.breaking)
+            return 'major';
+        if (parsed.type === 'feat')
+            bump = 'minor';
+        else if ((parsed.type === 'fix' || parsed.type === 'perf') && !bump)
+            bump = 'patch';
+    }
+    return bump;
+}

package/lib/contributors/authors.d.ts

@@ -0,0 +1,6 @@
+export interface AuthorCommit {
+    hash: string;
+    name?: string;
+    email?: string;
+}
+export declare function groupAuthorCommits(commits: readonly AuthorCommit[]): string[][];

package/lib/contributors/authors.js

@@ -0,0 +1,20 @@
+const validHash = /^[a-f\d]{7,64}$/i;
+function authorIdentity(commit) {
+    if (commit.email?.trim())
+        return `email:${commit.email.trim().toLowerCase()}`;
+    if (commit.name?.trim())
+        return `name:${commit.name.trim()}`;
+    return `commit:${commit.hash}`;
+}
+export function groupAuthorCommits(commits) {
+    const authors = new Map();
+    for (const commit of commits) {
+        if (!validHash.test(commit.hash))
+            continue;
+        const identity = authorIdentity(commit);
+        const hashes = authors.get(identity) ?? new Set();
+        hashes.add(commit.hash);
+        authors.set(identity, hashes);
+    }
+    return [...authors.values()].map((hashes) => [...hashes]);
+}

package/lib/contributors/privacy.d.ts

@@ -0,0 +1,2 @@
+export declare function redactEmails(value: string): string;
+export declare function authorName(value: string): string;

package/lib/contributors/privacy.js

@@ -0,0 +1,9 @@
+const emailAddressPattern = /[A-Z0-9.!#$%&'*+/=?^_`{|}~-]+(?:@|%40)[A-Z0-9-]+(?:(?:\.|%2e)[A-Z0-9-]+)+/gi;
+const unknownContributor = 'Unknown contributor';
+export function redactEmails(value) {
+    return value.replace(emailAddressPattern, '[redacted email]');
+}
+export function authorName(value) {
+    const name = value.trim();
+    return !name || redactEmails(name) !== name ? unknownContributor : name;
+}

package/lib/contributors/profile.d.ts

@@ -0,0 +1,5 @@
+import type { ContributorProfile } from '../types.js';
+export type { ContributorProfile } from '../types.js';
+export declare function validateProfile(username: unknown, urlValue: unknown, host: string): ContributorProfile | undefined;
+export declare function readGitHubProfile(data: unknown): ContributorProfile | undefined;
+export declare function readBitbucketProfile(data: unknown): ContributorProfile | undefined;

package/lib/contributors/profile.js

@@ -0,0 +1,51 @@
+function objectValue(value) {
+    return value !== null && typeof value === 'object'
+        ? value
+        : undefined;
+}
+export function validateProfile(username, urlValue, host) {
+    if (typeof username !== 'string' ||
+        !username.trim() ||
+        username.includes('@') ||
+        /[<>\r\n]/.test(username))
+        return undefined;
+    if (host === 'github.com' && /\s/.test(username))
+        return undefined;
+    if (typeof urlValue !== 'string')
+        return undefined;
+    try {
+        const url = new URL(urlValue);
+        const path = decodeURIComponent(url.pathname);
+        if (url.protocol !== 'https:' ||
+            url.hostname.toLowerCase() !== host ||
+            url.username ||
+            url.password ||
+            url.port ||
+            url.search ||
+            url.hash ||
+            !path ||
+            path === '/' ||
+            path.includes('@') ||
+            /%40/i.test(url.pathname))
+            return undefined;
+        return { username: username.trim(), url: url.href };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readGitHubProfile(data) {
+    const author = objectValue(objectValue(data)?.author);
+    return validateProfile(author?.login, author?.html_url, 'github.com');
+}
+export function readBitbucketProfile(data) {
+    const response = objectValue(data);
+    const author = objectValue(response?.author);
+    const user = objectValue(author?.user);
+    if (!user)
+        return undefined;
+    const links = objectValue(user.links);
+    const html = objectValue(links?.html);
+    const username = user.nickname ?? user.display_name;
+    return validateProfile(username, html?.href, 'bitbucket.org');
+}

package/lib/contributors/repository.d.ts

@@ -0,0 +1,7 @@
+export interface Repository {
+    host: 'github.com' | 'bitbucket.org';
+    path: string;
+}
+export declare function parseRepository(repositoryUrl?: string): Repository | undefined;
+export declare function getCommitEndpoint(repository: Repository, hash: string): string;
+export declare function getRepositoryToken(repository: Repository): string | undefined;

package/lib/contributors/repository.js

@@ -0,0 +1,36 @@
+export function parseRepository(repositoryUrl) {
+    if (!repositoryUrl)
+        return undefined;
+    try {
+        const url = new URL(repositoryUrl);
+        if (url.protocol !== 'https:' ||
+            url.username ||
+            url.password ||
+            url.port ||
+            url.search ||
+            url.hash)
+            return undefined;
+        const host = url.hostname.toLowerCase();
+        if (host !== 'github.com' && host !== 'bitbucket.org')
+            return undefined;
+        const path = url.pathname.replace(/^\/+|\/+$/g, '').replace(/\.git$/i, '');
+        const segments = path.split('/');
+        if (segments.length !== 2 ||
+            segments.some((part) => !/^[a-z\d_.-]+$/i.test(part) || part === '.' || part === '..'))
+            return undefined;
+        return { host, path };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function getCommitEndpoint(repository, hash) {
+    return repository.host === 'github.com'
+        ? `https://api.github.com/repos/${repository.path}/commits/${hash}`
+        : `https://api.bitbucket.org/2.0/repositories/${repository.path}/commit/${hash}`;
+}
+export function getRepositoryToken(repository) {
+    return repository.host === 'github.com'
+        ? process.env.GH_TOKEN || process.env.GITHUB_TOKEN
+        : process.env.BITBUCKET_TOKEN;
+}

package/lib/contributors/resolve.d.ts

@@ -0,0 +1,10 @@
+import type { AuthorCommit } from './authors.js';
+import type { ContributorProfile } from './profile.js';
+export type { ContributorProfile } from './profile.js';
+export interface ContributorProgress {
+    completed: number;
+    total: number;
+    resolved: number;
+    requests: number;
+}
+export declare function resolveContributors(commits: readonly AuthorCommit[], repositoryUrl?: string, onProgress?: (progress: ContributorProgress) => void): Promise<Record<string, ContributorProfile>>;