rman 2.5.0 → 2.6.1

package/builtins/platforms/node/services/ci.service.js

@@ -72,7 +72,7 @@ export var CiService;
         const progress = options.progress ?? true;
         const panel = new ProgressPanel('CI', !!process.stdout.isTTY && progress);
         const runStartedAt = Date.now();
-        panel.start();
+        panel.start(repository.app.statusRegion);
         const items = [];
         let failed = false;
         try {

package/builtins/platforms/node/services/clean.service.js

@@ -53,7 +53,7 @@ export var CleanService;
         const progress = options.progress ?? true;
         const logger = new Logger(options.logLevel ?? resolveRootLogLevel(repository));
         const panel = new ProgressPanel(dryRun ? 'CLEAN (dry-run)' : 'CLEAN', !!process.stdout.isTTY && progress);
-        panel.start();
+        panel.start(repository.app.statusRegion);
         let failed = false;
         try {
             const results = await Promise.allSettled(targets.map(pkg => {

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(app.statusRegion);
+            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.1';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rman",
   "description": "Repository manager",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "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;
     }
 }