@williamthorsen/release-kit 12.0.0 → 13.0.0

package/dist/esm/buildChangelogEntries.d.ts

@@ -1,10 +1,10 @@
 import { type RawCommit } from './enumerateReleaseWindows.js';
 import type { GenerateChangelogOptions } from './generateChangelogs.js';
-import type { ChangelogEntry, ChangelogSection, MalformedChangeRecordBlock, PolicyViolation, ReleaseConfig, ReleaseType, UndeclaredEntryType } from './types.js';
+import type { ChangelogEntry, ChangelogSection, MalformedChangeRecordBlock, PolicyViolation, ReleaseConfig, ReleaseType, UndeclaredEntryType, UnroutedEntryScope } from './types.js';
 /**
  * Strips a section title down to its bare name.
  *
- * A default title carries a leading emoji (e.g. `"🐛 Bug fixes"`), while a consumer's
+ * A default title has a leading emoji (e.g. `"🐛 Bug fixes"`), while a consumer's
  * `devOnlySections` or `workTypes` override may be written as a bare name. Comparing both sides
  * through this helper lets the two forms match.
  */
@@ -12,8 +12,7 @@ export declare function stripGroupDecorations(group: string): string;
 /**
  * Builds structured changelog entries from the release windows of git history, naming the unreleased window `tag`.
  *
- * Composes `readReleaseHistory` and `toChangelogEntries` for a caller that knows the tag before it reads. Performs no
- * `changelog.json` I/O; callers persist the entries via `renderChangelogJson`.
+ * Composes `readReleaseHistory` and `toChangelogEntries` for a caller that knows the tag before it reads.
  */
 export declare function buildChangelogEntries(config: ReleaseHistoryConfig, tag: string, options: GenerateChangelogOptions): {
     entries: ChangelogEntry[];
@@ -25,30 +24,35 @@ export interface ChangelogDiagnostics {
     /** Breaking-policy violations of the window's titles and change-record entries. */
     policyViolations: PolicyViolation[];
     undeclaredEntryTypes: UndeclaredEntryType[];
+    /**
+     * Entry scopes that don't route to any workspace. A read leaves it empty: Only a pass over every workspace can fill
+     * it.
+     */
+    unroutedEntryScopes: UnroutedEntryScope[];
 }
 /**
  * Reads a scope's release windows once and returns the changelog items of every window, with what the unreleased
  * window decides: its commits, its bump, and its diagnostics.
  *
- * A commit whose last `change-record` block records entries yields one item per entry; any other commit is
- * classified by its title through `classifyChangelogCommit`. A `release:` or merge subject yields nothing either
- * way. Only the unreleased window records diagnostics, since the released windows were reported when they were
- * prepared.
+ * A commit whose last `change-record` block records entries yields one item per entry routed to
+ * `options.workspaceDir`; any other commit is classified by its title through `classifyChangelogCommit`. A `release:`
+ * or merge subject yields nothing either way. The read records diagnostics only for the unreleased window, since the
+ * released windows were reported when they were prepared.
  */
 export declare function readReleaseHistory(config: ReleaseHistoryConfig, options: GenerateChangelogOptions): ReleaseHistory;
 /** The configuration that `readReleaseHistory` reads. */
-export type ReleaseHistoryConfig = Pick<ReleaseConfig, 'breakingPolicies' | 'changelogJson' | 'versionPatterns' | 'workTypes'>;
+export type ReleaseHistoryConfig = Pick<ReleaseConfig, 'breakingPolicies' | 'changelogJson' | 'scopeAliases' | 'versionPatterns' | 'workTypes'>;
 /** One read of a scope's release windows. */
 export interface ReleaseHistory {
     /** The newest matching tag that HEAD reaches; undefined when none does. */
     previousTag: string | undefined;
-    /** Entries of the released windows, newest first; a window that yields no item contributes none. */
+    /** Entries of the released windows, newest first; a window that doesn't yield any item contributes none. */
     releasedEntries: ChangelogEntry[];
     unreleased: UnreleasedWindowReading;
 }
 /** The unreleased window: its changelog sections and commits, and the bump and diagnostics that they determine. */
 export interface UnreleasedWindowReading {
-    /** The highest bump that the window's items call for; undefined when the window yields no item. */
+    /** The highest bump that the window's items call for; undefined when the window doesn't yield any item. */
     bump: ReleaseType | undefined;
     /** The window's commits, newest first, without release commits. */
     commits: RawCommit[];
@@ -59,10 +63,16 @@ export interface UnreleasedWindowReading {
     parsedCommitCount: number;
     sections: ChangelogSection[];
     /**
-     * Commits that yield no item and that neither an exclusion nor a diagnostic accounts for, newest first; undefined
-     * when none.
+     * Commits that don't yield any item and that neither an exclusion nor a diagnostic accounts for, newest first;
+     * undefined when none.
      */
     unparseableCommits: RawCommit[] | undefined;
 }
 /** Labels the unreleased window of `history` with `tag` and returns the entries of every window, newest first. */
 export declare function toChangelogEntries(history: ReleaseHistory, tag: string): ChangelogEntry[];
+/**
+ * Returns the entries that a direct release tagged `tag` records: those of `toChangelogEntries`, or, when the
+ * unreleased window doesn't yield any item, the synthetic "Forced version bump." entry dated `today` ahead of the
+ * released entries.
+ */
+export declare function toReleaseEntries(history: ReleaseHistory, tag: string, today: string): ChangelogEntry[];

package/dist/esm/buildChangelogEntries.js

@@ -1,4 +1,5 @@
 import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
+import { buildEmptyReleaseEntry } from "./buildEmptyReleaseEntry.js";
 import { extractVersion } from "./changelogJsonUtils.js";
 import { classifyChangelogCommit, isNonChangeSubject, isReleaseSubject } from "./classifyChangelogCommit.js";
 import { DEFAULT_BREAKING_POLICIES, DEFAULT_VERSION_PATTERNS, DEFAULT_WORK_TYPES } from "./defaults.js";
@@ -6,7 +7,7 @@ import { determineBumpType } from "./determineBumpType.js";
 import { enumerateReleaseWindows } from "./enumerateReleaseWindows.js";
 import { extractMigration } from "./extractMigration.js";
 import { parseChangeRecordBlock, stripChangeRecordBlocks } from "./parseChangeRecordBlock.js";
-import { COMMIT_PREPROCESSOR_PATTERNS, evaluateBreakingPolicy, PIPE_SCOPE_SOURCE, resolveType, } from "./parseCommitMessage.js";
+import { evaluateBreakingPolicy, parseSubject, resolveType } from "./parseCommitMessage.js";
 import { stripEmojiPrefix } from "./stripEmojiPrefix.js";
 const UNRELEASED_TAG = 'unreleased';
 const CANONICAL_SECTION_ORDER = new Map(Object.values(DEFAULT_WORK_TYPES).map((config, index) => [stripGroupDecorations(config.header), index]));
@@ -31,6 +32,9 @@ export function readReleaseHistory(config, options) {
         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,
         };
@@ -50,9 +54,20 @@ export function toChangelogEntries(history, tag) {
         ...history.releasedEntries,
     ];
 }
+export function toReleaseEntries(history, tag, today) {
+    if (history.unreleased.sections.length === 0) {
+        return [buildEmptyReleaseEntry(extractVersion(tag), today), ...history.releasedEntries];
+    }
+    return toChangelogEntries(history, tag);
+}
 function transformReleases(windows, context) {
     const [unreleasedWindow, baselineWindow] = windows;
-    const diagnostics = { malformedBlocks: [], policyViolations: [], undeclaredEntryTypes: [] };
+    const diagnostics = {
+        malformedBlocks: [],
+        policyViolations: [],
+        undeclaredEntryTypes: [],
+        unroutedEntryScopes: [],
+    };
     const signals = [];
     const unparseable = [];
     let parsedCommitCount = 0;
@@ -130,7 +145,7 @@ function readCommit(commit, context, diagnostics) {
     if (classification.kind !== 'header') {
         return { items: [], isUnparseable: classification.kind === 'unparseable' && reading.kind !== 'malformed' };
     }
-    const item = buildTitleItem(commit, classification.breaking);
+    const item = buildTitleItem(commit, classification.breaking, context.workTypes);
     return {
         items: [
             { header: classification.header, item, signal: { type: classification.type, breaking: item.breaking === true } },
@@ -149,6 +164,15 @@ function buildSections(sectionMap, devOnlySections) {
     }
     return sections.toSorted((a, b) => canonicalSectionPriority(a.title) - canonicalSectionPriority(b.title));
 }
+function isRoutedTo(scopes, routing) {
+    if (scopes.length === 0) {
+        return 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);
 }
@@ -161,7 +185,10 @@ function appendItem(sectionMap, header, item) {
     items.push(item);
 }
 function buildEntryItem(commit, entry, position, prNumber, context, diagnostics) {
-    const { breakingPolicies, workTypes } = context;
+    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({
@@ -208,13 +235,13 @@ function buildEntryItem(commit, entry, position, prNumber, context, diagnostics)
     item.entry = position;
     return { header: config.header, item, signal: { type, breaking } };
 }
-function buildTitleItem(commit, isParsedBreaking) {
+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)) {
+    if (isParsedBreaking && subjectHasBreakingMarker(commit.message, workTypes)) {
         item.breaking = true;
     }
     const migration = extractMigration(body);
@@ -224,21 +251,13 @@ function buildTitleItem(commit, isParsedBreaking) {
     item.hash = commit.hash;
     return item;
 }
-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, '');
-    }
-    return SUBJECT_BREAKING_MARKER_PATTERN.test(subject);
+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/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;