rman 1.0.8 → 1.0.10

package/rmanrc.schema.json

@@ -11,7 +11,12 @@
     },
     "packageManager": {
       "type": "string",
-      "enum": ["npm", "yarn", "pnpm", "bun"],
+      "enum": [
+        "npm",
+        "yarn",
+        "pnpm",
+        "bun"
+      ],
       "default": "npm",
       "description": "Package manager used by \"ci\"/\"publish\". Root-level only - an explicit --package-manager CLI flag wins over this."
     },
@@ -31,7 +36,15 @@
     "group": {
       "description": "Release-versioning group for \"version\"/\"publish\": true (default) puts the package in the implicit repo-wide group; a string joins exactly the other packages sharing that string; false makes it a solo, fully independent group. Per-package cascaded.",
       "default": true,
-      "oneOf": [{ "type": "boolean" }, { "type": "string", "minLength": 1 }]
+      "oneOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "string",
+          "minLength": 1
+        }
+      ]
     },
     "version": {
       "type": "object",
@@ -43,6 +56,16 @@
           "default": "chore(release): v{version}",
           "description": "Commit message for every group a \"version\" run commits. \"{version}\" is substituted when every bumped package in that commit shares one version. Root-level only."
         },
+        "changelog": {
+          "type": "boolean",
+          "default": false,
+          "description": "Default for \"version --changelog\" when the CLI flag isn't given - an explicit --changelog/--no-changelog still wins. Root-level only."
+        },
+        "releaseTagPattern": {
+          "type": "string",
+          "default": "release-*",
+          "description": "Root-level. Tag naming the repository's own release, as opposed to the per-package/group tags \"changelog.tagPattern\" names - only created when the root is on a calendar version (a repo with more than one version line). Must NOT match any package's \"changelog.tagPattern\", or that package's changelog boundary resolves to the repository release instead of its own."
+        },
         "script": {
           "$ref": "#/definitions/stringOrStringArray",
           "description": "Command(s) to run as this package's own \"version\" npm-lifecycle step, when its package.json does not define one itself."
@@ -64,7 +87,9 @@
       "properties": {
         "ignoreTypes": {
           "type": "array",
-          "items": { "type": "string" },
+          "items": {
+            "type": "string"
+          },
           "default": [],
           "description": "Conventional Commit types (e.g. \"chore\", \"ci\") dropped entirely from changelog output, instead of being folded into \"Other Changes\". Per-package cascaded."
         },
@@ -110,11 +135,20 @@
       "additionalProperties": false,
       "properties": {
         "target": {
-          "description": "Which registries \"publish\" targets for this package. Default [\"npm\"]. A package that only ships Docker images (typically also \"private\": true) sets [\"docker\"]; one that publishes both sets [\"npm\", \"docker\"].",
-          "default": ["npm"],
+          "description": "Which registry \"publish\" ships this package to. Default [\"npm\"]. A package that only ships Docker images (typically also \"private\": true) sets [\"docker\"]; both works too. Each target answers \"is this version already out there?\" against its own registry: npm via \"npm view\", docker via \"docker manifest inspect\". This is strictly about package distribution - the repository's GitHub Release is not a target here, see \"githubRelease\" and the \"github-release\" command.",
+          "default": [
+            "npm"
+          ],
           "oneOf": [
-            { "$ref": "#/definitions/publishTarget" },
-            { "type": "array", "items": { "$ref": "#/definitions/publishTarget" } }
+            {
+              "$ref": "#/definitions/publishTarget"
+            },
+            {
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/publishTarget"
+              }
+            }
           ]
         },
         "docker": {
@@ -124,14 +158,20 @@
         "skip": {
           "type": "boolean",
           "default": false,
-          "description": "Excludes this package from \"publish\" entirely (npm and docker both), regardless of \"target\"/\"private\" - a single, explicit \"never published\" statement. \"changelog\" also skips it by default (see its own --include-skipped). Independent of \"version\", which never consults this."
+          "description": "Excludes this package from \"publish\" entirely (every target), regardless of \"target\"/\"private\" - a single, explicit \"never published\" statement. \"changelog\" also skips it by default (see its own --include-skipped). Independent of \"version\", which never consults this."
         }
       }
     },
+    "githubRelease": {
+      "$ref": "#/definitions/githubReleaseConfig",
+      "description": "Details of the repository's GitHub Release (\"github-release\"/GithubReleaseService). Entirely optional - every required fact already has a sensible default source. Nothing here decides whether a release is cut: a release records that the repository shipped, so it is always cut. \"assets\" is per-package cascaded; the rest is root-level only."
+    },
     "run": {
       "type": "object",
       "description": "Per-script options for \"run\"/\"build\"/\"test\"/RunService, keyed by npm script name (e.g. \"build\", \"lint\", \"test\").",
-      "additionalProperties": { "$ref": "#/definitions/runScriptConfig" }
+      "additionalProperties": {
+        "$ref": "#/definitions/runScriptConfig"
+      }
     },
     "packages": {
       "type": "object",
@@ -143,8 +183,18 @@
           "dependencies": {
             "description": "Extra in-repo \"dependencies\" not present in this package's real package.json, purely for rman's own dependency graph (topo-sort, --deps/--dependents, run's task scheduling). An array defaults each entry's range to \"*\"; an object gives an explicit name -> range map.",
             "oneOf": [
-              { "type": "array", "items": { "type": "string" } },
-              { "type": "object", "additionalProperties": { "type": "string" } }
+              {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "string"
+                }
+              }
             ]
           }
         }
@@ -154,22 +204,41 @@
   "definitions": {
     "logLevel": {
       "type": "string",
-      "enum": ["silent", "error", "info", "verbose"]
+      "enum": [
+        "silent",
+        "error",
+        "info",
+        "verbose"
+      ]
     },
     "stringOrStringArray": {
       "oneOf": [
-        { "type": "string", "minLength": 1 },
-        { "type": "array", "items": { "type": "string", "minLength": 1 } }
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
       ]
     },
     "publishTarget": {
       "type": "string",
-      "enum": ["npm", "docker"]
+      "enum": [
+        "npm",
+        "docker"
+      ]
     },
     "dockerPublishConfig": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["image"],
+      "required": [
+        "image"
+      ],
       "properties": {
         "image": {
           "type": "string",
@@ -183,8 +252,12 @@
         },
         "platforms": {
           "type": "array",
-          "items": { "type": "string" },
-          "default": ["linux/amd64"],
+          "items": {
+            "type": "string"
+          },
+          "default": [
+            "linux/amd64"
+          ],
           "description": "\"docker buildx build --platform\" targets."
         },
         "cwd": {
@@ -193,12 +266,16 @@
         },
         "buildContexts": {
           "type": "object",
-          "additionalProperties": { "type": "string" },
+          "additionalProperties": {
+            "type": "string"
+          },
           "description": "Named \"docker buildx build --build-context <name>=<path>\" entries, keyed by name - each path relative to the package's own directory (or absolute)."
         },
         "buildArgs": {
           "type": "object",
-          "additionalProperties": { "type": "string" },
+          "additionalProperties": {
+            "type": "string"
+          },
           "description": "\"docker buildx build --build-arg <name>=<value>\" entries - a value of exactly \"$NAME\" expands to the NAME environment variable at build time."
         },
         "readme": {
@@ -208,6 +285,32 @@
         }
       }
     },
+    "githubReleaseConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "assets": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Files to attach to the release, as glob patterns relative to the package's own directory (e.g. [\"dist/*.tar.gz\"]). Read from every package, since one release covers the whole source tree. A release with no assets is still valid."
+        },
+        "repository": {
+          "type": "string",
+          "description": "\"owner/repo\". Default: parsed from the \"origin\" remote's URL."
+        },
+        "draft": {
+          "type": "boolean",
+          "default": false,
+          "description": "Create the release as an unpublished draft."
+        },
+        "prerelease": {
+          "type": "boolean",
+          "description": "Default: whether the version being released is itself a semver prerelease."
+        }
+      }
+    },
     "runScriptConfig": {
       "type": "object",
       "additionalProperties": false,

package/services/changelog.service.d.ts

@@ -11,10 +11,11 @@ export declare namespace ChangelogService {
     interface Options extends PackageFilterOptions {
         /** Generate the changelog since this commit/hash - applied the same way to every package.
          *  Default (also `"npm"` explicitly): auto-detect it per package instead, from that package's
-         *  currently-published npm version (see `detectChangeHash`); a package this can't be resolved
-         *  for (unpublished, no network, no matching tag) falls back to its own commits not yet
-         *  pushed to the current branch's upstream (same reference point `--changed`/
-         *  `--changed-since` use). */
+         *  own most recent release tag first - the same lookup `VersionService`/`changed` use, so this
+         *  never disagrees with them - falling back to its currently-published npm version only when
+         *  it has no tag yet (see `detectChangeHash`); a package this can't be resolved for either way
+         *  (never tagged, unpublished, no network) has never been released at all, so its whole
+         *  history counts as unreleased - the same view `version` takes. */
         from?: string;
         /** Generate for the whole repository even when the current directory is inside a single
          *  package (which otherwise scopes it to just that package) - see `Repository.currentPackage`. */
@@ -31,6 +32,14 @@ export declare namespace ChangelogService {
         /** A package with `.rmanrc "publish.skip"` is excluded by default - little point changelogging
          *  something that's never actually released. Set true to generate for it anyway. */
         includeSkipped?: boolean;
+        /** The version these entries are being generated *for* - what `{{version}}` renders as.
+         *  Without it the version is read back from git tags (see `resolveVersion`), which is only
+         *  correct once the release being described has actually been tagged. A caller generating
+         *  notes for a release that doesn't exist yet - `version --changelog` writing the entry before
+         *  it commits and tags, or a CI step producing release notes ahead of the bump - already knows
+         *  the number and has to say so, otherwise every entry ends up labelled with the *previous*
+         *  release's version. */
+        version?: string;
     }
     /** One package's (root included) generated changelog entry - what `getEntries`/`generate`
      *  return. */
@@ -39,7 +48,8 @@ export declare namespace ChangelogService {
         /** Display name for this entry's heading - `"<repo dir name> repository"` for the root
          *  package, its own name otherwise (see `getEntries`'s doc comment on `{{package}}`). */
         label: string;
-        /** Resolved from git tags, not package.json - see `resolveVersion`. */
+        /** `options.version` when the caller gave one, otherwise resolved from git tags rather than
+         *  package.json - see `resolveVersion`. */
         version: string;
         features: string[];
         fixes: string[];
@@ -71,16 +81,15 @@ export declare namespace ChangelogService {
      * Fixes/🔧 Other Changes on a best-effort Conventional Commits read; anything that doesn't parse
      * just lands in Other Changes as-is, so a repo that doesn't follow that convention still gets a
      * usable list. `.rmanrc changelog.ignoreTypes` (cascaded, e.g. `[chore, dev]`) drops commits of
-     * those types entirely instead - see `ignoreTypesConfig`. A bare version-bump commit
-     * (`"6.0.1"`) is always dropped outright, regardless of `ignoreTypes` - see
-     * `VERSION_BUMP_PATTERN`.
+     * those types entirely instead - see `ignoreTypesConfig`. A release marker - a bare version-bump
+     * commit (`"6.0.1"`), or any of the messages `version` itself writes - is always dropped
+     * outright, regardless of `ignoreTypes`; see `isReleaseCommit`.
      *
      * By default (or with `--from npm` explicitly), the boundary is auto-detected per package
      * instead of one shared one - see `detectChangeHash`. A package that can't be resolved this way
-     * (unpublished, no network, no matching tag) falls back to its own commits not yet pushed to
-     * the current branch's upstream (the same reference point `--changed`/`--changed-since` use
-     * elsewhere, via `GitHelper.listCommits`) - so the command still produces something useful even
-     * for a repo that's never been published or tagged at all. Packages that end up resolving to
+     * (unpublished, no network, no matching tag) has never been released at all, so its whole
+     * history counts as unreleased - the same view `version` takes, so a first-ever release still
+     * produces a real changelog. Packages that end up resolving to
      * the same hash (an explicit one, or several packages sharing one tag under fixed versioning)
      * only have their commits fetched once, not once per package.
      *

package/services/changelog.service.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { detectChangeHash, extractVersion, findLatestTag, tagPattern } from '../utils/change-hash.js';
-import { parseConventionalCommit, VERSION_BUMP_PATTERN } from '../utils/conventional-commits.js';
+import { isReleaseCommit, parseConventionalCommit } from '../utils/conventional-commits.js';
 import { GitHelper } from '../utils/git.js';
 import { filterPackages } from '../utils/package-filter.js';
 export var ChangelogService;
@@ -33,16 +33,15 @@ export var ChangelogService;
      * Fixes/🔧 Other Changes on a best-effort Conventional Commits read; anything that doesn't parse
      * just lands in Other Changes as-is, so a repo that doesn't follow that convention still gets a
      * usable list. `.rmanrc changelog.ignoreTypes` (cascaded, e.g. `[chore, dev]`) drops commits of
-     * those types entirely instead - see `ignoreTypesConfig`. A bare version-bump commit
-     * (`"6.0.1"`) is always dropped outright, regardless of `ignoreTypes` - see
-     * `VERSION_BUMP_PATTERN`.
+     * those types entirely instead - see `ignoreTypesConfig`. A release marker - a bare version-bump
+     * commit (`"6.0.1"`), or any of the messages `version` itself writes - is always dropped
+     * outright, regardless of `ignoreTypes`; see `isReleaseCommit`.
      *
      * By default (or with `--from npm` explicitly), the boundary is auto-detected per package
      * instead of one shared one - see `detectChangeHash`. A package that can't be resolved this way
-     * (unpublished, no network, no matching tag) falls back to its own commits not yet pushed to
-     * the current branch's upstream (the same reference point `--changed`/`--changed-since` use
-     * elsewhere, via `GitHelper.listCommits`) - so the command still produces something useful even
-     * for a repo that's never been published or tagged at all. Packages that end up resolving to
+     * (unpublished, no network, no matching tag) has never been released at all, so its whole
+     * history counts as unreleased - the same view `version` takes, so a first-ever release still
+     * produces a real changelog. Packages that end up resolving to
      * the same hash (an explicit one, or several packages sharing one tag under fixed versioning)
      * only have their commits fetched once, not once per package.
      *
@@ -65,9 +64,10 @@ export var ChangelogService;
         const packages = repository.getPackages().filter(p => p !== repository.rootPackage);
         const targets = (cwdScope ? [cwdScope] : filterPackages([repository.rootPackage, ...packages], options)).filter(pkg => options.includeSkipped || !pkg.config.publish?.skip);
         const git = new GitHelper({ cwd: repository.dirname });
-        // dropped up front, not just while grouping - a package whose only commits are version bumps
+        const commitMessage = repository.rootPackage.config?.version?.commitMessage;
+        // dropped up front, not just while grouping - a package whose only commits are release markers
         // should get no entry at all, rather than a heading with nothing real underneath it.
-        const dropVersionBumps = (commits) => commits.filter(c => !VERSION_BUMP_PATTERN.test(c.subject));
+        const dropVersionBumps = (commits) => commits.filter(c => !isReleaseCommit(c.subject, commitMessage));
         // Several packages often resolve to the identical hash (an explicit --from <hash> applies to
         // all of them the same way; under fixed versioning, npm auto-detection usually does too) - so
         // the git fetch for a given hash is cached, run once no matter how many packages share it.
@@ -76,7 +76,10 @@ export var ChangelogService;
             const key = hash ?? '';
             let promise = commitsByHash.get(key);
             if (!promise) {
-                promise = git.listCommits({ hash }).then(dropVersionBumps);
+                // No boundary at all means nothing has ever been released, so everything so far is
+                // unreleased - the same fallback `VersionService` makes. (Not "not yet pushed": that reads
+                // as empty the moment a first release is pushed, and for a repo with no remote at all.)
+                promise = (hash ? git.listCommits({ hash }) : git.listAllCommits()).then(dropVersionBumps);
                 commitsByHash.set(key, promise);
             }
             return promise;
@@ -102,7 +105,7 @@ export var ChangelogService;
             if (!grouped.features.length && !grouped.fixes.length && !grouped.other.length)
                 continue;
             const label = pkg === repository.rootPackage ? `${path.basename(repository.dirname)} repository` : pkg.name;
-            const { version, content } = await renderEntry(repository, pkg, label, grouped, git);
+            const { version, content } = await renderEntry(repository, pkg, label, grouped, git, options.version);
             entries.push({
                 package: pkg,
                 label,
@@ -129,8 +132,6 @@ function ignoreTypesConfig(pkg) {
 function groupCommits(subjects, ignoreTypes = new Set()) {
     const grouped = { features: [], fixes: [], other: [] };
     for (const subject of subjects) {
-        if (VERSION_BUMP_PATTERN.test(subject))
-            continue;
         const parsed = parseConventionalCommit(subject);
         if (!parsed) {
             grouped.other.push(subject);
@@ -244,9 +245,9 @@ function ownersOf(repository, commit) {
     }
     return owners;
 }
-async function renderEntry(repository, pkg, label, grouped, git) {
+async function renderEntry(repository, pkg, label, grouped, git, versionOverride) {
     const template = resolveTemplate(repository, pkg);
-    const version = await resolveVersion(git, pkg);
+    const version = versionOverride ?? (await resolveVersion(git, pkg));
     const content = render(template, {
         package: label,
         version,

package/services/github-release.service.d.ts

@@ -0,0 +1,69 @@
+import type { Package } from '../core/package.js';
+import type { Repository } from '../core/repository.js';
+export declare namespace GithubReleaseService {
+    /** Injectable "does this release already exist" check - mainly for tests, so they don't depend
+     *  on network access or a real GitHub token. Same shape as `DockerPublishService.Deps`' own
+     *  `imageExists`. */
+    interface Deps {
+        releaseExists?: (repository: string, tag: string) => Promise<boolean>;
+    }
+    interface Options {
+        /** Uncommitted local changes anywhere in the repository make the release `'skip'` instead of
+         *  `'error'` - same as `version`/`publish`'s other targets. */
+        ignoreDirty?: boolean;
+        /** `owner/repo` override - otherwise the root's own `githubRelease.repository`, falling back
+         *  to the `origin` remote's URL. */
+        repository?: string;
+    }
+    /** The repository's release outcome - see `getPlan`. At most one of these: a GitHub Release
+     *  belongs to the repository, not to a package. */
+    interface Entry {
+        /** Always the repository root - a release covers the whole source tree, not one package. */
+        package: Package;
+        /** The repository's own release version (see `buildRootEntry`). */
+        version: string;
+        status: 'publish' | 'skip' | 'up-to-date' | 'error';
+        /** The tag this release belongs to - the repository release tag on a calendar version, the
+         *  single shared version's tag otherwise. */
+        tag?: string;
+        /** `owner/repo` this release lands in - unset only when it couldn't be resolved (an `'error'`). */
+        repository?: string;
+        reason?: string;
+    }
+    /**
+     * Computes what `github-release` *would* do - **one** release per run.
+     *
+     * A GitHub Release is a property of the repository, not of a package: the tag covers the whole
+     * source tree, so everything that shipped under it belongs in it. There is deliberately **no
+     * opt-in**: it isn't a place a package ships to (that's `publish.target`, which is about
+     * registries - npm, Docker Hub, GitHub Packages), it's the repository's own record that a
+     * release happened, and a repository always wants that record. Re-running is harmless - an
+     * existing release for the tag reads `'up-to-date'`.
+     *
+     * The release is identified by the repository's own version (the root's - see
+     * `VersionService`'s `buildRootEntry`): its release tag when that version is a calendar one, and
+     * otherwise the tag of the single shared version, which is the group's own tag - so a repo with
+     * one version line gets no second name for the release it already has. Whether a release exists
+     * for that tag decides `'up-to-date'` vs `'publish'`.
+     *
+     * Uncommitted changes anywhere make it `'error'` unless `options.ignoreDirty` downgrades it to
+     * `'skip'`. An unresolvable `owner/repo`, or a lookup that fails for any reason other than "no
+     * such release", is `'error'` too - a blocking misconfiguration rather than a silent "not
+     * released yet" that only fails later.
+     */
+    function getPlan(repository: Repository, options?: Options, deps?: Deps): Promise<Entry[]>;
+    /**
+     * Creates the repository's GitHub Release, then uploads whatever `githubRelease.assets` globs
+     * match, across every package. The body covers **every** package that shipped under this
+     * release, since the tag covers all of their code either way.
+     *
+     * Each package's notes are bounded by the *previous repository release*, and headed with that
+     * package's own version, so a repo whose packages sit on different version lines still reads
+     * correctly. A package with nothing in that range simply contributes no section, which is also
+     * how a package that didn't ship in this release is left out - no ancestry arithmetic needed.
+     *
+     * An existing release for the tag is updated rather than treated as a failure, so a re-run after
+     * a partial failure converges.
+     */
+    function applyPlan(repository: Repository, plan: Entry[]): Promise<Entry[]>;
+}