rman 2.0.0-beta.2 → 2.0.0-beta.3

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

@@ -0,0 +1,223 @@
+import type path from 'node:path';
+import type semver from 'semver';
+import type { ConfigFileScope } from '../core/config/config-file-scope.js';
+/**
+ * **What a `${{ ... }}` expression can name**, and what a value function is handed.
+ *
+ * One file because these six describe one thing from different angles: `ConfigScope` is the whole
+ * of it, the others are its members, and `ConfigValueContext` is the same scope with `value` added
+ * for a function. They are `interfaces/` rather than `core/` for the reason the config interface
+ * already is - nothing here runs, and the audience is a config author.
+ */
+/**
+ * What a `${{ ... }}` expression can see - the bindings of the fresh global it is evaluated in.
+ * Namespaced rather than a flat bag of loose names: one obvious place per fact, and room to add
+ * helpers to `pkg`/`repository` later without crowding the global.
+ *
+ * Alongside these, **the config's own top-level keys are bound bare** (`${{ changelog.filePath }}`,
+ * `${{ clean.include }}`) - see `interpolateConfig`. They are not listed here because they come
+ * from the config being interpolated, not from this object; a name here wins over a config key of
+ * the same name.
+ *
+ * **Trap: bare `${{ version }}` is the `version` *options block*, not the package's version
+ * string** - that is `${{ pkg.version }}`. Same word, two different things, and the plain one
+ * belongs to the config because every other config key is reachable that way.
+ */
+export interface ConfigScope {
+    /** The package the config was resolved for - which is what lets one declaration at the root
+     *  still say something package-specific. */
+    pkg: PackageScope;
+    repository: RepositoryScope;
+    /** Paths, resolved against the package the config was resolved for. */
+    file: FileScope;
+    /**
+     * The **contents** of a structured file - `${{ read('tsconfig.json').compilerOptions.outDir }}` -
+     * where `file` answers only where one is. Resolved against `pkg.dirname` like `file`, so a
+     * `"[*]"` block asks each package about its own; a repository-level file is reached through
+     * `read(path.join(repository.dirname, ...))`.
+     *
+     * `.json`, `.yml`/`.yaml` and `.ini` by extension, or name it for a file that does not say
+     * (`read('.npmrc', 'ini')`). **Throws** when the file is absent, as `file.resolve` does - compose
+     * with `file.exists` when its absence is a case to handle.
+     *
+     * **A manifest is `pkg.manifest`, not this.** `read('package.json')` works and is the wrong
+     * answer: which file a package's identity lives in belongs to the ecosystem, so that expression
+     * is already wrong in a Cargo package sitting beside a Node one.
+     *
+     * The result is **deeply frozen and shared** - see `readStructuredFile`. Spread it to change it.
+     */
+    read: ConfigFileScope.ReadFile;
+    env: Record<string, string | undefined>;
+    /** rman's own `semver`, for the arithmetic every release config eventually wants
+     *  (`semver.major(pkg.version)`). */
+    semver: typeof semver;
+    /**
+     * Node's own `node:path` - `${{ path.join(pkg.dirname, 'LICENSE') }}`, rather than gluing
+     * strings with `+ "/" +` and getting a double separator or none.
+     *
+     * The platform's flavour, not `path.posix`, so a joined path is the one the shell on *this*
+     * machine understands; `path.posix` and `path.win32` are reachable through it when a config
+     * genuinely needs one of them (a Docker image path, say, which is always posix).
+     */
+    path: typeof path;
+    /**
+     * The checkout: branch, sha, whether the tree is dirty.
+     *
+     * **Top level, not `repository.git`** - which is where it used to be, and the move is the point.
+     * `repository` shares its shape with `pkg` because the repository root *is* a package, and its
+     * only other members (`monorepo`, `packages`, `package()`) say something about the repository as
+     * a container of packages. A branch name says nothing about any package; it describes the
+     * working tree every one of them happens to be sitting in - the same kind of ambient fact as
+     * `env`, and it belongs beside it.
+     *
+     * **Read from git only if an expression actually asks**, then remembered for the whole run: every
+     * command resolves config, and a repository that never mentions git must not pay for one. See
+     * `Repository.configScope` for the getter, and `interpolateConfig` for why the context is built
+     * from property descriptors rather than a spread - a spread would fire this getter on every
+     * command, which is exactly what moving it up here risked.
+     */
+    git: GitScope;
+}
+/** One package, as an expression sees it - the same shape for the package the config belongs to
+ *  and for the repository itself, so `${{ repository.basename }}` reads the way `${{ pkg.basename }}` does. */
+/**
+ * `file` in a `${{ ... }}` expression: what is actually on disk, resolved against **the package
+ * the config was resolved for** - so one declaration in a `"[*]"` block asks each package about
+ * its own directory.
+ *
+ * The pair exists because a config has two different questions about a path, and answering both
+ * with one function would mean picking a wrong default for the other:
+ *
+ * ```yaml
+ * "[*]":
+ *   run:
+ *     build:
+ *       # first of these that exists, and an error naming the config path if none do
+ *       exec: 'tsc -b ${{ file.exists("tsconfig-build.json") || file.resolve("tsconfig.json") }}'
+ * ```
+ *
+ * **Every member asks a question, and none may ever change anything - no `copy`, no `write`, no
+ * `mkdir`.** Not a matter of taste: this is evaluated when the config *resolves*, which every
+ * command does, so a member that acted would act on `rman list`, `rman info` and `rman config`.
+ *
+ * That has been tried, in the only way a missing function can be: a shared config reaching for a
+ * `file.copyMany(...)` that does not exist made **every** rman command exit 1 - and had it existed,
+ * the quieter outcome would have been files copied by `rman list`. Work belongs in a step
+ * (`run.<script>`'s slots, `version`'s hooks), which is the one place rman runs anything, and a
+ * step can now be a function - so there is nothing this would enable that is not already possible
+ * at the right moment.
+ */
+export interface FileScope {
+    /**
+     * The absolute path if it exists, **`''` if it does not** - so `a || b || c` picks the first one
+     * present, and so a miss never reaches the "nullish inside a string" guard that `undefined` would
+     * trip. Accepts a relative path (against the package directory) or an absolute one.
+     *
+     * It returns a path rather than a boolean on purpose: the caller almost always wants the path,
+     * and a separate `file.path()` to fetch it after a boolean test would read the disk twice and
+     * invite the two calls to disagree.
+     */
+    exists(target: string): string;
+    /** The absolute path, or **throws** - for a file whose absence is a mistake rather than a case to
+     *  handle. The error names the config path holding the expression, like any other. */
+    resolve(target: string): string;
+    /**
+     * The first of several that exists, or **throws** naming every candidate it tried:
+     *
+     * ```yaml
+     * exec: 'tsc -b ${{ file.resolveFirst("tsconfig-build.json", "tsconfig.build.json", "tsconfig.json") }}'
+     * ```
+     *
+     * The same thing an `exists() || exists() || resolve()` chain does, said once - and it cannot be
+     * got subtly wrong the way that chain can: ending it in `exists()` leaves `tsc -b ` with no
+     * argument when nothing matches, and tsc then silently falls back to the directory's default
+     * rather than reporting that the package has no build config.
+     */
+    resolveFirst(...targets: string[]): string;
+}
+export interface PackageScope {
+    /** The package's own name, scope included (`@sqb/builder`). */
+    name: string;
+    /** Just the scope (`@sqb`), or `undefined` for an unscoped package. */
+    scope: string | undefined;
+    /** The name with its scope stripped (`builder`). */
+    unscopedName: string;
+    version: string;
+    /** The package directory's last segment (`builder`) - not always the same as `unscopedName`,
+     *  which is why both exist, and usually what a sibling path (`../../coverage/builder`) is keyed on. */
+    basename: string;
+    /** Absolute path to the package's own directory - named as rman's own `Package.dirname` is. */
+    dirname: string;
+    /** That directory relative to the repository root (`packages/builder`), which is what a command
+     *  addressing another package from the root usually needs. Empty string for the root itself. */
+    relativeDir: string;
+    /**
+     * Which ecosystem this package belongs to - `'node'` for one the `node` built-in read, empty when no
+     * plugin claimed it. The same `Package.provider`, so one declaration can address a single
+     * ecosystem in a polyglot repository (`if: "${{ pkg.provider === 'node' }}"`).
+     */
+    provider: string;
+    /**
+     * The whole manifest, as a copy - so an expression can reach a field rman itself has no opinion
+     * about (`${{ pkg.manifest.engines.node }}`).
+     *
+     * Named `manifest`, not `json`: which file a package's identity lives in is the ecosystem's
+     * business now (see `Plugin`'s manifest members), and `json` was that assumption showing through the one
+     * remaining user-facing name. A config written against `${{ pkg.json... }}` needs the rename.
+     */
+    manifest: Record<string, unknown>;
+    /**
+     * The version this run is about to write - **bound only during `version`**, and only once its
+     * plan is computed. Reading it anywhere else throws rather than yielding `undefined`: no other
+     * command has a target version, so an expression asking for one has been put in the wrong place,
+     * and a config that quietly evaluates to "undefined" is the failure this evaluator exists to
+     * prevent.
+     */
+    targetVersion: string;
+}
+/** Facts about the repository, on top of the root package's own - because the repository root *is*
+ *  a package (`repository.name` is what its `package.json` says, `repository.basename` the directory
+ *  it sits in, and the two genuinely differ). Sharing `PackageScope`'s shape is what makes
+ *  `repository.version` read the way `pkg.version` does. */
+export interface RepositoryScope extends PackageScope {
+    monorepo: boolean;
+    /** Every package in the repository - the root included only when it *is* the one package. */
+    packages: PackageScope[];
+    /** One package by name, or `undefined` - for reaching a sibling's directory. */
+    package(name: string): PackageScope | undefined;
+}
+export interface GitScope {
+    branch: string | undefined;
+    sha: string | undefined;
+    shortSha: string | undefined;
+    /** Whether the working tree has uncommitted changes. */
+    dirty: boolean | undefined;
+}
+/**
+ * What a **value function** is handed - `clean: { include: ({ value, pkg }) => [...] }`.
+ *
+ * The same scope a `${{ }}` expression sees, plus `value`. There is no asymmetry between the two
+ * spellings and that is an invariant with a spec on it: the argument *is* the expression context
+ * with `value` on it, so a member defined straight onto the argument would split them silently and
+ * a config author would meet a name that works in one spelling and not the other.
+ *
+ * **The config's own top-level keys are bound bare too**, and they cannot be typed here - they come
+ * from the config being interpolated rather than from this object. Reach them through `pkg.config`
+ * when a type matters, or accept `any` from the bare name.
+ *
+ * **Not what a *step* function is handed.** `run.<script>.exec` and `version.<slot>` take a
+ * `RunStepFn`, which gets a `RunStepContext` (`pkg`, `repository`, `cwd`, `runBin`, `logger`) when
+ * its turn comes - a different object at a different time, which is the whole distinction the two
+ * forms exist to draw. Never widen a step key to accept this one.
+ */
+export interface ConfigValueContext extends ConfigScope {
+    /**
+     * What this key resolved to in the layers **below** this one - the list form of it, so
+     * `[...value, 'x']` needs no guard. `any` rather than a generic: the key's own type is what the
+     * function must return, while `value` is whatever the layers underneath happened to produce, and
+     * a scalar underneath arrives as a one-element list. See `previousValue`.
+     */
+    value: any;
+    /** The config's own top-level keys, bound bare - `vars`, `publish`, `clean`, … */
+    [key: string]: any;
+}

package/interfaces/config-scope.interface.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,10 +1,11 @@
 import type * as yargs from 'yargs';
 import type { RmanApplication } from '../core/application.js';
-import type { ConfigValue } from '../core/config.js';
-import type { CustomCommand } from '../core/custom-command.js';
-import type { Plugin } from '../core/plugin.js';
-import type { PublishTarget } from '../core/publish-target.js';
-import type { RunConditionFn, RunStepValue } from '../core/run-step.js';
+import type { CodeSubtree } from '../core/config/config-paths.js';
+import type { CustomCommand } from '../core/interfaces/custom-command.js';
+import type { Platform, Plugin } from '../core/interfaces/plugin.js';
+import type { PublishTarget } from '../core/interfaces/publish-target.js';
+import type { RunConditionFn, RunStepFn, RunStepValue } from '../core/interfaces/run-step.js';
+import type { ConfigValueContext } from './config-scope.interface.js';
 /**
  * The shape of `.rmanrc`/`.rmanrc.yml`/`.rmanrc.cjs`/`.mjs`/`.js` (and `package.json`'s own
  * `"rman"` key) - see docs/rman.md#configuration-rmanrc-rmanrcyml for the full reference. Every
@@ -127,6 +128,25 @@ export interface RmanConfigKeys {
      * package's own `.rmanrc` is never seen.
      */
     plugins?: string | Plugin | (string | Plugin)[];
+    /**
+     * **The technologies available here** - how a directory's packages are recognized, where they
+     * are, how their versions are planned.
+     *
+     * Each entry is a `Platform`, or a **glob** naming `.js` modules that `export default` one - the
+     * same two forms `plugins`, `commands` and `publishTargets` take. It **appends**: naming one
+     * never means "and drop the ones my preset brought", so a polyglot repository writes
+     * `extends: ['node', 'cargo']` and holds both.
+     *
+     * ```js
+     * // presets/node.js
+     * export default defineConfig({ platforms: [new NodePlatform()], commands, publishTargets });
+     * ```
+     *
+     * **Not the same key as `platform`** (singular), which *selects* one for a directory rather than
+     * contributing it: this says what is available, that says which one a package is. A package-level
+     * setting meant for one technology goes under `"[platform:node]"`.
+     */
+    platforms?: string | Platform | (string | Platform)[];
     /**
      * **Which technology a package belongs to**, by `Platform.name`.
      *
@@ -457,6 +477,16 @@ export declare namespace RmanConfig {
         command: string;
         /** Other names the command answers to - `list` is also `ls`. */
         aliases?: string[];
+        /**
+         * The technologies this command is for, by `Platform.name` - `['node']` for `clean` and `ci`,
+         * which only mean anything in an npm package. Absent means **every** platform, which is what a
+         * command that speaks for no one in particular says.
+         *
+         * It narrows what the command acts on: in a polyglot repository `rman clean` sweeps the node
+         * packages and leaves the Cargo ones alone, with no `--platform` and no check inside the
+         * command.
+         */
+        platforms?: string[];
         /**
          * yargs parser switches this command needs. `exec` is the only one so far and needs two:
          * `populate--` to keep everything after `--` out of its own options, and
@@ -898,4 +928,69 @@ type RequiredPositionalsOf<C extends string> = C extends `${string}<${infer N}>$
 /** A variadic positional (`[command..]`) collects a list; every other one is a single value. The
  *  command string is the only place that says which, since it is what yargs parses. */
 type PositionalValue<Cmd extends string, N extends string> = Cmd extends `${string}${'<' | '['}${N}..${string}` ? string[] : string;
+/**
+ * Identity helper for authoring a `.rmanrc.cjs`/`.mjs`/`.js` config with full type-checking and
+ * autocomplete - the same `defineConfig` pattern Vite/Vitest use. Returns `config` completely
+ * unchanged; this exists purely so TypeScript can infer/check against `RmanConfig`, not for any
+ * runtime behavior:
+ *
+ *   // .rmanrc.mjs
+ *   import { defineConfig } from 'rman';
+ *   export default defineConfig({ packageManager: 'pnpm' });
+ *
+ *   // .rmanrc.cjs
+ *   const { defineConfig } = require('rman');
+ *   module.exports = defineConfig({ packageManager: 'pnpm' });
+ */
+export declare function defineConfig(config: RmanConfig): RmanConfig;
+/**
+ * A config value that may be **written as a function instead**, computed per package at the moment
+ * the config resolves.
+ *
+ * `T` is what the function has to return, so the same checking applies either way - measured, with
+ * a control: a typo inside a wrapped object is still caught, and so is one inside an object a value
+ * function *returns*.
+ *
+ * **Not for a step key.** `run.<script>.before`/`.exec`/`.after`, `run.<script>.if` and
+ * `version.<slot>` already take a function, and it means something else there - code for `run` to
+ * call in its own time, with its own context. Wrapping one of those would produce a type that
+ * accepts a value function where a step is what actually runs. The key path decides which a
+ * function is (`STEP_PATHS`, `CODE_SUBTREES`), and the type can only follow that split by hand.
+ */
+export type ConfigValue<T> = T | ((ctx: ConfigValueContext) => T);
+/**
+ * The same config **after** it resolves: every `ConfigValue<T>` is just `T`, because
+ * `interpolateConfig` has already called it.
+ *
+ * **This is the half that lets `RmanConfig` be the author's type.** One type cannot answer both
+ * "what may I write?" (a function is fine - rman calls it) and "what do I get?" (never a function -
+ * it was already called), so it used to answer only the second, and writing a value function was a
+ * compile error the docs themselves committed. Widening `RmanConfig` alone just moves the problem:
+ * measured, six read sites needed a cast. The author's type widens and the *reader's* is computed
+ * from it - one derived type, applied at `Package.config`, rather than a second one to keep in step
+ * by hand.
+ *
+ * **Two guards, and each was measured by leaving it out.**
+ *
+ * - **Steps are named first.** A value function is recognised by its parameter, and
+ *   `ConfigValueContext` carries an index signature - so `RunStepFn` is assignable to it and a
+ *   `run.build.exec` function collapsed to its *return type*, leaving `RunService` nothing to call.
+ * - **`CODE_SUBTREES` is skipped, at every level.** `plugins`/`commands`/`publishTargets` hold code
+ *   all the way down, and the selector index (`[selector]: RmanConfig`) re-enters the config, so a
+ *   top-level-only guard misses the copy inside a `"[*]"` block. Left out, the walk reached
+ *   `Plugin.manifestProvider.versionScheme` and rewrote its **methods**: `smallestBump(): string`
+ *   became `string`, `bumpFor`/`isValid`/`compare`/`next` became `{}`. A function with *fewer*
+ *   parameters is assignable to one with more, so a zero-argument method matches the value-function
+ *   pattern - which makes this transform unsafe over any object carrying methods, and the guard the
+ *   only thing keeping one out of its way.
+ *
+ * Both lists are the runtime's own (`STEP_PATHS`' function types, `CODE_SUBTREES` itself), so the
+ * type follows the rule rather than restating it - the drift `ScopedVars` already demonstrated is
+ * not available here.
+ */
+export type Resolved<T> = T extends RunStepFn | RunConditionFn ? T : T extends (ctx: ConfigValueContext) => infer R ? R : T extends object ? {
+    [K in keyof T]: K extends CodeSubtree ? T[K] : Resolved<T[K]>;
+} : T;
+/** `pkg.config`'s type: what every command reads, with the value functions already called. */
+export type ResolvedConfig = Resolved<RmanConfig>;
 export {};

package/interfaces/rman-config.interface.js

@@ -59,3 +59,20 @@ export function registerCommand(def) {
 export function declareCommand(def) {
     return def;
 }
+/**
+ * Identity helper for authoring a `.rmanrc.cjs`/`.mjs`/`.js` config with full type-checking and
+ * autocomplete - the same `defineConfig` pattern Vite/Vitest use. Returns `config` completely
+ * unchanged; this exists purely so TypeScript can infer/check against `RmanConfig`, not for any
+ * runtime behavior:
+ *
+ *   // .rmanrc.mjs
+ *   import { defineConfig } from 'rman';
+ *   export default defineConfig({ packageManager: 'pnpm' });
+ *
+ *   // .rmanrc.cjs
+ *   const { defineConfig } = require('rman');
+ *   module.exports = defineConfig({ packageManager: 'pnpm' });
+ */
+export function defineConfig(config) {
+    return config;
+}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "rman",
   "description": "Repository manager",
-  "version": "2.0.0-beta.2",
+  "version": "2.0.0-beta.3",
   "author": "Panates",
   "license": "MIT",
   "dependencies": {
     "@netlify/parse-npm-script": "^0.1.2",
     "@xmldom/xmldom": "^0.9.12",
+    "@jsopen/objects": "^2.3.4",
     "ansi-colors": "^4.1.3",
     "cross-dirname": "^0.1.0",
     "easy-table": "^1.2.0",

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

@@ -1,4 +1,4 @@
-import type { Package } from '../core/package.js';
+import type { Package } from '../core/classes/package.js';
 import type { GitHelper } from '../utils/git.js';
 /**
  * Release boundaries and the tag names that mark them - **the single source for both directions**.
@@ -39,11 +39,33 @@ export declare namespace ChangeHashService {
          *  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*`). */
+    /**
+     * `.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 (`v*`).
+     *
+     * **Undeclared, the default is derived from how many version lines the repository has**, not
+     * fixed at `v*`. A repo-wide pattern has no `{name}`, so `findLatestTag` resolves it with `git
+     * describe --match` - the nearest tag HEAD descends from, whichever package it belongs to. That
+     * is exactly right while every package shares one line and **silently wrong** the moment they do
+     * not: measured on a two-line repository, releasing `pkg-a` put `v1.1.0` on HEAD, and `pkg-b` -
+     * which had a committed, unreleased `fix:` of its own sitting behind that tag - reported
+     * `no-change` and shipped nothing. Under `{name}@*` the same repository answers `bump 1.0.0 ->
+     * 1.0.1, changed since pkg-b@1.0.0`.
+     *
+     * So the choice is not a preference and should never have been one to remember: a repo-wide tag
+     * can only name a release that the whole repository shares. rman already decides the root's
+     * versioning scheme structurally from the same group count (`usesCalendarVersion`) - this is that
+     * rule applied to the other half of a release.
+     *
+     * **The root keeps `v*`.** It is never a member of any group, so the count says nothing about
+     * it, and the one caller that asks (`github-release`'s `releaseTagGlob`) only does so when the
+     * root is *not* on a calendar version - which is the single-line case, where `v*` is the answer
+     * anyway. With several lines the repository's release carries its own `version.releaseTagPattern`
+     * instead.
+     */
     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
@@ -51,6 +73,18 @@ export declare namespace ChangeHashService {
      *  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"). */
+    /**
+     * **Every pattern that may name this package's releases**, in precedence order - its own, and,
+     * only where the pattern was derived, the shared `v*` a repository used before it grew a second
+     * version line. One list, because two questions need it and must not disagree: `findLatestTag`
+     * picks the boundary off it, and `changelog`'s `splitByRelease` cuts the range at the tags it
+     * matches.
+     *
+     * They *did* disagree, for one commit: the boundary fell back to the shared tag while the split
+     * still looked only for `{name}@*`, which a repository mid-transition has none of - so a backfill
+     * reaching across twelve releases found no tag to cut at and rendered all of them as one.
+     */
+    function releaseTagPatterns(pkg: Package): string[];
     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/services/change-hash.service.js

@@ -1,4 +1,5 @@
-import { Manifest } from '../core/manifest.js';
+import { Manifest } from '../core/interfaces/manifest.js';
+import { versionLineCount } from '../utils/version-group.js';
 /**
  * Release boundaries and the tag names that mark them - **the single source for both directions**.
  *
@@ -16,14 +17,35 @@ export var 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*`). */
+    /**
+     * `.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 (`v*`).
+     *
+     * **Undeclared, the default is derived from how many version lines the repository has**, not
+     * fixed at `v*`. A repo-wide pattern has no `{name}`, so `findLatestTag` resolves it with `git
+     * describe --match` - the nearest tag HEAD descends from, whichever package it belongs to. That
+     * is exactly right while every package shares one line and **silently wrong** the moment they do
+     * not: measured on a two-line repository, releasing `pkg-a` put `v1.1.0` on HEAD, and `pkg-b` -
+     * which had a committed, unreleased `fix:` of its own sitting behind that tag - reported
+     * `no-change` and shipped nothing. Under `{name}@*` the same repository answers `bump 1.0.0 ->
+     * 1.0.1, changed since pkg-b@1.0.0`.
+     *
+     * So the choice is not a preference and should never have been one to remember: a repo-wide tag
+     * can only name a release that the whole repository shares. rman already decides the root's
+     * versioning scheme structurally from the same group count (`usesCalendarVersion`) - this is that
+     * rule applied to the other half of a release.
+     *
+     * **The root keeps `v*`.** It is never a member of any group, so the count says nothing about
+     * it, and the one caller that asks (`github-release`'s `releaseTagGlob`) only does so when the
+     * root is *not* on a calendar version - which is the single-line case, where `v*` is the answer
+     * anyway. With several lines the repository's release carries its own `version.releaseTagPattern`
+     * instead.
+     */
     function tagPattern(pkg) {
-        const cfg = pkg.config?.changelog;
-        return typeof cfg?.tagPattern === 'string' && cfg.tagPattern ? cfg.tagPattern : DEFAULT_TAG_PATTERN;
+        return resolvePattern(pkg).pattern;
     }
     ChangeHashService.tagPattern = tagPattern;
     /** This package's most recent release tag - the `{name}`-bearing pattern looks up that package's
@@ -32,10 +54,49 @@ export var ChangeHashService;
      *  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"). */
+    /**
+     * **Every pattern that may name this package's releases**, in precedence order - its own, and,
+     * only where the pattern was derived, the shared `v*` a repository used before it grew a second
+     * version line. One list, because two questions need it and must not disagree: `findLatestTag`
+     * picks the boundary off it, and `changelog`'s `splitByRelease` cuts the range at the tags it
+     * matches.
+     *
+     * They *did* disagree, for one commit: the boundary fell back to the shared tag while the split
+     * still looked only for `{name}@*`, which a repository mid-transition has none of - so a backfill
+     * reaching across twelve releases found no tag to cut at and rendered all of them as one.
+     */
+    function releaseTagPatterns(pkg) {
+        const { pattern, derived } = resolvePattern(pkg);
+        const expanded = pattern.replace('{name}', pkg.name);
+        return derived && expanded !== SHARED_TAG_PATTERN ? [expanded, SHARED_TAG_PATTERN] : [expanded];
+    }
+    ChangeHashService.releaseTagPatterns = releaseTagPatterns;
     async function findLatestTag(git, pkg) {
-        const pattern = tagPattern(pkg);
+        const { pattern, derived } = resolvePattern(pkg);
         const expanded = pattern.replace('{name}', pkg.name);
-        return pattern.includes('{name}') ? (await git.listTags(expanded))[0] : await git.describeTag(expanded);
+        if (!pattern.includes('{name}'))
+            return git.describeTag(expanded);
+        const own = (await git.listTags(expanded))[0];
+        if (own || !derived)
+            return own;
+        /**
+         * **The bridge across the default changing.** A repository that released under `v*` and has
+         * since grown a second version line has no `{name}` tag for this package yet - and reading the
+         * whole history instead would re-propose everything ever committed. Measured on a real
+         * four-package repository: every package came back on `unreleased commits` and three of them
+         * jumped a major, because some commit in the full history said `feat!:`.
+         *
+         * Falling back to the repo-wide tag gives exactly the boundary that *was* correct - before the
+         * split, every package genuinely shared it - so the first run after the split reads the same
+         * commits it would have read yesterday, and writes a `{name}` tag that every run after it
+         * finds directly. One transition, no manual tagging, no invented release.
+         *
+         * **Only when the pattern was derived.** A repository that asked for `{name}@*` in its own
+         * `.rmanrc` has said what names its tags; borrowing a `v*` tag it never asked about could hand
+         * a package a boundary belonging to something else entirely, and reading too little is the
+         * failure that ships nothing and says nothing.
+         */
+        return git.describeTag(SHARED_TAG_PATTERN);
     }
     ChangeHashService.findLatestTag = findLatestTag;
     /** The forward direction of `findLatestTag`: expands `pkg`'s (cascaded) `.rmanrc
@@ -109,4 +170,22 @@ export var ChangeHashService;
     }
     ChangeHashService.detect = detect;
 })(ChangeHashService || (ChangeHashService = {}));
-const DEFAULT_TAG_PATTERN = 'v*';
+/** One tag for the whole repository - right while every package releases on one line. */
+const SHARED_TAG_PATTERN = 'v*';
+/** One tag per package - the scheme lerna and changesets use, and the only one that can name a
+ *  release when a repository has more than one version line. */
+const PER_PACKAGE_TAG_PATTERN = '{name}@*';
+/**
+ * The pattern plus **where it came from**, which `findLatestTag` needs and callers do not: the
+ * bridge to a repo-wide tag applies only where rman changed the answer itself, never over a
+ * repository's own declaration.
+ */
+function resolvePattern(pkg) {
+    const configured = pkg.config?.changelog?.tagPattern;
+    if (typeof configured === 'string' && configured)
+        return { pattern: configured, derived: false };
+    if (pkg.isRoot)
+        return { pattern: SHARED_TAG_PATTERN, derived: true };
+    const several = versionLineCount(pkg) > 1;
+    return { pattern: several ? PER_PACKAGE_TAG_PATTERN : SHARED_TAG_PATTERN, derived: true };
+}

package/services/changelog.service.d.ts

@@ -1,5 +1,5 @@
-import type { Package } from '../core/package.js';
-import { Service } from '../core/service.js';
+import type { Package } from '../core/classes/package.js';
+import { Service } from '../core/classes/service.js';
 import { type PackageFilterOptions } from '../utils/package-filter.js';
 /**
  * A service class - see `ListService` for the shape and `Service` for the three measured
@@ -89,6 +89,21 @@ export declare namespace ChangelogService {
          *  the number and has to say so, otherwise every entry ends up labelled with the *previous*
          *  release's version. */
         version?: string;
+        /**
+         * Set by `generateToFile`; there is no reason for a caller to pass it. It tells `getEntries`
+         * that the entries are about to be **appended to a file**, which is what makes the file's own
+         * record of where it stopped the right boundary - see `resolveBoundary`. A print run asks a
+         * different question and deliberately ignores all of it.
+         */
+        write?: boolean;
+        /** Where this package's changelog begins - a version or release tag, a `YYYY-MM-DD` date, or a
+         *  commit. Releases below it are left out. `.rmanrc changelog.startingAt` when omitted; see
+         *  `resolveStartingPoint` for how the three forms are told apart. */
+        startingAt?: string;
+        /** Whether the not-yet-released commits get an entry - `.rmanrc changelog.unreleased` when
+         *  omitted, and `true` when neither says. A caller passing `version` always gets it, since that
+         *  names the release being cut; see `resolveUnreleased`. */
+        unreleased?: boolean;
     }
     /** One package's (root included) generated changelog entry - what `getEntries`/`generate`
      *  return. */
@@ -100,6 +115,19 @@ export declare namespace ChangelogService {
         /** `options.version` when the caller gave one, otherwise resolved from git tags rather than
          *  package.json - see `resolveVersion`. */
         version: string;
+        /** The last commit this entry covers. `generateToFile` writes it into the file as the marker
+         *  the next run starts from - see `Entry.filePath`. */
+        documentedUpTo: string;
+        /** Every section this entry renders, in the order it renders them - the heading a repository
+         *  chose through `.rmanrc changelog.titles`, and the lines under it. */
+        sections: {
+            title: string;
+            lines: string[];
+        }[];
+        /** The three buckets `Entry` carried before headings were configurable, derived from
+         *  `sections` so they keep meaning what they meant: whatever `feat` and `fix` are listed under,
+         *  and everything else together. A repository that adds a section of its own finds it in
+         *  `other` - the only honest slot for it in a shape that has three. */
         features: string[];
         fixes: string[];
         other: string[];
@@ -110,7 +138,7 @@ export declare namespace ChangelogService {
         filePath: string;
     }
 }
-declare module '../core/service.js' {
+declare module '../core/classes/service.js' {
     interface ServiceMap {
         changelog: ChangelogService;
     }