@williamthorsen/release-kit 12.0.0 → 13.0.0

package/dist/esm/renderChangelogMarkdown.js

@@ -1,10 +1,15 @@
-import { renderReleaseNotesMulti } from "./renderReleaseNotes.js";
+import { compareVersionsDescending } from "./compareVersions.js";
+import { renderReleaseNotesSingle } from "./renderReleaseNotes.js";
 const CHANGELOG_HEADER = `# Changelog
 
 All notable changes to this project will be documented in this file.`;
 const CHANGELOG_FOOTER = `<!-- Generated by release-kit. Do not edit this file. Use .meta/changelog-overrides.json to override entries. -->`;
 export function renderChangelogMarkdown(entries, options) {
-    const body = renderReleaseNotesMulti(entries, options);
+    const sections = interleavePreservedSections(entries.map((entry) => ({ version: entry.version, text: renderReleaseNotesSingle(entry, options) })), options?.preservedSections ?? []);
+    const body = sections
+        .map((part) => part.text)
+        .filter((text) => text.length > 0)
+        .join('\n');
     const trimmedBody = body.trimEnd();
     const parts = [CHANGELOG_HEADER];
     if (trimmedBody.length > 0) {
@@ -13,3 +18,23 @@ export function renderChangelogMarkdown(entries, options) {
     parts.push(CHANGELOG_FOOTER);
     return parts.join('\n\n') + '\n';
 }
+function interleavePreservedSections(rendered, preserved) {
+    const sorted = preserved.toSorted((a, b) => compareVersionsDescending(a.version, b.version));
+    const pending = sorted.map(withTrailingNewline);
+    const result = [];
+    let index = 0;
+    for (const part of rendered) {
+        let section = pending[index];
+        while (section !== undefined && compareVersionsDescending(section.version, part.version) < 0) {
+            result.push(section);
+            index++;
+            section = pending[index];
+        }
+        result.push(part);
+    }
+    result.push(...pending.slice(index));
+    return result;
+}
+function withTrailingNewline(section) {
+    return { version: section.version, text: `${section.text}\n` };
+}

package/dist/esm/renderReleaseNotes.d.ts

@@ -13,22 +13,14 @@ export interface RenderOptions {
     sectionOrder?: string[];
 }
 /**
- * Create a predicate that matches sections visible to the given audience.
+ * Creates a predicate that matches sections visible to the given audience.
  *
  * `"all"` matches only sections with `audience: "all"` (public-facing).
  * `"dev"` matches all sections (developers see everything).
  */
 export declare function matchesAudience(audience: ChangelogAudience): (section: ChangelogSection) => boolean;
 /**
- * Render a single `ChangelogEntry` to markdown.
- *
- * Output format mirrors the existing CHANGELOG.md style: an H2 version heading followed by
- * H3 section headings with bulleted items.
+ * Renders a single `ChangelogEntry` to markdown: an H2 version heading followed by H3 section
+ * headings with bulleted items.
  */
 export declare function renderReleaseNotesSingle(entry: ChangelogEntry, options?: RenderOptions): string;
-/**
- * Render multiple `ChangelogEntry` values to a single markdown document.
- *
- * Entries are rendered in the order provided; the caller is responsible for sorting.
- */
-export declare function renderReleaseNotesMulti(entries: ChangelogEntry[], options?: RenderOptions): string;

package/dist/esm/renderReleaseNotes.js

@@ -1,6 +1,6 @@
-import { WORK_TYPES_DATA } from "./workTypesData.js";
+import { CANONICAL_TAXONOMY } from '@williamthorsen/change-grammar';
 function getBreakingPrefix() {
-    const { emoji, label } = WORK_TYPES_DATA.markers.breaking;
+    const { emoji, label } = CANONICAL_TAXONOMY.markers.breaking;
     return `${emoji} **${label}:** `;
 }
 function allSections() {
@@ -62,7 +62,3 @@ function sortSectionsByOrder(sections, order) {
 function indentBodyLines(body) {
     return body.split('\n').map((line) => (line.length === 0 ? '' : `  ${line}`));
 }
-export function renderReleaseNotesMulti(entries, options) {
-    const parts = entries.map((entry) => renderReleaseNotesSingle(entry, options)).filter((part) => part.length > 0);
-    return parts.join('\n');
-}

package/dist/esm/reportPrepare.d.ts

@@ -1,6 +1,6 @@
 import { type OutputStyle } from '@williamthorsen/nmr-core';
 import type { PrepareResult } from './types.js';
-/** How the plan was carried out, which decides the tense the report is rendered in. */
+/** How the plan was carried out, which decides the report's tense. */
 export interface ReportPrepareOptions {
     /** True when the plan was written to disk; false for a dry run. */
     applied: boolean;
@@ -9,14 +9,13 @@ export interface ReportPrepareOptions {
     style: OutputStyle;
 }
 /**
- * Format a release plan into styled terminal output.
+ * Formats a release plan into styled terminal output, without writing it.
  *
- * Pure function: accepts structured data, returns a string. Never writes to stdout.
- * Single-workspace mode (no `name` field) renders flat output; multi-workspace mode
+ * Single-workspace mode (without a `name` field) renders flat output; multi-workspace mode
  * renders section headers per workspace, an optional project section, and a tag summary
  * at the end.
  *
- * Whether the plan was applied is a property of the render, not of the plan: the same plan
+ * Whether the plan was applied is a property of the render, not of the plan: The same plan
  * produces the dry-run report and the applied report.
  */
 export declare function reportPrepare(plan: PrepareResult, options: ReportPrepareOptions): string;

package/dist/esm/reportPrepare.js

@@ -51,7 +51,7 @@ function formatSingleWorkspace(result, options) {
     formatChangeRecordWarnings(lines, workspace, style);
     formatBumpFiles(lines, workspace, dryRun);
     lines.push(dim('Generating changelogs...'));
-    formatChangelogFiles(lines, workspace, dryRun);
+    formatChangelogFiles(lines, workspace, dryRun, style);
     formatPreviewFiles(lines, workspace, dryRun);
     formatFormatCommand(lines, result, options);
     formatWarnings(lines, result, style);
@@ -77,7 +77,7 @@ function formatMultiWorkspace(result, options) {
         }
     }
     else {
-        lines.push(`\n${formatStatusLine(style, 'skipped', 'No workspaces had release-worthy changes.')}`);
+        lines.push(`\n${formatStatusLine(style, 'skipped', 'The run did not find release-worthy changes in any workspace.')}`);
     }
     return lines.join('\n');
 }
@@ -111,14 +111,7 @@ function formatProjectSection(lines, project, dryRun, style) {
         }
     }
     lines.push(dim('  Generating changelogs...'));
-    for (const file of project.changelogFiles) {
-        if (dryRun) {
-            lines.push(dim(`    [dry-run] Would generate changelog: ${file}`));
-        }
-        else {
-            lines.push(dim(`    Generating changelog: ${file}`));
-        }
-    }
+    formatChangelogFiles(lines, project, dryRun, style, '  ');
     formatPreviewFiles(lines, project, dryRun, '  ');
     lines.push(`  ${formatGlyphLine(RELEASE_GLYPHS, style, 'tag', bold(tag))}`);
 }
@@ -136,7 +129,7 @@ function formatWorkspaceSection(lines, workspace, dryRun, style) {
         return;
     }
     const { propagatedFrom } = workspace;
-    const isPropagatedOnly = propagatedFrom !== undefined && workspace.commitCount === 0;
+    const isPropagatedOnly = workspace.propagatedOnly === true;
     formatCommitSummary(lines, workspace, propagatedFrom, isPropagatedOnly);
     formatUnparseableWarning(lines, workspace, style, '  ');
     formatPolicyViolations(lines, workspace.policyViolations, style, '  ');
@@ -145,14 +138,14 @@ function formatWorkspaceSection(lines, workspace, dryRun, style) {
     formatVersionLine(lines, workspace, propagatedFrom, isPropagatedOnly, style);
     formatBumpFiles(lines, workspace, dryRun, '  ');
     lines.push(dim('  Generating changelogs...'));
-    formatChangelogFiles(lines, workspace, dryRun, '  ');
+    formatChangelogFiles(lines, workspace, dryRun, style, '  ');
     formatPreviewFiles(lines, workspace, dryRun, '  ');
     lines.push(`  ${formatGlyphLine(RELEASE_GLYPHS, style, 'tag', bold(workspace.tag))}`);
 }
 function formatCommitSummary(lines, workspace, propagatedFrom, isPropagatedOnly) {
     if (isPropagatedOnly && propagatedFrom !== undefined) {
         const depNames = propagatedFrom.map((p) => p.packageName).join(', ');
-        lines.push(dim(`  0 commits (bumped via dependency: ${depNames})`));
+        lines.push(dim(`  Bumped via dependency: ${depNames}`));
     }
     else if (workspace.parsedCommitCount !== undefined && workspace.parsedCommitCount > 0) {
         lines.push(dim(`  Parsed ${workspace.parsedCommitCount} typed commits`));
@@ -192,14 +185,26 @@ function formatBumpFiles(lines, workspace, dryRun, indent = '') {
         }
     }
 }
-function formatChangelogFiles(lines, workspace, dryRun, indent = '') {
-    for (const file of workspace.changelogFiles) {
+function formatChangelogFiles(lines, release, dryRun, style, indent = '') {
+    for (const file of release.changelogFiles) {
         if (dryRun) {
             lines.push(dim(`${indent}  [dry-run] Would generate changelog: ${file}`));
         }
         else {
             lines.push(dim(`${indent}  Generating changelog: ${file}`));
         }
+        const preservation = release.changelogPreservation?.find((candidate) => candidate.file === file);
+        if (preservation === undefined) {
+            continue;
+        }
+        if (preservation.preservedVersions.length > 0) {
+            lines.push(dim(`${indent}    Kept from the existing file: ${preservation.preservedVersions.join(', ')}`));
+        }
+        const dropped = preservation.droppedUnversionedHeadings;
+        if (dropped.length > 0) {
+            const message = `Dropped ${dropped.length} section${dropped.length === 1 ? '' : 's'} without a version: ${dropped.join(', ')}`;
+            lines.push(`${indent}    ${formatStatusLine(style, 'warning', message)}`);
+        }
     }
 }
 function formatPreviewFiles(lines, release, dryRun, indent = '') {
@@ -237,17 +242,17 @@ function formatPolicyViolations(lines, violations, style, indent = '') {
         const subject = violation.commitSubject;
         const truncatedSubject = truncateSubject(subject);
         const location = violation.surface === 'entry' ? `entry ${violation.entryPosition ?? '?'}` : `${violation.surface} surface`;
-        lines.push(`${indent}    · ${shortHash} '${truncatedSubject}' — type '${violation.type}' at ${location}`);
+        lines.push(`${indent}    · ${shortHash} '${truncatedSubject}': type '${violation.type}' at ${location}`);
     }
 }
 function formatChangeRecordWarnings(lines, release, style, indent = '') {
-    const { malformedBlocks = [], undeclaredEntryTypes = [] } = release;
+    const { malformedBlocks = [], undeclaredEntryTypes = [], unroutedEntryScopes = [] } = release;
     if (malformedBlocks.length > 0) {
         const count = malformedBlocks.length;
         const header = `${count} change-record block${count === 1 ? '' : 's'} could not be read (item taken from the title)`;
         lines.push(`${indent}  ${formatStatusLine(style, 'warning', `${header}:`)}`);
         for (const block of malformedBlocks) {
-            lines.push(`${indent}    · ${block.commitHash.slice(0, 7)} '${truncateSubject(block.commitSubject)}' — ${block.reason}`);
+            lines.push(`${indent}    · ${block.commitHash.slice(0, 7)} '${truncateSubject(block.commitSubject)}': ${block.reason}`);
         }
     }
     if (undeclaredEntryTypes.length > 0) {
@@ -256,7 +261,16 @@ function formatChangeRecordWarnings(lines, release, style, indent = '') {
         lines.push(`${indent}  ${formatStatusLine(style, 'warning', `${header}:`)}`);
         for (const entry of undeclaredEntryTypes) {
             const shortHash = entry.commitHash.slice(0, 7);
-            lines.push(`${indent}    · ${shortHash} '${truncateSubject(entry.commitSubject)}' — type '${entry.type}' at entry ${entry.entryPosition}`);
+            lines.push(`${indent}    · ${shortHash} '${truncateSubject(entry.commitSubject)}': type '${entry.type}' at entry ${entry.entryPosition}`);
+        }
+    }
+    if (unroutedEntryScopes.length > 0) {
+        const count = unroutedEntryScopes.length;
+        const header = `${count} change-record entry scope${count === 1 ? ' does not match' : 's do not match'} any workspace in the commit's window (no item there)`;
+        lines.push(`${indent}  ${formatStatusLine(style, 'warning', `${header}:`)}`);
+        for (const finding of unroutedEntryScopes) {
+            const shortHash = finding.commitHash.slice(0, 7);
+            lines.push(`${indent}    · ${shortHash} '${truncateSubject(finding.commitSubject)}': scope '${finding.scope}' at entry ${finding.entryPosition}`);
         }
     }
 }

package/dist/esm/resolveCommandTags.d.ts

@@ -1,15 +1,19 @@
 import { type ResolvedTag } from './resolveReleaseTags.js';
+import type { ReleaseKitConfig } from './types.js';
 /**
- * Discover workspaces, resolve release tags from HEAD, validate `--tags` names against the
- * full resolved tag names (e.g., `nmr-core-v1.3.0`), and return the filtered tag list.
- * Works in both single-package and monorepo modes. Exits with an error message on any validation
- * failure — including `deriveWorkspaceConfig()` throws for workspaces missing a `package.json` `name` field,
- * and a workspace declaring patterns that resolve to no package, which is not single-package mode.
+ * Discovers workspaces, resolves release tags from HEAD, validates `--tags` names against the full resolved tag
+ * names (e.g., `nmr-core-v1.3.0`), and returns the filtered tag list. Exits with an error message on any validation
+ * failure, including a workspace whose `package.json` does not have a `name` field, a config that
+ * `mergeMonorepoConfig` rejects, and a workspace that does not resolve to any package, which is not single-package
+ * mode.
  *
- * In both modes `deriveWorkspaceConfig` is called so `WorkspaceConfig.isPublishable` (read
- * from `package.json#private`) propagates onto each `ResolvedTag`. Single-package mode now
- * derives `./package.json`'s workspace config too — consumers that previously relied on
- * single-package mode skipping the derive step need a `name` field on `./package.json`,
- * but in practice every npm/pnpm package already has one.
+ * In monorepo mode the workspace list is `userConfig` merged over the discovered workspaces, as `prepare` builds it.
+ * A tag on HEAD whose workspace the config excludes still counts as a tag on HEAD, so `--tags` may name it and a
+ * HEAD whose tags are all excluded returns an empty list rather than failing. Each excluded tag that the run
+ * selects, every one without `--tags` or the named ones with it, is dropped with a warning.
+ * Single-package mode ignores `userConfig`.
+ *
+ * In both modes the workspace configs come from `deriveWorkspaceConfig`, so that `WorkspaceConfig.isPublishable`
+ * (read from `package.json#private`) propagates onto each `ResolvedTag`.
  */
-export declare function resolveCommandTags(tags: string[] | undefined): ResolvedTag[];
+export declare function resolveCommandTags(tags: string[] | undefined, userConfig: ReleaseKitConfig | undefined): ResolvedTag[];

package/dist/esm/resolveCommandTags.js

@@ -1,9 +1,12 @@
+import { basename } from 'node:path';
 import { reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { deriveWorkspaceConfig } from "./deriveWorkspaceConfig.js";
 import { describeEmptyWorkspace, discoverWorkspaces } from "./discoverWorkspaces.js";
+import { formatExcludedSkip } from "./formatExcludedSkip.js";
+import { mergeMonorepoConfig, readRootPackageVersion } from "./loadConfig.js";
 import { resolveReleaseTags } from "./resolveReleaseTags.js";
-export function resolveCommandTags(tags) {
+export function resolveCommandTags(tags, userConfig) {
     let workspace;
     try {
         workspace = discoverWorkspaces();
@@ -18,12 +21,13 @@ export function resolveCommandTags(tags) {
     }
     let workspaces;
     let singleWorkspace;
+    const excludedDirs = workspace.kind === 'packages' ? collectExcludedDirs(userConfig) : new Set();
     try {
         if (workspace.kind === 'single-package') {
             singleWorkspace = deriveWorkspaceConfig('.');
         }
         else {
-            workspaces = workspace.packageDirs.map((workspacePath) => deriveWorkspaceConfig(workspacePath));
+            workspaces = buildMonorepoWorkspaces(workspace.packageDirs, userConfig, excludedDirs);
         }
     }
     catch (error) {
@@ -38,10 +42,10 @@ export function resolveCommandTags(tags) {
         resolvedTags = resolveReleaseTags({ singleWorkspace });
     }
     else {
-        throw new Error('resolveCommandTags: invariant violated — neither workspaces nor singleWorkspace was derived');
+        throw new Error('resolveCommandTags: invariant violated; neither workspaces nor singleWorkspace was derived');
     }
     if (resolvedTags.length === 0) {
-        reportError('No release tags found on HEAD. Create tags with `release-kit tag` first.');
+        reportError('HEAD does not have any release tags. Create tags with `release-kit tag` first.');
         process.exit(1);
     }
     if (tags !== undefined) {
@@ -55,5 +59,31 @@ export function resolveCommandTags(tags) {
         }
         resolvedTags = resolvedTags.filter((t) => tags.includes(t.tag));
     }
-    return resolvedTags;
+    return dropExcludedTags(resolvedTags, excludedDirs);
+}
+function buildMonorepoWorkspaces(packageDirs, userConfig, excludedDirs) {
+    const { workspaces } = mergeMonorepoConfig(packageDirs, userConfig, readRootPackageVersion());
+    if (excludedDirs.size === 0) {
+        return workspaces;
+    }
+    const excluded = packageDirs
+        .filter((packageDir) => excludedDirs.has(basename(packageDir)))
+        .map((packageDir) => deriveWorkspaceConfig(packageDir));
+    return [...workspaces, ...excluded];
+}
+function collectExcludedDirs(userConfig) {
+    const overrides = userConfig?.workspaces ?? [];
+    return new Set(overrides.filter((override) => override.shouldExclude === true).map((override) => override.dir));
+}
+function dropExcludedTags(resolvedTags, excludedDirs) {
+    const retained = [];
+    for (const resolvedTag of resolvedTags) {
+        if (excludedDirs.has(resolvedTag.dir)) {
+            console.warn(formatExcludedSkip(resolvedTag));
+        }
+        else {
+            retained.push(resolvedTag);
+        }
+    }
+    return retained;
 }

package/dist/esm/resolveConfigFlag.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Resolves a `--config` value against the directory from which `release-kit` was invoked, which differs from the
+ * working directory once the process has moved to the repo root.
+ *
+ * Returns `undefined` when the flag is absent, so that `loadConfig` falls back to the default path under the root.
+ */
+export declare function resolveConfigFlag(config: string | undefined, invocationDir: string): string | undefined;

package/dist/esm/resolveConfigFlag.js

@@ -0,0 +1,4 @@
+import path from 'node:path';
+export function resolveConfigFlag(config, invocationDir) {
+    return config === undefined ? undefined : path.resolve(invocationDir, config);
+}

package/dist/esm/resolveReleaseTags.d.ts

@@ -4,10 +4,8 @@ export interface ResolvedTag {
     dir: string;
     workspacePath: string;
     /**
-     * Whether the workspace this tag belongs to can be published to a registry. Propagated
-     * from the matched `WorkspaceConfig.isPublishable` (monorepo) or from the single-package
-     * workspace config (single-package mode). Consumed by `release-kit publish` to filter the
-     * tag set; other commands ignore it.
+     * Whether the workspace to which this tag belongs can be published to a registry, copied from the matched
+     * workspace's `WorkspaceConfig.isPublishable`.
      */
     isPublishable: boolean;
 }
@@ -18,15 +16,15 @@ type ResolveReleaseTagsArgs = {
     singleWorkspace: WorkspaceConfig;
 };
 /**
- * Resolve release tags pointing at HEAD into publishable package descriptors.
+ * Resolves release tags pointing at HEAD into publishable package descriptors.
  *
- * Pass `{ workspaces }` for monorepo mode: each tag is matched against the workspace
+ * Pass `{ workspaces }` for monorepo mode: Each tag is matched against the workspace
  * whose `tagPrefix` it starts with, and that workspace's `isPublishable` propagates onto
  * the `ResolvedTag`. Because `tagPrefix` is derived from `deriveWorkspaceConfig()` (the
  * same source that produced the tag), encoding and decoding stay colocated.
  *
- * Pass `{ singleWorkspace }` for single-package mode: tags like `v1.2.3` are matched and
- * each carries the workspace's `isPublishable` bit derived from `./package.json#private`.
+ * Pass `{ singleWorkspace }` for single-package mode: Tags like `v1.2.3` are matched and
+ * each has the workspace's `isPublishable` bit derived from `./package.json#private`.
  *
  * The no-arg form is a test-isolation convenience for unit tests that exercise tag
  * matching without needing `isPublishable` propagation; resolved tags default to

package/dist/esm/resolveReleaseTags.js

@@ -30,7 +30,7 @@ function resolveSinglePackageTags(tags, singleWorkspace) {
     return matched.map((tag) => ({ tag, dir: '.', workspacePath: '.', isPublishable }));
 }
 function resolveMonorepoTags(tags, workspaces) {
-    const sortedWorkspaces = [...workspaces].sort((a, b) => b.tagPrefix.length - a.tagPrefix.length);
+    const sortedWorkspaces = workspaces.toSorted((a, b) => b.tagPrefix.length - a.tagPrefix.length);
     const resolved = [];
     for (const tag of tags) {
         const match = findMatchingWorkspace(tag, sortedWorkspaces);

package/dist/esm/resolveStylesOrExit.d.ts

@@ -1,10 +1,10 @@
 import { type StreamStyles } from '@williamthorsen/nmr-core';
-/** The environment variable holding the caller's standing style preference: `auto`, `plain`, or `rich`. */
+/** The environment variable that sets the caller's standing style preference: `auto`, `plain`, or `rich`. */
 export declare const OUTPUT_STYLE_ENV_VAR = "RELEASE_KIT_OUTPUT_STYLE";
 export interface ResolveStylesOptions {
     readonly env: Readonly<Record<string, string | undefined>>;
     readonly stderrIsTty: boolean;
     readonly stdoutIsTty: boolean;
 }
-/** Resolves the style of each output stream, exiting with a usage error when the variable names no setting. */
+/** Resolves the style of each output stream, exiting with a usage error when the variable does not name a setting. */
 export declare function resolveStylesOrExit(options: ResolveStylesOptions): StreamStyles;

package/dist/esm/showTagPrefixesCommand.d.ts

@@ -1,15 +1,12 @@
 import { type StreamStyles } from '@williamthorsen/nmr-core';
 /**
- * Orchestrate the CLI `show-tag-prefixes` command.
+ * Runs the CLI `show-tag-prefixes` command and returns its exit code.
  *
- * Prints a per-workspace table of derived prefixes, tag counts, and declared legacy
- * entries, followed by an "Undeclared tag prefixes" section when candidate-shaped tags
- * exist outside the known set. Exits `0` on full derivation success and no collisions;
- * `1` on any derivation failure or collision. Undeclared candidates do not affect the
- * exit code. A config that exists and either fails to load or fails validation reports to stderr and
- * exits `1` in both repo modes, rather than falling back to a default-config preview that would
- * understate the declared legacy prefixes. An absent default config previews against derived defaults.
- *
- * @returns The exit code the caller should use.
+ * Prints a per-workspace table of derived prefixes, tag counts, and declared legacy entries, followed by an
+ * "Undeclared tag prefixes" section when candidate-shaped tags exist outside the known set. Returns `1` on any
+ * derivation failure or collision and `0` otherwise; undeclared candidates do not affect the exit code. When a config
+ * exists and either fails to load or fails validation, the command reports it to stderr and returns `1` in both repo
+ * modes, because a default-config preview would understate the declared legacy prefixes. When the default config is
+ * absent, the command previews against derived defaults.
  */
 export declare function showTagPrefixesCommand(styles: StreamStyles, configPath?: string): Promise<number>;

package/dist/esm/showTagPrefixesCommand.js

@@ -41,7 +41,7 @@ function renderMonorepo(preview, style) {
         lines.push('', ...preview.collisions.map((collision) => formatStatusLine(style, 'failed', `tag prefix collision: '${collision.tagPrefix}' used by ${collision.workspacePaths.join(', ')}`)));
     }
     if (preview.undeclaredCandidates.length > 0) {
-        lines.push('', 'Undeclared tag prefixes:', '', ...preview.undeclaredCandidates.map((candidate) => `  '${candidate.prefix}' — ${candidate.tagCount} tags (e.g., ${candidate.exampleTags.join(', ')})`), '', 'Suggested config snippet (adjust `dir` to match your workspace if the guess is wrong, and replace the `name` placeholder with the legacy npm name):', '', renderSuggestedSnippet(preview.undeclaredCandidates), '', "If the suggested `dir` does not match your workspace, adjust before pasting. Each legacy identity requires a `name` — replace the `TODO-fill-in-legacy-npm-name` placeholder with the package's prior npm name.");
+        lines.push('', 'Undeclared tag prefixes:', '', ...preview.undeclaredCandidates.map((candidate) => `  '${candidate.prefix}': ${candidate.tagCount} tags (e.g., ${candidate.exampleTags.join(', ')})`), '', 'Suggested config snippet (adjust `dir` to match the workspace if the guess is wrong, and replace the `name` placeholder with the legacy npm name):', '', renderSuggestedSnippet(preview.undeclaredCandidates), '', "If the suggested `dir` does not match the workspace, adjust it before pasting. Each legacy identity requires a `name`: Replace the `TODO-fill-in-legacy-npm-name` placeholder with the package's prior npm name.");
     }
     lines.push('');
     return lines.join('\n');
@@ -50,20 +50,20 @@ function renderWorkspaceRow(row, style) {
     const lines = [];
     if (row.derivedPrefix === null) {
         const failure = formatStatusLine(style, 'failed', `derivation failed: ${row.derivationError ?? 'unknown error'}`);
-        lines.push(`  ${row.workspacePath} — ${failure}`);
+        lines.push(`  ${row.workspacePath}: ${failure}`);
         return lines;
     }
     const statusMarker = row.derivedTagCount > 0
         ? formatStatusLine(style, 'passed', `${row.derivedTagCount} tags`)
         : formatStatusLine(style, 'warning', 'no existing tags');
-    lines.push(`  ${row.workspacePath} — derived prefix '${row.derivedPrefix}', ${statusMarker}`);
+    lines.push(`  ${row.workspacePath}: derived prefix '${row.derivedPrefix}', ${statusMarker}`);
     for (const entry of row.legacyEntries) {
         if (entry.tagCount > 0) {
             const recognized = `${entry.tagCount} legacy tags with '${entry.prefix}' prefix (recognized)`;
             lines.push(`      ${formatStatusLine(style, 'passed', recognized)}`);
         }
         else {
-            const tagless = `recorded legacy prefix '${entry.prefix}' has no tags`;
+            const tagless = `recorded legacy prefix '${entry.prefix}' does not have any tags`;
             lines.push(`      ${formatStatusLine(style, 'warning', tagless)}`);
         }
     }

package/dist/esm/stripEmojiPrefix.d.ts

@@ -1 +1,2 @@
+/** Removes a leading emoji and one space from a section title, returning the title unchanged when it has none. */
 export declare function stripEmojiPrefix(value: string): string;

package/dist/esm/stripScope.d.ts

@@ -1,8 +1,8 @@
 /**
- * Strip scope indicators from a raw commit message.
+ * Strips scope indicators from a raw commit message.
  *
  * Handles `scope|type: desc`, `type(scope): desc`, and messages with
  * ticket prefixes (e.g., `#72 release-kit|fix: ...`). Returns the
- * message unchanged when no scope is detected.
+ * message unchanged when it does not detect a scope.
  */
 export declare function stripScope(message: string): string;

package/dist/esm/stripScope.js

@@ -1,9 +1,9 @@
-import { COMMIT_PREPROCESSOR_PATTERNS, PIPE_SCOPE_SOURCE } from "./parseCommitMessage.js";
-const PIPE_SCOPE_PATTERN = new RegExp(String.raw `^${PIPE_SCOPE_SOURCE}\|(.*)$`);
+import { TICKET_PREFIX_PATTERNS } from '@williamthorsen/change-grammar';
+const PIPE_SCOPE_PATTERN = /^[^|]+\|(.*)$/;
 export function stripScope(message) {
     let ticketPrefix = '';
     let remainder = message;
-    for (const pattern of COMMIT_PREPROCESSOR_PATTERNS) {
+    for (const pattern of TICKET_PREFIX_PATTERNS) {
         const match = remainder.match(pattern);
         if (match) {
             ticketPrefix += match[0];

package/dist/esm/sync-labels/generateCommand.d.ts

@@ -4,34 +4,35 @@ import type { LabelDefinition } from './types.js';
 /** Output path for the generated labels file. */
 export declare const LABELS_OUTPUT_PATH = ".github/labels.yaml";
 /**
- * Formats resolved labels as YAML with generated header including preset hashes.
+ * Formats resolved labels as YAML under a generated header that includes the preset hashes.
  *
- * `configFilePath` is recorded in the header so that a reader of the generated file can find the config it came
- * from; it defaults to `CONFIG_FILE_PATH`.
+ * The header records `configFilePath` so that a reader of the generated file can find the config from which it came.
  */
 export declare function formatLabelsYaml(labels: LabelDefinition[], presetHashes: Map<string, string>, configFilePath?: string): string;
 /**
  * Loads the config file and returns its `repoLabels` block.
  *
  * Reports an actionable error and returns `undefined` when the config file is missing,
- * fails to load or validate, or carries no `repoLabels` block. Every message names the file
- * this run read, so that `--config` never points the reader at the default path.
+ * fails to load or validate, or lacks a `repoLabels` block. Every message names the file
+ * that this run read, so that `--config` never points the reader at the default path.
  */
 export declare function loadRepoLabelsConfig(stderrStyle: OutputStyle, configPath?: string): Promise<RepoLabelsConfig | undefined>;
 /** Options for the `sync-labels generate` subcommand. */
 interface GenerateOptions {
-    /** Compare the regenerated content against the committed file instead of writing. */
+    /** Compares the regenerated content against the committed file instead of writing. */
     check?: boolean;
     /** Config file to read, relative to the working directory. Defaults to `CONFIG_FILE_PATH`. */
     configPath?: string;
     styles: StreamStyles;
 }
 /**
- * Runs the `sync-labels generate` command.
+ * Runs the `sync-labels generate` command and returns the process exit code.
  *
- * Loads the `repoLabels` block from the config file, resolves presets and label adjustments, and writes
- * `.github/labels.yaml` -- or, with `check`, regenerates in memory and reports whether the committed file
- * is stale, writing nothing. Returns 0 on success, 1 on failure.
+ * Writes `.github/labels.yaml` from the config's `repoLabels` block, or, with `check`, reports whether the committed
+ * file is stale and writes nothing.
+ *
+ * The header names the config by its POSIX path relative to the working directory, the repo root, so that the file
+ * does not depend on the invocation directory or on the machine on which the command ran.
  */
 export declare function generateCommand({ check, configPath, styles }: GenerateOptions): Promise<number>;
 export {};

package/dist/esm/sync-labels/generateCommand.js

@@ -1,17 +1,17 @@
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
+import path from 'node:path';
 import { reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { stringify } from 'yaml';
 import { CONFIG_FILE_PATH } from "../loadConfig.js";
 import { loadValidatedConfig, reportConfigProblem } from "../loadValidatedConfig.js";
-import { hashPresetFile } from "./presets.js";
+import { hashPreset } from "./presets.js";
 import { resolveLabels } from "./resolveLabels.js";
 import { checkRetiredSyncLabelsConfig } from "./retiredConfig.js";
 export const LABELS_OUTPUT_PATH = '.github/labels.yaml';
 export function formatLabelsYaml(labels, presetHashes, configFilePath = CONFIG_FILE_PATH) {
     const headerLines = ['# Generated by release-kit sync-labels — do not edit.', `# Source: ${configFilePath}`];
-    const sortedPresetHashes = [...presetHashes].sort(([a], [b]) => a.localeCompare(b));
+    const sortedPresetHashes = [...presetHashes].toSorted(([a], [b]) => a.localeCompare(b));
     for (const [name, hash] of sortedPresetHashes) {
         headerLines.push(`# ${name} preset hash: ${hash}`);
     }
@@ -22,7 +22,7 @@ export function formatLabelsYaml(labels, presetHashes, configFilePath = CONFIG_F
 export async function loadRepoLabelsConfig(stderrStyle, configPath) {
     const result = await loadValidatedConfig(configPath);
     if (result.status === 'missing') {
-        reportError(`No config file found at ${result.configFilePath}. Run \`release-kit sync-labels init\` first.`);
+        reportError(`Config file not found at ${result.configFilePath}. Run \`release-kit sync-labels init\` first.`);
         return undefined;
     }
     if (result.status === 'invalid') {
@@ -30,7 +30,7 @@ export async function loadRepoLabelsConfig(stderrStyle, configPath) {
         return undefined;
     }
     if (result.config.repoLabels === undefined) {
-        reportError(`No \`repoLabels\` block found in ${result.configFilePath}. Run \`release-kit sync-labels init\` to seed one.`);
+        reportError(`The \`repoLabels\` block is missing from ${result.configFilePath}. Run \`release-kit sync-labels init\` to seed one.`);
         return undefined;
     }
     return result.config.repoLabels;
@@ -55,14 +55,14 @@ export async function generateCommand({ check = false, configPath, styles }) {
     const presetHashes = new Map();
     const presetNames = repoLabels.extends ?? [];
     for (const presetName of presetNames) {
-        presetHashes.set(presetName, hashPresetFile(presetName));
+        presetHashes.set(presetName, hashPreset(presetName));
     }
-    const content = formatLabelsYaml(labels, presetHashes, configPath);
+    const content = formatLabelsYaml(labels, presetHashes, toRootRelativePosixPath(configPath ?? CONFIG_FILE_PATH));
     if (check) {
         return compareAgainstCommittedFile(content);
     }
     try {
-        mkdirSync(dirname(LABELS_OUTPUT_PATH), { recursive: true });
+        mkdirSync(path.dirname(LABELS_OUTPUT_PATH), { recursive: true });
         writeFileSync(LABELS_OUTPUT_PATH, content, 'utf8');
     }
     catch (error) {
@@ -89,3 +89,6 @@ function compareAgainstCommittedFile(expected) {
     console.info(`${LABELS_OUTPUT_PATH} is up to date.`);
     return 0;
 }
+function toRootRelativePosixPath(filePath) {
+    return path.relative(process.cwd(), path.resolve(filePath)).split(path.sep).join('/');
+}