rman 2.5.0 → 2.6.1

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/exec.service.js

@@ -55,7 +55,7 @@ export class ExecService extends Service {
             const dependencies = topo ? pkg.dependencies.filter(d => names.has(d.name)).map(d => d.name) : [];
             return new Task(() => execForPackage(this.app, ctx, panel.enabled, pkg.dirname, command, logger, bail ? () => rootTask?.abort() : () => { }), { name: pkg.name, dependencies });
         });
-        panel.start();
+        panel.start(repository.app.statusRegion);
         let failed = false;
         try {
             /** bail:false here - each item's own task decides whether to call `rootTask.abort()`

package/services/run.service.js

@@ -228,7 +228,7 @@ export class RunService extends Service {
             err.logged = true;
             throw err;
         }
-        panel.start();
+        panel.start(repository.app.statusRegion);
         try {
             /** bail:false here - each package's own resolved bail setting decides whether to call
              *  `rootTask.abort()` itself (see `runSteps`), since power-tasks' own `bail` can't vary per package. */

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

@@ -1,4 +1,5 @@
 import { LiveRegion } from './live-region.js';
+import type { StatusRegion, TerminalRegion } from './status-region.js';
 export type ProgressStatus = 'pending' | 'running' | 'success' | 'failed' | 'skipped';
 export interface ProgressItem {
     readonly name: string;
@@ -41,20 +42,39 @@ export declare function formatDuration(ms: number): string;
  * callers are expected to fall back to their own plain logging in that case, the way `run`
  * falls back to its "classic" per-step log.
  */
-export declare class ProgressPanel {
+export declare class ProgressPanel implements TerminalRegion {
     private readonly title;
     readonly live: LiveRegion;
     private readonly items;
     private renderLoop?;
+    /** The region this panel took the terminal from, handed back in `stop`. */
+    private statusRegion?;
     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. */
     addItem(name: string, stepsTotal?: number): ProgressItem;
-    /** Starts the redraw loop. No-op (and no timer) when disabled. */
-    start(): void;
+    /**
+     * Starts the redraw loop. No-op (and no timer) when disabled.
+     *
+     * **Pass `statusRegion` wherever one exists** - `app.statusRegion`, which every command has while
+     * it runs. The panel takes the terminal over for as long as it draws and hands it back in `stop`;
+     * without that, two regions redraw on top of each other and the bottom lines visibly swap places
+     * several times a second. See `StatusRegion.suspend`.
+     */
+    start(statusRegion?: StatusRegion): void;
+    /** Writes `text` above the panel without corrupting it - erase, write, redraw underneath. The
+     *  `TerminalRegion` half of the takeover, so a `runBin` child's output goes somewhere sane while
+     *  a panel is up. */
+    passThrough(text: string): void;
     private render;
     /** Stops the redraw loop and erases the panel, leaving the cursor where it started. */
     stop(): void;