rman 2.8.0 → 2.9.0

package/core/config/config-paths.js

@@ -65,6 +65,30 @@ export const STEP_PATHS = [
     'version.before',
     'version.exec',
     'version.after',
+    /**
+     * The step inside a step's **object** form (`{ topo: true, command: buildWithTsc() }`).
+     *
+     * Array indices are dropped before matching but object keys are not, so `run.build.after[0].command`
+     * arrives as `run.build.after.command` - one segment longer than `run.*.after`, which matches by
+     * length. Without these the function would be taken for a *value* function and called while the
+     * repository loads, which is the exact failure the step/value split exists to prevent.
+     *
+     * **Measured on `@panates/rman-preset`**, whose build hook is a function under `command`: without
+     * these entries every command in a repository extending it died with
+     * `Config function in "run.build.after.command" (node/config.js) failed: Cannot read properties
+     * of undefined (reading 'vars')` - the hook called with the config scope instead of a step
+     * context, while merely resolving the config.
+     *
+     * A string at these paths is interpolated either way, which is what keeps
+     * `command: 'tsc -b ${{ file.resolve(...) }}'` working.
+     */
+    'run.*.command',
+    'run.*.before.command',
+    'run.*.exec.command',
+    'run.*.after.command',
+    'version.before.command',
+    'version.exec.command',
+    'version.after.command',
 ];
 /**
  * Config paths left untouched when a repository's config is first resolved, and evaluated only by

package/core/interfaces/custom-command.d.ts

@@ -1,9 +1,11 @@
 import type { ArgumentsCamelCase, Argv } from 'yargs';
 import type { RmanConfig as CommandDeclaration } from '../../interfaces/rman-config.interface.js';
+import type { RunService } from '../../services/run.service.js';
 import type { Logger } from '../../utils/logger.js';
 import type { RunBinOptions, RunBinResult } from '../../utils/run-bin.js';
 import type { Package } from '../classes/package.js';
 import type { Repository } from '../classes/repository.js';
+import type { RunStepFn } from './run-step.js';
 /** Where a repository keeps its own commands - one module per command, named after it. */
 export declare const CUSTOM_COMMAND_DIR = ".rman";
 /**
@@ -34,6 +36,43 @@ export interface CommandContext {
     runBin: (bin: string, argv: string[], options?: RunBinOptions) => Promise<RunBinResult>;
     /** Logger at this run's resolved level, for a command's own narration. */
     logger: Logger;
+    /**
+     * Runs `fn` once per package under the scheduler `run` uses - `--parallel`, `--bail`, dependency
+     * order on request, the progress panel, and `console` routed to the right row. Throws when any
+     * package failed, with the recap already printed.
+     *
+     * **A `for` loop is what this replaces, and the loop is worse in more ways than it looks.** It
+     * ignores `--parallel` outright, draws no panel, and leaves the command to re-implement `--bail`
+     * and a summary line. `rman check` was that loop: measured on a nineteen-package repository at
+     * 0.4-0.9s per package, eleven seconds of wall clock for work that is entirely independent.
+     *
+     * `fn` is handed exactly what a **function step** gets - `pkg`, `cwd`, a `runBin` already bound to
+     * that package's directory and this run's log level, and a `logger`. An imported `runBin` knows
+     * none of that, which is why a command using one had to thread `cwd`, `app` and `logLevel`
+     * through by hand at every call.
+     *
+     * ```js
+     * await context.forEachPackage(checkable, async ({ pkg, runBin }) => {
+     *   await runBin('dpdm', [...FLAGS, entry]);
+     * }, { label: 'check', parallel: args.parallel, bail: args.bail });
+     * ```
+     */
+    forEachPackage: (packages: readonly Package[], fn: RunStepFn, options?: RunService.ForEachOptions) => Promise<void>;
+    /**
+     * Runs `tasks` with at most `parallel` of them in flight - `Promise.all` under the repository's
+     * own concurrency rule.
+     *
+     * **The lower-level half, and the second thing to reach for.** It is the answer for work that is
+     * not per package (sharding a file list), and it buys nothing else: a bare list of functions
+     * carries no name, so there is no panel row to label, no package to name in a failure, and no
+     * dependency to order by. Anything per package wants `forEachPackage`.
+     *
+     * Rejects with the first failure once the tasks already started have settled, so nothing is left
+     * running behind the throw.
+     */
+    parallel: <T>(tasks: readonly (() => Promise<T>)[], options?: {
+        parallel?: boolean | number;
+    }) => Promise<T[]>;
 }
 /**
  * Which `.rmanrc` keys a command reads, for `--config` to print instead of running it - a dotted

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

@@ -62,9 +62,56 @@ export interface RunStepContext {
  * trouble only by returning something nobody reads is a step that passes while doing nothing.
  */
 export type RunStepFn = (context: RunStepContext) => void | Promise<void>;
-/** One entry of a `before`/`exec`/`after` slot: a shell command, or a function. A list of them runs
- *  in sequence, and the two forms mix freely within one list. */
-export type RunStepValue = string | RunStepFn;
+/**
+ * One step written as an object, which is how a step says something *about itself* - today, whether
+ * it has to wait for the package's dependencies.
+ *
+ * ```yml
+ * run:
+ *   build:
+ *     before:
+ *       - { topo: false, command: eslint . }   # nothing to wait for
+ *     exec: { topo: true, command: tsc -b }    # cannot start before the dependencies are built
+ * ```
+ *
+ * `command` is the step itself and takes the same two forms the plain value does - a shell command
+ * or a function - so the object adds the marker and takes nothing away. An unknown key is refused
+ * rather than ignored.
+ */
+export interface RunStepObject {
+    /**
+     * What the step runs: a shell command, or a function ([`RunStepFn`](#RunStepFn)), exactly as the
+     * plain value form. `${{ }}` in a string is interpolated as usual.
+     *
+     * One key for both, because `run.<script>.exec` is already one key taking both - a second name
+     * for the function case would mean two spellings of one thing and a rule about which to use.
+     */
+    command?: string | RunStepFn;
+    /**
+     * Whether this step waits for every package this one depends on to finish. `true` is the useful
+     * one - a `tsc -b` cannot start before the packages it compiles against are built, while an
+     * `eslint .` beside it has nothing to wait for.
+     *
+     * **The wait is for a dependency's whole script, so the *first* `true` is where the package
+     * actually blocks.** Everything after that has its dependencies behind it already, which makes a
+     * later `topo: false` a true statement about the step that changes nothing about when it runs -
+     * worth writing as intent, not a lever.
+     *
+     * **A script whose steps mention `topo` at all is taken as the whole statement**: the first
+     * `true` is the barrier, and if no step says `true` there is no wait. A script where no step
+     * mentions it falls back to `run.<script>.topo` - on by default - waiting before its first step,
+     * which is where the wait has always been. `run.<script>.topo: false` and `--no-topo` still turn
+     * ordering off outright.
+     *
+     * Only in `run.<script>`: a `version` hook runs for one package around its own version write,
+     * with no package graph to join, and the key is refused there rather than quietly doing nothing.
+     */
+    topo?: boolean;
+}
+/** 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
+ *  sequence, and the forms mix freely within one list. */
+export type RunStepValue = string | RunStepFn | RunStepObject;
 /**
  * A `run.<script>.if` written as JavaScript, deciding whether the script runs for this package.
  *

package/index.d.ts

@@ -66,7 +66,7 @@ export { Registry } from './core/classes/registry.js';
 export { Repository } from './core/classes/repository.js';
 export { Service, type ServiceFactory, type ServiceMap } from './core/classes/service.js';
 export { declaredTargets, type PublishTarget, shipsTo, targetsOf, unknownTargets, } from './core/interfaces/publish-target.js';
-export type { RunConditionFn, RunStepContext, RunStepFn, RunStepValue } from './core/interfaces/run-step.js';
+export type { RunConditionFn, RunStepContext, RunStepFn, RunStepObject, RunStepValue, } from './core/interfaces/run-step.js';
 /**
  * **`Platform` is one technology, whole**; **`Plugin` is whatever a package contributes**, platforms
  * among them.
@@ -124,6 +124,12 @@ export * from './services.js';
 /** Branch guarding: `allowBranch`/`ignoreBranch`, so a plugin's release command refuses to run on
  *  the wrong branch exactly as `publish` and `version` do. */
 export { applyBranchGuardOptions, assertAllowedBranch, type BranchGuardOptions, branchGuardOptions, readBranchGuardOptions, } from './utils/branch-guard.js';
+/**
+ * The flags every `run`-shaped command shares - `--parallel`, `--bail`, `--topo`, `--progress`,
+ * `--changed`, `--changed-since`, plus the package filters - and the reader that turns them into
+ * `RunService.Options`.
+ */
+export { parallelOptions, readParallelOptions, readRunOptions, runOptions } from './utils/run-options.js';
 /** Where a repository's locally installed binaries live - the core spells the PATH variable, a
  *  plugin says which directories go on it (see `Plugin.binPaths`). */
 export { BinPath } from './utils/bin-path.js';

package/index.js

@@ -106,6 +106,17 @@ export * from './services.js';
 /** Branch guarding: `allowBranch`/`ignoreBranch`, so a plugin's release command refuses to run on
  *  the wrong branch exactly as `publish` and `version` do. */
 export { applyBranchGuardOptions, assertAllowedBranch, branchGuardOptions, readBranchGuardOptions, } from './utils/branch-guard.js';
+/**
+ * The flags every `run`-shaped command shares - `--parallel`, `--bail`, `--topo`, `--progress`,
+ * `--changed`, `--changed-since`, plus the package filters - and the reader that turns them into
+ * `RunService.Options`.
+ */
+/* **Exported because a plugin cannot otherwise write an alias for `run <script>`.** `build` is one
+ * (`configKeys: ['run.build']`, a handler that calls `runScript`) and it reaches these through a
+ * relative import; a preset adding `compile` or `docs` had no way to, so it would restate the six
+ * flags and the reader - two lists free to disagree, which is how a flag ends up meaning one thing
+ * on `rman build` and nothing on the alias beside it. */
+export { parallelOptions, readParallelOptions, readRunOptions, runOptions } from './utils/run-options.js';
 /** Where a repository's locally installed binaries live - the core spells the PATH variable, a
  *  plugin says which directories go on it (see `Plugin.binPaths`). */
 export { BinPath } from './utils/bin-path.js';

package/interfaces/rman-config.interface.d.ts

@@ -1,7 +1,7 @@
 import type * as yargs from 'yargs';
 import type { RmanApplication } from '../core/application.js';
 import type { CodeSubtree } from '../core/config/config-paths.js';
-import type { CustomCommand } from '../core/interfaces/custom-command.js';
+import type { CommandContext, CustomCommand } from '../core/interfaces/custom-command.js';
 import type { Platform, Plugin } from '../core/interfaces/plugin.js';
 import type { PublishTarget } from '../core/interfaces/publish-target.js';
 import type { RunConditionFn, RunStepFn, RunStepValue } from '../core/interfaces/run-step.js';
@@ -577,7 +577,16 @@ export declare namespace RmanConfig {
          * `toYargsCommand` casts the handler to yargs' own and that cast is the single place the two
          * descriptions of argv are admitted to disagree.
          */
-        handler: (argv: never) => void;
+        /**
+         * The second parameter is the [`CommandContext`](../core/interfaces/custom-command.ts) - this
+         * run's `runBin`, `logger`, `forEachPackage` and `parallel` - and is **optional**, so a command
+         * that does not take it still satisfies this.
+         *
+         * `(args, context)` is the opposite order to `CustomCommand.handler`'s `(context, args)`, and
+         * the reason is compatibility rather than taste: every declared command in existence was
+         * `handler(args)`, so appending a parameter breaks none and prepending one breaks all.
+         */
+        handler: (argv: never, context?: CommandContext) => void;
     };
     /**
      * The names a command string declares as positionals: `'run <script> [args..]'` is
@@ -783,7 +792,16 @@ export declare namespace RmanConfig {
      * (`{ [K in string as K extends 'vars' ? never : K]: ... }`) was tried and does not help - the
      * remap still produces an index signature that claims `vars`.
      */
-    type RunConfig = Record<string, RunStepValue | RunStepValue[] | RunScriptOptions>;
+    /**
+     * **The bare shorthand is a command, a function or a list - never a single step *object*.** At
+     * this position an object is the long form (`{ exec, before, after, topo, ... }`), so admitting a
+     * `RunStepObject` beside it would make `run: { build: { topo: true, command: 'tsc -b' } }`
+     * type-check and then do nothing: `getConfig` reads an object as the options block, finds no
+     * `exec`, and the package reports declaring no such script. A list keeps the step object
+     * (`run: { build: [{ topo: true, command: 'tsc -b' }] }`), where there is nothing to confuse it
+     * with.
+     */
+    type RunConfig = Record<string, string | RunStepFn | RunStepValue[] | RunScriptOptions>;
     interface RunScriptOptions extends RunScriptOptionsKeys, ScopedVars {
     }
     /**

package/package.json

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

package/services/run.service.d.ts

@@ -4,6 +4,7 @@ import { Service } from '../core/classes/service.js';
 import type { RunStepContext, RunStepFn, RunStepValue } from '../core/interfaces/run-step.js';
 import { type LogLevel } from '../utils/logger.js';
 import { type PackageFilterOptions } from '../utils/package-filter.js';
+import { ProgressPanel } from '../utils/progress-panel.js';
 /**
  * A service class - see `ListService` for the shape and `Service` for the three measured
  * consequences a namespace had.
@@ -17,6 +18,66 @@ export declare class RunService extends Service {
     runScript(script: string, options?: RunService.Options & {
         commandName?: string;
     }): Promise<void>;
+    /**
+     * **The scheduler, shared by every driver that runs work per package.**
+     *
+     * `runScript` is one driver and `forEachPackage` is the other; both hand over a plan per package
+     * and get the same machinery, which is the point of this being a method rather than a shape each
+     * one builds for itself. Four things have had to be fixed in it this month alone - the status
+     * region handover, the depth-counted console patch, the per-row command, the failed list - and a
+     * second copy would have needed each fix twice, with nothing reporting the one that was missed.
+     *
+     * Throws when any package failed, with `logged` set: the panel has already printed the recap.
+     */
+    protected schedule(options: {
+        panel: ProgressPanel;
+        concurrency: number;
+        /** What the panel-off log lines call this run (`run`, `build`, `check`). */
+        commandName: string;
+        /** Named in the failure thrown when a package fails - `"build" failed`. */
+        failureLabel: string;
+        /** A repo-wide bookend run first, alone, which every package then waits for. */
+        before?: RunService.PackagePlan;
+        plans: RunService.PackagePlan[];
+        /** A repo-wide bookend run last, alone, after every package. */
+        after?: RunService.PackagePlan;
+    }): Promise<void>;
+    /**
+     * Runs `fn` once per package, under the same scheduler `run` uses - concurrency, `--bail`,
+     * dependency order, the progress panel, and `console` routed to the right row.
+     *
+     * **This is what a command reaches for instead of a `for` loop.** `check` was that loop: `await
+     * runBin(...)` per package, which ignores `--parallel` outright, draws no panel, and had
+     * re-implemented `--bail`, the package filters, the two-endings rule and a summary line - about
+     * sixty lines of this service, already drifted (its own tally counted packages a bail had skipped
+     * as successes, a bug fixed here separately). Measured on `panates/opra`: nineteen packages at
+     * 0.4-0.9s each, so eleven seconds of wall clock where the work is entirely independent.
+     *
+     * `fn` is handed exactly what a **function step** gets - `pkg`, `cwd`, a `runBin` already bound to
+     * that package's directory and this run's log level, and a `logger`. That is the answer to the
+     * complaint this exists for: an imported `runBin` knows neither, and a command reaching for one
+     * had to thread `cwd`, `app` and `logLevel` through by hand at every call.
+     *
+     * Ordering is **off** unless `topo` asks for it: a command sweeping packages with an independent
+     * tool is the common case, and a wait nobody asked for is the more expensive mistake here.
+     */
+    forEachPackage(packages: readonly Package[], fn: RunStepFn, options?: RunService.ForEachOptions): Promise<void>;
+    /**
+     * Runs `tasks` with at most `parallel` of them in flight - `Promise.all` under the repository's
+     * own concurrency rule.
+     *
+     * **The low-level half of `forEachPackage`, for work that is not per package** - sharding a file
+     * list across cores, say. It buys the concurrency limit and nothing else: a bare list of functions
+     * carries no name, so there is no panel row to label, nothing to name in a failure, and no
+     * dependency to order by. That is why it is the second thing to reach for, not the first.
+     *
+     * **Settles the tasks already in flight before rejecting.** A plain `Promise.all` rejects on the
+     * first failure while its siblings keep running - with child processes behind them, that leaves
+     * output arriving after the command has reported and exited.
+     */
+    parallel<T>(tasks: readonly (() => Promise<T>)[], options?: {
+        parallel?: boolean | number;
+    }): Promise<T[]>;
 }
 export declare namespace RunService {
     export interface Options extends PackageFilterOptions {
@@ -41,6 +102,49 @@ export declare namespace RunService {
          *  root, or outside any known package. */
         fromRoot?: boolean;
     }
+    /** What `forEachPackage` takes - the scheduling half of `Options`, with no script to read it from
+     *  the config and no package filtering, which the caller has already done. */
+    export interface ForEachOptions {
+        /** Max packages at once: `true`/omitted = CPU count, a number = that many, `false` = serial. */
+        parallel?: boolean | number;
+        /** Stop the batch at the first failure. Default `true`, as `run`'s is. */
+        bail?: boolean;
+        /**
+         * Wait for a package's dependencies before running it. **Default `false`**, unlike `run`'s: a
+         * command sweeping packages with an independent tool is the common case here, and a wait nobody
+         * asked for costs the whole point of the call.
+         */
+        topo?: boolean;
+        /** Show the live progress panel. Default true; auto-disabled when stdout isn't a TTY. */
+        progress?: boolean;
+        logLevel?: LogLevel;
+        /** The panel's title, the row's step name and the word in the failure - the command's own name
+         *  (`check`) reads best. */
+        label?: string;
+    }
+    /**
+     * One package's share of a scheduled run: what to do, where, and under which rules.
+     *
+     * **The unit the scheduler takes, and why it is a package rather than a bare function.** A row has
+     * to be named for the panel to label it, for the summary to say which package failed, and for the
+     * failed list to have something to list; a dependency edge has to name a package for ordering to
+     * mean anything. A `(() => Promise<void>)[]` carries neither, which is what makes it the wrong
+     * shape for this even though it is the obvious one.
+     */
+    export interface PackagePlan {
+        pkg: Package;
+        /** The panel row's name and the task's - unique within the run, and a package's own name, which
+         *  is what lets dependency edges be handed to power-tasks as names. */
+        name: string;
+        /** What the panel-off log line calls it: the package's name, or `root` for a bookend. */
+        label: string;
+        steps: ScriptStep[];
+        /** The directory the steps run in - the package's own, or the repository root for a bookend. */
+        cwd: string;
+        topo: boolean;
+        bail: boolean;
+        logLevel: LogLevel;
+    }
     /**
      * A package's `.rmanrc` (cascaded) can configure `run.<script>.*` - e.g.
      *   run:
@@ -83,6 +187,10 @@ export declare namespace RunService {
         /** What the progress panel and the per-step log print: the command itself, or the function's
          *  own name. */
         label: string;
+        /** What a step written as an object said about waiting, `undefined` for one that said nothing -
+         *  and the three are three different answers, which is why this is not a plain boolean. See
+         *  `RunStepObject.topo`. */
+        topo?: boolean;
     }
     export interface CommandStep extends StepBase {
         command: string;
@@ -167,7 +275,9 @@ export declare namespace RunService {
      * Exported, and the only implementation: `VersionService` used to carry a second one that behaved
      * differently, which is how `version.<slot>` came to join its array with `' && '`.
      */
-    export function normalizeScriptValue(value: unknown, at: string): RunStepValue[];
+    export function normalizeScriptValue(value: unknown, at: string, options?: {
+        topo?: boolean;
+    }): RunStepValue[];
     /**
      * Runs `fn` with `console` captured into `onLine`, and leaves the real `console` behind when the
      * last concurrent step is done.
@@ -224,6 +334,20 @@ export declare function resolveBool(cliValue: boolean | undefined, pkg: Package,
  */
 export declare function resolveBail(cliValue: boolean | undefined, pkg: Package, script: string, fallback: boolean): boolean;
 export declare function resolveNumber(cliValue: number | undefined, pkg: Package, script: string, key: string, fallback: number): number;
+/**
+ * How many packages run at once: what the flag said, or `whenUnset` where it said nothing.
+ *
+ * **`--parallel` and `concurrency` are deliberately different names**, so this is where the two
+ * meet: the flag is `boolean | number` (omit/`true` = CPU count, `false` = serially), the key is the
+ * number it resolves to. It was written out at `runScript`'s top and two more callers need the same
+ * answer - three copies of a four-branch ternary is how a flag comes to mean something slightly
+ * different depending on which command you typed.
+ *
+ * **Where the unset case comes from is the caller's**, and deliberately not read here: `run`'s is
+ * `run.<script>.concurrency`, while a command calling `forEachPackage` owns a key of its own
+ * (`check.concurrency`) that this function has no business guessing the name of.
+ */
+export declare function resolveConcurrency(parallel: boolean | number | undefined, whenUnset: number): number;
 export declare function resolveLogLevel(cliValue: LogLevel | undefined, pkg: Package, script: string, fallback: LogLevel): LogLevel;
 declare module '../core/classes/service.js' {
     interface ServiceMap {