rman 1.0.12 → 1.2.1

package/interfaces/rman-config.interface.d.ts

@@ -1,32 +1,170 @@
+import type { RmanPlugin } from '../core/plugin.js';
+import type { RunConditionFn, RunStepValue } from '../core/run-step.js';
+/**
+ * Adds a `+key` alongside every key of `T`, which **appends** to whatever that key already resolved
+ * to instead of replacing it - see `mergeConfig`.
+ *
+ * Generated by key remapping rather than written out, so a key added to the interface gets its
+ * append form automatically and the two can never drift apart.
+ */
+export type WithAppend<T> = {
+    [K in keyof T as `+${K & string}`]?: T[K];
+};
+/**
+ * The one key every nested config node may carry: `vars` scoping that node's subtree - a fresh copy
+ * per level, merged per key over the level above. See `withScopedVars` in `core/config.ts` for what
+ * it does at resolution time, and docs/rman.md#scoped-vars for how it reads.
+ *
+ * **Every nested options interface extends this**, and a new one has to remember to - which is the
+ * cost of the runtime rule being general (any object node scopes) while a type can only say it one
+ * interface at a time. TypeScript has no way to state "and every object below this may also carry
+ * `vars`" without a recursive remap that would wreck the error messages.
+ *
+ * Extended by the `XOptions` interface rather than declared on `XOptionsKeys`, so `WithAppend` does
+ * not generate a `+vars`: appending to `vars` means nothing, since objects merge either way.
+ */
+export interface ScopedVars {
+    /** Values for `${{ vars.* }}` to read, for this node and everything under it. */
+    vars?: Record<string, unknown>;
+}
 /**
  * The shape of `.rmanrc`/`.rmanrc.yml`/`.rmanrc.cjs`/`.mjs`/`.js` (and `package.json`'s own
- * `"rman"` key) - see docs/api.md#configuration-rmanrc-rmanrcyml for the full reference. Every
+ * `"rman"` key) - see docs/rman.md#configuration-rmanrc-rmanrcyml for the full reference. Every
  * field is optional and cascades from the repository root down to each package's own directory.
  * Purely a typing aid (used by `defineConfig` below, and importable on its own for a `.rmanrc.ts`/
  * `.mts` authored config, or a plain `: RmanConfig` annotation) - never read by rman itself, which
  * only ever sees the plain JS object a JS config file exports.
  */
-export interface RmanConfig {
-    packageManager?: 'npm' | 'yarn' | 'pnpm' | 'bun';
+export interface RmanConfig extends RmanConfigKeys, WithAppend<RmanConfigKeys> {
+    /**
+     * Configs to inherit from, merged **underneath** this one - a shared package
+     * (`"@panates/rman-monorepo"`), a relative path, or an array applied in declaration order.
+     *
+     * A bare name resolves through *this* file's own `node_modules`, so a subpath works too
+     * (`"@panates/rman-monorepo/strict"`). The target may be YAML, JSON, or a module exporting a
+     * config via `defineConfig`, and may itself `extends` another.
+     *
+     * Top level only: a `"[selector]"` block naming one is an error rather than a no-op, since
+     * inheritance is a statement about this config and not about the packages a selector names.
+     */
+    extends?: string | string[];
+}
+/** Every setting a config may carry, without the `+key` append forms or `extends` - the shape
+ *  `RmanConfig` is built from, kept separate only so `WithAppend` has something to map over. */
+export interface RmanConfigKeys {
+    /**
+     * **A plugin adds its own keys here, by declaration merging** - `rman-node` contributes
+     * `clean` and `publish.directory` from its own
+     * `interfaces/rman-config.interface.ts`, so `pkg.config.clean` stays typed wherever it is read
+     * without the core having to know npm has a `node_modules` or that TypeScript has build output.
+     * `WithAppend` is a mapped type evaluated at use, so an augmented key gets its `+key` form too.
+     *
+     * A config author annotates with the plugin's own name for the union - `RmanNodeConfig` - which
+     * is what makes the import that carries the augmentation explicit rather than incidental.
+     */
+    /**
+     * Plugins to load, in declaration order - a *package* contributing commands, where `.rman/*.mjs`
+     * contributes one repository's own.
+     *
+     * Each entry is **either a package name (or path) to import, or a plugin object itself**:
+     *
+     * ```yaml
+     * # .rmanrc.yml - imported by name, resolved through the repository's own node_modules
+     * plugins: ['rman-node']
+     * ```
+     *
+     * ```js
+     * // .rmanrc.mjs - or handed over directly, which a JS config can do and a YAML one cannot
+     * import { defineConfig, definePlugin } from 'rman';
+     * export default defineConfig({ plugins: [definePlugin({ name: 'mine', commands: [...] })] });
+     * ```
+     *
+     * The object form is what lets a **plugin package export a config** rather than a single plugin:
+     * `rman-node`'s entry point is `export default defineConfig({ plugins: [ ... ] })`, so it is an
+     * `.rmanrc` like any other and is free to grow a second plugin without changing its shape. When an
+     * imported module exports a config this way, **only its `plugins` are read** - a config's other
+     * keys reach a repository through `extends`, which is the key that means "merge this underneath
+     * mine".
+     *
+     * This is how everything that only means something in a Node repository lives outside rman's
+     * core. A plugin that cannot be loaded is an error, not a skip: silently losing `rman publish` is
+     * worse than not starting.
+     *
+     * Root level only - which commands exist is a property of the repository, not of a package.
+     */
+    plugins?: string | RmanPlugin | (string | RmanPlugin)[];
+    /**
+     * Values for `${{ vars.* }}` to read - a name for something the config would otherwise repeat:
+     *
+     * ```yaml
+     * vars:
+     *   outDir: build
+     *   image: 'panates/${{ pkg.basename }}'
+     * "[*]":
+     *   publish:
+     *     directory: '${{ vars.outDir }}'
+     * ```
+     *
+     * Any shape, and the values may themselves be expressions - they are evaluated for the package
+     * reading them, so one `vars.image` gives each package its own.
+     *
+     * **The one unmarked key that reaches every package**, rather than only the package of the
+     * directory declaring it. A package (or a `"[selector]"` block) overrides it **per key**, so
+     * redefining one var keeps the rest.
+     */
+    vars?: Record<string, unknown>;
     logLevel?: 'silent' | 'error' | 'info' | 'verbose';
     allowBranch?: string | string[];
     ignoreBranch?: string | string[];
+    /**
+     * Leave this package alone: **every command that acts on packages skips it** - `run`/`build`/
+     * `test`, `exec`, `clean`, `publish`, `version`, `changelog`. Per-package cascaded, so a root
+     * `"[selector]"` block can say it for several at once.
+     *
+     * One standing statement rather than a `skip` invented per command, which is what it was: three
+     * separate keys carried it and none of them meant quite the same thing. The finer-grained ones
+     * remain for when only one command should stop - `run.<script>.skip` for a single script,
+     * `publish.skip` for "never distributed, by any target" (which `changelog` reuses on purpose).
+     *
+     * **The commands that *report* deliberately ignore it** - `list` still shows the package, because
+     * it is still in the repository and an inventory hiding part of one is answering a different
+     * question. `changed` follows `version`, since its whole job is to say what `version` would do.
+     */
+    skip?: boolean;
     group?: boolean | string;
     version?: RmanConfig.VersionOptions;
     changelog?: RmanConfig.ChangelogOptions;
-    clean?: RmanConfig.CleanOptions;
     publish?: RmanConfig.PublishOptions;
     githubRelease?: RmanConfig.GithubReleaseOptions;
     /** Keyed by npm script name (e.g. `"build"`, `"lint"`, `"test"`). A bare string (or array of
      *  them) is shorthand for `{ exec: ... }` - `test: "mocha"` and `test: { exec: "mocha" }` mean
-     *  exactly the same thing. */
-    run?: Record<string, string | string[] | RmanConfig.RunScriptOptions>;
-    /** In-repo packages this one depends on beyond what its real `package.json` declares - purely
-     *  for rman's own dependency graph (topo-sort, `--deps`/`--dependents`, `run`'s scheduling). An
-     *  array defaults each entry's range to `"*"`; an object gives an explicit name -> range map.
-     *  Declared from the root via a selector (`"[pkg-a]": { dependencies: [...] }`) or in the
-     *  package's own `.rmanrc`. */
-    dependencies?: string[] | Record<string, string>;
+     *  exactly the same thing, and a bare function is the same shorthand for a function step. */
+    run?: RmanConfig.RunConfig;
+    /**
+     * In-repo packages this one depends on **beyond what its own manifest declares** - purely for
+     * rman's own dependency graph (topo-sort, `--deps`/`--dependents`, `run`'s scheduling, the version
+     * cascade). Declared from the root via a selector (`"[pkg-a]": { dependencies: [...] }`) or in the
+     * package's own `.rmanrc`.
+     *
+     * Each entry is a package **name, or a repository-relative directory** - tried in that order. The
+     * path form is not a convenience: a name identifies a package only where the ecosystem guarantees
+     * uniqueness, which npm does and others do not, while a directory is unique by construction. It is
+     * the same reason `Workspace.Layout` carries paths and `Package.dependencies` holds references
+     * rather than names.
+     *
+     * **A list, and only a list.** It used to accept a `Record<string, string>` too, documented as "an
+     * explicit name -> range map" - and the ranges went nowhere: the one reader took `Object.keys` and
+     * dropped the values. Nor could they ever mean anything here, since the cascade works from groups
+     * and severities, and `ManifestProvider.updateDependencyVersions` rewrites ranges in the
+     * *manifest* - a range declared only in `.rmanrc` has no file to be written to. What this key
+     * states is an **edge**, and an edge needs two ends and nothing else.
+     *
+     * **Core, and it has to be**: it is layered on top of whatever `ManifestProvider.dependencies`
+     * read, and it is the *only* way a repository with no provider at all has a graph - a repo whose
+     * manifests rman cannot read can still state its edges by hand. Moving it to an ecosystem plugin
+     * would take that away from exactly the repositories that need it.
+     */
+    dependencies?: string[];
     /**
      * Config for **other** packages, keyed by a `"[selector]"` naming them - `"[*]"` for every
      * package in the repository, `"[*-dialect]"` for a glob over package names, `"[pkg-a]"` for one.
@@ -57,7 +195,22 @@ export interface RmanConfig {
     [selector: `[${string}]`]: RmanConfig;
 }
 export declare namespace RmanConfig {
-    interface VersionOptions {
+    /**
+     * One `version.stamp` entry: a path, or a path plus the identifier that holds the version.
+     *
+     * The object form exists because the identifier was unnameable - only the exact lowercase word
+     * `version` was ever matched, so a Go `const Version`, a Python `__version__` and a plain
+     * `appVersion` were all silently skipped. What the identifier *means* is the ecosystem's
+     * (`ManifestProvider.stampVersion`); which file holds one is the repository's, which is why it is
+     * here.
+     */
+    type VersionStampEntry = string | {
+        file: string;
+        constant?: string;
+    };
+    interface VersionOptions extends VersionOptionsKeys, WithAppend<VersionOptionsKeys>, ScopedVars {
+    }
+    interface VersionOptionsKeys {
         commitMessage?: string;
         /** Default for `version --changelog` when the CLI flag isn't given - a standing "always fold
          *  the changelog into the version-bump commit" policy, rather than something that behaves
@@ -77,7 +230,7 @@ export declare namespace RmanConfig {
          *  already declares (never inserts one), and reads the same path `publish --target docker`
          *  builds from (`publish.docker.dockerfile`), so a package without one is a no-op. */
         stampDockerfile?: boolean;
-        /** Source files whose `version` constant is rewritten to the version being written, in the same
+        /** Files whose hard-coded version is rewritten to the version being written, in the same
          *  commit as the bump - paths relative to the package's own directory (e.g.
          *  `["src/constants.ts"]`). Per-package cascaded; a listed file a package doesn't have is a
          *  silent no-op, so one `"[*]"` declaration covers a repo where only some packages carry one.
@@ -85,27 +238,48 @@ export declare namespace RmanConfig {
          *  Stamping the source, not the build output: a build-time rewrite leaves the checked-in file
          *  claiming a placeholder, so anything running from source reports that placeholder, git never
          *  records the released version, and the rewrite has to be redone on every build. */
-        stamp?: string | string[];
-        /** Command(s) run as this package's own `version` npm-lifecycle step, when its `package.json`
-         *  doesn't define one itself. An array runs them in sequence. */
-        exec?: string | string[];
-        /** Same, for `preversion`. */
-        before?: string | string[];
-        /** Same, for `postversion`. */
-        after?: string | string[];
+        stamp?: VersionStampEntry | VersionStampEntry[];
+        /** Command(s) run at the version write itself, when the package does not declare a hook for
+         *  that slot of its own (`version` in a Node repository's `package.json#scripts`, whatever a
+         *  plugin's step source answers elsewhere - the package's own declaration wins, as in `run`).
+         *  An array runs them in sequence. `${{ pkg.targetVersion }}` is bound here and in the two
+         *  below, and nowhere else.
+         *
+         *  A `RunStepFn` runs in place of a shell command - but note that `${{ pkg.targetVersion }}` is
+         *  a *string* substitution, so a function reads the written version off `pkg` instead. */
+        exec?: RunStepValue | RunStepValue[];
+        /** Same, before the write (`preversion` in a Node repository). */
+        before?: RunStepValue | RunStepValue[];
+        /** Same, after it (`postversion` in a Node repository). */
+        after?: RunStepValue | RunStepValue[];
     }
-    interface ChangelogOptions {
+    interface ChangelogOptions extends ChangelogOptionsKeys, WithAppend<ChangelogOptionsKeys>, ScopedVars {
+    }
+    interface ChangelogOptionsKeys {
         ignoreTypes?: string[];
         template?: string;
         filePath?: string;
         tagPattern?: string;
     }
-    interface CleanOptions {
-        include?: string | string[];
-        exclude?: string | string[];
-        skip?: boolean;
+    /**
+     * The `run` block: scripts by name.
+     *
+     * **`run.vars` works at runtime but is deliberately not in this type**, and the reason is a
+     * measured trade rather than an oversight. `run` is keyed by script name, so any encoding that
+     * lets `vars` through has to widen the index signature's value type to something object-shaped -
+     * and TypeScript then stops excess-property-checking *every* script's options. Measured on the
+     * same file: with the widened index, `run: { build: { exce: 'tsc' } }` compiles clean.
+     *
+     * Catching that typo across every script is worth more than typing one key, so a typed JS config
+     * writing `run.vars` needs a cast (`run: { vars: { x: 2 }, build: ... } as RmanConfig['run']`).
+     * YAML and JSON configs are unchecked anyway and simply work. A key-remapped index signature
+     * (`{ [K in string as K extends 'vars' ? never : K]: ... }`) was tried and does not help - the
+     * remap still produces an index signature that claims `vars`.
+     */
+    type RunConfig = Record<string, RunStepValue | RunStepValue[] | RunScriptOptions>;
+    interface RunScriptOptions extends RunScriptOptionsKeys, WithAppend<RunScriptOptionsKeys>, ScopedVars {
     }
-    interface RunScriptOptions {
+    interface RunScriptOptionsKeys {
         concurrency?: number;
         topo?: boolean;
         bail?: boolean;
@@ -113,17 +287,23 @@ export declare namespace RmanConfig {
         logLevel?: 'silent' | 'error' | 'info' | 'verbose';
         changedSince?: string;
         skip?: boolean;
-        if?: string;
+        /** Whether this script runs for a package at all - the small `changed and not private` grammar,
+         *  or a `RunConditionFn` for a condition it cannot express. Both are evaluated per package when
+         *  the run reaches it; a `${{ }}` expression here is not, having been resolved when the config
+         *  loaded. */
+        if?: string | RunConditionFn;
         /** Command(s) to run as this script itself, when the package's `package.json` doesn't define
-         *  it. An array runs them in sequence. */
-        exec?: string | string[];
+         *  it. An array runs them in sequence, and may mix shell commands with functions. */
+        exec?: RunStepValue | RunStepValue[];
         /** Same, for this script's `pre<script>` hook. */
-        before?: string | string[];
+        before?: RunStepValue | RunStepValue[];
         /** Same, for its `post<script>` hook. */
-        after?: string | string[];
+        after?: RunStepValue | RunStepValue[];
         override?: boolean;
     }
-    interface PublishOptions {
+    interface PublishOptions extends PublishOptionsKeys, WithAppend<PublishOptionsKeys>, ScopedVars {
+    }
+    interface PublishOptionsKeys {
         /** Which **registry** `publish` ships this package to - default `['npm']` (every existing repo
          *  keeps working unchanged). A package that only ever wants Docker images (typically also
          *  `"private": true`, since it's not meant for npm at all) sets `['docker']`; both works too.
@@ -135,14 +315,6 @@ export declare namespace RmanConfig {
          *  a release happened, and it is never opted into: see `githubRelease` and the
          *  `github-release` command. */
         target?: PublishTarget | PublishTarget[];
-        /** Where this package's publishable output lives, relative to its own directory (e.g.
-         *  `"build"`). Per-package cascaded, so a root `"[*]"` block can say it once for the whole
-         *  repository instead of repeating `publishConfig.directory` in every `package.json` - which
-         *  still wins when a package declares it, being the more specific statement.
-         *
-         *  Publishing from such a directory means the manifest there is **generated by `publish`**,
-         *  from the package's own - see `PublishService`. There is nothing to configure about it. */
-        directory?: string;
         docker?: DockerPublishOptions;
         /** Excludes this package from `publish` entirely (every target), regardless of
          *  `target`/`"private"` - a single, explicit "never published" statement, e.g. for a package
@@ -155,7 +327,9 @@ export declare namespace RmanConfig {
     type PublishTarget = 'npm' | 'docker';
     /** Required once `"docker"` is one of this package's `publish.target`s - `publish --target
      *  docker` errors clearly on a package that opts in here but leaves this out. */
-    interface DockerPublishOptions {
+    interface DockerPublishOptions extends DockerPublishOptionsKeys, WithAppend<DockerPublishOptionsKeys>, ScopedVars {
+    }
+    interface DockerPublishOptionsKeys {
         /** DockerHub image name/repository - bare (e.g. `"my-app"`) to be prefixed with
          *  `--docker-namespace`/`DOCKERHUB_NAMESPACE`, or already-namespaced (contains a `/`) to use
          *  verbatim. */
@@ -181,7 +355,9 @@ export declare namespace RmanConfig {
      *  (which tag, which repository, what the notes say) already has a sensible source. Nothing here
      *  decides *whether* a release is cut: a release records that the repository shipped, so it is
      *  always cut, and these are only details about how. */
-    interface GithubReleaseOptions {
+    interface GithubReleaseOptions extends GithubReleaseOptionsKeys, WithAppend<GithubReleaseOptionsKeys>, ScopedVars {
+    }
+    interface GithubReleaseOptionsKeys {
         /** 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 at all is still perfectly valid - it records that the
@@ -191,8 +367,8 @@ export declare namespace RmanConfig {
         repository?: string;
         /** Create the release as an unpublished draft. Default `false`. Root-level only. */
         draft?: boolean;
-        /** Default: whether the version being released is itself a semver prerelease (`1.3.0-beta.0`).
-         *  Root-level only. */
+        /** Default: whether the version being released is itself a prerelease by the root's own version
+         *  scheme (`1.3.0-beta.0` under semver) - see `VersionScheme.isPrerelease`. Root-level only. */
         prerelease?: boolean;
     }
 }

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "rman",
   "description": "Repository manager",
-  "version": "1.0.12",
+  "version": "1.2.1",
   "author": "Panates",
   "license": "MIT",
   "dependencies": {
-    "@netlify/parse-npm-script": "^0.1.2",
+    "@xmldom/xmldom": "^0.9.12",
     "ansi-colors": "^4.1.3",
     "cross-dirname": "^0.1.0",
     "easy-table": "^1.2.0",
@@ -35,8 +35,11 @@
       "types": "./index.d.ts",
       "default": "./index.js"
     },
-    "./package.json": "./package.json",
-    "./rmanrc.schema.json": "./rmanrc.schema.json"
+    "./cli": {
+      "types": "./cli.d.ts",
+      "default": "./cli.js"
+    },
+    "./package.json": "./package.json"
   },
   "bin": {
     "rman": "cli.js"
@@ -45,11 +48,15 @@
     "node": ">=20.0"
   },
   "contributors": [
-    "Eray Hanoglu <e.hanoglu@panates.com>"
+    "Eray Hanoglu <e.hanoglu@panates.com>",
+    "Ilker Gurelli <i.gurelli@panates.com>",
+    "Onur Tokel <o.tokel@panates.com>",
+    "Bircan Yuruk <b.yuruk@panates.com>"
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/panates/rman.git"
+    "url": "git+https://github.com/panates/rman.git",
+    "directory": "./packages/rman"
   },
   "keywords": [
     "javascript",
@@ -59,5 +66,7 @@
     "build",
     "lerna"
   ],
-  "packageManager": "yarn@3.4.1+sha512.a333bf9c2557d71f5ba87dd1446cde24bb9c35301ec29dd2baba577b3f9d1ab61348b66a1324de9088c40a996c5b9203794da8bf14cab9fae6a6eccc00cb8078"
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/services/change-hash.service.d.ts

@@ -0,0 +1,88 @@
+import type { Package } from '../core/package.js';
+import type { GitHelper } from '../utils/git.js';
+/**
+ * Release boundaries and the tag names that mark them - **the single source for both directions**.
+ *
+ * Every command that asks question A ("what changed since this package's last release") comes
+ * through `detect`, and every command that needs to *name* a tag comes through `expandTag` /
+ * `findLatestTag`. No command builds a tag name of its own; that is what keeps `version`'s tag,
+ * `changelog`'s boundary and `github-release`'s lookup from drifting apart.
+ *
+ * A namespace for the reason `Manifest` and `Workspace` are ones: it is one subject with several
+ * operations, so the operations are named for what they do rather than carrying the subject in each
+ * name (`ChangeHashService.detect`, not `detectChangeHash`), and a plugin can augment it.
+ */
+export declare namespace ChangeHashService {
+    /** The one keyword `from` accepts instead of a ref: "work it out per package". Omitting `from`
+     *  means the same thing - this exists so a pipeline can say it explicitly. */
+    const AUTO = "auto";
+    interface DetectOptions {
+        /**
+         * Use this commit/hash directly instead of auto-detecting - applies the same way to every
+         * package. `AUTO` (or omitting `from` entirely) asks for auto-detection instead of being
+         * treated as a literal ref.
+         *
+         * The keyword used to be `"npm"`, which named a *source* - and the wrong one: auto-detection is
+         * mostly git, and the registry it may consult is now the ecosystem's business (see
+         * `ManifestProvider.publishedVersion`). What is being chosen here is a *mode*, so it is spelled
+         * as one. **A rename, not an alias**: `--from npm` now means a ref literally called `npm`,
+         * which is what it should have meant all along.
+         */
+        from?: string;
+        /** An existing record of what's already been documented (typically a changelog file) - only
+         *  consulted while auto-detecting (ignored when `from` is an explicit hash). Guards against a
+         *  gap: if this file's own last-modifying commit is *older* than the tag detected from the
+         *  registry - e.g. the file was last updated for 1.1.0, but 1.2.0-1.5.0 were released without
+         *  ever documenting them, and the registry now reports 1.5.0 - starting from the tag alone would
+         *  silently skip everything the file never recorded. The boundary becomes the merge-base of the
+         *  two, so the result always covers at least as much as the file is missing. Has no effect when
+         *  the file doesn't exist. */
+        catchUpFile?: string;
+    }
+    /** `.rmanrc changelog.tagPattern` (cascaded, per-package overridable) - a glob for this package's
+     *  release tags. `{name}` (if present) is replaced with the package's own name, e.g. `{name}@*`
+     *  for independent per-package versioning (`@scope/pkg@1.2.3`, the same scheme lerna/changesets
+     *  use - `@`/`/` are both fine in a git tag name). Without `{name}`, it's a single repo-wide tag
+     *  shared by every package (e.g. the default `v*`). */
+    function tagPattern(pkg: Package): string;
+    /** This package's most recent release tag - the `{name}`-bearing pattern looks up that package's
+     *  *own* tags directly (newest by version sort); a repo-wide pattern instead finds the nearest tag
+     *  HEAD actually descends from, since no single package "owns" that tag. `undefined` if never
+     *  tagged at all (a fresh package, or one that's never been released). Shared by `changelog`
+     *  (reading the last-documented version) and `version` (finding the boundary a bump measures
+     *  "since"). */
+    function findLatestTag(git: GitHelper, pkg: Package): Promise<string | undefined>;
+    /** 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),
+     *  `github-release` (finding the release that tag belongs to), and `detect`'s own registry
+     *  fallback (mapping a published version back onto a tag), so all three name tags identically. */
+    function expandTag(pkg: Package, version: string): string;
+    /** 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. */
+    function applyTagPattern(pattern: string, name: string, version: string): string;
+    /** 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). */
+    function extractVersion(tag: string, expandedPattern: string): string;
+    /**
+     * 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 `AUTO`) is returned as-is, applying the same
+     * 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 release history but no `rman`-created tags), whatever this package's **own ecosystem**
+     * reports as its published version (`ManifestProvider.publishedVersion`), mapped to a git tag via
+     * `.rmanrc changelog.tagPattern` and used only if that tag actually exists. 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).
+     */
+    function detect(git: GitHelper, pkg: Package, options?: DetectOptions): Promise<string | undefined>;
+}

package/services/change-hash.service.js

@@ -0,0 +1,112 @@
+import { Manifest } from '../core/manifest.js';
+/**
+ * Release boundaries and the tag names that mark them - **the single source for both directions**.
+ *
+ * Every command that asks question A ("what changed since this package's last release") comes
+ * through `detect`, and every command that needs to *name* a tag comes through `expandTag` /
+ * `findLatestTag`. No command builds a tag name of its own; that is what keeps `version`'s tag,
+ * `changelog`'s boundary and `github-release`'s lookup from drifting apart.
+ *
+ * A namespace for the reason `Manifest` and `Workspace` are ones: it is one subject with several
+ * operations, so the operations are named for what they do rather than carrying the subject in each
+ * name (`ChangeHashService.detect`, not `detectChangeHash`), and a plugin can augment it.
+ */
+export var ChangeHashService;
+(function (ChangeHashService) {
+    /** The one keyword `from` accepts instead of a ref: "work it out per package". Omitting `from`
+     *  means the same thing - this exists so a pipeline can say it explicitly. */
+    ChangeHashService.AUTO = 'auto';
+    /** `.rmanrc changelog.tagPattern` (cascaded, per-package overridable) - a glob for this package's
+     *  release tags. `{name}` (if present) is replaced with the package's own name, e.g. `{name}@*`
+     *  for independent per-package versioning (`@scope/pkg@1.2.3`, the same scheme lerna/changesets
+     *  use - `@`/`/` are both fine in a git tag name). Without `{name}`, it's a single repo-wide tag
+     *  shared by every package (e.g. the default `v*`). */
+    function tagPattern(pkg) {
+        const cfg = pkg.config?.changelog;
+        return typeof cfg?.tagPattern === 'string' && cfg.tagPattern ? cfg.tagPattern : DEFAULT_TAG_PATTERN;
+    }
+    ChangeHashService.tagPattern = tagPattern;
+    /** This package's most recent release tag - the `{name}`-bearing pattern looks up that package's
+     *  *own* tags directly (newest by version sort); a repo-wide pattern instead finds the nearest tag
+     *  HEAD actually descends from, since no single package "owns" that tag. `undefined` if never
+     *  tagged at all (a fresh package, or one that's never been released). Shared by `changelog`
+     *  (reading the last-documented version) and `version` (finding the boundary a bump measures
+     *  "since"). */
+    async function findLatestTag(git, pkg) {
+        const pattern = tagPattern(pkg);
+        const expanded = pattern.replace('{name}', pkg.name);
+        return pattern.includes('{name}') ? (await git.listTags(expanded))[0] : await git.describeTag(expanded);
+    }
+    ChangeHashService.findLatestTag = findLatestTag;
+    /** 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),
+     *  `github-release` (finding the release that tag belongs to), and `detect`'s own registry
+     *  fallback (mapping a published version back onto a tag), so all three name tags identically. */
+    function expandTag(pkg, version) {
+        return applyTagPattern(tagPattern(pkg), pkg.name, version);
+    }
+    ChangeHashService.expandTag = expandTag;
+    /** 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. */
+    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);
+    }
+    ChangeHashService.applyTagPattern = applyTagPattern;
+    /** 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). */
+    function extractVersion(tag, expandedPattern) {
+        const starIdx = expandedPattern.indexOf('*');
+        if (starIdx === -1)
+            return tag;
+        const prefix = expandedPattern.slice(0, starIdx);
+        return tag.startsWith(prefix) ? tag.slice(prefix.length) : tag;
+    }
+    ChangeHashService.extractVersion = extractVersion;
+    /**
+     * 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 `AUTO`) is returned as-is, applying the same
+     * 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 release history but no `rman`-created tags), whatever this package's **own ecosystem**
+     * reports as its published version (`ManifestProvider.publishedVersion`), mapped to a git tag via
+     * `.rmanrc changelog.tagPattern` and used only if that tag actually exists. 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).
+     */
+    async function detect(git, pkg, options = {}) {
+        if (options.from && options.from !== ChangeHashService.AUTO)
+            return options.from;
+        let tagHash = await findLatestTag(git, pkg);
+        if (!tagHash) {
+            /** Through the package's own ecosystem, not through npm: which registry (if any) knows about
+             *  this package is the `ManifestProvider`'s answer, and in a polyglot repository it differs
+             *  per package. A repository naming no plugin gets `undefined` here and git tags decide
+             *  alone. */
+            const publishedVersion = await Manifest.publishedVersion(pkg);
+            if (publishedVersion) {
+                const tag = expandTag(pkg, publishedVersion);
+                tagHash = (await git.tagExists(tag)) ? tag : undefined;
+            }
+        }
+        const fileHash = options.catchUpFile ? await git.lastCommitTouching(options.catchUpFile) : undefined;
+        if (!fileHash)
+            return tagHash;
+        if (!tagHash)
+            return fileHash;
+        return (await git.mergeBase(tagHash, fileHash)) ?? tagHash;
+    }
+    ChangeHashService.detect = detect;
+})(ChangeHashService || (ChangeHashService = {}));
+const DEFAULT_TAG_PATTERN = 'v*';