@williamthorsen/release-kit 10.9.0 → 12.0.0

package/dist/esm/releasePrepareProject.js

@@ -1,13 +1,11 @@
 import { join as joinPath } from 'node:path';
-import { buildChangelogEntries } from "./buildChangelogEntries.js";
+import { attachChangelogDiagnostics } from "./attachChangelogDiagnostics.js";
+import { readReleaseHistory, toChangelogEntries } from "./buildChangelogEntries.js";
 import { buildEmptyReleaseEntry } from "./buildEmptyReleaseEntry.js";
 import { mergeChangelogEntriesWithDisk, renderChangelogJson, resolveChangelogJsonPath } from "./changelogJsonFile.js";
 import { applyChangelogOverrides } from "./changelogOverrides.js";
-import { createPolicyViolationCollector } from "./collectPolicyViolations.js";
 import { decideRelease } from "./decideRelease.js";
-import { DEFAULT_BREAKING_POLICIES, DEFAULT_VERSION_PATTERNS, DEFAULT_WORK_TYPES } from "./defaults.js";
-import { buildTagPattern } from "./generateChangelogs.js";
-import { getCommitsSinceTarget } from "./getCommitsSinceTarget.js";
+import { DEFAULT_WORK_TYPES } from "./defaults.js";
 import { planReleaseNotesPreviews } from "./planReleaseNotesPreviews.js";
 import { planVersionBump } from "./planVersionBump.js";
 import { renderChangelogMarkdown } from "./renderChangelogMarkdown.js";
@@ -23,54 +21,43 @@ export function releasePrepareProject(args) {
         throw new Error('releasePrepareProject called without a configured project block');
     }
     const workTypes = config.workTypes ?? { ...DEFAULT_WORK_TYPES };
-    const versionPatterns = config.versionPatterns ?? { ...DEFAULT_VERSION_PATTERNS };
-    const breakingPolicies = config.breakingPolicies ?? DEFAULT_BREAKING_POLICIES;
-    const contributingPaths = project.paths;
-    const { tag, commits } = getCommitsSinceTarget([project.tagPrefix], contributingPaths);
+    const history = readReleaseHistory(config, { tagPrefixes: [project.tagPrefix], paths: project.paths });
+    const { commits, diagnostics, parsedCommitCount, unparseableCommits } = history.unreleased;
+    const tag = history.previousTag;
     const since = tag === undefined ? '(no previous release found)' : `since ${tag}`;
-    const collector = createPolicyViolationCollector();
     const decision = decideRelease({
-        commits,
+        naturalBump: history.unreleased.bump,
+        commitCount: commits.length,
         force,
         bumpOverride,
-        workTypes,
-        versionPatterns,
-        scopeAliases: config.scopeAliases,
-        breakingPolicies,
-        onPolicyViolation: collector.onPolicyViolation,
         skipReasons: {
             noCommits: `No commits ${since}. Pass --force to release at patch. Skipping.`,
             noBumpWorthy: `No bump-worthy commits ${since}. Pass --force to release at patch (or --force --bump=X for a different level). Skipping.`,
         },
     });
-    const policyViolations = collector.violations.length > 0 ? collector.violations : undefined;
     if (decision.outcome === 'skip') {
         const skipped = {
             status: 'skipped',
             commitCount: commits.length,
-            parsedCommitCount: decision.parsedCommitCount,
+            parsedCommitCount,
             skipReason: decision.skipReason,
         };
         if (tag !== undefined) {
             skipped.previousTag = tag;
         }
-        if (decision.unparseableCommits !== undefined) {
-            skipped.unparseableCommits = decision.unparseableCommits;
-        }
-        if (policyViolations !== undefined) {
-            skipped.policyViolations = policyViolations;
+        if (unparseableCommits !== undefined) {
+            skipped.unparseableCommits = unparseableCommits;
         }
+        attachChangelogDiagnostics(skipped, diagnostics);
         return skipped;
     }
-    const { releaseType, parsedCommitCount, unparseableCommits } = decision;
+    const { releaseType } = decision;
     const bump = planVersionBump([ROOT_PACKAGE_FILE], releaseType);
     writes.push(...bump.writes);
     const newTag = `${project.tagPrefix}${bump.newVersion}`;
     const changelogs = planProjectChangelogs({
         config,
-        project,
-        commits,
-        contributingPaths,
+        history,
         newTag,
         newVersion: bump.newVersion,
         rootOverrides,
@@ -114,12 +101,10 @@ export function releasePrepareProject(args) {
     if (unparseableCommits !== undefined) {
         result.unparseableCommits = unparseableCommits;
     }
-    if (policyViolations !== undefined) {
-        result.policyViolations = policyViolations;
-    }
     if (bumpOverride !== undefined) {
         result.bumpOverride = bumpOverride;
     }
+    attachChangelogDiagnostics(result, diagnostics);
     return result;
 }
 function resolveOptionalOverrideArgs(args) {
@@ -131,14 +116,11 @@ function resolveOptionalOverrideArgs(args) {
     };
 }
 function planProjectChangelogs(args) {
-    const { config, project, commits, contributingPaths, newTag, newVersion, rootOverrides, overrideWarnings, globalMatchedRootKeys, } = args;
-    const isEmptyRange = commits.length === 0;
+    const { config, history, newTag, newVersion, rootOverrides, overrideWarnings, globalMatchedRootKeys } = args;
+    const isEmptyRange = history.unreleased.commits.length === 0;
     const today = new Date().toISOString().slice(0, 10);
-    const tagPattern = buildTagPattern([project.tagPrefix]);
-    const newEntries = isEmptyRange
-        ? [buildEmptyReleaseEntry(newVersion, today)]
-        : buildChangelogEntries(config, newTag, { tagPattern, includePaths: contributingPaths });
-    const applied = applyChangelogOverrides(newEntries, rootOverrides);
+    const builtEntries = isEmptyRange ? [buildEmptyReleaseEntry(newVersion, today)] : toChangelogEntries(history, newTag);
+    const applied = applyChangelogOverrides(builtEntries, rootOverrides);
     if (applied.errors.length > 0) {
         throw new Error(`Changelog override application failed:\n  - ${applied.errors.join('\n  - ')}`);
     }

package/dist/esm/reportPrepare.js

@@ -1,8 +1,7 @@
-import { formatGlyphLine, formatStatusLine, measureGlyphColumn, STATUS_GLYPHS, } from '@williamthorsen/nmr-core';
+import { formatGlyphLine, formatStatusLine, measureGlyphColumn, STATUS_GLYPHS, truncateToWidth, } from '@williamthorsen/nmr-core';
 import { bold, dim, sectionHeader } from "./format.js";
 import { RELEASE_GLYPHS } from "./glyphs.js";
-import { GIT_CLIFF_NPX_ARGS } from "./runGitCliff.js";
-const CLIFF_DRY_RUN_COMMAND = `npx ${GIT_CLIFF_NPX_ARGS.join(' ')} ...`;
+const SUBJECT_COLUMN_BUDGET = 72;
 export function reportPrepare(plan, options) {
     const isMultiWorkspace = plan.workspaces.some((w) => w.name !== undefined) || plan.project !== undefined;
     if (isMultiWorkspace) {
@@ -26,6 +25,7 @@ function formatSingleWorkspace(result, options) {
     formatUnparseableWarning(lines, workspace, style);
     formatPolicyViolations(lines, workspace.policyViolations, style);
     if (workspace.status === 'skipped') {
+        formatChangeRecordWarnings(lines, workspace, style);
         lines.push(formatStatusLine(style, 'skipped', workspace.skipReason));
         formatWarnings(lines, result, style);
         return lines.join('\n');
@@ -48,6 +48,7 @@ function formatSingleWorkspace(result, options) {
     else if (workspace.releaseType !== undefined) {
         lines.push(formatGlyphLine(RELEASE_GLYPHS, style, 'bump', `${workspace.currentVersion} → ${bold(workspace.newVersion)} (${workspace.releaseType})`));
     }
+    formatChangeRecordWarnings(lines, workspace, style);
     formatBumpFiles(lines, workspace, dryRun);
     lines.push(dim('Generating changelogs...'));
     formatChangelogFiles(lines, workspace, dryRun);
@@ -86,6 +87,8 @@ function formatProjectSection(lines, project, dryRun, style) {
     lines.push(dim(`  Found ${project.commitCount} commits ${since}`));
     formatPolicyViolations(lines, project.policyViolations, style, '  ');
     if (project.status === 'skipped') {
+        formatUnparseableWarning(lines, project, style, '  ');
+        formatChangeRecordWarnings(lines, project, style, '  ');
         lines.push(`  ${formatStatusLine(style, 'skipped', project.skipReason)}`);
         return;
     }
@@ -96,7 +99,8 @@ function formatProjectSection(lines, project, dryRun, style) {
     if (project.bumpOverride !== undefined) {
         lines.push(`  Using bump override: ${project.bumpOverride}`);
     }
-    formatProjectUnparseable(lines, project, style);
+    formatUnparseableWarning(lines, project, style, '  ');
+    formatChangeRecordWarnings(lines, project, style, '  ');
     lines.push(dim(`  Bumping versions (${releaseType})...`), `  ${formatGlyphLine(RELEASE_GLYPHS, style, 'bump', `${currentVersion} → ${bold(newVersion)} (${releaseType})`)}`);
     for (const file of project.bumpedFiles) {
         if (dryRun) {
@@ -109,7 +113,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 run: ${CLIFF_DRY_RUN_COMMAND} --output ${file}`));
+            lines.push(dim(`    [dry-run] Would generate changelog: ${file}`));
         }
         else {
             lines.push(dim(`    Generating changelog: ${file}`));
@@ -118,21 +122,6 @@ function formatProjectSection(lines, project, dryRun, style) {
     formatPreviewFiles(lines, project, dryRun, '  ');
     lines.push(`  ${formatGlyphLine(RELEASE_GLYPHS, style, 'tag', bold(tag))}`);
 }
-function formatProjectUnparseable(lines, project, style) {
-    const unparseable = project.unparseableCommits;
-    if (unparseable === undefined || unparseable.length === 0) {
-        return;
-    }
-    const count = unparseable.length;
-    const isPatchFloor = project.parsedCommitCount === 0;
-    const suffix = isPatchFloor ? ' (defaulting to patch bump)' : '';
-    lines.push(`    ${formatStatusLine(style, 'warning', `${count} commit${count === 1 ? '' : 's'} could not be parsed${suffix}`)}`);
-    for (const commit of unparseable) {
-        const shortHash = commit.hash.slice(0, 7);
-        const truncatedMessage = commit.message.length > 72 ? `${commit.message.slice(0, 69)}...` : commit.message;
-        lines.push(`      · ${shortHash} ${truncatedMessage}`);
-    }
-}
 function formatWorkspaceSection(lines, workspace, dryRun, style) {
     if (workspace.name !== undefined) {
         lines.push(`\n${sectionHeader(workspace.name)}`);
@@ -140,6 +129,9 @@ function formatWorkspaceSection(lines, workspace, dryRun, style) {
     const since = workspace.previousTag === undefined ? '(no previous release found)' : `since ${workspace.previousTag}`;
     lines.push(dim(`  Found ${workspace.commitCount} commits ${since}`));
     if (workspace.status === 'skipped') {
+        formatUnparseableWarning(lines, workspace, style, '  ');
+        formatPolicyViolations(lines, workspace.policyViolations, style, '  ');
+        formatChangeRecordWarnings(lines, workspace, style, '  ');
         lines.push(`  ${formatStatusLine(style, 'skipped', workspace.skipReason)}`);
         return;
     }
@@ -148,6 +140,7 @@ function formatWorkspaceSection(lines, workspace, dryRun, style) {
     formatCommitSummary(lines, workspace, propagatedFrom, isPropagatedOnly);
     formatUnparseableWarning(lines, workspace, style, '  ');
     formatPolicyViolations(lines, workspace.policyViolations, style, '  ');
+    formatChangeRecordWarnings(lines, workspace, style, '  ');
     formatBumpLabels(lines, workspace, isPropagatedOnly);
     formatVersionLine(lines, workspace, propagatedFrom, isPropagatedOnly, style);
     formatBumpFiles(lines, workspace, dryRun, '  ');
@@ -202,7 +195,7 @@ function formatBumpFiles(lines, workspace, dryRun, indent = '') {
 function formatChangelogFiles(lines, workspace, dryRun, indent = '') {
     for (const file of workspace.changelogFiles) {
         if (dryRun) {
-            lines.push(dim(`${indent}  [dry-run] Would run: ${CLIFF_DRY_RUN_COMMAND} --output ${file}`));
+            lines.push(dim(`${indent}  [dry-run] Would generate changelog: ${file}`));
         }
         else {
             lines.push(dim(`${indent}  Generating changelog: ${file}`));
@@ -220,19 +213,17 @@ function formatPreviewFiles(lines, release, dryRun, indent = '') {
         }
     }
 }
-function formatUnparseableWarning(lines, workspace, style, indent = '') {
-    const unparseable = workspace.unparseableCommits;
+function formatUnparseableWarning(lines, release, style, indent = '') {
+    const unparseable = release.unparseableCommits;
     if (unparseable === undefined || unparseable.length === 0) {
         return;
     }
     const count = unparseable.length;
-    const isPatchFloor = workspace.parsedCommitCount === 0;
-    const suffix = isPatchFloor ? ' (defaulting to patch bump)' : '';
-    lines.push(`${indent}  ${formatStatusLine(style, 'warning', `${count} commit${count === 1 ? '' : 's'} could not be parsed${suffix}`)}`);
+    lines.push(`${indent}  ${formatStatusLine(style, 'warning', `${count} commit${count === 1 ? '' : 's'} could not be parsed`)}`);
     for (const commit of unparseable) {
         const shortHash = commit.hash.slice(0, 7);
-        const truncatedMessage = commit.message.length > 72 ? `${commit.message.slice(0, 69)}...` : commit.message;
-        lines.push(`${indent}    · ${shortHash} ${truncatedMessage}`);
+        const truncatedSubject = truncateSubject(commit.subject);
+        lines.push(`${indent}    · ${shortHash} ${truncatedSubject}`);
     }
 }
 function formatPolicyViolations(lines, violations, style, indent = '') {
@@ -244,8 +235,29 @@ function formatPolicyViolations(lines, violations, style, indent = '') {
     for (const violation of violations) {
         const shortHash = violation.commitHash.slice(0, 7);
         const subject = violation.commitSubject;
-        const truncatedSubject = subject.length > 72 ? `${subject.slice(0, 69)}...` : subject;
-        lines.push(`${indent}    · ${shortHash} '${truncatedSubject}' — type '${violation.type}' at ${violation.surface} surface`);
+        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}`);
+    }
+}
+function formatChangeRecordWarnings(lines, release, style, indent = '') {
+    const { malformedBlocks = [], undeclaredEntryTypes = [] } = 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}`);
+        }
+    }
+    if (undeclaredEntryTypes.length > 0) {
+        const count = undeclaredEntryTypes.length;
+        const header = `${count} change-record entr${count === 1 ? 'y has an' : 'ies have'} undeclared type${count === 1 ? '' : 's'} (no item)`;
+        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}`);
+        }
     }
 }
 function formatPropagationSuffix(propagatedFrom) {
@@ -280,3 +292,6 @@ function formatFormatCommand(lines, result, options) {
     const messageIndent = ' '.repeat(2 + measureGlyphColumn(STATUS_GLYPHS[options.style]) + 1);
     lines.push(`\n  ${formatStatusLine(options.style, 'warning', `Format command failed: ${result.formatCommand.command}`)}`, `${messageIndent}${options.formatError}`);
 }
+function truncateSubject(subject) {
+    return truncateToWidth(subject, { width: SUBJECT_COLUMN_BUDGET });
+}

package/dist/esm/resolveCommandTags.d.ts

@@ -3,7 +3,8 @@ import { type ResolvedTag } from './resolveReleaseTags.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.
+ * 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.
  *
  * In both modes `deriveWorkspaceConfig` is called so `WorkspaceConfig.isPublishable` (read
  * from `package.json#private`) propagates onto each `ResolvedTag`. Single-package mode now
@@ -11,4 +12,4 @@ import { type ResolvedTag } from './resolveReleaseTags.js';
  * single-package mode skipping the derive step need a `name` field on `./package.json`,
  * but in practice every npm/pnpm package already has one.
  */
-export declare function resolveCommandTags(tags: string[] | undefined): Promise<ResolvedTag[]>;
+export declare function resolveCommandTags(tags: string[] | undefined): ResolvedTag[];

package/dist/esm/resolveCommandTags.js

@@ -1,25 +1,29 @@
 import { reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { deriveWorkspaceConfig } from "./deriveWorkspaceConfig.js";
-import { discoverWorkspaces } from "./discoverWorkspaces.js";
+import { describeEmptyWorkspace, discoverWorkspaces } from "./discoverWorkspaces.js";
 import { resolveReleaseTags } from "./resolveReleaseTags.js";
-export async function resolveCommandTags(tags) {
-    let discoveredPaths;
+export function resolveCommandTags(tags) {
+    let workspace;
     try {
-        discoveredPaths = await discoverWorkspaces();
+        workspace = discoverWorkspaces();
     }
     catch (error) {
         reportError(`Failed to discover workspaces: ${describeError(error)}`);
         process.exit(1);
     }
+    if (workspace.kind === 'empty') {
+        reportError(`No workspace package to tag. ${describeEmptyWorkspace(workspace)}`);
+        process.exit(1);
+    }
     let workspaces;
     let singleWorkspace;
     try {
-        if (discoveredPaths === undefined) {
+        if (workspace.kind === 'single-package') {
             singleWorkspace = deriveWorkspaceConfig('.');
         }
         else {
-            workspaces = discoveredPaths.map((workspacePath) => deriveWorkspaceConfig(workspacePath));
+            workspaces = workspace.packageDirs.map((workspacePath) => deriveWorkspaceConfig(workspacePath));
         }
     }
     catch (error) {

package/dist/esm/resolveReleaseNotesConfig.d.ts

@@ -1,4 +1,4 @@
-import { type OutputStyle } from '@williamthorsen/nmr-core';
+import type { OutputStyle } from '@williamthorsen/nmr-core';
 import type { ReleaseNotesConfig } from './types.js';
 export interface ResolvedReleaseNotesConfig {
     releaseNotes: ReleaseNotesConfig;
@@ -7,19 +7,17 @@ export interface ResolvedReleaseNotesConfig {
     sectionOrder: string[];
 }
 export interface ResolveReleaseNotesConfigOptions {
-    /**
-     * When `true`, a `loadConfig()` rejection causes `process.exit(1)` rather than a fallback to
-     * defaults. Use from CLI commands whose entire behavior depends on the resolved config (e.g.
-     * `create-github-release`), so a corrupt or unreadable config cannot silently send the command
-     * to the wrong changelog path.
-     */
-    strictLoad?: boolean;
+    /** Config file to read, relative to the working directory. Defaults to `CONFIG_FILE_PATH`. */
+    configPath?: string;
 }
 /**
- * Load and validate the release-kit config.
+ * Loads and validates the release-kit config, resolving the release-notes settings it carries.
  *
- * By default, falls back to defaults when `loadConfig()` rejects (legacy publish behavior).
- * When `strictLoad` is `true`, a load failure prints an error and calls `process.exit(1)`.
+ * An unusable config reports to stderr and calls `process.exit(1)`, whether the file failed to load or failed
+ * validation, and whether it was named by the caller or the default one. Both callers are CLI commands whose
+ * whole behavior depends on the resolved config, so neither could proceed on derived defaults without silently
+ * dropping a configured `releaseNotes.shouldInjectIntoReadme`, `changelogJson.outputPath`, or `workTypes`.
+ * An absent default config is a supported state and resolves to the defaults.
  */
 export declare function resolveReleaseNotesConfig(stderrStyle: OutputStyle, options?: ResolveReleaseNotesConfigOptions): Promise<ResolvedReleaseNotesConfig>;
 /** Extract section headers in declaration order from a merged workTypes record. */

package/dist/esm/resolveReleaseNotesConfig.js

@@ -1,40 +1,21 @@
-import { formatStatusLine, printError, reportError } from '@williamthorsen/nmr-core';
-import { describeError } from '@williamthorsen/toolbelt.errors';
 import { DEFAULT_CHANGELOG_JSON_CONFIG, DEFAULT_RELEASE_NOTES_CONFIG } from "./defaults.js";
-import { loadConfig, resolveWorkTypes } from "./loadConfig.js";
-import { validateConfig } from "./validateConfig.js";
+import { resolveWorkTypes } from "./loadConfig.js";
+import { loadValidatedConfig, reportConfigProblem, reportConfigWarnings } from "./loadValidatedConfig.js";
 export async function resolveReleaseNotesConfig(stderrStyle, options = {}) {
-    const { strictLoad = false } = options;
-    let rawConfig;
-    try {
-        rawConfig = await loadConfig();
-    }
-    catch (error) {
-        const message = describeError(error);
-        if (strictLoad) {
-            reportError(`Failed to load config: ${message}`);
-            process.exit(1);
-        }
-        console.warn(`Warning: failed to load config; using defaults: ${message}`);
+    const result = await loadValidatedConfig(options.configPath);
+    if (result.status === 'invalid') {
+        reportConfigProblem(result.problem, stderrStyle);
+        process.exit(1);
     }
-    if (rawConfig === undefined) {
+    if (result.status === 'missing') {
         return {
             releaseNotes: { ...DEFAULT_RELEASE_NOTES_CONFIG },
             changelogJsonOutputPath: DEFAULT_CHANGELOG_JSON_CONFIG.outputPath,
             sectionOrder: deriveSectionOrder(resolveWorkTypes()),
         };
     }
-    const { config, errors, warnings } = validateConfig(rawConfig);
-    if (errors.length > 0) {
-        process.stderr.write('Invalid config:\n');
-        for (const err of errors) {
-            printError(err, stderrStyle);
-        }
-        process.exit(1);
-    }
-    for (const warning of warnings) {
-        console.warn(`  ${formatStatusLine(stderrStyle, 'warning', warning)}`);
-    }
+    reportConfigWarnings(result.warnings, stderrStyle);
+    const { config } = result;
     return {
         releaseNotes: {
             shouldInjectIntoReadme: config.releaseNotes?.shouldInjectIntoReadme ?? DEFAULT_RELEASE_NOTES_CONFIG.shouldInjectIntoReadme,

package/dist/esm/showTagPrefixesCommand.d.ts

@@ -6,8 +6,10 @@ import { type StreamStyles } from '@williamthorsen/nmr-core';
  * 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.
+ * 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.
  */
-export declare function showTagPrefixesCommand(styles: StreamStyles): Promise<number>;
+export declare function showTagPrefixesCommand(styles: StreamStyles, configPath?: string): Promise<number>;

package/dist/esm/showTagPrefixesCommand.js

@@ -1,12 +1,26 @@
-import { formatStatusLine } from '@williamthorsen/nmr-core';
+import { formatStatusLine, reportError } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { detectRepoType } from "./init/detectRepoType.js";
+import { loadValidatedConfig, reportConfigProblem } from "./loadValidatedConfig.js";
 import { previewTagPrefixes } from "./previewTagPrefixes.js";
-export async function showTagPrefixesCommand(styles) {
+export async function showTagPrefixesCommand(styles, configPath) {
+    const result = await loadValidatedConfig(configPath);
+    if (result.status === 'invalid') {
+        reportConfigProblem(result.problem, styles.stderr);
+        return 1;
+    }
     if (detectRepoType() === 'single-package') {
         process.stdout.write(renderSinglePackage());
         return 0;
     }
-    const preview = await previewTagPrefixes();
+    let preview;
+    try {
+        preview = previewTagPrefixes(result.status === 'ok' ? result.config : undefined);
+    }
+    catch (error) {
+        reportError(describeError(error));
+        return 1;
+    }
     process.stdout.write(renderMonorepo(preview, styles.stdout));
     return computeExitCode(preview);
 }

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

@@ -3,27 +3,35 @@ import type { RepoLabelsConfig } from '../types.js';
 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. */
-export declare function formatLabelsYaml(labels: LabelDefinition[], presetHashes: Map<string, string>): string;
 /**
- * Loads `.config/release-kit.config.ts` and returns its `repoLabels` block.
+ * Formats resolved labels as YAML with generated header including 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`.
+ */
+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.
+ * 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.
  */
-export declare function loadRepoLabelsConfig(stderrStyle: OutputStyle): Promise<RepoLabelsConfig | undefined>;
+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. */
     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.
  *
- * Loads the `repoLabels` block from `.config/release-kit.config.ts`, resolves presets and label adjustments,
- * and writes `.github/labels.yaml` -- or, with `check`, regenerates in memory and reports whether the committed file
+ * 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.
  */
-export declare function generateCommand({ check, styles }: GenerateOptions): Promise<number>;
+export declare function generateCommand({ check, configPath, styles }: GenerateOptions): Promise<number>;
 export {};

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

@@ -4,13 +4,13 @@ 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 } from "../loadValidatedConfig.js";
+import { loadValidatedConfig, reportConfigProblem } from "../loadValidatedConfig.js";
 import { hashPresetFile } 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) {
-    const headerLines = ['# Generated by release-kit sync-labels — do not edit.', `# Source: ${CONFIG_FILE_PATH}`];
+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));
     for (const [name, hash] of sortedPresetHashes) {
         headerLines.push(`# ${name} preset hash: ${hash}`);
@@ -19,26 +19,27 @@ export function formatLabelsYaml(labels, presetHashes) {
     const yamlBody = stringify(declared, { singleQuote: true, lineWidth: 0 });
     return headerLines.join('\n') + '\n' + yamlBody;
 }
-export async function loadRepoLabelsConfig(stderrStyle) {
-    const result = await loadValidatedConfig(stderrStyle);
+export async function loadRepoLabelsConfig(stderrStyle, configPath) {
+    const result = await loadValidatedConfig(configPath);
     if (result.status === 'missing') {
-        reportError(`No config file found at ${CONFIG_FILE_PATH}. Run \`release-kit sync-labels init\` first.`);
+        reportError(`No config file found at ${result.configFilePath}. Run \`release-kit sync-labels init\` first.`);
         return undefined;
     }
     if (result.status === 'invalid') {
+        reportConfigProblem(result.problem, stderrStyle);
         return undefined;
     }
     if (result.config.repoLabels === undefined) {
-        reportError(`No \`repoLabels\` block found in ${CONFIG_FILE_PATH}. Run \`release-kit sync-labels init\` to seed one.`);
+        reportError(`No \`repoLabels\` block found in ${result.configFilePath}. Run \`release-kit sync-labels init\` to seed one.`);
         return undefined;
     }
     return result.config.repoLabels;
 }
-export async function generateCommand({ check = false, styles }) {
-    if (checkRetiredSyncLabelsConfig()) {
+export async function generateCommand({ check = false, configPath, styles }) {
+    if (checkRetiredSyncLabelsConfig(configPath)) {
         return 1;
     }
-    const repoLabels = await loadRepoLabelsConfig(styles.stderr);
+    const repoLabels = await loadRepoLabelsConfig(styles.stderr, configPath);
     if (repoLabels === undefined) {
         return 1;
     }
@@ -56,7 +57,7 @@ export async function generateCommand({ check = false, styles }) {
     for (const presetName of presetNames) {
         presetHashes.set(presetName, hashPresetFile(presetName));
     }
-    const content = formatLabelsYaml(labels, presetHashes);
+    const content = formatLabelsYaml(labels, presetHashes, configPath);
     if (check) {
         return compareAgainstCommittedFile(content);
     }

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

@@ -1,6 +1,8 @@
 import { type StreamStyles } from '@williamthorsen/nmr-core';
 /** Options for the `sync-labels init` subcommand. */
 interface InitOptions {
+    /** Config file to read, relative to the working directory. Defaults to `CONFIG_FILE_PATH`. */
+    configPath?: string;
     dryRun: boolean;
     force: boolean;
     styles: StreamStyles;
@@ -9,9 +11,12 @@ interface InitOptions {
  * Run the `sync-labels init` subcommand.
  *
  * Discovers workspaces and retired packages, scaffolds the caller workflow, then seeds the
- * `repoLabels` block: into a new `.config/release-kit.config.ts` when none exists, or
- * printed to stdout for manual paste when the file is already there — an existing,
- * hand-authored config is never rewritten. Returns 0 on success, 1 on failure.
+ * `repoLabels` block: into a new config file when none exists, or printed to stdout for manual
+ * paste when the file is already there — an existing, hand-authored config is never rewritten.
+ * Returns 0 on success, 1 on failure.
+ *
+ * `configPath` names the config to read. Naming one that does not exist fails the command, so the
+ * scaffolding branch is reached only under the default path and always writes to `CONFIG_FILE_PATH`.
  */
-export declare function syncLabelsInitCommand({ dryRun, force, styles }: InitOptions): Promise<number>;
+export declare function syncLabelsInitCommand({ configPath, dryRun, force, styles }: InitOptions): Promise<number>;
 export {};