versionary 0.2.0 → 0.3.0

package/README.md

@@ -1,9 +1,74 @@
-# versionary
+# Versionary
 
 Versionary is a software-agnostic automated release tool focused on SemVer,
 conventional commits, release PR workflows, and extensibility.
 
-Configuration is loaded from `versionary.jsonc` by default.
+## Why this exists
+
+Versionary is designed as a practical middle ground between `semantic-release`
+and `release-please`.
+
+- Like `semantic-release`, it supports direct release execution.
+- Like `release-please`, it supports a release PR workflow so maintainers can
+  preview and review changes before publication.
+
+The core idea is to keep versioning, changelog generation, tagging, and SCM
+release metadata in one tool, while leaving package publication (npm, crates.io,
+etc.) to dedicated CI workflows triggered by tags or releases.
+
+## Product direction
+
+Versionary is being built to:
+
+- support both direct releases and release-PR-gated releases
+- work across repository types (Node, Rust, docs/LaTeX, etc.)
+- stay SCM-agnostic at the core, with integrations via plugin capabilities
+  (GitHub first; GitLab/Codeberg later)
+- keep a small, stable core with explicit extension points
+- handle trunk-based development and monorepo workflows cleanly
+
+## Scope and non-goals
+
+In scope:
+
+- semantic version planning from commits
+- changelog generation
+- release PR automation
+- tags + SCM release metadata (e.g. GitHub Releases)
+
+Out of scope (intentional):
+
+- publishing artifacts to language registries
+- replacing package-specific publish tooling
+
+Use your CI/CD platform for registry publishing, triggered from a created
+release/tag.
+
+## Current status vs roadmap
+
+Current implementation focuses on:
+
+- strategy-based version updates (`simple`, `node`)
+- release planning and changelog generation
+- review-mode vs direct-mode release flow
+- built-in GitHub SCM plugin capabilities
+
+Planned/harder areas include deeper monorepo ergonomics, broader SCM coverage,
+and stronger failure recovery around release steps.
+
+## Architecture layout (current migration)
+
+The repository is moving to explicit layered modules:
+
+- `src/app/`: command-level application services and orchestration boundaries
+- `src/domain/`: release and strategy domain logic/contracts
+- `src/infra/`: platform integrations (SCM, git/runtime adapters)
+
+Legacy `src/simple/` has been removed. Remaining compatibility paths are
+`src/strategies` and `src/scm` while migration is finalized.
+
+Configuration is loaded from `versionary.jsonc` by default (or
+`versionary.json`).
 
 Schema URL for editor support:
 
@@ -15,16 +80,40 @@ For a quick trial, use:
 
 - `version-file` (default `version.txt`) as version source
 - `changelog-file` (default `CHANGELOG.md`) as release notes output
-- stable release branch (`release-branch`, default:
-  `versionary/release`) so release PRs are updated in-place
-- `baseline-file` (default `.versionary-manifest.json`) tracks baseline SHA for deterministic commit
-  ranges independent of tags
-- review mode (`review-mode`): `review` (PR/MR style) or `direct` (no
-  review request)
+- `release-type: "node"` uses `package.json` as version source and updates it
+  during release PR prep
+- simple/default strategy keeps `version.txt` as source of truth and does not
+  update `package.json`
+- stable release branch (`release-branch`, default: `versionary/release`) so
+  release PRs are updated in-place
+- `baseline-file` (default `.versionary-manifest.json`) tracks baseline SHA for
+  deterministic commit ranges independent of tags
+- pre-1.0 policy defaults to conservative major handling: for `0.y.z`, breaking
+  changes bump to `0.(y+1).0`; set `allow-stable-major: true` to allow explicit
+  auto-transition to `1.0.0` on a breaking release
+- review mode (`review-mode`): `review` (PR/MR style) or `direct` (no review
+  request)
 - optional monorepo planning with `monorepo-mode` and `packages`:
   - `independent` computes package bumps per path
   - `fixed` computes one shared bump across configured package paths
 
+## Commit parsing and release analysis
+
+Release planning is based on Conventional Commit parsing semantics:
+
+- parses type/scope/description from commit headers
+- exposes structured parsed fields (`header`, `body`, `footer`, `type`, `scope`,
+  `description`, `notes`, `references`, `mentions`, `revert`)
+- separates parser output from release policy mapping (`inferReleaseType*`)
+- recognizes breaking changes from `!` and `BREAKING CHANGE` /
+  `BREAKING-CHANGE` footers
+- maps release impact as `feat => minor`, `fix|perf => patch`, breaking => major
+- treats `revert:` as non-releasable commits
+- suppresses commits that are reverted within the analyzed release window so they
+  do not affect bump/changelog output
+- emits parser diagnostics for malformed headers/footers/references and ambiguous
+  revert messages
+
 Commands:
 
 - `pnpm verify`
@@ -39,8 +128,23 @@ Commands:
 via SCM plugin capability. `pnpm run` is the recommended CI entrypoint and
 auto-dispatches between PR/update and release publish.
 
-For first-run bootstrapping, set `bootstrap-sha` (similar to release-please). Subsequent runs use
-the baseline state file.
+For first-run bootstrapping, set `bootstrap-sha` (similar to release-please).
+Subsequent runs use the baseline state file.
+
+## Release retry and recovery behavior
+
+Release publish (`pnpm release` or the publish path in `pnpm run`) is
+idempotent by target tag:
+
+- if a tag already exists, Versionary reuses it rather than recreating it
+- if release metadata already exists for the tag (e.g., GitHub Release), it is
+  reused
+- if a prior run created/pushed the tag but failed before metadata creation, a
+  rerun creates the missing metadata and proceeds
+
+Versionary fails fast when recovery is unsafe (for example, local and remote
+tags with the same name point to different SHAs). In these cases, the error
+message includes remediation guidance so CI logs are actionable.
 
 ## Built-in plugins
 
@@ -48,8 +152,80 @@ Versionary ships with built-in SCM plugin support:
 
 - `github` (default): review request + release metadata
 
+### GitHub integration: env, permissions, and flow
+
+Required environment for the built-in GitHub plugin:
+
+- `GITHUB_REPOSITORY` (format: `owner/repo`)
+- one token env var: `VERSIONARY_PR_TOKEN` or `GH_TOKEN` or `GITHUB_TOKEN`
+
+Token precedence is:
+
+- `VERSIONARY_PR_TOKEN` > `GH_TOKEN` > `GITHUB_TOKEN`
+
+Minimum GitHub token/repo permissions for Versionary-managed metadata:
+
+- release PR create/update flow: `contents: write`, `pull-requests: write`
+- release metadata flow (GitHub Release create/read): `contents: write`
+
+`review-mode` behavior:
+
+- `review`: `pnpm run run` prepares/updates the release branch and creates or
+  updates a release PR
+- `direct`: `pnpm run run` prepares/updates the release branch and skips review
+  request creation
+
+Concise GitHub Actions examples:
+
+```yaml
+# 1) Release PR / update flow (run on push to default branch)
+permissions:
+  contents: write
+  pull-requests: write
+
+steps:
+  - uses: actions/checkout@v6
+    with:
+      fetch-depth: 0
+      fetch-tags: true
+  - uses: pnpm/action-setup@v6
+  - uses: actions/setup-node@v6
+    with:
+      node-version-file: .nvmrc
+      cache: pnpm
+  - run: pnpm install --frozen-lockfile --ignore-scripts
+  - run: |
+      git config user.name "github-actions[bot]"
+      git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      pnpm run run
+    env:
+      GITHUB_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+```
+
+```yaml
+# 2) Release publish flow after merge (release commit context)
+permissions:
+  contents: write
+
+steps:
+  - uses: actions/checkout@v6
+    with:
+      fetch-depth: 0
+      fetch-tags: true
+  - uses: pnpm/action-setup@v6
+  - uses: actions/setup-node@v6
+    with:
+      node-version-file: .nvmrc
+      cache: pnpm
+  - run: pnpm install --frozen-lockfile --ignore-scripts
+  - run: pnpm run run
+    env:
+      GITHUB_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+```
+
 Package publication is intentionally out of scope in the current release flow.
-Use separate CI workflows for publishing after Versionary has prepared/tagged the release.
+Use separate CI workflows for publishing after Versionary has prepared/tagged
+the release.
 
 ## Install from GitHub
 

package/dist/{simple → app/release}/pr.d.ts

@@ -1,4 +1,5 @@
-import type { CommitInfo } from "./git.js";
+import { type SimplePlan } from "../../domain/release/plan.js";
+import type { ParsedCommit } from "../../infra/git/commits.js";
 export declare function splitSafeDirtyFiles(files: string[]): {
     ignored: string[];
     blocking: string[];
@@ -7,9 +8,11 @@ export declare function prepareSimpleReleasePr(cwd?: string): {
     branch: string;
     title: string;
     version: string;
-    commits: CommitInfo[];
+    previousVersion: string;
+    commits: ParsedCommit[];
+    plan: SimplePlan;
 };
-export declare function renderSimpleReviewRequestBody(version: string, commits: CommitInfo[], cwd?: string): string;
-export declare function openOrUpdateSimpleReviewRequest(cwd: string, branch: string, title: string, version: string, commits: CommitInfo[]): Promise<string>;
+export declare function renderSimpleReviewRequestBody(version: string, previousVersion: string, commits: ParsedCommit[], plan?: SimplePlan | null, cwd?: string): string;
+export declare function openOrUpdateSimpleReviewRequest(cwd: string, branch: string, title: string, version: string, previousVersion: string, commits: ParsedCommit[], plan?: SimplePlan | null): Promise<string>;
 export declare function pushReleaseBranch(cwd: string, branch: string): void;
 export declare function isReleaseCommitMessage(subject: string): boolean;

package/dist/{simple → app/release}/pr.js

@@ -9,16 +9,14 @@ exports.renderSimpleReviewRequestBody = renderSimpleReviewRequestBody;
 exports.openOrUpdateSimpleReviewRequest = openOrUpdateSimpleReviewRequest;
 exports.pushReleaseBranch = pushReleaseBranch;
 exports.isReleaseCommitMessage = isReleaseCommitMessage;
-const node_fs_1 = __importDefault(require("node:fs"));
-const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
-const load_config_js_1 = require("../config/load-config.js");
-const capabilities_js_1 = require("../plugins/capabilities.js");
-const runtime_js_1 = require("../plugins/runtime.js");
-const plan_js_1 = require("./plan.js");
-const git_js_1 = require("./git.js");
-const repo_url_js_1 = require("./repo-url.js");
-const changelog_js_1 = require("./changelog.js");
+const node_path_1 = __importDefault(require("node:path"));
+const load_config_js_1 = require("../../config/load-config.js");
+const changelog_js_1 = require("../../domain/release/changelog.js");
+const plan_js_1 = require("../../domain/release/plan.js");
+const resolve_js_1 = require("../../domain/strategy/resolve.js");
+const capabilities_js_1 = require("../../plugins/capabilities.js");
+const runtime_js_1 = require("../../plugins/runtime.js");
 const state_js_1 = require("./state.js");
 const SAFE_DIRTY_FILES = new Set([
     "pnpm-lock.yaml",
@@ -69,94 +67,111 @@ function ensureCleanWorktree(cwd) {
 }
 function prepareSimpleReleasePr(cwd = process.cwd()) {
     const plan = (0, plan_js_1.createSimplePlan)(cwd);
+    const loaded = (0, load_config_js_1.loadConfig)(cwd);
+    const strategy = (0, resolve_js_1.resolveVersionStrategy)(loaded.config);
     if (!plan.nextVersion) {
         throw new Error("No releasable commits found. Nothing to open a release PR for.");
     }
     ensureCleanWorktree(cwd);
-    const versionPath = node_path_1.default.join(cwd, plan.versionFile);
-    node_fs_1.default.writeFileSync(versionPath, `${plan.nextVersion}\n`, "utf8");
+    const updatedVersionFiles = strategy.writeVersion(cwd, loaded.config, plan.nextVersion);
     const section = (0, changelog_js_1.renderSimpleChangelog)(plan);
     (0, changelog_js_1.prependChangelog)(cwd, plan.changelogFile, section);
     const branch = plan.releaseBranchPrefix;
     const title = `chore(release): v${plan.nextVersion}`;
-    (0, node_child_process_1.execFileSync)("git", ["checkout", "-B", branch], { cwd, stdio: ["ignore", "pipe", "ignore"] });
-    (0, node_child_process_1.execFileSync)("git", ["add", plan.versionFile, plan.changelogFile], {
+    (0, node_child_process_1.execFileSync)("git", ["checkout", "-B", branch], {
+        cwd,
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+    const filesToAdd = [...new Set([...updatedVersionFiles, plan.changelogFile])];
+    (0, node_child_process_1.execFileSync)("git", ["add", ...filesToAdd], {
         cwd,
         stdio: ["ignore", "pipe", "ignore"],
     });
-    (0, node_child_process_1.execFileSync)("git", ["commit", "-m", title], { cwd, stdio: ["ignore", "pipe", "ignore"] });
-    (0, state_js_1.writeBaselineSha)(cwd);
+    (0, node_child_process_1.execFileSync)("git", ["commit", "-m", title], {
+        cwd,
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+    const releaseTargets = plan.packages
+        ? plan.packages
+            .filter((pkg) => pkg.nextVersion)
+            .map((pkg) => ({
+            path: pkg.path,
+            version: pkg.nextVersion ?? "",
+            tag: pkg.path === "."
+                ? `v${pkg.nextVersion ?? ""}`
+                : `${pkg.path.replaceAll("/", "-")}-v${pkg.nextVersion ?? ""}`,
+            notes: (0, changelog_js_1.renderSimpleReleaseNotes)({
+                currentVersion: pkg.currentVersion,
+                nextVersion: pkg.nextVersion ?? "",
+                commits: pkg.commits,
+                cwd,
+            }, { includeFooter: false }),
+        }))
+        : [
+            {
+                path: ".",
+                version: plan.nextVersion,
+                tag: `v${plan.nextVersion}`,
+                notes: (0, changelog_js_1.renderSimpleReleaseNotes)({
+                    currentVersion: plan.currentVersion,
+                    nextVersion: plan.nextVersion,
+                    commits: plan.commits,
+                    cwd,
+                }, { includeFooter: false }),
+            },
+        ];
+    (0, state_js_1.writeBaselineSha)(cwd, undefined, releaseTargets);
     (0, node_child_process_1.execFileSync)("git", ["add", (0, state_js_1.getBaselineStatePath)(cwd)], {
         cwd,
         stdio: ["ignore", "pipe", "ignore"],
     });
-    (0, node_child_process_1.execFileSync)("git", ["commit", "--amend", "--no-edit"], { cwd, stdio: ["ignore", "pipe", "ignore"] });
+    (0, node_child_process_1.execFileSync)("git", ["commit", "--amend", "--no-edit"], {
+        cwd,
+        stdio: ["ignore", "pipe", "ignore"],
+    });
     return {
         branch,
         title,
         version: plan.nextVersion,
+        previousVersion: plan.currentVersion,
         commits: plan.commits,
+        plan,
     };
 }
-function formatCommitMessage(subject) {
-    const conventional = subject.match(/^[a-z]+(?:\(([^)]+)\))?!?:\s+(.+)$/iu);
-    if (!conventional) {
-        return { label: "", message: subject };
+function renderSimpleReviewRequestBody(version, previousVersion, commits, plan = null, cwd = process.cwd()) {
+    if (plan?.packages && plan.packages.length > 1) {
+        const sections = plan.packages
+            .filter((pkg) => pkg.nextVersion)
+            .map((pkg) => {
+            const notes = (0, changelog_js_1.renderSimpleReleaseNotes)({
+                currentVersion: pkg.currentVersion,
+                nextVersion: pkg.nextVersion ?? "",
+                commits: pkg.commits,
+                cwd,
+            }, { includeFooter: false });
+            const linkedHeader = notes.match(/^##\s+\[([^\]]+)\]\(([^)]+)\)\s+\(([^)]+)\)/u);
+            if (linkedHeader) {
+                const [, , compareUrl, date] = linkedHeader;
+                return notes.replace(/^##\s+\[[^\]]+\]\([^)]+\)\s+\([^)]+\)/u, `## [${pkg.path}: ${pkg.nextVersion ?? ""}](${compareUrl}) (${date})`);
+            }
+            const plainHeader = notes.match(/^##\s+([^\s]+)\s+\(([^)]+)\)/u);
+            if (plainHeader) {
+                const [, , date] = plainHeader;
+                return notes.replace(/^##\s+[^\s]+\s+\([^)]+\)/u, `## ${pkg.path}: ${pkg.nextVersion ?? ""} (${date})`);
+            }
+            return notes;
+        })
+            .join("\n\n");
+        return `${sections}\n\nThis PR was generated by Versionary.`;
     }
-    const scope = conventional[1]?.trim();
-    const message = conventional[2]?.trim() ?? subject;
-    const label = scope ? `**${scope}:** ` : "";
-    return { label, message };
-}
-function renderSimpleReviewRequestBody(version, commits, cwd = process.cwd()) {
-    const breaking = [];
-    const features = [];
-    const fixes = [];
-    const commitBaseUrl = (0, repo_url_js_1.resolveRepositoryWebBaseUrl)(cwd);
-    for (const commit of commits) {
-        const subject = commit.subject;
-        const { label, message } = formatCommitMessage(subject);
-        const hash = commit.hash.slice(0, 7);
-        const hashLabel = commitBaseUrl ? `[\`${hash}\`](${commitBaseUrl}/commit/${commit.hash})` : `\`${hash}\``;
-        const type = (0, git_js_1.inferReleaseTypeFromSubject)(subject);
-        if (!type) {
-            continue;
-        }
-        const item = `- ${label}${message} (${hashLabel})`;
-        if (type === "major") {
-            breaking.push(item);
-            continue;
-        }
-        if (type === "minor") {
-            features.push(item);
-            continue;
-        }
-        fixes.push(item);
-    }
-    const sections = [];
-    if (breaking.length > 0) {
-        sections.push("### Breaking changes", ...breaking, "");
-    }
-    if (features.length > 0) {
-        sections.push("### Features", ...features, "");
-    }
-    if (fixes.length > 0) {
-        sections.push("### Fixes", ...fixes, "");
-    }
-    return [
-        ":robot: I have created a release PR for this repository.",
-        "",
-        `## Version`,
-        "",
-        `This PR prepares **v${version}**.`,
-        "",
-        "## Release notes preview",
-        "",
-        ...sections,
-        "This PR was generated by Versionary.",
-    ].join("\n");
+    return (0, changelog_js_1.renderSimpleReleaseNotes)({
+        currentVersion: previousVersion,
+        nextVersion: version,
+        commits,
+        cwd,
+    }, { includeFooter: true });
 }
-async function openOrUpdateSimpleReviewRequest(cwd, branch, title, version, commits) {
+async function openOrUpdateSimpleReviewRequest(cwd, branch, title, version, previousVersion, commits, plan = null) {
     const loaded = (0, load_config_js_1.loadConfig)(cwd);
     const releaseFlow = loaded.config["review-mode"] ?? "direct";
     if (releaseFlow !== "review") {
@@ -175,7 +190,7 @@ async function openOrUpdateSimpleReviewRequest(cwd, branch, title, version, comm
         baseBranch: process.env.VERSIONARY_BASE_BRANCH ?? "main",
         headBranch: branch,
         title,
-        body: renderSimpleReviewRequestBody(version, commits, cwd),
+        body: renderSimpleReviewRequestBody(version, previousVersion, commits, plan, cwd),
         labels: ["release"],
     }, {
         cwd,

package/dist/app/release/recovery.d.ts

@@ -0,0 +1,17 @@
+import type { VersionaryScmReleaseMetadataResult } from "../../types/plugins.js";
+export type TagStepResult = "created" | "exists";
+export interface ReleaseTargetInput {
+    tag: string;
+    version: string;
+    notes: string;
+}
+export interface ReleaseExecutionContext {
+    createReleaseMetadata: (input: ReleaseTargetInput) => Promise<VersionaryScmReleaseMetadataResult>;
+}
+export interface ReleaseTargetOutcome {
+    tag: string;
+    tagStatus: TagStepResult;
+    metadataStatus: "created" | "exists";
+    url: string;
+}
+export declare function executeIdempotentReleaseTarget(cwd: string, target: ReleaseTargetInput, context: ReleaseExecutionContext): Promise<ReleaseTargetOutcome>;

package/dist/app/release/recovery.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeIdempotentReleaseTarget = executeIdempotentReleaseTarget;
+const node_child_process_1 = require("node:child_process");
+function hasRemoteTag(cwd, tag) {
+    try {
+        const output = (0, node_child_process_1.execFileSync)("git", ["ls-remote", "--tags", "origin", `refs/tags/${tag}`], {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return output.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function readRemoteTagSha(cwd, tag) {
+    try {
+        const output = (0, node_child_process_1.execFileSync)("git", ["ls-remote", "--tags", "origin", `refs/tags/${tag}`], {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (!output) {
+            return null;
+        }
+        const [sha] = output.split(/\s+/u);
+        return sha ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function createTagWithRecovery(cwd, tag) {
+    const localTag = (0, node_child_process_1.execFileSync)("git", ["tag", "--list", tag], {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (localTag.length > 0) {
+        const localSha = (0, node_child_process_1.execFileSync)("git", ["rev-parse", `refs/tags/${tag}`], {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        const remoteSha = readRemoteTagSha(cwd, tag);
+        if (remoteSha && remoteSha !== localSha) {
+            throw new Error(`Tag drift detected for "${tag}": local tag (${localSha.slice(0, 7)}) differs from remote (${remoteSha.slice(0, 7)}). Resolve the tag mismatch before retrying release.`);
+        }
+        return "exists";
+    }
+    try {
+        (0, node_child_process_1.execFileSync)("git", ["tag", tag], {
+            cwd,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+    }
+    catch {
+        throw new Error(`Failed creating local tag "${tag}". Ensure repository is writable and retry.`);
+    }
+    try {
+        (0, node_child_process_1.execFileSync)("git", ["push", "origin", tag], {
+            cwd,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        return "created";
+    }
+    catch {
+        if (hasRemoteTag(cwd, tag)) {
+            const localSha = (0, node_child_process_1.execFileSync)("git", ["rev-parse", `refs/tags/${tag}`], {
+                cwd,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+            }).trim();
+            const remoteSha = readRemoteTagSha(cwd, tag);
+            if (remoteSha && remoteSha !== localSha) {
+                throw new Error(`Tag drift detected for "${tag}": local tag (${localSha.slice(0, 7)}) differs from remote (${remoteSha.slice(0, 7)}). Resolve the tag mismatch before retrying release.`);
+            }
+            return "exists";
+        }
+        throw new Error(`Failed pushing tag "${tag}" to origin. Check push permissions and remote connectivity, then retry.`);
+    }
+}
+async function executeIdempotentReleaseTarget(cwd, target, context) {
+    const tagStatus = createTagWithRecovery(cwd, target.tag);
+    const metadata = await context.createReleaseMetadata(target);
+    const metadataStatus = metadata.status ?? "created";
+    if (tagStatus === "exists" && metadataStatus === "created") {
+        console.info(`Recovered drift for ${target.tag}: tag already existed and release metadata has now been created.`);
+    }
+    if (!metadata.url) {
+        throw new Error(`Release metadata for "${target.tag}" did not return a URL. Verify SCM API permissions and retry.`);
+    }
+    return {
+        tag: target.tag,
+        tagStatus,
+        metadataStatus,
+        url: metadata.url,
+    };
+}