rman 1.0.8 → 1.0.9

package/utils/change-hash.js

@@ -20,6 +20,22 @@ export async function findLatestTag(git, pkg) {
     const expanded = pattern.replace('{name}', pkg.name);
     return pattern.includes('{name}') ? (await git.listTags(expanded))[0] : await git.describeTag(expanded);
 }
+/** The forward direction of `findLatestTag`: expands `pkg`'s (cascaded) `.rmanrc
+ *  changelog.tagPattern` into the concrete tag name `version` belongs under - `{name}` becomes the
+ *  package's own name, `*` becomes `version`. Shared by `version` (creating the tag), `publish
+ *  --target github` (finding the release that tag belongs to), and `detectChangeHash`'s own npm
+ *  fallback (mapping a published version back onto a tag), so all three name tags identically. */
+export function expandTag(pkg, version) {
+    return applyTagPattern(tagPattern(pkg), pkg.name, version);
+}
+/** The pattern expansion `expandTag` performs, on any pattern - `{name}` becomes `name`, `*` becomes
+ *  `version`. Shared with the repository's own release tag, which uses a different pattern (see
+ *  `releaseTagPattern`) but names tags the same way. */
+export function applyTagPattern(pattern, name, version) {
+    const expanded = pattern.replace('{name}', name);
+    const starIdx = expanded.indexOf('*');
+    return starIdx === -1 ? expanded : expanded.slice(0, starIdx) + version + expanded.slice(starIdx + 1);
+}
 /** Strips the pattern's literal prefix (everything before its first `*`) from `tag` to get just
  *  the version part - e.g. tag `@sqb/builder@1.2.3` against pattern `@sqb/builder@*` -> `1.2.3`.
  *  A pattern with no `*` is returned as its own "version" verbatim (an exact tag, nothing to strip). */
@@ -47,40 +63,36 @@ export async function defaultNpmViewVersion(name, cwd) {
  * Resolves the commit/hash a package's changes should be measured "since" - the boundary
  * `changelog --from` uses, but reusable anywhere a command wants to answer "what changed for this
  * package". An explicit `options.from` (anything but `"npm"`) is returned as-is, applying the same
- * way to every package. Otherwise, it's auto-detected in order: (1) the package's
- * currently-published npm version - looked up via `npmViewVersion`, then mapped to a git tag using
- * `.rmanrc changelog.tagPattern` (so independent and fixed monorepo versioning schemes both work -
- * see `tagPattern`); (2) failing that (never published, private, no network, ...), this package's
- * own most recent release tag directly - the same `findLatestTag` lookup `version` itself uses, so
- * a package that's never been on npm (e.g. Docker-only) but has real tags from a previous `version`
- * run still gets a correct boundary, not just "everything ever". Either way, if `catchUpFile` is
- * given and exists, the result is widened to also cover anything that file hasn't caught up on yet
- * (see its doc comment). Returns `undefined` when nothing can be resolved at all (never published
- * *and* never tagged, no catch-up file - a genuinely first-ever release) - callers should fall back
- * to their own default in that case (e.g. `GitHelper.listCommits`'s "not yet pushed" default when
- * no hash is given).
+ * way to every package. Otherwise, it's auto-detected in order: (1) this package's own most recent
+ * release tag - the same network-free `findLatestTag` lookup `version`/`changed` themselves use,
+ * so all three commands agree on "since when" for any repo whose tags are the ones `rman version`
+ * actually created; (2) failing that (no tag at all yet - e.g. onboarding `rman` onto a repo with
+ * real npm history but no `rman`-created tags), the package's currently-published npm version -
+ * looked up via `npmViewVersion`, then mapped to a git tag using `.rmanrc changelog.tagPattern`
+ * (see `tagPattern`). Either way, if `catchUpFile` is given and exists, the result is widened to
+ * also cover anything that file hasn't caught up on yet (see its doc comment). Returns `undefined`
+ * when nothing can be resolved at all (never tagged *and* never published, no catch-up file - a
+ * genuinely first-ever release) - callers should fall back to their own default in that case (e.g.
+ * the whole history, since nothing has ever been released).
  */
 export async function detectChangeHash(git, pkg, options = {}) {
     if (options.from && options.from !== 'npm')
         return options.from;
-    const npmViewVersion = options.npmViewVersion ?? defaultNpmViewVersion;
-    const publishedVersion = await npmViewVersion(pkg.name, git.cwd);
-    let npmHash;
-    if (publishedVersion) {
-        const pattern = tagPattern(pkg);
-        const expanded = pattern.replace('{name}', pkg.name);
-        const starIdx = expanded.indexOf('*');
-        const tag = starIdx === -1 ? expanded : expanded.slice(0, starIdx) + publishedVersion + expanded.slice(starIdx + 1);
-        npmHash = (await git.tagExists(tag)) ? tag : undefined;
+    let tagHash = await findLatestTag(git, pkg);
+    if (!tagHash) {
+        const npmViewVersion = options.npmViewVersion ?? defaultNpmViewVersion;
+        const publishedVersion = await npmViewVersion(pkg.name, git.cwd);
+        if (publishedVersion) {
+            const tag = expandTag(pkg, publishedVersion);
+            tagHash = (await git.tagExists(tag)) ? tag : undefined;
+        }
     }
-    if (!npmHash)
-        npmHash = await findLatestTag(git, pkg);
     const fileHash = options.catchUpFile ? await git.lastCommitTouching(options.catchUpFile) : undefined;
     if (!fileHash)
-        return npmHash;
-    if (!npmHash)
+        return tagHash;
+    if (!tagHash)
         return fileHash;
-    return (await git.mergeBase(npmHash, fileHash)) ?? npmHash;
+    return (await git.mergeBase(tagHash, fileHash)) ?? tagHash;
 }
 const execFileAsync = promisify(execFile);
 const DEFAULT_TAG_PATTERN = 'v*';

package/utils/conventional-commits.d.ts

@@ -10,6 +10,19 @@ export declare const CONVENTIONAL_PATTERN: RegExp;
  *  not a real change worth describing (or worth bumping a version over on its own), so it's
  *  dropped everywhere a real change is being looked for. */
 export declare const VERSION_BUMP_PATTERN: RegExp;
+/**
+ * Whether `subject` is a release marker rather than a real change - dropped everywhere real
+ * changes are looked for (changelog entries, and what counts as "changed" for a version bump).
+ *
+ * Covers the bare-version form other tools use (`VERSION_BUMP_PATTERN`) plus every message shape
+ * `version` itself writes: its commit message (`commitMessageTemplate`, or the built-in
+ * `"chore(release): v{version}"` when a repo doesn't override it), the multi-version form that
+ * template falls back to when one commit spans several versions (`chore(release): a@1.2.0,
+ * b@1.3.0`), and the monorepo root's own version-sync commit. Without this, rman's own release
+ * commits show up in the changelogs it generates - visible whenever the boundary reaches back past
+ * a previous release (see `detectChangeHash`'s `catchUpFile`).
+ */
+export declare function isReleaseCommit(subject: string, commitMessageTemplate?: string): boolean;
 export interface ParsedCommitSubject {
     type: string;
     scope?: string;

package/utils/conventional-commits.js

@@ -10,6 +10,32 @@ export const CONVENTIONAL_PATTERN = /^(\w+)(\(([^)]+)\))?(!)?:\s*(.+)$/;
  *  not a real change worth describing (or worth bumping a version over on its own), so it's
  *  dropped everywhere a real change is being looked for. */
 export const VERSION_BUMP_PATTERN = /^v?\d+\.\d+\.\d+(?:[-+][\w.]+)?$/;
+/**
+ * Whether `subject` is a release marker rather than a real change - dropped everywhere real
+ * changes are looked for (changelog entries, and what counts as "changed" for a version bump).
+ *
+ * Covers the bare-version form other tools use (`VERSION_BUMP_PATTERN`) plus every message shape
+ * `version` itself writes: its commit message (`commitMessageTemplate`, or the built-in
+ * `"chore(release): v{version}"` when a repo doesn't override it), the multi-version form that
+ * template falls back to when one commit spans several versions (`chore(release): a@1.2.0,
+ * b@1.3.0`), and the monorepo root's own version-sync commit. Without this, rman's own release
+ * commits show up in the changelogs it generates - visible whenever the boundary reaches back past
+ * a previous release (see `detectChangeHash`'s `catchUpFile`).
+ */
+export function isReleaseCommit(subject, commitMessageTemplate) {
+    if (VERSION_BUMP_PATTERN.test(subject))
+        return true;
+    if (ROOT_SYNC_PATTERN.test(subject))
+        return true;
+    if (MULTI_VERSION_RELEASE_PATTERN.test(subject))
+        return true;
+    // The built-in message is checked even when a repo overrides it: the override only applies to
+    // commits spanning a single version (see `buildCommitMessage`), and a repo that adopted one later
+    // still has older releases committed under the default.
+    if (templatePattern(DEFAULT_COMMIT_MESSAGE).test(subject))
+        return true;
+    return !!commitMessageTemplate && templatePattern(commitMessageTemplate).test(subject);
+}
 /** Parses a commit subject as Conventional Commits, or `undefined` if it doesn't match at all
  *  (a non-conventional message - still a real change, just with no `type` to key off of). */
 export function parseConventionalCommit(subject) {
@@ -26,6 +52,27 @@ export function parseConventionalCommit(subject) {
 export function hasBreakingChangeFooter(body) {
     return /^BREAKING[ -]CHANGE:/im.test(body);
 }
+/** A semver version, as it appears inside a commit subject - the `\d+\.\d+\.\d+` core of
+ *  `VERSION_BUMP_PATTERN`, reusable inside the larger patterns below. */
+const SEMVER_SOURCE = String.raw `\d+\.\d+\.\d+(?:[-+][\w.]+)?`;
+/** Mirrors `VersionService`'s own default `version.commitMessage` - kept in sync by
+ *  `version.command.ts`'s documented default, not imported, to keep this module dependency-free. */
+const DEFAULT_COMMIT_MESSAGE = 'chore(release): v{version}';
+/** `VersionService.applyPlan`'s trailing commit for a monorepo root's informational version. */
+const ROOT_SYNC_PATTERN = new RegExp(String.raw `^chore: sync root version to ${SEMVER_SOURCE}$`);
+/** What the commit-message template falls back to when one commit covers several versions at once
+ *  (a cross-group ripple) - `{version}` has nothing single to substitute, so each bumped package is
+ *  listed by name instead. */
+const MULTI_VERSION_RELEASE_PATTERN = new RegExp(String.raw `^chore\(release\): \S+@${SEMVER_SOURCE}(?:, \S+@${SEMVER_SOURCE})*$`);
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Turns a `version.commitMessage` template into a matcher for the commits it produces: every
+ *  literal part escaped, each `{version}` placeholder standing in for any semver. */
+function templatePattern(template) {
+    const source = template.split('{version}').map(escapeRegExp).join(SEMVER_SOURCE);
+    return new RegExp(`^${source}$`);
+}
 /**
  * A `Release-As: patch|minor|major` footer in a commit `body` - lets that one commit's own
  * contribution to a detected bump severity be overridden by hand, regardless of what its subject

package/utils/git.d.ts

@@ -57,7 +57,11 @@ export declare class GitHelper {
     /** The most recent tag matching the glob `pattern` that HEAD actually descends from (unlike
      *  `listTags`, this follows commit ancestry rather than just sorting tag names - the right
      *  choice for a single repo-wide tag scheme, where a package has no tag of its own). */
-    describeTag(pattern: string): Promise<string | undefined>;
+    describeTag(pattern: string, ref?: string): Promise<string | undefined>;
+    /** The repository's very first commit (the oldest root commit, for a history with several) -
+     *  `undefined` for a repository with no commits at all. The "since the beginning" boundary for
+     *  a package being released for the first time, with no earlier tag to measure from. */
+    rootCommit(): Promise<string | undefined>;
     /** Stages and commits exactly `files` (relative to `cwd`, or absolute) with `message` - never a
      *  blanket `git add -A`, so the commit only ever contains what the caller explicitly asked for. */
     commit(files: string[], message: string): Promise<void>;
@@ -71,6 +75,9 @@ export declare class GitHelper {
         remote?: string;
         tags?: boolean;
     }): Promise<void>;
+    /** `git remote get-url <remote>` (default `"origin"`) - `undefined` when that remote isn't
+     *  configured at all, which is a perfectly normal state for a local-only repository. */
+    remoteUrl(remote?: string): Promise<string | undefined>;
     /** Raw `git diff <hash>..HEAD` text (committed changes plus any uncommitted local ones, same as
      *  plain `git diff <hash>`) - unlike `listChangedSince`, the actual patch content, not just
      *  which files changed. `pathspec`, if given, narrows it to just that file/directory. */

package/utils/git.js

@@ -183,9 +183,9 @@ export class GitHelper {
     /** The most recent tag matching the glob `pattern` that HEAD actually descends from (unlike
      *  `listTags`, this follows commit ancestry rather than just sorting tag names - the right
      *  choice for a single repo-wide tag scheme, where a package has no tag of its own). */
-    async describeTag(pattern) {
+    async describeTag(pattern, ref = 'HEAD') {
         try {
-            const { stdout } = await execFileAsync('git', ['describe', '--tags', '--abbrev=0', '--match', pattern], {
+            const { stdout } = await execFileAsync('git', ['describe', '--tags', '--abbrev=0', '--match', pattern, ref], {
                 cwd: this.cwd,
             });
             return stdout.trim() || undefined;
@@ -194,6 +194,19 @@ export class GitHelper {
             return undefined;
         }
     }
+    /** The repository's very first commit (the oldest root commit, for a history with several) -
+     *  `undefined` for a repository with no commits at all. The "since the beginning" boundary for
+     *  a package being released for the first time, with no earlier tag to measure from. */
+    async rootCommit() {
+        try {
+            const { stdout } = await execFileAsync('git', ['rev-list', '--max-parents=0', 'HEAD'], { cwd: this.cwd });
+            const shas = stdout.trim().split(/\r?\n/).filter(Boolean);
+            return shas[shas.length - 1] || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
     /** Stages and commits exactly `files` (relative to `cwd`, or absolute) with `message` - never a
      *  blanket `git add -A`, so the commit only ever contains what the caller explicitly asked for. */
     async commit(files, message) {
@@ -229,6 +242,17 @@ export class GitHelper {
             throw new Error(`Unable to push to "${remote}": ${e.message}`, { cause: e });
         }
     }
+    /** `git remote get-url <remote>` (default `"origin"`) - `undefined` when that remote isn't
+     *  configured at all, which is a perfectly normal state for a local-only repository. */
+    async remoteUrl(remote = 'origin') {
+        try {
+            const { stdout } = await execFileAsync('git', ['remote', 'get-url', remote], { cwd: this.cwd });
+            return stdout.trim() || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
     /** Raw `git diff <hash>..HEAD` text (committed changes plus any uncommitted local ones, same as
      *  plain `git diff <hash>`) - unlike `listChangedSince`, the actual patch content, not just
      *  which files changed. `pathspec`, if given, narrows it to just that file/directory. */

package/utils/release-version.d.ts

@@ -0,0 +1,50 @@
+import type { Package } from '../core/package.js';
+import type { GitHelper } from './git.js';
+/**
+ * A calendar release version: `YYYY.M.D-HHmm`, every part **unpadded** (`2026.9.5-930`, not
+ * `2026.09.05-0930`). The padding isn't a style choice - semver forbids leading zeroes in numeric
+ * identifiers, so a padded month or time makes the version invalid, and a monorepo root's
+ * `package.json` has to hold a valid one. Unpadded still orders correctly: the date parts compare
+ * numerically as major/minor/patch, and the time compares numerically as a prerelease identifier
+ * (`930` < `1430`).
+ */
+export declare const CALENDAR_VERSION_PATTERN: RegExp;
+/** `.rmanrc version.releaseTagPattern` (root-level) - the tag naming the repository's own release,
+ *  as opposed to the per-package/group tags `changelog.tagPattern` names. Deliberately a **separate**
+ *  pattern with a non-`v` default: `findLatestTag` resolves a repo-wide package pattern with `git
+ *  describe --match`, so a release tag that also matched `v*` would be picked up as some package's
+ *  own last release - corrupting both its changelog boundary and the version its entry is headed
+ *  with. */
+export declare function releaseTagPattern(root: Package): string;
+export declare function isCalendarVersion(version: string): boolean;
+/** `date` as a calendar release version - see `CALENDAR_VERSION_PATTERN` for why nothing is padded.
+ *  The time becomes a single number (`14:30` -> `1430`, `09:30` -> `930`), which is both unpadded
+ *  by construction and ordered the way the clock is. */
+export declare function formatCalendarVersion(date: Date): string;
+/**
+ * Whether this repository's releases are identified by a calendar version rather than a shared
+ * semver one. Derived, never configured - a repo that picked "highest package version" would only
+ * be picking a bug: with two version lines the highest can stay put while a lower one releases,
+ * leaving the release with no identity of its own.
+ *
+ * `groupCount > 1` makes the first call: with several version lines there is no meaningful shared
+ * number, so any semver-looking identity would claim something untrue. The other two make it
+ * **sticky** - going back would *lower* the root version (`2026.9.15-1430` -> `1.4.0` compares as a
+ * decrease), so once a calendar release exists the repo stays on calendar even if its groups later
+ * collapse back to one. The last-release-tag check is the authoritative one (tags record what was
+ * actually released); the root's own current version covers the case where tags aren't available
+ * at all, e.g. a shallow clone.
+ */
+export declare function usesCalendarVersion(options: {
+    groupCount: number;
+    rootVersion: string;
+    lastReleaseVersion?: string;
+}): boolean;
+/** The tag naming a given repository release - `releaseTagPattern` run forward, the way
+ *  `expandTag` runs `changelog.tagPattern` forward for a package. */
+export declare function expandReleaseTag(root: Package, version: string): string;
+/** The version of the repository's most recent release, from its release tags (highest by version
+ *  sort) - `undefined` for a repo that has never cut one, or whose tags aren't available (a shallow
+ *  clone). The authoritative half of `usesCalendarVersion`'s stickiness check: tags record what was
+ *  actually released, unlike a `package.json` that can drift. */
+export declare function findLastReleaseVersion(git: GitHelper, root: Package): Promise<string | undefined>;

package/utils/release-version.js

@@ -0,0 +1,66 @@
+import { applyTagPattern, extractVersion } from './change-hash.js';
+/**
+ * A calendar release version: `YYYY.M.D-HHmm`, every part **unpadded** (`2026.9.5-930`, not
+ * `2026.09.05-0930`). The padding isn't a style choice - semver forbids leading zeroes in numeric
+ * identifiers, so a padded month or time makes the version invalid, and a monorepo root's
+ * `package.json` has to hold a valid one. Unpadded still orders correctly: the date parts compare
+ * numerically as major/minor/patch, and the time compares numerically as a prerelease identifier
+ * (`930` < `1430`).
+ */
+export const CALENDAR_VERSION_PATTERN = /^\d{4}\.\d{1,2}\.\d{1,2}-\d+$/;
+/** `.rmanrc version.releaseTagPattern` (root-level) - the tag naming the repository's own release,
+ *  as opposed to the per-package/group tags `changelog.tagPattern` names. Deliberately a **separate**
+ *  pattern with a non-`v` default: `findLatestTag` resolves a repo-wide package pattern with `git
+ *  describe --match`, so a release tag that also matched `v*` would be picked up as some package's
+ *  own last release - corrupting both its changelog boundary and the version its entry is headed
+ *  with. */
+export function releaseTagPattern(root) {
+    const cfg = root.config?.version?.releaseTagPattern;
+    return typeof cfg === 'string' && cfg ? cfg : DEFAULT_RELEASE_TAG_PATTERN;
+}
+export function isCalendarVersion(version) {
+    return CALENDAR_VERSION_PATTERN.test(version);
+}
+/** `date` as a calendar release version - see `CALENDAR_VERSION_PATTERN` for why nothing is padded.
+ *  The time becomes a single number (`14:30` -> `1430`, `09:30` -> `930`), which is both unpadded
+ *  by construction and ordered the way the clock is. */
+export function formatCalendarVersion(date) {
+    const time = date.getHours() * 100 + date.getMinutes();
+    return `${date.getFullYear()}.${date.getMonth() + 1}.${date.getDate()}-${time}`;
+}
+/**
+ * Whether this repository's releases are identified by a calendar version rather than a shared
+ * semver one. Derived, never configured - a repo that picked "highest package version" would only
+ * be picking a bug: with two version lines the highest can stay put while a lower one releases,
+ * leaving the release with no identity of its own.
+ *
+ * `groupCount > 1` makes the first call: with several version lines there is no meaningful shared
+ * number, so any semver-looking identity would claim something untrue. The other two make it
+ * **sticky** - going back would *lower* the root version (`2026.9.15-1430` -> `1.4.0` compares as a
+ * decrease), so once a calendar release exists the repo stays on calendar even if its groups later
+ * collapse back to one. The last-release-tag check is the authoritative one (tags record what was
+ * actually released); the root's own current version covers the case where tags aren't available
+ * at all, e.g. a shallow clone.
+ */
+export function usesCalendarVersion(options) {
+    if (options.lastReleaseVersion && isCalendarVersion(options.lastReleaseVersion))
+        return true;
+    if (isCalendarVersion(options.rootVersion))
+        return true;
+    return options.groupCount > 1;
+}
+/** The tag naming a given repository release - `releaseTagPattern` run forward, the way
+ *  `expandTag` runs `changelog.tagPattern` forward for a package. */
+export function expandReleaseTag(root, version) {
+    return applyTagPattern(releaseTagPattern(root), root.name, version);
+}
+/** The version of the repository's most recent release, from its release tags (highest by version
+ *  sort) - `undefined` for a repo that has never cut one, or whose tags aren't available (a shallow
+ *  clone). The authoritative half of `usesCalendarVersion`'s stickiness check: tags record what was
+ *  actually released, unlike a `package.json` that can drift. */
+export async function findLastReleaseVersion(git, root) {
+    const glob = releaseTagPattern(root).replace('{name}', root.name);
+    const tag = (await git.listTags(glob))[0];
+    return tag ? extractVersion(tag, glob) : undefined;
+}
+const DEFAULT_RELEASE_TAG_PATTERN = 'release-*';