rman 2.5.0 → 2.6.0

package/commands/changelog.command.d.ts

@@ -98,6 +98,48 @@ declare const config: {
         describe: string;
         type: "boolean";
     };
+    /**
+     * **What one changelog file is about.** `'package'` gives every package its own; `'group'` gives
+     * one to each set of packages that versions and releases together (`.rmanrc group`), written at
+     * the repository root - `CHANGELOG.md` for the default group, `CHANGELOG-<name>.md` for a named
+     * one. A `group: false` package is a group of itself either way, so its file stays its own.
+     *
+     * **`'package'` is the default because changing a repository's layout silently is not something a
+     * minor release may do**, not because it is the better answer. For a repository releasing along
+     * one line it is measurably the worse one: every package is bumped together, so most of them have
+     * no commit of their own and get a file that only ever says "Updated dependencies" - measured on
+     * `panates/sqb`, fifteen of seventeen. The whole release is then readable nowhere.
+     *
+     * Read off the repository root and nowhere else - see `changelogGroupBy`.
+     */
+    /**
+     * **The panel is drawn on stderr, not stdout**, which is the whole reason this needed a change
+     * rather than a call: `changelog` is `printsDocument`, so `rman changelog > NOTES.md` would
+     * otherwise capture the panel's cursor-movement codes into the notes. Same reasoning the status
+     * region already carries.
+     */
+    /**
+     * **Implies `--write`, because there is nothing else it could mean.** "Rebuild the changelog"
+     * with no file to rebuild would either print (which `rman changelog --from <first-tag>` already
+     * does) or silently do nothing; neither is what was asked for.
+     */
+    rebuild: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+    progress: {
+        target: "both";
+        describe: string;
+        type: "boolean";
+    };
+    groupBy: {
+        target: "both";
+        cliName: string;
+        describe: string;
+        type: "string";
+        choices: readonly ["package", "group"];
+    };
     startingAt: {
         target: "both";
         cliName: string;
@@ -278,6 +320,48 @@ declare const changelogCommand: (app: import("../index.js").RmanApplication) =>
             describe: string;
             type: "boolean";
         };
+        /**
+         * **What one changelog file is about.** `'package'` gives every package its own; `'group'` gives
+         * one to each set of packages that versions and releases together (`.rmanrc group`), written at
+         * the repository root - `CHANGELOG.md` for the default group, `CHANGELOG-<name>.md` for a named
+         * one. A `group: false` package is a group of itself either way, so its file stays its own.
+         *
+         * **`'package'` is the default because changing a repository's layout silently is not something a
+         * minor release may do**, not because it is the better answer. For a repository releasing along
+         * one line it is measurably the worse one: every package is bumped together, so most of them have
+         * no commit of their own and get a file that only ever says "Updated dependencies" - measured on
+         * `panates/sqb`, fifteen of seventeen. The whole release is then readable nowhere.
+         *
+         * Read off the repository root and nowhere else - see `changelogGroupBy`.
+         */
+        /**
+         * **The panel is drawn on stderr, not stdout**, which is the whole reason this needed a change
+         * rather than a call: `changelog` is `printsDocument`, so `rman changelog > NOTES.md` would
+         * otherwise capture the panel's cursor-movement codes into the notes. Same reasoning the status
+         * region already carries.
+         */
+        /**
+         * **Implies `--write`, because there is nothing else it could mean.** "Rebuild the changelog"
+         * with no file to rebuild would either print (which `rman changelog --from <first-tag>` already
+         * does) or silently do nothing; neither is what was asked for.
+         */
+        rebuild: {
+            target: "cli";
+            describe: string;
+            type: "boolean";
+        };
+        progress: {
+            target: "both";
+            describe: string;
+            type: "boolean";
+        };
+        groupBy: {
+            target: "both";
+            cliName: string;
+            describe: string;
+            type: "string";
+            choices: readonly ["package", "group"];
+        };
         startingAt: {
             target: "both";
             cliName: string;

package/commands/changelog.command.js

@@ -1,8 +1,10 @@
+import path from 'node:path';
 import colors from 'ansi-colors';
 import { registerCommand } from '../interfaces/rman-config.interface.js';
 import { ChangeHashService } from '../services/change-hash.service.js';
 import { Logger, resolveRootLogLevel } from '../utils/logger.js';
 import { fromRootOption, packageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';
+import { ProgressPanel } from '../utils/progress-panel.js';
 const COMMAND = 'changelog';
 const config = {
     ...packageFilterOptions,
@@ -122,6 +124,50 @@ const config = {
             '--no-unreleased for a changelog of released history only',
         type: 'boolean',
     },
+    /**
+     * **What one changelog file is about.** `'package'` gives every package its own; `'group'` gives
+     * one to each set of packages that versions and releases together (`.rmanrc group`), written at
+     * the repository root - `CHANGELOG.md` for the default group, `CHANGELOG-<name>.md` for a named
+     * one. A `group: false` package is a group of itself either way, so its file stays its own.
+     *
+     * **`'package'` is the default because changing a repository's layout silently is not something a
+     * minor release may do**, not because it is the better answer. For a repository releasing along
+     * one line it is measurably the worse one: every package is bumped together, so most of them have
+     * no commit of their own and get a file that only ever says "Updated dependencies" - measured on
+     * `panates/sqb`, fifteen of seventeen. The whole release is then readable nowhere.
+     *
+     * Read off the repository root and nowhere else - see `changelogGroupBy`.
+     */
+    /**
+     * **The panel is drawn on stderr, not stdout**, which is the whole reason this needed a change
+     * rather than a call: `changelog` is `printsDocument`, so `rman changelog > NOTES.md` would
+     * otherwise capture the panel's cursor-movement codes into the notes. Same reasoning the status
+     * region already carries.
+     */
+    /**
+     * **Implies `--write`, because there is nothing else it could mean.** "Rebuild the changelog"
+     * with no file to rebuild would either print (which `rman changelog --from <first-tag>` already
+     * does) or silently do nothing; neither is what was asked for.
+     */
+    rebuild: {
+        target: 'cli',
+        describe: 'Regenerate each changelog file from the whole history instead of appending to it - ' +
+            'implies --write, and replaces what is in the file rather than prepending to it',
+        type: 'boolean',
+    },
+    progress: {
+        target: 'both',
+        describe: 'Show a live progress panel (default: true; auto-disabled when stderr is not a TTY)',
+        type: 'boolean',
+    },
+    groupBy: {
+        target: 'both',
+        cliName: 'group-by',
+        describe: 'What one changelog file covers: "package" (default, one per package) or "group" (one per ' +
+            'set of packages released together, at the repository root)',
+        type: 'string',
+        choices: ['package', 'group'],
+    },
     startingAt: {
         target: 'both',
         cliName: 'starting-at',
@@ -148,13 +194,20 @@ const changelogCommand = registerCommand(app => {
         ],
         handler: async (args) => {
             const from = args.from;
-            const write = args.write;
+            const rebuild = !!args.rebuild;
+            const write = args.write || rebuild;
             const logger = new Logger(args.logLevel ?? resolveRootLogLevel(repository));
-            if (!from || from === ChangeHashService.AUTO) {
-                // Auto-detection is mostly local git work, but the registry fallback it can reach for
-                // (only when a package has no tag at all, and only if the package's own ecosystem provides
-                // one) is a network round trip per package - without this, the command looks hung for that
-                // stretch instead of just busy.
+            /**
+             * **The panel replaces the static line, and only where it can actually draw.** That line
+             * ("Detecting each package's last release...") answered "did it start" and then said nothing
+             * for the rest of the run - which is the longer half: measured on a `panates/sqb` backfill,
+             * boundary detection is 1.2s and reading the commits is 6.6s, one target at a time.
+             *
+             * Off it falls back to the line, because the two cases it is off in are exactly the two the
+             * line is for: a pipe, and `--no-progress`.
+             */
+            const panel = new ProgressPanel('CHANGELOG', (args.progress ?? resolveProgressConfig(repository)) !== false && !!process.stderr.isTTY, process.stderr);
+            if (!panel.enabled && (!from || from === ChangeHashService.AUTO)) {
                 logger.info(colors.gray("Detecting each package's last release..."));
             }
             const options = {
@@ -167,20 +220,110 @@ const changelogCommand = registerCommand(app => {
                 startingAt: args.startingAt,
                 unreleased: args.unreleased,
                 commitHash: args.commitHash,
+                groupBy: args.groupBy,
+                rebuild,
+                progress: panelReporter(panel),
             };
             const changelog = app.getService('changelog');
-            const entries = write ? await changelog.generateToFile(options) : await changelog.getEntries(options);
+            panel.start();
+            let entries;
+            try {
+                entries = write ? await changelog.generateToFile(options) : await changelog.getEntries(options);
+            }
+            finally {
+                /** In a `finally`, or a throw leaves the redraw interval running and the cursor parked
+                 *  inside a half-drawn block - the process then prints its error over the panel. */
+                panel.stop();
+            }
             if (!entries.length) {
                 logger.info(colors.gray('No unreleased changes.'));
                 return;
             }
-            for (const entry of entries) {
-                if (write)
-                    logger.info(colors.green('updated'), colors.cyan(entry.label), entry.filePath);
-                else
+            if (!write) {
+                for (const entry of entries)
                     console.log(entry.content);
+                return;
+            }
+            /**
+             * **One line per file, not one per entry.** An entry is a *release*, so a backfill produces
+             * several for the same file and printed per entry the run repeats `updated ... CHANGELOG.md`
+             * once per release it found - twelve identical lines on a real repository, saying nothing
+             * the first did not.
+             *
+             * The path is repository-relative and the label is gone with the repetition: `packages/core/
+             * CHANGELOG.md` already says which package it belongs to, and under
+             * `changelog.groupBy: 'group'` the label names a group while the path names the file that
+             * was actually written - which is what the reader is being told about.
+             */
+            for (const file of new Set(entries.map(e => e.file))) {
+                logger.info(colors.green('updated'), path.relative(repository.dirname, file));
             }
         },
     };
 });
+/** `.rmanrc changelog.progress`, off the **root** - one panel for the run, so one answer for the
+ *  repository, the rule `run`'s `concurrency` already follows. */
+function resolveProgressConfig(repository) {
+    const v = repository.rootPackage.config?.changelog?.progress;
+    return typeof v === 'boolean' ? v : undefined;
+}
+/**
+ * The panel, driven by what `ChangelogService` reports.
+ *
+ * A label sits at `pending` between its two phases on purpose: `detect` finishing does not finish
+ * the label, and the header's bar counts anything not pending as done - so marking it otherwise
+ * would show the run complete while the slow half had not started.
+ */
+const PHASE_LABELS = {
+    detect: 'detecting last release',
+    commits: 'reading commits',
+    render: 'writing changelog',
+};
+function panelReporter(panel) {
+    const items = new Map();
+    return {
+        start(labels) {
+            for (const label of labels)
+                items.set(label, panel.addItem(label));
+        },
+        step(label, phase) {
+            const item = items.get(label);
+            if (!item)
+                return;
+            item.currentStep = PHASE_LABELS[phase];
+            item.startedAt ??= Date.now();
+            /**
+             * **`detect` leaves the row pending on purpose.** Every label enters it at once and it is
+             * over in milliseconds; showing all of them "running" would fill the panel with rows that
+             * are about to go quiet again, and the header counts anything not pending as done.
+             */
+            item.status = phase === 'detect' ? 'pending' : 'running';
+            /** The counter belongs to `commits` alone - there it counts real work, and a `(1/3)` over
+             *  the other two would be counting phases, which the label already names. */
+            item.stepIndex = undefined;
+            item.stepsTotal = undefined;
+        },
+        commits(label, done, total) {
+            const item = items.get(label);
+            if (!item)
+                return;
+            /** **This is what the panel is for.** The row sat at one line for the whole of the slow
+             *  phase - measured on `panates/sqb`, minutes for a full rebuild's 1825 commits - because
+             *  the unit shown was files to write, and there is exactly one of those under
+             *  `changelog.groupBy: 'group'`. The commits are the work. */
+            item.stepsTotal = total;
+            /** 0-based: the panel renders `stepIndex + 1`, the way `RunService` sets it. */
+            item.stepIndex = Math.max(0, done - 1);
+        },
+        done(label, wrote) {
+            const item = items.get(label);
+            if (!item)
+                return;
+            /** Nothing to document is not a failure and not a success - it is the third thing the panel
+             *  already has a word for. */
+            item.status = wrote ? 'success' : 'skipped';
+            item.finishedAt = Date.now();
+        },
+    };
+}
 export default changelogCommand;

package/constants.js

@@ -1 +1 @@
-export const version = '2.5.0';
+export const version = '2.6.0';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rman",
   "description": "Repository manager",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "author": "Panates",
   "license": "MIT",
   "dependencies": {

package/services/changelog.service.d.ts

@@ -1,4 +1,5 @@
 import type { Package } from '../core/classes/package.js';
+import type { Repository } from '../core/classes/repository.js';
 import { Service } from '../core/classes/service.js';
 import { type PackageFilterOptions } from '../utils/package-filter.js';
 /**
@@ -55,6 +56,18 @@ export declare class ChangelogService extends Service {
      */
     getEntries(options?: ChangelogService.Options): Promise<ChangelogService.Entry[]>;
 }
+/**
+ * What one changelog file is about - `.rmanrc changelog.groupBy`, `'package'` when nothing says.
+ *
+ * **Read off the repository root and nowhere else.** It decides a *layout*, so there is one answer
+ * for the whole repository, exactly as `run`'s `concurrency` is the root's because there is one
+ * scheduler. Cascaded per package it would mean two packages of one group disagreeing about which
+ * file they share, which has no answer.
+ *
+ * `VersionService` asks too, so that `version --changelog` makes one call per file rather than one
+ * per package - the same entry prepended once per member otherwise.
+ */
+export declare function changelogGroupBy(repository: Repository, options?: ChangelogService.Options): 'package' | 'group';
 export declare namespace ChangelogService {
     interface Options extends PackageFilterOptions {
         /** Generate the changelog since this commit/hash - applied the same way to every package.
@@ -96,6 +109,10 @@ export declare namespace ChangelogService {
          * different question and deliberately ignores all of it.
          */
         write?: boolean;
+        /** Regenerate each file from the whole history rather than appending to what is there: the
+         *  file's own marker and `catchUpFile` are both ignored, and every file this run writes is
+         *  emptied first. Only meaningful with `write`; an explicit `from` still wins over it. */
+        rebuild?: 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. */
@@ -107,13 +124,58 @@ export declare namespace ChangelogService {
         /** Whether each line ends with its commit's short sha - `.rmanrc changelog.commitHash` when
          *  omitted, and `true` when neither says. See `withCommitHash`. */
         commitHash?: boolean;
+        /** What one changelog file is about - a package, or the group of packages that release
+         *  together. `.rmanrc changelog.groupBy` (read off the root) when omitted, and `'package'` when
+         *  neither says. See `changelogGroupBy` and `partitionTargets`. */
+        groupBy?: 'package' | 'group';
+        /** Where this run reports what it is doing, so a caller can draw a panel. Left out, nothing is
+         *  reported and nothing is printed - see `Progress`. */
+        progress?: Progress;
+    }
+    /**
+     * **What a run reports, for a caller that wants to render it.** `ChangelogService` prints
+     * nothing itself - `version --changelog` drives it in the middle of its own output, so a panel
+     * drawn from inside would land on top of that. The CLI implements this against `ProgressPanel`;
+     * every other caller leaves it out and the calls cost nothing.
+     *
+     * A label names a **file** rather than a package, since that is the unit under
+     * `changelog.groupBy: 'group'` - it is the same string `Entry.label` carries.
+     */
+    interface Progress {
+        /** Every label this run will work through, before any of it starts. */
+        start(labels: string[]): void;
+        /**
+         * A label entered a phase, in this order:
+         *
+         * - `'detect'` - resolving its boundary. Every label enters this at once, and it is quick.
+         * - `'commits'` - reading and parsing the range. **The slow one**, two `git show` per commit,
+         *   one commit at a time; `commits()` counts it.
+         * - `'render'` - cutting into releases, grouping and templating. No git, so however long the
+         *   list is this is the fast one.
+         */
+        step(label: string, phase: 'detect' | 'commits' | 'render'): void;
+        /**
+         * How far the `'commits'` phase has got - `done` of `total`, called with `(0, total)` first so
+         * the total is known while the count is still zero.
+         *
+         * Optional because it is the only member that fires per *commit* rather than per label: a
+         * reporter that only wants the phases leaves it out and pays nothing.
+         */
+        commits?(label: string, done: number, total: number): void;
+        /** A label is finished. `wrote` is false when the range produced no entry for it. */
+        done(label: string, wrote: boolean): void;
     }
     /** One package's (root included) generated changelog entry - what `getEntries`/`generate`
      *  return. */
     interface Entry {
+        /** **Whose directory holds the file**, which under `groupBy: 'group'` is the repository root
+         *  for every group of more than one - the entry is about all of them. The member whose config
+         *  and tags the entry was resolved from is not carried: it is an implementation detail of the
+         *  group, and naming one member here would read as the entry being that package's. */
         package: Package;
-        /** Display name for this entry's heading - `"<repo dir name> repository"` for the root
-         *  package, its own name otherwise (see `getEntries`'s doc comment on `{{package}}`). */
+        /** Display name for this entry's heading - the group's name under `groupBy: 'group'`,
+         *  `"<repo dir name> repository"` for the root package, its own name otherwise (see
+         *  `getEntries`'s doc comment on `{{package}}`). */
         label: string;
         /** `options.version` when the caller gave one, otherwise resolved from git tags rather than
          *  package.json - see `resolveVersion`. */
@@ -136,8 +198,12 @@ export declare namespace ChangelogService {
         other: string[];
         /** The fully rendered entry, via `.rmanrc changelog.template` (or the built-in default). */
         content: string;
-        /** Where this entry would be (or, with `options.write`, was) written, relative to the
-         *  package's own directory - see `GetOptions.filePath`. */
+        /** Where this entry would be (or, with `options.write`, was) written - **absolute**, and what
+         *  `generateToFile` writes to. A caller needing the path resolves it from here rather than
+         *  rebuilding it from `package` and `filePath`, which a group's file cannot be rebuilt from:
+         *  its name carries the group. */
+        file: string;
+        /** `file` relative to `package`'s own directory, for display - see `Options.filePath`. */
         filePath: string;
     }
 }

package/services/changelog.service.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { Service } from '../core/classes/service.js';
 import { GitHelper } from '../utils/git.js';
 import { filterPackages } from '../utils/package-filter.js';
+import { groupKeyOf } from '../utils/version-group.js';
 import { ChangeHashService } from './change-hash.service.js';
 import { ConventionalCommitsService } from './conventional-commits.service.js';
 /**
@@ -19,6 +20,19 @@ export class ChangelogService extends Service {
      */
     async generateToFile(options = {}) {
         const entries = await this.getEntries({ ...options, write: true });
+        /**
+         * **`rebuild` empties each file before anything is prepended, once.** Without it the
+         * regenerated history lands *on top of* the history already in the file - every release
+         * written twice, which is the one outcome a rebuild must not produce.
+         *
+         * Only files this run actually produced an entry for: a file the run has nothing to say about
+         * is left alone rather than deleted, since emptying it would lose what is there and put
+         * nothing back.
+         */
+        if (options.rebuild) {
+            for (const file of new Set(entries.map(e => e.file)))
+                fs.rmSync(file, { force: true });
+        }
         /**
          * **Where each file is documented up to, recorded in the file itself.** Read back by
          * `resolveBoundary` on the next run, which is what makes a second `--write` append the commits
@@ -34,7 +48,7 @@ export class ChangelogService extends Service {
          * for a file leaves the newest documented commit behind it.
          */
         for (const entry of entries) {
-            prependToChangelogFile(entry.package, entry.filePath, entry.content, entry.documentedUpTo);
+            prependToChangelogFile(entry.file, entry.content, entry.documentedUpTo);
         }
         return entries;
     }
@@ -91,10 +105,15 @@ export class ChangelogService extends Service {
         // all of them the same way; under fixed versioning, npm auto-detection usually does too) - so
         // the git fetch for a given hash is cached, run once no matter how many packages share it.
         const commitsByHash = new Map();
-        const listCommitsCached = (hash) => {
+        /** `label` only steers the progress report, and only for the target that *triggers* the fetch:
+         *  several targets sharing a boundary share one fetch, so the commits are counted under
+         *  whichever asked first. Reporting it per sharer would mean either several fetches or several
+         *  rows counting the same work. */
+        const listCommitsCached = (hash, label) => {
             const key = hash ?? '';
             let promise = commitsByHash.get(key);
             if (!promise) {
+                const onProgress = (done, total) => options.progress?.commits?.(label, done, total);
                 // No boundary at all means nothing has ever been released, so everything so far is
                 // unreleased - the same fallback `VersionService` makes. (Not "not yet pushed": that reads
                 // as empty the moment a first release is pushed, and for a repo with no remote at all.)
@@ -105,20 +124,48 @@ export class ChangelogService extends Service {
                  * against shas that are no longer in the list - every cut silently missed, and the whole
                  * range rendered as one release. Measured while writing it.
                  */
-                promise = hash ? git.listCommits({ hash }) : git.listAllCommits();
+                promise = hash ? git.listCommits({ hash, onProgress }) : git.listAllCommits({ onProgress });
                 commitsByHash.set(key, promise);
             }
             return promise;
         };
-        const commitsByTarget = await Promise.all(targets.map(async (pkg) => {
-            const changelogFile = path.join(pkg.dirname, resolveFilePath(pkg, options.filePath));
-            const from = await resolveBoundary(git, pkg, changelogFile, options);
-            return listCommitsCached(from);
+        /**
+         * **The unit is a changelog group, not a package** - see `partitionTargets`. Under the default
+         * `groupBy: 'package'` every target is a group of one, so everything below reads exactly as it
+         * did when this loop was written against packages.
+         */
+        const groups = partitionTargets(repository, targets, options);
+        /** **Reported, never printed** - this service stays pure with respect to the console, which is
+         *  not tidiness here: `version --changelog` calls it in the middle of its own output, and a
+         *  panel painted from in here would land on top of that. */
+        const progress = options.progress;
+        progress?.start(groups.map(g => g.label));
+        /** Every boundary resolves at once - `Promise.all` over the groups, and `GitHelper` spawns
+         *  through `execFile`, so nothing below serializes them. Measured on `panates/sqb`: 18 targets,
+         *  18 concurrent `git describe`, 1.2s wall against 1.8s of summed duration. Within one target
+         *  the steps are a chain (tag -> registry -> file -> merge-base) and cannot be. */
+        const commitsByTarget = await Promise.all(groups.map(async (group) => {
+            progress?.step(group.label, 'detect');
+            const from = await resolveBoundary(git, group.home, group.file, options);
+            /** **Reading the range happens here, not in the loop below**, which is what makes this the
+             *  phase a panel has to name: the boundary is resolved and then every commit after it is
+             *  fetched, still inside this `Promise.all`. The loop below is `splitByRelease`, the
+             *  grouping and the template - all in memory. */
+            progress?.step(group.label, 'commits');
+            return listCommitsCached(from, group.label);
         }));
         const entries = [];
-        for (let i = 0; i < targets.length; i++) {
-            const pkg = targets[i];
-            const label = pkg === repository.rootPackage ? `${path.basename(repository.dirname)} repository` : pkg.name;
+        for (let i = 0; i < groups.length; i++) {
+            const group = groups[i];
+            /** Every per-package question - the boundary, the tag pattern, the titles, the template -
+             *  is asked of one member, because a group is by definition the packages that release
+             *  together and therefore answer these the same way. */
+            const pkg = group.home;
+            const label = group.label;
+            /** Cutting the range into releases, grouping the subjects and rendering - no git left, so
+             *  this is the fast phase however long the list is. */
+            progress?.step(label, 'render');
+            const entriesBefore = entries.length;
             /**
              * **One entry per release in the range, not one entry per package.** The range is whatever
              * the boundary opened up, and a release tag inside it ends a release: a changelog that does
@@ -140,7 +187,9 @@ export class ChangelogService extends Service {
                     continue;
                 if (await isBelowStartingPoint(git, pkg, segment, floor, floorIndex))
                     continue;
-                const ownCommits = dropVersionBumps(segment.commits).filter(c => ownersOf(repository, c).has(pkg));
+                /** A commit belongs to a group when it belongs to **any** of its members - one line for a
+                 *  commit touching two of them, which is the whole reason a group shares a file. */
+                const ownCommits = dropVersionBumps(segment.commits).filter(c => [...ownersOf(repository, c)].some(owner => group.members.has(owner)));
                 if (!ownCommits.length)
                     continue;
                 const sections = groupCommits(ownCommits, ignoreTypesConfig(pkg), titles, order, withCommitHash(pkg, options));
@@ -148,9 +197,9 @@ export class ChangelogService extends Service {
                 // rather than rendering a heading with nothing real underneath it.
                 if (!sections.length)
                     continue;
-                const { version, content } = await renderEntry(repository, pkg, label, sections, titles, git, options.version, segment.tag);
+                const { version, content } = await renderEntry(repository, pkg, label, sections, titles, git, options.version, segment.tag, group.grouped);
                 entries.push({
-                    package: pkg,
+                    package: group.filePkg,
                     label,
                     version,
                     /** The last commit this entry covers - what the file's marker records. For a tagged
@@ -160,13 +209,32 @@ export class ChangelogService extends Service {
                     sections,
                     ...legacyBuckets(sections, titles),
                     content,
-                    filePath: resolveFilePath(pkg, options.filePath),
+                    file: group.file,
+                    filePath: path.relative(group.filePkg.dirname, group.file),
                 });
             }
+            /** `false` where the range held nothing this target owns, or `ignoreTypes` emptied it - an
+             *  answer, not a failure, which is why it is a flag rather than a status. */
+            progress?.done(label, entries.length > entriesBefore);
         }
         return entries;
     }
 }
+/**
+ * What one changelog file is about - `.rmanrc changelog.groupBy`, `'package'` when nothing says.
+ *
+ * **Read off the repository root and nowhere else.** It decides a *layout*, so there is one answer
+ * for the whole repository, exactly as `run`'s `concurrency` is the root's because there is one
+ * scheduler. Cascaded per package it would mean two packages of one group disagreeing about which
+ * file they share, which has no answer.
+ *
+ * `VersionService` asks too, so that `version --changelog` makes one call per file rather than one
+ * per package - the same entry prepended once per member otherwise.
+ */
+export function changelogGroupBy(repository, options = {}) {
+    const declared = options.groupBy ?? repository.rootPackage.config?.changelog?.groupBy;
+    return declared === 'group' ? 'group' : 'package';
+}
 /** `.rmanrc changelog.ignoreTypes` (cascaded, per-package overridable) - Conventional Commits
  *  `type`s to drop entirely (e.g. `[chore, dev]`), not just fold into "General Changes". Only
  *  applies to commits that actually parse as `type: ...` - a non-conventional message always
@@ -514,6 +582,59 @@ function resolveFilePath(pkg, optionsFilePath) {
     const cfg = pkg.config?.changelog?.filePath;
     return typeof cfg === 'string' && cfg ? cfg : DEFAULT_CHANGELOG_FILE;
 }
+/**
+ * The targets cut into the files they will be written to.
+ *
+ * **One rule, not two.** A changelog belongs to the set of packages that version and release
+ * together - `.rmanrc group`, the same key `version` batches its plan by - and `group: false`
+ * already makes a package a group of itself. So a solo group's file is its package's own, and
+ * anything wider goes to the repository root, where it is the one file describing that release.
+ *
+ * Under the default `groupBy: 'package'` every target is made a group of one, so this returns
+ * exactly what the loop saw when it was written against packages. That is the whole of the
+ * opt-out: no repository's layout changes until it asks.
+ *
+ * The default group is unsuffixed (`CHANGELOG.md`), since a repository releasing along one line has
+ * nothing to distinguish it from; a named group takes its name (`CHANGELOG-core.md`). The name is
+ * checked where it is read - see `groupKeyOf` - so nothing has to be escaped here.
+ */
+function partitionTargets(repository, targets, options) {
+    const grouping = changelogGroupBy(repository, options);
+    const byKey = new Map();
+    for (const pkg of targets) {
+        const key = grouping === 'group' ? groupKeyOf(pkg) : `solo:${pkg.name}`;
+        const members = byKey.get(key);
+        if (members)
+            members.push(pkg);
+        else
+            byKey.set(key, [pkg]);
+    }
+    const repositoryLabel = `${path.basename(repository.dirname)} repository`;
+    return [...byKey].map(([key, members]) => {
+        /** `targets` starts at the root, so a group holding it has it first - which is what makes the
+         *  root the `home` of the default group without a second rule saying so. */
+        const home = members[0];
+        const grouped = !key.startsWith('solo:');
+        const named = key.startsWith('named:') ? key.slice('named:'.length) : undefined;
+        const filePkg = grouped ? repository.rootPackage : home;
+        return {
+            home,
+            filePkg,
+            grouped,
+            members: new Set(members),
+            label: named ?? (home === repository.rootPackage ? repositoryLabel : home.name),
+            file: path.join(filePkg.dirname, suffixFileName(resolveFilePath(home, options.filePath), named)),
+        };
+    });
+}
+/** `CHANGELOG.md` + `core` -> `CHANGELOG-core.md`, keeping whatever directory and extension
+ *  `changelog.filePath` chose (`docs/HISTORY.md` -> `docs/HISTORY-core.md`). */
+function suffixFileName(filePath, suffix) {
+    if (!suffix)
+        return filePath;
+    const ext = path.extname(filePath);
+    return path.join(path.dirname(filePath), `${path.basename(filePath, ext)}-${suffix}${ext}`);
+}
 /**
  * This package's current version, from git tags rather than its (possibly stale - see the
  * `{{version}}` doc on `Changelog.getEntries`) package.json. Falls back to package.json's version
@@ -533,17 +654,27 @@ function resolveFilePath(pkg, optionsFilePath) {
  * entry before it commits and tags), so there is no tag to read a date off and the clock is the
  * only answer. That is why this is decided here, beside the version, rather than at the template.
  */
-async function resolveHeading(git, pkg, label, versionOverride, segmentTag) {
+async function resolveHeading(git, pkg, label, versionOverride, segmentTag, grouped) {
     const today = new Date().toISOString().slice(0, 10);
-    const expanded = ChangeHashService.tagPattern(pkg).replace('{name}', pkg.name);
+    const pattern = ChangeHashService.tagPattern(pkg);
+    const expanded = pattern.replace('{name}', pkg.name);
+    /**
+     * **A group's heading may not be one member's tag.** Under a repo-wide pattern the tag is already
+     * package-neutral (`v1.2.3`) and is the best heading there is. Under `{name}@*` it is
+     * `pkg-a@1.2.3` - one member's name over a file describing the whole group, and a different
+     * member's name each time the first one changes. There the group's own label carries it.
+     */
+    const ownTag = !grouped || !pattern.includes('{name}');
+    const groupHeading = (version) => `${label} ${version}`;
     /** A segment that a release tag closes is headed by **that** release, whatever the newest one
      *  is - which is the whole point of splitting, and the reason an override cannot win here: a
      *  caller naming a version is naming the *unreleased* one, the segment with no tag. */
     if (segmentTag) {
+        const version = ChangeHashService.extractVersion(segmentTag, expanded);
         return {
-            version: ChangeHashService.extractVersion(segmentTag, expanded),
+            version,
             date: (await git.commitDate(segmentTag)) ?? today,
-            title: segmentTag,
+            title: ownTag ? segmentTag : groupHeading(version),
         };
     }
     /**
@@ -553,7 +684,11 @@ async function resolveHeading(git, pkg, label, versionOverride, segmentTag) {
      * that is when it is happening.
      */
     if (versionOverride) {
-        return { version: versionOverride, date: today, title: ChangeHashService.expandTag(pkg, versionOverride) };
+        return {
+            version: versionOverride,
+            date: today,
+            title: ownTag ? ChangeHashService.expandTag(pkg, versionOverride) : groupHeading(versionOverride),
+        };
     }
     /**
      * **Nothing else is a release**, so nothing else gets a release's heading. This used to read the
@@ -655,9 +790,9 @@ function ownersOf(repository, commit) {
     }
     return owners;
 }
-async function renderEntry(repository, pkg, label, sections, titles, git, versionOverride, segmentTag) {
+async function renderEntry(repository, pkg, label, sections, titles, git, versionOverride, segmentTag, grouped) {
     const template = resolveTemplate(repository, pkg);
-    const { version, date, title } = await resolveHeading(git, pkg, label, versionOverride, segmentTag);
+    const { version, date, title } = await resolveHeading(git, pkg, label, versionOverride, segmentTag, grouped);
     const content = render(template, {
         package: label,
         version,
@@ -704,6 +839,18 @@ const MARKER = /^<!-- rman:documented-up-to ([0-9a-f]{7,40}) -->[ \t]*\r?\n+/m;
 async function resolveBoundary(git, pkg, changelogFile, options) {
     if (options.from && options.from !== ChangeHashService.AUTO)
         return options.from;
+    /**
+     * **A rebuild starts from nothing, on purpose.** Both of the things that narrow a boundary are
+     * records of what a *previous* run wrote - the file's own marker, and `catchUpFile`'s last
+     * modifying commit - so consulting either would rebuild the file from where the file already is,
+     * which is the opposite of the request. The whole history it is, cut at every release tag by
+     * `splitByRelease` and floored by `changelog.startingAt`.
+     *
+     * An explicit `--from` still wins, above: that names a boundary the caller chose for this run,
+     * not one read back off disk.
+     */
+    if (options.rebuild)
+        return undefined;
     if (options.write) {
         const exists = fs.existsSync(changelogFile);
         if (!exists)
@@ -720,8 +867,7 @@ async function resolveBoundary(git, pkg, changelogFile, options) {
 /** Prepends `content` right after the top-level "# Changelog" heading if the file already has
  *  one, otherwise creates the file (and any missing parent directory - `relFilePath` can nest one,
  *  e.g. `'docs/CHANGELOG.md'`) with one. Leaves everything already in the file untouched below it. */
-function prependToChangelogFile(pkg, relFilePath, content, documentedUpTo) {
-    const file = path.join(pkg.dirname, relFilePath);
+function prependToChangelogFile(file, content, documentedUpTo) {
     const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf-8') : '';
     const headerMatch = /^# Changelog\r?\n+/.exec(existing);
     const header = headerMatch ? headerMatch[0] : '# Changelog\n\n';

package/services/version.service.js

@@ -4,9 +4,12 @@ import { Service } from '../core/classes/service.js';
 import { ConfigInterpolator } from '../core/config/config-interpolator.js';
 import { Manifest } from '../core/interfaces/manifest.js';
 import { GitHelper } from '../utils/git.js';
+import { ROOT_SELECTOR } from '../utils/package-filter.js';
 import { expandReleaseTag, isCalendarVersion } from '../utils/release-version.js';
+import { groupKeyOf } from '../utils/version-group.js';
 import { stampVersionLabel } from '../utils/version-stamp.js';
 import { ChangeHashService } from './change-hash.service.js';
+import { changelogGroupBy } from './changelog.service.js';
 import { RunService } from './run.service.js';
 import { VersionPlanService } from './version-plan.service.js';
 /**
@@ -119,12 +122,43 @@ export class VersionService extends Service {
          *  `version` never required at all. Falls back to `changelog`'s own default only when this
          *  package genuinely has no prior tag (a first-ever release). */
         const changelogFileByPackage = new Map();
+        /**
+         * Every entry the changelog is written for - which, unlike `bumped`, **includes a monorepo's
+         * root**.
+         */
+        /* **Without the root, a repository-wide commit is documented nowhere.** `ChangelogService`
+         * attributes a commit touching more than half the packages to the root instead of repeating it
+         * in all of them (`ownersOf`/`BROAD_COMMIT_THRESHOLD`) - and the root was excluded here, so
+         * that commit reached no file at all. Measured on `panates/sqb`'s 6.0.11: the one commit in the
+         * range touched all 17 packages, every package's entry was therefore empty and skipped by
+         * `changelog.service.ts`'s `!ownCommits.length` guard, and the release shipped with two
+         * changelogs updated out of seventeen and the change itself recorded in none of them.
+         *
+         * The two rules have to agree about who owns a broad commit, and the attribution is the one
+         * worth keeping: repeating an identical line in seventeen files is what the threshold exists to
+         * avoid. So the root gets its changelog written, and the repository has one file that says what
+         * a release contained repository-wide.
+         *
+         * **`bumped` stays as it is.** It drives the manifest writes, the stamps and `updated`, and a
+         * monorepo root's version is informational - writing it as a release would be the thing
+         * `isRealEntry` exists to prevent. This is a different question with a different answer. */
+        const changelogTargets = plan.filter(e => e.status === 'bump');
         if (options.changelog) {
-            for (const entry of bumped) {
+            /** **One call per file, not one per package.** Under `changelog.groupBy: 'group'` a group's
+             *  members share one file, so calling per package would prepend that group's entry once per
+             *  member - the same release written into the file three times. */
+            for (const target of changelogCalls(repository, changelogTargets)) {
+                const entry = target.entries[0];
+                /** **The root is addressed structurally, never by name.** A glob does not match a
+                 *  monorepo's root, so `scope: entry.package.name` would select nothing for it - the same
+                 *  vocabulary `--scope /` and `.rmanrc`'s `"[/]"` already use. */
+                const scope = target.entries.map(e => repository.monorepo && e.package === repository.rootPackage ? ROOT_SELECTOR : e.package.name);
+                /** Every member of a group releases at the same version off the same tag, so any of them
+                 *  answers for the boundary - see `applyPlan`'s own per-group tag set. */
                 const fromTag = ChangeHashService.expandTag(entry.package, entry.from);
                 const from = (await git.tagExists(fromTag)) ? fromTag : undefined;
                 const changelogEntries = await this.app.getService('changelog').generateToFile({
-                    scope: entry.package.name,
+                    scope,
                     fromRoot: true,
                     from,
                     // The tag for this release doesn't exist yet (it's created below), so changelog's own
@@ -135,8 +169,13 @@ export class VersionService extends Service {
                     // to bump, so its folded-in changelog shouldn't then be silently dropped by that flag.
                     includeSkipped: true,
                 });
+                /** Recorded against **every** package the call covered, not against the entry's own
+                 *  `package` - a group's file sits at the repository root, so keying it by that would file
+                 *  the group's changelog under the root and leave the group commit without it. */
                 for (const ce of changelogEntries) {
-                    changelogFileByPackage.set(ce.package.name, path.relative(repository.dirname, path.join(ce.package.dirname, ce.filePath)));
+                    const file = path.relative(repository.dirname, ce.file);
+                    for (const e of target.entries)
+                        changelogFileByPackage.set(e.package.name, file);
                 }
             }
         }
@@ -149,7 +188,19 @@ export class VersionService extends Service {
         const tagged = [];
         if (rootEntry?.status === 'bump') {
             const message = `chore: sync root version to ${rootEntry.to}`;
-            const sha = await git.commit([path.relative(repository.dirname, repository.rootPackage.manifestFileName)], message);
+            /** The root's own `CHANGELOG.md` rides along here, for the same reason its manifest does:
+             *  it belongs to no group, so no group commit would carry it and it would be left behind as
+             *  an uncommitted edit that `publish` then reads as a dirty tree. */
+            const files = [path.relative(repository.dirname, repository.rootPackage.manifestFileName)];
+            const rootChangelog = changelogFileByPackage.get(repository.rootPackage.name);
+            /** **Unless a group commit below is already carrying it**, which is the ordinary case under
+             *  `changelog.groupBy: 'group'`: the root is a member of the default group, so its file *is*
+             *  the group's. Committed here it would land one commit before the tag, leaving `git show
+             *  <tag>` without the notes for the release that tag names. */
+            const claimedByGroup = new Set(bumped.map(e => changelogFileByPackage.get(e.package.name)));
+            if (rootChangelog && !claimedByGroup.has(rootChangelog))
+                files.push(rootChangelog);
+            const sha = await git.commit(files, message);
             /** No packages: this commit carries the root's informational version and nothing releasable,
              *  which is why `updated` does not count it either. */
             commits.push({ sha, message, packages: [] });
@@ -163,15 +214,19 @@ export class VersionService extends Service {
                 byGroup.set(entry.groupKey, [entry]);
         }
         for (const [, groupEntries] of byGroup) {
-            const files = groupEntries.map(e => path.relative(repository.dirname, e.package.manifestFileName));
+            /** A **set**: the members of a group share one changelog file under
+             *  `changelog.groupBy: 'group'`, and `git commit` given the same path twice is a needless
+             *  way to find out whether it minds. */
+            const files = new Set(groupEntries.map(e => path.relative(repository.dirname, e.package.manifestFileName)));
             for (const e of groupEntries) {
                 const changelogFile = changelogFileByPackage.get(e.package.name);
                 if (changelogFile)
-                    files.push(changelogFile);
-                files.push(...(stampedByPackage.get(e.package.name) ?? []));
+                    files.add(changelogFile);
+                for (const f of stampedByPackage.get(e.package.name) ?? [])
+                    files.add(f);
             }
             const message = VersionService.buildCommitMessage(repository, groupEntries, options.message);
-            const sha = await git.commit(files, message);
+            const sha = await git.commit([...files], message);
             commits.push({ sha, message, packages: groupEntries.map(e => e.package.name) });
             const tags = new Set(groupEntries.map(e => ChangeHashService.expandTag(e.package, e.to)));
             for (const tag of tags) {
@@ -391,3 +446,28 @@ function assertStampable(pkg, version) {
                     `version is declared in it. Name a plugin in .rmanrc "plugins".`));
     }
 }
+/**
+ * The plan entries cut into one call to `ChangelogService.generateToFile` per **file** it will
+ * write.
+ *
+ * Under the default `changelog.groupBy: 'package'` that is one call per entry, which is what this
+ * always was. Under `'group'` the members of a group share one file, so they share one call - and
+ * the grouping asked for is the changelog's (`groupKeyOf`), never the *planner's*: those two answer
+ * different questions and disagree about the root, which `VersionPlanService` puts in a group of its
+ * own (`__root__`) while `groupKeyOf` puts it wherever its config does. Batching by the planner's
+ * key would give a `group: true` repository two files where it asked for one.
+ */
+function changelogCalls(repository, entries) {
+    if (changelogGroupBy(repository) !== 'group')
+        return entries.map(entry => ({ entries: [entry] }));
+    const byKey = new Map();
+    for (const entry of entries) {
+        const key = groupKeyOf(entry.package);
+        const list = byKey.get(key);
+        if (list)
+            list.push(entry);
+        else
+            byKey.set(key, [entry]);
+    }
+    return [...byKey.values()].map(grouped => ({ entries: grouped }));
+}

package/utils/git.d.ts

@@ -36,12 +36,15 @@ export declare class GitHelper {
      */
     listCommits(options?: {
         hash?: string;
+        onProgress?: GitHelper.CommitProgress;
     }): Promise<CommitInfo[]>;
     /** Every commit reachable from HEAD, oldest first - for a boundary-free "everything so far"
      *  view (e.g. a package that's never been tagged/released at all, so there's no "since" ref to
      *  measure from and `listCommits()`'s own no-hash fallback, upstream push status, doesn't apply -
      *  a repo with no configured remote at all is common and shouldn't read as "nothing happened"). */
-    listAllCommits(): Promise<CommitInfo[]>;
+    listAllCommits(options?: {
+        onProgress?: GitHelper.CommitProgress;
+    }): Promise<CommitInfo[]>;
     private _commitInfoFor;
     /** Tag names matching the glob `pattern` (e.g. `"v*"`, `"pkg-a@*"`), newest version first. */
     listTags(pattern: string): Promise<string[]>;
@@ -123,3 +126,8 @@ export declare class GitHelper {
      *  fall back to a content-level three-way merge instead of failing outright. */
     applyPatches(patchFiles: string[]): Promise<void>;
 }
+export declare namespace GitHelper {
+    /** Called once with `(0, total)` before the first commit, then after each one - so a caller can
+     *  show the total while the count is still zero. */
+    type CommitProgress = (done: number, total: number) => void;
+}

package/utils/git.js

@@ -96,13 +96,13 @@ export class GitHelper {
             }
             shas = Array.from(cherryOut.matchAll(/[a-f0-9]{7,40}/gi)).map(m => m[0]);
         }
-        return this._commitInfoFor(shas);
+        return this._commitInfoFor(shas, options?.onProgress);
     }
     /** Every commit reachable from HEAD, oldest first - for a boundary-free "everything so far"
      *  view (e.g. a package that's never been tagged/released at all, so there's no "since" ref to
      *  measure from and `listCommits()`'s own no-hash fallback, upstream push status, doesn't apply -
      *  a repo with no configured remote at all is common and shouldn't read as "nothing happened"). */
-    async listAllCommits() {
+    async listAllCommits(options) {
         let stdout;
         try {
             ({ stdout } = await execFileAsync('git', ['log', '--reverse', '--format=%H'], { cwd: this.cwd }));
@@ -111,10 +111,17 @@ export class GitHelper {
             return [];
         }
         const shas = stdout.trim() ? stdout.trim().split(/\r?\n/) : [];
-        return this._commitInfoFor(shas);
+        return this._commitInfoFor(shas, options?.onProgress);
     }
-    async _commitInfoFor(shas) {
+    /* **The slow loop, and the only one worth reporting.** Two `git show` per commit, one commit at
+     * a time - measured on `panates/sqb`, 156 invocations at peak concurrency 1 for a four-release
+     * range, and 1825 commits for a full rebuild. Everything around it is either concurrent across
+     * targets or in memory, which is why `onProgress` is here and nowhere else. */
+    async _commitInfoFor(shas, onProgress) {
         const commits = [];
+        /** Reported before the first commit, so a caller knows the total while the count is still 0 -
+         *  otherwise a panel has nothing to draw for the whole of the first commit. */
+        onProgress?.(0, shas.length);
         for (const sha of shas) {
             // subject and body in one call (NUL-separated, since a commit message itself never
             // contains one) - halves the process-spawns per commit compared to two separate `git show`s.
@@ -132,6 +139,7 @@ export class GitHelper {
                 body: body.trim(),
                 files: files.map(f => path.join(this.cwd, f)),
             });
+            onProgress?.(commits.length, shas.length);
         }
         return commits;
     }

package/utils/progress-panel.d.ts

@@ -48,7 +48,13 @@ export declare class ProgressPanel {
     private renderLoop?;
     private spinnerFrame;
     private startedAt;
-    constructor(title: string, enabled: boolean);
+    /**
+     * `stream` is where the panel is drawn - **stdout by default**, which is what `run` and `exec`
+     * have always used. A command whose *answer* goes to stdout passes `process.stderr`, or
+     * redirecting that answer into a file captures the panel's cursor-movement codes along with it:
+     * `rman changelog > NOTES.md` is the case, and it is the same reason the status region moved.
+     */
+    constructor(title: string, enabled: boolean, stream?: NodeJS.WriteStream);
     get enabled(): boolean;
     /** Registers an item and returns it - callers mutate the returned object directly (`status`,
      *  `currentStep`, `lastLine`, ...) to drive the next render tick. */

package/utils/progress-panel.js

@@ -21,9 +21,15 @@ export class ProgressPanel {
     renderLoop;
     spinnerFrame = 0;
     startedAt = 0;
-    constructor(title, enabled) {
+    /**
+     * `stream` is where the panel is drawn - **stdout by default**, which is what `run` and `exec`
+     * have always used. A command whose *answer* goes to stdout passes `process.stderr`, or
+     * redirecting that answer into a file captures the panel's cursor-movement codes along with it:
+     * `rman changelog > NOTES.md` is the case, and it is the same reason the status region moved.
+     */
+    constructor(title, enabled, stream) {
         this.title = title;
-        this.live = new LiveRegion(enabled);
+        this.live = new LiveRegion(enabled, stream);
     }
     get enabled() {
         return this.live.enabled;
@@ -49,16 +55,35 @@ export class ProgressPanel {
         let running = 0;
         let done = 0;
         let failedSoFar = 0;
+        /**
+         * **What the bar is filled from, and it is not `done`.** A finished item counts as a whole one;
+         * a *running* item counts as the fraction of its own steps it has got through, so the bar moves
+         * while a single item is working rather than only when one ends.
+         *
+         * Counting whole items made the bar useless exactly where it was needed most: `rman changelog`
+         * writes one file under `changelog.groupBy: 'group'`, so the bar sat empty at `0/1` for the
+         * entire run while the row beside it counted to 1825. `run` gains the same thing in the small -
+         * a nine-step build now advances within the package instead of jumping at the end of it.
+         */
+        let filled = 0;
         for (const item of this.items.values()) {
-            if (item.status === 'running')
+            if (item.status === 'running') {
                 running++;
-            else if (item.status !== 'pending')
+                /** `stepIndex` is 0-based, so a step in progress is `index + 1` of `total` begun - and
+                 *  clamped, since a caller may report more steps than it first declared. */
+                if (item.stepsTotal && item.stepIndex != null) {
+                    filled += Math.min(1, (item.stepIndex + 1) / item.stepsTotal);
+                }
+            }
+            else if (item.status !== 'pending') {
                 done++;
+                filled += 1;
+            }
             if (item.status === 'failed')
                 failedSoFar++;
         }
         const header = colors.bgCyan.black.bold(` ${this.title} `);
-        const bar = renderProgressBar(done, total);
+        const bar = renderProgressBar(filled, total);
         const totalElapsed = formatDuration(Date.now() - this.startedAt);
         const failedText = failedSoFar > 0 ? colors.red.bold(`${failedSoFar} failed`) : colors.gray(`${failedSoFar} failed`);
         const lines = [
@@ -179,7 +204,10 @@ function truncate(text, width) {
 }
 /** Classic braille "dots" spinner (cli-spinners' default), one frame per render tick. */
 const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+/** `done` is fractional - see the `filled` accumulator in `render`. Clamped both ends, or a
+ *  rounding overshoot asks `repeat` for a negative count and throws inside a redraw. */
 function renderProgressBar(done, total, width = 24) {
-    const filled = total ? Math.round((done / total) * width) : 0;
+    const cells = total ? Math.round((done / total) * width) : 0;
+    const filled = Math.max(0, Math.min(width, cells));
     return colors.green('█'.repeat(filled)) + colors.gray('░'.repeat(width - filled));
 }

package/utils/version-group.js

@@ -19,7 +19,7 @@ export function groupKeyOf(pkg) {
     if (g === false)
         return `solo:${pkg.name}`;
     if (typeof g === 'string' && g)
-        return `named:${g}`;
+        return `named:${assertGroupName(g, pkg)}`;
     return 'default';
 }
 /**
@@ -41,3 +41,35 @@ export function versionLineCount(pkg) {
         return 1;
     return new Set(packages.map(groupKeyOf)).size;
 }
+/**
+ * What a group may be called - a letter or digit, then letters, digits, `.`, `-` and `_`, up to
+ * `GROUP_NAME_MAX`.
+ *
+ * **A group name is a file name now**, since `changelog.groupBy: 'group'` writes one
+ * `CHANGELOG-<name>.md` per group, so it is no longer a key nothing outside rman ever sees. The
+ * alternative was escaping it at the one place it is written, and that is the worse half of the
+ * trade: an escape turns `core/api` into some `core-api.md` the repository never asked for and
+ * cannot search for, and it would have to be repeated by every future reader of the name. A
+ * refusal is one rule, stated once, before anything is written.
+ *
+ * Leading `.` and `-` are out for the two reasons a file name has: a dot-file is hidden, and a
+ * leading dash reads as a flag to everything that takes a path on a command line.
+ */
+const GROUP_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * **15, and the limit is about the reader rather than any filesystem.** A group name is repeated in
+ * every heading of the file it names and in the file name itself; a sentence-long one stops being a
+ * label. Filesystems allow far more, which is exactly why a limit has to be a decision rather than
+ * whatever the platform happens to permit.
+ */
+const GROUP_NAME_MAX = 15;
+function assertGroupName(name, pkg) {
+    if (name.length > GROUP_NAME_MAX)
+        throw new Error(`Invalid group name "${name}" on package "${pkg.name}": at most ${GROUP_NAME_MAX} characters, ` +
+            `and it is ${name.length}. A group name is written into a file name (CHANGELOG-${name}.md).`);
+    if (!GROUP_NAME.test(name))
+        throw new Error(`Invalid group name "${name}" on package "${pkg.name}": start with a letter or digit, then ` +
+            `letters, digits, ".", "-" or "_". A group name is written into a file name ` +
+            `(CHANGELOG-<name>.md), so it has to be one.`);
+    return name;
+}