rman 2.19.1 → 2.21.0

package/cli.js

@@ -99,6 +99,12 @@ export async function runCli(options) {
                         ? err.message
                         : '';
                 console.log('\n' + colors.red(text));
+                /** The handler's own error is marked too, because it is the one that comes back: yargs
+                 *  rejects `parseAsync` with what the handler threw, not with what this throws, so
+                 *  `runCli`'s catch saw it unmarked and printed the same line again on stderr - every
+                 *  failing command said its reason twice. */
+                if (err && typeof err === 'object')
+                    err.logged = true;
                 /** A real `Error`, marked `logged` since the text above just went out: yargs hands the
                  *  reason over as a bare string, and rethrowing that raw made bad argv indistinguishable
                  *  from success to anything holding the promise - or the shell. */

package/constants.js

@@ -1 +1 @@
-export const version = '2.19.1';
+export const version = '2.21.0';

package/core/classes/progress-panel.d.ts

@@ -24,6 +24,20 @@ export interface ProgressItem {
     finishedAt?: number;
     /** Captured output, printed back out if the item ends up failing. */
     log: string[];
+    /**
+     * The same output split by the step that printed it, when the driver reports steps (`run`'s
+     * scheduler does). A failed item's recap then names the steps that passed in a line each and
+     * prints the output of the one that failed; without it, `log` is printed whole.
+     */
+    steps?: StepLog[];
+}
+/** One step of an item, as the recap shows it - see `ProgressItem.steps`. */
+export interface StepLog {
+    /** `before: rman check` - the slot and what ran in it. */
+    label: string;
+    /** Unset while it runs, and for a step that never got to end. */
+    status?: 'success' | 'failed';
+    lines: string[];
 }
 export interface ProgressSummary {
     successCount: number;
@@ -81,6 +95,13 @@ export declare class ProgressPanel implements TerminalRegion {
      *  `TerminalRegion` half of the takeover, so a `runBin` child's output goes somewhere sane while
      *  a panel is up. */
     passThrough(text: string): void;
+    /**
+     * A failed item's steps: one line for each that passed, and the one that failed - or never got to
+     * end - with its whole output under it.
+     */
+    protected stepRecap(steps: readonly StepLog[]): string;
+    /** Every line of a replayed log moved two columns right - an empty line left empty. */
+    protected indentLog(text: string): string;
     private render;
     /** Stops the redraw loop and erases the panel, leaving the cursor where it started. */
     stop(): void;

package/core/classes/progress-panel.js

@@ -79,6 +79,35 @@ export class ProgressPanel {
         process.stdout.write(text);
         this.render();
     }
+    /**
+     * A failed item's steps: one line for each that passed, and the one that failed - or never got to
+     * end - with its whole output under it.
+     */
+    /* **Only the failing step's output, and the user's call.** The whole log used to be replayed, on
+     * the reasoning that an earlier step's output can explain a later failure. In a real build that
+     * put `rman check`'s file count and its own recap above every lint error, four lines of success
+     * the reader had to skip to reach the one that mattered. The passing steps keep a line each, so
+     * the order is still there; `--log-file` keeps every line. */
+    stepRecap(steps) {
+        const out = [];
+        for (const step of steps) {
+            if (step.status === 'success') {
+                out.push(`${colors.green('✔')} ${colors.gray(step.label)}`);
+                continue;
+            }
+            out.push(`${colors.red('✖')} ${step.label}`);
+            if (step.lines.length)
+                out.push(this.indentLog(step.lines.join('\n')));
+        }
+        return out.join('\n');
+    }
+    /** Every line of a replayed log moved two columns right - an empty line left empty. */
+    indentLog(text) {
+        return text
+            .split('\n')
+            .map(line => (line ? `  ${line}` : line))
+            .join('\n');
+    }
     render() {
         this.spinnerFrame = (this.spinnerFrame + 1) % SPINNER_FRAMES.length;
         const spinner = colors.cyan(SPINNER_FRAMES[this.spinnerFrame]);
@@ -273,9 +302,14 @@ export class ProgressPanel {
                      * the comma after it red.
                      *
                      * The `X` above already says the item failed, and the step that failed printed its own
-                     * error. */
-                    if (item.log.length)
-                        console.log(item.log.join('\n'));
+                     * error.
+                     *
+                     * **Indented two columns**, so the log reads as belonging to the `X` line above it - level
+                     * with the recap's own lines it ran together with them, a nested rman's recap most of all. */
+                    if (item.steps?.length)
+                        console.log(this.indentLog(this.stepRecap(item.steps)));
+                    else if (item.log.length)
+                        console.log(this.indentLog(item.log.join('\n')));
                 }
             }
             else if (this.live.enabled) {
@@ -339,6 +373,7 @@ class PanelItem {
     startedAt;
     finishedAt;
     log = [];
+    steps = [];
     _currentStep;
     _currentCommand;
     constructor(name, stepsTotal) {

package/core/classes/run-reporters.d.ts

@@ -54,11 +54,16 @@ export declare class PanelReporter extends PlainReporter {
      *  would only be escape codes counted as text there. */
     readonly childEnv: undefined;
     constructor(commandName: string, panel: ProgressPanel);
-    /** The row names the step itself; there is no separate line to print. */
-    protected started(): void;
+    /** The row names the step itself; there is no separate line to print - but the recap needs to
+     *  know which lines were whose, so a step is opened here. */
+    protected started(event: Extract<LogEvent, {
+        event: 'start';
+    }>, origin: ReportOrigin): void;
     protected output(event: Extract<LogEvent, {
         event: 'output';
     }>, origin: ReportOrigin): void;
-    /** The row shows the step's outcome; the recap prints the package's. */
-    protected ended(): void;
+    /** The row shows the step's outcome; the recap prints the package's - and reads it from here. */
+    protected ended(event: Extract<LogEvent, {
+        event: 'end';
+    }>, origin: ReportOrigin): void;
 }

package/core/classes/run-reporters.js

@@ -124,12 +124,20 @@ export class PanelReporter extends PlainReporter {
     constructor(commandName, panel) {
         super(commandName, panel);
     }
-    /** The row names the step itself; there is no separate line to print. */
-    started() { }
+    /** The row names the step itself; there is no separate line to print - but the recap needs to
+     *  know which lines were whose, so a step is opened here. */
+    started(event, origin) {
+        origin.item.steps?.push({ label: event.command ? `${event.step}: ${event.command}` : event.step, lines: [] });
+    }
     output(event, origin) {
         origin.item.log.push(event.line);
+        origin.item.steps?.at(-1)?.lines.push(event.line);
         origin.item.lastLine = event.line;
     }
-    /** The row shows the step's outcome; the recap prints the package's. */
-    ended() { }
+    /** The row shows the step's outcome; the recap prints the package's - and reads it from here. */
+    ended(event, origin) {
+        const step = origin.item.steps?.at(-1);
+        if (step)
+            step.status = event.status;
+    }
 }

package/core/config/config-paths.js

@@ -89,6 +89,15 @@ export const STEP_PATHS = [
     'version.before.command',
     'version.exec.command',
     'version.after.command',
+    /** A step object's own `if`, for the reason `run.*.if` is here: called while the config loads it
+     *  would collapse to a boolean and stop being a condition. `run.*.if` already covers the
+     *  shorthand's (`run: { build: [{ if, command }] }`), which arrives at the same path. */
+    'run.*.before.if',
+    'run.*.exec.if',
+    'run.*.after.if',
+    'version.before.if',
+    'version.exec.if',
+    'version.after.if',
 ];
 /**
  * Config paths left untouched when a repository's config is first resolved, and evaluated only by

package/core/interfaces/run-step.d.ts

@@ -47,6 +47,16 @@ export interface RunStepContext {
      * `ctx.runBin` is already bound to this directory, so a binary run through it needs no such care.
      */
     cwd: string;
+    /**
+     * The package the run was narrowed to because rman was started inside it, or `undefined` when it
+     * covers the repository - started at the root, or with `--from-root`.
+     *
+     * What a step asks to tell "the whole repository is building" from "just this package is":
+     * `repository.currentPackage` answers where rman was started and cannot see `--from-root`. Set by
+     * `run` and the commands built on it (`build`, `test`); `undefined` in a `version` hook, which
+     * always covers the repository.
+     */
+    scopedTo?: Package;
     /**
      * The repository's locally installed binaries, already carrying this run's `cwd` and log level -
      * handed over rather than imported, for the reason `CommandContext.runBin` is.
@@ -107,6 +117,17 @@ export interface RunStepObject {
      * with no package graph to join, and the key is refused there rather than quietly doing nothing.
      */
     topo?: boolean;
+    /**
+     * Whether this one step runs, asked when its turn comes - the same two forms
+     * `run.<script>.if` takes: a condition (`changed`, `dirty and not committed`) or a function
+     * handed the step's context. A step that says no is passed over, and the ones after it still
+     * run.
+     *
+     * @example
+     * // lint the package only when the build was started inside it
+     * { if: ({ scopedTo }) => !!scopedTo, command: 'rman lint' }
+     */
+    if?: string | RunConditionFn;
 }
 /** One entry of a `before`/`exec`/`after` slot: a shell command, a function, or a
  *  [`RunStepObject`](#RunStepObject) saying something about the step. A list of them runs in

package/package.json

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

package/services/run.service.d.ts

@@ -4,7 +4,7 @@ import type { Package } from '../core/classes/package.js';
 import { ProgressPanel } from '../core/classes/progress-panel.js';
 import type { Repository } from '../core/classes/repository.js';
 import { Service } from '../core/classes/service.js';
-import type { RunStepContext, RunStepFn, RunStepValue } from '../core/interfaces/run-step.js';
+import type { RunConditionFn, RunStepContext, RunStepFn, RunStepValue } from '../core/interfaces/run-step.js';
 import { type PackageFilterOptions } from '../utils/package-filter.js';
 /**
  * A service class - see `ListService` for the shape and `Service` for the three measured
@@ -160,6 +160,8 @@ export declare namespace RunService {
         steps: ScriptStep[];
         /** The directory the steps run in - the package's own, or the repository root for a bookend. */
         cwd: string;
+        /** The package the run was narrowed to by the directory it started in - `RunStepContext.scopedTo`. */
+        scopedTo?: Package;
         topo: boolean;
         bail: boolean;
         logLevel: LogLevel;
@@ -210,6 +212,8 @@ export declare namespace RunService {
          *  and the three are three different answers, which is why this is not a plain boolean. See
          *  `RunStepObject.topo`. */
         topo?: boolean;
+        /** The step's own condition, from its object form - see `RunStepObject.if`. */
+        if?: string | RunConditionFn;
     }
     export interface CommandStep extends StepBase {
         command: string;
@@ -306,7 +310,7 @@ export declare namespace RunService {
      * `onCommand` is told what the step is spawning, for as long as it runs - the argv while a child
      * is up, `undefined` when it returns.
      */
-    export function createStepContext(pkg: Package, cwd: string, onCommand?: (command: string | undefined) => void, onLine?: (line: string, stream?: 'stdout' | 'stderr') => void): RunStepContext;
+    export function createStepContext(pkg: Package, cwd: string, onCommand?: (command: string | undefined) => void, onLine?: (line: string, stream?: 'stdout' | 'stderr') => void, scopedTo?: Package): RunStepContext;
     /**
      * `.rmanrc` conditional execution, GitHub Actions-`if`-flavored but a small closed grammar
      * instead of a full expression language (less to get wrong, still covers what's asked for) -

package/services/run.service.js

@@ -60,7 +60,7 @@ export class RunService extends Service {
         const rootSkipped = !!cwdScope ||
             !repository.monorepo ||
             rootCfg.skip === true ||
-            !(await passesIf(repository, repository.rootPackage, rootCfg.if, repository.dirname, ifStatusCache));
+            !(await passesIf(repository, repository.rootPackage, rootCfg.if, repository.dirname, ifStatusCache, cwdScope));
         const rootSteps = rootSkipped ? [] : getScriptSteps(repository.rootPackage, script);
         /** Filtered on the slot, not on `'pre' + script`: the step labels are `before`/`exec`/`after`
          *  now - the same words the config uses - rather than npm's `pre<script>` naming, which moved
@@ -75,6 +75,7 @@ export class RunService extends Service {
                 label: 'root',
                 steps,
                 cwd: repository.dirname,
+                scopedTo: cwdScope,
                 topo: false,
                 bail: resolveBail(options.bail, repository.rootPackage, script, true),
                 logLevel: resolveLogLevel(options.logLevel, repository.rootPackage, script, logLevelDefault),
@@ -87,7 +88,7 @@ export class RunService extends Service {
             const pkgCfg = RunService.getConfig(pkg, script);
             if (pkgCfg.skip === true)
                 continue;
-            if (!(await passesIf(repository, pkg, pkgCfg.if, pkg.dirname, ifStatusCache)))
+            if (!(await passesIf(repository, pkg, pkgCfg.if, pkg.dirname, ifStatusCache, cwdScope)))
                 continue;
             const steps = getScriptSteps(pkg, script);
             if (!steps.length)
@@ -98,6 +99,7 @@ export class RunService extends Service {
                 label: pkg.name,
                 steps,
                 cwd: pkg.dirname,
+                scopedTo: cwdScope,
                 topo: resolveBool(options.topo, pkg, script, 'topo', topo),
                 bail: resolveBail(options.bail, pkg, script, true),
                 logLevel: resolveLogLevel(options.logLevel, pkg, script, logLevelDefault),
@@ -162,6 +164,8 @@ export class RunService extends Service {
          *  abort using *its own* resolved bail setting (see `runSteps` below) - power-tasks' own
          *  `bail` is a single blanket policy for the whole batch, it can't vary per package. */
         let rootTask;
+        /** One `git` query per reference for every step's `if: changed`, as the scripts' share one. */
+        const stepIfCache = new Map();
         const runSteps = async (ctx, plan, steps, 
         /**
          * Which slice of the package's steps this call runs, when a `topo` step split it in two.
@@ -170,7 +174,7 @@ export class RunService extends Service {
          * one must not mark the package finished.
          */
         part) => {
-            const { pkg, cwd, bail: pkgBail, logLevel: pkgLogLevel, label: pkgLabel } = plan;
+            const { pkg, cwd, bail: pkgBail, logLevel: pkgLogLevel, label: pkgLabel, scopedTo } = plan;
             const from = part?.from ?? 0;
             /** Only the first part starts the clock: the row's elapsed time is the package's, and a
              *  package waiting at a `topo` barrier is waiting as part of its own run. */
@@ -181,6 +185,12 @@ export class RunService extends Service {
             try {
                 for (let i = from; i < steps.length; i++) {
                     const step = steps[i];
+                    /** Asked when the step's turn comes, not when the plan is made - a condition may read
+                     *  what the steps before it left behind. A step that says no is passed over in silence:
+                     *  it is not a failure, and announcing it on every package would bury the steps that ran. */
+                    if (step.if !== undefined && !(await passesIf(pkg.repository, pkg, step.if, cwd, stepIfCache, scopedTo))) {
+                        continue;
+                    }
                     ctx.currentStep = step.name;
                     /** The command for a shell step, the function's own name for a JS one - and a bare
                      *  marker for an anonymous function, which is still worth saying: the slot label alone
@@ -217,7 +227,7 @@ export class RunService extends Service {
                          * run step should.
                          */
                         if (step.run)
-                            await runFunctionStep(step.run, pkg, cwd, onLine, onCommand);
+                            await runFunctionStep(step.run, pkg, cwd, onLine, onCommand, scopedTo);
                         else {
                             await exec(step.command, {
                                 cwd,
@@ -583,6 +593,8 @@ export class RunService extends Service {
              *  (`{ command }` / `{ run }`) reaches here too and only one place knows the three spellings.
              *  `topo` cannot be set on this path - `normalizeScriptValue` refuses it for a version hook. */
             const step = toStep(slot, value);
+            if (step.if !== undefined && !(await passesIf(pkg.repository, pkg, step.if, pkg.dirname, new Map())))
+                continue;
             if (step.run) {
                 await step.run(createStepContext(pkg, pkg.dirname));
                 continue;
@@ -720,12 +732,13 @@ export class RunService extends Service {
      * whole of a build, because that is all the slot knows; what a reader wants is the `tsc -b
      * <tsconfig>` it is sitting in. A function step is the shape every shared config uses, so this is
      * the common case rather than an edge one. */
-    function createStepContext(pkg, cwd, onCommand, onLine) {
+    function createStepContext(pkg, cwd, onCommand, onLine, scopedTo) {
         const logLevel = resolveRootLogLevel(pkg.repository);
         return {
             pkg,
             repository: pkg.repository,
             cwd,
+            scopedTo,
             runBin: async (bin, argv, opts) => {
                 onCommand?.([bin, ...argv].join(' '));
                 const result = await runBin(bin, argv, { cwd, logLevel, app: pkg.repository.app, onLine, ...opts });
@@ -830,10 +843,12 @@ function describeValue(value) {
  *  the slot's own word for one passed inline, which has no name at all. */
 function toStep(slot, value) {
     const topo = typeof value === 'object' ? value.topo : undefined;
+    const condition = typeof value === 'object' ? value.if : undefined;
     const step = typeof value === 'object' ? value.command : value;
-    if (typeof step === 'function')
-        return { name: slot, label: step.name || `${slot} (js)`, run: step, topo };
-    return { name: slot, label: step, command: step, topo };
+    if (typeof step === 'function') {
+        return { name: slot, label: step.name || `${slot} (js)`, run: step, topo, if: condition };
+    }
+    return { name: slot, label: step, command: step, topo, if: condition };
 }
 /**
  * Checks a step written as an object and hands it back - a `command` that is a shell command or a
@@ -873,10 +888,20 @@ function assertStepObject(item, where, allowTopo) {
             throw new Error(`"${where}" must set "topo" to true or false, but it is ${describeValue(item.topo)}.`);
         }
     }
-    return { command: item.command, topo: item.topo };
+    /** The same two forms `run.<script>.if` takes. An empty string is refused rather than read as
+     *  "no condition": a key written and left blank is more likely a mistake than a decision. */
+    if (item.if !== undefined && typeof item.if !== 'function' && (typeof item.if !== 'string' || !item.if.trim())) {
+        throw new Error(`"${where}" must set "if" to a condition (\`changed\`, \`dirty and not committed\`) or a function, ` +
+            `but it is ${describeValue(item.if)}.`);
+    }
+    return {
+        command: item.command,
+        topo: item.topo,
+        ...(item.if !== undefined && { if: item.if }),
+    };
 }
-/** What a step object may hold - the step itself, and the marker beside it. */
-const STEP_OBJECT_KEYS = ['command', 'topo'];
+/** What a step object may hold - the step itself, and the markers beside it. */
+const STEP_OBJECT_KEYS = ['command', 'topo', 'if'];
 /**
  * Runs a function step, with its `console` captured into `onLine` - the step's own lines, routed to
  * whichever reporters the run has, beside those of the children it spawns.
@@ -894,8 +919,8 @@ const STEP_OBJECT_KEYS = ['command', 'topo'];
  * nowhere at all. Written to `onLine` on stderr, ahead of the step's `end` - the order a shell step
  * already produces.
  */
-async function runFunctionStep(run, pkg, cwd, onLine, onCommand) {
-    const context = RunService.createStepContext(pkg, cwd, onCommand, onLine);
+async function runFunctionStep(run, pkg, cwd, onLine, onCommand, scopedTo) {
+    const context = RunService.createStepContext(pkg, cwd, onCommand, onLine, scopedTo);
     try {
         await RunService.withCapturedConsole(onLine, () => run(context));
     }
@@ -920,15 +945,16 @@ function format(args) {
     return args.map(arg => (typeof arg === 'string' ? arg : inspect(arg))).join(' ');
 }
 /**
- * Whether a script runs for `pkg` at all - `run.<script>.if`, in either of its two forms.
+ * Whether a script runs for `pkg` at all - `run.<script>.if` - or a single step does (a step
+ * object's own `if`), in either of their two forms.
  *
  * The function form is checked **first**: `parseIfExpr` answers `undefined` for anything that is
  * not a string, which the caller reads as "no condition given", so a function reaching it would be
  * a condition that silently always passed.
  */
-async function passesIf(repository, pkg, raw, cwd, statusCache) {
+async function passesIf(repository, pkg, raw, cwd, statusCache, scopedTo) {
     if (typeof raw === 'function') {
-        return !!(await raw(RunService.createStepContext(pkg, cwd)));
+        return !!(await raw(RunService.createStepContext(pkg, cwd, undefined, undefined, scopedTo)));
     }
     const node = RunService.parseIfExpr(raw);
     return node ? RunService.evaluateIf(repository, pkg, node, statusCache) : true;