@williamthorsen/release-kit 12.0.0 → 13.1.0

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,28 +1,33 @@
 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}`);
     }
-    const declared = labels.map((label) => ({ ...label, description: label.description ?? '' }));
+    const declared = labels.map(({ archived, color, description, name }) => ({
+        name,
+        color,
+        description: description ?? '',
+        ...(archived !== undefined && { archived }),
+    }));
     const yamlBody = stringify(declared, { singleQuote: true, lineWidth: 0 });
     return headerLines.join('\n') + '\n' + yamlBody;
 }
 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 +35,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 +60,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 +94,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);
         }
@@ -26,6 +26,7 @@ export function resolveLabels(config) {
                 name,
                 color: spec.color,
                 ...(spec.description !== undefined && { description: spec.description }),
+                ...(spec.archived !== undefined && { archived: spec.archived }),
             });
         }
     }

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

@@ -1,9 +1,11 @@
-/** A single GitHub label definition compatible with EndBug/label-sync. */
+/** A single GitHub label definition, as `sync-labels generate` writes it to `.github/labels.yaml`. */
 export interface LabelDefinition {
     /** Display name of the label. */
     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;
+    /** Marks the label for the sync to archive rather than keep active. Absent for an active label. */
+    archived?: true;
 }

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[];