rman 1.3.0 → 2.0.0-beta.3

package/interfaces/rman-config.interface.js

@@ -1 +1,78 @@
-export {};
+export const commandRegistry = [];
+/**
+ * Registers a command and hands the register function straight back.
+ *
+ * **It returns the function, not the command's config, and that is the point.** The function has
+ * not run yet - it runs during init, once there is a `Repository` - so at registration time no
+ * config object exists to return. Declaring one anyway is what made the old body
+ * (`return def['config']`) uncompilable: `def` is a function, and `config` belongs to what it
+ * *returns*.
+ *
+ * Nothing is lost by being honest, because the metadata type rides along on the return type:
+ * `ReturnType<typeof someCommand>` is the `CommandMetadata`, and `CommandConfigFromMetadata` maps
+ * it to the config object the command contributes. A phantom property carrying the config type was
+ * tried and is unnecessary for exactly this reason - and it would not have survived being stored in
+ * `commandRegistry`, whose element type erases it.
+ *
+ * **`M` is inferred from the metadata rather than from the function, so that the same position can
+ * check it.** With the plainer `<T extends CommandRegisterFunction>(def: T)`, `T` is inferred from
+ * the literal itself, so the constraint is a subtype check - and a subtype check does no
+ * excess-property checking. Measured: `anotherBogusTopLevelKey: true` and a `totallyBogusKey`
+ * inside an option both compiled silently, which is how `cliName` and `examples` went unnoticed in
+ * `version.command.ts`. `M & ValidMeta<M>` keeps the bare `M` as the inference site and puts the
+ * check beside it, so a misspelled key now errors on its own line and names itself.
+ *
+ * **A command's `command` string needs `as const`** for the config key to be derivable from it
+ * (`'version [bump]' as const` -> `'version'`). `type: 'string'` survives inference on its own,
+ * since `yargs.Options['type']` is a union of literals and a union suppresses widening; `command`
+ * is a plain `string`, so it widens without the assertion. Spelling it `` `${string}` `` does not
+ * help - measured; that trick only applies where the constraint sits on the generic parameter.
+ */
+export function registerCommand(def) {
+    /** The same cast `declareCommand` makes, rather than a call to it: passing `def` through would
+     *  re-infer `M` from a type that already carries `ValidMeta<M>`, and the check then compounds
+     *  onto itself (`Exact<M & Exact<M, …>, …>`) and fails on every command. Two lines, one cast
+     *  each, is the honest shape. */
+    const fn = def;
+    commandRegistry.push(fn);
+    return fn;
+}
+/**
+ * The same declaration, **without** the registration - for a command that must exist only when
+ * something asks for it.
+ *
+ * That is exactly a contributed command's situation: `commandRegistry` is a module-level array
+ * walked by every `runCli`, so a package pushing onto it would give its commands to repositories
+ * that never named it - the module is imported as soon as anything imports the package. A package
+ * puts the function in its config's `commands` instead, and `cli.ts` calls it once the repository
+ * exists.
+ *
+ * **Why a factory rather than the metadata itself**: the config is resolved *inside*
+ * `Repository.create`, before the packages are known (plugins are what find them), so
+ * `app.repository` throws at that point. The function is stored unrun and called later, in
+ * `cli.ts`, where the built-ins' own factories run.
+ *
+ * Everything `registerCommand` documents about inference - `M & ValidMeta<M>`, the `as const` on
+ * `command`, the metadata riding on the return type - applies here unchanged; the two differ in one
+ * line.
+ */
+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,11 +1,13 @@
 {
   "name": "rman",
   "description": "Repository manager",
-  "version": "1.3.0",
+  "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**.
@@ -24,7 +24,7 @@ export declare namespace ChangeHashService {
          *
          * 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
+         * `Plugin.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.
          */
@@ -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
@@ -76,7 +110,7 @@ export declare namespace ChangeHashService {
      * 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
+     * reports as its published version (`Plugin.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

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
@@ -77,7 +138,7 @@ export var ChangeHashService;
      * 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
+     * reports as its published version (`Plugin.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
@@ -91,7 +152,7 @@ export var ChangeHashService;
         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
+             *  this package is the `Plugin`'s manifest members'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);
@@ -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,20 +1,74 @@
-import type { Package } from '../core/package.js';
-import type { Repository } from '../core/repository.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
+ * consequences a namespace had. `repository` left the signature because the application carries it.
+ */
+export declare class ChangelogService extends Service {
+    /**
+     * Same as `getEntries`, and additionally - for every returned entry, when `options.write` is
+     * set - prepends `entry.content` into that package's own changelog file (see `ChangelogService.Entry.filePath`).
+     * Still pure with respect to console output: writing a file is a real, callable-for-its-own-
+     * sake side effect (a "save this" request), not presentation, so it stays here rather than in
+     * the CLI command - printing what happened is the command's job.
+     */
+    generateToFile(options?: ChangelogService.Options): Promise<ChangelogService.Entry[]>;
+    /**
+     * Computes a changelog entry per package (root included) from real commits only - either
+     * everything since a given `--from <hash>` (applied the same way to every package), or, by
+     * default, auto-detected per package instead (see `detectChangeHash`). Pure: returns the
+     * entries, never prints or touches `CHANGELOG.md` - see `generate` for that.
+     *
+     * A commit is attributed to every package its files fall under (root included, for anything
+     * outside every package) - unless it's broad enough to count as a repo-wide change (see
+     * `BROAD_COMMIT_THRESHOLD`/`ownersOf`), in which case it goes to root alone instead of being
+     * repeated verbatim across most of the repository. Subject lines are grouped ✨ Features/🐛 Bug
+     * Fixes/🔧 Other Changes on a best-effort Conventional Commits read; anything that doesn't parse
+     * just lands in Other Changes as-is, so a repo that doesn't follow that convention still gets a
+     * usable list. `.rmanrc changelog.ignoreTypes` (cascaded, e.g. `[chore, dev]`) drops commits of
+     * those types entirely instead - see `ignoreTypesConfig`. A release marker - a bare version-bump
+     * commit (`"6.0.1"`), or any of the messages `version` itself writes - is always dropped
+     * outright, regardless of `ignoreTypes`; see `isReleaseCommit`.
+     *
+     * By default (or with `--from npm` explicitly), the boundary is auto-detected per package
+     * instead of one shared one - see `detectChangeHash`. A package that can't be resolved this way
+     * (unpublished, no network, no matching tag) has never been released at all, so its whole
+     * history counts as unreleased - the same view `version` takes, so a first-ever release still
+     * produces a real changelog. Packages that end up resolving to
+     * the same hash (an explicit one, or several packages sharing one tag under fixed versioning)
+     * only have their commits fetched once, not once per package.
+     *
+     * Formatting comes from `.rmanrc changelog.template` - a *path* to a template file (not the
+     * template text itself, to keep `.rmanrc` readable), with `{{package}}`/`{{version}}`/
+     * `{{date}}`/`{{commits}}` (the full grouped block) and `{{features}}`/`{{fixes}}`/`{{other}}`
+     * (their bullet lists alone, for templates that want their own headings/order) - see
+     * `resolveTemplate`. `{{package}}` for the repository root is `"<repo dir name> repository"`
+     * (e.g. "sqb repository"), not its raw package.json name - which is often a private,
+     * non-published placeholder (`"sqb.v4"`) that reads like a stray version marker rather than a
+     * recognizable label. `{{version}}` comes from git tags, not package.json (which can drift out
+     * of sync with what's actually been released) - see `resolveVersion`/`.rmanrc
+     * changelog.tagPattern`.
+     *
+     * Run from inside a single package's own directory, it only covers that package unless
+     * `options.fromRoot` says otherwise (see `Repository.currentPackage`).
+     */
+    getEntries(options?: ChangelogService.Options): Promise<ChangelogService.Entry[]>;
+}
 export declare namespace ChangelogService {
     interface Options extends PackageFilterOptions {
         /** Generate the changelog since this commit/hash - applied the same way to every package.
          *  Default (also `"auto"` explicitly): auto-detect it per package instead, from that package's
          *  own most recent release tag first - the same lookup `VersionService`/`changed` use, so this
          *  never disagrees with them - falling back to whatever its own ecosystem's registry reports
-         *  only when it has no tag yet (`ManifestProvider.publishedVersion`, and only ever to guess a
+         *  only when it has no tag yet (`Plugin.publishedVersion`, and only ever to guess a
          *  tag name - see `detectChangeHash`); a package this can't be resolved for either way (never
          *  tagged, unpublished, no plugin) has never been released at all, so its whole history counts
          *  as unreleased - the same view `version` takes. */
         from?: string;
         /** Generate for the whole repository even when the current directory is inside a single
          *  package (which otherwise scopes it to just that package) - see `Repository.currentPackage`. */
-        root?: boolean;
+        fromRoot?: boolean;
         /** Where a package's changelog file lives, relative to *that package's own* directory -
          *  default `'CHANGELOG.md'`. Applies the same way to every package; for a package that wants
          *  its own filename instead, use `.rmanrc changelog.filePath` (cascaded, per-package
@@ -35,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. */
@@ -46,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[];
@@ -55,52 +137,9 @@ export declare namespace ChangelogService {
          *  package's own directory - see `GetOptions.filePath`. */
         filePath: string;
     }
-    /**
-     * Same as `getEntries`, and additionally - for every returned entry, when `options.write` is
-     * set - prepends `entry.content` into that package's own changelog file (see `Entry.filePath`).
-     * Still pure with respect to console output: writing a file is a real, callable-for-its-own-
-     * sake side effect (a "save this" request), not presentation, so it stays here rather than in
-     * the CLI command - printing what happened is the command's job.
-     */
-    function generateToFile(repository: Repository, options?: Options): Promise<Entry[]>;
-    /**
-     * Computes a changelog entry per package (root included) from real commits only - either
-     * everything since a given `--from <hash>` (applied the same way to every package), or, by
-     * default, auto-detected per package instead (see `detectChangeHash`). Pure: returns the
-     * entries, never prints or touches `CHANGELOG.md` - see `generate` for that.
-     *
-     * A commit is attributed to every package its files fall under (root included, for anything
-     * outside every package) - unless it's broad enough to count as a repo-wide change (see
-     * `BROAD_COMMIT_THRESHOLD`/`ownersOf`), in which case it goes to root alone instead of being
-     * repeated verbatim across most of the repository. Subject lines are grouped ✨ Features/🐛 Bug
-     * Fixes/🔧 Other Changes on a best-effort Conventional Commits read; anything that doesn't parse
-     * just lands in Other Changes as-is, so a repo that doesn't follow that convention still gets a
-     * usable list. `.rmanrc changelog.ignoreTypes` (cascaded, e.g. `[chore, dev]`) drops commits of
-     * those types entirely instead - see `ignoreTypesConfig`. A release marker - a bare version-bump
-     * commit (`"6.0.1"`), or any of the messages `version` itself writes - is always dropped
-     * outright, regardless of `ignoreTypes`; see `isReleaseCommit`.
-     *
-     * By default (or with `--from npm` explicitly), the boundary is auto-detected per package
-     * instead of one shared one - see `detectChangeHash`. A package that can't be resolved this way
-     * (unpublished, no network, no matching tag) has never been released at all, so its whole
-     * history counts as unreleased - the same view `version` takes, so a first-ever release still
-     * produces a real changelog. Packages that end up resolving to
-     * the same hash (an explicit one, or several packages sharing one tag under fixed versioning)
-     * only have their commits fetched once, not once per package.
-     *
-     * Formatting comes from `.rmanrc changelog.template` - a *path* to a template file (not the
-     * template text itself, to keep `.rmanrc` readable), with `{{package}}`/`{{version}}`/
-     * `{{date}}`/`{{commits}}` (the full grouped block) and `{{features}}`/`{{fixes}}`/`{{other}}`
-     * (their bullet lists alone, for templates that want their own headings/order) - see
-     * `resolveTemplate`. `{{package}}` for the repository root is `"<repo dir name> repository"`
-     * (e.g. "sqb repository"), not its raw package.json name - which is often a private,
-     * non-published placeholder (`"sqb.v4"`) that reads like a stray version marker rather than a
-     * recognizable label. `{{version}}` comes from git tags, not package.json (which can drift out
-     * of sync with what's actually been released) - see `resolveVersion`/`.rmanrc
-     * changelog.tagPattern`.
-     *
-     * Run from inside a single package's own directory, it only covers that package unless
-     * `options.root` says otherwise (see `Repository.currentPackage`).
-     */
-    function getEntries(repository: Repository, options?: Options): Promise<Entry[]>;
+}
+declare module '../core/classes/service.js' {
+    interface ServiceMap {
+        changelog: ChangelogService;
+    }
 }