@williamthorsen/release-kit 14.0.0 → 14.2.0

package/dist/esm/loadConfig.js

@@ -11,7 +11,9 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
 import { DEFAULT_CHANGELOG_JSON_CONFIG, DEFAULT_PROJECT_TAG_PREFIX, DEFAULT_RELEASE_NOTES_CONFIG, DEFAULT_VERSION_PATTERNS, DEFAULT_WORK_TYPES, } from "./defaults.js";
+import { deriveDirectoryConfig } from "./deriveDirectoryConfig.js";
 import { deriveWorkspaceConfig } from "./deriveWorkspaceConfig.js";
+import { getTargetName, normalizeWorkspacePath, resolveReleaseDeclaration, } from "./resolveReleaseDeclaration.js";
 import { isRecord } from "./typeGuards.js";
 export const ROOT_PACKAGE_JSON_PATH = 'package.json';
 export function readRootPackageVersion() {
@@ -55,33 +57,25 @@ export async function loadConfig(configPath) {
     return resolved;
 }
 export function mergeMonorepoConfig(discoveredPaths, userConfig, rootPackage) {
-    let workspaces = discoveredPaths.map((workspacePath) => deriveWorkspaceConfig(workspacePath));
-    assertUniqueTagPrefixes(workspaces);
-    if (userConfig?.workspaces !== undefined) {
-        const overrides = new Map(userConfig.workspaces.map((w) => [w.dir, w]));
-        workspaces = workspaces
-            .filter((w) => {
-            const override = overrides.get(w.dir);
-            return override?.shouldExclude !== true;
-        })
-            .map((w) => {
-            const override = overrides.get(w.dir);
-            if (override?.legacyIdentities === undefined) {
-                return w;
-            }
-            assertLegacyIdentityDoesNotMatchCurrent(w.dir, w.name, w.tagPrefix, override.legacyIdentities);
-            return { ...w, legacyIdentities: override.legacyIdentities.map((identity) => ({ ...identity })) };
-        });
+    const discovered = discoveredPaths.map((workspacePath) => deriveWorkspaceConfig(workspacePath));
+    assertUniqueTagPrefixes(discovered);
+    const { retained: workspaces, excluded, directories: declaredDirectories, composite, } = resolveReleaseDeclaration(discovered, userConfig);
+    const directories = declaredDirectories.map((declared) => deriveDirectoryConfig(declared));
+    for (const workspace of workspaces) {
+        if (workspace.legacyIdentities !== undefined) {
+            assertLegacyIdentityDoesNotMatchCurrent(workspace.dir, workspace.name, workspace.tagPrefix, workspace.legacyIdentities);
+        }
     }
     if (userConfig?.retiredPackages !== undefined) {
         assertRetiredPackagesDoNotCollideWithActive(workspaces, userConfig.retiredPackages);
     }
-    const project = resolveProjectConfig(userConfig?.project, rootPackage, workspaces);
+    const project = resolveProjectConfig(composite, rootPackage, workspaces);
     const workTypes = resolveWorkTypes(userConfig?.workTypes);
     const versionPatterns = userConfig?.versionPatterns === undefined ? { ...DEFAULT_VERSION_PATTERNS } : { ...userConfig.versionPatterns };
     const changelogJson = mergeChangelogJsonConfig(userConfig?.changelogJson);
     const releaseNotes = mergeReleaseNotesConfig(userConfig?.releaseNotes);
-    assertNoTagPrefixCollisions(workspaces, userConfig?.retiredPackages, project);
+    assertNoSharedVersionFiles(workspaces, directories, project);
+    assertNoTagPrefixCollisions(workspaces, directories, userConfig?.retiredPackages, project);
     const result = {
         workspaces,
         workTypes,
@@ -89,6 +83,12 @@ export function mergeMonorepoConfig(discoveredPaths, userConfig, rootPackage) {
         changelogJson,
         releaseNotes,
     };
+    if (excluded.length > 0) {
+        result.excludedWorkspaces = excluded;
+    }
+    if (directories.length > 0) {
+        result.directories = directories;
+    }
     if (project !== undefined) {
         result.project = project;
     }
@@ -96,6 +96,9 @@ export function mergeMonorepoConfig(discoveredPaths, userConfig, rootPackage) {
     return result;
 }
 function applyOptionalPassthroughFields(result, userConfig) {
+    if (userConfig?.changelogMarkdown !== undefined) {
+        result.changelogMarkdown = userConfig.changelogMarkdown;
+    }
     if (userConfig?.formatCommand !== undefined) {
         result.formatCommand = userConfig.formatCommand;
     }
@@ -110,14 +113,14 @@ export function mergeSinglePackageConfig(userConfig) {
     if (userConfig?.project !== undefined) {
         throw new Error('project block is not supported in single-package mode');
     }
+    if (userConfig?.releases !== undefined) {
+        throw new Error('releases block is not supported in single-package mode');
+    }
     const workTypes = resolveWorkTypes(userConfig?.workTypes);
     const versionPatterns = userConfig?.versionPatterns === undefined ? { ...DEFAULT_VERSION_PATTERNS } : { ...userConfig.versionPatterns };
     const changelogJson = mergeChangelogJsonConfig(userConfig?.changelogJson);
     const releaseNotes = mergeReleaseNotesConfig(userConfig?.releaseNotes);
     const result = {
-        tagPrefix: 'v',
-        packageFiles: ['package.json'],
-        changelogPaths: ['.'],
         workTypes,
         versionPatterns,
         changelogJson,
@@ -161,22 +164,52 @@ function assertRetiredPackagesDoNotCollideWithActive(workspaces, retiredPackages
         }
     }
 }
-function resolveProjectConfig(userProject, rootPackage, workspaces) {
-    if (userProject === undefined) {
+function resolveProjectConfig(composite, rootPackage, workspaces) {
+    if (composite === undefined) {
         return undefined;
     }
+    const subject = composite.name === undefined ? 'project block' : `composite release '${composite.name}'`;
     if (rootPackage === undefined || !rootPackage.exists) {
-        throw new Error(`project block requires a root ${ROOT_PACKAGE_JSON_PATH}; create one with a 'version' field at the repo root`);
+        throw new Error(`${subject} requires a root ${ROOT_PACKAGE_JSON_PATH}; create one with a 'version' field at the repo root`);
     }
     if (rootPackage.version === undefined) {
-        throw new Error(`project block requires root ${ROOT_PACKAGE_JSON_PATH} to have a 'version' field; add a 'version' field to the root package.json`);
+        throw new Error(`${subject} requires root ${ROOT_PACKAGE_JSON_PATH} to have a 'version' field; add a 'version' field to the root package.json`);
     }
     return {
-        paths: userProject.paths ?? workspaces.flatMap((workspace) => workspace.paths),
-        tagPrefix: userProject.tagPrefix ?? DEFAULT_PROJECT_TAG_PREFIX,
+        paths: composite.paths ?? workspaces.flatMap((workspace) => workspace.paths),
+        tagPrefix: composite.tagPrefix ?? DEFAULT_PROJECT_TAG_PREFIX,
+        ...(composite.name !== undefined && { name: composite.name }),
+        ...(composite.members !== undefined && { members: composite.members }),
     };
 }
-function assertNoTagPrefixCollisions(workspaces, retiredPackages, project) {
+function assertNoSharedVersionFiles(workspaces, directories, project) {
+    const owners = [
+        ...directories.map((directory) => ({
+            label: `directory release '${directory.name}'`,
+            versionFiles: [directory.versionFile],
+        })),
+        ...workspaces.map((workspace) => ({
+            label: `workspace '${getTargetName(workspace)}'`,
+            versionFiles: workspace.packageFiles.map(normalizeWorkspacePath),
+        })),
+        ...(project === undefined
+            ? []
+            : [
+                {
+                    label: project.name === undefined ? 'the project release' : `composite release '${project.name}'`,
+                    versionFiles: [ROOT_PACKAGE_JSON_PATH],
+                },
+            ]),
+    ];
+    for (const [index, directory] of directories.entries()) {
+        const peer = owners.slice(index + 1).find((owner) => owner.versionFiles.includes(directory.versionFile));
+        if (peer !== undefined) {
+            throw new Error(`directory release '${directory.name}' and ${peer.label} share the version file '${directory.versionFile}', ` +
+                "so each release would overwrite the other's version and changelog; declare only one of them");
+        }
+    }
+}
+function assertNoTagPrefixCollisions(workspaces, directories, retiredPackages, project) {
     const sources = [];
     for (const workspace of workspaces) {
         const owner = `ws:${workspace.dir}`;
@@ -190,6 +223,18 @@ function assertNoTagPrefixCollisions(workspaces, retiredPackages, project) {
             });
         }
     }
+    for (const directory of directories) {
+        const owner = `dir:${directory.path}`;
+        sources.push({ prefix: directory.tagPrefix, label: `directory release '${directory.name}'`, owner });
+        const legacyIdentities = directory.legacyIdentities ?? [];
+        for (const identity of legacyIdentities) {
+            sources.push({
+                prefix: identity.tagPrefix,
+                label: `directory release '${directory.name}' legacyIdentities entry (name='${identity.name}')`,
+                owner,
+            });
+        }
+    }
     const retiredEntries = (retiredPackages ?? []).entries();
     for (const [index, retired] of retiredEntries) {
         sources.push({
@@ -199,7 +244,11 @@ function assertNoTagPrefixCollisions(workspaces, retiredPackages, project) {
         });
     }
     if (project !== undefined) {
-        sources.push({ prefix: project.tagPrefix, label: 'project', owner: 'project' });
+        sources.push({
+            prefix: project.tagPrefix,
+            label: project.name === undefined ? 'project' : `composite release '${project.name}'`,
+            owner: 'project',
+        });
     }
     for (let i = 0; i < sources.length; i++) {
         for (let j = i + 1; j < sources.length; j++) {

package/dist/esm/matchesTagPrefix.d.ts

@@ -0,0 +1,2 @@
+/** Checks whether a tag name is one of the prefixes followed by a complete SemVer version. */
+export declare function matchesTagPrefix(tagName: string, tagPrefixes: readonly string[]): boolean;

package/dist/esm/matchesTagPrefix.js

@@ -0,0 +1,4 @@
+const SEMVER_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+export function matchesTagPrefix(tagName, tagPrefixes) {
+    return tagPrefixes.some((prefix) => tagName.startsWith(prefix) && SEMVER_VERSION_PATTERN.test(tagName.slice(prefix.length)));
+}

package/dist/esm/npmRegistry.d.ts

@@ -0,0 +1,35 @@
+export declare const AUTH_ERROR_CODES: ReadonlySet<string>;
+export declare const UNREACHABLE_ERROR_CODES: ReadonlySet<string>;
+/**
+ * Classifies the outcome of `npm view <package> version --json`.
+ *
+ * Only `E404` means that the registry doesn't know the package; any other failure leaves the question open.
+ */
+export declare function classifyNpmPackageLookup(result: NpmCommandResult): NpmPackageLookup;
+/** Looks up whether a package exists on the npm registry, querying `registry` when one is given. */
+export declare function lookUpNpmPackage(packageName: string, registry?: string): NpmPackageLookup;
+export interface NpmCommandResult {
+    exitOk: boolean;
+    stdout: string;
+}
+export interface NpmErrorPayload {
+    code: string;
+    summary: string;
+}
+export type NpmPackageLookup = {
+    status: 'published';
+} | {
+    status: 'unpublished';
+} | {
+    status: 'unverifiable';
+    detail: string;
+};
+/** Reads npm's `--json` error envelope, which npm writes to stdout on both the success and failure paths. */
+export declare function readNpmError(stdout: string): NpmErrorPayload | undefined;
+/**
+ * Runs npm with the given arguments, capturing stdout whether or not the command exits zero.
+ *
+ * The arguments are expected to include `--json`: npm writes its machine-readable error envelope to stdout,
+ * which `execFileSync` attaches to the thrown error instead of returning it.
+ */
+export declare function runNpmJson(args: readonly string[]): NpmCommandResult;

package/dist/esm/npmRegistry.js

@@ -0,0 +1,58 @@
+import { execFileSync } from 'node:child_process';
+import { isRecord } from "./typeGuards.js";
+export const AUTH_ERROR_CODES = new Set(['E401', 'ENEEDAUTH']);
+export const UNREACHABLE_ERROR_CODES = new Set([
+    'EAI_AGAIN',
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'ENETUNREACH',
+    'ENOTFOUND',
+    'ERR_SOCKET_TIMEOUT',
+    'ETIMEDOUT',
+]);
+export function classifyNpmPackageLookup(result) {
+    if (result.exitOk) {
+        return { status: 'published' };
+    }
+    const error = readNpmError(result.stdout);
+    if (error === undefined) {
+        return { status: 'unverifiable', detail: 'The npm registry query failed without a readable error payload' };
+    }
+    if (error.code === 'E404') {
+        return { status: 'unpublished' };
+    }
+    if (AUTH_ERROR_CODES.has(error.code)) {
+        return { status: 'unverifiable', detail: `The npm registry rejected the session (${error.code})` };
+    }
+    if (UNREACHABLE_ERROR_CODES.has(error.code)) {
+        return { status: 'unverifiable', detail: `Cannot reach the npm registry (${error.code})` };
+    }
+    return { status: 'unverifiable', detail: `The npm registry query failed (${error.code}): ${error.summary}` };
+}
+export function lookUpNpmPackage(packageName, registry) {
+    const args = ['view', packageName, 'version', '--json', ...(registry === undefined ? [] : ['--registry', registry])];
+    return classifyNpmPackageLookup(runNpmJson(args));
+}
+export function readNpmError(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(parsed) || !isRecord(parsed['error']) || typeof parsed['error']['code'] !== 'string') {
+        return undefined;
+    }
+    const { code, summary } = parsed['error'];
+    return { code, summary: typeof summary === 'string' ? summary : '' };
+}
+export function runNpmJson(args) {
+    try {
+        return { exitOk: true, stdout: execFileSync('npm', args, { encoding: 'utf8', stdio: 'pipe' }) };
+    }
+    catch (error) {
+        const stdout = isRecord(error) && typeof error['stdout'] === 'string' ? error['stdout'] : '';
+        return { exitOk: false, stdout };
+    }
+}

package/dist/esm/prepareCommand.d.ts

@@ -49,7 +49,7 @@ export declare function parseArgs(argv: string[]): {
 };
 /**
  * Orchestrates the CLI `prepare` command: checks the working tree, loads and validates the config, discovers the
- * workspaces, and prepares the release in single-package or monorepo mode.
+ * workspaces, and prepares the release over the targets of the repo shape.
  *
  * A relative `--config` resolves against `invocationDir`.
  */

package/dist/esm/prepareCommand.js

@@ -2,18 +2,18 @@ import { execSync } from 'node:child_process';
 import { formatGlyphLine, parseArgsOrExit, reportError, } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { assertCleanWorkingTree } from "./assertCleanWorkingTree.js";
+import { assertReleasesOnNpm } from "./assertReleasesOnNpm.js";
 import { configFlagSchema } from "./configFlagSchema.js";
 import { describeEmptyWorkspace, discoverWorkspaces } from "./discoverWorkspaces.js";
 import { dim } from "./format.js";
 import { RELEASE_GLYPHS } from "./glyphs.js";
-import { mergeMonorepoConfig, mergeSinglePackageConfig, readRootPackageVersion } from "./loadConfig.js";
 import { loadValidatedConfig, reportConfigProblem, reportConfigWarnings } from "./loadValidatedConfig.js";
 import { RELEASE_SUMMARY_FILE, RELEASE_TAGS_FILE } from "./releaseFiles.js";
 import { applyReleasePlan } from "./releasePlan.js";
-import { releasePrepare } from "./releasePrepare.js";
-import { releasePrepareMono } from "./releasePrepareMono.js";
+import { releasePrepareTargets } from "./releasePrepareTargets.js";
 import { reportPrepare } from "./reportPrepare.js";
 import { resolveConfigFlag } from "./resolveConfigFlag.js";
+import { isSinglePackageTargets, PROJECT_TARGET_ID, resolveReleaseTargets, SINGLE_PACKAGE_TARGET_ID, } from "./resolveReleaseTargets.js";
 const VALID_BUMP_TYPES = ['major', 'minor', 'patch'];
 const CANONICAL_SEMVER_PATTERN = /^\d+\.\d+\.\d+$/;
 function isReleaseType(value) {
@@ -99,56 +99,70 @@ export async function prepareCommand(argv, styles, invocationDir) {
         reportError(`No workspace package to release. ${describeEmptyWorkspace(workspace)}`);
         process.exit(1);
     }
-    if (workspace.kind === 'single-package') {
-        runSinglePackageMode(userConfig, options, only, setVersion, dryRun, styles.stdout);
-    }
-    else {
-        runMonorepoMode(workspace.packageDirs, userConfig, options, only, setVersion, dryRun, styles.stdout);
-    }
+    const config = resolveTargetsOrExit(userConfig, workspace, only, setVersion);
+    const targetOptions = {
+        ...options,
+        ...(only !== undefined && { only }),
+        ...(setVersion !== undefined && { setVersions: resolveSetVersions(setVersion, config.targets) }),
+    };
+    runAndReport(() => {
+        const plan = releasePrepareTargets(config, targetOptions);
+        assertReleasesOnNpm(findReleasedPackagePaths(plan, config.targets));
+        return plan;
+    }, dryRun, styles.stdout);
 }
-function runSinglePackageMode(userConfig, options, only, setVersion, dryRun, style) {
-    if (only !== undefined) {
-        reportError('--only is only supported for monorepo configurations');
-        process.exit(1);
-    }
-    if (setVersion !== undefined && !CANONICAL_SEMVER_PATTERN.test(setVersion)) {
-        reportError(`Invalid --set-version value "${setVersion}". Must be canonical semver (N.N.N, no pre-release suffix).`);
-        process.exit(1);
-    }
-    const config = mergeSinglePackageConfig(userConfig);
-    runAndReport(() => releasePrepare(config, { ...options, ...(setVersion !== undefined && { setVersion }) }), dryRun, style);
+function findReleasedPackagePaths(plan, targets) {
+    const releasedIds = new Set(plan.targets.flatMap((result) => result.status === 'released' && result.kind === 'package' ? [result.targetId] : []));
+    return targets.flatMap((target) => target.kind === 'package' && releasedIds.has(target.id) ? [target.packagePath] : []);
 }
-function runMonorepoMode(discoveredPaths, userConfig, options, only, setVersion, dryRun, style) {
+function resolveTargetsOrExit(userConfig, discovery, only, setVersion) {
+    if (discovery.kind === 'single-package') {
+        if (only !== undefined) {
+            reportError('--only is only supported for monorepo configurations');
+            process.exit(1);
+        }
+        if (setVersion !== undefined && !CANONICAL_SEMVER_PATTERN.test(setVersion)) {
+            reportError(`Invalid --set-version value "${setVersion}". Must be canonical semver (N.N.N, no pre-release suffix).`);
+            process.exit(1);
+        }
+        return resolveReleaseTargets(userConfig, discovery);
+    }
     let config;
     try {
-        const rootPackage = readRootPackageVersion();
-        config = mergeMonorepoConfig(discoveredPaths, userConfig, rootPackage);
+        config = resolveReleaseTargets(userConfig, discovery);
     }
     catch (error) {
         reportError(`Failed to resolve workspaces: ${describeError(error)}`);
         process.exit(1);
     }
-    if (setVersion !== undefined && config.project !== undefined) {
+    if (setVersion !== undefined && config.targets.some((target) => target.kind === 'composite')) {
         reportError('--set-version cannot be combined with a project release. ' +
             "--set-version sets individual workspaces' versions; a project release rolls up every " +
-            'contributing workspace. To use --set-version, run on a config without a `project` block.');
+            'contributing workspace. To use --set-version, run on a config without a `project` block or a `releases` composite.');
         process.exit(1);
     }
-    const knownNames = config.workspaces.map((w) => w.dir);
+    const knownNames = listSelectableIds(config.targets);
     const onlyNames = only ?? [];
     for (const name of onlyNames) {
         if (knownNames.includes(name)) {
             continue;
         }
-        reportError(`Unknown workspace "${name}". Known workspaces: ${knownNames.join(', ')}`);
+        reportError(`Unknown release target "${name}". Known targets: ${knownNames.join(', ')}`);
         process.exit(1);
     }
-    const monorepoOptions = {
-        ...options,
-        ...(only !== undefined && { only }),
-        ...(setVersion !== undefined && { setVersions: parseSetVersions(setVersion, knownNames) }),
-    };
-    runAndReport(() => releasePrepareMono(config, monorepoOptions), dryRun, style);
+    return config;
+}
+function resolveSetVersions(setVersion, targets) {
+    if (isSinglePackageTargets(targets)) {
+        return new Map([[SINGLE_PACKAGE_TARGET_ID, setVersion]]);
+    }
+    return parseSetVersions(setVersion, listMemberIds(targets));
+}
+function listSelectableIds(targets) {
+    return targets.flatMap((target) => (target.id === PROJECT_TARGET_ID ? [] : [target.id]));
+}
+function listMemberIds(targets) {
+    return targets.flatMap((target) => (target.kind === 'composite' ? [] : [target.id]));
 }
 function parseSetVersions(value, knownNames) {
     const setVersions = new Map();
@@ -157,16 +171,16 @@ function parseSetVersions(value, knownNames) {
         const name = entry.slice(0, Math.max(0, separatorIndex));
         const version = entry.slice(separatorIndex + 1);
         if (separatorIndex <= 0 || !CANONICAL_SEMVER_PATTERN.test(version)) {
-            reportError(`Invalid --set-version entry "${entry}". In monorepo mode, each entry must be <workspace>@N.N.N ` +
+            reportError(`Invalid --set-version entry "${entry}". In monorepo mode, each entry must be <target>@N.N.N ` +
                 '(canonical semver, no pre-release suffix), e.g. --set-version=arrays@1.0.0.');
             process.exit(1);
         }
         if (!knownNames.includes(name)) {
-            reportError(`Unknown workspace "${name}" in --set-version. Known workspaces: ${knownNames.join(', ')}`);
+            reportError(`Unknown release target "${name}" in --set-version. Known targets: ${knownNames.join(', ')}`);
             process.exit(1);
         }
         if (setVersions.has(name)) {
-            reportError(`--set-version names workspace "${name}" more than once`);
+            reportError(`--set-version names target "${name}" more than once`);
             process.exit(1);
         }
         setVersions.set(name, version);

package/dist/esm/prepareTarget.d.ts

@@ -0,0 +1,103 @@
+import { type UntaggedBaseline } from './assertTaggedBaseline.js';
+import { type ReleaseHistory } from './buildChangelogEntries.js';
+import { type OverrideContext } from './changelogOverrides.js';
+import { type GenerateChangelogOptions } from './generateChangelogs.js';
+import type { PlannedWrite } from './releasePlan.js';
+import type { DirectoryTarget, PropagationSource, ReleasedTargetResult, ReleaseSettings, ReleaseTarget, ReleaseType, TargetPrepareResult } from './types.js';
+/** The shared settings that the prepare step reads, which do not include the release-notes settings. */
+export type TargetPrepareSettings = Omit<ReleaseSettings, 'releaseNotes'>;
+/** One read of a target's release windows, and the untagged baseline that it found, if any. */
+export interface TargetReading {
+    history: ReleaseHistory;
+    untagged: UntaggedBaseline | undefined;
+}
+/** Outcome of {@link decideTargetRelease}: a release at a decided level or at an explicit version, or a skip. */
+export type TargetDecision = {
+    outcome: 'release';
+    releaseType: ReleaseType;
+    bumpOverride: ReleaseType | undefined;
+    setVersion: undefined;
+} | {
+    outcome: 'release';
+    releaseType: undefined;
+    bumpOverride: undefined;
+    setVersion: string;
+} | {
+    outcome: 'skip';
+    skipReason: string;
+};
+/** The release level that a target takes, whether its own commits or a dependency's bump decided it. */
+export interface TargetRelease {
+    releaseType: ReleaseType;
+    /** Dependencies whose bumps this release records; present for a propagated or mixed release. */
+    propagatedFrom?: PropagationSource[];
+}
+/** Inputs to {@link planTargetRelease}. */
+export interface PlanTargetReleaseArgs {
+    target: ReleaseTarget;
+    settings: TargetPrepareSettings;
+    /** The level of the release and, for a propagated release, the dependencies that set it. */
+    release: TargetRelease;
+    /**
+     * The decision behind a direct release; undefined for a release that propagation alone set, whose own window called
+     * for none.
+     */
+    decision: Extract<TargetDecision, {
+        outcome: 'release';
+    }> | undefined;
+    /** The window that the target's read produced. */
+    history: ReleaseHistory;
+    overrideContext: OverrideContext;
+    /** Section titles in priority order. */
+    sectionOrder: string[];
+    /** Header of the section under which a propagation-only entry lists its dependencies. */
+    dependenciesHeader: string;
+    /** True when release-notes previews are requested and `changelogJson.enabled` is true. */
+    shouldPlanPreviews: boolean;
+    /** The release date, as `YYYY-MM-DD`. */
+    today: string;
+}
+/** A target's planned release: its result and the tag, writes, and modified files that the run collects. */
+export interface PlannedTargetRelease {
+    result: ReleasedTargetResult;
+    tag: string;
+    writes: PlannedWrite[];
+    /** Archive files of the target's `CHANGELOG.md` that the release removes. */
+    removals: string[];
+    /**
+     * Files that the format command covers: the version files, the `CHANGELOG.md` and its archive files, and any
+     * changelog JSON.
+     */
+    modifiedFiles: string[];
+    /** Warnings raised while planning the release-notes previews. */
+    warnings: string[];
+}
+/** Reads a target's release windows under its tag prefixes and commit window, and finds its untagged baseline. */
+export declare function readTargetHistory(target: ReleaseTarget, settings: TargetPrepareSettings): TargetReading;
+/**
+ * Returns the bounds of a target's history read: its current and legacy tag prefixes, its commit window, and, for a
+ * workspace or a directory other than the repo root, the scope to which change-record entries route, which is its name.
+ */
+export declare function describeHistoryWindow(target: ReleaseTarget): GenerateChangelogOptions;
+/**
+ * Decides a target's direct release from its window: `setVersion` releases at that version, and otherwise the
+ * window's bump, `force`, and `bumpOverride` decide as {@link decideRelease} states.
+ */
+export declare function decideTargetRelease(target: ReleaseTarget, history: ReleaseHistory, options: {
+    force: boolean;
+    bumpOverride: ReleaseType | undefined;
+    setVersion: string | undefined;
+}): TargetDecision;
+/**
+ * Plans a target's release: the version bump, the changelogs, and the release-notes previews, and builds its result.
+ *
+ * The changelog entries come from the target's release windows, with the synthetic "Forced version bump." entry for a
+ * window that doesn't yield any item, or, for a release that propagation alone set, from one synthetic entry listing
+ * the dependencies. Overrides apply before `changelog.json` and `CHANGELOG.md` render from the merged set, and
+ * `CHANGELOG.md` keeps the existing sections whose versions the merged set lacks.
+ */
+export declare function planTargetRelease(args: PlanTargetReleaseArgs): PlannedTargetRelease;
+/** Builds the result of a target that skips, from the window that its read produced. */
+export declare function buildSkippedTargetResult(target: ReleaseTarget, history: ReleaseHistory, skipReason: string): TargetPrepareResult;
+/** Reports whether a directory target is the repo root, which reads the whole repo and renders every entry. */
+export declare function isRepoRoot(target: DirectoryTarget): boolean;