versionary 0.12.0 → 0.14.0

package/README.md

@@ -86,8 +86,10 @@ Current ecosystem policy defaults:
 
 - changelog source for publish:
   - root target uses root `changelog-file`
-  - package target uses `packages.<path>.changelog-file` when configured, else
-    root `changelog-file`
+  - package target uses package changelog defaults:
+    - `packages.<path>.changelog-file` when configured
+    - otherwise `NEWS.md` for R targets or `CHANGELOG.md` for other targets at
+      `<package-path>/<default-file>`
 - lockfiles:
   - Node strategy updates root `package-lock.json`/`npm-shrinkwrap.json` when
     present
@@ -142,6 +144,10 @@ For a quick trial, use:
   request)
 - `release-draft` (default `false`) publishes GitHub releases as drafts when
   enabled
+- `release-reference-comments` controls release comments on linked issues/PRs:
+  - `off` (default): do not post comments
+  - `best-effort`: post comments and continue on API/permission failures
+  - `strict`: fail release if comment posting fails
 - optional monorepo planning with `monorepo-mode` and `packages`:
   - `independent` computes package bumps per path
   - `fixed` computes one shared bump across configured package paths

package/dist/cli/index.js

@@ -52,7 +52,7 @@ async function main() {
         }).trim();
         if ((0, pr_js_1.isReleaseCommitMessage)(commitMessage)) {
             if (flags["dry-run"] && !flags.json) {
-                const release = await (0, release_js_1.runSimpleReleaseDetailed)(process.cwd(), {
+                const release = await (0, release_js_1.runReleaseDetailed)(process.cwd(), {
                     logger,
                     "dry-run": true,
                 });
@@ -62,7 +62,7 @@ async function main() {
                 }
             }
             if (flags.json) {
-                const release = await (0, release_js_1.runSimpleReleaseDetailed)(process.cwd(), {
+                const release = await (0, release_js_1.runReleaseDetailed)(process.cwd(), {
                     logger,
                     "dry-run": flags["dry-run"],
                 });
@@ -93,11 +93,11 @@ async function main() {
                 });
                 return 0;
             }
-            const message = await (0, release_js_1.runSimpleRelease)(process.cwd());
+            const message = await (0, release_js_1.runRelease)(process.cwd());
             console.log(message);
             return 0;
         }
-        const plan = (0, plan_js_1.createSimplePlan)();
+        const plan = (0, plan_js_1.createReleasePlan)();
         if (!plan.nextVersion) {
             const message = "No releasable commits found. Nothing to do.";
             if (flags.json) {
@@ -140,9 +140,9 @@ async function main() {
             console.log(dryRunMessage);
             return 0;
         }
-        const pr = (0, pr_js_1.prepareSimpleReleasePr)(process.cwd(), { logger });
+        const pr = (0, pr_js_1.prepareReleasePr)(process.cwd(), { logger });
         (0, pr_js_1.pushReleaseBranch)(process.cwd(), pr.branch);
-        const reviewResult = await (0, pr_js_1.openOrUpdateSimpleReviewRequest)(process.cwd(), pr.branch, pr.title, pr.version, pr.previousVersion, pr.commits, pr.plan, { logger });
+        const reviewResult = await (0, pr_js_1.openOrUpdateReviewRequest)(process.cwd(), pr.branch, pr.title, pr.version, pr.previousVersion, pr.commits, pr.plan, { logger });
         const message = `Prepared release PR branch ${pr.branch}`;
         if (flags.json) {
             emitJson({
@@ -165,18 +165,18 @@ async function main() {
         return printVerifyResult();
     }
     if (command === "plan") {
-        const plan = (0, plan_js_1.createSimplePlan)();
+        const plan = (0, plan_js_1.createReleasePlan)();
         console.log(JSON.stringify(plan, null, 2));
         return 0;
     }
     if (command === "changelog") {
         const write = args.includes("--write");
-        const plan = (0, plan_js_1.createSimplePlan)();
+        const plan = (0, plan_js_1.createReleasePlan)();
         if (!plan.nextVersion) {
             console.log("No releasable commits found.");
             return 0;
         }
-        const section = (0, changelog_js_1.renderSimpleChangelog)(plan);
+        const section = (0, changelog_js_1.renderReleasePlanChangelog)(plan);
         if (!write) {
             console.log(section);
             return 0;
@@ -187,7 +187,7 @@ async function main() {
     }
     if (command === "pr") {
         if (flags["dry-run"]) {
-            const plan = (0, plan_js_1.createSimplePlan)();
+            const plan = (0, plan_js_1.createReleasePlan)();
             if (!plan.nextVersion) {
                 console.log("No releasable commits found. Nothing to do.");
                 return 0;
@@ -195,9 +195,9 @@ async function main() {
             console.log(`Dry run: would prepare release PR branch ${plan.releaseBranchPrefix} for ${plan.nextVersion}`);
             return 0;
         }
-        const pr = (0, pr_js_1.prepareSimpleReleasePr)(process.cwd(), { logger: console });
+        const pr = (0, pr_js_1.prepareReleasePr)(process.cwd(), { logger: console });
         (0, pr_js_1.pushReleaseBranch)(process.cwd(), pr.branch);
-        const reviewResult = await (0, pr_js_1.openOrUpdateSimpleReviewRequest)(process.cwd(), pr.branch, pr.title, pr.version, pr.previousVersion, pr.commits, pr.plan);
+        const reviewResult = await (0, pr_js_1.openOrUpdateReviewRequest)(process.cwd(), pr.branch, pr.title, pr.version, pr.previousVersion, pr.commits, pr.plan);
         console.log(`Prepared release PR branch ${pr.branch}`);
         console.log(`Title: ${pr.title}`);
         console.log(reviewResult);
@@ -205,7 +205,7 @@ async function main() {
     }
     if (command === "release") {
         if (flags["dry-run"]) {
-            const result = await (0, release_js_1.runSimpleReleaseDetailed)(process.cwd(), {
+            const result = await (0, release_js_1.runReleaseDetailed)(process.cwd(), {
                 logger,
                 "dry-run": true,
             });
@@ -220,7 +220,7 @@ async function main() {
             }
             return 0;
         }
-        const message = await (0, release_js_1.runSimpleRelease)(process.cwd());
+        const message = await (0, release_js_1.runRelease)(process.cwd());
         console.log(message);
         return 0;
     }
@@ -228,7 +228,7 @@ async function main() {
     console.log("Commands:");
     console.log("  run [--json] [--dry-run]  Auto-dispatch release PR/update or release publish by context");
     console.log("  verify  Validate config and basic repository shape");
-    console.log("  plan    Print release plan (simple mode)");
+    console.log("  plan    Print release plan");
     console.log("  changelog [--write]  Print or write changelog section");
     console.log("  pr [--dry-run]      Prepare release PR commit and branch");
     console.log("  release [--dry-run] Publish release metadata for release commit context");

package/dist/config/schema.d.ts

@@ -14,6 +14,11 @@ export declare const configSchema: z.ZodObject<{
         "r-news": "r-news";
     }>>;
     "release-draft": z.ZodOptional<z.ZodBoolean>;
+    "release-reference-comments": z.ZodOptional<z.ZodEnum<{
+        off: "off";
+        "best-effort": "best-effort";
+        strict: "strict";
+    }>>;
     "release-branch": z.ZodOptional<z.ZodString>;
     "baseline-file": z.ZodOptional<z.ZodString>;
     "bootstrap-sha": z.ZodOptional<z.ZodString>;

package/dist/config/schema.js

@@ -68,6 +68,9 @@ exports.configSchema = zod_1.z
     "changelog-file": zod_1.z.string().optional(),
     "changelog-format": zod_1.z.enum(["markdown-changelog", "r-news"]).optional(),
     "release-draft": zod_1.z.boolean().optional(),
+    "release-reference-comments": zod_1.z
+        .enum(["off", "best-effort", "strict"])
+        .optional(),
     "release-branch": zod_1.z.string().optional(),
     "baseline-file": zod_1.z.string().optional(),
     "bootstrap-sha": zod_1.z.string().optional(),

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { verifyProject } from "./release/verify-project.js";
 export { findPluginsByCapability, pluginHasCapability, } from "./scm/capabilities.js";
 export { getScmClient } from "./scm/client.js";
 export { createGitHubPlugin } from "./scm/github-plugin.js";
-export type { ScmClient, ScmClientContext, ScmProvider, ScmReleaseMetadataInput, ScmReleaseMetadataResult, ScmReviewRequestInput, ScmReviewRequestResult, } from "./scm/types.js";
+export type { ScmClient, ScmClientContext, ScmProvider, ScmReleaseMetadataInput, ScmReleaseMetadataResult, ScmReleaseReferenceCommentsInput, ScmReleaseReferenceCommentsResult, ScmReviewRequestInput, ScmReviewRequestResult, } from "./scm/types.js";
 export { resolveVersionStrategy } from "./strategy/resolve.js";
 export type { VersionaryArtifactRule, VersionaryConfig, VersionaryPackage, } from "./types/config.js";
-export type { VersionaryPluginCapability, VersionaryPluginContext, VersionaryPluginRuntime, VersionaryScmReleaseMetadataInput, VersionaryScmReleaseMetadataResult, VersionaryScmReviewRequestInput, VersionaryScmReviewRequestResult, } from "./types/plugins.js";
+export type { VersionaryPluginCapability, VersionaryPluginContext, VersionaryPluginRuntime, VersionaryScmReleaseMetadataInput, VersionaryScmReleaseMetadataResult, VersionaryScmReleaseReferenceCommentsInput, VersionaryScmReleaseReferenceCommentsResult, VersionaryScmReviewRequestInput, VersionaryScmReviewRequestResult, } from "./types/plugins.js";

package/dist/release/changelog.d.ts

@@ -1,6 +1,6 @@
 import { type ParsedCommit } from "../git/commits.js";
 import type { VersionaryChangelogFormat } from "../types/config.js";
-import type { SimplePlan } from "./plan.js";
+import type { ReleasePlan, SimplePlan } from "./plan.js";
 export declare function renderSimpleReleaseNotes(input: {
     currentVersion: string;
     nextVersion: string;
@@ -13,6 +13,8 @@ export declare function renderSimpleReleaseNotes(input: {
 }, options?: {
     includeFooter?: boolean;
 }): string;
+export declare function renderReleasePlanChangelog(plan: ReleasePlan): string;
+/** @deprecated Use renderReleasePlanChangelog. */
 export declare function renderSimpleChangelog(plan: SimplePlan): string;
 export declare function renderPackageChangelogSection(input: {
     currentVersion: string;

package/dist/release/changelog.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderSimpleReleaseNotes = renderSimpleReleaseNotes;
+exports.renderReleasePlanChangelog = renderReleasePlanChangelog;
 exports.renderSimpleChangelog = renderSimpleChangelog;
 exports.renderPackageChangelogSection = renderPackageChangelogSection;
 exports.prependChangelog = prependChangelog;
@@ -112,7 +113,7 @@ function renderSimpleReleaseNotes(input, options = {}) {
     }
     return lines.join("\n");
 }
-function renderSimpleChangelog(plan) {
+function renderReleasePlanChangelog(plan) {
     if (!plan.nextVersion) {
         return "";
     }
@@ -129,22 +130,29 @@ function renderSimpleChangelog(plan) {
             version: pkg.nextVersion,
         }))
         : [];
+    const dedupedCommits = [
+        ...new Map(plan.commits.map((commit) => [commit.hash, commit])).values(),
+    ];
     if (plan.changelogFormat === "r-news") {
         return renderRNewsReleaseNotes({
             packageName: plan.packageName,
             nextVersion: plan.nextVersion,
-            commits: plan.commits,
+            commits: dedupedCommits,
             cwd: process.cwd(),
         });
     }
     return renderSimpleReleaseNotes({
         currentVersion: plan.currentVersion,
         nextVersion: plan.nextVersion,
-        commits: plan.commits,
+        commits: dedupedCommits,
         cwd: process.cwd(),
         dependencies,
     });
 }
+/** @deprecated Use renderReleasePlanChangelog. */
+function renderSimpleChangelog(plan) {
+    return renderReleasePlanChangelog(plan);
+}
 function renderPackageChangelogSection(input) {
     const repoUrl = (0, repo_url_js_1.resolveRepositoryWebBaseUrl)(input.cwd ?? process.cwd());
     const header = repoUrl
@@ -172,15 +180,16 @@ function prependChangelog(cwd, changelogFile, section, format = "markdown-change
         ? node_fs_1.default.readFileSync(changelogPath, "utf8")
         : "";
     if (format === "r-news") {
-        const separator = existing.length > 0 ? "\n\n" : "";
-        const next = `${section}${separator}${existing}`.trimEnd() + "\n";
+        const bodyWithoutDevHeader = existing.replace(/^#\s+.+\s+\(development version\)\s*(?:\r?\n)*/u, "");
+        const separator = bodyWithoutDevHeader.length > 0 ? "\n\n" : "";
+        const next = `${`${section}${separator}${bodyWithoutDevHeader}`.trimEnd()}\n`;
         node_fs_1.default.writeFileSync(changelogPath, next, "utf8");
         return;
     }
     const heading = "# Changelog\n\n";
     const bodyWithoutHeading = existing.replace(/^# Changelog\s*/u, "");
     const separator = existing.length > 0 ? "\n" : "";
-    const next = `${heading}${section}${separator}${bodyWithoutHeading}`.trimEnd() + "\n";
+    const next = `${`${heading}${section}${separator}${bodyWithoutHeading}`.trimEnd()}\n`;
     node_fs_1.default.writeFileSync(changelogPath, next, "utf8");
 }
 function renderRNewsReleaseNotes(input) {

package/dist/release/plan.d.ts

@@ -1,7 +1,7 @@
 import { type ParsedCommit } from "../git/commits.js";
 import type { VersionaryChangelogFormat, VersionaryConfig } from "../types/config.js";
 import { type ReleaseType } from "./semver.js";
-export interface SimplePlan {
+export interface ReleasePlan {
     mode: "simple";
     releaseType: ReleaseType;
     currentVersion: string;
@@ -22,6 +22,8 @@ export interface SimplePlan {
         commits: ParsedCommit[];
     }>;
 }
+/** @deprecated Use ReleasePlan. */
+export type SimplePlan = ReleasePlan;
 export declare function getChangelogDefaults(config: {
     "release-type"?: VersionaryConfig["release-type"];
     "changelog-file"?: VersionaryConfig["changelog-file"];
@@ -30,4 +32,6 @@ export declare function getChangelogDefaults(config: {
     changelogFile: string;
     changelogFormat: VersionaryChangelogFormat;
 };
-export declare function createSimplePlan(cwd?: string): SimplePlan;
+export declare function createReleasePlan(cwd?: string): ReleasePlan;
+/** @deprecated Use createReleasePlan. */
+export declare function createSimplePlan(cwd?: string): ReleasePlan;

package/dist/release/plan.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getChangelogDefaults = getChangelogDefaults;
+exports.createReleasePlan = createReleasePlan;
 exports.createSimplePlan = createSimplePlan;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -23,7 +24,7 @@ function getChangelogDefaults(config) {
         (changelogFormat === "r-news" ? "NEWS.md" : "CHANGELOG.md");
     return { changelogFile, changelogFormat };
 }
-function createSimplePlan(cwd = process.cwd()) {
+function createReleasePlan(cwd = process.cwd()) {
     const loaded = (0, load_config_js_1.loadConfig)(cwd);
     const strategy = (0, resolve_js_1.resolveVersionStrategy)(loaded.config);
     const versionFile = strategy.getVersionFile(loaded.config);
@@ -189,3 +190,7 @@ function createSimplePlan(cwd = process.cwd()) {
         packages: adjustedPackages,
     };
 }
+/** @deprecated Use createReleasePlan. */
+function createSimplePlan(cwd = process.cwd()) {
+    return createReleasePlan(cwd);
+}

package/dist/release/pr.d.ts

@@ -1,11 +1,11 @@
 import type { ParsedCommit } from "../git/commits.js";
 import type { VersionaryPluginContext } from "../types/plugins.js";
-import { type SimplePlan } from "./plan.js";
+import { type ReleasePlan, type SimplePlan } from "./plan.js";
 export declare function splitSafeDirtyFiles(files: string[]): {
     ignored: string[];
     blocking: string[];
 };
-export declare function prepareSimpleReleasePr(cwd?: string, options?: {
+export declare function prepareReleasePr(cwd?: string, options?: {
     logger?: VersionaryPluginContext["logger"];
 }): {
     branch: string;
@@ -13,9 +13,17 @@ export declare function prepareSimpleReleasePr(cwd?: string, options?: {
     version: string;
     previousVersion: string;
     commits: ParsedCommit[];
-    plan: SimplePlan;
+    plan: ReleasePlan;
 };
 export declare function renderSimpleReviewRequestBody(version: string, previousVersion: string, commits: ParsedCommit[], plan?: SimplePlan | null, cwd?: string): string;
+export declare function openOrUpdateReviewRequest(cwd: string, branch: string, title: string, version: string, previousVersion: string, commits: ParsedCommit[], plan?: SimplePlan | null, options?: {
+    logger?: VersionaryPluginContext["logger"];
+}): Promise<string>;
+/** @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"];
 }): Promise<string>;

package/dist/release/pr.js

@@ -4,8 +4,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.splitSafeDirtyFiles = splitSafeDirtyFiles;
-exports.prepareSimpleReleasePr = prepareSimpleReleasePr;
+exports.prepareReleasePr = prepareReleasePr;
 exports.renderSimpleReviewRequestBody = renderSimpleReviewRequestBody;
+exports.openOrUpdateReviewRequest = openOrUpdateReviewRequest;
+exports.prepareSimpleReleasePr = prepareSimpleReleasePr;
 exports.openOrUpdateSimpleReviewRequest = openOrUpdateSimpleReviewRequest;
 exports.pushReleaseBranch = pushReleaseBranch;
 exports.isReleaseCommitMessage = isReleaseCommitMessage;
@@ -202,8 +204,8 @@ function formatReleaseCommitTitle(releaseTargets) {
     }
     return `chore(release): ${tags[0]} (+${tags.length - 1} more)`;
 }
-function prepareSimpleReleasePr(cwd = process.cwd(), options = {}) {
-    const plan = (0, plan_js_1.createSimplePlan)(cwd);
+function prepareReleasePr(cwd = process.cwd(), options = {}) {
+    const plan = (0, plan_js_1.createReleasePlan)(cwd);
     const loaded = (0, load_config_js_1.loadConfig)(cwd);
     const strategy = (0, resolve_js_1.resolveVersionStrategy)(loaded.config);
     if (!plan.nextVersion) {
@@ -253,7 +255,7 @@ function prepareSimpleReleasePr(cwd = process.cwd(), options = {}) {
     const updatedArtifactFiles = (0, artifact_rules_js_1.applyConfiguredArtifactRules)(cwd, loaded.config, plan);
     const updatedRustLockFiles = ensureCargoLockUpToDate(cwd);
     const packageReleaseMetadata = buildPackageReleaseMetadata(cwd, plan, loaded.config);
-    const section = (0, changelog_js_1.renderSimpleChangelog)(plan);
+    const section = (0, changelog_js_1.renderReleasePlanChangelog)(plan);
     (0, changelog_js_1.prependChangelog)(cwd, plan.changelogFile, section, plan.changelogFormat);
     const updatedChangelogFiles = [plan.changelogFile];
     for (const packagePlan of plan.packages ?? []) {
@@ -261,10 +263,11 @@ function prepareSimpleReleasePr(cwd = process.cwd(), options = {}) {
             continue;
         }
         const packageConfig = loaded.config.packages?.[packagePlan.path] ?? {};
-        const packageChangelogFile = packageConfig["changelog-file"];
-        if (!packageChangelogFile) {
-            continue;
-        }
+        const { changelogFile: packageChangelogFile } = (0, plan_js_1.getChangelogDefaults)({
+            "release-type": packageConfig["release-type"] ?? loaded.config["release-type"],
+            "changelog-file": packageConfig["changelog-file"] ?? loaded.config["changelog-file"],
+            "changelog-format": packageConfig["changelog-format"] ?? loaded.config["changelog-format"],
+        });
         const packageMetadata = packageReleaseMetadata[packagePlan.path];
         if (!packageMetadata) {
             continue;
@@ -342,9 +345,28 @@ function renderSimpleReviewRequestBody(version, previousVersion, commits, plan =
             .sort((a, b) => a.name.localeCompare(b.name));
         return directSources;
     };
+    const relabelSectionHeader = (notes, packageLabel, nextVersion) => {
+        const linkedHeader = notes.match(/^##\s+\[([^\]]+)\]\(([^)]+)\)\s+\(([^)]+)\)/u);
+        if (linkedHeader) {
+            const [, , compareUrl, date] = linkedHeader;
+            return notes.replace(/^##\s+\[[^\]]+\]\([^)]+\)\s+\([^)]+\)/u, `## [${packageLabel}: ${nextVersion}](${compareUrl}) (${date})`);
+        }
+        const plainHeader = notes.match(/^##\s+([^\s]+)\s+\(([^)]+)\)/u);
+        if (plainHeader) {
+            const [, , date] = plainHeader;
+            return notes.replace(/^##\s+[^\s]+\s+\([^)]+\)/u, `## ${packageLabel}: ${nextVersion} (${date})`);
+        }
+        return notes;
+    };
     if (plan?.packages && plan.packages.length > 1) {
-        const sections = plan.packages
-            .filter((pkg) => pkg.nextVersion)
+        const sections = [];
+        const rootPackage = plan.packages.find((pkg) => pkg.path === "." && pkg.nextVersion);
+        if (rootPackage?.nextVersion) {
+            const rootNotes = (0, changelog_js_1.renderReleasePlanChangelog)(plan);
+            sections.push(relabelSectionHeader(rootNotes, formatPackageLabel("."), rootPackage.nextVersion));
+        }
+        const packageSections = plan.packages
+            .filter((pkg) => pkg.path !== "." && pkg.nextVersion)
             .map((pkg) => {
             const packageLabel = formatPackageLabel(pkg.path);
             const propagatedDependencies = findPropagatedDependencies(pkg.path, plan.packages ?? []);
@@ -355,20 +377,14 @@ function renderSimpleReviewRequestBody(version, previousVersion, commits, plan =
                 cwd,
                 dependencies: propagatedDependencies,
             }, { includeFooter: false });
-            const linkedHeader = notes.match(/^##\s+\[([^\]]+)\]\(([^)]+)\)\s+\(([^)]+)\)/u);
-            if (linkedHeader) {
-                const [, , compareUrl, date] = linkedHeader;
-                return notes.replace(/^##\s+\[[^\]]+\]\([^)]+\)\s+\([^)]+\)/u, `## [${packageLabel}: ${pkg.nextVersion ?? ""}](${compareUrl}) (${date})`);
-            }
-            const plainHeader = notes.match(/^##\s+([^\s]+)\s+\(([^)]+)\)/u);
-            if (plainHeader) {
-                const [, , date] = plainHeader;
-                return notes.replace(/^##\s+[^\s]+\s+\([^)]+\)/u, `## ${packageLabel}: ${pkg.nextVersion ?? ""} (${date})`);
-            }
-            return notes;
-        })
-            .join("\n\n");
-        return `${sections}\n\nThis PR was generated by Versionary.`;
+            return relabelSectionHeader(notes, packageLabel, pkg.nextVersion ?? "");
+        });
+        sections.push(...packageSections);
+        const bodySections = sections.join("\n\n");
+        if (bodySections.length === 0) {
+            return "This PR was generated by Versionary.";
+        }
+        return `${bodySections}\n\nThis PR was generated by Versionary.`;
     }
     return (0, changelog_js_1.renderSimpleReleaseNotes)({
         currentVersion: previousVersion,
@@ -377,7 +393,7 @@ function renderSimpleReviewRequestBody(version, previousVersion, commits, plan =
         cwd,
     }, { includeFooter: true });
 }
-async function openOrUpdateSimpleReviewRequest(cwd, branch, title, version, previousVersion, commits, plan = null, options = {}) {
+async function openOrUpdateReviewRequest(cwd, branch, title, version, previousVersion, commits, plan = null, options = {}) {
     const loaded = (0, load_config_js_1.loadConfig)(cwd);
     const releaseFlow = loaded.config["review-mode"] ?? "pr";
     if (releaseFlow === "direct") {
@@ -396,6 +412,14 @@ async function openOrUpdateSimpleReviewRequest(cwd, branch, title, version, prev
     });
     return result.url;
 }
+/** @deprecated Use prepareReleasePr. */
+function prepareSimpleReleasePr(cwd = process.cwd(), options = {}) {
+    return prepareReleasePr(cwd, options);
+}
+/** @deprecated Use openOrUpdateReviewRequest. */
+async function openOrUpdateSimpleReviewRequest(cwd, branch, title, version, previousVersion, commits, plan = null, options = {}) {
+    return openOrUpdateReviewRequest(cwd, branch, title, version, previousVersion, commits, plan, options);
+}
 function pushReleaseBranch(cwd, branch) {
     (0, node_child_process_1.execFileSync)("git", ["push", "--force-with-lease", "origin", branch], {
         cwd,

package/dist/release/release.d.ts

@@ -1,8 +1,10 @@
 import type { VersionaryConfig } from "../types/config.js";
 import type { VersionaryPluginContext } from "../types/plugins.js";
+export declare function extractReleaseNotes(content: string, version: string, changelogFormat: "markdown-changelog" | "r-news"): string;
+export declare function extractClosingReferencesFromNotes(notes: string): number[];
 export declare function resolveTargetChangelogFile(config: VersionaryConfig, rootChangelogFile: string, targetPath: string): string;
-export declare function runSimpleRelease(cwd?: string): Promise<string>;
-export type SimpleRunReleaseResult = {
+export declare function runRelease(cwd?: string): Promise<string>;
+export type RunReleaseResult = {
     action: "release-skipped";
     reason: string;
 } | {
@@ -22,8 +24,16 @@ export type SimpleRunReleaseResult = {
         metadataStatus: "created" | "exists";
     }[];
 };
-export interface RunSimpleReleaseOptions {
+export interface RunReleaseOptions {
     logger?: VersionaryPluginContext["logger"];
     "dry-run"?: boolean;
 }
+export declare function runReleaseDetailed(cwd?: string, options?: RunReleaseOptions): Promise<RunReleaseResult>;
+/** @deprecated Use RunReleaseResult. */
+export type SimpleRunReleaseResult = RunReleaseResult;
+/** @deprecated Use RunReleaseOptions. */
+export type RunSimpleReleaseOptions = RunReleaseOptions;
+/** @deprecated Use runRelease. */
+export declare function runSimpleRelease(cwd?: string): Promise<string>;
+/** @deprecated Use runReleaseDetailed. */
 export declare function runSimpleReleaseDetailed(cwd?: string, options?: RunSimpleReleaseOptions): Promise<SimpleRunReleaseResult>;

package/dist/release/release.js

@@ -3,7 +3,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractReleaseNotes = extractReleaseNotes;
+exports.extractClosingReferencesFromNotes = extractClosingReferencesFromNotes;
 exports.resolveTargetChangelogFile = resolveTargetChangelogFile;
+exports.runRelease = runRelease;
+exports.runReleaseDetailed = runReleaseDetailed;
 exports.runSimpleRelease = runSimpleRelease;
 exports.runSimpleReleaseDetailed = runSimpleReleaseDetailed;
 const node_child_process_1 = require("node:child_process");
@@ -16,60 +20,109 @@ const plan_js_1 = require("./plan.js");
 const pr_js_1 = require("./pr.js");
 const recovery_js_1 = require("./recovery.js");
 const state_js_1 = require("./state.js");
-function getHeadCommitMessage(cwd) {
-    return (0, node_child_process_1.execFileSync)("git", ["log", "-1", "--pretty=%B"], {
-        cwd,
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "ignore"],
-    }).trim();
+function escapeRegExp(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
-function readReleaseNotes(cwd, version, changelogFile) {
-    const changelogPath = node_path_1.default.join(cwd, changelogFile);
-    if (!node_fs_1.default.existsSync(changelogPath)) {
-        return `Automated release for v${version}`;
-    }
-    const content = node_fs_1.default.readFileSync(changelogPath, "utf8");
+function extractReleaseNotes(content, version, changelogFormat) {
     const lines = content.split("\n");
     const shortVersion = version.replace(/\.\d+$/u, "");
-    const start = lines.findIndex((line) => line.startsWith(`## ${version} -`) ||
-        line.startsWith(`## [${version}](`) ||
-        line.startsWith(`# ${shortVersion} -`) ||
-        line.startsWith(`# [${shortVersion}](`) ||
-        new RegExp(`^#\\s+.+\\s+${shortVersion}\\s*$`, "u").test(line));
+    const start = changelogFormat === "r-news"
+        ? lines.findIndex((line) => {
+            const fullMatch = new RegExp(`^#\\s+.+\\s+${escapeRegExp(version)}\\s*$`, "u");
+            const shortMatch = new RegExp(`^#\\s+.+\\s+${escapeRegExp(shortVersion)}\\s*$`, "u");
+            return fullMatch.test(line) || shortMatch.test(line);
+        })
+        : lines.findIndex((line) => line.startsWith(`## ${version} -`) ||
+            line.startsWith(`## [${version}](`) ||
+            line.startsWith(`# ${shortVersion} -`) ||
+            line.startsWith(`# [${shortVersion}](`) ||
+            new RegExp(`^#\\s+.+\\s+${shortVersion}\\s*$`, "u").test(line));
     if (start < 0) {
-        return `Automated release for v${version}`;
+        return "";
     }
     let end = lines.length;
     for (let idx = start + 1; idx < lines.length; idx += 1) {
-        if (lines[idx]?.startsWith("## ")) {
+        const line = lines[idx] ?? "";
+        if (changelogFormat === "r-news") {
+            if (/^#(?!#)\s+/u.test(line)) {
+                end = idx;
+                break;
+            }
+            continue;
+        }
+        if (line.startsWith("## ")) {
             end = idx;
             break;
         }
     }
-    const notes = lines
+    return lines
         .slice(start + 1, end)
         .join("\n")
         .trim();
+}
+function getHeadCommitMessage(cwd) {
+    return (0, node_child_process_1.execFileSync)("git", ["log", "-1", "--pretty=%B"], {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+}
+function readReleaseNotes(cwd, version, changelogFile, changelogFormat) {
+    const changelogPath = node_path_1.default.join(cwd, changelogFile);
+    if (!node_fs_1.default.existsSync(changelogPath)) {
+        return `Automated release for v${version}`;
+    }
+    const content = node_fs_1.default.readFileSync(changelogPath, "utf8");
+    const notes = extractReleaseNotes(content, version, changelogFormat);
     return notes.length > 0 ? notes : `Automated release for v${version}`;
 }
+function extractClosingReferencesFromNotes(notes) {
+    const refs = new Set();
+    const linkedPattern = /\b(close|closes|closed|fix|fixes|fixed|resolve|resolves|resolved)\b\s+\[#(\d+)\]\([^)]+\)/giu;
+    for (const match of notes.matchAll(linkedPattern)) {
+        const issue = Number(match[2] ?? "");
+        if (Number.isInteger(issue) && issue > 0) {
+            refs.add(issue);
+        }
+    }
+    const plainPattern = /\b(close|closes|closed|fix|fixes|fixed|resolve|resolves|resolved)\b\s+#(\d+)/giu;
+    for (const match of notes.matchAll(plainPattern)) {
+        const issue = Number(match[2] ?? "");
+        if (Number.isInteger(issue) && issue > 0) {
+            refs.add(issue);
+        }
+    }
+    return [...refs].sort((a, b) => a - b);
+}
 function resolveTargetChangelogFile(config, rootChangelogFile, targetPath) {
     if (targetPath === ".") {
         return rootChangelogFile;
     }
-    const packageChangelogFile = config.packages?.[targetPath]?.["changelog-file"];
-    if (!packageChangelogFile) {
-        return rootChangelogFile;
-    }
+    const packageConfig = config.packages?.[targetPath];
+    const { changelogFile: packageChangelogFile } = (0, plan_js_1.getChangelogDefaults)({
+        "release-type": packageConfig?.["release-type"] ?? config["release-type"],
+        "changelog-file": packageConfig?.["changelog-file"] ?? config["changelog-file"],
+        "changelog-format": packageConfig?.["changelog-format"] ?? config["changelog-format"],
+    });
     return node_path_1.default.posix.join(targetPath, packageChangelogFile);
 }
-async function runSimpleRelease(cwd = process.cwd()) {
-    const result = await runSimpleReleaseDetailed(cwd, { logger: console });
+function resolveTargetChangelogFormat(config, targetPath) {
+    const packageConfig = targetPath === "." ? undefined : config.packages?.[targetPath];
+    const { changelogFormat } = (0, plan_js_1.getChangelogDefaults)({
+        "release-type": packageConfig?.["release-type"] ?? config["release-type"],
+        "changelog-file": packageConfig?.["changelog-file"] ?? config["changelog-file"],
+        "changelog-format": packageConfig?.["changelog-format"] ?? config["changelog-format"],
+    });
+    return changelogFormat;
+}
+async function runRelease(cwd = process.cwd()) {
+    const result = await runReleaseDetailed(cwd, { logger: console });
     if (result.action === "release-skipped") {
         return result.reason;
     }
     return result.message;
 }
-async function runSimpleReleaseDetailed(cwd = process.cwd(), options = {}) {
+async function runReleaseDetailed(cwd = process.cwd(), options = {}) {
     const commitMessage = getHeadCommitMessage(cwd);
     if (!(0, pr_js_1.isReleaseCommitMessage)(commitMessage)) {
         return {
@@ -80,6 +133,7 @@ async function runSimpleReleaseDetailed(cwd = process.cwd(), options = {}) {
     const loaded = (0, load_config_js_1.loadConfig)(cwd);
     const strategy = (0, resolve_js_1.resolveVersionStrategy)(loaded.config);
     const { changelogFile } = (0, plan_js_1.getChangelogDefaults)(loaded.config);
+    const referenceCommentMode = loaded.config["release-reference-comments"] ?? "off";
     const version = strategy.readVersion(cwd, loaded.config);
     const defaultTag = `v${version}`;
     const releaseTargets = (0, state_js_1.readReleaseTargets)(cwd);
@@ -105,12 +159,16 @@ async function runSimpleReleaseDetailed(cwd = process.cwd(), options = {}) {
     }
     const scmClient = (0, client_js_1.getScmClient)();
     const releases = [];
+    const referencesByTag = new Map();
     for (const target of targets) {
         const targetChangelogFile = resolveTargetChangelogFile(loaded.config, changelogFile, target.path);
+        const targetChangelogFormat = resolveTargetChangelogFormat(loaded.config, target.path);
+        const releaseNotes = readReleaseNotes(cwd, target.version, targetChangelogFile, targetChangelogFormat);
+        referencesByTag.set(target.tag, extractClosingReferencesFromNotes(releaseNotes));
         const outcome = await (0, recovery_js_1.executeIdempotentReleaseTarget)(cwd, {
             tag: target.tag,
             version: target.version,
-            notes: readReleaseNotes(cwd, target.version, targetChangelogFile),
+            notes: releaseNotes,
             draft: loaded.config["release-draft"] ?? false,
         }, {
             createReleaseMetadata: (input) => scmClient.createReleaseMetadata(input, {
@@ -125,6 +183,20 @@ async function runSimpleReleaseDetailed(cwd = process.cwd(), options = {}) {
             tagStatus: outcome.tagStatus,
             metadataStatus: outcome.metadataStatus,
         });
+        const references = referencesByTag.get(outcome.tag) ?? [];
+        if (references.length > 0 &&
+            referenceCommentMode !== "off" &&
+            scmClient.createReleaseReferenceComments) {
+            await scmClient.createReleaseReferenceComments({
+                version: target.version,
+                releaseUrl: outcome.url,
+                references,
+                mode: referenceCommentMode,
+            }, {
+                cwd,
+                logger: options.logger,
+            });
+        }
     }
     const published = releases.map((outcome) => `${outcome.tag}: ${outcome.url} (tag=${outcome.tagStatus}, metadata=${outcome.metadataStatus})`);
     return {
@@ -133,3 +205,11 @@ async function runSimpleReleaseDetailed(cwd = process.cwd(), options = {}) {
         message: `Published releases ${published.join(", ")}`,
     };
 }
+/** @deprecated Use runRelease. */
+async function runSimpleRelease(cwd = process.cwd()) {
+    return runRelease(cwd);
+}
+/** @deprecated Use runReleaseDetailed. */
+async function runSimpleReleaseDetailed(cwd = process.cwd(), options = {}) {
+    return runReleaseDetailed(cwd, options);
+}

package/dist/release/semver.js

@@ -5,10 +5,21 @@ exports.isValidVersion = isValidVersion;
 exports.compareVersions = compareVersions;
 exports.bumpVersion = bumpVersion;
 const SEMVER_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/u;
+const COMPAT_DOTTED_PRERELEASE_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u;
+function normalizeVersionInput(version) {
+    const trimmed = version.trim();
+    const compatMatch = trimmed.match(COMPAT_DOTTED_PRERELEASE_PATTERN);
+    if (!compatMatch) {
+        return trimmed;
+    }
+    const [, major, minor, patch, prerelease] = compatMatch;
+    return `${major}.${minor}.${patch}-${prerelease}`;
+}
 function parseVersion(version) {
-    const match = version.trim().match(SEMVER_PATTERN);
+    const normalized = normalizeVersionInput(version);
+    const match = normalized.match(SEMVER_PATTERN);
     if (!match) {
-        throw new Error(`Invalid version in version file: "${version}". Expected SemVer 2.0.0 format.`);
+        throw new Error(`Invalid version in version file: "${version}". Expected SemVer 2.0.0 format (or compatibility form X.Y.Z.W).`);
     }
     return {
         major: Number(match[1]),
@@ -19,7 +30,7 @@ function parseVersion(version) {
     };
 }
 function isValidVersion(version) {
-    return SEMVER_PATTERN.test(version.trim());
+    return SEMVER_PATTERN.test(normalizeVersionInput(version));
 }
 function isNumericIdentifier(identifier) {
     return /^(0|[1-9]\d*)$/u.test(identifier);

package/dist/scm/github-plugin.js

@@ -89,7 +89,11 @@ async function ensureLabels(octokit, repo, pullNumber, labels, branchContext) {
 function createGitHubPlugin() {
     return {
         name: "github",
-        capabilities: ["scm.reviewRequest", "scm.releaseMetadata"],
+        capabilities: [
+            "scm.reviewRequest",
+            "scm.releaseMetadata",
+            "scm.releaseReferenceComments",
+        ],
         provider: "github",
         async createOrUpdateReviewRequest(input, _context) {
             const repo = getRepoFromEnv();
@@ -205,5 +209,38 @@ function createGitHubPlugin() {
             }
             return { url: data.html_url, status: "created" };
         },
+        async createReleaseReferenceComments(input, context) {
+            const repo = getRepoFromEnv();
+            const octokit = new rest_1.Octokit({ auth: getGitHubToken() });
+            const uniqueReferences = [...new Set(input.references)].sort((a, b) => a - b);
+            const commented = [];
+            const mode = input.mode ?? "best-effort";
+            for (const reference of uniqueReferences) {
+                const body = reference >= 1_000_000_000
+                    ? `This pull request is included in [version ${input.version}](${input.releaseUrl}).`
+                    : `This issue has been resolved in [version ${input.version}](${input.releaseUrl}).`;
+                try {
+                    await octokit.issues.createComment({
+                        owner: repo.owner,
+                        repo: repo.repo,
+                        issue_number: reference,
+                        body,
+                    });
+                    commented.push(reference);
+                }
+                catch (error) {
+                    const { status, message } = parseGitHubError(error);
+                    if (mode === "strict") {
+                        throw new Error(`Failed creating release reference comment on #${reference}: [${repoRef(repo)}] ${message}`);
+                    }
+                    if (status === 404 || status === 410 || status === 403) {
+                        context.logger?.warn(`Skipping release reference comment on #${reference}: [${repoRef(repo)}] ${message}`);
+                        continue;
+                    }
+                    context.logger?.warn(`Skipping release reference comment on #${reference}: [${repoRef(repo)}] ${message}`);
+                }
+            }
+            return { commented };
+        },
     };
 }

package/dist/scm/types.d.ts

@@ -30,8 +30,18 @@ export interface ScmReleaseMetadataResult {
     url: string;
     status?: "created" | "exists";
 }
+export interface ScmReleaseReferenceCommentsInput {
+    version: string;
+    releaseUrl: string;
+    references: number[];
+    mode?: "best-effort" | "strict";
+}
+export interface ScmReleaseReferenceCommentsResult {
+    commented: number[];
+}
 export interface ScmClient {
     provider: ScmProvider;
     createOrUpdateReviewRequest: (input: ScmReviewRequestInput, context: ScmClientContext) => Promise<ScmReviewRequestResult>;
     createReleaseMetadata: (input: ScmReleaseMetadataInput, context: ScmClientContext) => Promise<ScmReleaseMetadataResult>;
+    createReleaseReferenceComments?: (input: ScmReleaseReferenceCommentsInput, context: ScmClientContext) => Promise<ScmReleaseReferenceCommentsResult>;
 }

package/dist/types/config.d.ts

@@ -1,5 +1,6 @@
 export type ConfigFileFormat = "jsonc" | "json" | "toml" | "js";
 export type VersionaryChangelogFormat = "markdown-changelog" | "r-news";
+export type ReleaseReferenceCommentsMode = "off" | "best-effort" | "strict";
 export interface VersionaryArtifactRule {
     type: "json" | "toml" | "yaml" | "regex";
     path: string;
@@ -22,6 +23,7 @@ export interface VersionaryConfig {
     "changelog-file"?: string;
     "changelog-format"?: VersionaryChangelogFormat;
     "release-draft"?: boolean;
+    "release-reference-comments"?: ReleaseReferenceCommentsMode;
     "release-branch"?: string;
     "baseline-file"?: string;
     "bootstrap-sha"?: string;

package/dist/types/plugins.d.ts

@@ -1,9 +1,11 @@
-import type { ScmClientContext, ScmProvider, ScmReleaseMetadataInput, ScmReleaseMetadataResult, ScmReviewRequestInput, ScmReviewRequestResult } from "../scm/types.js";
-export type VersionaryPluginCapability = "scm.reviewRequest" | "scm.releaseMetadata";
+import type { ScmClientContext, ScmProvider, ScmReleaseMetadataInput, ScmReleaseMetadataResult, ScmReleaseReferenceCommentsInput, ScmReleaseReferenceCommentsResult, ScmReviewRequestInput, ScmReviewRequestResult } from "../scm/types.js";
+export type VersionaryPluginCapability = "scm.reviewRequest" | "scm.releaseMetadata" | "scm.releaseReferenceComments";
 export type VersionaryScmReviewRequestInput = ScmReviewRequestInput;
 export type VersionaryScmReviewRequestResult = ScmReviewRequestResult;
 export type VersionaryScmReleaseMetadataInput = ScmReleaseMetadataInput;
 export type VersionaryScmReleaseMetadataResult = ScmReleaseMetadataResult;
+export type VersionaryScmReleaseReferenceCommentsInput = ScmReleaseReferenceCommentsInput;
+export type VersionaryScmReleaseReferenceCommentsResult = ScmReleaseReferenceCommentsResult;
 export type VersionaryPluginContext = ScmClientContext;
 export interface VersionaryPluginRuntime {
     name: string;
@@ -11,4 +13,5 @@ export interface VersionaryPluginRuntime {
     provider?: ScmProvider;
     createOrUpdateReviewRequest?: (input: VersionaryScmReviewRequestInput, context: VersionaryPluginContext) => Promise<VersionaryScmReviewRequestResult>;
     createReleaseMetadata?: (input: VersionaryScmReleaseMetadataInput, context: VersionaryPluginContext) => Promise<VersionaryScmReleaseMetadataResult>;
+    createReleaseReferenceComments?: (input: VersionaryScmReleaseReferenceCommentsInput, context: VersionaryPluginContext) => Promise<VersionaryScmReleaseReferenceCommentsResult>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "versionary",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Automatic release framework based on conventional commits and semantic versioning",
   "keywords": [
     "releasing",