@williamthorsen/release-kit 12.0.0 → 13.0.0

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`, `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

@@ -169,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),
@@ -212,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; ' +
-                    'a tag under the longer prefix can then match the shorter one, whose releases would absorb it.');
+                    '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

@@ -2,9 +2,9 @@
  * 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 carries `entries` plus the top-level `pr_number` and `ticket_ref`.
+ * 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; no entry is salvaged from a defective list.
+ * defect makes the whole block malformed; `parseChangeRecordBlock` does not salvage any entry from a defective list.
  */
 export declare function parseChangeRecordBlock(message: string): ChangeRecordBlockReading;
 /**

package/dist/esm/parseCommitMessage.d.ts

@@ -1,14 +1,5 @@
+import { type BreakingPolicy, type ChangeRecord } from '@williamthorsen/change-grammar';
 import type { Commit, ParsedCommit, WorkTypeConfig } from './types.js';
-/** Regex patterns stripped from the start of commit messages before parsing. */
-export declare const COMMIT_PREPROCESSOR_PATTERNS: readonly RegExp[];
-/**
- * Regex source for the pipe-prefixed scope atom (the `web` in `web|feat: ...`).
- *
- * Deliberately permissive: `*` is the sanctioned structural scope for changes spanning every
- * workspace, so the atom admits any run of non-pipe characters rather than word characters.
- * Exported because `buildChangelogEntries.ts` builds its breaking-marker pattern from the same atom.
- */
-export declare const PIPE_SCOPE_SOURCE = "[^|]+";
 /**
  * Surface where a breaking-policy violation was detected: a subject's `!`, a `BREAKING CHANGE:` footer, or a
  * change-record entry's `breaking`.
@@ -17,40 +8,34 @@ export type PolicyViolationSurface = 'prefix' | 'body' | 'entry';
 /**
  * Callback invoked when `parseCommitMessage` detects a `!`-policy violation.
  *
- * The parser warns and continues on a violation, so legacy log entries don't block releases.
- * `readReleaseHistory` collects the invocations for the unreleased window, and the release
- * report lists them.
+ * Parsing continues after a violation so that an older commit in the log does not block a release.
  */
 export type PolicyViolationHandler = (commit: Commit, type: string, surface: PolicyViolationSurface) => void;
 /** Optional configuration for `parseCommitMessage` beyond the core inputs. */
 export interface ParseCommitMessageOptions {
-    /**
-     * Per-type breaking-policy lookup keyed by canonical type name. Missing entries are
-     * treated as `'optional'` for backward compatibility with consumers that have not
-     * supplied policies.
-     */
-    breakingPolicies?: Record<string, 'forbidden' | 'optional' | 'required'>;
+    /** Per-type breaking-policy lookup keyed by canonical type name; a type without an entry is `'optional'`. */
+    breakingPolicies?: Record<string, BreakingPolicy>;
     /** Receives policy-violation notifications. See {@link PolicyViolationHandler}. */
     onPolicyViolation?: PolicyViolationHandler;
 }
 /**
- * Parse a commit message into structured metadata.
+ * Parses a commit message into structured metadata.
  *
- * Supports three formats:
- * - `type: description`
- * - `scope|type: description` (pipe-prefixed scope)
- * - `type(scope): description` (conventional commit parenthesized scope)
+ * Reads the first line through change-grammar's `pipedScope` template (`scope|type: description`, the scope optional),
+ * then its `conventionalCommits` template (`type(scope): description`), and takes the first match. Types and aliases
+ * resolve against `workTypes`, ignoring case; scope aliases resolve when a `scopeAliases` map is provided. Detects
+ * breaking changes via the subject's `!` or `BREAKING CHANGE:` in the message.
  *
- * Resolves aliases (e.g., `feature` → `feat`) using the provided work-type configs and the
- * canonical aliases list. Resolves scope aliases when a `scopeAliases` map is provided.
- * Detects breaking changes via `type!:` or `BREAKING CHANGE:` in the message.
- *
- * `!`-policy enforcement is **release-time tolerant**: when the resolved type's policy
+ * `!`-policy enforcement is **release-time tolerant**: When the resolved type's policy
  * forbids `!`, the marker is dropped from the parse (`breaking: false`) and
- * `onPolicyViolation` is invoked. When the policy requires `!`, a bare type triggers the
- * same warning path.
+ * `onPolicyViolation` is invoked.
  */
 export declare function parseCommitMessage(message: string, hash: string, workTypes: Record<string, WorkTypeConfig>, scopeAliases?: Record<string, string>, options?: ParseCommitMessageOptions): ParsedCommit | undefined;
+/**
+ * Reads a commit subject into a change record through the templates that release-kit accepts, before any breaking
+ * policy applies. The engine strips ticket prefixes.
+ */
+export declare function parseSubject(subject: string, workTypes: Record<string, WorkTypeConfig>): ChangeRecord | undefined;
 /** Inputs for {@link evaluateBreakingPolicy}. */
 export interface BreakingPolicyInputs {
     commit: Commit;
@@ -58,7 +43,7 @@ export interface BreakingPolicyInputs {
     /** Whether the marker that `prefixSurface` names is present. */
     hasPrefixBreaking: boolean;
     hasFooterBreaking: boolean;
-    policy: 'forbidden' | 'optional' | 'required';
+    policy: BreakingPolicy;
     onPolicyViolation: PolicyViolationHandler | undefined;
     /** The surface reported for a violation of the marker; `'prefix'` when omitted. */
     prefixSurface?: PolicyViolationSurface;

package/dist/esm/parseCommitMessage.js

@@ -1,45 +1,44 @@
-export const COMMIT_PREPROCESSOR_PATTERNS = [/^##\s+/, /^#\d+([.-]\d+)?\s+/, /^[A-Z]+-\d+\s+/];
-export const PIPE_SCOPE_SOURCE = '[^|]+';
-const COMMIT_SUBJECT_PATTERN = new RegExp(String.raw `^(?:(${PIPE_SCOPE_SOURCE})\|)?(\w+)(?:\(([^)]+)\))?(!)?:\s*(.*)$`);
+import { compileTemplate, parse, TEMPLATE_CATALOGUE, } from '@williamthorsen/change-grammar';
+const SUBJECT_TEMPLATES = [
+    compileTemplate(TEMPLATE_CATALOGUE.pipedScope),
+    compileTemplate(TEMPLATE_CATALOGUE.conventionalCommits),
+];
 export function parseCommitMessage(message, hash, workTypes, scopeAliases, options) {
     const firstLine = message.split('\n', 1)[0] ?? '';
-    const stripped = stripTicketPrefix(firstLine);
-    const match = stripped.match(COMMIT_SUBJECT_PATTERN);
-    if (!match) {
-        return undefined;
-    }
-    const pipeScope = match[1];
-    const rawType = match[2];
-    const parenthesizedScope = match[3];
-    const breakingMarker = match[4];
-    const description = match[5];
-    if (rawType === undefined || description === undefined) {
-        return undefined;
-    }
-    const resolvedType = resolveType(rawType, workTypes);
-    if (resolvedType === undefined) {
+    const record = parseSubject(firstLine, workTypes);
+    if (record?.type === undefined || record.title === undefined) {
         return undefined;
     }
     const commit = { message, subject: firstLine, hash };
     const breaking = evaluateBreakingPolicy({
         commit,
-        resolvedType,
-        hasPrefixBreaking: breakingMarker === '!',
+        resolvedType: record.type,
+        hasPrefixBreaking: record.breaking === true,
         hasFooterBreaking: message.includes('BREAKING CHANGE:'),
-        policy: options?.breakingPolicies?.[resolvedType] ?? 'optional',
+        policy: options?.breakingPolicies?.[record.type] ?? 'optional',
         onPolicyViolation: options?.onPolicyViolation,
     });
-    const rawScope = pipeScope ?? parenthesizedScope;
+    const rawScope = record.scope;
     const resolvedScope = rawScope !== undefined && scopeAliases !== undefined ? (scopeAliases[rawScope] ?? rawScope) : rawScope;
     return {
         message,
         hash,
-        type: resolvedType,
-        description,
+        type: record.type,
+        description: record.title,
         breaking,
         ...(resolvedScope !== undefined && { scope: resolvedScope }),
     };
 }
+export function parseSubject(subject, workTypes) {
+    const taxonomy = toTaxonomy(workTypes);
+    for (const nodes of SUBJECT_TEMPLATES) {
+        const record = parse(nodes, subject, taxonomy);
+        if (record !== undefined) {
+            return record;
+        }
+    }
+    return undefined;
+}
 export function evaluateBreakingPolicy(inputs) {
     const { commit, resolvedType, hasPrefixBreaking, hasFooterBreaking, policy, onPolicyViolation } = inputs;
     const prefixSurface = inputs.prefixSurface ?? 'prefix';
@@ -52,13 +51,6 @@ export function evaluateBreakingPolicy(inputs) {
         }
         return false;
     }
-    if (policy === 'required') {
-        if (!hasPrefixBreaking) {
-            onPolicyViolation?.(commit, resolvedType, prefixSurface);
-            return false;
-        }
-        return true;
-    }
     return hasPrefixBreaking || hasFooterBreaking;
 }
 export function resolveType(rawType, workTypes) {
@@ -77,10 +69,9 @@ export function resolveType(rawType, workTypes) {
     }
     return undefined;
 }
-function stripTicketPrefix(message) {
-    let result = message;
-    for (const pattern of COMMIT_PREPROCESSOR_PATTERNS) {
-        result = result.replace(pattern, '');
-    }
-    return result;
+function toTaxonomy(workTypes) {
+    return {
+        tiers: [],
+        types: Object.entries(workTypes).map(([key, config]) => ({ aliases: config.aliases ?? [], key, tier: '' })),
+    };
 }

package/dist/esm/parseRequestedTags.d.ts

@@ -1,8 +1,8 @@
 /**
- * Parse the comma-separated `--tags` flag value into a list of requested tag names.
+ * Parses the comma-separated `--tags` flag value into a list of requested tag names.
  *
  * Empty segments (from `--tags=`, leading/trailing commas, or `--tags=,,`) are dropped. When the
- * resulting list is empty, returns `undefined` so the caller treats it as "no filter" — the same
- * behavior as omitting `--tags` entirely.
+ * resulting list is empty, returns `undefined`, and the caller does not filter the tags, as when
+ * `--tags` is omitted.
  */
 export declare function parseRequestedTags(flagValue: string | undefined): string[] | undefined;