versionary 0.32.0 → 1.0.1

package/dist/release/plan.js

@@ -4,6 +4,7 @@ import { loadConfig } from "../config/load-config.js";
 import { analyzeParsedCommits, applyRevertSuppression, getParsedCommitsForPath, getParsedCommitsSinceLastTag, } from "../git/commits.js";
 import { resolvePackageStrategyContext } from "../strategy/package-context.js";
 import { resolveVersionStrategy } from "../strategy/resolve.js";
+import { releaseTypeBetween, resolveReleaseAsOverride } from "./release-as.js";
 import { bumpVersion, maxReleaseType } from "./semver.js";
 import { readBaselineSha, readReleaseTargets } from "./state.js";
 function getMode(configMode) {
@@ -78,19 +79,34 @@ export function createReleasePlan(cwd = process.cwd()) {
         }
         const effectiveCommits = applyRevertSuppression(parsedCommits);
         const commits = effectiveCommits;
-        const releaseType = analyzeParsedCommits(parsedCommits);
-        const nextVersion = releaseType
-            ? bumpVersion(packageCurrentVersion, releaseType, {
-                allowStableMajor: allowStableMajorForPath(pkg.path),
-            })
-            : null;
+        const analyzedType = analyzeParsedCommits(parsedCommits);
+        const override = resolveReleaseAsOverride(commits, packageCurrentVersion);
+        let releaseType;
+        let nextVersion;
+        let bumpReason;
+        if (override) {
+            // An explicit `Release-As:` footer forces a release with the requested
+            // version, even when the conventional-commit analysis produces no bump.
+            nextVersion = override.version;
+            releaseType = releaseTypeBetween(packageCurrentVersion, override.version);
+            bumpReason = "release-as";
+        }
+        else {
+            releaseType = analyzedType;
+            nextVersion = releaseType
+                ? bumpVersion(packageCurrentVersion, releaseType, {
+                    allowStableMajor: allowStableMajorForPath(pkg.path),
+                })
+                : null;
+            bumpReason = nextVersion ? "direct" : undefined;
+        }
         return {
             path: pkg.path,
             implicitRoot: pkg.implicitRoot,
             releaseType,
             currentVersion: packageCurrentVersion,
             nextVersion,
-            bumpReason: nextVersion ? "direct" : undefined,
+            bumpReason,
             commits,
             parsedCommits,
             resolvedVersionFile: packageContext.versionFile,
@@ -119,39 +135,179 @@ export function createReleasePlan(cwd = process.cwd()) {
         ...(implicitRootPlan ? [implicitRootPlan] : []),
     ].sort((a, b) => a.path.localeCompare(b.path));
     const packageCurrentVersionByPath = {};
-    const packageNextVersionByPath = {};
     const strategyPackagesByName = new Map();
+    // Strategy contexts are shared by reference with their group so that forcing
+    // a bump during the fixpoint below is immediately visible to the next
+    // `propagateDependentPatchImpacts` query.
+    const strategyContextByPath = new Map();
+    const strategyByPath = new Map();
     for (const packagePlan of packagePlans) {
         const packageConfig = loaded.config.packages?.[packagePlan.path] ?? {};
         const packageContext = resolvePackageStrategyContext(loaded.config, packagePlan.path, packageConfig);
+        const strategyContext = {
+            packagePath: packagePlan.path,
+            versionFile: packagePlan.resolvedVersionFile,
+            currentVersion: packagePlan.currentVersion,
+            nextVersion: packagePlan.nextVersion,
+        };
+        strategyContextByPath.set(packagePlan.path, strategyContext);
+        strategyByPath.set(packagePlan.path, packageContext.strategy);
         const existingGroup = strategyPackagesByName.get(packageContext.strategy.name);
         if (existingGroup) {
-            existingGroup.packages.push({
-                packagePath: packagePlan.path,
-                versionFile: packagePlan.resolvedVersionFile,
-                currentVersion: packagePlan.currentVersion,
-                nextVersion: packagePlan.nextVersion,
-            });
+            existingGroup.packages.push(strategyContext);
         }
         else {
             strategyPackagesByName.set(packageContext.strategy.name, {
                 strategy: packageContext.strategy,
-                packages: [
-                    {
-                        packagePath: packagePlan.path,
-                        versionFile: packagePlan.resolvedVersionFile,
-                        currentVersion: packagePlan.currentVersion,
-                        nextVersion: packagePlan.nextVersion,
-                    },
-                ],
+                packages: [strategyContext],
             });
         }
         packageCurrentVersionByPath[packagePlan.path] = packagePlan.currentVersion;
-        if (packagePlan.nextVersion) {
-            packageNextVersionByPath[packagePlan.path] = packagePlan.nextVersion;
+    }
+    const workingPlans = packagePlans.map((pkgPlan) => ({ ...pkgPlan }));
+    const workingPlanByPath = new Map(workingPlans.map((pkgPlan) => [pkgPlan.path, pkgPlan]));
+    const forcePatchBump = (target, reason) => {
+        const current = packageCurrentVersionByPath[target.path] ?? target.currentVersion;
+        target.releaseType = "patch";
+        target.nextVersion = bumpVersion(current, "patch", {
+            allowStableMajor: allowStableMajorForPath(target.path),
+        });
+        target.bumpReason = reason;
+        const strategyContext = strategyContextByPath.get(target.path);
+        if (strategyContext) {
+            strategyContext.nextVersion = target.nextVersion;
+        }
+    };
+    /**
+     * Packages that record a version requirement on `sourcePath`, found by
+     * asking the strategy who would need a requirement rewrite if `sourcePath`
+     * alone released. Works whether or not `sourcePath` is currently bumping,
+     * so it doubles as a reverse-edge lookup for a package that has not entered
+     * the plan yet.
+     */
+    const findDependents = (sourcePath) => {
+        const strategyContext = strategyContextByPath.get(sourcePath);
+        // The implicit root can name a version file that does not exist. Nothing
+        // can record a requirement on a package that has no manifest, and asking
+        // the strategy would make it read one.
+        if (!strategyContext ||
+            !fs.existsSync(path.join(cwd, strategyContext.versionFile))) {
+            return [];
+        }
+        const strategy = strategyByPath.get(sourcePath);
+        const strategyGroup = strategy
+            ? strategyPackagesByName.get(strategy.name)
+            : undefined;
+        if (!strategyGroup?.strategy.propagateDependentPatchImpacts) {
+            return [];
+        }
+        const hypotheticalVersion = strategyContext.nextVersion ??
+            bumpVersion(packageCurrentVersionByPath[sourcePath] ??
+                strategyContext.currentVersion, "patch", { allowStableMajor: allowStableMajorForPath(sourcePath) });
+        return strategyGroup.strategy.propagateDependentPatchImpacts(cwd, strategyGroup.packages.map((pkg) => ({
+            ...pkg,
+            nextVersion: pkg.packagePath === sourcePath ? hypotheticalVersion : null,
+        })));
+    };
+    const isPublishable = (packagePath) => {
+        const strategy = strategyByPath.get(packagePath);
+        const strategyContext = strategyContextByPath.get(packagePath);
+        if (!strategy?.isPublishable || !strategyContext) {
+            return true;
+        }
+        // Abstaining counts as publishable: the enforcement below should only be
+        // skipped on a positive signal that nothing reaches a registry.
+        return strategy.isPublishable(cwd, strategyContext) !== false;
+    };
+    // Forward dependency edges, inverted from the reverse-edge lookup above.
+    // Whether one package records a requirement on another is a property of the
+    // manifests, not of the versions in flight, so this is computed once.
+    const dependenciesByPath = new Map();
+    for (const pkgPlan of workingPlans) {
+        for (const dependentPath of findDependents(pkgPlan.path)) {
+            const existing = dependenciesByPath.get(dependentPath);
+            if (existing) {
+                existing.add(pkgPlan.path);
+                continue;
+            }
+            dependenciesByPath.set(dependentPath, new Set([pkgPlan.path]));
+        }
+    }
+    /**
+     * Every package reachable by following dependency edges down from a
+     * publishable package that is currently releasing. Staleness matters
+     * transitively: a release that pulls in a stale grandparent resolves against
+     * the stale published copy just as readily as a direct dependency does.
+     */
+    const collectReleasingDependencyClosure = () => {
+        const reachable = new Set();
+        const queue = workingPlans
+            .filter((pkgPlan) => pkgPlan.nextVersion && isPublishable(pkgPlan.path))
+            .map((pkgPlan) => pkgPlan.path);
+        while (queue.length > 0) {
+            const currentPath = queue.shift();
+            if (currentPath === undefined) {
+                continue;
+            }
+            for (const dependencyPath of dependenciesByPath.get(currentPath) ?? []) {
+                if (reachable.has(dependencyPath)) {
+                    continue;
+                }
+                reachable.add(dependencyPath);
+                queue.push(dependencyPath);
+            }
+        }
+        return reachable;
+    };
+    // Both rules below can enable each other: forcing a bump creates a dependent
+    // whose requirement must be rewritten, and rewriting a dependent can in turn
+    // expose a stale dependency a further level up. Iterating to a fixpoint
+    // avoids having to order them, and terminates because a package can only
+    // ever move from not-releasing to releasing.
+    for (let iteration = 0; iteration <= workingPlans.length; iteration += 1) {
+        let changed = false;
+        // Rule 1: a package whose recorded requirement on a releasing sibling
+        // would change must release too, or the rewritten requirement ships in the
+        // release commit without a version to publish it under.
+        for (const strategyGroup of strategyPackagesByName.values()) {
+            const impacted = strategyGroup.strategy.propagateDependentPatchImpacts?.(cwd, strategyGroup.packages) ?? [];
+            for (const impactedPath of impacted) {
+                const target = workingPlanByPath.get(impactedPath);
+                if (!target || target.nextVersion) {
+                    continue;
+                }
+                forcePatchBump(target, "dependency-propagation");
+                changed = true;
+            }
+        }
+        // Rule 2: a package that changed since its own last release but produced
+        // no bump would leave a releasing dependent pointing at a stale published
+        // copy. Commit type is deliberately not consulted — the exposure comes
+        // from the change existing, not from how it was labeled.
+        const reachableDependencies = collectReleasingDependencyClosure();
+        for (const candidate of workingPlans) {
+            if (candidate.nextVersion || candidate.commits.length === 0) {
+                continue;
+            }
+            if (!reachableDependencies.has(candidate.path)) {
+                continue;
+            }
+            if (!isPublishable(candidate.path)) {
+                continue;
+            }
+            forcePatchBump(candidate, "stale-dependency");
+            changed = true;
+        }
+        if (!changed) {
+            break;
+        }
+    }
+    const packageNextVersionByPath = {};
+    for (const pkgPlan of workingPlans) {
+        if (pkgPlan.nextVersion) {
+            packageNextVersionByPath[pkgPlan.path] = pkgPlan.nextVersion;
         }
     }
-    const impactedPaths = new Set();
     const dependencySourcePathsByPackage = new Map();
     const addDependencySourcePath = (targetPath, sourcePath) => {
         if (targetPath === sourcePath) {
@@ -164,48 +320,30 @@ export function createReleasePlan(cwd = process.cwd()) {
         }
         dependencySourcePathsByPackage.set(targetPath, new Set([sourcePath]));
     };
+    // Attribute each dependent's requirement rewrite to the specific sources
+    // driving it, using the settled version set so chained bumps are credited.
     for (const strategyGroup of strategyPackagesByName.values()) {
-        const impactedByAll = strategyGroup.strategy.propagateDependentPatchImpacts?.(cwd, strategyGroup.packages) ?? [];
-        for (const pkgPath of impactedByAll) {
-            impactedPaths.add(pkgPath);
-        }
-        const sourcePackages = strategyGroup.packages.filter((pkg) => Boolean(pkg.nextVersion));
-        for (const sourcePackage of sourcePackages) {
-            const scopedImpacts = strategyGroup.strategy.propagateDependentPatchImpacts?.(cwd, strategyGroup.packages.map((pkg) => ({
-                ...pkg,
-                nextVersion: pkg.packagePath === sourcePackage.packagePath
-                    ? sourcePackage.nextVersion
-                    : null,
-            }))) ?? [];
-            for (const impactedPath of scopedImpacts) {
+        for (const sourcePackage of strategyGroup.packages) {
+            if (!sourcePackage.nextVersion) {
+                continue;
+            }
+            for (const impactedPath of findDependents(sourcePackage.packagePath)) {
                 addDependencySourcePath(impactedPath, sourcePackage.packagePath);
             }
         }
     }
-    const propagatedPackages = packagePlans.map((pkgPlan) => {
+    const propagatedPackages = workingPlans.map((pkgPlan) => {
         const dependencySourcePaths = [
             ...(dependencySourcePathsByPackage.get(pkgPlan.path) ??
                 new Set()),
         ]
             .filter((sourcePath) => Boolean(packageNextVersionByPath[sourcePath]))
             .sort((a, b) => a.localeCompare(b));
-        if (pkgPlan.nextVersion || !impactedPaths.has(pkgPlan.path)) {
-            if (dependencySourcePaths.length === 0) {
-                return pkgPlan;
-            }
-            return {
-                ...pkgPlan,
-                dependencySourcePaths,
-            };
+        if (dependencySourcePaths.length === 0) {
+            return pkgPlan;
         }
-        const current = packageCurrentVersionByPath[pkgPlan.path] ?? pkgPlan.currentVersion;
         return {
             ...pkgPlan,
-            releaseType: "patch",
-            nextVersion: bumpVersion(current, "patch", {
-                allowStableMajor: allowStableMajorForPath(pkgPlan.path),
-            }),
-            bumpReason: "dependency-propagation",
             dependencySourcePaths,
         };
     });
@@ -217,6 +355,11 @@ export function createReleasePlan(cwd = process.cwd()) {
         }
     }
     const adjustedPackages = propagatedPackages.map((pkgPlan) => {
+        if (pkgPlan.bumpReason === "release-as") {
+            // An explicit override pins this package's version; do not let a
+            // followed source recompute it out from under the requested version.
+            return pkgPlan;
+        }
         const followsSources = followsByPath.get(pkgPlan.path) ?? [];
         const bumpingSources = followsSources
             .map((sourcePath) => propagatedPackages.find((pkg) => pkg.path === sourcePath))
@@ -237,6 +380,7 @@ export function createReleasePlan(cwd = process.cwd()) {
         ].sort((a, b) => a.localeCompare(b));
         const sourceDrove = combinedReleaseType !== ownReleaseType ||
             pkgPlan.bumpReason === "dependency-propagation" ||
+            pkgPlan.bumpReason === "stale-dependency" ||
             pkgPlan.bumpReason === undefined;
         const baseVersion = packageCurrentVersionByPath[pkgPlan.path] ?? pkgPlan.currentVersion;
         const nextVersion = combinedReleaseType
@@ -272,12 +416,19 @@ export function createReleasePlan(cwd = process.cwd()) {
             commits: rootPackagePlan.commits,
         };
     }
+    const rootOverridden = rootPackagePlan.bumpReason === "release-as";
     if (monorepoMode === "fixed") {
-        const fixedType = analyzeParsedCommits(adjustedPackages.flatMap((pkgPlan) => pkgPlan.parsedCommits));
+        const analyzedFixedType = analyzeParsedCommits(adjustedPackages.flatMap((pkgPlan) => pkgPlan.parsedCommits));
         const fixedBaseVersion = rootPackagePlan.currentVersion;
-        const fixedNextVersion = fixedType
-            ? bumpVersion(fixedBaseVersion, fixedType, { allowStableMajor })
-            : null;
+        // A `Release-As:` footer on the shared (root) version pins every package.
+        const fixedType = rootOverridden
+            ? rootPackagePlan.releaseType
+            : analyzedFixedType;
+        const fixedNextVersion = rootOverridden
+            ? rootPackagePlan.nextVersion
+            : analyzedFixedType
+                ? bumpVersion(fixedBaseVersion, analyzedFixedType, { allowStableMajor })
+                : null;
         const adjusted = adjustedPackages.map((pkgPlan) => ({
             ...pkgPlan,
             releaseType: fixedType,
@@ -300,11 +451,20 @@ export function createReleasePlan(cwd = process.cwd()) {
                 .map(({ implicitRoot: _implicitRoot, ...pkgPlan }) => pkgPlan),
         };
     }
-    const overallType = analyzeParsedCommits(adjustedPackages.flatMap((pkgPlan) => pkgPlan.parsedCommits));
+    const analyzedOverallType = analyzeParsedCommits(adjustedPackages.flatMap((pkgPlan) => pkgPlan.parsedCommits));
     const overallBaseVersion = rootPackagePlan.currentVersion;
-    const overallNextVersion = overallType
-        ? bumpVersion(overallBaseVersion, overallType, { allowStableMajor })
-        : null;
+    // A root-level `Release-As:` footer drives the aggregate version too, keeping
+    // the top-level plan consistent with the pinned root package.
+    const overallType = rootOverridden
+        ? rootPackagePlan.releaseType
+        : analyzedOverallType;
+    const overallNextVersion = rootOverridden
+        ? rootPackagePlan.nextVersion
+        : analyzedOverallType
+            ? bumpVersion(overallBaseVersion, analyzedOverallType, {
+                allowStableMajor,
+            })
+            : null;
     return {
         mode: "simple",
         releaseType: overallType,
@@ -320,9 +480,37 @@ export function createReleasePlan(cwd = process.cwd()) {
         packages: visiblePackages.map(({ implicitRoot: _implicitRoot, ...pkgPlan }) => pkgPlan),
     };
 }
-/** @deprecated Use createReleasePlan. */
-export function createSimplePlan(cwd = process.cwd()) {
-    return createReleasePlan(cwd);
+/**
+ * The root package's own release, as distinct from the plan-level aggregate.
+ *
+ * `plan.releaseType`/`plan.nextVersion`/`plan.commits` describe the repository
+ * as a whole: the aggregate release type folds in every package's commits and
+ * is then applied to root's version number. That answers "is anything
+ * releasing, and how large is the biggest change anywhere" — not "what is root
+ * releasing". A sibling's `feat` therefore lifts the aggregate to a minor even
+ * when root's own `exclude-paths` drop that commit, so anything that names or
+ * describes root's release must go through here instead. Using the aggregate
+ * would report a version no version file carries and list commits root
+ * deliberately excluded.
+ *
+ * Falls back to the aggregate when the plan has no explicit root package: the
+ * top-level changelog is then a repository-wide summary with no package of its
+ * own to describe.
+ */
+export function resolveRootReleaseView(plan) {
+    const rootPackage = plan.packages?.find((pkg) => pkg.path === ".");
+    if (!rootPackage) {
+        return {
+            currentVersion: plan.currentVersion,
+            nextVersion: plan.nextVersion,
+            commits: plan.commits,
+        };
+    }
+    return {
+        currentVersion: rootPackage.currentVersion,
+        nextVersion: rootPackage.nextVersion,
+        commits: rootPackage.commits,
+    };
 }
 export function resolvePackageDependencies(plan, packagePath) {
     const target = plan.packages?.find((pkg) => pkg.path === packagePath);

package/dist/release/pr.d.ts

@@ -1,15 +1,7 @@
 import type { ParsedCommit } from "../git/commits.js";
 import type { VersionaryChangelogFormat, VersionaryConfig } from "../types/config.js";
 import type { VersionaryPluginContext } from "../types/plugins.js";
-import { type ReleasePlan, type SimplePlan } from "./plan.js";
-export declare function getNextReleaseFile(config: VersionaryConfig): string;
-export declare function readNextReleaseHighlights(cwd: string, config: VersionaryConfig): {
-    content: string;
-    filePath: string;
-} | null;
-export declare function consumeNextReleaseFile(cwd: string, filePath: string): {
-    tracked: boolean;
-};
+import { type ReleasePlan } from "./plan.js";
 /**
  * Read the manual-notes ("Unreleased") prose from the top of a changelog file.
  * Returns an empty string when the file is absent or has no notes block.
@@ -17,15 +9,13 @@ export declare function consumeNextReleaseFile(cwd: string, filePath: string): {
 export declare function readChangelogHighlights(cwd: string, changelogFile: string, format: VersionaryChangelogFormat): string;
 export interface ResolvedReleaseHighlights {
     highlights: string;
-    source: "changelog" | "file" | "none";
-    filePath?: string;
+    source: "changelog" | "none";
 }
 /**
- * Resolve release highlights, preferring an editable "Unreleased" section at the
- * top of the changelog. Falls back to the deprecated `NEXT_RELEASE.md` file
- * (emitting a warning) so existing setups keep working.
+ * Resolve release highlights from the editable "Unreleased" section at the top
+ * of the changelog.
  */
-export declare function resolveReleaseHighlights(cwd: string, config: VersionaryConfig, changelogFile: string, format: VersionaryChangelogFormat, logger?: VersionaryPluginContext["logger"]): ResolvedReleaseHighlights;
+export declare function resolveReleaseHighlights(cwd: string, changelogFile: string, format: VersionaryChangelogFormat): ResolvedReleaseHighlights;
 export declare function splitSafeDirtyFiles(files: string[]): {
     ignored: string[];
     blocking: string[];
@@ -42,8 +32,8 @@ export declare function prepareReleasePr(cwd?: string, options?: {
     updated: boolean;
     highlights: string;
 };
-export declare function renderSimpleReviewRequestBody(version: string, previousVersion: string, commits: ParsedCommit[], plan?: SimplePlan | null, cwd?: string, highlights?: string, loadedConfig?: VersionaryConfig): string;
-export declare function openOrUpdateReviewRequest(cwd: string, branch: string, title: string, version: string, previousVersion: string, commits: ParsedCommit[], plan?: SimplePlan | null, options?: {
+export declare function renderSimpleReviewRequestBody(version: string, previousVersion: string, commits: ParsedCommit[], plan?: ReleasePlan | null, cwd?: string, highlights?: string, loadedConfig?: VersionaryConfig): string;
+export declare function openOrUpdateReviewRequest(cwd: string, branch: string, title: string, version: string, previousVersion: string, commits: ParsedCommit[], plan?: ReleasePlan | null, options?: {
     logger?: VersionaryPluginContext["logger"];
     highlights?: string;
 }): Promise<string>;
@@ -54,14 +44,5 @@ export declare function closeStaleReviewRequestIfExists(cwd?: string, options?:
     url?: string;
     number?: number;
 }>;
-/** @deprecated Use prepareReleasePr. */
-export declare function prepareSimpleReleasePr(cwd?: string, options?: {
-    logger?: VersionaryPluginContext["logger"];
-}): ReturnType<typeof prepareReleasePr>;
-/** @deprecated Use openOrUpdateReviewRequest. */
-export declare function openOrUpdateSimpleReviewRequest(cwd: string, branch: string, title: string, version: string, previousVersion: string, commits: ParsedCommit[], plan?: SimplePlan | null, options?: {
-    logger?: VersionaryPluginContext["logger"];
-    highlights?: string;
-}): Promise<string>;
 export declare function pushReleaseBranch(cwd: string, branch: string): void;
 export declare function isReleaseCommitMessage(commitMessage: string): boolean;

package/dist/release/pr.js

@@ -17,38 +17,6 @@ const SAFE_DIRTY_FILES = new Set([
     "npm-shrinkwrap.json",
 ]);
 const VERSIONARY_RELEASE_TRAILER = "Versionary-Release: true";
-export function getNextReleaseFile(config) {
-    return config["next-release-file"] ?? "NEXT_RELEASE.md";
-}
-export function readNextReleaseHighlights(cwd, config) {
-    const filePath = getNextReleaseFile(config);
-    const fullPath = path.join(cwd, filePath);
-    if (!fs.existsSync(fullPath)) {
-        return null;
-    }
-    const content = fs.readFileSync(fullPath, "utf8").trim();
-    return { content, filePath };
-}
-function isTrackedFile(cwd, filePath) {
-    try {
-        execFileSync("git", ["ls-files", "--error-unmatch", "--", filePath], {
-            cwd,
-            stdio: ["ignore", "pipe", "ignore"],
-        });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-export function consumeNextReleaseFile(cwd, filePath) {
-    const tracked = isTrackedFile(cwd, filePath);
-    const fullPath = path.join(cwd, filePath);
-    if (fs.existsSync(fullPath)) {
-        fs.rmSync(fullPath);
-    }
-    return { tracked };
-}
 /**
  * Read the manual-notes ("Unreleased") prose from the top of a changelog file.
  * Returns an empty string when the file is absent or has no notes block.
@@ -62,24 +30,14 @@ export function readChangelogHighlights(cwd, changelogFile, format) {
     return extractUnreleasedNotes(existing, format).highlights;
 }
 /**
- * Resolve release highlights, preferring an editable "Unreleased" section at the
- * top of the changelog. Falls back to the deprecated `NEXT_RELEASE.md` file
- * (emitting a warning) so existing setups keep working.
+ * Resolve release highlights from the editable "Unreleased" section at the top
+ * of the changelog.
  */
-export function resolveReleaseHighlights(cwd, config, changelogFile, format, logger) {
+export function resolveReleaseHighlights(cwd, changelogFile, format) {
     const fromChangelog = readChangelogHighlights(cwd, changelogFile, format);
     if (fromChangelog.length > 0) {
         return { highlights: fromChangelog, source: "changelog" };
     }
-    const fromFile = readNextReleaseHighlights(cwd, config);
-    if (fromFile) {
-        logger?.warn(`${fromFile.filePath} is deprecated; add release notes under an "Unreleased" heading at the top of ${changelogFile} instead.`);
-        return {
-            highlights: fromFile.content,
-            source: "file",
-            filePath: fromFile.filePath,
-        };
-    }
     return { highlights: "", source: "none" };
 }
 function listTrackedDirtyFiles(cwd) {
@@ -297,19 +255,16 @@ export function prepareReleasePr(cwd = process.cwd(), options = {}) {
     }
     const updatedArtifactFiles = applyConfiguredArtifactRules(cwd, loaded.config, plan);
     const packageReleaseMetadata = buildPackageReleaseMetadata(cwd, plan, loaded.config);
-    const highlightsResult = resolveReleaseHighlights(cwd, loaded.config, plan.changelogFile, plan.changelogFormat, options.logger);
+    const highlightsResult = resolveReleaseHighlights(cwd, plan.changelogFile, plan.changelogFormat);
     const highlights = highlightsResult.highlights;
     const section = renderReleasePlanChangelog(plan, { highlights, cwd });
-    prependChangelog(cwd, plan.changelogFile, section, plan.changelogFormat);
-    const updatedChangelogFiles = [plan.changelogFile];
-    let consumedHighlightsPath = null;
-    // The changelog "Unreleased" block is stripped in-place by prependChangelog;
-    // only the legacy side file needs explicit consumption and staging.
-    if (highlightsResult.source === "file" && highlightsResult.filePath) {
-        const { tracked } = consumeNextReleaseFile(cwd, highlightsResult.filePath);
-        if (tracked) {
-            consumedHighlightsPath = highlightsResult.filePath;
-        }
+    const updatedChangelogFiles = [];
+    // An empty section means root itself is not releasing, only siblings are.
+    // Writing then would leave a bare heading behind and, worse, strip the
+    // manual-notes block that nothing has folded in yet.
+    if (section.length > 0) {
+        prependChangelog(cwd, plan.changelogFile, section, plan.changelogFormat);
+        updatedChangelogFiles.push(plan.changelogFile);
     }
     for (const packagePlan of plan.packages ?? []) {
         if (!packagePlan.nextVersion || packagePlan.path === ".") {
@@ -357,7 +312,6 @@ export function prepareReleasePr(cwd = process.cwd(), options = {}) {
             ...updatedVersionFiles,
             ...updatedArtifactFiles,
             ...updatedChangelogFiles,
-            ...(consumedHighlightsPath ? [consumedHighlightsPath] : []),
         ]),
     ];
     execFileSync("git", ["add", ...filesToAdd], {
@@ -497,14 +451,6 @@ export async function closeStaleReviewRequestIfExists(cwd = process.cwd(), optio
     }
     return result;
 }
-/** @deprecated Use prepareReleasePr. */
-export function prepareSimpleReleasePr(cwd = process.cwd(), options = {}) {
-    return prepareReleasePr(cwd, options);
-}
-/** @deprecated Use openOrUpdateReviewRequest. */
-export async function openOrUpdateSimpleReviewRequest(cwd, branch, title, version, previousVersion, commits, plan = null, options = {}) {
-    return openOrUpdateReviewRequest(cwd, branch, title, version, previousVersion, commits, plan, options);
-}
 export function pushReleaseBranch(cwd, branch) {
     execFileSync("git", ["push", "--force-with-lease", "origin", branch], {
         cwd,

package/dist/release/release-as.d.ts

@@ -0,0 +1,29 @@
+import type { ParsedCommit } from "../git/commits.js";
+import { type ReleaseType } from "./semver.js";
+/**
+ * Footer token (case-insensitive) that requests an explicit next version, e.g.
+ *
+ *   chore: graduate to stable release
+ *
+ *   Release-As: 1.0.0
+ *
+ * The override forces a release with the requested version even when the
+ * conventional-commit analysis alone would produce no bump.
+ */
+export declare const RELEASE_AS_FOOTER_TOKEN = "release-as";
+export interface ReleaseAsOverride {
+    /** The requested target version (leading `v` stripped, validated SemVer). */
+    version: string;
+    /** Hash of the commit carrying the winning footer. */
+    sourceHash: string;
+}
+/**
+ * Scan a release window for a `Release-As:` footer override.
+ *
+ * Returns the explicit target version, or `null` when no footer is present.
+ * Throws on an invalid version, a downgrade or no-op relative to
+ * `currentVersion`, or conflicting override versions within the window.
+ */
+export declare function resolveReleaseAsOverride(commits: ParsedCommit[], currentVersion: string): ReleaseAsOverride | null;
+/** Derive the semantic release level implied by moving `from` -> `to`. */
+export declare function releaseTypeBetween(from: string, to: string): ReleaseType;