@williamthorsen/release-kit 11.0.0 → 13.0.0

package/dist/esm/buildChangelogEntries.js

@@ -1,161 +1,263 @@
 import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
+import { buildEmptyReleaseEntry } from "./buildEmptyReleaseEntry.js";
 import { extractVersion } from "./changelogJsonUtils.js";
-import { DEFAULT_BREAKING_POLICIES, DEFAULT_WORK_TYPES } from "./defaults.js";
+import { classifyChangelogCommit, isNonChangeSubject, isReleaseSubject } from "./classifyChangelogCommit.js";
+import { DEFAULT_BREAKING_POLICIES, DEFAULT_VERSION_PATTERNS, DEFAULT_WORK_TYPES } from "./defaults.js";
+import { determineBumpType } from "./determineBumpType.js";
+import { enumerateReleaseWindows } from "./enumerateReleaseWindows.js";
 import { extractMigration } from "./extractMigration.js";
-import { COMMIT_PREPROCESSOR_PATTERNS, parseCommitMessage, PIPE_SCOPE_SOURCE } from "./parseCommitMessage.js";
-import { resolveCliffConfigPath } from "./resolveCliffConfigPath.js";
-import { runGitCliff } from "./runGitCliff.js";
+import { parseChangeRecordBlock, stripChangeRecordBlocks } from "./parseChangeRecordBlock.js";
+import { evaluateBreakingPolicy, parseSubject, resolveType } from "./parseCommitMessage.js";
 import { stripEmojiPrefix } from "./stripEmojiPrefix.js";
-import { isRecord, isUnknownArray } from "./typeGuards.js";
-const HTML_COMMENT_PREFIX_PATTERN = /^<!--[^>]*-->/;
+const UNRELEASED_TAG = 'unreleased';
 const CANONICAL_SECTION_ORDER = new Map(Object.values(DEFAULT_WORK_TYPES).map((config, index) => [stripGroupDecorations(config.header), index]));
 function canonicalSectionPriority(title) {
     const index = CANONICAL_SECTION_ORDER.get(stripGroupDecorations(title));
     return index ?? Infinity;
 }
 export function stripGroupDecorations(group) {
-    return stripEmojiPrefix(group.replace(HTML_COMMENT_PREFIX_PATTERN, ''));
+    return stripEmojiPrefix(group);
 }
 export function buildChangelogEntries(config, tag, options) {
-    const resolvedConfigPath = resolveCliffConfigPath(config.cliffConfigPath, import.meta.url);
-    const cliffArgs = ['--context', '--tag', tag];
-    if (options?.tagPattern !== undefined) {
-        cliffArgs.push('--tag-pattern', options.tagPattern);
-    }
-    const includePaths = options?.includePaths ?? [];
-    for (const includePath of includePaths) {
-        cliffArgs.push('--include-path', includePath);
-    }
+    const history = readReleaseHistory(config, options);
+    return { entries: toChangelogEntries(history, tag), diagnostics: history.unreleased.diagnostics };
+}
+export function readReleaseHistory(config, options) {
     try {
-        const contextJson = runGitCliff(resolvedConfigPath, cliffArgs);
-        const releases = parseCliffContext(contextJson);
-        const devOnlySections = new Set(config.changelogJson.devOnlySections);
-        const workTypes = config.workTypes ?? DEFAULT_WORK_TYPES;
-        const breakingPolicies = config.breakingPolicies ?? DEFAULT_BREAKING_POLICIES;
-        return transformReleases(releases, devOnlySections, workTypes, breakingPolicies);
+        const windows = enumerateReleaseWindows({
+            ...(options.paths !== undefined && { paths: options.paths }),
+            tagPrefixes: options.tagPrefixes,
+            unreleasedTag: UNRELEASED_TAG,
+        });
+        const context = {
+            breakingPolicies: config.breakingPolicies ?? DEFAULT_BREAKING_POLICIES,
+            devOnlySections: new Set(config.changelogJson.devOnlySections.map(stripGroupDecorations)),
+            ...(options.workspaceDir !== undefined && {
+                routing: { workspaceDir: options.workspaceDir, scopeAliases: config.scopeAliases ?? {} },
+            }),
+            versionPatterns: config.versionPatterns ?? DEFAULT_VERSION_PATTERNS,
+            workTypes: config.workTypes ?? DEFAULT_WORK_TYPES,
+        };
+        return transformReleases(windows, context);
     }
     catch (error) {
-        throw chainError(`Failed to build changelog entries for tag ${tag}`, error);
+        throw chainError(`Failed to read the release history for ${options.tagPrefixes.join(', ')}`, error);
     }
 }
-function parseCliffContext(json) {
-    const parsed = JSON.parse(json);
-    if (!isUnknownArray(parsed)) {
-        throw new TypeError('Expected git-cliff --context output to be an array');
+export function toChangelogEntries(history, tag) {
+    const { unreleased } = history;
+    if (unreleased.sections.length === 0) {
+        return [...history.releasedEntries];
     }
-    return parsed.map(toCliffContextRelease);
+    return [
+        { version: extractVersion(tag), date: unreleased.date, sections: unreleased.sections },
+        ...history.releasedEntries,
+    ];
 }
-function toCliffContextRelease(value) {
-    if (!isRecord(value)) {
-        return {};
-    }
-    const release = {};
-    if (typeof value['version'] === 'string') {
-        release.version = value['version'];
-    }
-    if (typeof value['timestamp'] === 'number') {
-        release.timestamp = value['timestamp'];
-    }
-    if (isUnknownArray(value['commits'])) {
-        release.commits = value['commits'].map(toCliffContextCommit);
+export function toReleaseEntries(history, tag, today) {
+    if (history.unreleased.sections.length === 0) {
+        return [buildEmptyReleaseEntry(extractVersion(tag), today), ...history.releasedEntries];
     }
-    return release;
+    return toChangelogEntries(history, tag);
 }
-function toCliffContextCommit(value) {
-    if (!isRecord(value)) {
-        return { message: '' };
-    }
-    const commit = {
-        message: typeof value['message'] === 'string' ? value['message'] : '',
+function transformReleases(windows, context) {
+    const [unreleasedWindow, baselineWindow] = windows;
+    const diagnostics = {
+        malformedBlocks: [],
+        policyViolations: [],
+        undeclaredEntryTypes: [],
+        unroutedEntryScopes: [],
     };
-    if (typeof value['group'] === 'string') {
-        commit.group = value['group'];
-    }
-    if (typeof value['id'] === 'string') {
-        commit.id = value['id'];
-    }
-    return commit;
-}
-function transformReleases(releases, devOnlySections, workTypes, breakingPolicies) {
-    const entries = [];
-    const devOnlyNormalised = new Set([...devOnlySections].map(stripGroupDecorations));
-    for (const release of releases) {
-        if (release.version === undefined) {
-            continue;
+    const signals = [];
+    const unparseable = [];
+    let parsedCommitCount = 0;
+    const sectionMap = new Map();
+    const unreleasedCommits = unreleasedWindow?.commits ?? [];
+    for (const commit of unreleasedCommits) {
+        const reading = readCommit(commit, context, diagnostics);
+        for (const derived of reading.items) {
+            appendItem(sectionMap, derived.header, derived.item);
+            signals.push(derived.signal);
         }
-        const version = extractVersion(release.version);
-        const date = release.timestamp !== undefined ? new Date(release.timestamp * 1_000).toISOString().slice(0, 10) : 'unreleased';
-        const sectionMap = new Map();
-        const commits = release.commits ?? [];
-        for (const commit of commits) {
-            const group = stripCommentPrefix(commit.group ?? 'Other');
-            const description = extractDescription(commit.message);
-            const body = extractBody(commit.message);
-            const breaking = isBreakingUnderPolicy(commit, workTypes, breakingPolicies);
-            let items = sectionMap.get(group);
-            if (items === undefined) {
-                items = [];
-                sectionMap.set(group, items);
-            }
-            const item = { description };
-            if (body !== undefined) {
-                item.body = body;
-            }
-            if (breaking) {
-                item.breaking = true;
-            }
-            const migration = extractMigration(body);
-            if (migration !== undefined) {
-                item.migration = migration;
-            }
-            if (commit.id !== undefined && commit.id !== '') {
-                item.hash = commit.id;
-            }
-            items.push(item);
+        if (reading.items.length > 0) {
+            parsedCommitCount += 1;
+        }
+        else if (reading.isUnparseable) {
+            unparseable.push(commit);
         }
-        const sections = [];
-        for (const [title, items] of sectionMap) {
-            if (items.length === 0) {
-                continue;
+    }
+    const releasedEntries = [];
+    for (const release of windows.slice(1)) {
+        const releaseSections = new Map();
+        for (const commit of release.commits) {
+            for (const derived of readCommit(commit, context, undefined).items) {
+                appendItem(releaseSections, derived.header, derived.item);
             }
-            sections.push({
-                title,
-                audience: devOnlyNormalised.has(stripGroupDecorations(title)) ? 'dev' : 'all',
-                items,
-            });
         }
-        sections.sort((a, b) => canonicalSectionPriority(a.title) - canonicalSectionPriority(b.title));
+        const sections = buildSections(releaseSections, context.devOnlySections);
         if (sections.length > 0) {
-            entries.push({ version, date, sections });
+            releasedEntries.push({ version: extractVersion(release.version), date: formatDate(release.timestamp), sections });
         }
     }
-    return entries;
+    return {
+        previousTag: baselineWindow?.version,
+        releasedEntries,
+        unreleased: {
+            bump: determineBumpType(signals, context.workTypes, context.versionPatterns),
+            commits: unreleasedCommits.filter((commit) => !isReleaseSubject(commit.subject)).toReversed(),
+            date: formatDate(unreleasedWindow?.timestamp ?? Math.floor(Date.now() / 1_000)),
+            diagnostics,
+            parsedCommitCount,
+            sections: buildSections(sectionMap, context.devOnlySections),
+            unparseableCommits: unparseable.length > 0 ? unparseable.toReversed() : undefined,
+        },
+    };
 }
-function stripCommentPrefix(group) {
-    return group.replace(HTML_COMMENT_PREFIX_PATTERN, '');
+function readCommit(commit, context, diagnostics) {
+    if (isNonChangeSubject(commit.subject)) {
+        return { items: [], isUnparseable: false };
+    }
+    const reading = parseChangeRecordBlock(commit.message);
+    if (reading.kind === 'malformed') {
+        diagnostics?.malformedBlocks.push({
+            commitHash: commit.hash,
+            commitSubject: commit.subject,
+            reason: reading.reason,
+        });
+    }
+    if (reading.kind === 'read' && reading.entries.length > 0) {
+        const items = reading.entries.flatMap((entry, entryIndex) => buildEntryItem(commit, entry, entryIndex + 1, reading.prNumber, context, diagnostics) ?? []);
+        return { items, isUnparseable: false };
+    }
+    const classification = classifyChangelogCommit(commit, context.workTypes, {
+        breakingPolicies: context.breakingPolicies,
+        ...(diagnostics !== undefined && {
+            onPolicyViolation: (violating, type, surface) => {
+                diagnostics.policyViolations.push({
+                    commitHash: violating.hash,
+                    commitSubject: violating.subject,
+                    type,
+                    surface,
+                });
+            },
+        }),
+    });
+    if (classification.kind !== 'header') {
+        return { items: [], isUnparseable: classification.kind === 'unparseable' && reading.kind !== 'malformed' };
+    }
+    const item = buildTitleItem(commit, classification.breaking, context.workTypes);
+    return {
+        items: [
+            { header: classification.header, item, signal: { type: classification.type, breaking: item.breaking === true } },
+        ],
+        isUnparseable: false,
+    };
+}
+function buildSections(sectionMap, devOnlySections) {
+    const sections = [];
+    for (const [title, items] of sectionMap) {
+        sections.push({
+            title,
+            audience: devOnlySections.has(stripGroupDecorations(title)) ? 'dev' : 'all',
+            items,
+        });
+    }
+    return sections.toSorted((a, b) => canonicalSectionPriority(a.title) - canonicalSectionPriority(b.title));
 }
-function isBreakingUnderPolicy(commit, workTypes, breakingPolicies) {
-    if (!subjectHasBreakingMarker(commit.message)) {
-        return false;
+function isRoutedTo(scopes, routing) {
+    if (scopes.length === 0) {
+        return true;
     }
-    const parsed = parseCommitMessage(commit.message, commit.id ?? '', workTypes, undefined, { breakingPolicies });
-    return parsed?.breaking ?? true;
+    return scopes.some((scope) => {
+        const resolved = routing.scopeAliases[scope] ?? scope;
+        return resolved === '*' || resolved === routing.workspaceDir;
+    });
+}
+function formatDate(timestamp) {
+    return new Date(timestamp * 1_000).toISOString().slice(0, 10);
 }
-const SUBJECT_BREAKING_MARKER_PATTERN = new RegExp(String.raw `^(?:${PIPE_SCOPE_SOURCE}\|)?\w+(?:\([^)]+\))?!:`);
-function subjectHasBreakingMarker(message) {
-    let subject = message.split('\n', 1)[0] ?? '';
-    for (const pattern of COMMIT_PREPROCESSOR_PATTERNS) {
-        subject = subject.replace(pattern, '');
+function appendItem(sectionMap, header, item) {
+    let items = sectionMap.get(header);
+    if (items === undefined) {
+        items = [];
+        sectionMap.set(header, items);
     }
-    return SUBJECT_BREAKING_MARKER_PATTERN.test(subject);
+    items.push(item);
+}
+function buildEntryItem(commit, entry, position, prNumber, context, diagnostics) {
+    const { breakingPolicies, routing, workTypes } = context;
+    if (routing !== undefined && !isRoutedTo(entry.scopes, routing)) {
+        return undefined;
+    }
+    const type = resolveType(entry.type, workTypes);
+    if (type === undefined) {
+        diagnostics?.undeclaredEntryTypes.push({
+            commitHash: commit.hash,
+            commitSubject: commit.subject,
+            entryPosition: position,
+            type: entry.type,
+        });
+        return undefined;
+    }
+    const config = workTypes[type];
+    if (config === undefined || config.excludedFromChangelog === true) {
+        return undefined;
+    }
+    const breaking = evaluateBreakingPolicy({
+        commit: { message: commit.message, subject: commit.subject, hash: commit.hash },
+        resolvedType: type,
+        hasPrefixBreaking: entry.breaking,
+        hasFooterBreaking: false,
+        policy: breakingPolicies[type] ?? 'optional',
+        prefixSurface: 'entry',
+        onPolicyViolation: diagnostics === undefined
+            ? undefined
+            : (violating, violatedType, surface) => {
+                diagnostics.policyViolations.push({
+                    commitHash: violating.hash,
+                    commitSubject: violating.subject,
+                    type: violatedType,
+                    surface,
+                    entryPosition: position,
+                });
+            },
+    });
+    const item = {
+        description: prNumber === undefined ? entry.text : `${entry.text} (#${prNumber})`,
+    };
+    if (breaking) {
+        item.breaking = true;
+    }
+    if (entry.migration !== undefined) {
+        item.migration = entry.migration;
+    }
+    item.hash = commit.hash;
+    item.entry = position;
+    return { header: config.header, item, signal: { type, breaking } };
+}
+function buildTitleItem(commit, isParsedBreaking, workTypes) {
+    const body = extractBody(stripChangeRecordBlocks(commit.message));
+    const item = { description: extractDescription(commit.message) };
+    if (body !== undefined) {
+        item.body = body;
+    }
+    if (isParsedBreaking && subjectHasBreakingMarker(commit.message, workTypes)) {
+        item.breaking = true;
+    }
+    const migration = extractMigration(body);
+    if (migration !== undefined) {
+        item.migration = migration;
+    }
+    item.hash = commit.hash;
+    return item;
+}
+function subjectHasBreakingMarker(message, workTypes) {
+    return parseSubject(message.split('\n', 1)[0] ?? '', workTypes)?.breaking === true;
 }
 function extractDescription(message) {
     const firstLine = message.split('\n', 1)[0] ?? message;
     const afterColon = firstLine.split(': ').slice(1).join(': ');
-    if (afterColon.length > 0) {
-        return afterColon.charAt(0).toUpperCase() + afterColon.slice(1);
-    }
-    return firstLine;
+    return afterColon.charAt(0).toUpperCase() + afterColon.slice(1);
 }
 const TRAILER_PATTERNS = [
     /^Change:/i,

package/dist/esm/buildDependencyGraph.d.ts

@@ -1,17 +1,17 @@
 import type { WorkspaceConfig } from './types.js';
 /** Identities, current versions, and `workspace:` dependency edges of the workspaces' packages. */
 export interface DependencyGraph {
-    /** Resolve a package name to its workspace `dir`. */
+    /** Maps a package name to its workspace `dir`. */
     packageNameToDir: Map<string, string>;
-    /** Resolve a workspace `dir` to its package name (inverse of `packageNameToDir`). */
+    /** Maps a workspace `dir` to its package name (inverse of `packageNameToDir`). */
     dirToPackageName: Map<string, string>;
-    /** Resolve a workspace `dir` to its current version; absent when its `package.json` has no string `version`. */
+    /** Maps a workspace `dir` to its current version; absent when its `package.json` doesn't have a string `version`. */
     dirToVersion: Map<string, string>;
-    /** Map a package name to the workspaces that depend on it. */
+    /** Maps a package name to the workspaces that depend on it. */
     dependentsOf: Map<string, WorkspaceConfig[]>;
     /**
-     * Forward adjacency: map a workspace `dir` to the set of `workspace:`-protocol package
-     * names it declares in `dependencies` or `peerDependencies`. Complement of `dependentsOf`.
+     * Maps a workspace `dir` to the `workspace:`-protocol package names that it declares in `dependencies` or
+     * `peerDependencies` (the forward counterpart of `dependentsOf`).
      */
     dependenciesOf: Map<string, Set<string>>;
 }

package/dist/esm/buildEmptyReleaseEntry.d.ts

@@ -1,10 +1,3 @@
 import type { ChangelogEntry } from './types.js';
-/**
- * Build a synthetic changelog entry for a forced empty-range release.
- *
- * Produces a single `ChangelogEntry` with one `'Notes'` section (audience `'dev'`)
- * containing a single `'Forced version bump.'` item. Used when `release-kit prepare`
- * proceeds via `--force`, `--bump=X`, or `--set-version` against a unit with zero
- * qualifying commits since its last tag. Pure function: no I/O.
- */
+/** Builds the changelog entry of a forced release whose unreleased window doesn't yield any changelog item. */
 export declare function buildEmptyReleaseEntry(version: string, date: string): ChangelogEntry;

package/dist/esm/buildReleaseSummary.d.ts

@@ -1,12 +1,6 @@
 import type { PrepareResult } from './types.js';
 /**
- * Build a release commit body from a prepare result.
- *
- * Each released workspace with commits gets a section headed by its tag,
- * followed by scope-stripped commit messages as bullet points. Sections
- * are separated by blank lines. The project release (when present) is
- * appended as a final section using the same format. Returns an empty
- * string when no released workspaces have commits and there is no project
- * release.
+ * Builds a release commit body from a prepare result: one section per released workspace or project that has commits,
+ * the project last, each headed by its tag and listing its scope-stripped commit subjects.
  */
 export declare function buildReleaseSummary(result: Pick<PrepareResult, 'project' | 'workspaces'>): string;

package/dist/esm/buildReleaseSummary.js

@@ -11,7 +11,7 @@ export function buildReleaseSummary(result) {
         }
         const lines = [workspace.tag];
         for (const commit of commits) {
-            lines.push(`- ${stripScope(commit.message)}`);
+            lines.push(`- ${stripScope(commit.subject)}`);
         }
         sections.push(lines.join('\n'));
     }
@@ -19,7 +19,7 @@ export function buildReleaseSummary(result) {
     if (project !== undefined && project.status === 'released' && project.commits.length > 0) {
         const lines = [project.tag];
         for (const commit of project.commits) {
-            lines.push(`- ${stripScope(commit.message)}`);
+            lines.push(`- ${stripScope(commit.subject)}`);
         }
         sections.push(lines.join('\n'));
     }

package/dist/esm/buildSyntheticChangelogEntry.d.ts

@@ -1,11 +1,9 @@
 import type { ChangelogEntry } from './types.js';
 /**
- * Build a synthetic changelog entry for a propagation-only bump.
- *
- * Produces a single `ChangelogEntry` with one `'Dependency updates'` section (audience `'dev'`)
- * containing one item per propagated-from dependency. Pure function: no I/O.
+ * Builds the changelog entry of a propagation-only bump, with one item per dependency whose bump propagated, under
+ * `sectionTitle`, the resolved `deps` work type's header.
  */
 export declare function buildSyntheticChangelogEntry(propagatedFrom: ReadonlyArray<{
     packageName: string;
     newVersion: string;
-}>, version: string, date: string): ChangelogEntry;
+}>, version: string, date: string, sectionTitle: string): ChangelogEntry;

package/dist/esm/buildSyntheticChangelogEntry.js

@@ -1,10 +1,10 @@
-export function buildSyntheticChangelogEntry(propagatedFrom, version, date) {
+export function buildSyntheticChangelogEntry(propagatedFrom, version, date, sectionTitle) {
     const items = propagatedFrom.map((dep) => ({
         description: `Bumped \`${dep.packageName}\` to ${dep.newVersion}`,
     }));
     return {
         version,
         date,
-        sections: [{ title: 'Dependency updates', audience: 'dev', items }],
+        sections: [{ title: sectionTitle, audience: 'dev', items }],
     };
 }

package/dist/esm/bumpVersion.d.ts

@@ -1,10 +1,3 @@
 import type { ReleaseType } from './types.js';
-/**
- * Bumps a semver version string by the given release type.
- *
- * @param version - A semver version string (e.g., '1.2.3').
- * @param releaseType - The type of release bump to apply.
- * @returns The bumped version string.
- * @throws If the version string is not a valid semver format.
- */
+/** Bumps a `major.minor.patch` version by the release type; throws on a version of any other form. */
 export declare function bumpVersion(version: string, releaseType: ReleaseType): string;

package/dist/esm/changelogJsonFile.d.ts

@@ -1,15 +1,13 @@
 import type { ChangelogEntry, ReleaseConfig } from './types.js';
-/** Resolve the absolute output path for the `changelog.json` file under a workspace's changelog directory. */
+/** Resolves the path of the `changelog.json` file under a workspace's changelog directory. */
 export declare function resolveChangelogJsonPath(config: Pick<ReleaseConfig, 'changelogJson'>, changelogPath: string): string;
 /** Renders changelog entries as a `changelog.json` file's complete content, sorted newest-first. */
 export declare function renderChangelogJson(entries: ChangelogEntry[]): string;
 /**
- * Merges `entries` with the on-disk entries at `filePath` and returns the merged set in
- * newest-first order, without writing.
+ * Merges `entries` with the on-disk entries at `filePath` and returns the merged set in newest-first order, without
+ * writing.
  *
- * Preserves entries that exist on disk but are absent from `entries` — load-bearing for
- * synthetic-entry preservation across propagation runs. Reads the file when present; treats a
- * missing or malformed file as an empty existing set, so a malformed file does not abort the
- * release.
+ * Keeps an on-disk entry that `entries` lacks, which preserves synthetic entries across propagation runs. A missing or
+ * malformed file counts as empty, so that a malformed file does not abort the release.
  */
 export declare function mergeChangelogEntriesWithDisk(filePath: string, entries: ChangelogEntry[]): ChangelogEntry[];

package/dist/esm/changelogJsonFile.js

@@ -2,8 +2,8 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import stringify from 'json-stringify-pretty-compact';
-import semver from 'semver';
 import { isChangelogEntry } from "./changelogJsonUtils.js";
+import { compareVersionsDescending } from "./compareVersions.js";
 import { isUnknownArray } from "./typeGuards.js";
 export function resolveChangelogJsonPath(config, changelogPath) {
     return join(changelogPath, config.changelogJson.outputPath);
@@ -16,7 +16,7 @@ export function mergeChangelogEntriesWithDisk(filePath, entries) {
     return mergeEntries(entries, existing);
 }
 function sortNewestFirst(entries) {
-    return [...entries].sort((a, b) => compareVersionsDescending(a.version, b.version));
+    return [...entries].toSorted((a, b) => compareVersionsDescending(a.version, b.version));
 }
 function readExistingEntries(filePath) {
     if (!existsSync(filePath)) {
@@ -45,18 +45,3 @@ function mergeEntries(newEntries, existingEntries) {
     }
     return sortNewestFirst(versionMap.values());
 }
-function compareVersionsDescending(a, b) {
-    const aValid = semver.valid(a);
-    const bValid = semver.valid(b);
-    if (aValid && bValid)
-        return semver.rcompare(aValid, bValid);
-    if (aValid)
-        return -1;
-    if (bValid)
-        return 1;
-    if (a > b)
-        return -1;
-    if (a < b)
-        return 1;
-    return 0;
-}

package/dist/esm/changelogJsonUtils.d.ts

@@ -1,19 +1,16 @@
 import type { ChangelogEntry } from './types.js';
 /**
- * Type guard for `ChangelogEntry` values parsed from JSON.
+ * Reports whether a value parsed from JSON is a `ChangelogEntry`.
  *
- * Checks the entry's top level only: `sections` is verified to be an array, and its contents pass
- * through unvalidated. `.meta/changelog.json` is written by release-kit and read tolerantly; strict
- * validation applies to the human-authored `.meta/changelog-overrides.json`, in `changelogOverrides.ts`.
+ * Checks the entry's top level only: `sections` must be an array, and its contents pass through unvalidated.
+ * `.meta/changelog.json` is written by release-kit and read tolerantly; strict validation applies to the
+ * human-authored `.meta/changelog-overrides.json`, in `changelogOverrides.ts`.
  */
 export declare function isChangelogEntry(value: unknown): value is ChangelogEntry;
-/** Extract the version from a tag by stripping the prefix up to the first digit. */
+/** Extracts the version from a tag: the text from its first `N.N.N` onward, or the whole tag when it contains none. */
 export declare function extractVersion(tag: string): string;
 /**
- * Read and parse a changelog JSON file, returning validated entries.
- *
- * Returns `undefined` if the file cannot be read or does not contain a valid array.
- * Silent on parse error — for the warn-and-treat-as-empty variant used by upsert callers,
- * see `readExistingEntries` in `./changelogJsonFile.ts`.
+ * Reads the changelog entries in a JSON file; undefined when the file is missing or unreadable, or doesn't contain an
+ * array.
  */
 export declare function readChangelogEntries(filePath: string): ChangelogEntry[] | undefined;