@williamthorsen/release-kit 11.0.0 → 13.0.0

package/dist/esm/init/initCommand.js

@@ -3,15 +3,7 @@ import { describeError } from '@williamthorsen/toolbelt.errors';
 import { hasPackageJson, isGitRepo, usesPnpm } from "./checks.js";
 import { detectRepoType } from "./detectRepoType.js";
 import { scaffoldFiles } from "./scaffold.js";
-function runRequiredCheck(label, result, styles) {
-    if (result.ok) {
-        printSuccess(label, styles.stdout);
-        return true;
-    }
-    printError(result.message ?? `${label} failed`, styles.stderr);
-    return false;
-}
-function checkEligibility(styles) {
+export function checkEligibility(styles) {
     printStep('Checking eligibility');
     if (!runRequiredCheck('Git repository detected', isGitRepo(), styles))
         return false;
@@ -62,14 +54,22 @@ export function initCommand({ dryRun, force, styles, withConfig }) {
     }
     printStep('Next steps');
     const configHint = withConfig
-        ? '1. (Optional) Customize .config/release-kit.config.ts and .config/git-cliff.toml.'
+        ? '1. (Optional) Customize .config/release-kit.config.ts.'
         : '1. (Optional) Run again with --with-config to scaffold config files.';
     console.info(`
   ${configHint}
-  2. If this is a public repo, set provenance: true in .github/workflows/publish.yaml.
+  2. If this is a private repo, remove provenance: true from .github/workflows/publish.yaml.
   3. Test by running: npx @williamthorsen/release-kit prepare --dry-run
   4. Commit the generated files.
   5. Register each package as a trusted publisher on npmjs.com.
 `);
     return 0;
 }
+function runRequiredCheck(label, result, styles) {
+    if (result.ok) {
+        printSuccess(label, styles.stdout);
+        return true;
+    }
+    printError(result.message ?? `${label} failed`, styles.stderr);
+    return false;
+}

package/dist/esm/init/parseJsonRecord.d.ts

@@ -1,5 +1,2 @@
-/**
- * Parse a JSON string and return the result if it is a plain object (Record<string, unknown>).
- * Returns `undefined` if parsing fails or the result is not a plain object.
- */
+/** Parses a JSON string, returning the result if it is a plain object and `undefined` otherwise. */
 export declare function parseJsonRecord(raw: string): Record<string, unknown> | undefined;

package/dist/esm/init/scaffold.d.ts

@@ -6,8 +6,6 @@ interface ScaffoldOptions {
     overwrite: boolean;
     withConfig: boolean;
 }
-/** Copy the bundled cliff.toml.template to `.config/git-cliff.toml` in the target repo. */
-export declare function copyCliffTemplate(dryRun: boolean, overwrite: boolean): WriteResult;
-/** Scaffold release-kit files for the target repo. Returns a result for each file attempted. */
+/** Scaffolds release-kit files for the target repo, returning a result for each file attempted. */
 export declare function scaffoldFiles({ repoType, dryRun, overwrite, withConfig }: ScaffoldOptions): WriteResult[];
 export {};

package/dist/esm/init/scaffold.js

@@ -1,33 +1,5 @@
-import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { findPackageRoot, writeFileWithCheck } from '@williamthorsen/nmr-core';
-import { describeError } from '@williamthorsen/toolbelt.errors';
+import { writeFileWithCheck } from '@williamthorsen/nmr-core';
 import { createGithubReleaseWorkflow, publishWorkflow, releaseConfigScript, releaseWorkflow } from "./templates.js";
-export function copyCliffTemplate(dryRun, overwrite) {
-    const destPath = '.config/git-cliff.toml';
-    let root;
-    try {
-        root = findPackageRoot(import.meta.url);
-    }
-    catch (error) {
-        const message = describeError(error);
-        return { filePath: destPath, outcome: 'failed', error: `Failed to resolve package root: ${message}` };
-    }
-    const templatePath = resolve(root, 'cliff.toml.template');
-    let content;
-    try {
-        content = readFileSync(templatePath, 'utf8');
-    }
-    catch (error) {
-        const message = describeError(error);
-        return {
-            filePath: destPath,
-            outcome: 'failed',
-            error: `Failed to read bundled template at ${templatePath}: ${message}`,
-        };
-    }
-    return writeFileWithCheck(destPath, content, { dryRun, overwrite });
-}
 export function scaffoldFiles({ repoType, dryRun, overwrite, withConfig }) {
     const results = [
         writeFileWithCheck('.github/workflows/create-github-release.yaml', createGithubReleaseWorkflow(repoType), {
@@ -38,7 +10,7 @@ export function scaffoldFiles({ repoType, dryRun, overwrite, withConfig }) {
         writeFileWithCheck('.github/workflows/release.yaml', releaseWorkflow(repoType), { dryRun, overwrite }),
     ];
     if (withConfig) {
-        results.push(writeFileWithCheck('.config/release-kit.config.ts', releaseConfigScript(repoType), { dryRun, overwrite }), copyCliffTemplate(dryRun, overwrite));
+        results.push(writeFileWithCheck('.config/release-kit.config.ts', releaseConfigScript(repoType), { dryRun, overwrite }));
     }
     return results;
 }

package/dist/esm/init/templates.d.ts

@@ -1,18 +1,16 @@
 import type { RepoType } from './detectRepoType.js';
-/** Generate the `.config/release-kit.config.ts` starter config with TODOs for customization. */
+/** Generates the `.config/release-kit.config.ts` starter config, with commented-out options to customize. */
 export declare function releaseConfigScript(repoType: RepoType): string;
 /**
- * Generate the publish.yaml GitHub Actions entry-point workflow.
+ * Generates the publish.yaml GitHub Actions entry-point workflow.
  *
- * The `permissions` block is present for explicitness; the reusable workflow declares its own
- * permissions, so GitHub uses those rather than the caller's block.
- */
-export declare function publishWorkflow(repoType: RepoType): string;
-/**
- * Generate the create-github-release.yaml GitHub Actions caller workflow.
- *
- * Fires on tag push and delegates to the reusable workflow under `contents: write`.
+ * The caller's `permissions` block caps what the reusable workflow receives, so it must grant the `id-token: write`
+ * that OIDC publishing needs. `provenance: false` omits the provenance input, which a private repo cannot use.
  */
+export declare function publishWorkflow(repoType: RepoType, { provenance }?: {
+    provenance?: boolean;
+}): string;
+/** Generates the create-github-release.yaml GitHub Actions caller workflow. */
 export declare function createGithubReleaseWorkflow(repoType: RepoType): string;
-/** Generate the release.yaml GitHub Actions workflow. */
+/** Generates the release.yaml GitHub Actions workflow. */
 export declare function releaseWorkflow(repoType: RepoType): string;

package/dist/esm/init/templates.js

@@ -39,7 +39,7 @@ export default defineConfig({
 });
 `;
 }
-export function publishWorkflow(repoType) {
+export function publishWorkflow(repoType, { provenance = true } = {}) {
     const tagPattern = repoType === 'monorepo' ? "'*-v[0-9]*.[0-9]*.[0-9]*'" : "'v[0-9]*.[0-9]*.[0-9]*'";
     return `# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
 name: Publish
@@ -57,8 +57,7 @@ jobs:
   publish:
     uses: williamthorsen/node-monorepo-tools/.github/workflows/publish.reusable.yaml@workflow/publish-v1
     with:
-      provenance: true
-      tags: \${{ github.ref_name }}
+${provenance ? '      provenance: true\n' : ''}      tags: \${{ github.ref_name }}
 `;
 }
 export function createGithubReleaseWorkflow(repoType) {
@@ -94,16 +93,17 @@ on:
         required: false
         type: string
       bump:
-        description: 'Override version bump type (leave empty to auto-detect from commits)'
+        description: 'Version bump type (auto detects it from commits)'
         required: false
         type: choice
+        default: auto
         options:
-          - ''
+          - auto
           - patch
           - minor
           - major
       force:
-        description: 'Force a release even when no commits or no bump-worthy commits exist (defaults to patch; combine with --bump for a different level)'
+        description: 'Force a release even when there are not any commits, or any bump-worthy commits, since the last release (defaults to patch; combine with --bump for a different level)'
         required: false
         type: boolean
         default: false
@@ -117,7 +117,7 @@ jobs:
     uses: williamthorsen/node-monorepo-tools/.github/workflows/release.reusable.yaml@workflow/release-v1
     with:
       only: \${{ inputs.only }}
-      bump: \${{ inputs.bump }}
+      bump: \${{ inputs.bump != 'auto' && inputs.bump || '' }}
       force: \${{ inputs.force }}
 `;
     }
@@ -128,16 +128,17 @@ on:
   workflow_dispatch:
     inputs:
       bump:
-        description: 'Override version bump type (leave empty to auto-detect from commits)'
+        description: 'Version bump type (auto detects it from commits)'
         required: false
         type: choice
+        default: auto
         options:
-          - ''
+          - auto
           - patch
           - minor
           - major
       force:
-        description: 'Force a release even when no commits or no bump-worthy commits exist (defaults to patch; combine with --bump for a different level)'
+        description: 'Force a release even when there are not any commits, or any bump-worthy commits, since the last release (defaults to patch; combine with --bump for a different level)'
         required: false
         type: boolean
         default: false
@@ -150,7 +151,7 @@ jobs:
   release:
     uses: williamthorsen/node-monorepo-tools/.github/workflows/release.reusable.yaml@workflow/release-v1
     with:
-      bump: \${{ inputs.bump }}
+      bump: \${{ inputs.bump != 'auto' && inputs.bump || '' }}
       force: \${{ inputs.force }}
 `;
 }

package/dist/esm/init/updateTemplatesCommand.d.ts

@@ -0,0 +1,13 @@
+import { type StreamStyles } from '@williamthorsen/nmr-core';
+interface UpdateTemplatesOptions {
+    dryRun: boolean;
+    styles: StreamStyles;
+}
+/**
+ * Runs the `release-kit update-templates` command and returns the process exit code.
+ *
+ * Brings each workflow that release-kit scaffolds up to date with the installed templates. The opt-in
+ * `sync-labels.yaml` is refreshed only when it exists, and config files are never read or written.
+ */
+export declare function updateTemplatesCommand({ dryRun, styles }: UpdateTemplatesOptions): number;
+export {};

package/dist/esm/init/updateTemplatesCommand.js

@@ -0,0 +1,64 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { printError, printStep, printSuccess, reportTemplateUpdate, updateManagedFile, } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { syncLabelsWorkflow } from "../sync-labels/templates.js";
+import { detectRepoType } from "./detectRepoType.js";
+import { hasProvenance } from "./hasProvenance.js";
+import { checkEligibility } from "./initCommand.js";
+import { createGithubReleaseWorkflow, publishWorkflow, releaseWorkflow } from "./templates.js";
+const PUBLISH_WORKFLOW_PATH = '.github/workflows/publish.yaml';
+const SYNC_LABELS_WORKFLOW_PATH = '.github/workflows/sync-labels.yaml';
+export function updateTemplatesCommand({ dryRun, styles }) {
+    if (dryRun) {
+        console.info('[dry-run mode]');
+    }
+    let eligible;
+    try {
+        eligible = checkEligibility(styles);
+    }
+    catch (error) {
+        printError(`Eligibility check failed: ${describeError(error)}`, styles.stderr);
+        return 1;
+    }
+    if (!eligible)
+        return 1;
+    printStep('Detecting repo type');
+    let repoType;
+    try {
+        repoType = detectRepoType();
+    }
+    catch (error) {
+        printError(`Failed to detect repo type: ${describeError(error)}`, styles.stderr);
+        return 1;
+    }
+    printSuccess(`Detected: ${repoType}`, styles.stdout);
+    printStep('Updating workflows');
+    let results;
+    try {
+        results = buildManagedFiles(repoType).map(([filePath, content]) => updateManagedFile(filePath, content, { dryRun }));
+    }
+    catch (error) {
+        printError(`Failed to render workflows: ${describeError(error)}`, styles.stderr);
+        return 1;
+    }
+    for (const result of results) {
+        reportTemplateUpdate(result, dryRun, styles);
+    }
+    return results.some((result) => result.outcome === 'failed') ? 1 : 0;
+}
+function buildManagedFiles(repoType) {
+    const files = [
+        ['.github/workflows/create-github-release.yaml', createGithubReleaseWorkflow(repoType)],
+        [PUBLISH_WORKFLOW_PATH, publishWorkflow(repoType, { provenance: readProvenanceSetting() })],
+        ['.github/workflows/release.yaml', releaseWorkflow(repoType)],
+    ];
+    if (existsSync(SYNC_LABELS_WORKFLOW_PATH)) {
+        files.push([SYNC_LABELS_WORKFLOW_PATH, syncLabelsWorkflow()]);
+    }
+    return files;
+}
+function readProvenanceSetting() {
+    if (!existsSync(PUBLISH_WORKFLOW_PATH))
+        return true;
+    return hasProvenance(readFileSync(PUBLISH_WORKFLOW_PATH, 'utf8'));
+}

package/dist/esm/injectReleaseNotesIntoReadme.d.ts

@@ -3,15 +3,11 @@ import type { ChangelogEntry } from './types.js';
 export interface RenderedInjectedReadme {
     /** The README with the release-notes section injected at the marker position. */
     injectedReadme: string;
-    /**
-     * The standalone release-notes markdown for the target version (trimmed), prefixed with a
-     * labeled `## Release notes — v{version} ({date})` heading so the file is self-identifying.
-     * The GitHub-release body is rendered separately (without this heading) by `createGithubRelease`.
-     */
+    /** The standalone release-notes markdown for the target version, trimmed and led by a `## Release notes` heading. */
     releaseNotesMarkdown: string;
 }
 /**
- * Discriminated reason no release notes were rendered for a tag.
+ * Discriminated reason why release notes were not rendered for a tag.
  *
  * Shares the vocabulary of `CreateReleaseSkipReason` in `createGithubRelease.ts`, which classifies
  * the same two conditions on the GitHub-release path.
@@ -30,11 +26,11 @@ export type RenderInjectedReadmeResult = {
  * Renders a README with release notes injected at the marker position, and the standalone
  * release-notes markdown, from an already-loaded README string and an in-memory entry set.
  *
- * This is the pure rendering core: it reads nothing, writes nothing, and reports nothing, so a
- * caller holding entries a release has computed but not yet written gets the same result as one
- * rendering from a saved file, and each caller words a skip for its own output.
+ * This is the pure rendering core: It reads nothing, writes nothing, and reports nothing, so a
+ * caller that has entries that a release has computed but not yet written gets the same result as
+ * one rendering from a saved file, and each caller words a skip for its own output.
  *
- * Carries the version on a skip because both callers name it in their message and only this
+ * Returns the version on a skip because both callers name it in their message and only this
  * function has derived it from the tag.
  */
 export declare function renderInjectedReadmeFromEntries(readme: string, entries: readonly ChangelogEntry[], tag: string, sectionOrder?: string[]): RenderInjectedReadmeResult;
@@ -42,16 +38,15 @@ export declare function renderInjectedReadmeFromEntries(readme: string, entries:
  * Path-taking wrapper over {@link renderInjectedReadmeFromEntries} for callers rendering from a
  * saved `changelog.json`, such as the publish-time injection flow.
  *
- * Adds the two skip conditions that only a file can present: the changelog is missing, or it does
- * not parse. Warns on every skip, its own and the renderer's alike, because the publish path has
- * no other channel for the message.
+ * Adds the two skip conditions that only a file can present: The changelog is missing, or it does
+ * not parse. Warns on every skip, its own and the renderer's alike, because the publish path does
+ * not have any other channel for the message.
  */
 export declare function renderInjectedReadme(readme: string, changelogJsonPath: string, tag: string, sectionOrder?: string[]): RenderedInjectedReadme | undefined;
 /**
- * Inject release notes into a README and return the original content for restoration.
- *
- * Returns the original README content, or `undefined` if injection was skipped.
+ * Injects release notes into a README file, returning the original content for restoration, or `undefined` when
+ * injection was skipped.
  */
 export declare function injectReleaseNotesIntoReadme(readmePath: string, changelogJsonPath: string, tag: string, sectionOrder?: string[]): string | undefined;
-/** Find the README file in a workspace directory. */
+/** Returns the path of a workspace's `README.md`, or `undefined` when it has none. */
 export declare function resolveReadmePath(workspacePath: string): string | undefined;

package/dist/esm/injectSection.d.ts

@@ -1,7 +1,7 @@
 /**
- * Replace or insert a delimited section in file content.
+ * Replaces or inserts a delimited section in file content.
  *
- * When markers exist, replaces the content between them. When absent, prepends the section
- * (with markers) at the top of the content. The function is pure — no file I/O.
+ * When both markers exist in order, replaces the content between them. Otherwise, prepends the
+ * section (with markers) at the top of the content.
  */
 export declare function injectSection(content: string, key: string, injection: string): string;

package/dist/esm/loadConfig.d.ts

@@ -2,11 +2,12 @@ import type { MonorepoReleaseConfig, ReleaseConfig, ReleaseKitConfig, WorkTypeCo
 /** Path of the root `package.json` consulted when validating a `project` block. */
 export declare const ROOT_PACKAGE_JSON_PATH = "package.json";
 /**
- * Read the root `package.json` and return its `version` field.
+ * Reads the root `package.json` and returns its `version` field.
  *
  * Returns `{ exists: false }` when the file is missing, `{ exists: true, version: undefined }`
- * when the file exists but has no `version` field, and `{ exists: true, version }` when both
- * are present. The caller (`mergeMonorepoConfig`) decides whether the situation is an error.
+ * when the file exists but does not have a `version` field, and `{ exists: true, version }`
+ * when both are present; `mergeMonorepoConfig` decides whether the situation is an error.
+ * Throws when the file cannot be read or parsed.
  */
 export declare function readRootPackageVersion(): {
     exists: boolean;
@@ -17,16 +18,17 @@ export declare const CONFIG_FILE_PATH = ".config/release-kit.config.ts";
 /**
  * Loads the config file, returning the raw config object.
  *
- * `configPath` is resolved against the working directory and defaults to `CONFIG_FILE_PATH`. An absent default
- * path returns `undefined`, because a repo that declares no config is a supported state; an absent named path
+ * `configPath` is resolved against the working directory, which the CLI sets to the repo root, and defaults to
+ * `CONFIG_FILE_PATH`. The CLI resolves a `--config` value to an absolute path before passing it. An absent default
+ * path returns `undefined`, because a repo that does not declare a config is a supported state; an absent named path
  * throws, because the caller asked for that file by name. Also throws when the file exists but cannot be
  * imported, or exports neither a default nor a named `config`.
  */
 export declare function loadConfig(configPath?: string): Promise<unknown>;
 /**
  * Information about the root `package.json` passed into `mergeMonorepoConfig` when a
- * `project` block is configured. The async I/O lives in `readRootPackageVersion`; this
- * function stays a pure transformation.
+ * `project` block is configured. `readRootPackageVersion` performs the read, so that
+ * `mergeMonorepoConfig` does not perform any I/O.
  */
 export interface RootPackageInfo {
     exists: boolean;
@@ -36,12 +38,12 @@ export interface RootPackageInfo {
  * Resolves a final monorepo config from discovered workspaces and an optional user config overlay.
  *
  * Merging rules:
- * - `workspaces`: match overlay entries by `dir` against discovered list; `shouldExclude: true`
+ * - `workspaces`: Match overlay entries by `dir` against discovered list; `shouldExclude: true`
  *   removes the workspace; unlisted packages keep defaults.
- * - `workTypes`: shallow merge — consumer entries override or add to defaults by key.
- * - `versionPatterns`: consumer value replaces defaults entirely.
- * - `formatCommand`, `cliffConfigPath`, `scopeAliases`: consumer value wins.
- * - `project`: present iff `userConfig.project` is declared. Resolves `tagPrefix` to
+ * - `workTypes`: Shallow merge; consumer entries override or add to defaults by key.
+ * - `versionPatterns`: Consumer value replaces defaults entirely.
+ * - Pass-through fields (see `applyOptionalPassthroughFields`): Consumer value wins.
+ * - `project`: Present iff `userConfig.project` is declared. Resolves `tagPrefix` to
  *   `DEFAULT_PROJECT_TAG_PREFIX` and `paths` to the union of the retained workspaces' `paths`
  *   when omitted. Requires `rootPackage` to be passed and to contain a valid `version` field;
  *   throws otherwise. The resolved prefix is included in the strict-prefix collision check
@@ -51,13 +53,13 @@ export declare function mergeMonorepoConfig(discoveredPaths: string[], userConfi
 /**
  * Resolves a final single-package config from an optional user config overlay.
  *
- * Rejects a configured `project` block: project-level releases are a monorepo-only feature,
+ * Rejects a configured `project` block: Project-level releases are a monorepo-only feature,
  * since the implicit "all non-excluded workspaces contribute" rule is meaningless in a
  * single-package repo.
  */
 export declare function mergeSinglePackageConfig(userConfig: ReleaseKitConfig | undefined): ReleaseConfig;
 /**
- * Merge consumer work-type overrides onto `DEFAULT_WORK_TYPES`.
+ * Merges consumer work-type overrides onto `DEFAULT_WORK_TYPES`.
  *
  * Preserves the declaration order of defaults; net-new consumer keys append at the end.
  */

package/dist/esm/loadConfig.js

@@ -99,9 +99,6 @@ function applyOptionalPassthroughFields(result, userConfig) {
     if (userConfig?.formatCommand !== undefined) {
         result.formatCommand = userConfig.formatCommand;
     }
-    if (userConfig?.cliffConfigPath !== undefined) {
-        result.cliffConfigPath = userConfig.cliffConfigPath;
-    }
     if (userConfig?.scopeAliases !== undefined) {
         result.scopeAliases = userConfig.scopeAliases;
     }
@@ -172,7 +169,7 @@ function resolveProjectConfig(userProject, rootPackage, workspaces) {
         throw new Error(`project block requires a root ${ROOT_PACKAGE_JSON_PATH}; create one with a 'version' field at the repo root`);
     }
     if (rootPackage.version === undefined) {
-        throw new Error(`project block requires root ${ROOT_PACKAGE_JSON_PATH} to have a 'version' field; add a 'version' field to your root package.json`);
+        throw new Error(`project block requires root ${ROOT_PACKAGE_JSON_PATH} to have a 'version' field; add a 'version' field to the root package.json`);
     }
     return {
         paths: userProject.paths ?? workspaces.flatMap((workspace) => workspace.paths),
@@ -215,7 +212,7 @@ function assertNoTagPrefixCollisions(workspaces, retiredPackages, project) {
             if (isPrefixCollision(a.prefix, b.prefix)) {
                 throw new Error(`Tag prefix collision: '${a.prefix}' (${a.label}) and '${b.prefix}' (${b.label}). ` +
                     'One prefix is identical to or a strict prefix of the other; ' +
-                    'this would cause `git describe --match=<prefix>*` to return cross-matches.');
+                    'a tag under the longer prefix can then match the shorter one and be counted among its releases.');
             }
         }
     }

package/dist/esm/loadValidatedConfig.d.ts

@@ -1,7 +1,7 @@
 import { type OutputStyle } from '@williamthorsen/nmr-core';
 import type { ReleaseKitConfig } from './types.js';
 /**
- * Why a config file could not be used: the import threw, or the contents failed the schema.
+ * Why a config file could not be used: The import threw, or the contents failed the schema.
  *
  * The distinction exists so that a caller can render the two differently. Every caller aborts on either.
  */
@@ -13,12 +13,12 @@ export type ConfigProblem = {
     errors: string[];
 };
 /**
- * Outcome of loading and validating the consumer config file. `missing` is not an error
- * here — whether an absent config file is one is the caller's call.
+ * Outcome of loading and validating the consumer config file. `missing` is not an error here; the caller decides
+ * whether an absent config file is one.
  *
- * `configFilePath` names the file the run read: the caller's `configPath`, or `CONFIG_FILE_PATH` when none was
- * given. It stays relative to the working directory, so a message or a generated artifact that splices it reads
- * the same on every machine.
+ * `configFilePath` names the file that the run read: the caller's `configPath`, or `CONFIG_FILE_PATH` when none was
+ * given. The default stays relative to the working directory, so a message or a generated artifact that includes it
+ * reads the same on every machine.
  */
 export type LoadValidatedConfigResult = {
     status: 'invalid';
@@ -36,25 +36,22 @@ export type LoadValidatedConfigResult = {
 /**
  * Loads the consumer config file and validates it against the shared schema, returning the outcome.
  *
- * Writes nothing to any stream: the caller picks the sink, which is what lets a command that must stay silent
- * reuse this loader. `reportConfigProblem` and `reportConfigWarnings` render the stderr form.
+ * Writes nothing to any stream: The caller picks the sink, which lets a command that must stay silent reuse this
+ * loader. `reportConfigProblem` and `reportConfigWarnings` render the stderr form.
  *
- * `configPath` defaults to `CONFIG_FILE_PATH`. A named path that does not exist is a load failure, so it reports
- * as `invalid` rather than `missing`.
+ * `configPath` defaults to `CONFIG_FILE_PATH`. A named path that does not exist is a load failure, so this function
+ * reports it as `invalid` rather than `missing`.
  */
 export declare function loadValidatedConfig(configPath?: string): Promise<LoadValidatedConfigResult>;
 /**
- * Loads and validates the config, reporting the problem and exiting 1 when it is unusable, so that a command
- * whose later work may never reach a loader still fails on a config that does.
+ * Loads and validates the config for a CLI command, returning it, or `undefined` when the default config file does
+ * not exist.
  *
- * An absent default config returns cleanly, which is what keeps a repo that declares no config a supported state.
- * Reports problems but never warnings: the command's own later load stays the single place that emits those, so
- * a warning is not printed twice.
- *
- * The second load costs nothing: `import()` caches by URL and `validateConfig` is pure.
+ * Reports an unusable config to stderr and exits 1, whether the file failed to load or failed validation, and
+ * whether it was named by the caller or the default one. Validation warnings print to stderr.
  */
-export declare function assertConfigUsable(stderrStyle: OutputStyle, configPath?: string): Promise<void>;
-/** Writes a config problem to stderr in the form every CLI command uses. */
+export declare function loadUsableConfig(stderrStyle: OutputStyle, configPath?: string): Promise<ReleaseKitConfig | undefined>;
+/** Writes a config problem to stderr in the form used by every CLI command. */
 export declare function reportConfigProblem(problem: ConfigProblem, stderrStyle: OutputStyle): void;
 /** Writes validation warnings to stderr as indented status lines. */
 export declare function reportConfigWarnings(warnings: readonly string[], stderrStyle: OutputStyle): void;

package/dist/esm/loadValidatedConfig.js

@@ -20,12 +20,17 @@ export async function loadValidatedConfig(configPath) {
     }
     return { status: 'ok', config, configFilePath, warnings };
 }
-export async function assertConfigUsable(stderrStyle, configPath) {
+export async function loadUsableConfig(stderrStyle, configPath) {
     const result = await loadValidatedConfig(configPath);
     if (result.status === 'invalid') {
         reportConfigProblem(result.problem, stderrStyle);
         process.exit(1);
     }
+    if (result.status === 'missing') {
+        return undefined;
+    }
+    reportConfigWarnings(result.warnings, stderrStyle);
+    return result.config;
 }
 export function reportConfigProblem(problem, stderrStyle) {
     if (problem.kind === 'load') {

package/dist/esm/packsPath.d.ts

@@ -1,15 +1,15 @@
 /**
  * Reports whether npm would place `path` in the published tarball, given a package.json `files` value.
  *
- * An absent or malformed `files` value packs everything, so it reports `true`; an empty array packs nothing
- * beyond the files npm always includes, so it reports `false`. An entry naming an ancestor directory covers
- * everything beneath it, which is how `files: ["dist/*"]` ships `dist/esm/index.js`, so every ancestor prefix
- * of `path` is tested rather than `path` alone.
+ * npm packs everything when the `files` value is absent or malformed, and `packsPath` reports `true`; for an empty
+ * array, npm packs only the files that it always includes, and `packsPath` reports `false`. An entry naming an
+ * ancestor directory covers everything beneath it, which is how `files: ["dist/*"]` includes `dist/esm/index.js`, so
+ * `packsPath` tests every ancestor prefix of `path` rather than `path` alone.
  *
- * Two approximations of npm's packing rules remain, both failing toward a silent pass: a negation entry
- * (`!dist/*.map`) never counts toward inclusion, because gitignore-style ordered negation is not modeled; and a
- * repo controlling its tarball through `.npmignore` alone declares no `files` field, so it reports `true`
- * without the ignore file being read. For a check that warns about an omission, a missed report costs less than
- * a false one.
+ * Two approximations of npm's packing rules remain, both failing toward a silent pass: A negation entry
+ * (`!dist/*.map`) never counts toward inclusion, because gitignore-style ordered negation is not modeled; and for a
+ * repo controlling its tarball through `.npmignore` alone, which does not declare a `files` field, `packsPath`
+ * reports `true` without reading the ignore file. For a check that warns about an omission, a missed report does
+ * less harm than a false one.
  */
 export declare function packsPath(filesField: unknown, path: string): boolean;

package/dist/esm/parseChangeRecordBlock.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Reads the last `change-record` block in a commit message into the change entries that it records.
+ *
+ * The block's grammar is codeassembly's `change-record.md`: a fence whose info string is exactly `change-record`,
+ * containing a YAML mapping. A merge commit's block contains `entries` plus the top-level `pr_number` and `ticket_ref`.
+ * A key that the grammar does not declare is ignored, and a declared key whose value is null reads as absent. Any
+ * defect makes the whole block malformed; `parseChangeRecordBlock` does not salvage any entry from a defective list.
+ */
+export declare function parseChangeRecordBlock(message: string): ChangeRecordBlockReading;
+/**
+ * Removes every `change-record` block from a message, fences included. A block that never closes runs to the end of
+ * the message, as a Markdown renderer reads it.
+ */
+export declare function stripChangeRecordBlocks(message: string): string;
+/**
+ * What a commit's last `change-record` block reads as: absent, malformed with the defect named, or the entries that
+ * it records with the merge's pull-request number and ticket reference when the block declares them.
+ */
+export type ChangeRecordBlockReading = {
+    kind: 'absent';
+} | {
+    kind: 'malformed';
+    reason: string;
+} | {
+    kind: 'read';
+    entries: ChangeRecordEntry[];
+    prNumber?: number;
+    ticketRef?: string;
+};
+/** One outcome of a change, as the block records it. */
+export interface ChangeRecordEntry {
+    breaking: boolean;
+    migration?: string;
+    scopes: string[];
+    text: string;
+    type: string;
+}