rman 2.5.0 → 2.6.1

package/utils/progress-panel.js

@@ -19,11 +19,19 @@ export class ProgressPanel {
     live;
     items = new Map();
     renderLoop;
+    /** The region this panel took the terminal from, handed back in `stop`. */
+    statusRegion;
     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;
@@ -35,13 +43,36 @@ export class ProgressPanel {
         this.items.set(name, item);
         return item;
     }
-    /** Starts the redraw loop. No-op (and no timer) when disabled. */
-    start() {
+    /**
+     * 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) {
         this.startedAt = Date.now();
         if (!this.live.enabled)
             return;
+        /** Only when this panel is actually drawing: a disabled panel owns nothing, and suspending the
+         *  status line for it would take away the one thing a non-TTY run still shows. */
+        this.statusRegion = statusRegion;
+        this.statusRegion?.suspend(this);
         this.renderLoop = setInterval(() => this.render(), 100);
     }
+    /** 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) {
+        if (!this.live.enabled) {
+            process.stdout.write(text);
+            return;
+        }
+        this.live.clear();
+        process.stdout.write(text);
+        this.render();
+    }
     render() {
         this.spinnerFrame = (this.spinnerFrame + 1) % SPINNER_FRAMES.length;
         const spinner = colors.cyan(SPINNER_FRAMES[this.spinnerFrame]);
@@ -49,16 +80,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 = [
@@ -104,6 +154,11 @@ export class ProgressPanel {
             clearInterval(this.renderLoop);
         this.renderLoop = undefined;
         this.live.clear();
+        /** **Handed back, not left suspended.** A command keeps working after its panel comes down -
+         *  `ci` prints its summary, `run` its recap - and those writes have to go through a region
+         *  again, or they scroll the status line's own block. */
+        this.statusRegion?.resume();
+        this.statusRegion = undefined;
     }
     /**
      * Prints the final per-item recap (✓/X/○) and the "N succeeded, M failed (Xs)" summary line,
@@ -179,7 +234,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/status-region.d.ts

@@ -7,19 +7,56 @@
  * ✔ lint  3.6s                 <- once it ends
  * ```
  */
-export declare class StatusRegion {
+/**
+ * What a region has to offer to take the terminal over from `StatusRegion` - and `passThrough` is
+ * the whole of it.
+ *
+ * **Deliberately not `live`.** `StatusRegion.live` answers "does something own this terminal", which
+ * is what `runBin` reads and which stays true across a takeover; `ProgressPanel` spells the same
+ * question `enabled` and uses `live` for the `LiveRegion` itself. Putting it in the contract would
+ * force one of the two to be renamed for no gain - the handover needs somewhere to write, nothing
+ * more.
+ */
+export interface TerminalRegion {
+    /** Write `text` without corrupting the block: erase, write, redraw underneath. */
+    passThrough(text: string): void;
+}
+export declare class StatusRegion implements TerminalRegion {
     private readonly label;
     private readonly detail;
     private readonly region;
     private readonly startedAt;
     private timer?;
     private frame;
+    /**
+     * Who owns the terminal while this region is suspended - see `suspend`. Pass-through is forwarded
+     * there, so `runBin` keeps asking one object (`app.statusRegion`) whatever is actually drawing.
+     */
+    private takeover?;
     constructor(label: string, detail?: string, enabled?: boolean);
     /** Whether the spinner is actually drawn. `false` leaves `passThrough` a plain write and `stop`
      *  its single line, which is what a non-TTY wants. */
     get live(): boolean;
     /** Starts the spinner. Safe to call when not live - it does nothing. */
     start(): void;
+    /**
+     * **Hands the terminal to another region**, usually a `ProgressPanel` - the spinner stops, its
+     * line is erased, and pass-through is forwarded to `takeover` until `resume`.
+     *
+     * **Two live regions on one terminal cannot both work, and this is what enforces that.** Each
+     * redraws by moving the cursor up by *its own* line count; interleaved, every redraw lands on the
+     * other's rows. On screen that reads as the last line and the status line swapping places several
+     * times a second - reported on `rman ci`, and `rman build` has it too through `runBin`, whose
+     * pass-through went to this region while the panel was drawing. `LiveRegion`'s own doc has said
+     * "only one region is ever live" since it grew a `stream` parameter; nothing enforced it.
+     *
+     * `live` deliberately stays `true` while suspended: it answers "does something own this
+     * terminal", which is what `runBin` needs to decide to pipe rather than let a child scroll the
+     * screen. The answer to *which* region is the forwarding above.
+     */
+    suspend(takeover?: TerminalRegion): void;
+    /** Takes the terminal back and starts drawing again - a no-op when it was never suspended. */
+    resume(): void;
     /** Writes `text` without corrupting the block: erase, write, redraw underneath. */
     passThrough(text: string): void;
     /** Erases the spinner and leaves one line saying how it went. */

package/utils/status-region.js

@@ -1,32 +1,5 @@
 import colors from 'ansi-colors';
 import { LiveRegion } from './live-region.js';
-/**
- * One line at the bottom of the terminal while a command runs - a spinner, the command's name, the
- * repository, and the elapsed time counting up - replaced by a result line when it ends.
- *
- * ```
- * ⠹ lint  postgrejs  2.4s      <- while running, redrawn in place
- * ✔ lint  3.6s                 <- once it ends
- * ```
- */
-/* **Why a live line rather than one printed at the start**: a command that prints nothing is
- * indistinguishable from one that never ran, and a static start line answers "did it start" without
- * answering "is it still going". `rman lint` on a clean repository is silent for several seconds
- * because eslint says nothing when it has nothing to say.
- *
- * **On stderr, unlike `ProgressPanel`'s region.** A command's *answer* goes to stdout, and
- * `rman changelog > NOTES.md` has to leave the notes alone in the file - cursor-movement codes in
- * there would be worse than noise. The two streams share a terminal, so only one region is ever
- * live.
- *
- * **Anything printed while it is live has to go through `passThrough`**, which erases the block,
- * writes, and redraws below. A write that bypasses it scrolls the screen, and the next redraw's
- * "move up N rows" then lands on the wrong rows and erases what was just printed - the same cursor
- * arithmetic `LiveRegion` documents as its own hard edge. That is why `runBin` pipes a child while
- * a region is live instead of letting it inherit the terminal.
- *
- * **No-op when stderr is not a TTY** (CI, a pipe), where the escape codes mean nothing. There the
- * caller still gets the result line, which is the part that carries information. */
 export class StatusRegion {
     label;
     detail;
@@ -34,6 +7,11 @@ export class StatusRegion {
     startedAt = Date.now();
     timer;
     frame = 0;
+    /**
+     * Who owns the terminal while this region is suspended - see `suspend`. Pass-through is forwarded
+     * there, so `runBin` keeps asking one object (`app.statusRegion`) whatever is actually drawing.
+     */
+    takeover;
     constructor(label, detail = '', enabled) {
         this.label = label;
         this.detail = detail;
@@ -57,8 +35,41 @@ export class StatusRegion {
         }, FRAME_MS);
         this.timer.unref();
     }
+    /**
+     * **Hands the terminal to another region**, usually a `ProgressPanel` - the spinner stops, its
+     * line is erased, and pass-through is forwarded to `takeover` until `resume`.
+     *
+     * **Two live regions on one terminal cannot both work, and this is what enforces that.** Each
+     * redraws by moving the cursor up by *its own* line count; interleaved, every redraw lands on the
+     * other's rows. On screen that reads as the last line and the status line swapping places several
+     * times a second - reported on `rman ci`, and `rman build` has it too through `runBin`, whose
+     * pass-through went to this region while the panel was drawing. `LiveRegion`'s own doc has said
+     * "only one region is ever live" since it grew a `stream` parameter; nothing enforced it.
+     *
+     * `live` deliberately stays `true` while suspended: it answers "does something own this
+     * terminal", which is what `runBin` needs to decide to pipe rather than let a child scroll the
+     * screen. The answer to *which* region is the forwarding above.
+     */
+    suspend(takeover) {
+        this.takeover = takeover;
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+        this.region.clear();
+    }
+    /** Takes the terminal back and starts drawing again - a no-op when it was never suspended. */
+    resume() {
+        if (!this.takeover && this.timer)
+            return;
+        this.takeover = undefined;
+        this.start();
+    }
     /** Writes `text` without corrupting the block: erase, write, redraw underneath. */
     passThrough(text) {
+        if (this.takeover) {
+            this.takeover.passThrough(text);
+            return;
+        }
         if (!this.region.enabled) {
             process.stderr.write(text);
             return;
@@ -69,6 +80,7 @@ export class StatusRegion {
     }
     /** Erases the spinner and leaves one line saying how it went. */
     stop(outcome) {
+        this.takeover = undefined;
         if (this.timer)
             clearInterval(this.timer);
         this.timer = undefined;

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;
+}