@williamthorsen/release-kit 14.2.2 → 14.2.4

package/dist/esm/help/overridesHelp.js

@@ -0,0 +1,32 @@
+export function showOverridesHelp() {
+    console.info(`
+Usage: release-kit overrides <subcommand> [options]
+
+Manage editorial changelog overrides.
+
+Subcommands:
+  validate      Validate every \`.meta/changelog-overrides.json\` file across all scopes
+
+Options:
+  --help, -h    Show this help message
+`);
+}
+export function showOverridesValidateHelp() {
+    console.info(`
+Usage: release-kit overrides validate
+
+Validate every \`.meta/changelog-overrides.json\` file across the project and per-workspace
+scopes. Reports schema/parse errors, ambiguous-prefix errors, conflicting-key errors, and
+stale-key warnings.
+
+Exit codes:
+  0    Clean: no errors, no stale keys
+  1    Stale-key warnings only (no errors)
+  2    Schema/parse, ambiguous-prefix, or conflicting-key errors (errors take precedence)
+
+Options:
+  --config <path>  Config file, relative to the current directory
+                   (default: .config/release-kit.config.ts at the repo root)
+  --help, -h       Show this help message
+`);
+}

package/dist/esm/help/releaseStepsHelp.d.ts

@@ -0,0 +1,12 @@
+/** Prints the `commit` command's help text. */
+export declare function showCommitHelp(): void;
+/** Prints the `create-github-release` command's help text. */
+export declare function showCreateGithubReleaseHelp(): void;
+/** Prints the `publish` command's help text. */
+export declare function showPublishHelp(): void;
+/** Prints the `push` command's help text. */
+export declare function showPushHelp(): void;
+/** Prints the `show-tag-prefixes` command's help text. */
+export declare function showShowTagPrefixesHelp(): void;
+/** Prints the `tag` command's help text. */
+export declare function showTagHelp(): void;

package/dist/esm/help/releaseStepsHelp.js

@@ -0,0 +1,91 @@
+export function showCommitHelp() {
+    console.info(`
+Usage: release-kit commit [options]
+
+Stage all changes and create the release commit using tags and summary
+produced by \`prepare\`.
+
+Options:
+  --dry-run     Preview the commit message without creating it
+  --help, -h    Show this help message
+`);
+}
+export function showCreateGithubReleaseHelp() {
+    console.info(`
+Usage: release-kit create-github-release [options]
+
+Create GitHub Releases from changelog.json for tags on HEAD. Private
+(package.json#private) workspaces are skipped with a warning, and the command
+doesn't create a Release for them. A project tag gets a Release even when the
+root package is private.
+
+Options:
+  --config <path>        Config file, relative to the current directory
+                         (default: .config/release-kit.config.ts at the repo root)
+  --dry-run              Preview without creating releases
+  --tags=tag1,tag2       Only create releases for the named tags (comma-separated, full tag names)
+  --help, -h             Show this help message
+`);
+}
+export function showPublishHelp() {
+    console.info(`
+Usage: release-kit publish [options]
+
+Publish packages that have release tags on HEAD. Operates only on workspaces whose
+package.json#private is absent or false. Without --tags, unpublishable workspaces are
+silently filtered out. With --tags, an unpublishable tag is skipped with a warning while
+any publishable tags are still published. A project tag is never published.
+
+Options:
+  --config <path>        Config file, relative to the current directory
+                         (default: .config/release-kit.config.ts at the repo root)
+  --dry-run              Preview without publishing
+  --no-git-checks        Skip the clean-working-tree check
+  --tags=tag1,tag2       Only publish the named tags (comma-separated, full tag names)
+  --provenance           Generate provenance statement (requires OIDC, not supported by classic yarn)
+  --help, -h             Show this help message
+`);
+}
+export function showPushHelp() {
+    console.info(`
+Usage: release-kit push [options]
+
+Push the release commit and each tag individually, so that GitHub Actions
+starts a separate workflow run for each tag.
+
+Options:
+  --config <path>        Config file, relative to the current directory
+                         (default: .config/release-kit.config.ts at the repo root)
+  --dry-run              Preview without pushing
+  --tags=tag1,tag2       Only push the named tags (comma-separated, full tag names)
+  --tags-only            Skip the branch push (push tags only)
+  --help, -h             Show this help message
+`);
+}
+export function showShowTagPrefixesHelp() {
+    console.info(`
+Usage: release-kit show-tag-prefixes [options]
+
+Print a per-workspace table of derived tag prefixes, tag counts, and declared
+legacy tag prefixes. Reports any release-shaped tags whose prefix is neither a
+derived prefix nor declared in \`legacyIdentities\`, with a copy-pasteable
+config snippet.
+
+Options:
+  --config <path>  Config file, relative to the current directory
+                   (default: .config/release-kit.config.ts at the repo root)
+  --help, -h       Show this help message
+`);
+}
+export function showTagHelp() {
+    console.info(`
+Usage: release-kit tag [options]
+
+Create annotated git tags from the tags file produced by \`prepare\`.
+
+Options:
+  --dry-run          Preview without creating tags
+  --no-git-checks    Skip dirty working tree check
+  --help, -h         Show this help message
+`);
+}

package/dist/esm/help/syncLabelsHelp.d.ts

@@ -0,0 +1,8 @@
+/** Prints the `sync-labels generate` subcommand's help text. */
+export declare function showSyncLabelsGenerateHelp(): void;
+/** Prints the `sync-labels` command's help text. */
+export declare function showSyncLabelsHelp(): void;
+/** Prints the `sync-labels init` subcommand's help text. */
+export declare function showSyncLabelsInitHelp(): void;
+/** Prints the `sync-labels sync` subcommand's help text. */
+export declare function showSyncLabelsSyncHelp(): void;

package/dist/esm/help/syncLabelsHelp.js

@@ -0,0 +1,55 @@
+export function showSyncLabelsGenerateHelp() {
+    console.info(`
+Usage: release-kit sync-labels generate [options]
+
+Regenerate .github/labels.yaml from the repoLabels block of .config/release-kit.config.ts.
+
+Options:
+  --check          Report whether .github/labels.yaml is stale instead of writing it
+  --config <path>  Config file, relative to the current directory
+                   (default: .config/release-kit.config.ts at the repo root)
+  --help, -h       Show this help message
+`);
+}
+export function showSyncLabelsHelp() {
+    console.info(`
+Usage: release-kit sync-labels <subcommand> [options]
+
+Manage GitHub label synchronization via preset and custom label definitions.
+
+Subcommands:
+  init          Scaffold caller workflow and config, then generate labels
+  generate      Regenerate .github/labels.yaml from config
+  sync          Trigger the sync-labels workflow via gh CLI
+
+Options:
+  --help, -h    Show this help message
+`);
+}
+export function showSyncLabelsInitHelp() {
+    console.info(`
+Usage: release-kit sync-labels init [options]
+
+Scaffold the sync-labels caller workflow and seed the repoLabels block of
+.config/release-kit.config.ts with scope labels discovered from workspaces and
+retired packages, then generate .github/labels.yaml. When the config file already
+exists, print the block for manual paste instead of rewriting the file.
+
+Options:
+  --config <path>  Config file, relative to the current directory
+                   (default: .config/release-kit.config.ts at the repo root)
+  --dry-run        Preview changes without writing files
+  --force          Overwrite existing files instead of skipping them
+  --help, -h       Show this help message
+`);
+}
+export function showSyncLabelsSyncHelp() {
+    console.info(`
+Usage: release-kit sync-labels sync
+
+Trigger the sync-labels GitHub Actions workflow via the gh CLI.
+
+Options:
+  --help, -h    Show this help message
+`);
+}

package/dist/esm/help/usage.d.ts

@@ -0,0 +1,2 @@
+/** Prints the top-level usage text. */
+export declare function showUsage(): void;

package/dist/esm/help/usage.js

@@ -0,0 +1,29 @@
+import { OUTPUT_STYLE_ENV_VAR } from "../resolveStylesOrExit.js";
+export function showUsage() {
+    console.info(`
+Usage: release-kit <command> [options]
+
+Commands:
+  prepare          Run release preparation (auto-discovers workspaces)
+  commit           Stage changes and create the release commit
+  tag              Create annotated git tags from the tags file
+  push             Push release commit and tags (one push per tag)
+  publish          Publish packages with release tags on HEAD
+  create-github-release  Create GitHub Releases from changelog.json for tags on HEAD
+  show-tag-prefixes  Show derived and declared legacy tag prefixes per workspace
+  init             Initialize release-kit in the current repository
+  update-templates Update the scaffolded workflows to the current templates
+  overrides        Manage editorial changelog overrides
+  sync-labels      Manage GitHub label synchronization
+
+Options:
+  --dry-run        Preview changes without writing files
+  --help, -h       Show this help message
+  --version, -V    Show the version number
+
+Environment:
+  ${OUTPUT_STYLE_ENV_VAR}
+                   Output style: auto (default), plain, or rich. auto prints plain,
+                   without emoji, when CI is set or the stream is not a terminal.
+`);
+}

package/dist/esm/index.d.ts

@@ -1,2 +1,2 @@
-export { type ChangelogOverrideScope, type OverrideTargetItem, validateAllChangelogOverrides, type ValidateAllChangelogOverridesInputs, type ValidateAllChangelogOverridesResult, } from './changelogOverrides.js';
+export { type ChangelogOverrideScope, type OverrideTargetItem, validateAllChangelogOverrides, type ValidateAllChangelogOverridesInputs, type ValidateAllChangelogOverridesResult, } from './validateAllChangelogOverrides.js';
 export { formatValidateOverridesResult, type ValidateOverridesCommandResult } from './validateOverridesCommand.js';

package/dist/esm/index.js

@@ -1,2 +1,2 @@
-export { validateAllChangelogOverrides, } from "./changelogOverrides.js";
+export { validateAllChangelogOverrides, } from "./validateAllChangelogOverrides.js";
 export { formatValidateOverridesResult } from "./validateOverridesCommand.js";

package/dist/esm/loadChangelogOverrides.d.ts

@@ -0,0 +1,31 @@
+import type { ChangelogOverride } from './types.js';
+/** Known fields on a single override entry; presence of any other field is a validation error. */
+export declare const KNOWN_OVERRIDE_FIELDS: Set<string>;
+/**
+ * Loads and validates the editorial overrides file at `path`. A missing file yields an empty map; an unreadable file,
+ * malformed JSON, a wrong top-level shape, or any per-entry validation failure yields errors.
+ */
+export declare function loadChangelogOverrides(path: string): LoadChangelogOverridesResult;
+/** Result of loading an override file: either parsed overrides or a list of structured errors. */
+export type LoadChangelogOverridesResult = {
+    overrides: Map<string, ChangelogOverride>;
+} | {
+    errors: string[];
+};
+/** Form of an override key: a lowercase hex commit hash or prefix, optionally followed by `:<n>`, a 1-based entry position. */
+export declare const OVERRIDE_KEY_PATTERN: RegExp;
+/** Splits a valid override key into its hash prefix and, for an ordinal key, its 1-based entry position. */
+export declare function parseOverrideKey(key: string): {
+    hashPrefix: string;
+    entry?: number;
+};
+/**
+ * Validates a parsed override record, returning the valid overrides and an error message for each problem.
+ *
+ * Each error names the offending key (e.g. `overrides['abc']: 'audience' must be one of …`) so that the user can find
+ * it in the override file.
+ */
+export declare function validateChangelogOverrides(raw: unknown): {
+    overrides: Map<string, ChangelogOverride>;
+    errors: string[];
+};

package/dist/esm/loadChangelogOverrides.js

@@ -0,0 +1,138 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { isRecord } from "./typeGuards.js";
+const VALID_AUDIENCE_VALUES = new Set(['all', 'dev', 'skip']);
+const V1_SUPPORTED_AUDIENCE_VALUES = new Set(['skip']);
+const SCHEMA_KEY = '$schema';
+export const KNOWN_OVERRIDE_FIELDS = new Set(['audience', 'description', 'body', 'breaking']);
+export function loadChangelogOverrides(path) {
+    if (!existsSync(path)) {
+        return { overrides: new Map() };
+    }
+    let content;
+    try {
+        content = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        return {
+            errors: [`Failed to read override file ${path}: ${describeError(error)}`],
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (error) {
+        return {
+            errors: [`Failed to parse override file ${path}: ${describeError(error)}`],
+        };
+    }
+    const result = validateChangelogOverrides(parsed);
+    if (result.errors.length > 0) {
+        return { errors: result.errors };
+    }
+    return { overrides: result.overrides };
+}
+export const OVERRIDE_KEY_PATTERN = /^[0-9a-f]+(:[1-9][0-9]*)?$/;
+export function parseOverrideKey(key) {
+    const separatorIndex = key.indexOf(':');
+    if (separatorIndex === -1) {
+        return { hashPrefix: key };
+    }
+    return { hashPrefix: key.slice(0, separatorIndex), entry: Number(key.slice(separatorIndex + 1)) };
+}
+export function validateChangelogOverrides(raw) {
+    const overrides = new Map();
+    const errors = [];
+    if (!isRecord(raw)) {
+        errors.push('Override file: top-level value must be an object keyed by commit hash');
+        return { overrides, errors };
+    }
+    for (const [key, rawEntry] of Object.entries(raw)) {
+        if (key === SCHEMA_KEY) {
+            if (typeof rawEntry !== 'string') {
+                errors.push(`Override file: '${SCHEMA_KEY}' must be a string`);
+            }
+            continue;
+        }
+        if (!OVERRIDE_KEY_PATTERN.test(key)) {
+            errors.push(`overrides['${key}']: key must be a lowercase hex commit hash or prefix, optionally followed by ':<n>'`);
+            continue;
+        }
+        const validated = validateSingleOverride(key, rawEntry, errors);
+        if (validated !== undefined) {
+            overrides.set(key, validated);
+        }
+    }
+    return { overrides, errors };
+}
+function validateAudience(key, value, errors) {
+    if (typeof value !== 'string' || !VALID_AUDIENCE_VALUES.has(value)) {
+        errors.push(`overrides['${key}']: 'audience' must be one of 'all' | 'dev' | 'skip'`);
+        return undefined;
+    }
+    if (!V1_SUPPORTED_AUDIENCE_VALUES.has(value)) {
+        errors.push(`overrides['${key}']: audience '${value}' is not yet supported; only 'skip' is currently accepted`);
+        return undefined;
+    }
+    return 'skip';
+}
+function validateSingleOverride(key, rawEntry, errors) {
+    if (!isRecord(rawEntry)) {
+        errors.push(`overrides['${key}']: must be an object`);
+        return undefined;
+    }
+    let entryValid = true;
+    for (const fieldName of Object.keys(rawEntry)) {
+        if (KNOWN_OVERRIDE_FIELDS.has(fieldName)) {
+            continue;
+        }
+        errors.push(`overrides['${key}']: unknown field '${fieldName}'`);
+        entryValid = false;
+    }
+    const result = {};
+    if (rawEntry['audience'] !== undefined) {
+        const audienceResult = validateAudience(key, rawEntry['audience'], errors);
+        if (audienceResult === undefined) {
+            entryValid = false;
+        }
+        else {
+            result.audience = audienceResult;
+        }
+    }
+    if (rawEntry['description'] !== undefined) {
+        if (typeof rawEntry['description'] !== 'string') {
+            errors.push(`overrides['${key}']: 'description' must be a string`);
+            entryValid = false;
+        }
+        else {
+            result.description = rawEntry['description'];
+        }
+    }
+    if (rawEntry['body'] !== undefined) {
+        if (typeof rawEntry['body'] !== 'string') {
+            errors.push(`overrides['${key}']: 'body' must be a string`);
+            entryValid = false;
+        }
+        else {
+            result.body = rawEntry['body'];
+        }
+    }
+    if (rawEntry['breaking'] !== undefined) {
+        if (typeof rawEntry['breaking'] !== 'boolean') {
+            errors.push(`overrides['${key}']: 'breaking' must be a boolean`);
+            entryValid = false;
+        }
+        else {
+            result.breaking = rawEntry['breaking'];
+        }
+    }
+    if (Object.keys(result).length === 0 && entryValid) {
+        errors.push(`overrides['${key}']: at least one override field must be set`);
+        return undefined;
+    }
+    if (!entryValid) {
+        return undefined;
+    }
+    return result;
+}

package/dist/esm/loadConfig.d.ts

@@ -1,4 +1,3 @@
-import type { MonorepoReleaseConfig, ReleaseKitConfig, ReleaseSettings, WorkTypeConfig } from './types.js';
 /** Path of the root `package.json` consulted when validating a `project` block. */
 export declare const ROOT_PACKAGE_JSON_PATH = "package.json";
 /**
@@ -25,42 +24,3 @@ export declare const CONFIG_FILE_PATH = ".config/release-kit.config.ts";
  * imported, or exports neither a default nor a named `config`.
  */
 export declare function loadConfig(configPath?: string): Promise<unknown>;
-/**
- * Information about the root `package.json` passed into `mergeMonorepoConfig` when a
- * `project` block is configured. `readRootPackageVersion` performs the read, so that
- * `mergeMonorepoConfig` does not perform any I/O.
- */
-export interface RootPackageInfo {
-    exists: boolean;
-    version: string | undefined;
-}
-/**
- * Resolves a final monorepo config from discovered workspaces and an optional user config overlay.
- *
- * Merging rules:
- * - Release targets: `resolveReleaseDeclaration` projects the `releases` block, or the `workspaces` overrides and the
- *   `project` block, onto the discovered workspaces. Excluded workspaces move to `excludedWorkspaces`, and the
- *   directories that `releases` declares resolve through `deriveDirectoryConfig` into `directories`, which must not
- *   share a version file with any other target.
- * - `workTypes`: Shallow merge; consumer entries override or add to defaults by key.
- * - `versionPatterns`: Consumer value replaces defaults entirely.
- * - Pass-through fields (see `applyOptionalPassthroughFields`): Consumer value wins.
- * - `project`: Present iff the config declares a composite. Resolves `tagPrefix` to `DEFAULT_PROJECT_TAG_PREFIX` and
- *   `paths` to the union of its members' `paths` when omitted. Requires `rootPackage` to be passed and to contain a
- *   valid `version` field; throws otherwise. The resolved prefix is included in the strict-prefix collision check
- *   across all workspace and retired-package prefixes.
- */
-export declare function mergeMonorepoConfig(discoveredPaths: string[], userConfig: ReleaseKitConfig | undefined, rootPackage?: RootPackageInfo): MonorepoReleaseConfig;
-/**
- * Resolves the release settings of a single-package repo from an optional user config overlay.
- *
- * Rejects a configured `project` or `releases` block: Both declare the targets of a monorepo, and a single-package
- * repo has one target, its root package.
- */
-export declare function mergeSinglePackageConfig(userConfig: ReleaseKitConfig | undefined): ReleaseSettings;
-/**
- * Merges consumer work-type overrides onto `DEFAULT_WORK_TYPES`.
- *
- * Preserves the declaration order of defaults; net-new consumer keys append at the end.
- */
-export declare function resolveWorkTypes(userWorkTypes?: ReleaseKitConfig['workTypes']): Record<string, WorkTypeConfig>;