versionary 0.2.0 → 0.4.0

package/README.md

@@ -1,13 +1,78 @@
-# 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:
 
-- `https://raw.githubusercontent.com/jolars/versionary/main/schemas/versionary-schema.json`
+- `https://raw.githubusercontent.com/jolars/versionary/main/schemas/config.json`
 
 ## Config (manifest style)
 
@@ -15,21 +80,85 @@ 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
+- `release-type: "r"` uses `DESCRIPTION` as version source and updates the
+  `Version:` field
+- `release-type: "rust"` uses Cargo manifests (`Cargo.toml`) as version source;
+  `version-file` must point to a `Cargo.toml` (default: `Cargo.toml`)
+- 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
 
+Rust strategy examples:
+
+```jsonc
+// Single crate
+{
+  "release-type": "rust",
+  "version-file": "Cargo.toml"
+}
+```
+
+```jsonc
+// Workspace root (virtual or root crate + members)
+{
+  "release-type": "rust",
+  "version-file": "Cargo.toml"
+}
+```
+
+Current rust auto-update behavior (phase scope):
+
+- updates crate versions in each targeted crate `[package].version`
+- updates internal workspace dependency versions when the dependency name
+  matches another targeted crate name
+- applies dependency version rewrites in:
+  - `[dependencies]`, `[dev-dependencies]`, `[build-dependencies]`
+  - `[target.*.dependencies]`, `[target.*.dev-dependencies]`,
+    `[target.*.build-dependencies]`
+
+Current rust non-goals/limits:
+
+- does not update external dependency versions
+- does not update `workspace.dependencies`
+- does not add missing `version = ...` fields to dependency inline tables
+- does not perform Cargo publish/release to crates.io
+
+## 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`
 - `pnpm run` (default orchestration: no-op, create/update release PR, or publish
   release based on context)
+- `pnpm run -- --json` (machine-readable orchestration result)
 - `pnpm plan`
 - `pnpm changelog -- --write`
 - `pnpm pr`
@@ -39,8 +168,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 +192,83 @@ 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
+  - id: versionary
+    uses: jolars/versionary@v1
+    with:
+      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
+  - id: versionary
+    uses: jolars/versionary@v1
+    with:
+      github-token: ${{ secrets.RELEASE_TOKEN }}
+  - if: ${{ steps.versionary.outputs.release_created == 'true' }}
+    run: echo "Released ${{ steps.versionary.outputs.tag_name }}"
+```
+
+Action outputs:
+
+- `action`: `noop`, `pr-prepared`, `release-published`, `release-skipped`
+- `message`: human-readable summary
+- `release_created`: `"true"` when at least one release was published
+- `tag_name`: first published tag (for single-target flows)
+- `tag_names`: JSON array of published tags
+- `review_url`: review request URL when PR flow runs
+
+For GitHub Action consumers, publish immutable tags (for example `v1.2.3`) and
+maintain a moving major tag (`v1`, `v2`, ...). A small release-triggered
+workflow should update `v<major>` to the latest release tag so `uses:
+jolars/versionary@v1` stays current without breaking major compatibility.
+
 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/app/release/artifact-rules.d.ts

@@ -0,0 +1,3 @@
+import type { SimplePlan } from "../../domain/release/plan.js";
+import type { VersionaryConfig } from "../../types/config.js";
+export declare function applyConfiguredArtifactRules(cwd: string, config: VersionaryConfig, plan: SimplePlan): string[];

package/dist/app/release/artifact-rules.js

@@ -0,0 +1,186 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyConfiguredArtifactRules = applyConfiguredArtifactRules;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const toml_1 = __importDefault(require("@iarna/toml"));
+const yaml_1 = __importDefault(require("yaml"));
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function parseJsonPath(jsonpath) {
+    if (!jsonpath.startsWith("$")) {
+        throw new Error(`Invalid jsonpath "${jsonpath}". Must start with "$".`);
+    }
+    const tokens = [];
+    let index = 1;
+    while (index < jsonpath.length) {
+        const current = jsonpath[index];
+        if (current === ".") {
+            const keyMatch = jsonpath.slice(index + 1).match(/^[A-Za-z0-9_-]+/u);
+            if (!keyMatch) {
+                throw new Error(`Invalid jsonpath "${jsonpath}" near index ${index}.`);
+            }
+            tokens.push(keyMatch[0]);
+            index += 1 + keyMatch[0].length;
+            continue;
+        }
+        if (current === "[") {
+            const rest = jsonpath.slice(index + 1);
+            const numberMatch = rest.match(/^(\d+)\]/u);
+            if (numberMatch) {
+                tokens.push(Number(numberMatch[1]));
+                index += 2 + numberMatch[1].length;
+                continue;
+            }
+            const keyMatch = rest.match(/^"([^"]+)"\]/u);
+            if (keyMatch) {
+                tokens.push(keyMatch[1]);
+                index += 4 + keyMatch[1].length;
+                continue;
+            }
+            throw new Error(`Invalid jsonpath "${jsonpath}" near index ${index}.`);
+        }
+        throw new Error(`Invalid jsonpath "${jsonpath}" near index ${index}.`);
+    }
+    if (tokens.length === 0) {
+        throw new Error(`Invalid jsonpath "${jsonpath}". Path must target a field.`);
+    }
+    return tokens;
+}
+function setVersionAtJsonPath(document, jsonpath, version) {
+    const tokens = parseJsonPath(jsonpath);
+    let cursor = document;
+    for (let index = 0; index < tokens.length - 1; index += 1) {
+        const token = tokens[index];
+        if (typeof token === "number") {
+            if (!Array.isArray(cursor) || token >= cursor.length) {
+                throw new Error(`jsonpath "${jsonpath}" does not resolve to an existing field.`);
+            }
+            cursor = cursor[token];
+            continue;
+        }
+        if (!isRecord(cursor) || !(token in cursor)) {
+            throw new Error(`jsonpath "${jsonpath}" does not resolve to an existing field.`);
+        }
+        cursor = cursor[token];
+    }
+    const leaf = tokens.at(-1);
+    if (typeof leaf === "number") {
+        if (!Array.isArray(cursor) || leaf >= cursor.length) {
+            throw new Error(`jsonpath "${jsonpath}" does not resolve to an existing field.`);
+        }
+        const current = cursor[leaf];
+        if (typeof current !== "string" && typeof current !== "number") {
+            throw new Error(`jsonpath "${jsonpath}" must point to a string or number field for version updates.`);
+        }
+        cursor[leaf] = version;
+        return;
+    }
+    if (!isRecord(cursor) || !(leaf in cursor)) {
+        throw new Error(`jsonpath "${jsonpath}" does not resolve to an existing field.`);
+    }
+    const current = cursor[leaf];
+    if (typeof current !== "string" && typeof current !== "number") {
+        throw new Error(`jsonpath "${jsonpath}" must point to a string or number field for version updates.`);
+    }
+    cursor[leaf] = version;
+}
+function parseRegexPattern(pattern) {
+    const slashPattern = pattern.match(/^\/((?:\\\/|[^/])+)\/([a-z]*)$/u);
+    if (slashPattern) {
+        return new RegExp(slashPattern[1], slashPattern[2]);
+    }
+    return new RegExp(pattern, "m");
+}
+function applyRegexRule(content, pattern, version) {
+    const regex = parseRegexPattern(pattern);
+    const matchFlags = regex.flags.includes("g")
+        ? regex.flags
+        : `${regex.flags}g`;
+    const globalRegex = new RegExp(regex.source, matchFlags);
+    const matches = [...content.matchAll(globalRegex)];
+    if (matches.length !== 1) {
+        throw new Error(`Regex pattern must match exactly one occurrence; matched ${matches.length}.`);
+    }
+    const match = matches[0];
+    const start = match.index;
+    if (start === undefined) {
+        throw new Error("Regex match did not include an index.");
+    }
+    const full = match[0];
+    const groupOne = match[1];
+    const replacement = typeof groupOne === "string" ? full.replace(groupOne, version) : version;
+    return `${content.slice(0, start)}${replacement}${content.slice(start + full.length)}`;
+}
+function applyArtifactRuleToContent(content, rule, version) {
+    if (rule.type === "regex") {
+        return applyRegexRule(content, rule.pattern, version);
+    }
+    if (rule.type === "json") {
+        const parsed = JSON.parse(content);
+        setVersionAtJsonPath(parsed, rule.jsonpath, version);
+        return `${JSON.stringify(parsed, null, 2)}\n`;
+    }
+    if (rule.type === "toml") {
+        const parsed = toml_1.default.parse(content);
+        setVersionAtJsonPath(parsed, rule.jsonpath, version);
+        return `${toml_1.default.stringify(parsed)}\n`;
+    }
+    const parsed = yaml_1.default.parse(content);
+    setVersionAtJsonPath(parsed, rule.jsonpath, version);
+    return `${yaml_1.default.stringify(parsed)}`;
+}
+function normalizeRelative(base, target) {
+    return node_path_1.default.relative(base, target).replaceAll("\\", "/");
+}
+function applyArtifactRulesForPackage(cwd, packagePath, packageConfig, version) {
+    const rules = packageConfig["extra-files"] ?? [];
+    if (rules.length === 0) {
+        return [];
+    }
+    const packageBase = node_path_1.default.join(cwd, packagePath);
+    const updated = [];
+    for (const rule of rules) {
+        const targetPath = node_path_1.default.join(packageBase, rule.path);
+        if (!node_fs_1.default.existsSync(targetPath)) {
+            throw new Error(`Artifact rule target missing for package "${packagePath}": ${rule.path}`);
+        }
+        const existing = node_fs_1.default.readFileSync(targetPath, "utf8");
+        let next;
+        try {
+            next = applyArtifactRuleToContent(existing, rule, version);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed applying artifact rule (${rule.type}) for package "${packagePath}" file "${rule.path}": ${message}`);
+        }
+        node_fs_1.default.writeFileSync(targetPath, next, "utf8");
+        updated.push(normalizeRelative(cwd, targetPath));
+    }
+    return updated;
+}
+function applyConfiguredArtifactRules(cwd, config, plan) {
+    const packageConfigs = config.packages ?? {};
+    if (!plan.packages || plan.packages.length === 0) {
+        return [];
+    }
+    const updated = new Set();
+    for (const packagePlan of plan.packages) {
+        if (!packagePlan.nextVersion) {
+            continue;
+        }
+        const packageConfig = packageConfigs[packagePlan.path];
+        if (!packageConfig?.["extra-files"]?.length) {
+            continue;
+        }
+        const files = applyArtifactRulesForPackage(cwd, packagePlan.path, packageConfig, packagePlan.nextVersion);
+        for (const file of files) {
+            updated.add(file);
+        }
+    }
+    return [...updated].sort((a, b) => a.localeCompare(b));
+}

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

@@ -0,0 +1,23 @@
+import { type SimplePlan } from "../../domain/release/plan.js";
+import type { ParsedCommit } from "../../infra/git/commits.js";
+import type { VersionaryPluginContext } from "../../types/plugins.js";
+export declare function splitSafeDirtyFiles(files: string[]): {
+    ignored: string[];
+    blocking: string[];
+};
+export declare function prepareSimpleReleasePr(cwd?: string, options?: {
+    logger?: VersionaryPluginContext["logger"];
+}): {
+    branch: string;
+    title: string;
+    version: string;
+    previousVersion: string;
+    commits: ParsedCommit[];
+    plan: SimplePlan;
+};
+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, options?: {
+    logger?: VersionaryPluginContext["logger"];
+}): Promise<string>;
+export declare function pushReleaseBranch(cwd: string, branch: string): void;
+export declare function isReleaseCommitMessage(subject: string): boolean;