versionary 0.30.0 → 0.32.0

package/README.md

@@ -1,474 +1,136 @@
 # Versionary
 
 Versionary is a software-agnostic automated release tool focused on SemVer,
-conventional commits, release PR workflows, and extensibility.
+Conventional Commits, release-PR workflows, and extensibility.
 
-## Why this exists
+📖 **Documentation: <https://versionary.dev/>**
 
-Versionary is designed as a practical middle ground between `semantic-release`
-and `release-please`.
+## Why this exists
 
-- 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.
+Versionary is a practical middle ground between
+[`semantic-release`](https://github.com/semantic-release/semantic-release) and
+[`release-please`](https://github.com/googleapis/release-please):
 
-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.
+- 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.
 
-## Product direction
+It keeps 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.
 
-Versionary is being built to:
+It is 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 built-in integration adapters
-  (GitHub first; GitLab/Codeberg later)
-- keep a small, stable core with explicit extension points
+- work across ecosystems (Node, Rust, Python, R, Julia, LaTeX, …)
+- stay SCM-agnostic at the core with built-in integration (GitHub first)
+- keep a small, stable core with clear extension points
 - handle trunk-based development and monorepo workflows cleanly
 
-## Scope and non-goals
+> **Status:** early, alpha-stage development. Breaking changes are expected
+> before `1.0.0`.
 
-In scope:
+## Quick start
 
-- semantic version planning from commits
-- changelog generation
-- release PR automation
-- tags + SCM release metadata (e.g. GitHub Releases)
+Install:
 
-Out of scope (intentional):
+```bash
+pnpm add -D versionary    # or npm install --save-dev versionary
+```
 
-- publishing artifacts to language registries
-- replacing package-specific publish tooling
-- external/user-provided plugin loading
+Add a `versionary.jsonc` at the repo root:
 
-Use your CI/CD platform for registry publishing, triggered from a created
-release/tag.
+```jsonc
+{
+  "$schema": "https://raw.githubusercontent.com/jolars/versionary/main/schemas/config.json",
+  "version": 1,
+  "release-type": "node"
+}
+```
 
-## Current status vs roadmap
+Check it and preview the next release:
 
-Current implementation focuses on:
+```bash
+npx versionary verify
+npx versionary plan
+```
 
-- strategy-based version updates (`simple`, `node`, `rust`, `r`, `latex`,
-  `python`)
-- release planning and changelog generation
-- review-mode vs direct-mode release flow
-- a static internal SCM client (`github` provider today)
+Then automate it in CI—see the
+[Getting started](https://versionary.dev/guide/getting-started) and
+[GitHub Actions](https://versionary.dev/guide/github-actions)
+guides.
 
-Planned/harder areas include deeper monorepo ergonomics, broader SCM coverage,
-and stronger failure recovery around release steps.
+## Documentation
 
-## Adding a new release strategy
+The full documentation lives at <https://versionary.dev/>:
 
-Versionary is set up so new language strategies can be added internally without
-changing release orchestration. A new strategy should implement the
-`VersionStrategy` contract in `src/strategy/types.ts` and be wired in
-`src/strategy/resolve.ts`.
+- [Getting started](https://versionary.dev/guide/getting-started)
+- [GitHub Actions setup](https://versionary.dev/guide/github-actions)
+  (including tokens and permissions)
+- [Release workflows](https://versionary.dev/guide/workflows)
+- [Monorepos](https://versionary.dev/guide/monorepos)
+- [Conventional Commits](https://versionary.dev/guide/conventional-commits)
+  and [Versioning](https://versionary.dev/guide/versioning)
+- Reference:
+  [CLI](https://versionary.dev/reference/cli),
+  [Configuration](https://versionary.dev/reference/configuration),
+  [Strategies](https://versionary.dev/reference/strategies)
 
-Checklist for new strategies:
+## Scope and non-goals
 
-- define strategy `name`
-- define `getVersionFile(config)` defaults and config override behavior
-- implement `readVersion(cwd, config)` with explicit malformed-file errors
-- implement `writeVersion(cwd, config, version)` returning deterministic updated
-  file paths
-- optionally implement `readPackageName(cwd, config)` so monorepo release tags
-  can derive from language metadata (similar to Node/Rust/R)
-- optionally implement `propagateDependentPatchImpacts(cwd, packages)` if
-  dependency updates in this ecosystem should trigger dependent package patch
-  bumps
-- optionally implement `finalizeVersionWrites(cwd, writes, context)` for
-  ecosystem post-processing after all target version files are written
-- add focused strategy tests for ecosystem-specific behavior and edge cases
-- add/extend strategy contract tests in `tests/strategy-contract.test.ts`
-- update schema/docs for new `release-type` behavior and defaults
+In scope: semantic version planning from commits, changelog generation, release
+PR automation, and tags + SCM release metadata (e.g. GitHub Releases).
 
-Current ecosystem policy defaults:
-
-- changelog source for publish:
-  - root target uses 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
-  - Rust release PR prep refreshes all discovered `Cargo.lock` files
-  - Python strategy refreshes any `poetry.lock`/`uv.lock`/`pdm.lock` at the
-    package root by shelling out to the matching tool (`poetry lock
-    --no-update`, `uv lock`, `pdm lock --update-reuse`); the corresponding
-    binary must be on `PATH`
-- workspace/inheritance:
-  - Rust supports `version.workspace = true` via `[workspace.package].version`
-  - other strategies should document equivalent inheritance behavior explicitly
+Out of scope (intentional): publishing artifacts to language registries,
+replacing package-specific publish tooling, and external/user-provided plugin
+loading. Use your CI/CD platform for registry publishing, triggered from a
+created release/tag.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development setup, commands, and
+commit conventions.
 
 ## Architecture layout (canonical)
 
-Current runtime code uses a flat `src/` layout with clear module boundaries:
+Runtime code uses a flat `src/` layout with clear module boundaries:
 
 - `src/cli/`: command router (`run`, `verify`, `plan`, `changelog`, `pr`, `release`)
 - `src/release/`: release orchestration (plan/changelog/PR/release/state/recovery)
 - `src/strategy/`: strategy contracts, resolver, and built-in implementations
-  (`simple`, `node`, `rust`, `r`, `latex`, `python`)
+  (`simple`, `node`, `rust`, `r`, `latex`, `python`, `julia`)
 - `src/scm/`: SCM client contracts and provider implementation(s)
 - `src/config/`: config loading and schema validation
 - `src/git/`: git commit/range and repository URL helpers
-- `src/verify/`: repository/config verification
 - `src/types/`: shared config/plugin-facing types
 
 Configuration is loaded from `versionary.jsonc` by default (or
-`versionary.json`).
-
-Schema URL for editor support:
-
-- `https://raw.githubusercontent.com/jolars/versionary/main/schemas/config.json`
-
-## Config (manifest style)
-
-For a quick trial, use:
-
-- `version-file` (default `version.txt`) as version source
-- `changelog-file` (default `CHANGELOG.md`) as release notes output
-- `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`)
-- `release-type: "latex"` uses `build.lua` as version source and updates LaTeX
-  `\ProvidesPackage{...}[YYYY-MM-DD vX.Y.Z ...]` metadata in `src/**/*.dtx`
-  using the release commit date
-- `release-type: "python"` uses `pyproject.toml` (default) and updates
-  `[project].version` and/or `[tool.poetry].version`; point `version-file` at a
-  Python source file (e.g. `src/<pkg>/__init__.py`) to update a `__version__`
-  assignment instead. Refreshes `poetry.lock`/`uv.lock`/`pdm.lock` at the
-  package root if present
-- `release-type` can also be an array of strategy names to compose them across
-  manifests, e.g. `["python", "rust"]` for a PyO3/maturin project: the first
-  entry is the *primary* (drives `readVersion`, `readPackageName`, and consumes
-  any `version-file` override); each *secondary* writes its default manifest
-  with the same target version. Common combinations:
-  - `["python", "rust"]` — PyO3/maturin (`pyproject.toml` + `Cargo.toml` +
-    `Cargo.lock`)
-  - `["node", "rust"]` — napi-rs (`package.json` + `Cargo.toml` + `Cargo.lock`)
-  - `["r", "rust"]` — R packages with embedded Rust crates (note: nested
-    `src/rust/Cargo.toml` layouts are not supported by the array form yet —
-    use a single strategy until per-strategy `version-file` overrides land)
-- 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`): `pr` (PR/MR style) or `direct` (no review
-  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
-  - comments are authored by the account that owns the configured token; see
-    [Comment and commit author identity](#comment-and-commit-author-identity)
-    to post them under a bot identity
-- optional monorepo planning with `monorepo-mode` and `packages`:
-  - `independent` computes package bumps per path
-  - `fixed` computes one shared bump across configured package paths
-  - per-package `package-name` can override release identity (labels + tag base)
-  - per-package `changelog-file` writes package release notes to
-    `<package-path>/<changelog-file>`
-  - per-package `follows` declares an asymmetric version link to one or more
-    source packages: when any source bumps, the follower releases too, with
-    bump = `max(own bump, max(source bumps))`. The follower's changelog gets a
-    `### Dependencies` section listing the followed sources. Use it when one
-    package bundles another's artifact (e.g. an editor extension that ships
-    the CLI binary). Cycles, self-references, unknown source paths, and
-    combining `follows` with `monorepo-mode: "fixed"` are config errors.
-    `follows` is non-transitive: A follows B does not imply A follows what B
-    follows.
-  - per-package `exclude-paths` drops commits that only touch the listed paths
-    (relative to the package) from that package's bump and changelog. A
-    top-level `exclude-paths` applies to every package; the effective excludes
-    for a package are the union of the top-level list and the package's own
-    list. The top-level list also applies to a single-package (non-`packages`)
-    repository.
-
-```jsonc
-// Editor extension that bundles the root CLI artifact
-{
-  "version": 1,
-  "release-type": "rust",
-  "monorepo-mode": "independent",
-  "packages": {
-    ".": { "exclude-paths": ["editors"] },
-    "editors/code": {
-      "release-type": "node",
-      "package-name": "panache-code",
-      "follows": ["."]
-    }
-  }
-}
-```
-
-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`
-- supports targeted crates using `version.workspace = true` by updating
-  `[workspace.package].version` in the owning workspace manifest
-- updates internal workspace dependency versions when the dependency name
-  matches another targeted crate name
-- refreshes `Cargo.lock` via `cargo generate-lockfile` when `Cargo.lock` exists
-  in repo root
-- 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
-
-If `Cargo.lock` exists, `cargo` must be available in PATH during PR preparation.
-
-### Monorepo release names and tag naming
-
-For independent monorepo targets, Versionary derives release tags as:
-
-- root package (`"."`): `v<version>`
-- non-root package: `<release-name>-v<version>`
-
-`release-name` precedence is:
-
-1. `packages.<path>.package-name` (explicit override)
-2. strategy-native package name from version file:
-   - Node: `package.json` `name`
-   - Rust: `Cargo.toml` `[package].name`
-   - R: `DESCRIPTION` `Package:`
-3. package path fallback
-
-When multiple packages resolve to the same `<release-name>` and version, the run
-fails fast with a duplicate-tag error and suggests setting unique
-`package-name` values.
-
-## 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:` commits as patch-releasable by default (and major if marked
-  breaking, e.g. `revert!:` or `BREAKING CHANGE`)
-- 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:
+`versionary.json`). The config schema lives in `src/config/schema.ts`; the
+editor-facing `schemas/config.json` is generated via `pnpm gen:schema`.
 
-- `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`
-- `pnpm release`
-
-`pnpm pr` prepares release commit + branch and opens/updates a review request
-through the SCM client. `pnpm run` is the recommended CI entrypoint and
-auto-dispatches between PR/update and release publish.
-
-### Moloch migration example (semantic-release -> versionary)
-
-For LaTeX projects like `moloch`, use `release-type: "latex"` so Versionary:
-
-- bumps `build.lua` version
-- updates `src/**/*.dtx` `\ProvidesPackage{...}[YYYY-MM-DD vX.Y.Z ...]` entries
-  with the release commit date (`git show --format=%cs <sha>`)
-
-Example `versionary.jsonc` for `moloch`:
-
-```jsonc
-{
-  "version": 1,
-  "review-mode": "pr",
-  "release-type": "latex",
-  "version-file": "build.lua",
-  "changelog-file": "CHANGELOG.md",
-  "release-branch": "versionary/release"
-}
-```
-
-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.
-
-## SCM API model
-
-Versionary currently uses a static internal SCM client model:
-
-- `src/scm/types.ts` defines the `ScmClient` contract
-- `src/scm/client.ts` returns the active provider client
-- current provider is `github` via `src/scm/github-plugin.ts`
-
-There is no runtime discovery/loading of external SCM providers in the release
-flow. Adding another provider is an internal extension: implement `ScmClient`
-and wire provider selection in `src/scm/client.ts`.
-
-### GitHub integration: env, permissions, and flow
-
-Required environment for the GitHub SCM provider:
-
-- `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:
-
-- `pr` (preferred; `review` is a backward-compatible alias): `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:
-      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:
-      token: ${{ secrets.RELEASE_TOKEN }}
-  - if: ${{ steps.versionary.outputs.release_created == 'true' }}
-    run: echo "Released ${{ steps.versionary.outputs.tag_name }}"
-```
-
-`token` is used for both GitHub API calls and git push authentication in
-the composite action. This means release-branch force-pushes are attributed to
-that token and can trigger downstream workflows when using a PAT/App token.
-(`github-token` remains as a deprecated alias for backward compatibility.)
-
-#### Comment and commit author identity
-
-Two distinct identities are at play; keep them apart.
-
-**Release-reference comments, the GitHub Release, and the tag/branch push** are
-attributed to the account that owns the token you provide. There is no GitHub
-API to set a custom author independent of the token, so this identity always
-follows the token's account:
-
-- the workflow's default `GITHUB_TOKEN` acts as `github-actions[bot]` — the
-  common case, and what most `semantic-release` setups show
-- a **personal access token (PAT)** acts as your own user
-- a **dedicated bot user account** acts as that account (for example
-  `semantic-release`'s own `@semantic-release-bot`): create a separate GitHub
-  user, generate a PAT for it, and store it as the release token
-- a **GitHub App installation token** (e.g. minted with
-  `actions/create-github-app-token`) acts as `<app-name>[bot]`
-
-**The release commit's committer** comes from git's `user.name`/`user.email`,
-not the token. When neither is configured (e.g. a bare CI runner), Versionary
-defaults it to `github-actions[bot]`, so no `git config` step is needed in your
-workflow; an existing identity (local, global, or the one the GitHub Action
-wrapper sets) is left untouched.
-
-The release-reference comment body itself is signed by Versionary regardless of
-which account posts it.
-
-Action outputs:
+## Adding a new release strategy
 
-- `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
+New language strategies can be added internally without changing release
+orchestration. A new strategy should implement the `VersionStrategy` contract in
+`src/strategy/types.ts` and be wired in `src/strategy/resolve.ts`.
 
-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.
+Checklist for new strategies:
 
-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.
+- define strategy `name`
+- define `getVersionFile(config)` defaults and config override behavior
+- implement `readVersion(cwd, config)` with explicit malformed-file errors
+- implement `writeVersion(cwd, config, version)` returning deterministic updated
+  file paths
+- optionally implement `readPackageName(cwd, config)` so monorepo release tags
+  can derive from language metadata (similar to Node/Rust/R)
+- optionally implement `propagateDependentPatchImpacts(cwd, packages)` if
+  dependency updates in this ecosystem should trigger dependent package patch
+  bumps
+- optionally implement `finalizeVersionWrites(cwd, writes, context)` for
+  ecosystem post-processing after all target version files are written
+- add focused strategy tests for ecosystem-specific behavior and edge cases
+- add/extend strategy contract tests in `tests/strategy-contract.test.ts`
+- update schema/docs for new `release-type` behavior and defaults
 
 ## Install from GitHub
 
@@ -483,4 +145,8 @@ You can install directly from a git ref:
 ```
 
 The package runs a `prepare` build during git installation so the `versionary`
-CLI binary is available after `pnpm install`.
+CLI binary is available after install.
+
+## License
+
+[MIT](LICENSE)

package/dist/config/schema.d.ts

@@ -40,6 +40,7 @@ export declare const configSchema: z.ZodObject<{
             "markdown-changelog": "markdown-changelog";
             "r-news": "r-news";
         }>>;
+        "allow-stable-major": z.ZodOptional<z.ZodBoolean>;
         "exclude-paths": z.ZodOptional<z.ZodArray<z.ZodString>>;
         "extra-files": z.ZodOptional<z.ZodArray<z.ZodObject<{
             type: z.ZodEnum<{
@@ -53,6 +54,7 @@ export declare const configSchema: z.ZodObject<{
             "field-path": z.ZodOptional<z.ZodString>;
             jsonpath: z.ZodOptional<z.ZodString>;
             pattern: z.ZodOptional<z.ZodString>;
+            replacement: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
         follows: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>>;

package/dist/config/schema.js

@@ -6,6 +6,7 @@ const artifactRuleSchema = z
     "field-path": z.string().optional(),
     jsonpath: z.string().optional(),
     pattern: z.string().optional(),
+    replacement: z.string().optional(),
 })
     .superRefine((value, ctx) => {
     const needsJsonPath = value.type === "json" ||
@@ -27,6 +28,13 @@ const artifactRuleSchema = z
             path: ["pattern"],
         });
     }
+    if (needsJsonPath && value.replacement) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `${value.type} artifact rules do not support "replacement".`,
+            path: ["replacement"],
+        });
+    }
     if (value["field-path"] && value.jsonpath) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
@@ -57,6 +65,7 @@ const packageSchema = z
     "package-name": z.string().optional(),
     "changelog-file": z.string().optional(),
     "changelog-format": z.enum(["markdown-changelog", "r-news"]).optional(),
+    "allow-stable-major": z.boolean().optional(),
     "exclude-paths": z.array(z.string()).optional(),
     "extra-files": z.array(artifactRuleSchema).optional(),
     follows: z.array(z.string().min(1)).optional(),

package/dist/release/artifact-rules.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 import YAML from "yaml";
+import { parseVersion } from "./semver.js";
 const WILDCARD = Symbol("wildcard");
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -160,12 +161,34 @@ function parseRegexPattern(pattern) {
     }
     return new RegExp(pattern, "m");
 }
-function applyRegexRule(content, pattern, version) {
+const REPLACEMENT_TOKEN_PATTERN = /\{\{\s*([A-Za-z]+)\s*\}\}/gu;
+function renderReplacementTemplate(template, version) {
+    const parsed = parseVersion(version);
+    const tokens = {
+        version,
+        major: String(parsed.major),
+        minor: String(parsed.minor),
+        patch: String(parsed.patch),
+        prerelease: parsed.prerelease.join("."),
+        build: parsed.build.join("."),
+    };
+    return template.replace(REPLACEMENT_TOKEN_PATTERN, (_whole, name) => {
+        const key = name.toLowerCase();
+        const value = tokens[key];
+        if (value === undefined) {
+            throw new Error(`Unknown replacement token "{{${name}}}". Supported tokens: ${Object.keys(tokens)
+                .map((token) => `{{${token}}}`)
+                .join(", ")}.`);
+        }
+        return value;
+    });
+}
+function applyRegexRule(content, pattern, version, replacementTemplate) {
     const regex = parseRegexPattern(pattern);
     const matchFlags = regex.flags.includes("g")
         ? regex.flags
         : `${regex.flags}g`;
-    const globalRegex = new RegExp(regex.source, matchFlags);
+    const globalRegex = new RegExp(regex.source, matchFlags.includes("d") ? matchFlags : `${matchFlags}d`);
     const matches = [...content.matchAll(globalRegex)];
     if (matches.length !== 1) {
         throw new Error(`Regex pattern must match exactly one occurrence; matched ${matches.length}.`);
@@ -179,9 +202,21 @@ function applyRegexRule(content, pattern, version) {
         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)}`;
+    // With a replacement template, render it and replace the entire match.
+    if (replacementTemplate !== undefined) {
+        const rendered = renderReplacementTemplate(replacementTemplate, version);
+        return `${content.slice(0, start)}${rendered}${content.slice(start + full.length)}`;
+    }
+    // Legacy behavior: substitute the full version into the first capture group,
+    // leaving the rest of the match intact. Splice by group indices rather than
+    // `String.replace` so literal `$` sequences and repeated group content are
+    // handled correctly.
+    const groupIndices = match.indices?.[1];
+    if (!groupIndices) {
+        return `${content.slice(0, start)}${version}${content.slice(start + full.length)}`;
+    }
+    const [groupStart, groupEnd] = groupIndices;
+    return `${content.slice(0, groupStart)}${version}${content.slice(groupEnd)}`;
 }
 function applyTomlRulePreservingFormatting(content, fieldPath, version) {
     const simplePath = fieldPath.match(/^\$\.([A-Za-z0-9_-]+)$/u);
@@ -368,7 +403,7 @@ function applyArtifactRuleToContent(content, rule, version) {
         if (!rule.pattern) {
             throw new Error('regex artifact rules require "pattern".');
         }
-        return applyRegexRule(content, rule.pattern, version);
+        return applyRegexRule(content, rule.pattern, version, rule.replacement);
     }
     if (rule.type === "json") {
         const parsed = JSON.parse(content);

package/dist/release/plan.js

@@ -50,6 +50,8 @@ export function createReleasePlan(cwd = process.cwd()) {
     const baselineSha = readBaselineSha(cwd) ?? loaded.config["bootstrap-sha"] ?? null;
     const releaseTargetByPath = new Map(readReleaseTargets(cwd).map((target) => [target.path, target]));
     const allowStableMajor = loaded.config["allow-stable-major"] ?? false;
+    const allowStableMajorForPath = (packagePath) => loaded.config.packages?.[packagePath]?.["allow-stable-major"] ??
+        allowStableMajor;
     const monorepoMode = getMode(loaded.config["monorepo-mode"]);
     const buildPackagePlan = (pkg) => {
         const packageContext = resolvePackageStrategyContext(loaded.config, pkg.path, pkg.config);
@@ -78,7 +80,9 @@ export function createReleasePlan(cwd = process.cwd()) {
         const commits = effectiveCommits;
         const releaseType = analyzeParsedCommits(parsedCommits);
         const nextVersion = releaseType
-            ? bumpVersion(packageCurrentVersion, releaseType, { allowStableMajor })
+            ? bumpVersion(packageCurrentVersion, releaseType, {
+                allowStableMajor: allowStableMajorForPath(pkg.path),
+            })
             : null;
         return {
             path: pkg.path,
@@ -198,7 +202,9 @@ export function createReleasePlan(cwd = process.cwd()) {
         return {
             ...pkgPlan,
             releaseType: "patch",
-            nextVersion: bumpVersion(current, "patch", { allowStableMajor }),
+            nextVersion: bumpVersion(current, "patch", {
+                allowStableMajor: allowStableMajorForPath(pkgPlan.path),
+            }),
             bumpReason: "dependency-propagation",
             dependencySourcePaths,
         };
@@ -234,7 +240,9 @@ export function createReleasePlan(cwd = process.cwd()) {
             pkgPlan.bumpReason === undefined;
         const baseVersion = packageCurrentVersionByPath[pkgPlan.path] ?? pkgPlan.currentVersion;
         const nextVersion = combinedReleaseType
-            ? bumpVersion(baseVersion, combinedReleaseType, { allowStableMajor })
+            ? bumpVersion(baseVersion, combinedReleaseType, {
+                allowStableMajor: allowStableMajorForPath(pkgPlan.path),
+            })
             : null;
         return {
             ...pkgPlan,

package/dist/release/pr.js

@@ -435,6 +435,15 @@ export function renderSimpleReviewRequestBody(version, previousVersion, commits,
         }
         return `${bodySections}\n\n${renderReviewRequestFooter()}`;
     }
+    // Honor the plan's changelog format (e.g. r-news) so manual notes, which are
+    // authored/extracted relative to that format's heading depth, render at the
+    // right level. Falling through to renderReleaseNotesSection would always use
+    // the markdown-changelog convention and leave r-news highlights one level too
+    // high relative to the auto-generated sections.
+    if (plan && plan.changelogFormat === "r-news") {
+        const notes = renderReleasePlanChangelog(plan, { cwd, highlights });
+        return `${notes}\n\n${renderReviewRequestFooter()}`;
+    }
     return renderReleaseNotesSection({
         currentVersion: previousVersion,
         nextVersion: version,

package/dist/release/semver.d.ts

@@ -14,14 +14,16 @@ export declare function parseVersion(version: string): ParsedVersion;
 export declare function isValidVersion(version: string): boolean;
 /**
  * Decide whether a changelog heading denotes a released version (e.g.
- * `## [0.28.2](url) (2026-06-02)`, `## 1.2.3`, `## v1.2.3`, `## 0.28.2.9000`)
- * rather than a manual-notes heading (e.g. `## Unreleased`, `## Upcoming`).
+ * `## [0.28.2](url) (2026-06-02)`, `## 1.2.3`, `## v1.2.3`, `## 0.28.2.9000`,
+ * `# pkg 8.0`) rather than a manual-notes heading (e.g. `## Unreleased`,
+ * `## Upcoming`).
  *
  * Intentionally liberal: a heading counts as a version if it contains any
- * version-like token that {@link isValidVersion} accepts. This errs toward
- * "it's a version", so a real release heading is never mistaken for a notes
- * block (and therefore never stripped). Dates such as `2026-06-02` use dashes,
- * not dots, so they never match the three-component token.
+ * version-like token that {@link isValidVersion} accepts, or ends with a bare
+ * `major.minor` token (the R `NEWS.md` convention). This errs toward "it's a
+ * version", so a real release heading is never mistaken for a notes block (and
+ * therefore never stripped). Dates such as `2026-06-02` use dashes, not dots,
+ * so they never match either token.
  */
 export declare function isVersionHeading(heading: string): boolean;
 export declare function compareVersions(leftRaw: string, rightRaw: string): number;

package/dist/release/semver.js

@@ -39,23 +39,30 @@ export function isValidVersion(version) {
     return SEMVER_PATTERN.test(normalizeVersionInput(version));
 }
 const VERSION_TOKEN_PATTERN = /v?(\d+\.\d+\.\d+(?:\.\d+)?)/u;
+// R `NEWS.md` headings conventionally abbreviate to `major.minor` (e.g.
+// `# pkg 8.0`). Accept a bare two-component token only when it is the trailing
+// token of the heading, so genuine R release headings register as versions
+// while prose like `## Notes for 2.0 milestone` does not.
+const TRAILING_MAJOR_MINOR_PATTERN = /\bv?\d+\.\d+\s*$/u;
 /**
  * Decide whether a changelog heading denotes a released version (e.g.
- * `## [0.28.2](url) (2026-06-02)`, `## 1.2.3`, `## v1.2.3`, `## 0.28.2.9000`)
- * rather than a manual-notes heading (e.g. `## Unreleased`, `## Upcoming`).
+ * `## [0.28.2](url) (2026-06-02)`, `## 1.2.3`, `## v1.2.3`, `## 0.28.2.9000`,
+ * `# pkg 8.0`) rather than a manual-notes heading (e.g. `## Unreleased`,
+ * `## Upcoming`).
  *
  * Intentionally liberal: a heading counts as a version if it contains any
- * version-like token that {@link isValidVersion} accepts. This errs toward
- * "it's a version", so a real release heading is never mistaken for a notes
- * block (and therefore never stripped). Dates such as `2026-06-02` use dashes,
- * not dots, so they never match the three-component token.
+ * version-like token that {@link isValidVersion} accepts, or ends with a bare
+ * `major.minor` token (the R `NEWS.md` convention). This errs toward "it's a
+ * version", so a real release heading is never mistaken for a notes block (and
+ * therefore never stripped). Dates such as `2026-06-02` use dashes, not dots,
+ * so they never match either token.
  */
 export function isVersionHeading(heading) {
     const match = heading.match(VERSION_TOKEN_PATTERN);
-    if (!match?.[1]) {
-        return false;
+    if (match?.[1] && isValidVersion(match[1])) {
+        return true;
     }
-    return isValidVersion(match[1]);
+    return TRAILING_MAJOR_MINOR_PATTERN.test(heading);
 }
 function isNumericIdentifier(identifier) {
     return /^(0|[1-9]\d*)$/u.test(identifier);

package/dist/strategy/julia.d.ts

@@ -0,0 +1,2 @@
+import type { VersionStrategy } from "./types.js";
+export declare const juliaVersionStrategy: VersionStrategy;

package/dist/strategy/julia.js

@@ -0,0 +1,115 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseToml } from "smol-toml";
+function parseProjectToml(content, versionFile) {
+    let parsed;
+    try {
+        parsed = parseToml(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to parse ${versionFile}: ${message}`);
+    }
+    if (parsed && typeof parsed === "object") {
+        return parsed;
+    }
+    throw new Error(`Failed to parse ${versionFile}: not a TOML table.`);
+}
+function readProjectVersion(content, versionFile) {
+    const parsed = parseProjectToml(content, versionFile);
+    const version = parsed.version;
+    if (typeof version === "string" && version.trim().length > 0) {
+        return version.trim();
+    }
+    throw new Error(`${versionFile} is missing a valid root "version" field required by release-type "julia".`);
+}
+function writeProjectVersion(rawContent, versionFile, version) {
+    const lineEnding = rawContent.includes("\r\n") ? "\r\n" : "\n";
+    const hasFinalLineEnding = rawContent.endsWith("\n") || rawContent.endsWith("\r\n");
+    const lines = rawContent.split(/\r?\n/u);
+    let activeTable = null;
+    let replaced = false;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? "";
+        const sectionMatch = line.match(/^\s*\[([^\]]+)\]\s*(?:#.*)?$/u);
+        if (sectionMatch) {
+            activeTable = sectionMatch[1]?.trim() ?? null;
+            continue;
+        }
+        // The Julia version is a root key: only match before the first table header.
+        if (activeTable !== null) {
+            continue;
+        }
+        const versionMatch = line.match(/^(\s*version\s*=\s*)(["'])([^"']*)(\2)(\s*(?:#.*)?)?$/u);
+        if (!versionMatch) {
+            continue;
+        }
+        const [, prefix = "", quote = '"', , , suffix = ""] = versionMatch;
+        lines[index] = `${prefix}${quote}${version}${quote}${suffix}`;
+        replaced = true;
+        break;
+    }
+    if (!replaced) {
+        throw new Error(`${versionFile} is missing a valid root "version" field required by release-type "julia".`);
+    }
+    let updated = lines.join(lineEnding);
+    if (hasFinalLineEnding && !updated.endsWith(lineEnding)) {
+        updated += lineEnding;
+    }
+    if (!hasFinalLineEnding && updated.endsWith(lineEnding)) {
+        updated = updated.slice(0, -lineEnding.length);
+    }
+    return updated;
+}
+export const juliaVersionStrategy = {
+    name: "julia",
+    getVersionFile(config) {
+        return config["version-file"] ?? "Project.toml";
+    },
+    validateProject(cwd, config) {
+        const versionFile = this.getVersionFile(config);
+        const versionPath = path.join(cwd, versionFile);
+        if (!fs.existsSync(versionPath)) {
+            return null;
+        }
+        try {
+            readProjectVersion(fs.readFileSync(versionPath, "utf8"), versionFile);
+            return null;
+        }
+        catch (error) {
+            return error instanceof Error ? error.message : String(error);
+        }
+    },
+    readVersion(cwd, config) {
+        const versionFile = this.getVersionFile(config);
+        const versionPath = path.join(cwd, versionFile);
+        if (!fs.existsSync(versionPath)) {
+            throw new Error(`Versionary requires ${versionFile} to exist.`);
+        }
+        return readProjectVersion(fs.readFileSync(versionPath, "utf8"), versionFile);
+    },
+    writeVersion(cwd, config, version) {
+        const versionFile = this.getVersionFile(config);
+        const versionPath = path.join(cwd, versionFile);
+        if (!fs.existsSync(versionPath)) {
+            throw new Error(`Versionary requires ${versionFile} to exist.`);
+        }
+        const existing = fs.readFileSync(versionPath, "utf8");
+        const updated = writeProjectVersion(existing, versionFile, version);
+        fs.writeFileSync(versionPath, updated, "utf8");
+        return [versionFile];
+    },
+    readPackageName(cwd, config) {
+        const versionFile = this.getVersionFile(config);
+        const versionPath = path.join(cwd, versionFile);
+        if (!fs.existsSync(versionPath)) {
+            throw new Error(`Versionary requires ${versionFile} to exist.`);
+        }
+        const parsed = parseProjectToml(fs.readFileSync(versionPath, "utf8"), versionFile);
+        const name = parsed.name;
+        if (typeof name === "string" && name.trim().length > 0) {
+            return name.trim();
+        }
+        return null;
+    },
+};

package/dist/strategy/resolve.js

@@ -1,4 +1,5 @@
 import { compositeVersionStrategy } from "./composite.js";
+import { juliaVersionStrategy } from "./julia.js";
 import { latexVersionStrategy } from "./latex.js";
 import { nodeVersionStrategy } from "./node.js";
 import { pythonVersionStrategy } from "./python.js";
@@ -6,6 +7,7 @@ import { rVersionStrategy } from "./r.js";
 import { rustVersionStrategy } from "./rust.js";
 import { simpleVersionStrategy } from "./simple.js";
 const strategyRegistry = {
+    julia: juliaVersionStrategy,
     latex: latexVersionStrategy,
     simple: simpleVersionStrategy,
     node: nodeVersionStrategy,

package/dist/types/config.d.ts

@@ -7,12 +7,14 @@ export interface VersionaryArtifactRule {
     "field-path"?: string;
     jsonpath?: string;
     pattern?: string;
+    replacement?: string;
 }
 export interface VersionaryPackage {
     "release-type"?: string | string[];
     "package-name"?: string;
     "changelog-file"?: string;
     "changelog-format"?: VersionaryChangelogFormat;
+    "allow-stable-major"?: boolean;
     "exclude-paths"?: string[];
     "extra-files"?: VersionaryArtifactRule[];
     follows?: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "versionary",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "Automatic release framework based on conventional commits and semantic versioning",
   "keywords": [
     "releasing",
@@ -27,27 +27,33 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
-    "smol-toml": "^1.4.2",
     "@octokit/rest": "^22.0.0",
     "jsonc-parser": "^3.3.1",
+    "smol-toml": "^1.4.2",
     "yaml": "^2.8.3",
     "zod": "^4.1.12"
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
+    "@types/node": "^26.0.1",
     "tsx": "^4.20.6",
     "typescript": "^6.0.3",
+    "vite": "^8.0.0",
+    "vitepress": "^1.6.4",
     "vitest": "^4.1.4"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
+    "gen:schema": "tsx scripts/generate-schema.ts && biome format --write schemas/config.json",
     "test": "vitest run",
     "verify": "tsx src/cli/index.ts verify",
     "run": "tsx src/cli/index.ts run",
     "plan": "tsx src/cli/index.ts plan",
     "changelog": "tsx src/cli/index.ts changelog",
     "pr": "tsx src/cli/index.ts pr",
-    "release": "tsx src/cli/index.ts release"
+    "release": "tsx src/cli/index.ts release",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   }
 }