@williamthorsen/release-kit 10.9.0 → 11.0.0

package/dist/esm/pushCommand.js

@@ -8,11 +8,11 @@ const pushFlagSchema = {
     tags: { long: '--tags', type: 'string' },
     tagsOnly: { long: '--tags-only', type: 'boolean' },
 };
-export async function pushCommand(argv) {
+export function pushCommand(argv) {
     const parsed = parseArgsOrExit(argv, pushFlagSchema);
     const { dryRun, tagsOnly } = parsed.flags;
     const requestedTags = parseRequestedTags(parsed.flags.tags);
-    const resolvedTags = await resolveCommandTags(requestedTags);
+    const resolvedTags = resolveCommandTags(requestedTags);
     if (resolvedTags.length === 0) {
         return;
     }

package/dist/esm/reportPrepare.js

@@ -1,8 +1,9 @@
-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) {
@@ -129,7 +130,7 @@ function formatProjectUnparseable(lines, project, style) {
     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;
+        const truncatedMessage = truncateSubject(commit.message);
         lines.push(`      · ${shortHash} ${truncatedMessage}`);
     }
 }
@@ -231,7 +232,7 @@ function formatUnparseableWarning(lines, workspace, style, indent = '') {
     lines.push(`${indent}  ${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;
+        const truncatedMessage = truncateSubject(commit.message);
         lines.push(`${indent}    · ${shortHash} ${truncatedMessage}`);
     }
 }
@@ -244,7 +245,7 @@ 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;
+        const truncatedSubject = truncateSubject(subject);
         lines.push(`${indent}    · ${shortHash} '${truncatedSubject}' — type '${violation.type}' at ${violation.surface} surface`);
     }
 }
@@ -280,3 +281,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 {};

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

@@ -1,47 +1,52 @@
 import { existsSync } from 'node:fs';
 import { reportWriteResult, writeFileWithCheck } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
-import { discoverWorkspaces } from "../discoverWorkspaces.js";
+import { describeEmptyWorkspace, discoverWorkspaces } from "../discoverWorkspaces.js";
 import { CONFIG_FILE_PATH } from "../loadConfig.js";
-import { loadValidatedConfig } from "../loadValidatedConfig.js";
+import { loadValidatedConfig, reportConfigProblem } from "../loadValidatedConfig.js";
 import { generateCommand, LABELS_OUTPUT_PATH } from "./generateCommand.js";
 import { checkRetiredSyncLabelsConfig } from "./retiredConfig.js";
 import { buildScopeLabels, renderRepoLabelsBlock, repoLabelsConfigScript, syncLabelsWorkflow } from "./templates.js";
 const WORKFLOW_PATH = '.github/workflows/sync-labels.yaml';
-export async function syncLabelsInitCommand({ dryRun, force, styles }) {
-    if (checkRetiredSyncLabelsConfig()) {
+export async function syncLabelsInitCommand({ configPath, dryRun, force, styles }) {
+    const configFilePath = configPath ?? CONFIG_FILE_PATH;
+    if (checkRetiredSyncLabelsConfig(configPath)) {
         return 1;
     }
     if (dryRun) {
         console.info('[dry-run mode]');
     }
     console.info('\n> Discovering workspaces');
-    let workspacePaths;
+    let workspace;
     try {
-        workspacePaths = await discoverWorkspaces();
+        workspace = discoverWorkspaces();
     }
     catch (error) {
         const message = describeError(error);
         process.stderr.write(`  Failed to discover workspaces: ${message}\n`);
         return 1;
     }
-    if (workspacePaths === undefined) {
+    if (workspace.kind === 'empty') {
+        process.stderr.write(`  No workspace package to label. ${describeEmptyWorkspace(workspace)}\n`);
+        return 1;
+    }
+    if (workspace.kind === 'single-package') {
         console.info('  No pnpm workspaces found (single-package repo)');
     }
     else {
-        console.info(`  Found ${String(workspacePaths.length)} workspaces`);
+        console.info(`  Found ${String(workspace.packageDirs.length)} workspaces`);
     }
-    const configExists = existsSync(CONFIG_FILE_PATH);
-    const retiredNames = configExists ? await loadRetiredPackageNames(styles) : [];
+    const configExists = configPath !== undefined || existsSync(CONFIG_FILE_PATH);
+    const retiredNames = configExists ? await loadRetiredPackageNames(styles, configPath) : [];
     if (retiredNames === undefined) {
         return 1;
     }
-    const scopeLabels = workspacePaths === undefined ? [] : buildScopeLabels(workspacePaths, retiredNames);
+    const scopeLabels = workspace.kind === 'single-package' ? [] : buildScopeLabels(workspace.packageDirs, retiredNames);
     console.info('\n> Scaffolding files');
     const workflowResult = writeFileWithCheck(WORKFLOW_PATH, syncLabelsWorkflow(), { dryRun, overwrite: force });
     reportWriteResult(workflowResult, dryRun, styles);
     if (configExists) {
-        console.info(`\n> ${CONFIG_FILE_PATH} already exists; add this block to the object passed to defineConfig:\n`);
+        console.info(`\n> ${configFilePath} already exists; add this block to the object passed to defineConfig:\n`);
         console.info(renderRepoLabelsBlock(scopeLabels));
         if (workflowResult.outcome === 'failed') {
             process.stderr.write('Failed to scaffold one or more files.\n');
@@ -49,7 +54,7 @@ export async function syncLabelsInitCommand({ dryRun, force, styles }) {
         }
         console.info(`
 > Next steps
-  1. Paste the block above into ${CONFIG_FILE_PATH}.
+  1. Paste the block above into ${configFilePath}.
   2. Run \`release-kit sync-labels generate\` to produce ${LABELS_OUTPUT_PATH}.
   3. Commit the changes.
   4. Run \`release-kit sync-labels sync\` to apply labels to your GitHub repo.
@@ -87,9 +92,10 @@ export async function syncLabelsInitCommand({ dryRun, force, styles }) {
 `);
     return 0;
 }
-async function loadRetiredPackageNames(styles) {
-    const result = await loadValidatedConfig(styles.stderr);
+async function loadRetiredPackageNames(styles, configPath) {
+    const result = await loadValidatedConfig(configPath);
     if (result.status === 'invalid') {
+        reportConfigProblem(result.problem, styles.stderr);
         return undefined;
     }
     if (result.status === 'missing') {

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

@@ -5,6 +5,8 @@ export declare const RETIRED_SYNC_LABELS_CONFIG_PATH = ".config/sync-labels.conf
  *
  * Returns `true` when the file exists, in which case the caller must abort. The check is
  * unconditional on config content: file presence alone triggers it, so a half-migrated
- * repo cannot silently lose its custom labels.
+ * repo cannot silently lose its custom labels. `configPath` names the config to move the labels
+ * into; it defaults to `CONFIG_FILE_PATH`, which `sync-labels sync` relies on because it takes
+ * no `--config`.
  */
-export declare function checkRetiredSyncLabelsConfig(): boolean;
+export declare function checkRetiredSyncLabelsConfig(configPath?: string): boolean;

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

@@ -2,10 +2,10 @@ import { existsSync } from 'node:fs';
 import { reportError } from '@williamthorsen/nmr-core';
 import { CONFIG_FILE_PATH } from "../loadConfig.js";
 export const RETIRED_SYNC_LABELS_CONFIG_PATH = '.config/sync-labels.config.ts';
-export function checkRetiredSyncLabelsConfig() {
+export function checkRetiredSyncLabelsConfig(configPath = CONFIG_FILE_PATH) {
     if (!existsSync(RETIRED_SYNC_LABELS_CONFIG_PATH)) {
         return false;
     }
-    reportError(`${RETIRED_SYNC_LABELS_CONFIG_PATH} is no longer read. Move its labels into the \`repoLabels\` block of ${CONFIG_FILE_PATH} (presets move to \`repoLabels.extends\`; each label becomes a \`'name': { color, description }\` entry under \`repoLabels.labels\`), then delete the file.`);
+    reportError(`${RETIRED_SYNC_LABELS_CONFIG_PATH} is no longer read. Move its labels into the \`repoLabels\` block of ${configPath} (presets move to \`repoLabels.extends\`; each label becomes a \`'name': { color, description }\` entry under \`repoLabels.labels\`), then delete the file.`);
     return true;
 }

package/dist/esm/validateOverridesCommand.d.ts

@@ -1,5 +1,7 @@
 import { type OutputStyle, type StreamStyles } from '@williamthorsen/nmr-core';
 import { type ValidateAllChangelogOverridesInputs, type ValidateAllChangelogOverridesResult } from './changelogOverrides.js';
+import { type WorkspaceDiscovery } from './discoverWorkspaces.js';
+import { type LoadValidatedConfigResult } from './loadValidatedConfig.js';
 import type { ChangelogEntry, ReleaseConfig } from './types.js';
 /**
  * Result of {@link validateOverridesCommand}: tiered exit code paired with a human-readable
@@ -16,8 +18,8 @@ export interface ValidateOverridesCommandResult {
 }
 /** Injection seams for unit testing. Production callers leave defaults; tests substitute deterministic fakes. */
 export interface ValidateOverridesCommandDependencies {
-    discoverWorkspaces?: () => Promise<string[] | undefined>;
-    loadConfig?: () => Promise<unknown>;
+    discoverWorkspaces?: () => WorkspaceDiscovery;
+    loadValidatedConfig?: () => Promise<LoadValidatedConfigResult>;
     /**
      * Build changelog entries for a scope. Defaults to `buildChangelogEntries`, the same path
      * `release-kit prepare` uses — anchoring `validate`'s hash universe to `prepare`'s by
@@ -34,9 +36,13 @@ export interface ValidateOverridesCommandDependencies {
  * {@link validateAllChangelogOverrides}.
  *
  * Single-package and monorepo modes are handled uniformly: single-package collapses to one
- * project scope; monorepo expands to a project scope plus one scope per workspace.
+ * project scope; monorepo expands to a project scope plus one scope per workspace. A workspace declaring
+ * patterns that resolve to no package is neither, and exits `2`.
+ *
+ * `configPath` names the config file to read, relative to the working directory; it defaults to
+ * `CONFIG_FILE_PATH`.
  */
-export declare function validateOverridesCommand(styles: StreamStyles, dependencies?: ValidateOverridesCommandDependencies): Promise<ValidateOverridesCommandResult>;
+export declare function validateOverridesCommand(styles: StreamStyles, configPath?: string, dependencies?: ValidateOverridesCommandDependencies): Promise<ValidateOverridesCommandResult>;
 /**
  * Pure formatter — take an aggregated validation result, return the tiered exit code and a
  * rendered message. Exported for unit testing without going through the full discovery path.

package/dist/esm/validateOverridesCommand.js

@@ -2,43 +2,40 @@ import { formatErrorLine, formatStatusLine } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { buildChangelogEntries } from "./buildChangelogEntries.js";
 import { resolveOverridePath, validateAllChangelogOverrides, } from "./changelogOverrides.js";
-import { discoverWorkspaces } from "./discoverWorkspaces.js";
+import { describeEmptyWorkspace, discoverWorkspaces } from "./discoverWorkspaces.js";
 import { buildTagPattern, getAllTagPrefixes } from "./generateChangelogs.js";
-import { loadConfig, mergeMonorepoConfig, mergeSinglePackageConfig, readRootPackageVersion } from "./loadConfig.js";
-import { validateConfig } from "./validateConfig.js";
+import { mergeMonorepoConfig, mergeSinglePackageConfig, readRootPackageVersion } from "./loadConfig.js";
+import { loadValidatedConfig } from "./loadValidatedConfig.js";
 const SYNTHETIC_VALIDATE_TAG = 'validate-only';
-export async function validateOverridesCommand(styles, dependencies = {}) {
+export async function validateOverridesCommand(styles, configPath, dependencies = {}) {
     const discover = dependencies.discoverWorkspaces ?? discoverWorkspaces;
-    const load = dependencies.loadConfig ?? loadConfig;
+    const load = dependencies.loadValidatedConfig ?? (() => loadValidatedConfig(configPath));
     const buildEntries = dependencies.buildEntries ?? defaultBuildEntries;
     const validate = dependencies.validate ?? validateAllChangelogOverrides;
-    let rawConfig;
-    try {
-        rawConfig = await load();
-    }
-    catch (error) {
-        return { exitCode: 2, message: formatErrorLine(`Failed to load config: ${describeError(error)}`) };
-    }
-    let userConfig;
-    try {
-        userConfig = validateLoadedConfig(rawConfig);
-    }
-    catch (error) {
-        return { exitCode: 2, message: describeError(error) };
+    const configResult = await load();
+    if (configResult.status === 'invalid') {
+        return { exitCode: 2, message: formatConfigProblem(configResult.problem) };
     }
-    let discoveredPaths;
+    const userConfig = configResult.status === 'ok' ? configResult.config : undefined;
+    let workspace;
     try {
-        discoveredPaths = await discover();
+        workspace = discover();
     }
     catch (error) {
         return { exitCode: 2, message: formatErrorLine(`Failed to discover workspaces: ${describeError(error)}`) };
     }
+    if (workspace.kind === 'empty') {
+        return {
+            exitCode: 2,
+            message: formatErrorLine(`No workspace package to validate. ${describeEmptyWorkspace(workspace)}`),
+        };
+    }
     let inputs;
     try {
         inputs =
-            discoveredPaths === undefined
+            workspace.kind === 'single-package'
                 ? buildSinglePackageInputs(userConfig, buildEntries)
-                : buildMonorepoInputs(discoveredPaths, userConfig, buildEntries);
+                : buildMonorepoInputs(workspace.packageDirs, userConfig, buildEntries);
     }
     catch (error) {
         return { exitCode: 2, message: formatErrorLine(`Failed to resolve overrides scope: ${describeError(error)}`) };
@@ -94,15 +91,10 @@ function flattenEntriesToHashes(entries) {
     }
     return hashes;
 }
-function validateLoadedConfig(rawConfig) {
-    if (rawConfig === undefined) {
-        return undefined;
-    }
-    const { config, errors } = validateConfig(rawConfig);
-    if (errors.length > 0) {
-        throw new Error(`Invalid config:\n  - ${errors.join('\n  - ')}`);
-    }
-    return config;
+function formatConfigProblem(problem) {
+    return problem.kind === 'load'
+        ? formatErrorLine(`Failed to load config: ${problem.message}`)
+        : `Invalid config:\n  - ${problem.errors.join('\n  - ')}`;
 }
 function buildSinglePackageInputs(userConfig, buildEntries) {
     const config = mergeSinglePackageConfig(userConfig);

package/docs/configuration.md

@@ -4,6 +4,16 @@ The fields of `.config/release-kit.config.ts`, how a workspace declares its prio
 
 A minimal config file is in the [README](../README.md#configuration).
 
+## Config file location
+
+release-kit reads `.config/release-kit.config.ts`, resolved against the working directory. A run reads a different file when the subcommand is given `--config <path>`, which is also resolved against the working directory.
+
+The flag is accepted by every subcommand that reads a config: `prepare`, `publish`, `create-github-release`, `show-tag-prefixes`, `overrides validate`, `sync-labels init`, and `sync-labels generate`. `commit`, `tag`, `push`, and `sync-labels sync` read no config and reject it.
+
+The two paths differ in what an absent file means. An absent default path means the repo declares no config, and the run proceeds on discovered defaults. An absent `--config` path fails the command with an error naming the resolved path, because a caller who names a file expects that file to be read. A file that exists and fails validation is an error on both paths alike, and so is one that exists and fails to load.
+
+`--config` names a file to read, never a write target. `release-kit init --with-config` scaffolds to `.config/release-kit.config.ts` and takes no `--config`, and `sync-labels init` writes its seeded `repoLabels` block to that same path.
+
 ## `ReleaseKitConfig` reference
 
 | Field              | Type                                                      | Description                                                                                                                                                                                   |
@@ -89,6 +99,8 @@ Print a per-workspace table of derived tag prefixes, tag counts, and declared le
 
 Exits `0` when every workspace derives a prefix and there are no cross-workspace collisions; exits `1` on any derivation failure or collision. Undeclared candidates do not affect the exit code — they surface as a warning via the `legacy tag prefixes are declared` readyup check.
 
+A config file that exists and either fails to load or fails schema validation reports the failure on stderr and exits `1`, printing no preview, because a config that cannot be read leaves the declared-versus-undeclared verdict wrong in the one dimension the command exists to report on. That holds on the default path and under `--config`, and in single-package mode as well as monorepo mode. An absent default config is a supported state and still previews against derived defaults.
+
 In single-package mode, prints a single row with `workspacePath = .` and `derivedPrefix = v`; legacy entries and undeclared-candidate scanning are not applicable.
 
 ## `VersionPatterns`