rman 2.8.0 → 2.9.0

package/services/run.service.js

@@ -42,24 +42,133 @@ export class RunService extends Service {
             const status = await repository.listStatus({ hash: changedSince });
             packages = packages.filter(p => status[p.name] !== 'clean');
         }
-        const concurrency = options.parallel === false
-            ? 1
-            : typeof options.parallel === 'number'
-                ? options.parallel
-                : options.parallel === true
-                    ? os.cpus().length
-                    : resolveNumber(undefined, repository.rootPackage, script, 'concurrency', os.cpus().length);
+        const concurrency = resolveConcurrency(options.parallel, resolveNumber(undefined, repository.rootPackage, script, 'concurrency', os.cpus().length));
         const progress = resolveBool(options.progress, repository.rootPackage, script, 'progress', true);
         const panel = new ProgressPanel(`RUN ${script}`, !!process.stdout.isTTY && progress);
+        /** Shared across all `if: changed[ = hash]` evaluations so the same reference is only `git`-queried once. */
+        const ifStatusCache = new Map();
+        /** Repo-wide bookend: root's own pre/post hooks run once each, exclusively, around every package
+         *  (unless root itself opts out via `run.<script>.skip`, fails its own `run.<script>.if`, or the
+         *  run is scoped to a single package by `cwdScope` - a repo-wide bookend has no place there).
+         *
+         *  Only in a monorepo. Without one the root *is* the single package, already in the loop below
+         *  with the same hooks and the same directory - a bookend would simply run each of them a
+         *  second time. */
+        /** Short-circuited deliberately: a root already out of the run for a structural reason must not
+         *  have its `if` evaluated, now that evaluating one can mean calling the repository's own code. */
+        const rootSkipped = !!cwdScope ||
+            !repository.monorepo ||
+            rootCfg.skip === true ||
+            !(await passesIf(repository, repository.rootPackage, rootCfg.if, repository.dirname, ifStatusCache));
+        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
+         *  out with the package.json source. */
+        const bookend = (slot, name) => {
+            const steps = rootSteps.filter(s => s.name === slot);
+            if (!steps.length)
+                return undefined;
+            return {
+                pkg: repository.rootPackage,
+                name,
+                label: 'root',
+                steps,
+                cwd: repository.dirname,
+                topo: false,
+                bail: resolveBail(options.bail, repository.rootPackage, script, true),
+                logLevel: resolveLogLevel(options.logLevel, repository.rootPackage, script, logLevelDefault),
+            };
+        };
+        const before = bookend('before', 'root (pre)');
+        const after = bookend('after', 'root (post)');
+        const plans = [];
+        for (const pkg of packages) {
+            const pkgCfg = RunService.getConfig(pkg, script);
+            if (pkgCfg.skip === true)
+                continue;
+            if (!(await passesIf(repository, pkg, pkgCfg.if, pkg.dirname, ifStatusCache)))
+                continue;
+            const steps = getScriptSteps(pkg, script);
+            if (!steps.length)
+                continue;
+            plans.push({
+                pkg,
+                name: pkg.name,
+                label: pkg.name,
+                steps,
+                cwd: pkg.dirname,
+                topo: resolveBool(options.topo, pkg, script, 'topo', topo),
+                bail: resolveBail(options.bail, pkg, script, true),
+                logLevel: resolveLogLevel(options.logLevel, pkg, script, logLevelDefault),
+            });
+        }
+        if (!plans.length && !before && !after) {
+            /**
+             * Two different nothings, and only one of them is fine.
+             *
+             * Nobody in the repository defines this script at all: the name is a mistake - a typo, or a
+             * script that used to exist - and `npm run` fails on exactly this. Staying silent is how
+             * `rman run qc` sat in a CI pipeline for months reporting success while running nothing, with
+             * `qc` defined only on the root (whose own scripts a monorepo never runs, only its
+             * `pre`/`post` bookends).
+             *
+             * Everything was filtered out instead - `--scope`, `--changed`, `run.<script>.skip`, an
+             * `if:` that didn't match: zero is the correct answer to what was asked, and asking "build
+             * only what changed" when nothing changed must not fail a pipeline.
+             */
+            /** `getPackages()` and nothing else - in a monorepo that excludes the root, which is the
+             *  point: the root contributes only `pre`/`post` bookends, never the script itself, so a
+             *  `qc` defined *only* there is exactly the mistake above rather than an excuse for it. (And
+             *  had the root contributed a bookend, there would be a plan.) In a single-package
+             *  repository the root *is* the one package, and is covered. */
+            const definedSomewhere = repository.getPackages().some(pkg => getScriptSteps(pkg, script).length > 0);
+            if (definedSomewhere) {
+                console.log(colors.gray(`Nothing to run - every package was filtered out of "${script}".`));
+                return;
+            }
+            const message = `No package defines a "${script}" script.`;
+            console.log(colors.red(message));
+            const err = new Error(message);
+            err.logged = true;
+            throw err;
+        }
+        await this.schedule({ panel, concurrency, commandName, failureLabel: `"${script}"`, before, plans, after });
+    }
+    /**
+     * **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.
+     */
+    async schedule(options) {
+        const { panel, concurrency, commandName } = options;
         /** Set once the aggregate Task exists, so a package's own failure can trigger a manual
          *  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;
-        const runSteps = async (ctx, pkg, pkgLabel, steps, cwd, pkgBail, pkgLogLevel) => {
-            ctx.status = 'running';
-            ctx.startedAt = Date.now();
+        const runSteps = async (ctx, plan, steps, 
+        /**
+         * Which slice of the package's steps this call runs, when a `topo` step split it in two.
+         * `from` keeps `stepIndex` counting across the pair, so one panel row spans both tasks and
+         * still reports `(4/9)` rather than restarting; `more` says another call is coming, so this
+         * one must not mark the package finished.
+         */
+        part) => {
+            const { pkg, cwd, bail: pkgBail, logLevel: pkgLogLevel, label: pkgLabel } = 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. */
+            if (!from) {
+                ctx.status = 'running';
+                ctx.startedAt = Date.now();
+            }
             try {
-                for (let i = 0; i < steps.length; i++) {
+                for (let i = from; i < steps.length; i++) {
                     const step = steps[i];
                     ctx.currentStep = step.name;
                     /** The command for a shell step, the function's own name for a JS one - and a bare
@@ -120,6 +229,15 @@ export class RunService extends Service {
                             throw stepError;
                     }
                 }
+                /** Another part is coming, so the package is not done - and it is about to sit at the
+                 *  barrier, which the row says out loud rather than leaving the last step's command on
+                 *  screen as though it were still running. (The setter clears the row's last output line,
+                 *  which would otherwise read as that step's.) */
+                if (part?.more) {
+                    ctx.currentStep = 'waiting';
+                    ctx.currentCommand = 'waiting for dependencies';
+                    return;
+                }
                 ctx.status = 'success';
             }
             catch (e) {
@@ -129,114 +247,79 @@ export class RunService extends Service {
                 throw e;
             }
             finally {
-                ctx.finishedAt = Date.now();
+                if (!part?.more || ctx.status === 'failed')
+                    ctx.finishedAt = Date.now();
             }
         };
         const children = [];
-        /** Shared across all `if: changed[ = hash]` evaluations so the same reference is only `git`-queried once. */
-        const ifStatusCache = new Map();
-        /** Repo-wide bookend: root's own pre/post hooks run once each, exclusively, around every package
-         *  (unless root itself opts out via `run.<script>.skip`, fails its own `run.<script>.if`, or the
-         *  run is scoped to a single package by `cwdScope` - a repo-wide bookend has no place there).
-         *
-         *  Only in a monorepo. Without one the root *is* the single package, already in the loop below
-         *  with the same hooks and the same directory - a bookend would simply run each of them a
-         *  second time. */
-        /** Short-circuited deliberately: a root already out of the run for a structural reason must not
-         *  have its `if` evaluated, now that evaluating one can mean calling the repository's own code. */
-        const rootSkipped = !!cwdScope ||
-            !repository.monorepo ||
-            rootCfg.skip === true ||
-            !(await passesIf(repository, repository.rootPackage, rootCfg.if, repository.dirname, ifStatusCache));
-        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
-         *  out with the package.json source. */
-        const rootPre = rootSteps.filter(s => s.name === 'before');
-        const rootPost = rootSteps.filter(s => s.name === 'after');
-        const rootPreName = 'root (pre)';
-        const rootPostName = 'root (post)';
-        if (rootPre.length) {
-            const ctx = panel.addItem(rootPreName, rootPre.length);
-            const pkgBail = resolveBail(options.bail, repository.rootPackage, script, true);
-            const pkgLogLevel = resolveLogLevel(options.logLevel, repository.rootPackage, script, logLevelDefault);
-            children.push(new Task(() => runSteps(ctx, repository.rootPackage, 'root', rootPre, repository.dirname, pkgBail, pkgLogLevel), {
-                name: ctx.name,
-                exclusive: true,
-            }));
+        /** Row and task names are the plan's, and a package's is its package name - which is what lets
+         *  the dependency edges below be handed to power-tasks as names. Mapped rather than assumed, so
+         *  a driver labelling its rows differently does not silently lose its ordering. */
+        const taskOf = new Map(options.plans.map(plan => [plan.pkg.name, plan.name]));
+        if (options.before) {
+            const plan = options.before;
+            const ctx = panel.addItem(plan.name, plan.steps.length);
+            children.push(new Task(() => runSteps(ctx, plan, plan.steps), { name: plan.name, exclusive: true }));
         }
-        const stepsByPackage = new Map();
-        for (const pkg of packages) {
-            const pkgCfg = RunService.getConfig(pkg, script);
-            if (pkgCfg.skip === true)
-                continue;
-            if (!(await passesIf(repository, pkg, pkgCfg.if, pkg.dirname, ifStatusCache)))
-                continue;
-            const steps = getScriptSteps(pkg, script);
-            if (steps.length)
-                stepsByPackage.set(pkg.name, steps);
-        }
-        for (const pkg of packages) {
-            const steps = stepsByPackage.get(pkg.name);
-            if (!steps)
-                continue;
-            const ctx = panel.addItem(pkg.name, steps.length);
-            const pkgTopo = resolveBool(options.topo, pkg, script, 'topo', topo);
-            const pkgBail = resolveBail(options.bail, pkg, script, true);
-            const pkgLogLevel = resolveLogLevel(options.logLevel, pkg, script, logLevelDefault);
+        for (const plan of options.plans) {
+            const ctx = panel.addItem(plan.name, plan.steps.length);
+            const steps = plan.steps;
             /** power-tasks identifies a task by its name string, so the graph is handed over as names -
              *  the references are what rman reasons with, the names are what the scheduler wants. */
-            const dependencies = pkgTopo ? pkg.dependencies.filter(d => stepsByPackage.has(d.name)).map(d => d.name) : [];
-            if (rootPre.length)
-                dependencies.push(rootPreName);
-            children.push(new Task(() => runSteps(ctx, pkg, pkg.name, steps, pkg.dirname, pkgBail, pkgLogLevel), {
-                name: ctx.name,
-                dependencies,
-            }));
-        }
-        if (rootPost.length) {
-            const ctx = panel.addItem(rootPostName, rootPost.length);
-            const pkgBail = resolveBail(options.bail, repository.rootPackage, script, true);
-            const pkgLogLevel = resolveLogLevel(options.logLevel, repository.rootPackage, script, logLevelDefault);
-            children.push(new Task(() => runSteps(ctx, repository.rootPackage, 'root', rootPost, repository.dirname, pkgBail, pkgLogLevel), {
-                name: ctx.name,
-                exclusive: true,
-                /** Must wait for every package task to finish, not just be "exclusive" once it starts. */
-                dependencies: [...stepsByPackage.keys()],
-            }));
-        }
-        if (!children.length) {
+            const waitsFor = plan.topo
+                ? plan.pkg.dependencies.map(d => taskOf.get(d.name)).filter((name) => !!name)
+                : [];
             /**
-             * Two different nothings, and only one of them is fine.
+             * **Where this package starts waiting for its dependencies**, or `-1` for not at all.
              *
-             * Nobody in the repository defines this script at all: the name is a mistake - a typo, or a
-             * script that used to exist - and `npm run` fails on exactly this. Staying silent is how
-             * `rman run qc` sat in a CI pipeline for months reporting success while running nothing, with
-             * `qc` defined only on the root (whose own scripts a monorepo never runs, only its
-             * `pre`/`post` bookends).
+             * A script whose steps mention `topo` at all is taken as the whole statement: the first step
+             * saying `true` is where the package blocks, and a script where every step says `false` does
+             * not wait. Only where **no** step mentions it does `run.<script>.topo` decide, and then the
+             * wait is before the first step - where it has always been.
              *
-             * Everything was filtered out instead - `--scope`, `--changed`, `run.<script>.skip`, an
-             * `if:` that didn't match: zero is the correct answer to what was asked, and asking "build
-             * only what changed" when nothing changed must not fail a pipeline.
+             * The two halves cannot be collapsed into one `findIndex`: "no step marked true" and "no step
+             * marked at all" are different answers (no wait against the old wait at step 0), and reading
+             * `-1` as either one alone gets the other wrong.
              */
-            /** `getPackages()` and nothing else - in a monorepo that excludes the root, which is the
-             *  point: the root contributes only `pre`/`post` bookends, never the script itself, so a
-             *  `qc` defined *only* there is exactly the mistake above rather than an excuse for it. (And
-             *  had the root contributed a bookend, `children` wouldn't be empty.) In a single-package
-             *  repository the root *is* the one package, and is covered. */
-            const definedSomewhere = repository.getPackages().some(pkg => getScriptSteps(pkg, script).length > 0);
-            if (definedSomewhere) {
-                console.log(colors.gray(`Nothing to run - every package was filtered out of "${script}".`));
-                return;
+            const barrier = !plan.topo ? -1 : steps.some(s => s.topo !== undefined) ? steps.findIndex(s => s.topo) : 0;
+            /**
+             * **Split only when the wait is in the middle of the package and there is something to wait
+             * for.** A barrier at step 0 is one task, as it always was; a package with no in-run
+             * dependencies has nothing to wait for wherever its barrier sits, and a second task would buy
+             * an empty wait and a second panel transition for it.
+             */
+            if (barrier > 0 && waitsFor.length) {
+                /** A name of its own, because power-tasks addresses tasks by name and the plan's name has to
+                 *  stay the *whole* package: a dependency waiting on it, and the root's post bookend
+                 *  waiting on all of them, both mean "everything this package does". */
+                const freeName = `${plan.name} (pre-topo)`;
+                children.push(new Task(() => runSteps(ctx, plan, steps.slice(0, barrier), { from: 0, more: true }), {
+                    name: freeName,
+                    dependencies: options.before ? [options.before.name] : [],
+                }));
+                children.push(new Task(() => runSteps(ctx, plan, steps, { from: barrier }), {
+                    name: plan.name,
+                    dependencies: [freeName, ...waitsFor],
+                }));
+                continue;
             }
-            const message = `No package defines a "${script}" script.`;
-            console.log(colors.red(message));
-            const err = new Error(message);
-            err.logged = true;
-            throw err;
+            const dependencies = barrier < 0 ? [] : [...waitsFor];
+            if (options.before)
+                dependencies.push(options.before.name);
+            children.push(new Task(() => runSteps(ctx, plan, steps), { name: plan.name, dependencies }));
+        }
+        if (options.after) {
+            const plan = options.after;
+            const ctx = panel.addItem(plan.name, plan.steps.length);
+            children.push(new Task(() => runSteps(ctx, plan, plan.steps), {
+                name: plan.name,
+                exclusive: true,
+                /** Must wait for every package task to finish, not just be "exclusive" once it starts. */
+                dependencies: [...taskOf.values()],
+            }));
         }
-        panel.detail = repository.name;
-        panel.start(repository.app.statusRegion);
+        panel.detail = this.repository.name;
+        panel.start(this.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. */
@@ -257,17 +340,121 @@ export class RunService extends Service {
             panel.stop();
         }
         const summary = panel.printSummary();
+        /** The tallies, never `rootTask.toPromise()`'s own outcome: with a sibling still in flight at
+         *  the moment one package failed, that promise *resolves*, and this command used to exit 0 on a
+         *  run it had just reported as failed - non-deterministically, since it came down to which
+         *  packages happened to still be running (measured: `1 0 1 1 0` across five identical runs).
+         *  A single failed package must fail the command, every time. */
         /** The tallies, never `rootTask.toPromise()`'s own outcome: with a sibling still in flight at
          *  the moment one package failed, that promise *resolves*, and this command used to exit 0 on a
          *  run it had just reported as failed - non-deterministically, since it came down to which
          *  packages happened to still be running (measured: `1 0 1 1 0` across five identical runs).
          *  A single failed package must fail the command, every time. */
         if (summary.failedCount > 0) {
-            const err = new Error(`"${script}" failed`);
+            const err = new Error(`${options.failureLabel} failed`);
             err.logged = true;
             throw err;
         }
     }
+    /**
+     * 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.
+     */
+    async forEachPackage(packages, fn, options = {}) {
+        const repository = this.repository;
+        const label = options.label ?? 'each';
+        const logLevel = options.logLevel ?? resolveRootLogLevel(repository);
+        const concurrency = resolveConcurrency(options.parallel, os.cpus().length);
+        const panel = new ProgressPanel(label.toUpperCase(), !!process.stdout.isTTY && options.progress !== false);
+        /** Nothing to do is not a failure, and the caller is the one that can tell the two endings
+         *  apart - it knows why its list is empty. `check` says so itself and returns. */
+        if (!packages.length)
+            return;
+        /**
+         * **The step's label is the function's own name, and empty for an anonymous one** - never the
+         * run's label repeated. A sweep has one step whose slot name is already the label, so falling
+         * back to it printed the same word three times on the panel-off line:
+         * `info check @opra/testing ┆ check success ┆ check`. The panel path never had it - a row shows
+         * whatever `runBin` spawned (`dpdm -T ...`) as soon as there is one.
+         */
+        const steps = [{ name: label, label: fn.name, run: fn }];
+        const plans = packages.map(pkg => ({
+            pkg,
+            name: pkg.name,
+            label: pkg.name,
+            /** One step object per package, not one shared: `ScriptStep` is read for `topo` and the row's
+             *  own labels, and a shared object would be fine today and a race the day a driver writes to
+             *  it. */
+            steps: [...steps],
+            cwd: pkg.dirname,
+            topo: options.topo === true,
+            bail: options.bail !== false,
+            logLevel,
+        }));
+        await this.schedule({
+            panel,
+            concurrency,
+            commandName: label,
+            failureLabel: `"${label}"`,
+            plans,
+        });
+    }
+    /**
+     * 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.
+     */
+    async parallel(tasks, options = {}) {
+        const limit = Math.max(1, resolveConcurrency(options.parallel, os.cpus().length));
+        const results = new Array(tasks.length);
+        const running = new Set();
+        let failure;
+        let failed = false;
+        for (let i = 0; i < tasks.length; i++) {
+            if (failed)
+                break;
+            const index = i;
+            const started = (async () => {
+                results[index] = await tasks[index]();
+            })().catch(error => {
+                if (!failed) {
+                    failed = true;
+                    failure = error;
+                }
+            });
+            running.add(started);
+            void started.finally(() => running.delete(started));
+            if (running.size >= limit)
+                await Promise.race(running);
+        }
+        await Promise.allSettled(running);
+        if (failed)
+            throw failure;
+        return results;
+    }
 }
 (function (RunService) {
     /**
@@ -311,11 +498,15 @@ export class RunService extends Service {
     async function runLifecycleSlot(pkg, script, slot, fallback) {
         const values = slotValues(slot, contributedSlots(pkg, script)?.[slot] ?? [], fallback ?? [], false);
         for (const value of values) {
-            if (typeof value === 'function') {
-                await value(createStepContext(pkg, pkg.dirname));
+            /** Through `toStep` rather than reading the value's own shape, so the object form
+             *  (`{ 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.run) {
+                await step.run(createStepContext(pkg, pkg.dirname));
                 continue;
             }
-            await exec(value, { cwd: pkg.dirname, stdio: 'inherit', app: pkg.repository.app });
+            await exec(step.command, { cwd: pkg.dirname, stdio: 'inherit', app: pkg.repository.app });
         }
     }
     RunService.runLifecycleSlot = runLifecycleSlot;
@@ -349,7 +540,7 @@ export class RunService extends Service {
      * 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 `' && '`.
      */
-    function normalizeScriptValue(value, at) {
+    function normalizeScriptValue(value, at, options) {
         const items = Array.isArray(value) ? value : [value];
         const steps = [];
         for (let i = 0; i < items.length; i++) {
@@ -358,13 +549,18 @@ export class RunService extends Service {
              *  declaring a slot some packages don't use has always behaved. */
             if (item === undefined || item === null || item === '')
                 continue;
+            const where = Array.isArray(value) ? `${at}[${i}]` : at;
             if (typeof item === 'string' || typeof item === 'function') {
                 steps.push(item);
                 continue;
             }
-            const where = Array.isArray(value) ? `${at}[${i}]` : at;
-            throw new Error(`"${where}" must be a shell command or a function, but it is ${describeValue(item)}.\n` +
-                `  A list of either (or both) runs them in sequence.`);
+            if (item && typeof item === 'object' && !Array.isArray(item)) {
+                steps.push(assertStepObject(item, where, options?.topo !== false));
+                continue;
+            }
+            throw new Error(`"${where}" must be a shell command, a function, or { command | run, topo }, ` +
+                `but it is ${describeValue(item)}.\n` +
+                `  A list of any of them runs them in sequence.`);
         }
         return steps;
     }
@@ -540,7 +736,7 @@ function printLegacyExecutingLine(commandName, pkgLabel, step, level) {
     if (LOG_LEVELS.indexOf(level) < LOG_LEVELS.indexOf('verbose'))
         return;
     const sep = colors.gray('┆');
-    console.log(colors.magenta('verbose'), commandName, colors.cyan(pkgLabel), sep, colors.cyanBright.bold(step.name), colors.cyanBright.bold('executing'), sep, step.label);
+    console.log(colors.magenta('verbose'), commandName, colors.cyan(pkgLabel), sep, colors.cyanBright.bold(step.name), colors.cyanBright.bold('executing'), ...describing(step));
 }
 function printLegacyStepLine(commandName, pkgLabel, step, durationMs, level, error) {
     if (!error && LOG_LEVELS.indexOf(level) < LOG_LEVELS.indexOf('info'))
@@ -550,7 +746,13 @@ function printLegacyStepLine(commandName, pkgLabel, step, durationMs, level, err
     const sep = colors.gray('┆');
     const levelLabel = error ? colors.red('error') : colors.green('info');
     const status = error ? colors.red.bold('failed') : colors.green.bold('success');
-    console.log(levelLabel, commandName, colors.cyan(pkgLabel), sep, colors.cyanBright.bold(step.name), status, sep, step.label, colors.yellow(` (${durationMs} ms)`));
+    console.log(levelLabel, commandName, colors.cyan(pkgLabel), sep, colors.cyanBright.bold(step.name), status, ...describing(step), colors.yellow(` (${durationMs} ms)`));
+}
+/** The `┆ <what it runs>` tail of a legacy log line, **or nothing at all** when the step has no
+ *  label of its own - an anonymous function handed to `forEachPackage`, where the slot name already
+ *  said everything there is to say and a separator with nothing after it is just noise. */
+function describing(step) {
+    return step.label ? [colors.gray('┆'), step.label] : [];
 }
 function describeValue(value) {
     if (Array.isArray(value))
@@ -563,10 +765,54 @@ function describeValue(value) {
  *  `function copyDocs()` and `const copyDocs = () => {}` both read as `copyDocs` - falling back to
  *  the slot's own word for one passed inline, which has no name at all. */
 function toStep(slot, value) {
-    if (typeof value === 'function')
-        return { name: slot, label: value.name || `${slot} (js)`, run: value };
-    return { name: slot, label: value, command: value };
+    const topo = typeof value === 'object' ? value.topo : 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 };
 }
+/**
+ * Checks a step written as an object and hands it back - a `command` that is a shell command or a
+ * function, and a boolean `topo` where ordering means anything.
+ *
+ * **An unknown key is refused, which is most of what this is for.** The object form exists to carry
+ * one marker beside the step, so anything else in it is a mistake with no effect - and the mistake
+ * is a plausible one: `{ topo: true, script: 'tsc -b' }` reads perfectly well and names the key rman
+ * uses for the *lifecycle* (`run.<script>`) rather than the step. Ignored, that step would silently
+ * run nothing while the run reported success, which is the failure `normalizeScriptValue` was
+ * already rewritten once to stop.
+ *
+ * **`command` takes a function as well as a string**, because `run.<script>.exec` already does: a
+ * second key for the function case would be two spellings of one thing plus a rule about which to
+ * use. The first draft of this did have one (`run`), and the config that drove the feature -
+ * `@panates/rman-preset`'s build hook - reached for `command` without being asked.
+ *
+ * `allowTopo` is false for `version`'s hooks: they belong to one package's version write, with no
+ * package graph to wait on, so the key means nothing there and says so rather than being dropped.
+ */
+function assertStepObject(item, where, allowTopo) {
+    for (const key of Object.keys(item)) {
+        if (!STEP_OBJECT_KEYS.includes(key)) {
+            throw new Error(`"${where}" has an unknown key "${key}". A step object takes ${STEP_OBJECT_KEYS.join(', ')}.\n` +
+                `  The step itself goes in "command" - "script" is the name of the lifecycle, not the step.`);
+        }
+    }
+    if (typeof item.command !== 'function' && (typeof item.command !== 'string' || item.command === '')) {
+        throw new Error(`"${where}" must set "command" to a shell command or a function, but it is ` + `${describeValue(item.command)}.`);
+    }
+    if (item.topo !== undefined) {
+        if (!allowTopo) {
+            throw new Error(`"${where}" cannot set "topo": it is a version hook, which runs for one package and has no\n` +
+                `  dependency order to wait for. The key belongs to run.<script> steps.`);
+        }
+        if (typeof item.topo !== 'boolean') {
+            throw new Error(`"${where}" must set "topo" to true or false, but it is ${describeValue(item.topo)}.`);
+        }
+    }
+    return { command: item.command, topo: item.topo };
+}
+/** What a step object may hold - the step itself, and the marker beside it. */
+const STEP_OBJECT_KEYS = ['command', 'topo'];
 /**
  * Runs a function step.
  *
@@ -802,6 +1048,28 @@ export function resolveNumber(cliValue, pkg, script, key, fallback) {
     const v = RunService.getConfig(pkg, script)[key];
     return typeof v === 'number' ? v : fallback;
 }
+/**
+ * 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 function resolveConcurrency(parallel, whenUnset) {
+    if (parallel === false)
+        return 1;
+    if (typeof parallel === 'number')
+        return parallel;
+    if (parallel === true)
+        return os.cpus().length;
+    return whenUnset;
+}
 export function resolveLogLevel(cliValue, pkg, script, fallback) {
     if (cliValue !== undefined)
         return cliValue;

package/services/version.service.d.ts

@@ -101,6 +101,8 @@ export declare namespace VersionService {
      * never run. (The doc comment also still named `.script`/`.preScript`/`.postScript`, three keys
      * that have been `before`/`exec`/`after` for a long time.)
      */
+    /** `topo` is refused by default here, which is the one way this differs from `RunService`'s: a
+     *  version hook has no package ordering to join. */
     function normalizeScriptValue(value: unknown, at: string): RunStepValue[];
     /**
      * Keeps a package's Dockerfile `org.opencontainers.image.version` label in step with the version