@williamthorsen/release-kit 11.0.0 → 13.0.0

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('/');
+}

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

@@ -8,15 +8,14 @@ interface InitOptions {
     styles: StreamStyles;
 }
 /**
- * Run the `sync-labels init` subcommand.
+ * Runs the `sync-labels init` subcommand and returns the process exit code.
  *
- * Discovers workspaces and retired packages, scaffolds the caller workflow, then seeds the
- * `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.
+ * Scaffolds the caller workflow and seeds the `repoLabels` block with scope labels for the workspaces and retired
+ * packages. The block goes into a new config file when none exists; an existing config is never rewritten, so the
+ * command prints the block for manual paste instead.
  *
- * `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`.
+ * `configPath` names the config to read. Because the command fails when the named config does not exist, it
+ * reaches the scaffolding branch only under the default path, and that branch always writes to `CONFIG_FILE_PATH`.
  */
 export declare function syncLabelsInitCommand({ configPath, dryRun, force, styles }: InitOptions): Promise<number>;
 export {};

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

@@ -57,7 +57,7 @@ export async function syncLabelsInitCommand({ configPath, dryRun, force, styles
   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.
+  4. Run \`release-kit sync-labels sync\` to apply labels to the GitHub repo.
 `);
         return 0;
     }
@@ -88,7 +88,7 @@ export async function syncLabelsInitCommand({ configPath, dryRun, force, styles
      - ${LABELS_OUTPUT_PATH}
   2. Customize the \`repoLabels\` block in ${CONFIG_FILE_PATH} as needed, then re-run \`release-kit sync-labels generate\`.
   3. Commit the generated files.
-  4. Run \`release-kit sync-labels sync\` to apply labels to your GitHub repo.
+  4. Run \`release-kit sync-labels sync\` to apply labels to the GitHub repo.
 `);
     return 0;
 }

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

@@ -1,9 +1,10 @@
 import type { LabelDefinition } from './types.js';
-/** Computes SHA-256 hex digest of a preset file's raw content. Throws if the preset does not exist. */
-export declare function hashPresetFile(presetName: string): string;
+/** Computes the SHA-256 hex digest of a preset's resolved labels. Throws as `loadPreset` does. */
+export declare function hashPreset(presetName: string): string;
 /**
- * Loads a named preset from the bundled YAML files.
+ * Loads a named preset from the bundled YAML files. The `common` preset also defines the label of every work type in
+ * change-grammar's taxonomy, ahead of the labels in its file.
  *
- * Returns the parsed label definitions. Throws if the preset does not exist or has invalid content.
+ * Throws if the preset does not exist or has invalid content.
  */
 export declare function loadPreset(presetName: string): LabelDefinition[];

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

@@ -1,22 +1,22 @@
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { CANONICAL_TAXONOMY } from '@williamthorsen/change-grammar';
 import { findPackageRoot } from '@williamthorsen/nmr-core';
 import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
 import { parse } from 'yaml';
 import { isRecord } from "../typeGuards.js";
-export function hashPresetFile(presetName) {
-    const presetPath = resolvePresetPath(presetName);
-    if (!existsSync(presetPath)) {
-        throw new Error(`Unknown preset "${presetName}". No file found at ${presetPath}`);
-    }
-    const content = readFileSync(presetPath, 'utf8');
-    return createHash('sha256').update(content).digest('hex');
+import { deriveTypeLabels } from "./typeLabels.js";
+const TYPE_LABELS_PRESET = 'common';
+export function hashPreset(presetName) {
+    return createHash('sha256')
+        .update(JSON.stringify(loadPreset(presetName)))
+        .digest('hex');
 }
 export function loadPreset(presetName) {
     const presetPath = resolvePresetPath(presetName);
     if (!existsSync(presetPath)) {
-        throw new Error(`Unknown preset "${presetName}". No file found at ${presetPath}`);
+        throw new Error(`Unknown preset "${presetName}". The file ${presetPath} does not exist`);
     }
     let content;
     try {
@@ -42,7 +42,7 @@ export function loadPreset(presetName) {
         }
         labels.push({ name, color, ...(description !== undefined && { description }) });
     }
-    return labels;
+    return presetName === TYPE_LABELS_PRESET ? [...deriveTypeLabels(CANONICAL_TAXONOMY), ...labels] : labels;
 }
 function resolvePresetPath(presetName) {
     const root = findPackageRoot(import.meta.url);

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

@@ -3,13 +3,13 @@ import type { LabelDefinition } from './types.js';
 /**
  * Resolves the repository's label set from a `repoLabels` config block.
  *
- * Resolution is an ordered fold with last-writer-wins: presets are loaded in `extends` order (a later preset replaces
+ * Resolution is an ordered fold with last-writer-wins: Presets are loaded in `extends` order (a later preset replaces
  * an earlier preset's label of the same name), then the `labels` record is applied: An entry adds a label, replaces
- * one an earlier layer defined, or removes it (`null`). Names match case-insensitively, as GitHub matches them, and the
- * replacing layer's spelling becomes the label's name. Replacement is wholesale, so an entry omitting `description`
- * drops the one an earlier layer supplied rather than inheriting it.
- * Throws on two misstatements that would otherwise leave no trace in the output diff: keys in the `labels` record that
- * differ only in case, all but one of which the fold would discard, and a dangling `null`, a removal naming a label that
- * no preset defined.
+ * one that an earlier layer defined, or removes it (`null`). Names match case-insensitively, as GitHub matches them,
+ * and the replacing layer's spelling becomes the label's name. Replacement is wholesale, so an entry omitting
+ * `description` drops the one that an earlier layer supplied rather than inheriting it.
+ * Throws on two misstatements that the output diff would otherwise not show: keys in the `labels` record that differ
+ * only in case, all but one of which the fold would discard, and a dangling `null`, a removal naming a label that the
+ * `extends` presets did not define.
  */
 export declare function resolveLabels(config: RepoLabelsConfig): LabelDefinition[];

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

@@ -17,7 +17,7 @@ export function resolveLabels(config) {
         const key = toLabelKey(name);
         if (spec === null) {
             if (!resolved.has(key)) {
-                throw new Error(`Label '${name}' is set to null (remove), but no preset in 'extends' defines it. Fix the name or delete the entry.`);
+                throw new Error(`Label '${name}' is set to null (remove), but the presets in 'extends' don't define it. Fix the name or delete the entry.`);
             }
             resolved.delete(key);
         }

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

@@ -1,12 +1,11 @@
 /** Path of the retired standalone sync-labels config file. */
 export declare const RETIRED_SYNC_LABELS_CONFIG_PATH = ".config/sync-labels.config.ts";
 /**
- * Report an actionable migration error when the retired standalone config file is present.
+ * Reports an actionable migration error when the retired standalone config file is present.
  *
  * 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. `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`.
+ * unconditional on config content: File presence alone triggers it, so a half-migrated
+ * repo cannot silently lose its custom labels. `configPath` names the config into which the
+ * message directs the labels.
  */
 export declare function checkRetiredSyncLabelsConfig(configPath?: string): boolean;

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

@@ -1,7 +1,4 @@
 /**
- * Run the `sync-labels sync` subcommand.
- *
- * Validates prerequisites (gh CLI, workflow file), then triggers the sync-labels workflow
- * via `gh workflow run`. Returns 0 on success, 1 on failure.
+ * Runs the `sync-labels sync` subcommand, which triggers the sync-labels workflow, and returns the process exit code.
  */
 export declare function syncLabelsCommand(): number;

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

@@ -5,8 +5,8 @@ export declare function syncLabelsWorkflow(): string;
  * Generates scope labels from workspace paths and retired-package names.
  *
  * Workspace labels are named after the path basename; retired-package labels after the unscoped package name.
- * None carries a description: GitHub renders a described label taller and more prominently than a bare one, and
- * the scope labels are meant to read as a compact group.
+ * None has a description: GitHub renders a described label taller and more prominently than a bare one, and
+ * the scope labels are meant to appear as a compact group.
  * Describing only the retired scopes would single them out for that prominence.
  */
 export declare function buildScopeLabels(workspacePaths: string[], retiredNames?: string[]): LabelDefinition[];
@@ -15,5 +15,5 @@ export declare function buildScopeLabels(workspacePaths: string[], retiredNames?
  * `.config/release-kit.config.ts`.
  */
 export declare function renderRepoLabelsBlock(scopeLabels: LabelDefinition[]): string;
-/** Generates a new `.config/release-kit.config.ts` carrying the `repoLabels` block. */
+/** Generates a new `.config/release-kit.config.ts` containing the `repoLabels` block. */
 export declare function repoLabelsConfigScript(scopeLabels: LabelDefinition[]): string;

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

@@ -6,7 +6,7 @@ name: Sync labels
 on:
   workflow_dispatch:
 
-  # Apply on merge, so that a regenerated labels file cannot sit unapplied.
+  # Apply on merge, so that the repository's labels match each merged version of the labels file.
   push:
     paths:
       - .github/labels.yaml
@@ -19,8 +19,8 @@ on:
 # Permissions are fixed when a run is created and cannot vary by trigger within a job,
 # so applying and previewing are separate jobs.
 jobs:
-  # The push arm applies on the default branch alone. A \`branches:\` filter cannot name the default branch,
-  # so that the gate lives on the job and this file stays identical across repos.
+  # The push arm applies on the default branch alone. The job's \`if:\` names that branch through the event payload,
+  # which keeps this file identical across repos; a \`branches:\` filter would have to name it literally.
   sync:
     if: github.event_name != 'pull_request' && (github.event_name != 'push' || github.ref_name == github.event.repository.default_branch)
     permissions:

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

@@ -0,0 +1,14 @@
+import type { CanonicalWorkTypeEntry } from '@williamthorsen/change-grammar';
+import type { LabelDefinition } from './types.js';
+/**
+ * Builds one label per work type, named by the type's tracker label. A type without a presentation row gets its
+ * tier's default color and does not get a description.
+ */
+export declare function deriveTypeLabels(taxonomy: {
+    types: readonly Pick<CanonicalWorkTypeEntry, 'key' | 'tier' | 'trackerLabel'>[];
+}): LabelDefinition[];
+/** Color and description of each work type's label, keyed by work-type key. Descriptions fit GitHub's 100 characters. */
+export declare const TYPE_LABEL_PRESENTATION: Readonly<Record<string, {
+    color: string;
+    description: string;
+}>>;

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

@@ -0,0 +1,38 @@
+const FALLBACK_COLOR = 'ededed';
+const TIER_DEFAULT_COLORS = {
+    internal: '1d76db',
+    process: 'edc287',
+    public: '0075ca',
+};
+export function deriveTypeLabels(taxonomy) {
+    return taxonomy.types.map(({ key, tier, trackerLabel }) => {
+        const presentation = TYPE_LABEL_PRESENTATION[key];
+        if (presentation === undefined) {
+            return { name: trackerLabel, color: TIER_DEFAULT_COLORS[tier] ?? FALLBACK_COLOR };
+        }
+        return { name: trackerLabel, ...presentation };
+    });
+}
+export const TYPE_LABEL_PRESENTATION = {
+    ai: {
+        color: 'a2eeef',
+        description: 'Guidance on working in this repo, such as its AGENTS.md or a repo-local skill, or its agent config',
+    },
+    ci: { color: 'edc287', description: 'CI/CD tooling & configuration' },
+    deprecate: { color: 'fbca04', description: 'Marks functionality for future removal' },
+    deps: { color: 'edc287', description: 'Change to dependencies' },
+    docs: {
+        color: 'a2eeef',
+        description: 'Documentation for human readers, such as a README, a guide, or a code comment',
+    },
+    drop: { color: 'd93f0b', description: 'Removes functionality that consumers depend on' },
+    feat: { color: '0075ca', description: 'Added or improved external functionality' },
+    fix: { color: 'd73a4a', description: 'Fixes a bug' },
+    fmt: { color: 'edc287', description: 'Formatting only, with no change to content' },
+    internal: { color: '1d76db', description: 'Internal change without external impact' },
+    perf: { color: '0075ca', description: 'Improves performance without changing behavior' },
+    refactor: { color: 'edc287', description: 'Improvement to code without change in functionality' },
+    sec: { color: 'b60205', description: 'Security vulnerability or hardening' },
+    tests: { color: 'edc287', description: 'Tests' },
+    tooling: { color: 'edc287', description: 'Development tools' },
+};

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

@@ -4,6 +4,6 @@ export interface LabelDefinition {
     name: string;
     /** Hex color code without the leading `#`. */
     color: string;
-    /** Short description shown in the GitHub UI. Absent when the label carries none. */
+    /** Short description shown in the GitHub UI. Absent when the label has none. */
     description?: string;
 }

package/dist/esm/tagCommand.d.ts

@@ -1,3 +1,3 @@
 import { type StreamStyles } from '@williamthorsen/nmr-core';
-/** Orchestrate the CLI `tag` command: parse flags and delegate to `createTags`. */
+/** Runs the CLI `tag` command: parses flags and delegates to `createTags`. */
 export declare function tagCommand(argv: string[], styles: StreamStyles): void;

package/dist/esm/typeGuards.d.ts

@@ -1,4 +1,4 @@
-/** Check whether a value is a plain object (non-null, non-array). */
+/** Checks whether a value is a plain object (non-null, non-array). */
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
-/** Narrow an `unknown` value to `unknown[]` via `Array.isArray`, avoiding `any[]`. */
+/** Narrows an `unknown` value to `unknown[]` via `Array.isArray`, avoiding `any[]`. */
 export declare function isUnknownArray(value: unknown): value is unknown[];