@williamthorsen/release-kit 14.2.1 → 14.2.3

package/dist/esm/applyChangelogOverrides.d.ts

@@ -0,0 +1,50 @@
+import type { ChangelogEntry, ChangelogOverride } from './types.js';
+/**
+ * Applies overrides to changelog entries, returning new entries without mutating the input.
+ *
+ * Each key's hash prefix is matched against the distinct `ChangelogItem.hash` values:
+ * - No match: The key is unmatched in this batch, and this function doesn't emit a warning.
+ * - One match: A bare key resolves to every item of that commit, and an ordinal key `<hash>:<n>` to the items whose
+ *   `entry` is `n`. A key that doesn't resolve to any item is unmatched, so an ordinal key on a title-derived item
+ *   goes stale.
+ * - Several matches: an error (ambiguous prefix).
+ *
+ * Two more conditions are errors, and the keys involved apply nowhere: a bare key that sets `description` or `body` on a
+ * commit with several items, and two keys that resolve to the same item.
+ *
+ * `matchedKeys` lists the keys that resolved to at least one item without error. The caller computes stale-key
+ * warnings, because in a monorepo a key may target a commit in another workspace: A key unmatched in one batch is not
+ * necessarily stale.
+ *
+ * An override whose audience is `'skip'` removes its item, and a section left empty is dropped; an entry left without
+ * sections is kept. An item without a `hash`, such as a synthetic propagation item, passes through unmatched. Errors
+ * are returned rather than thrown, and the caller decides whether to abort.
+ */
+export declare function applyChangelogOverrides(entries: ChangelogEntry[], overrides: Map<string, ChangelogOverride>): {
+    entries: ChangelogEntry[];
+    warnings: string[];
+    errors: string[];
+    matchedKeys: string[];
+};
+/** Formats the warning for an override key that did not match any item in the changelog. */
+export declare function formatStaleOverrideKeyWarning(key: string): string;
+/** Collects, for each hash, the distinct `entry` positions of the items that have it. */
+export declare function indexItemPositions(items: readonly {
+    hash?: string | undefined;
+    entry?: number | undefined;
+}[]): Map<string, Set<number | undefined>>;
+/**
+ * Resolves one override key against the commits' entry positions. `positions` lists the targeted items' `entry` values,
+ * ascending, with `undefined` standing for a title-derived item; it is empty when the key doesn't target any item of
+ * the commit.
+ */
+export declare function resolveOverrideKey(overrideKey: string, positionsByHash: Map<string, Set<number | undefined>>): {
+    kind: 'none';
+} | {
+    kind: 'ambiguous';
+    hashes: string[];
+} | {
+    kind: 'items';
+    hash: string;
+    positions: (number | undefined)[];
+};

package/dist/esm/applyChangelogOverrides.js

@@ -0,0 +1,162 @@
+import { extractMigration } from "./extractMigration.js";
+import { parseOverrideKey } from "./loadChangelogOverrides.js";
+export function applyChangelogOverrides(entries, overrides) {
+    const warnings = [];
+    if (overrides.size === 0) {
+        return { entries: entries.map(cloneEntry), warnings, errors: [], matchedKeys: [] };
+    }
+    const { errors, itemIdToKey } = resolveOverrideKeys(indexEntryPositions(entries), overrides);
+    const itemIdToOverride = new Map();
+    for (const [itemId, overrideKey] of itemIdToKey) {
+        const override = overrides.get(overrideKey);
+        if (override !== undefined) {
+            itemIdToOverride.set(itemId, override);
+        }
+    }
+    const matchedKeys = [...new Set(itemIdToKey.values())];
+    const transformedEntries = [];
+    for (const entry of entries) {
+        const transformedSections = [];
+        for (const section of entry.sections) {
+            const transformedItems = applyOverridesToItems(section.items, itemIdToOverride);
+            if (transformedItems.length === 0) {
+                continue;
+            }
+            transformedSections.push({ ...section, items: transformedItems });
+        }
+        transformedEntries.push({ ...entry, sections: transformedSections });
+    }
+    return { entries: transformedEntries, warnings, errors, matchedKeys };
+}
+export function formatStaleOverrideKeyWarning(key) {
+    return `Override key '${key}' did not match any item in the changelog (likely a stale reference)`;
+}
+export function indexItemPositions(items) {
+    const positionsByHash = new Map();
+    for (const item of items) {
+        if (item.hash === undefined)
+            continue;
+        const positions = positionsByHash.get(item.hash) ?? new Set();
+        positions.add(item.entry);
+        positionsByHash.set(item.hash, positions);
+    }
+    return positionsByHash;
+}
+export function resolveOverrideKey(overrideKey, positionsByHash) {
+    const { hashPrefix, entry } = parseOverrideKey(overrideKey);
+    const hashes = positionsByHash
+        .keys()
+        .filter((hash) => hash.startsWith(hashPrefix))
+        .toArray();
+    const [hash] = hashes;
+    if (hash === undefined) {
+        return { kind: 'none' };
+    }
+    if (hashes.length > 1) {
+        return { kind: 'ambiguous', hashes };
+    }
+    const available = [...(positionsByHash.get(hash) ?? [])];
+    const positions = entry === undefined
+        ? available.toSorted((left, right) => (left ?? 0) - (right ?? 0))
+        : available.filter((position) => position === entry);
+    return positions.length === 0 ? { kind: 'none' } : { kind: 'items', hash, positions };
+}
+function applyOverridesToItems(items, itemIdToOverride) {
+    const result = [];
+    for (const item of items) {
+        if (item.hash === undefined) {
+            result.push(cloneItem(item));
+            continue;
+        }
+        const override = itemIdToOverride.get(formatItemId(item.hash, item.entry));
+        if (override === undefined) {
+            result.push(cloneItem(item));
+            continue;
+        }
+        if (override.audience === 'skip') {
+            continue;
+        }
+        result.push(applyOverrideToItem(item, override));
+    }
+    return result;
+}
+function applyOverrideToItem(item, override) {
+    const result = { ...item };
+    if (override.description !== undefined) {
+        result.description = override.description;
+    }
+    if (override.body !== undefined) {
+        result.body = override.body;
+    }
+    if (override.body !== undefined && item.entry === undefined) {
+        const migration = extractMigration(override.body);
+        if (migration === undefined) {
+            delete result.migration;
+        }
+        else {
+            result.migration = migration;
+        }
+    }
+    if (override.breaking !== undefined) {
+        result.breaking = override.breaking;
+    }
+    return result;
+}
+function cloneEntry(entry) {
+    return {
+        ...entry,
+        sections: entry.sections.map((section) => ({ ...section, items: section.items.map(cloneItem) })),
+    };
+}
+function cloneItem(item) {
+    return { ...item };
+}
+function formatItemId(hash, entry) {
+    return entry === undefined ? hash : `${hash}:${entry}`;
+}
+function indexEntryPositions(entries) {
+    return indexItemPositions(entries.flatMap((entry) => entry.sections.flatMap((section) => section.items)));
+}
+function resolveOverrideKeys(positionsByHash, overrides) {
+    const errors = [];
+    const failedKeys = new Set();
+    const itemIdToKey = new Map();
+    for (const [overrideKey, override] of overrides) {
+        const resolution = resolveOverrideKey(overrideKey, positionsByHash);
+        if (resolution.kind === 'ambiguous') {
+            errors.push(`Override key '${overrideKey}' is ambiguous: matches multiple commits (${resolution.hashes.join(', ')}). ` +
+                'Use a longer prefix or the full commit hash.');
+            continue;
+        }
+        if (resolution.kind === 'none') {
+            continue;
+        }
+        const { hash, positions } = resolution;
+        if (parseOverrideKey(overrideKey).entry === undefined && positions.length > 1) {
+            const fieldsSet = ['description', 'body'].filter((field) => override[field] !== undefined);
+            if (fieldsSet.length > 0) {
+                const ordinalKeys = positions.map((position) => `${overrideKey}:${position}`).join(', ');
+                errors.push(`Override key '${overrideKey}' sets ${fieldsSet.join(' and ')} on a commit with several items; use ${ordinalKeys}`);
+                continue;
+            }
+        }
+        for (const position of positions) {
+            const itemId = formatItemId(hash, position);
+            const claimingKey = itemIdToKey.get(itemId);
+            if (claimingKey === undefined) {
+                itemIdToKey.set(itemId, overrideKey);
+                continue;
+            }
+            const target = position === undefined ? `commit ${hash}` : `the item at ${hash}:${position}`;
+            errors.push(`Override keys '${claimingKey}' and '${overrideKey}' both match ${target}; keep one`);
+            failedKeys.add(claimingKey);
+            failedKeys.add(overrideKey);
+        }
+    }
+    for (const [itemId, overrideKey] of itemIdToKey) {
+        if (failedKeys.has(overrideKey)) {
+            itemIdToKey.delete(itemId);
+        }
+    }
+    return { errors, itemIdToKey };
+}

package/dist/esm/attachChangelogDiagnostics.d.ts

@@ -1,4 +1,4 @@
-import type { ChangelogDiagnostics } from './buildChangelogEntries.js';
+import type { ChangelogDiagnostics } from './buildChangelogItem.js';
 import type { ReleasedPackageResult } from './types.js';
 /** Attaches a history's diagnostics to a released or skipped result, omitting each empty list. */
 export declare function attachChangelogDiagnostics(result: Pick<ReleasedPackageResult, 'malformedBlocks' | 'policyViolations' | 'undeclaredEntryTypes' | 'unroutedEntryScopes'>, diagnostics: ChangelogDiagnostics): void;

package/dist/esm/bin/release-kit.js

@@ -5,14 +5,19 @@ import { commitCommand } from "../commitCommand.js";
 import { configFlagSchema } from "../configFlagSchema.js";
 import { createGithubReleaseCommand } from "../createGithubReleaseCommand.js";
 import { enterRepoRoot } from "../enterRepoRoot.js";
+import { showInitHelp, showUpdateTemplatesHelp } from "../help/initHelp.js";
+import { showOverridesHelp, showOverridesValidateHelp } from "../help/overridesHelp.js";
 import { showPrepareHelp } from "../help/prepareHelp.js";
+import { showCommitHelp, showCreateGithubReleaseHelp, showPublishHelp, showPushHelp, showShowTagPrefixesHelp, showTagHelp, } from "../help/releaseStepsHelp.js";
+import { showSyncLabelsGenerateHelp, showSyncLabelsHelp, showSyncLabelsInitHelp, showSyncLabelsSyncHelp, } from "../help/syncLabelsHelp.js";
+import { showUsage } from "../help/usage.js";
 import { initCommand } from "../init/initCommand.js";
 import { updateTemplatesCommand } from "../init/updateTemplatesCommand.js";
 import { prepareCommand } from "../prepareCommand.js";
 import { publishCommand } from "../publishCommand.js";
 import { pushCommand } from "../pushCommand.js";
 import { resolveConfigFlag } from "../resolveConfigFlag.js";
-import { OUTPUT_STYLE_ENV_VAR, resolveStylesOrExit } from "../resolveStylesOrExit.js";
+import { resolveStylesOrExit } from "../resolveStylesOrExit.js";
 import { showTagPrefixesCommand } from "../showTagPrefixesCommand.js";
 import { generateCommand } from "../sync-labels/generateCommand.js";
 import { syncLabelsInitCommand } from "../sync-labels/initCommand.js";
@@ -20,243 +25,6 @@ import { syncLabelsCommand } from "../sync-labels/syncCommand.js";
 import { tagCommand } from "../tagCommand.js";
 import { validateOverridesCommand } from "../validateOverridesCommand.js";
 const VERSION = resolveSelfVersion(import.meta.url);
-function showUsage() {
-    console.info(`
-Usage: release-kit <command> [options]
-
-Commands:
-  prepare          Run release preparation (auto-discovers workspaces)
-  commit           Stage changes and create the release commit
-  tag              Create annotated git tags from the tags file
-  push             Push release commit and tags (one push per tag)
-  publish          Publish packages with release tags on HEAD
-  create-github-release  Create GitHub Releases from changelog.json for tags on HEAD
-  show-tag-prefixes  Show derived and declared legacy tag prefixes per workspace
-  init             Initialize release-kit in the current repository
-  update-templates Update the scaffolded workflows to the current templates
-  overrides        Manage editorial changelog overrides
-  sync-labels      Manage GitHub label synchronization
-
-Options:
-  --dry-run        Preview changes without writing files
-  --help, -h       Show this help message
-  --version, -V    Show the version number
-
-Environment:
-  ${OUTPUT_STYLE_ENV_VAR}
-                   Output style: auto (default), plain, or rich. auto prints plain,
-                   without emoji, when CI is set or the stream is not a terminal.
-`);
-}
-function showSyncLabelsHelp() {
-    console.info(`
-Usage: release-kit sync-labels <subcommand> [options]
-
-Manage GitHub label synchronization via preset and custom label definitions.
-
-Subcommands:
-  init          Scaffold caller workflow and config, then generate labels
-  generate      Regenerate .github/labels.yaml from config
-  sync          Trigger the sync-labels workflow via gh CLI
-
-Options:
-  --help, -h    Show this help message
-`);
-}
-function showSyncLabelsInitHelp() {
-    console.info(`
-Usage: release-kit sync-labels init [options]
-
-Scaffold the sync-labels caller workflow and seed the repoLabels block of
-.config/release-kit.config.ts with scope labels discovered from workspaces and
-retired packages, then generate .github/labels.yaml. When the config file already
-exists, print the block for manual paste instead of rewriting the file.
-
-Options:
-  --config <path>  Config file, relative to the current directory
-                   (default: .config/release-kit.config.ts at the repo root)
-  --dry-run        Preview changes without writing files
-  --force          Overwrite existing files instead of skipping them
-  --help, -h       Show this help message
-`);
-}
-function showSyncLabelsGenerateHelp() {
-    console.info(`
-Usage: release-kit sync-labels generate [options]
-
-Regenerate .github/labels.yaml from the repoLabels block of .config/release-kit.config.ts.
-
-Options:
-  --check          Report whether .github/labels.yaml is stale instead of writing it
-  --config <path>  Config file, relative to the current directory
-                   (default: .config/release-kit.config.ts at the repo root)
-  --help, -h       Show this help message
-`);
-}
-function showSyncLabelsSyncHelp() {
-    console.info(`
-Usage: release-kit sync-labels sync
-
-Trigger the sync-labels GitHub Actions workflow via the gh CLI.
-
-Options:
-  --help, -h    Show this help message
-`);
-}
-function showInitHelp() {
-    console.info(`
-Usage: release-kit init [options]
-
-Initialize release-kit in the current repository.
-By default, scaffolds only the GitHub Actions workflow files. When every
-package is private, skips publish.yaml and create-github-release.yaml.
-
-Options:
-  --with-config   Also scaffold .config/release-kit.config.ts
-  --force         Overwrite existing files instead of skipping them
-  --dry-run       Preview changes without writing files
-  --help, -h      Show this help message
-`);
-}
-function showUpdateTemplatesHelp() {
-    console.info(`
-Usage: release-kit update-templates [options]
-
-Update the GitHub Actions workflows that release-kit scaffolds to the templates
-of the installed version, showing what changed in each file. Creates a missing
-workflow that \`init\` would create, and refreshes sync-labels.yaml only when it
-exists. When every package is private, refreshes publish.yaml and
-create-github-release.yaml only when they exist. Keeps publish.yaml's provenance
-setting. Never touches config files.
-
-Options:
-  --dry-run       Preview changes without writing files
-  --help, -h      Show this help message
-`);
-}
-function showCommitHelp() {
-    console.info(`
-Usage: release-kit commit [options]
-
-Stage all changes and create the release commit using tags and summary
-produced by \`prepare\`.
-
-Options:
-  --dry-run     Preview the commit message without creating it
-  --help, -h    Show this help message
-`);
-}
-function showTagHelp() {
-    console.info(`
-Usage: release-kit tag [options]
-
-Create annotated git tags from the tags file produced by \`prepare\`.
-
-Options:
-  --dry-run          Preview without creating tags
-  --no-git-checks    Skip dirty working tree check
-  --help, -h         Show this help message
-`);
-}
-function showPushHelp() {
-    console.info(`
-Usage: release-kit push [options]
-
-Push the release commit and each tag individually, so that GitHub Actions
-starts a separate workflow run for each tag.
-
-Options:
-  --config <path>        Config file, relative to the current directory
-                         (default: .config/release-kit.config.ts at the repo root)
-  --dry-run              Preview without pushing
-  --tags=tag1,tag2       Only push the named tags (comma-separated, full tag names)
-  --tags-only            Skip the branch push (push tags only)
-  --help, -h             Show this help message
-`);
-}
-function showCreateGithubReleaseHelp() {
-    console.info(`
-Usage: release-kit create-github-release [options]
-
-Create GitHub Releases from changelog.json for tags on HEAD. Private
-(package.json#private) workspaces are skipped with a warning, and the command
-doesn't create a Release for them. A project tag gets a Release even when the
-root package is private.
-
-Options:
-  --config <path>        Config file, relative to the current directory
-                         (default: .config/release-kit.config.ts at the repo root)
-  --dry-run              Preview without creating releases
-  --tags=tag1,tag2       Only create releases for the named tags (comma-separated, full tag names)
-  --help, -h             Show this help message
-`);
-}
-function showShowTagPrefixesHelp() {
-    console.info(`
-Usage: release-kit show-tag-prefixes [options]
-
-Print a per-workspace table of derived tag prefixes, tag counts, and declared
-legacy tag prefixes. Reports any release-shaped tags whose prefix is neither a
-derived prefix nor declared in \`legacyIdentities\`, with a copy-pasteable
-config snippet.
-
-Options:
-  --config <path>  Config file, relative to the current directory
-                   (default: .config/release-kit.config.ts at the repo root)
-  --help, -h       Show this help message
-`);
-}
-function showOverridesHelp() {
-    console.info(`
-Usage: release-kit overrides <subcommand> [options]
-
-Manage editorial changelog overrides.
-
-Subcommands:
-  validate      Validate every \`.meta/changelog-overrides.json\` file across all scopes
-
-Options:
-  --help, -h    Show this help message
-`);
-}
-function showOverridesValidateHelp() {
-    console.info(`
-Usage: release-kit overrides validate
-
-Validate every \`.meta/changelog-overrides.json\` file across the project and per-workspace
-scopes. Reports schema/parse errors, ambiguous-prefix errors, conflicting-key errors, and
-stale-key warnings.
-
-Exit codes:
-  0    Clean: no errors, no stale keys
-  1    Stale-key warnings only (no errors)
-  2    Schema/parse, ambiguous-prefix, or conflicting-key errors (errors take precedence)
-
-Options:
-  --config <path>  Config file, relative to the current directory
-                   (default: .config/release-kit.config.ts at the repo root)
-  --help, -h       Show this help message
-`);
-}
-function showPublishHelp() {
-    console.info(`
-Usage: release-kit publish [options]
-
-Publish packages that have release tags on HEAD. Operates only on workspaces whose
-package.json#private is absent or false. Without --tags, unpublishable workspaces are
-silently filtered out. With --tags, an unpublishable tag is skipped with a warning while
-any publishable tags are still published. A project tag is never published.
-
-Options:
-  --config <path>        Config file, relative to the current directory
-                         (default: .config/release-kit.config.ts at the repo root)
-  --dry-run              Preview without publishing
-  --no-git-checks        Skip the clean-working-tree check
-  --tags=tag1,tag2       Only publish the named tags (comma-separated, full tag names)
-  --provenance           Generate provenance statement (requires OIDC, not supported by classic yarn)
-  --help, -h             Show this help message
-`);
-}
 function enterRepoRootOrExit() {
     try {
         return enterRepoRoot();

package/dist/esm/buildChangelogEntries.d.ts

@@ -1,14 +1,7 @@
+import { type ChangelogDiagnostics } from './buildChangelogItem.js';
 import { type RawCommit } from './enumerateReleaseWindows.js';
 import type { GenerateChangelogOptions } from './generateChangelogs.js';
-import type { ChangelogEntry, ChangelogSection, MalformedChangeRecordBlock, PolicyViolation, ReleaseSettings, ReleaseType, UndeclaredEntryType, UnroutedEntryScope } from './types.js';
-/**
- * Strips a section title down to its bare name.
- *
- * 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.
- */
-export declare function stripGroupDecorations(group: string): string;
+import type { ChangelogEntry, ChangelogSection, ReleaseSettings, ReleaseType } from './types.js';
 /**
  * Builds structured changelog entries from the release windows of git history, naming the unreleased window `tag`.
  *
@@ -18,18 +11,6 @@ export declare function buildChangelogEntries(config: ReleaseHistoryConfig, tag:
     entries: ChangelogEntry[];
     diagnostics: ChangelogDiagnostics;
 };
-/** What reading the unreleased window reports beyond its items. */
-export interface ChangelogDiagnostics {
-    malformedBlocks: MalformedChangeRecordBlock[];
-    /** 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.
@@ -40,8 +21,6 @@ export interface ChangelogDiagnostics {
  * 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<ReleaseSettings, '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. */
@@ -50,6 +29,24 @@ export interface ReleaseHistory {
     releasedEntries: ChangelogEntry[];
     unreleased: UnreleasedWindowReading;
 }
+/** The configuration that `readReleaseHistory` reads. */
+export type ReleaseHistoryConfig = Pick<ReleaseSettings, 'breakingPolicies' | 'changelogJson' | 'scopeAliases' | 'versionPatterns' | 'workTypes'>;
+/**
+ * Strips a section title down to its bare name.
+ *
+ * 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.
+ */
+export declare function stripGroupDecorations(group: string): string;
+/** 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[];
 /** 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 doesn't yield any item. */
@@ -68,11 +65,3 @@ export interface UnreleasedWindowReading {
      */
     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[];