@williamthorsen/release-kit 14.0.0 → 14.2.0

package/dist/esm/releasePrepareTargets.js

@@ -0,0 +1,335 @@
+import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
+import { assertTaggedBaseline } from "./assertTaggedBaseline.js";
+import { buildDependencyGraph } from "./buildDependencyGraph.js";
+import { buildReleaseSummary } from "./buildReleaseSummary.js";
+import { createOverrideContext, formatStaleOverrideKeyWarning } from "./changelogOverrides.js";
+import { deriveDependenciesHeader, deriveSectionOrder } from "./deriveReleaseNotesConfig.js";
+import { detectUndeclaredTagPrefixes } from "./detectUndeclaredTagPrefixes.js";
+import { findTransitiveDependents } from "./findTransitiveDependents.js";
+import { findUnroutedEntryScopes } from "./findUnroutedEntryScopes.js";
+import { getAllTagPrefixes } from "./generateChangelogs.js";
+import { hasPrettierConfig } from "./hasPrettierConfig.js";
+import { resolveWorkTypes } from "./loadConfig.js";
+import { buildSkippedTargetResult, decideTargetRelease, isRepoRoot, planTargetRelease, readTargetHistory, } from "./prepareTarget.js";
+import { propagateBumps } from "./propagateBumps.js";
+import { isSinglePackageTargets, PROJECT_TARGET_ID } from "./resolveReleaseTargets.js";
+const PREVIEWS_REQUIRE_JSON_WARNING = '--with-release-notes requires changelogJson.enabled; skipping preview generation';
+export function releasePrepareTargets(config, options) {
+    const { settings } = config;
+    const { only, withReleaseNotes } = options;
+    const isSinglePackage = isSinglePackageTargets(config.targets);
+    const memberTargets = config.targets.filter((target) => target.kind !== 'composite');
+    const compositeTargets = config.targets.filter((target) => target.kind === 'composite');
+    const warnings = [];
+    const graph = buildDependencyGraph(memberTargets.filter((target) => target.kind === 'package').filter((target) => target.isWorkspace));
+    const startIds = selectStartIds(memberTargets, options);
+    const plannedIds = findTransitiveDependents(graph, startIds);
+    const planned = memberTargets.filter((target) => plannedIds.has(target.id));
+    const arePreviewsBlocked = withReleaseNotes === true && !settings.changelogJson.enabled;
+    if (arePreviewsBlocked && !isSinglePackage) {
+        warnings.push(PREVIEWS_REQUIRE_JSON_WARNING);
+    }
+    const workTypes = resolveWorkTypes(settings.workTypes);
+    const context = {
+        settings,
+        overrideContext: createOverrideContext(planned.flatMap(listOverrideDirectory)),
+        sectionOrder: deriveSectionOrder(workTypes),
+        dependenciesHeader: deriveDependenciesHeader(workTypes),
+        shouldPlanPreviews: withReleaseNotes === true && settings.changelogJson.enabled,
+        today: new Date().toISOString().slice(0, 10),
+    };
+    const direct = decideDirectReleases(planned, settings, options, startIds);
+    if (!isSinglePackage) {
+        reportUnroutedEntryScopes(planned, direct, settings, memberTargets);
+    }
+    const releaseSet = propagateBumps(direct.bumps, graph);
+    assertTaggedBaseline([...direct.untaggedBaselines]
+        .filter(([id]) => direct.bumps.has(id) || !releaseSet.has(id))
+        .map(([, untagged]) => untagged));
+    const { sorted: sortedIds, cyclicIds } = topologicalSort(releaseSet, graph);
+    if (cyclicIds.length > 0) {
+        warnings.push(`Circular workspace dependencies detected among: ${cyclicIds.join(', ')}. ` +
+            'Propagation metadata may be incomplete for these workspaces.');
+    }
+    const resultsById = new Map();
+    for (const target of planned) {
+        const decision = direct.decisions.get(target.id);
+        if (decision?.outcome === 'skip' && !releaseSet.has(target.id)) {
+            resultsById.set(target.id, buildSkippedTargetResult(target, readHistory(direct.readings, target), decision.skipReason));
+        }
+    }
+    const collected = { tags: [], writes: [], removals: [], modifiedFiles: [] };
+    for (const id of sortedIds) {
+        const target = planned.find((candidate) => candidate.id === id);
+        const release = releaseSet.get(id);
+        if (target === undefined || release === undefined) {
+            continue;
+        }
+        const decision = direct.decisions.get(id);
+        const plannedRelease = runStage(describeStage(target), () => planTargetRelease({
+            ...context,
+            target,
+            release,
+            decision: decision?.outcome === 'release' ? decision : undefined,
+            history: readHistory(direct.readings, target),
+        }));
+        collect(collected, plannedRelease);
+        warnings.push(...plannedRelease.warnings);
+        resultsById.set(id, plannedRelease.result);
+    }
+    const results = planned.flatMap((target) => resultsById.get(target.id) ?? []);
+    for (const composite of compositeTargets) {
+        const skipWarning = describeCompositeSkip(composite, only);
+        if (skipWarning !== undefined) {
+            warnings.push(skipWarning);
+            continue;
+        }
+        const result = runStage(describeStage(composite), () => prepareComposite(composite, context, options, collected, warnings));
+        results.push(result);
+    }
+    const formatCommand = planFormatCommand(settings.formatCommand, collected);
+    const { overrideContext } = context;
+    for (const overrideKey of overrideContext.project.keys()) {
+        if (!overrideContext.globalMatchedRootKeys.has(overrideKey)) {
+            overrideContext.overrideWarnings.push(formatStaleOverrideKeyWarning(overrideKey));
+        }
+    }
+    const allWarnings = isSinglePackage
+        ? composeSinglePackageWarnings(collected, overrideContext, arePreviewsBlocked, warnings)
+        : [...warnings, ...overrideContext.overrideWarnings];
+    return {
+        targets: results,
+        tags: collected.tags,
+        writes: collected.writes,
+        removals: collected.removals,
+        summary: buildReleaseSummary({ targets: results }),
+        formatCommand,
+        ...(allWarnings.length > 0 && { warnings: allWarnings }),
+    };
+}
+function collect(collected, planned) {
+    collected.tags.push(planned.tag);
+    collected.writes.push(...planned.writes);
+    collected.removals.push(...planned.removals);
+    collected.modifiedFiles.push(...planned.modifiedFiles);
+}
+function composeSinglePackageWarnings(collected, overrideContext, arePreviewsBlocked, previewWarnings) {
+    if (collected.tags.length === 0) {
+        return [];
+    }
+    return [
+        ...overrideContext.overrideWarnings,
+        ...(arePreviewsBlocked ? [PREVIEWS_REQUIRE_JSON_WARNING] : []),
+        ...previewWarnings,
+    ];
+}
+function decideDirectReleases(planned, settings, options, startIds) {
+    const { force, bumpOverride, setVersions } = options;
+    const direct = {
+        readings: new Map(),
+        decisions: new Map(),
+        bumps: new Map(),
+        untaggedBaselines: new Map(),
+    };
+    const hintState = { emitted: false };
+    const knownPrefixes = planned.flatMap(getAllTagPrefixes);
+    for (const target of planned) {
+        const { history, untagged } = runStage(describeStage(target), () => readTargetHistory(target, settings));
+        direct.readings.set(target.id, history);
+        if (untagged !== undefined) {
+            direct.untaggedBaselines.set(target.id, untagged);
+        }
+        if (history.previousTag === undefined && target.kind === 'package' && target.isWorkspace) {
+            maybeEmitBaselineHint(target, knownPrefixes, hintState);
+        }
+        const setVersion = setVersions?.get(target.id);
+        const decision = decideTargetRelease(target, history, {
+            force: force === true && startIds.has(target.id),
+            bumpOverride,
+            setVersion,
+        });
+        direct.decisions.set(target.id, decision);
+        if (decision.outcome === 'skip') {
+            continue;
+        }
+        direct.bumps.set(target.id, decision.setVersion === undefined
+            ? { releaseType: decision.releaseType }
+            : { releaseType: 'patch', newVersionOverride: decision.setVersion });
+    }
+    return direct;
+}
+function describeCompositeSkip(composite, only) {
+    if (only === undefined || only.includes(composite.id)) {
+        return undefined;
+    }
+    if (composite.id === PROJECT_TARGET_ID) {
+        return (`Project release skipped: --only narrows this run to ${only.join(', ')}. ` +
+            'Run `release-kit prepare` without --only to include the project release.');
+    }
+    return `Release '${composite.id}' skipped: --only does not name it. Add ${composite.id} to --only to include it.`;
+}
+function describeStage(target) {
+    switch (target.kind) {
+        case 'composite':
+            return 'project release stage';
+        case 'directory':
+            return `directory '${target.id}' release stage`;
+        case 'package':
+            return target.isWorkspace ? `workspace '${target.id}' release stage` : undefined;
+    }
+}
+function maybeEmitBaselineHint(target, knownPrefixes, state) {
+    if (state.emitted)
+        return;
+    if ((target.legacyIdentities?.length ?? 0) > 0)
+        return;
+    const candidates = detectUndeclaredTagPrefixes(knownPrefixes);
+    if (candidates.length === 0)
+        return;
+    const totalTags = candidates.reduce((sum, candidate) => sum + candidate.tagCount, 0);
+    const example = candidates[0]?.exampleTags[0] ?? `${candidates[0]?.prefix ?? ''}?`;
+    process.stderr.write(`Hint: no baseline tag found for ${target.id} under '${target.tagPrefix}', but ` +
+        `${totalTags} candidate-shaped tags exist (e.g., ${example}). ` +
+        "Run 'release-kit show-tag-prefixes' to check for undeclared legacy prefixes.\n");
+    state.emitted = true;
+}
+function planFormatCommand(configuredCommand, collected) {
+    const formatCommandStr = configuredCommand ?? (hasPrettierConfig() ? 'npx prettier --write' : undefined);
+    if (collected.tags.length === 0 || formatCommandStr === undefined) {
+        return undefined;
+    }
+    const files = collected.modifiedFiles;
+    return { command: `${formatCommandStr} ${files.join(' ')}`, files };
+}
+function prepareComposite(composite, context, options, collected, warnings) {
+    const { history, untagged } = readTargetHistory(composite, context.settings);
+    assertTaggedBaseline([untagged]);
+    const decision = decideTargetRelease(composite, history, {
+        force: options.force === true,
+        bumpOverride: options.bumpOverride,
+        setVersion: undefined,
+    });
+    if (decision.outcome === 'skip') {
+        return buildSkippedTargetResult(composite, history, decision.skipReason);
+    }
+    if (decision.setVersion !== undefined) {
+        throw new Error('A composite target cannot take --set-version');
+    }
+    const planned = planTargetRelease({
+        ...context,
+        target: composite,
+        release: { releaseType: decision.releaseType },
+        decision,
+        history,
+    });
+    collect(collected, planned);
+    warnings.push(...planned.warnings);
+    return planned.result;
+}
+function isRepoRootTarget(target) {
+    return target.kind === 'directory' && isRepoRoot(target);
+}
+function listOverrideDirectory(target) {
+    if (target.kind === 'directory') {
+        return isRepoRootTarget(target) ? [] : [target.directoryPath];
+    }
+    return target.isWorkspace ? [target.packagePath] : [];
+}
+function readHistory(readings, target) {
+    const history = readings.get(target.id);
+    if (history === undefined) {
+        throw new Error(`Target '${target.id}' was planned without a history`);
+    }
+    return history;
+}
+function reportUnroutedEntryScopes(planned, direct, settings, memberTargets) {
+    const releasing = planned.filter((target) => direct.decisions.get(target.id)?.outcome === 'release');
+    const windows = [...releasing, ...planned.filter((target) => !releasing.includes(target))].map((target) => ({
+        target,
+        history: readHistory(direct.readings, target),
+    }));
+    const findings = findUnroutedEntryScopes(windows.map(({ target, history }) => ({ dir: target.id, commits: history.unreleased.commits })), memberTargets.map((target) => target.id), settings.scopeAliases ?? {});
+    for (const { target, history } of windows) {
+        history.unreleased.diagnostics.unroutedEntryScopes = isRepoRootTarget(target)
+            ? []
+            : (findings.get(target.id) ?? []);
+    }
+}
+function runStage(stage, fn) {
+    if (stage === undefined) {
+        return fn();
+    }
+    try {
+        return fn();
+    }
+    catch (error) {
+        throw chainError(stage, error);
+    }
+}
+function selectStartIds(memberTargets, options) {
+    const { only, setVersions } = options;
+    if (only === undefined) {
+        return new Set(memberTargets.map((target) => target.id));
+    }
+    return new Set([...only, ...(setVersions?.keys() ?? [])]);
+}
+function topologicalSort(releaseSet, graph) {
+    const releaseIds = new Set(releaseSet.keys());
+    if (releaseIds.size === 0) {
+        return { sorted: [], cyclicIds: [] };
+    }
+    const inDegree = new Map();
+    const forwardEdges = new Map();
+    for (const id of releaseIds) {
+        inDegree.set(id, 0);
+        forwardEdges.set(id, []);
+    }
+    for (const [packageName, dependents] of graph.dependentsOf) {
+        const dependencyId = graph.packageNameToDir.get(packageName);
+        if (dependencyId === undefined || !releaseIds.has(dependencyId)) {
+            continue;
+        }
+        for (const dependent of dependents) {
+            if (!releaseIds.has(dependent.id)) {
+                continue;
+            }
+            const edges = forwardEdges.get(dependencyId);
+            if (edges !== undefined) {
+                edges.push(dependent.id);
+            }
+            inDegree.set(dependent.id, (inDegree.get(dependent.id) ?? 0) + 1);
+        }
+    }
+    const queue = [];
+    for (const [id, degree] of inDegree) {
+        if (degree === 0) {
+            queue.push(id);
+        }
+    }
+    const sorted = [];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        if (id === undefined) {
+            break;
+        }
+        sorted.push(id);
+        const dependents = forwardEdges.get(id) ?? [];
+        for (const dependent of dependents) {
+            const newDegree = (inDegree.get(dependent) ?? 1) - 1;
+            inDegree.set(dependent, newDegree);
+            if (newDegree === 0) {
+                queue.push(dependent);
+            }
+        }
+    }
+    const sortedSet = new Set(sorted);
+    const cyclicIds = [];
+    for (const id of releaseIds) {
+        if (sortedSet.has(id)) {
+            continue;
+        }
+        sorted.push(id);
+        cyclicIds.push(id);
+    }
+    return { sorted, cyclicIds };
+}

package/dist/esm/renderChangelogMarkdown.d.ts

@@ -10,6 +10,29 @@ export interface RenderChangelogMarkdownOptions {
      */
     preservedSections?: readonly VersionedMarkdownSection[];
 }
+/** Options for `renderChangelogFiles`. */
+export interface RenderChangelogFilesOptions extends RenderChangelogMarkdownOptions {
+    /** How many of the newest sections the main file keeps; every section when omitted. Must be at least 1. */
+    keepVersions?: number;
+}
+/** A rendered archive file: the sections of one major version that the main file does not keep. */
+export interface RenderedChangelogArchive {
+    major: number;
+    content: string;
+}
+/** The rendered `CHANGELOG.md` and its archive files, newest major first. */
+export interface RenderedChangelogFiles {
+    main: string;
+    archives: RenderedChangelogArchive[];
+}
+/**
+ * Renders entries and preserved sections into `CHANGELOG.md` and its per-major archive files.
+ *
+ * The main file keeps the newest `keepVersions` sections, counting preserved sections, and links to each archive file
+ * from a paragraph below its header. Each older section goes to the archive file of its major version. Every file
+ * has the same header and footer.
+ */
+export declare function renderChangelogFiles(entries: ChangelogEntry[], options?: RenderChangelogFilesOptions): RenderedChangelogFiles;
 /**
  * Renders `ChangelogEntry[]` into a complete `CHANGELOG.md`-shaped string.
  *

package/dist/esm/renderChangelogMarkdown.js

@@ -1,22 +1,43 @@
+import semver from 'semver';
+import { describeArchivePath } from "./changelogArchive.js";
 import { compareVersionsDescending } from "./compareVersions.js";
 import { renderReleaseNotesSingle } from "./renderReleaseNotes.js";
 const CHANGELOG_HEADER = `# Changelog
 
 All notable changes to this project will be documented in this file.`;
 const CHANGELOG_FOOTER = `<!-- Generated by release-kit. Do not edit this file. Use .meta/changelog-overrides.json to override entries. -->`;
+export function renderChangelogFiles(entries, options) {
+    const sections = interleavePreservedSections(entries.map((entry) => ({ version: entry.version, text: renderReleaseNotesSingle(entry, options) })), options?.preservedSections ?? []).filter((section) => section.text.length > 0);
+    const keepVersions = options?.keepVersions;
+    if (keepVersions === undefined || sections.length <= keepVersions) {
+        return { main: renderFile(sections), archives: [] };
+    }
+    const archived = groupByMajor(sections.slice(keepVersions));
+    return {
+        main: renderFile(sections.slice(0, keepVersions), describeArchivePointer(archived.map(({ major }) => major))),
+        archives: archived.map(({ major, sections: majorSections }) => ({ major, content: renderFile(majorSections) })),
+    };
+}
 export function renderChangelogMarkdown(entries, options) {
-    const sections = interleavePreservedSections(entries.map((entry) => ({ version: entry.version, text: renderReleaseNotesSingle(entry, options) })), options?.preservedSections ?? []);
-    const body = sections
-        .map((part) => part.text)
-        .filter((text) => text.length > 0)
-        .join('\n');
-    const trimmedBody = body.trimEnd();
-    const parts = [CHANGELOG_HEADER];
-    if (trimmedBody.length > 0) {
-        parts.push(trimmedBody);
+    return renderChangelogFiles(entries, options).main;
+}
+function describeArchivePointer(majors) {
+    const links = majors.map((major) => `[v${major}](${describeArchivePath(major)})`);
+    return `Earlier versions: ${links.join(', ')}.`;
+}
+function groupByMajor(sections) {
+    const groups = new Map();
+    for (const section of sections) {
+        const major = semver.major(section.version);
+        const group = groups.get(major);
+        if (group === undefined) {
+            groups.set(major, [section]);
+        }
+        else {
+            group.push(section);
+        }
     }
-    parts.push(CHANGELOG_FOOTER);
-    return parts.join('\n\n') + '\n';
+    return Array.from(groups, ([major, majorSections]) => ({ major, sections: majorSections })).toSorted((a, b) => b.major - a.major);
 }
 function interleavePreservedSections(rendered, preserved) {
     const sorted = preserved.toSorted((a, b) => compareVersionsDescending(a.version, b.version));
@@ -35,6 +56,21 @@ function interleavePreservedSections(rendered, preserved) {
     result.push(...pending.slice(index));
     return result;
 }
+function renderFile(sections, paragraph) {
+    const body = sections
+        .map((section) => section.text)
+        .join('\n')
+        .trimEnd();
+    const parts = [CHANGELOG_HEADER];
+    if (paragraph !== undefined) {
+        parts.push(paragraph);
+    }
+    if (body.length > 0) {
+        parts.push(body);
+    }
+    parts.push(CHANGELOG_FOOTER);
+    return parts.join('\n\n') + '\n';
+}
 function withTrailingNewline(section) {
     return { version: section.version, text: `${section.text}\n` };
 }

package/dist/esm/reportPrepare.d.ts

@@ -11,9 +11,8 @@ export interface ReportPrepareOptions {
 /**
  * Formats a release plan into styled terminal output, without writing it.
  *
- * Single-workspace mode (without a `name` field) renders flat output; multi-workspace mode
- * renders section headers per workspace, an optional project section, and a tag summary
- * at the end.
+ * A plan whose package results lack a `name` and that lacks a composite result renders flat output, as a
+ * single-package release does; any other plan renders a section per target and a tag summary at the end.
  *
  * Whether the plan was applied is a property of the render, not of the plan: The same plan
  * produces the dry-run report and the applied report.

package/dist/esm/reportPrepare.js

@@ -1,9 +1,10 @@
 import { formatGlyphLine, formatStatusLine, measureGlyphColumn, STATUS_GLYPHS, truncateToWidth, } from '@williamthorsen/nmr-core';
 import { bold, dim, sectionHeader } from "./format.js";
 import { RELEASE_GLYPHS } from "./glyphs.js";
+import { PROJECT_TARGET_ID } from "./resolveReleaseTargets.js";
 const SUBJECT_COLUMN_BUDGET = 72;
 export function reportPrepare(plan, options) {
-    const isMultiWorkspace = plan.workspaces.some((w) => w.name !== undefined) || plan.project !== undefined;
+    const isMultiWorkspace = plan.targets.some((target) => target.kind === 'composite' || target.name !== undefined);
     if (isMultiWorkspace) {
         return formatMultiWorkspace(plan, options);
     }
@@ -13,8 +14,8 @@ function formatSingleWorkspace(result, options) {
     const dryRun = !options.applied;
     const { style } = options;
     const lines = [];
-    const workspace = result.workspaces[0];
-    if (workspace === undefined) {
+    const workspace = result.targets[0];
+    if (workspace === undefined || workspace.kind === 'composite') {
         return '';
     }
     const since = workspace.previousTag === undefined ? 'the beginning' : workspace.previousTag;
@@ -62,11 +63,13 @@ function formatMultiWorkspace(result, options) {
     const dryRun = !options.applied;
     const { style } = options;
     const lines = [];
-    for (const workspace of result.workspaces) {
-        formatWorkspaceSection(lines, workspace, dryRun, style);
-    }
-    if (result.project !== undefined) {
-        formatProjectSection(lines, result.project, dryRun, style);
+    for (const target of result.targets) {
+        if (target.kind === 'composite') {
+            formatProjectSection(lines, target, dryRun, style);
+        }
+        else {
+            formatWorkspaceSection(lines, target, dryRun, style);
+        }
     }
     formatFormatCommand(lines, result, options);
     formatWarnings(lines, result, style);
@@ -82,7 +85,7 @@ function formatMultiWorkspace(result, options) {
     return lines.join('\n');
 }
 function formatProjectSection(lines, project, dryRun, style) {
-    lines.push(`\n${sectionHeader('project')}`);
+    lines.push(`\n${sectionHeader(project.targetId === PROJECT_TARGET_ID ? 'project' : project.targetId)}`);
     const since = project.previousTag === undefined ? '(no previous release found)' : `since ${project.previousTag}`;
     lines.push(dim(`  Found ${project.commitCount} commits ${since}`));
     formatPolicyViolations(lines, project.policyViolations, style, '  ');
@@ -128,8 +131,8 @@ function formatWorkspaceSection(lines, workspace, dryRun, style) {
         lines.push(`  ${formatStatusLine(style, 'skipped', workspace.skipReason)}`);
         return;
     }
-    const { propagatedFrom } = workspace;
-    const isPropagatedOnly = workspace.propagatedOnly === true;
+    const propagatedFrom = workspace.kind === 'package' ? workspace.propagatedFrom : undefined;
+    const isPropagatedOnly = workspace.kind === 'package' && workspace.propagatedOnly === true;
     formatCommitSummary(lines, workspace, propagatedFrom, isPropagatedOnly);
     formatUnparseableWarning(lines, workspace, style, '  ');
     formatPolicyViolations(lines, workspace.policyViolations, style, '  ');
@@ -198,7 +201,7 @@ function formatChangelogFiles(lines, release, dryRun, style, indent = '') {
             continue;
         }
         if (preservation.preservedVersions.length > 0) {
-            lines.push(dim(`${indent}    Kept from the existing file: ${preservation.preservedVersions.join(', ')}`));
+            lines.push(dim(`${indent}    Kept from the existing changelog: ${preservation.preservedVersions.join(', ')}`));
         }
         const dropped = preservation.droppedUnversionedHeadings;
         if (dropped.length > 0) {
@@ -206,6 +209,15 @@ function formatChangelogFiles(lines, release, dryRun, style, indent = '') {
             lines.push(`${indent}    ${formatStatusLine(style, 'warning', message)}`);
         }
     }
+    const removedFiles = release.removedChangelogFiles ?? [];
+    for (const file of removedFiles) {
+        if (dryRun) {
+            lines.push(dim(`${indent}  [dry-run] Would remove changelog: ${file}`));
+        }
+        else {
+            lines.push(dim(`${indent}  Removing changelog: ${file}`));
+        }
+    }
 }
 function formatPreviewFiles(lines, release, dryRun, indent = '') {
     const previewFiles = release.previewFiles ?? [];

package/dist/esm/resolveCommandTags.d.ts

@@ -7,7 +7,9 @@ import type { ReleaseKitConfig } from './types.js';
  * `mergeMonorepoConfig` rejects, and a workspace that does not resolve to any package, which is not single-package
  * mode.
  *
- * In monorepo mode the workspace list is `userConfig` merged over the discovered workspaces, as `prepare` builds it.
+ * In monorepo mode the workspace list is `userConfig` merged over the discovered workspaces, as `prepare` builds it,
+ * and each directory target and a declared composite (a `project` block or a `releases` composite) contribute their
+ * `tagPrefix`, so that their tags resolve alongside them.
  * A tag on HEAD whose workspace the config excludes still counts as a tag on HEAD, so `--tags` may name it and a
  * HEAD whose tags are all excluded returns an empty list rather than failing. Each excluded tag that the run
  * selects, every one without `--tags` or the named ones with it, is dropped with a warning.

package/dist/esm/resolveCommandTags.js

@@ -1,4 +1,3 @@
-import { basename } from 'node:path';
 import { reportError } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { deriveWorkspaceConfig } from "./deriveWorkspaceConfig.js";
@@ -20,14 +19,21 @@ export function resolveCommandTags(tags, userConfig) {
         process.exit(1);
     }
     let workspaces;
+    let directories = [];
+    let project;
     let singleWorkspace;
-    const excludedDirs = workspace.kind === 'packages' ? collectExcludedDirs(userConfig) : new Set();
+    let excludedPaths = new Set();
     try {
         if (workspace.kind === 'single-package') {
             singleWorkspace = deriveWorkspaceConfig('.');
         }
         else {
-            workspaces = buildMonorepoWorkspaces(workspace.packageDirs, userConfig, excludedDirs);
+            const merged = mergeMonorepoConfig(workspace.packageDirs, userConfig, readRootPackageVersion());
+            const excluded = merged.excludedWorkspaces ?? [];
+            workspaces = [...merged.workspaces, ...excluded];
+            directories = merged.directories ?? [];
+            project = merged.project;
+            excludedPaths = new Set(excluded.map((excludedWorkspace) => excludedWorkspace.workspacePath));
         }
     }
     catch (error) {
@@ -36,7 +42,7 @@ export function resolveCommandTags(tags, userConfig) {
     }
     let resolvedTags;
     if (workspaces !== undefined) {
-        resolvedTags = resolveReleaseTags({ workspaces });
+        resolvedTags = resolveReleaseTags({ workspaces, directories, ...(project !== undefined && { project }) });
     }
     else if (singleWorkspace !== undefined) {
         resolvedTags = resolveReleaseTags({ singleWorkspace });
@@ -59,27 +65,14 @@ export function resolveCommandTags(tags, userConfig) {
         }
         resolvedTags = resolvedTags.filter((t) => tags.includes(t.tag));
     }
-    return dropExcludedTags(resolvedTags, excludedDirs);
+    return dropExcludedTags(resolvedTags, excludedPaths, userConfig?.releases === undefined ? 'legacy' : 'releases');
 }
-function buildMonorepoWorkspaces(packageDirs, userConfig, excludedDirs) {
-    const { workspaces } = mergeMonorepoConfig(packageDirs, userConfig, readRootPackageVersion());
-    if (excludedDirs.size === 0) {
-        return workspaces;
-    }
-    const excluded = packageDirs
-        .filter((packageDir) => excludedDirs.has(basename(packageDir)))
-        .map((packageDir) => deriveWorkspaceConfig(packageDir));
-    return [...workspaces, ...excluded];
-}
-function collectExcludedDirs(userConfig) {
-    const overrides = userConfig?.workspaces ?? [];
-    return new Set(overrides.filter((override) => override.shouldExclude === true).map((override) => override.dir));
-}
-function dropExcludedTags(resolvedTags, excludedDirs) {
+function dropExcludedTags(resolvedTags, excludedPaths, surface) {
     const retained = [];
     for (const resolvedTag of resolvedTags) {
-        if (excludedDirs.has(resolvedTag.dir)) {
-            console.warn(formatExcludedSkip(resolvedTag));
+        if (resolvedTag.kind === 'package' && excludedPaths.has(resolvedTag.workspacePath)) {
+            const setting = surface === 'releases' ? `releases.${resolvedTag.dir}: false` : undefined;
+            console.warn(formatExcludedSkip(resolvedTag, setting));
         }
         else {
             retained.push(resolvedTag);

package/dist/esm/resolveReleaseDeclaration.d.ts

@@ -0,0 +1,45 @@
+import type { ReleaseKitConfig, WorkspaceConfig } from './types.js';
+/** The composite that a config declares, before the defaults and the root `package.json` check of `loadConfig`. */
+export interface DeclaredComposite {
+    /** Name that selects the composite; `undefined` for a `project` block. */
+    name?: string;
+    /** Target names of the members; `undefined` means every retained workspace. */
+    members?: string[];
+    /** Commit window; `undefined` means the union of the members' windows. */
+    paths?: string[];
+    tagPrefix?: string;
+}
+/** A directory that a `releases` entry declares as a target, before `loadConfig` checks it on disk. */
+export interface DeclaredDirectory {
+    /** Name of the target, its entry key. */
+    name: string;
+    /** Repo-relative POSIX path of the directory; `.` for the repo root. */
+    path: string;
+    /** Commit window; `undefined` for the repo root, whose window is the whole repo. */
+    paths?: string[];
+    tagPrefix?: string;
+    legacyIdentities?: WorkspaceConfig['legacyIdentities'];
+}
+/** The release targets that a config declares over the discovered workspaces. */
+export interface ReleaseDeclaration {
+    /** Retained workspaces in discovery order, each with its target name and legacy identities applied. */
+    retained: WorkspaceConfig[];
+    /** Discovered workspaces that the config excludes, in discovery order. */
+    excluded: WorkspaceConfig[];
+    /** Directories that `releases` entries declare as targets, in config order. */
+    directories: DeclaredDirectory[];
+    composite?: DeclaredComposite;
+}
+/** Returns the name of a workspace's release target. */
+export declare function getTargetName(workspace: WorkspaceConfig): string;
+/** Normalizes a configured path to the repo-relative POSIX form of a discovered `workspacePath`. */
+export declare function normalizeWorkspacePath(configuredPath: string): string;
+/**
+ * Projects the config's `releases` block, or its `workspaces` and `project` blocks, onto the discovered workspaces.
+ *
+ * Every discovered workspace is retained under its `dir` unless an entry excludes or renames it, and a `releases`
+ * entry whose path isn't a discovered workspace declares a directory. Throws when a `releases` entry names a path
+ * outside the repo, sets `tagPrefix` on a workspace, excludes a name that isn't a workspace's `dir`, repeats a path,
+ * declares a second composite, or includes a target that is neither a retained workspace nor a directory.
+ */
+export declare function resolveReleaseDeclaration(workspaces: readonly WorkspaceConfig[], userConfig: ReleaseKitConfig | undefined): ReleaseDeclaration;