@williamthorsen/release-kit 14.1.0 → 14.2.0

package/dist/esm/bin/release-kit.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { parseArgsOrExit, readPackageVersion, reportError } from '@williamthorsen/nmr-core';
+import { parseArgsOrExit, reportError, resolveSelfVersion } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { commitCommand } from "../commitCommand.js";
 import { configFlagSchema } from "../configFlagSchema.js";
@@ -19,7 +19,7 @@ import { syncLabelsInitCommand } from "../sync-labels/initCommand.js";
 import { syncLabelsCommand } from "../sync-labels/syncCommand.js";
 import { tagCommand } from "../tagCommand.js";
 import { validateOverridesCommand } from "../validateOverridesCommand.js";
-const VERSION = readPackageVersion(import.meta.url);
+const VERSION = resolveSelfVersion(import.meta.url);
 function showUsage() {
     console.info(`
 Usage: release-kit <command> [options]
@@ -180,7 +180,8 @@ 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.
+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
@@ -244,7 +245,7 @@ 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.
+any publishable tags are still published. A project tag is never published.
 
 Options:
   --config <path>        Config file, relative to the current directory

package/dist/esm/buildChangelogEntries.d.ts

@@ -1,6 +1,6 @@
 import { type RawCommit } from './enumerateReleaseWindows.js';
 import type { GenerateChangelogOptions } from './generateChangelogs.js';
-import type { ChangelogEntry, ChangelogSection, MalformedChangeRecordBlock, PolicyViolation, ReleaseConfig, ReleaseType, UndeclaredEntryType, UnroutedEntryScope } from './types.js';
+import type { ChangelogEntry, ChangelogSection, MalformedChangeRecordBlock, PolicyViolation, ReleaseSettings, ReleaseType, UndeclaredEntryType, UnroutedEntryScope } from './types.js';
 /**
  * Strips a section title down to its bare name.
  *
@@ -35,13 +35,13 @@ export interface ChangelogDiagnostics {
  * window decides: its commits, its bump, and its diagnostics.
  *
  * A commit whose last `change-record` block records entries yields one item per entry routed to
- * `options.workspaceDir`; any other commit is classified by its title through `classifyChangelogCommit`. A `release:`
+ * `options.scope`; any other commit is classified by its title through `classifyChangelogCommit`. A `release:`
  * or merge subject yields nothing either way. The read records diagnostics only for the unreleased window, since the
  * released windows were reported when they were prepared.
  */
 export declare function readReleaseHistory(config: ReleaseHistoryConfig, options: GenerateChangelogOptions): ReleaseHistory;
 /** The configuration that `readReleaseHistory` reads. */
-export type ReleaseHistoryConfig = Pick<ReleaseConfig, 'breakingPolicies' | 'changelogJson' | 'scopeAliases' | 'versionPatterns' | 'workTypes'>;
+export type ReleaseHistoryConfig = Pick<ReleaseSettings, 'breakingPolicies' | 'changelogJson' | 'scopeAliases' | 'versionPatterns' | 'workTypes'>;
 /** One read of a scope's release windows. */
 export interface ReleaseHistory {
     /** The newest matching tag that HEAD reaches; undefined when none does. */

package/dist/esm/buildChangelogEntries.js

@@ -32,8 +32,8 @@ export function readReleaseHistory(config, options) {
         const context = {
             breakingPolicies: config.breakingPolicies ?? DEFAULT_BREAKING_POLICIES,
             devOnlySections: new Set(config.changelogJson.devOnlySections.map(stripGroupDecorations)),
-            ...(options.workspaceDir !== undefined && {
-                routing: { workspaceDir: options.workspaceDir, scopeAliases: config.scopeAliases ?? {} },
+            ...(options.scope !== undefined && {
+                routing: { scope: options.scope, scopeAliases: config.scopeAliases ?? {} },
             }),
             versionPatterns: config.versionPatterns ?? DEFAULT_VERSION_PATTERNS,
             workTypes: config.workTypes ?? DEFAULT_WORK_TYPES,
@@ -170,7 +170,7 @@ function isRoutedTo(scopes, routing) {
     }
     return scopes.some((scope) => {
         const resolved = routing.scopeAliases[scope] ?? scope;
-        return resolved === '*' || resolved === routing.workspaceDir;
+        return resolved === '*' || resolved === routing.scope;
     });
 }
 function formatDate(timestamp) {

package/dist/esm/buildDependencyGraph.d.ts

@@ -1,25 +1,25 @@
-import type { WorkspaceConfig } from './types.js';
-/** Identities, current versions, and `workspace:` dependency edges of the workspaces' packages. */
+import type { PackageTarget } from './types.js';
+/** Identities, current versions, and `workspace:` dependency edges of the package targets. */
 export interface DependencyGraph {
-    /** Maps a package name to its workspace `dir`. */
+    /** Maps a package name to its target id, the workspace `dir`. */
     packageNameToDir: Map<string, string>;
-    /** Maps a workspace `dir` to its package name (inverse of `packageNameToDir`). */
+    /** Maps a target id (a workspace `dir`) to its package name (inverse of `packageNameToDir`). */
     dirToPackageName: Map<string, string>;
-    /** Maps a workspace `dir` to its current version; absent when its `package.json` doesn't have a string `version`. */
+    /** Maps a target id to its current version; absent when its `package.json` doesn't have a string `version`. */
     dirToVersion: Map<string, string>;
-    /** Maps a package name to the workspaces that depend on it. */
-    dependentsOf: Map<string, WorkspaceConfig[]>;
+    /** Maps a package name to the targets that depend on it. */
+    dependentsOf: Map<string, PackageTarget[]>;
     /**
-     * Maps a workspace `dir` to the `workspace:`-protocol package names that it declares in `dependencies` or
+     * Maps a target id to the `workspace:`-protocol package names that it declares in `dependencies` or
      * `peerDependencies` (the forward counterpart of `dependentsOf`).
      */
     dependenciesOf: Map<string, Set<string>>;
 }
 /**
- * Builds the dependency graph from the workspaces' `package.json` files.
+ * Builds the dependency graph from the package targets' `package.json` files.
  *
- * Reads each workspace's primary `package.json` (first entry in `packageFiles`) to discover
+ * Reads each target's primary `package.json` (first entry in `versionFiles`) to discover
  * `workspace:` references in `dependencies` and `peerDependencies`, and to record its current
  * version.
  */
-export declare function buildDependencyGraph(workspaces: readonly WorkspaceConfig[]): DependencyGraph;
+export declare function buildDependencyGraph(targets: readonly PackageTarget[]): DependencyGraph;

package/dist/esm/buildDependencyGraph.js

@@ -3,30 +3,30 @@ import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
 function isPackageJsonSubset(value) {
     return typeof value === 'object' && value !== null;
 }
-export function buildDependencyGraph(workspaces) {
+export function buildDependencyGraph(targets) {
     const packageNameToDir = new Map();
     const dirToPackageName = new Map();
     const dirToVersion = new Map();
     const dependentsOf = new Map();
     const dependenciesOf = new Map();
-    const workspacePackages = new Map();
-    for (const workspace of workspaces) {
-        const primaryPackageFile = workspace.packageFiles[0];
+    const targetPackages = new Map();
+    for (const target of targets) {
+        const primaryPackageFile = target.versionFiles[0];
         if (primaryPackageFile === undefined) {
             continue;
         }
         const pkg = readPackageJsonSubset(primaryPackageFile);
-        workspacePackages.set(workspace, pkg);
+        targetPackages.set(target, pkg);
         if (typeof pkg.version === 'string') {
-            dirToVersion.set(workspace.dir, pkg.version);
+            dirToVersion.set(target.id, pkg.version);
         }
         if (pkg.name === undefined) {
             continue;
         }
-        packageNameToDir.set(pkg.name, workspace.dir);
-        dirToPackageName.set(workspace.dir, pkg.name);
+        packageNameToDir.set(pkg.name, target.id);
+        dirToPackageName.set(target.id, pkg.name);
     }
-    for (const [workspace, pkg] of workspacePackages) {
+    for (const [target, pkg] of targetPackages) {
         const allDeps = { ...pkg.dependencies, ...pkg.peerDependencies };
         for (const [depName, depVersion] of Object.entries(allDeps)) {
             if (typeof depVersion !== 'string' || !depVersion.startsWith('workspace:')) {
@@ -34,14 +34,14 @@ export function buildDependencyGraph(workspaces) {
             }
             const existing = dependentsOf.get(depName);
             if (existing === undefined) {
-                dependentsOf.set(depName, [workspace]);
+                dependentsOf.set(depName, [target]);
             }
             else {
-                existing.push(workspace);
+                existing.push(target);
             }
-            const forward = dependenciesOf.get(workspace.dir);
+            const forward = dependenciesOf.get(target.id);
             if (forward === undefined) {
-                dependenciesOf.set(workspace.dir, new Set([depName]));
+                dependenciesOf.set(target.id, new Set([depName]));
             }
             else {
                 forward.add(depName);

package/dist/esm/buildReleaseSummary.d.ts

@@ -1,6 +1,6 @@
 import type { PrepareResult } from './types.js';
 /**
- * Builds a release commit body from a prepare result: one section per released workspace or project that has commits,
- * the project last, each headed by its tag and listing its scope-stripped commit subjects.
+ * Builds a release commit body from a prepare result: one section per released target that has commits, in result
+ * order, each headed by its tag and listing its scope-stripped commit subjects.
  */
-export declare function buildReleaseSummary(result: Pick<PrepareResult, 'project' | 'workspaces'>): string;
+export declare function buildReleaseSummary(result: Pick<PrepareResult, 'targets'>): string;

package/dist/esm/buildReleaseSummary.js

@@ -1,27 +1,19 @@
 import { stripScope } from "./stripScope.js";
 export function buildReleaseSummary(result) {
     const sections = [];
-    for (const workspace of result.workspaces) {
-        if (workspace.status !== 'released') {
+    for (const target of result.targets) {
+        if (target.status !== 'released') {
             continue;
         }
-        const commits = workspace.commits;
+        const commits = target.commits;
         if (commits === undefined || commits.length === 0) {
             continue;
         }
-        const lines = [workspace.tag];
+        const lines = [target.tag];
         for (const commit of commits) {
             lines.push(`- ${stripScope(commit.subject)}`);
         }
         sections.push(lines.join('\n'));
     }
-    const project = result.project;
-    if (project !== undefined && project.status === 'released' && project.commits.length > 0) {
-        const lines = [project.tag];
-        for (const commit of project.commits) {
-            lines.push(`- ${stripScope(commit.subject)}`);
-        }
-        sections.push(lines.join('\n'));
-    }
     return sections.join('\n\n');
 }

package/dist/esm/changelogArchive.d.ts

@@ -0,0 +1,14 @@
+/** Directory, relative to a changelog directory, that contains the per-major archive files of its `CHANGELOG.md`. */
+export declare const CHANGELOG_ARCHIVE_DIRECTORY = "changelogs";
+/** An archive file that exists on disk. */
+export interface ChangelogArchivePath {
+    major: number;
+    path: string;
+}
+/** Returns the path, relative to the changelog directory, of the archive file for a major version. */
+export declare function describeArchivePath(major: number): string;
+/**
+ * Lists the archive files under the changelog directory, newest major first. A missing archive directory has none;
+ * files whose names do not match the archive pattern are ignored.
+ */
+export declare function listArchiveFiles(changelogDir: string): ChangelogArchivePath[];

package/dist/esm/changelogArchive.js

@@ -0,0 +1,21 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+export const CHANGELOG_ARCHIVE_DIRECTORY = 'changelogs';
+export function describeArchivePath(major) {
+    return `${CHANGELOG_ARCHIVE_DIRECTORY}/CHANGELOG-v${major}.md`;
+}
+export function listArchiveFiles(changelogDir) {
+    const archiveDir = join(changelogDir, CHANGELOG_ARCHIVE_DIRECTORY);
+    if (!existsSync(archiveDir)) {
+        return [];
+    }
+    const archives = [];
+    for (const name of readdirSync(archiveDir)) {
+        const match = ARCHIVE_FILE_PATTERN.exec(name);
+        if (match?.[1] !== undefined) {
+            archives.push({ major: Number(match[1]), path: join(archiveDir, name) });
+        }
+    }
+    return archives.toSorted((a, b) => b.major - a.major);
+}
+const ARCHIVE_FILE_PATTERN = /^CHANGELOG-v(\d+)\.md$/;

package/dist/esm/changelogJsonFile.d.ts

@@ -1,6 +1,6 @@
-import type { ChangelogEntry, ReleaseConfig } from './types.js';
+import type { ChangelogEntry, ReleaseSettings } from './types.js';
 /** Resolves the path of the `changelog.json` file under a workspace's changelog directory. */
-export declare function resolveChangelogJsonPath(config: Pick<ReleaseConfig, 'changelogJson'>, changelogPath: string): string;
+export declare function resolveChangelogJsonPath(config: Pick<ReleaseSettings, 'changelogJson'>, changelogPath: string): string;
 /** Renders changelog entries as a `changelog.json` file's complete content, sorted newest-first. */
 export declare function renderChangelogJson(entries: ChangelogEntry[]): string;
 /**

package/dist/esm/changelogOverrides.d.ts

@@ -1,4 +1,4 @@
-import type { ChangelogEntry, ChangelogOverride, WorkspaceConfig } from './types.js';
+import type { ChangelogEntry, 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>;
 /** Form of an override key: a lowercase hex commit hash or prefix, optionally followed by `:<n>`, a 1-based entry position. */
@@ -102,11 +102,11 @@ export interface OverrideContext {
     globalMatchedRootKeys: Set<string>;
 }
 /**
- * Loads and validates the override files of the root and every workspace, and bundles them with empty warning
- * aggregators. Throws if any file fails to load, so that a malformed checked-in override file stops `prepare` before
- * any workspace writes.
+ * Loads and validates the override files of the root and of every workspace at the given repo-relative paths, and
+ * bundles them with empty warning aggregators. Throws if any file fails to load, so that a malformed checked-in
+ * override file stops `prepare` before any workspace writes.
  */
-export declare function createOverrideContext(workspaces: WorkspaceConfig[]): OverrideContext;
+export declare function createOverrideContext(workspacePaths: readonly string[]): OverrideContext;
 /** A changelog item as override matching sees it. `entry` is absent for a title-derived item. */
 export interface OverrideTargetItem {
     hash: string;
@@ -164,12 +164,13 @@ export interface ValidateAllChangelogOverridesResult {
  */
 export declare function validateAllChangelogOverrides(inputs: ValidateAllChangelogOverridesInputs): ValidateAllChangelogOverridesResult;
 /**
- * Applies the composed root and workspace override map to a workspace's changelog entries, and records stale keys by
- * tier.
+ * Applies the composed root and workspace override map to a target's changelog entries, and records stale keys by
+ * tier. A target without a workspace override file, such as the project, passes `undefined` for `workspacePath` and
+ * applies the root tier alone.
  *
  * A workspace key that matched nothing, whether or not the root map has the same key, is stale, and it is warned about
  * at once. The function adds each root key that matched without being shadowed to `globalMatchedRootKeys`, from which
  * the caller warns, at the end of the run, about the root keys that matched nowhere. Throws if applying reports any
  * error, such as an ambiguous prefix.
  */
-export declare function applyWorkspaceOverrides(newEntries: ChangelogEntry[], workspacePath: string, overrideContext: OverrideContext): ReturnType<typeof applyChangelogOverrides>;
+export declare function applyWorkspaceOverrides(newEntries: ChangelogEntry[], workspacePath: string | undefined, overrideContext: OverrideContext): ReturnType<typeof applyChangelogOverrides>;

package/dist/esm/changelogOverrides.js

@@ -336,11 +336,8 @@ export function composeOverrides(rootEntries, workspaceEntries) {
     }
     return composed;
 }
-export function createOverrideContext(workspaces) {
-    const result = loadOverridesForScopes({
-        project: '.',
-        workspaces: workspaces.map((workspace) => workspace.workspacePath),
-    });
+export function createOverrideContext(workspacePaths) {
+    const result = loadOverridesForScopes({ project: '.', workspaces: [...workspacePaths] });
     if (result.errors.length > 0) {
         throw new Error(`Failed to load changelog overrides:\n  - ${result.errors.join('\n  - ')}`);
     }
@@ -488,7 +485,7 @@ function formatRootStaleWarning(filePath, key) {
 }
 export function applyWorkspaceOverrides(newEntries, workspacePath, overrideContext) {
     const { project, perWorkspace, overrideWarnings, globalMatchedRootKeys } = overrideContext;
-    const workspaceOverrides = perWorkspace.get(workspacePath);
+    const workspaceOverrides = workspacePath === undefined ? undefined : perWorkspace.get(workspacePath);
     const composed = composeOverrides(project, workspaceOverrides);
     const applied = applyChangelogOverrides(newEntries, composed);
     if (applied.errors.length > 0) {

package/dist/esm/createGithubReleaseCommand.d.ts

@@ -4,6 +4,7 @@ import { type StreamStyles } from '@williamthorsen/nmr-core';
  * a comma-separated `--tags` subset, without publishing to npm.
  *
  * A private workspace's tag is skipped with a warning and doesn't get a Release; an all-private tag set is a clean
- * no-op. A relative `--config` resolves against `invocationDir`.
+ * no-op. A project tag gets a Release whatever the root `package.json#private` says. A relative `--config` resolves
+ * against `invocationDir`.
  */
 export declare function createGithubReleaseCommand(argv: string[], styles: StreamStyles, invocationDir: string): Promise<void>;

package/dist/esm/createGithubReleaseCommand.js

@@ -20,19 +20,19 @@ export async function createGithubReleaseCommand(argv, styles, invocationDir) {
     const userConfig = await loadUsableConfig(styles.stderr, configPath);
     const requestedTags = parseRequestedTags(parsed.flags.tags);
     const resolvedTags = resolveCommandTags(requestedTags, userConfig);
-    const publishableTags = resolvedTags.filter((resolvedTag) => resolvedTag.isPublishable);
+    const releasableTags = resolvedTags.filter(isReleasable);
     for (const resolvedTag of resolvedTags) {
-        if (!resolvedTag.isPublishable) {
+        if (!isReleasable(resolvedTag)) {
             console.warn(formatPrivateSkip(resolvedTag));
         }
     }
-    if (publishableTags.length === 0) {
+    if (releasableTags.length === 0) {
         return;
     }
     const { changelogJsonOutputPath, sectionOrder } = deriveReleaseNotesConfig(userConfig);
     let outcome;
     try {
-        outcome = createGithubReleases(publishableTags, changelogJsonOutputPath, dryRun, sectionOrder);
+        outcome = createGithubReleases(releasableTags, changelogJsonOutputPath, dryRun, sectionOrder);
     }
     catch (error) {
         reportError(`Failed to create GitHub Releases: ${describeError(error)}`);
@@ -43,3 +43,6 @@ export async function createGithubReleaseCommand(argv, styles, invocationDir) {
         console.info(`Skipped ${outcome.skipped.length} tag(s) without releasable content: ${formatted}.`);
     }
 }
+function isReleasable(resolvedTag) {
+    return resolvedTag.kind !== 'package' || resolvedTag.isPublishable;
+}

package/dist/esm/deriveDirectoryConfig.d.ts

@@ -0,0 +1,13 @@
+import type { DeclaredDirectory } from './resolveReleaseDeclaration.js';
+import type { DirectoryConfig } from './types.js';
+/** Name of the version file of a directory that doesn't contain a `package.json`. */
+export declare const DIRECTORY_VERSION_FILE = "version.json";
+/**
+ * Derives a directory target's configuration from its declaration, reading the directory under `root`.
+ *
+ * The version file is the directory's `package.json` when it has one, and its `version.json` otherwise; either must
+ * contain a string `version`. The tag prefix defaults to the directory's basename followed by `-v`, and to `v` for the
+ * repo root. Throws when the path isn't a directory, when the version file is missing or lacks a `version`, and when
+ * the basename would not make a valid tag prefix.
+ */
+export declare function deriveDirectoryConfig(declared: DeclaredDirectory, root?: string): DirectoryConfig;

package/dist/esm/deriveDirectoryConfig.js

@@ -0,0 +1,59 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
+import { isRecord } from "./typeGuards.js";
+export const DIRECTORY_VERSION_FILE = 'version.json';
+const TAG_PREFIX_PATTERN = /^[\w.-]+$/;
+export function deriveDirectoryConfig(declared, root = process.cwd()) {
+    const label = `releases.${declared.name}`;
+    if (statSync(path.resolve(root, declared.path), { throwIfNoEntry: false })?.isDirectory() !== true) {
+        throw new Error(`${label}: path '${declared.path}' is not a directory; declare a directory that exists in the repo`);
+    }
+    const versionFile = resolveVersionFile(declared.path, root);
+    assertVersionField(label, versionFile, root);
+    const config = {
+        name: declared.name,
+        path: declared.path,
+        versionFile,
+        tagPrefix: declared.tagPrefix ?? deriveTagPrefix(label, declared.path),
+    };
+    if (declared.paths !== undefined) {
+        config.paths = [...declared.paths];
+    }
+    if (declared.legacyIdentities !== undefined) {
+        config.legacyIdentities = declared.legacyIdentities;
+    }
+    return config;
+}
+function assertVersionField(label, versionFile, root) {
+    const absolutePath = path.resolve(root, versionFile);
+    if (!existsSync(absolutePath)) {
+        throw new Error(`${label}: ${versionFile} not found; create it with the directory's current version, such as { "version": "0.0.0" }`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(absolutePath, 'utf8'));
+    }
+    catch (error) {
+        throw chainError(`${label}: failed to read ${versionFile}`, error);
+    }
+    if (!isRecord(parsed) || typeof parsed['version'] !== 'string') {
+        throw new Error(`${label}: ${versionFile} does not contain a string 'version' field; add one`);
+    }
+}
+function deriveTagPrefix(label, directoryPath) {
+    if (directoryPath === '.') {
+        return 'v';
+    }
+    const basename = path.posix.basename(directoryPath);
+    if (!TAG_PREFIX_PATTERN.test(basename)) {
+        throw new Error(`${label}: the directory name '${basename}' cannot form a tag prefix; set tagPrefix, such as '${basename.replaceAll(/[^\w.-]+/g, '-')}-v'`);
+    }
+    return `${basename}-v`;
+}
+function resolveVersionFile(directoryPath, root) {
+    const packageJson = path.posix.join(directoryPath, 'package.json');
+    return existsSync(path.resolve(root, packageJson))
+        ? packageJson
+        : path.posix.join(directoryPath, DIRECTORY_VERSION_FILE);
+}

package/dist/esm/deriveWorkspaceConfig.js

@@ -26,7 +26,6 @@ export function deriveWorkspaceConfig(workspacePath) {
         workspacePath,
         isPublishable,
         packageFiles: [packageJsonPath],
-        changelogPaths: [workspacePath],
         paths: [`${workspacePath}/**`],
     };
 }

package/dist/esm/discoverWorkspaces.d.ts

@@ -50,8 +50,8 @@ export declare function describeEmptyWorkspace(workspace: EmptyWorkspace): strin
  * as patterns at all.
  *
  * `packageDirs` come back relative to `monorepoRoot` as POSIX paths, because that is what every consumer
- * needs: `WorkspaceConfig.paths` feeds `git log -- <paths>`, and `packageFiles` and `changelogPaths` are read
- * from disk relative to the working directory. The workspace root itself relativizes to `.`, the path through
- * which `deriveWorkspaceConfig` reads a root package's manifest.
+ * needs: `WorkspaceConfig.paths` feeds `git log -- <paths>`, and `packageFiles` and the changelogs under
+ * `workspacePath` are read from disk relative to the working directory. The workspace root itself relativizes to
+ * `.`, the path through which `deriveWorkspaceConfig` reads a root package's manifest.
  */
 export declare function discoverWorkspaces(monorepoRoot?: string): WorkspaceDiscovery;

package/dist/esm/findTransitiveDependents.js

@@ -10,10 +10,10 @@ export function findTransitiveDependents(graph, startDirs) {
             continue;
         const dependents = graph.dependentsOf.get(packageName) ?? [];
         for (const dependent of dependents) {
-            if (found.has(dependent.dir))
+            if (found.has(dependent.id))
                 continue;
-            found.add(dependent.dir);
-            queue.push(dependent.dir);
+            found.add(dependent.id);
+            queue.push(dependent.id);
         }
     }
     return found;

package/dist/esm/findUnroutedEntryScopes.d.ts

@@ -1,13 +1,13 @@
 import type { RawCommit } from './enumerateReleaseWindows.js';
 import type { UnroutedEntryScope } from './types.js';
-/** A workspace's `dir` with the commits of its unreleased window. */
+/** A workspace target's name, the scope that routes to it, with the commits of its unreleased window. */
 export interface WorkspaceWindow {
     commits: readonly RawCommit[];
     dir: string;
 }
 /**
  * Finds the change-record entry scopes of the unreleased windows that do not route their entry to any workspace whose
- * window contains the commit, and returns the findings keyed by the `dir` of every workspace whose window contains it.
+ * window contains the commit, and returns the findings keyed by the name of every workspace whose window contains it.
  *
  * A scope resolves through `scopeAliases` first. It is not reported when it resolves to `*`, to a workspace whose
  * window contains the commit, or to a `configuredDirs` workspace absent from `windows`, which the run did not read.

package/dist/esm/formatDirectoryPublishSkip.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedTag } from './resolveReleaseTags.js';
+/** Formats the warning emitted when `publish` is asked for a directory target's tag, which is never published. */
+export declare function formatDirectoryPublishSkip(resolvedTag: Pick<ResolvedTag, 'dir' | 'tag'>): string;

package/dist/esm/formatDirectoryPublishSkip.js

@@ -0,0 +1,3 @@
+export function formatDirectoryPublishSkip(resolvedTag) {
+    return `Skipping ${resolvedTag.tag}: directory release '${resolvedTag.dir}' is not published to a registry.`;
+}

package/dist/esm/formatExcludedSkip.d.ts

@@ -1,3 +1,6 @@
 import type { ResolvedTag } from './resolveReleaseTags.js';
-/** Formats the warning emitted when a release tag's workspace is excluded by config and therefore skipped. */
-export declare function formatExcludedSkip(resolvedTag: Pick<ResolvedTag, 'tag' | 'workspacePath'>): string;
+/**
+ * Formats the warning emitted when a release tag's workspace is excluded by config and therefore skipped, naming the
+ * `setting` that excluded it, which defaults to the `workspaces` override form.
+ */
+export declare function formatExcludedSkip(resolvedTag: Pick<ResolvedTag, 'tag' | 'workspacePath'>, setting?: string): string;

package/dist/esm/formatExcludedSkip.js

@@ -1,3 +1,3 @@
-export function formatExcludedSkip(resolvedTag) {
-    return `Skipping ${resolvedTag.tag} (${resolvedTag.workspacePath}): excluded by config (shouldExclude: true).`;
+export function formatExcludedSkip(resolvedTag, setting = 'shouldExclude: true') {
+    return `Skipping ${resolvedTag.tag} (${resolvedTag.workspacePath}): excluded by config (${setting}).`;
 }

package/dist/esm/formatProjectPublishSkip.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedTag } from './resolveReleaseTags.js';
+/** Formats the warning emitted when `publish` is asked for a project tag, which does not have an npm package. */
+export declare function formatProjectPublishSkip(resolvedTag: Pick<ResolvedTag, 'tag'>): string;

package/dist/esm/formatProjectPublishSkip.js

@@ -0,0 +1,3 @@
+export function formatProjectPublishSkip(resolvedTag) {
+    return `Skipping ${resolvedTag.tag}: a project tag is not an npm package.`;
+}

package/dist/esm/generateChangelogs.d.ts

@@ -1,6 +1,6 @@
-import type { WorkspaceConfig } from './types.js';
-/** Returns the workspace's derived tag prefix followed by each declared legacy-identity tag prefix. */
-export declare function getAllTagPrefixes(workspace: WorkspaceConfig): string[];
+import type { ReleaseTarget } from './types.js';
+/** Returns the derived tag prefix followed by each declared legacy-identity tag prefix. */
+export declare function getAllTagPrefixes(owner: Pick<ReleaseTarget, 'legacyIdentities' | 'tagPrefix'>): string[];
 /**
  * Options for `readReleaseHistory`: the tag prefixes and pathspecs that bound its release windows, and the workspace
  * to which it routes change-record entries.
@@ -11,9 +11,9 @@ export interface GenerateChangelogOptions {
     /** Git pathspecs restricting the history to commits that touch them; all paths when omitted. */
     paths?: readonly string[];
     /**
-     * The `dir` of the workspace being read. When set, the read includes a change-record entry only when its scopes,
-     * after `scopeAliases` resolution, name this `dir`, are empty, or contain `*`; when omitted, the read includes every
-     * entry.
+     * The scope of the workspace being read, its target name. When set, the read includes a change-record entry only
+     * when its scopes, after `scopeAliases` resolution, name this scope, are empty, or contain `*`; when omitted, the
+     * read includes every entry.
      */
-    workspaceDir?: string;
+    scope?: string;
 }

package/dist/esm/generateChangelogs.js

@@ -1,3 +1,3 @@
-export function getAllTagPrefixes(workspace) {
-    return [workspace.tagPrefix, ...(workspace.legacyIdentities?.map((identity) => identity.tagPrefix) ?? [])];
+export function getAllTagPrefixes(owner) {
+    return [owner.tagPrefix, ...(owner.legacyIdentities?.map((identity) => identity.tagPrefix) ?? [])];
 }

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

@@ -2,6 +2,6 @@
  * Help text for `release-kit prepare`. The module does not have any import-time side effects, so that a test can
  * import it without running the CLI.
  */
-export declare const prepareHelpText = "\nUsage: release-kit prepare [options]\n\nRun release preparation with automatic workspace discovery.\n\nOptions:\n  --config <path>       Config file, relative to the current directory\n                         (default: .config/release-kit.config.ts at the repo root)\n  --dry-run             Run without modifying any files\n  --bump=major|minor|patch  Set the level of every release that happens; does not trigger one\n  --set-version=X.Y.Z   Set an explicit version; bypasses the changelog-derived bump. In monorepo\n                         mode, name each workspace: --set-version=arrays@1.0.0[,strings@2.0.0].\n                         Rejected when a 'project' block is configured.\n  --force               Release even when the last tag is not followed by any commits,\n                         or by any bump-worthy ones. Defaults to patch when --bump is not given;\n                         use --bump=X for a different level.\n  --no-git-checks, -n   Skip the clean-working-tree check\n  --only=name1,name2    Release only the named workspaces and their dependents (comma-separated,\n                         monorepo only).\n                         When a 'project' block is configured, the project release is skipped.\n  --with-release-notes  Also write per-workspace release-notes previews under <workspacePath>/docs/\n                         (docs/README.v<version>.md and docs/RELEASE_NOTES.v<version>.md).\n                         Recommended .gitignore entry: packages/*/docs/*.v*.md (or docs/*.v*.md).\n  --help, -h            Show this help message\n";
+export declare const prepareHelpText = "\nUsage: release-kit prepare [options]\n\nRun release preparation with automatic workspace discovery.\n\nOptions:\n  --config <path>       Config file, relative to the current directory\n                         (default: .config/release-kit.config.ts at the repo root)\n  --dry-run             Run without modifying any files\n  --bump=major|minor|patch  Set the level of every release that happens; does not trigger one\n  --set-version=X.Y.Z   Set an explicit version; bypasses the changelog-derived bump. In monorepo\n                         mode, name each workspace or directory target:\n                         --set-version=arrays@1.0.0[,strings@2.0.0].\n                         Rejected when a composite (a 'project' block or a releases composite)\n                         is configured.\n  --force               Release even when the last tag is not followed by any commits,\n                         or by any bump-worthy ones. Defaults to patch when --bump is not given;\n                         use --bump=X for a different level.\n  --no-git-checks, -n   Skip the clean-working-tree check\n  --only=name1,name2    Release only the named release targets and their dependents\n                         (comma-separated, monorepo only). A composite declared under 'releases'\n                         releases only when named; a 'project' block's release is skipped.\n  --with-release-notes  Also write per-workspace release-notes previews under <workspacePath>/docs/\n                         (docs/README.v<version>.md and docs/RELEASE_NOTES.v<version>.md).\n                         Recommended .gitignore entry: packages/*/docs/*.v*.md (or docs/*.v*.md).\n  --help, -h            Show this help message\n";
 /** Prints the prepare command's help text. */
 export declare function showPrepareHelp(): void;

package/dist/esm/help/prepareHelp.js

@@ -9,15 +9,17 @@ Options:
   --dry-run             Run without modifying any files
   --bump=major|minor|patch  Set the level of every release that happens; does not trigger one
   --set-version=X.Y.Z   Set an explicit version; bypasses the changelog-derived bump. In monorepo
-                         mode, name each workspace: --set-version=arrays@1.0.0[,strings@2.0.0].
-                         Rejected when a 'project' block is configured.
+                         mode, name each workspace or directory target:
+                         --set-version=arrays@1.0.0[,strings@2.0.0].
+                         Rejected when a composite (a 'project' block or a releases composite)
+                         is configured.
   --force               Release even when the last tag is not followed by any commits,
                          or by any bump-worthy ones. Defaults to patch when --bump is not given;
                          use --bump=X for a different level.
   --no-git-checks, -n   Skip the clean-working-tree check
-  --only=name1,name2    Release only the named workspaces and their dependents (comma-separated,
-                         monorepo only).
-                         When a 'project' block is configured, the project release is skipped.
+  --only=name1,name2    Release only the named release targets and their dependents
+                         (comma-separated, monorepo only). A composite declared under 'releases'
+                         releases only when named; a 'project' block's release is skipped.
   --with-release-notes  Also write per-workspace release-notes previews under <workspacePath>/docs/
                          (docs/README.v<version>.md and docs/RELEASE_NOTES.v<version>.md).
                          Recommended .gitignore entry: packages/*/docs/*.v*.md (or docs/*.v*.md).