@depup/nx 22.6.4-depup.2 → 23.1.0-depup.0

package/dist/src/tasks-runner/life-cycles/dynamic-run-one-terminal-output-life-cycle.js

@@ -0,0 +1,238 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRunOneDynamicOutputRenderer = createRunOneDynamicOutputRenderer;
+const tslib_1 = require("tslib");
+const cliCursor = tslib_1.__importStar(require("cli-cursor"));
+const cli_spinners_1 = require("cli-spinners");
+const os_1 = require("os");
+const readline = tslib_1.__importStar(require("readline"));
+const output_1 = require("../../utils/output");
+const pretty_time_1 = require("./pretty-time");
+const formatting_utils_1 = require("./formatting-utils");
+const view_logs_utils_1 = require("./view-logs-utils");
+const handle_import_1 = require("../../utils/handle-import");
+const pc = tslib_1.__importStar(require("picocolors"));
+const LEFT_PAD = `   `;
+const SPACER = `  `;
+const EXTENDED_LEFT_PAD = `      `;
+/**
+ * The following function is responsible for creating a life cycle with dynamic
+ * outputs, meaning previous outputs can be rewritten or modified as new outputs
+ * are added. It is therefore intended for use on a user's local machines.
+ *
+ * In CI environments the static equivalent of this life cycle should be used.
+ *
+ * NOTE: output.dim() should be preferred over output.colors.gray() because it
+ * is much more consistently readable across different terminal color themes.
+ */
+async function createRunOneDynamicOutputRenderer({ initiatingProject, tasks, args, overrides, }) {
+    cliCursor.hide();
+    // Show the cursor again after the process exits
+    process.on('exit', () => {
+        cliCursor.show();
+    });
+    let resolveRenderIsDonePromise;
+    const renderIsDone = new Promise((resolve) => (resolveRenderIsDonePromise = resolve)).then(() => {
+        clearRenderInterval();
+        cliCursor.show();
+    });
+    function clearRenderInterval() {
+        if (renderDependentTargetsIntervalId) {
+            clearInterval(renderDependentTargetsIntervalId);
+        }
+    }
+    process.on('exit', () => clearRenderInterval());
+    process.on('SIGINT', () => clearRenderInterval());
+    process.on('SIGTERM', () => clearRenderInterval());
+    process.on('SIGHUP', () => clearRenderInterval());
+    const lifeCycle = {};
+    const start = process.hrtime();
+    const figures = await (0, handle_import_1.handleImport)('figures');
+    let state = 'EXECUTING_DEPENDENT_TARGETS';
+    const tasksToTerminalOutputs = {};
+    const totalTasks = tasks.length;
+    const totalDependentTasks = totalTasks - 1;
+    const totalTasksFromInitiatingProject = tasks.filter((t) => t.target.project === initiatingProject).length;
+    // Tasks from the initiating project are treated differently, they forward their output
+    const totalDependentTasksNotFromInitiatingProject = totalTasks - totalTasksFromInitiatingProject;
+    const targetName = tasks[0].target.target;
+    let dependentTargetsNumLines = 0;
+    let totalCompletedTasks = 0;
+    let totalSuccessfulTasks = 0;
+    let totalFailedTasks = 0;
+    let totalCachedTasks = 0;
+    // Used to control the rendering of the spinner
+    let dependentTargetsCurrentFrame = 0;
+    let renderDependentTargetsIntervalId;
+    const moveCursorToStartOfDependentTargetLines = () => {
+        readline.cursorTo(process.stdout, 0);
+        readline.moveCursor(process.stdout, 0, -dependentTargetsNumLines);
+    };
+    const renderLines = (lines, dividerColor = 'cyan', renderDivider = true) => {
+        let additionalLines = 0;
+        if (renderDivider) {
+            const dividerLines = output_1.output.getVerticalSeparatorLines(dividerColor);
+            for (const line of dividerLines) {
+                output_1.output.overwriteLine(line);
+            }
+            additionalLines += dividerLines.length;
+            lines.push('');
+        }
+        for (const line of lines) {
+            output_1.output.overwriteLine(line);
+        }
+        dependentTargetsNumLines = lines.length + additionalLines;
+        // clear any possible text below the cursor's position
+        readline.clearScreenDown(process.stdout);
+    };
+    const renderDependentTargets = (renderDivider = true) => {
+        if (totalDependentTasksNotFromInitiatingProject <= 0) {
+            return;
+        }
+        const max = cli_spinners_1.dots.frames.length - 1;
+        const curr = dependentTargetsCurrentFrame;
+        dependentTargetsCurrentFrame = curr >= max ? 0 : curr + 1;
+        const linesToRender = [''];
+        const remainingDependentTasksNotFromInitiatingProject = totalDependentTasksNotFromInitiatingProject - totalCompletedTasks;
+        switch (state) {
+            case 'EXECUTING_DEPENDENT_TARGETS':
+                if (totalFailedTasks === 0) {
+                    linesToRender.push(`${LEFT_PAD}${output_1.output.colors.cyan(cli_spinners_1.dots.frames[dependentTargetsCurrentFrame])}${SPACER}${output_1.output.dim(`Nx is waiting on ${remainingDependentTasksNotFromInitiatingProject} dependent project tasks before running tasks from`)} ${initiatingProject}${output_1.output.dim('...')}`);
+                    if (totalSuccessfulTasks > 0) {
+                        linesToRender.push('');
+                    }
+                }
+                break;
+        }
+        if (totalFailedTasks > 0) {
+            linesToRender.push(pc.dim(pc.red(`${LEFT_PAD}${output_1.output.colors.red(figures.cross)}${SPACER}${totalFailedTasks}${`/${totalCompletedTasks}`} dependent project tasks failed (see below)`)));
+        }
+        if (totalSuccessfulTasks > 0) {
+            linesToRender.push(output_1.output.dim(`${LEFT_PAD}${output_1.output.dim(figures.tick)}${SPACER}${totalSuccessfulTasks}${`/${totalCompletedTasks}`} dependent project tasks succeeded ${output_1.output.dim(`[${totalCachedTasks} read from cache]`)}`));
+        }
+        moveCursorToStartOfDependentTargetLines();
+        if (linesToRender.length > 1) {
+            renderLines(linesToRender, 'gray', renderDivider && state !== 'EXECUTING_DEPENDENT_TARGETS');
+        }
+        else {
+            renderLines([]);
+        }
+    };
+    lifeCycle.startCommand = () => {
+        renderDependentTargets();
+    };
+    lifeCycle.startTasks = (tasks) => {
+        for (const task of tasks) {
+            // Move from the dependent project tasks phase to the initiating project's targets
+            if (task.target.project === initiatingProject &&
+                state !== 'EXECUTING_INITIATING_PROJECT_TARGET') {
+                state = 'EXECUTING_INITIATING_PROJECT_TARGET';
+                clearRenderInterval();
+                renderDependentTargets(false);
+                if (totalDependentTasksNotFromInitiatingProject > 0) {
+                    output_1.output.addNewline();
+                    process.stdout.write(`${LEFT_PAD}${output_1.output.dim('Hint: you can run the command with')} --verbose ${output_1.output.dim('to see the full dependent project outputs')}` + os_1.EOL);
+                    output_1.output.addVerticalSeparator('gray');
+                }
+            }
+        }
+        if (!renderDependentTargetsIntervalId &&
+            state === 'EXECUTING_DEPENDENT_TARGETS') {
+            renderDependentTargetsIntervalId = setInterval(renderDependentTargets, 100);
+        }
+    };
+    lifeCycle.printTaskTerminalOutput = (task, cacheStatus, terminalOutput) => {
+        if (task.target.project === initiatingProject) {
+            output_1.output.logCommandOutput(task.id, cacheStatus, terminalOutput);
+        }
+        else {
+            tasksToTerminalOutputs[task.id] = terminalOutput;
+        }
+    };
+    lifeCycle.endTasks = (taskResults) => {
+        for (let t of taskResults) {
+            totalCompletedTasks++;
+            switch (t.status) {
+                case 'remote-cache':
+                case 'local-cache':
+                case 'local-cache-kept-existing':
+                    totalCachedTasks++;
+                    totalSuccessfulTasks++;
+                    break;
+                case 'success':
+                    totalSuccessfulTasks++;
+                    break;
+                case 'failure':
+                    totalFailedTasks++;
+                    /**
+                     * A dependent project has failed so we stop executing and update the relevant
+                     * dependent project task messaging
+                     */
+                    if (t.task.target.project !== initiatingProject) {
+                        clearRenderInterval();
+                        renderDependentTargets(false);
+                        output_1.output.addVerticalSeparator('red');
+                        output_1.output.logCommandOutput(t.task.id, t.status, tasksToTerminalOutputs[t.task.id]);
+                    }
+                    break;
+            }
+            delete tasksToTerminalOutputs[t.task.id];
+        }
+    };
+    lifeCycle.endCommand = () => {
+        clearRenderInterval();
+        const timeTakenText = (0, pretty_time_1.prettyTime)(process.hrtime(start));
+        if (totalSuccessfulTasks === totalTasks) {
+            state = 'COMPLETED_SUCCESSFULLY';
+            const text = `Successfully ran ${(0, formatting_utils_1.formatTargetsAndProjects)([initiatingProject], [targetName], tasks)}`;
+            const taskOverridesLines = [];
+            const filteredOverrides = Object.entries(overrides).filter(
+            // Don't print the data passed through from the version subcommand to the publish executor options, it could be quite large and it's an implementation detail.
+            ([flag]) => flag !== 'nxReleaseVersionData');
+            if (filteredOverrides.length > 0) {
+                taskOverridesLines.push('');
+                taskOverridesLines.push(`${EXTENDED_LEFT_PAD}${pc.dim(pc.green('With additional flags:'))}`);
+                filteredOverrides
+                    .map(([flag, value]) => pc.dim(pc.green((0, formatting_utils_1.formatFlags)(EXTENDED_LEFT_PAD, flag, value))))
+                    .forEach((arg) => taskOverridesLines.push(arg));
+            }
+            const pinnedFooterLines = [
+                output_1.output.applyNxPrefix('green', output_1.output.colors.green(text) + output_1.output.dim(` (${timeTakenText})`)),
+                ...taskOverridesLines,
+            ];
+            if (totalCachedTasks > 0) {
+                pinnedFooterLines.push(output_1.output.dim(`${os_1.EOL}Nx read the output from the cache instead of running the command for ${totalCachedTasks} out of ${totalTasks} tasks.`));
+            }
+            renderLines(pinnedFooterLines, 'green');
+        }
+        else {
+            state = 'COMPLETED_WITH_ERRORS';
+            let text = `Ran target ${output_1.output.bold(targetName)} for project ${output_1.output.bold(initiatingProject)}`;
+            if (totalDependentTasks > 0) {
+                text += ` and ${output_1.output.bold(totalDependentTasks)} task(s) they depend on`;
+            }
+            const taskOverridesLines = [];
+            const filteredOverrides = Object.entries(overrides).filter(
+            // Don't print the data passed through from the version subcommand to the publish executor options, it could be quite large and it's an implementation detail.
+            ([flag]) => flag !== 'nxReleaseVersionData');
+            if (filteredOverrides.length > 0) {
+                taskOverridesLines.push('');
+                taskOverridesLines.push(`${EXTENDED_LEFT_PAD}${pc.dim(pc.red('With additional flags:'))}`);
+                filteredOverrides
+                    .map(([flag, value]) => pc.dim(pc.red((0, formatting_utils_1.formatFlags)(EXTENDED_LEFT_PAD, flag, value))))
+                    .forEach((arg) => taskOverridesLines.push(arg));
+            }
+            const viewLogs = (0, view_logs_utils_1.viewLogsFooterRows)(totalFailedTasks);
+            renderLines([
+                output_1.output.applyNxPrefix('red', output_1.output.colors.red(text) + output_1.output.dim(` (${timeTakenText})`)),
+                ...taskOverridesLines,
+                '',
+                `${LEFT_PAD}${output_1.output.colors.red(figures.cross)}${SPACER}${totalFailedTasks}${`/${totalCompletedTasks}`} failed`,
+                `${LEFT_PAD}${output_1.output.dim(figures.tick)}${SPACER}${totalSuccessfulTasks}${`/${totalCompletedTasks}`} succeeded ${output_1.output.dim(`[${totalCachedTasks} read from cache]`)}`,
+                ...viewLogs,
+            ], 'red');
+        }
+        resolveRenderIsDonePromise();
+    };
+    return { lifeCycle, renderIsDone };
+}

package/dist/src/tasks-runner/life-cycles/empty-terminal-output-life-cycle.d.ts

@@ -0,0 +1,5 @@
+import type { LifeCycle } from '../life-cycle';
+import { TaskStatus } from '../tasks-runner';
+export declare class EmptyTerminalOutputLifeCycle implements LifeCycle {
+    printTaskTerminalOutput(task: any, cacheStatus: TaskStatus, terminalOutput: string): void;
+}

package/dist/src/tasks-runner/life-cycles/formatting-utils.d.ts

@@ -0,0 +1,3 @@
+import { Task } from '../../config/task-graph';
+export declare function formatFlags(leftPadding: string, flag: string, value: any): string;
+export declare function formatTargetsAndProjects(projectNames: string[], targets: string[], tasks: Task[]): string;

package/dist/src/tasks-runner/life-cycles/invoke-runner-terminal-output-life-cycle.d.ts

@@ -0,0 +1,13 @@
+import { TaskStatus } from '../tasks-runner';
+import type { LifeCycle, TaskResult } from '../life-cycle';
+import { Task } from '../../config/task-graph';
+export declare class InvokeRunnerTerminalOutputLifeCycle implements LifeCycle {
+    private readonly tasks;
+    failedTasks: Task[];
+    cachedTasks: Task[];
+    constructor(tasks: Task[]);
+    startCommand(): void;
+    endCommand(): void;
+    endTasks(taskResults: TaskResult[]): void;
+    printTaskTerminalOutput(task: Task, cacheStatus: TaskStatus, terminalOutput: string): void;
+}

package/dist/src/tasks-runner/life-cycles/invoke-runner-terminal-output-life-cycle.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvokeRunnerTerminalOutputLifeCycle = void 0;
+const output_1 = require("../../utils/output");
+const utils_1 = require("../utils");
+class InvokeRunnerTerminalOutputLifeCycle {
+    constructor(tasks) {
+        this.tasks = tasks;
+        this.failedTasks = [];
+        this.cachedTasks = [];
+    }
+    startCommand() {
+        output_1.output.log({
+            color: 'cyan',
+            title: `Running ${this.tasks.length} tasks:`,
+            bodyLines: this.tasks.map((task) => {
+                const unparsed = (0, utils_1.getUnparsedOverrideArgs)(task);
+                return `- Task ${task.id} ${unparsed.length > 0 ? `Overrides: ${unparsed.join(' ')}` : ''}`;
+            }),
+        });
+        output_1.output.addVerticalSeparatorWithoutNewLines('cyan');
+    }
+    endCommand() {
+        output_1.output.addNewline();
+        const taskIds = this.tasks.map((task) => {
+            const cached = this.cachedTasks.indexOf(task) !== -1;
+            const failed = this.failedTasks.indexOf(task) !== -1;
+            const unparsed = (0, utils_1.getUnparsedOverrideArgs)(task);
+            return `- Task ${task.id} ${unparsed.length > 0 ? `Overrides: ${unparsed.join(' ')}` : ''} ${cached ? 'CACHED' : ''} ${failed ? 'FAILED' : ''}`;
+        });
+        if (this.failedTasks.length === 0) {
+            output_1.output.addVerticalSeparatorWithoutNewLines('green');
+            output_1.output.success({
+                title: `Successfully ran ${this.tasks.length} tasks:`,
+                bodyLines: taskIds,
+            });
+        }
+        else {
+            output_1.output.addVerticalSeparatorWithoutNewLines('red');
+            output_1.output.error({
+                title: `Ran ${this.tasks.length} tasks:`,
+                bodyLines: taskIds,
+            });
+        }
+    }
+    endTasks(taskResults) {
+        for (let t of taskResults) {
+            if (t.status === 'failure') {
+                this.failedTasks.push(t.task);
+            }
+            else if (t.status === 'local-cache') {
+                this.cachedTasks.push(t.task);
+            }
+            else if (t.status === 'local-cache-kept-existing') {
+                this.cachedTasks.push(t.task);
+            }
+            else if (t.status === 'remote-cache') {
+                this.cachedTasks.push(t.task);
+            }
+        }
+    }
+    printTaskTerminalOutput(task, cacheStatus, terminalOutput) {
+        const args = (0, utils_1.getPrintableCommandArgsForTask)(task);
+        output_1.output.logCommandOutput(args.join(' '), cacheStatus, terminalOutput);
+    }
+}
+exports.InvokeRunnerTerminalOutputLifeCycle = InvokeRunnerTerminalOutputLifeCycle;

package/dist/src/tasks-runner/life-cycles/performance-analysis.d.ts

@@ -0,0 +1,166 @@
+import { TaskGraph } from '../../config/task-graph';
+import { NxJsonConfiguration } from '../../config/nx-json';
+import { TaskResult } from '../life-cycle';
+export interface TaskTiming {
+    startTime?: number;
+    endTime?: number;
+    continuous: boolean;
+}
+/** A discrete task that ran, with its window and whether it monopolizes the pool (`parallelism: false`). */
+export interface TimedTask {
+    id: string;
+    start: number;
+    end: number;
+    nonParallel: boolean;
+}
+/**
+ * One [start, end) slice of the run where the counts below hold steady — the gap between
+ * two adjacent sweep boundaries (see {@link buildTimespans}). Because nothing changes
+ * within the slice, the analysis treats it as a flat rectangle of `end - start` ms.
+ */
+export interface Timespan {
+    /** Slice bounds (epoch ms); occ/waiting/nonParallel are constant across [start, end). */
+    start: number;
+    end: number;
+    /** Slots busy for the whole slice (a `parallelism: false` task counts as the entire pool). */
+    occ: number;
+    /** Tasks eligible to run but still queued for a free slot. */
+    waiting: number;
+    /** `parallelism: false` tasks running during the slice (each one holds every slot). */
+    nonParallel: number;
+}
+export interface PerformanceSummary {
+    runDuration: number;
+    criticalPathDuration: number;
+    criticalPathTaskCount: number;
+    /** Longest critical-path tasks that ran (desc, capped at a few), cache hits excluded; empty when the path was fully cached. */
+    criticalPathTop: Array<{
+        id: string;
+        duration: number;
+    }>;
+    /** Ids of tasks that failed (slowest first), for the GitHub Actions summary's failed-tasks list. Continuous tasks and tasks without a complete window are excluded. */
+    failedTasks: string[];
+    /** runDuration − criticalPathDuration. */
+    overhead: number;
+    /** Overhead split by lever; these + coordinatorOverhead sum to `overhead`. Their sum is the slot-contention time (derived, never stored, so the halves can't drift). */
+    recoverableByParallel: number;
+    recoverableByMachines: number;
+    coordinatorOverhead: number;
+    parallel: number;
+    cores: number;
+    isCI: boolean;
+    /** In CI and not already distributing — so suggesting Nx Agents is actionable. */
+    canDistribute: boolean;
+    /** Already running on Nx Agents (NX_CLOUD_DISTRIBUTED_EXECUTION_AGENT_COUNT set). */
+    distributing: boolean;
+    /** Coordinator overhead outweighs task work, so the longest tasks aren't the lever (typical cached run). */
+    coordinatorDominated: boolean;
+    cacheHits: number;
+    /** Tasks with any cache outcome (hits + tasks that ran). */
+    cacheableCount: number;
+    cacheSkipped: boolean;
+    remoteCacheEnabled: boolean;
+}
+/** Construction-time inputs for {@link PerformanceLifeCycle}. */
+export interface PerformanceLifeCycleOptions {
+    /** Whether `--skip-nx-cache` was passed (feeds the cache-skipped check). */
+    skipNxCache?: boolean;
+    /** Passed in at construction so the lifecycle doesn't re-read nx.json. */
+    nxJson?: NxJsonConfiguration;
+}
+/**
+ * Pure analysis over one finished run's collected timings — no lifecycle state and no
+ * mutation. Built once per run from the {@link PerformanceLifeCycle}'s accumulated
+ * maps; everything here is a function of that snapshot plus the environment it reads.
+ */
+export declare class PerformanceAnalysis {
+    private readonly timings;
+    private readonly statuses;
+    private readonly taskGraph;
+    private readonly batchSiblings;
+    /** Resolved `--parallel` (getThreadPoolSize's `discrete`), set on the lifecycle by the runner; falls back to 1. */
+    private readonly parallel;
+    private readonly options;
+    constructor(timings: Map<string, TaskTiming>, statuses: Map<string, TaskResult['status']>, taskGraph: TaskGraph, batchSiblings: Map<string, string[]>, 
+    /** Resolved `--parallel` (getThreadPoolSize's `discrete`), set on the lifecycle by the runner; falls back to 1. */
+    parallel: number, options: PerformanceLifeCycleOptions);
+    /**
+     * Whether a remote (Nx Cloud) cache is active, from the nx.json handed in at
+     * construction. Assumes no remote cache when it wasn't provided rather than
+     * re-reading nx.json from disk — the CLI path always provides it.
+     */
+    private remoteCacheEnabled;
+    /** Discrete tasks that ran and have a start + end timestamp. */
+    private timedTasks;
+    /**
+     * Longest-duration chain through the dependency DAG — the floor with unlimited
+     * slots. `finishEstimate(t) = duration[t] + max(finishEstimate(p) for predecessors
+     * p)`. Predecessors are real dependencies *plus* earlier batch siblings (a batch runs
+     * sequentially in one process, so that ordering is part of the floor too). On equal
+     * finish estimates keep the longer-running predecessor.
+     */
+    private criticalPath;
+    /**
+     * Real predecessors of `id`: dependencies plus any earlier batch sibling that FINISHED
+     * before `id` started. A batch runs sequentially in one process, so that ordering is
+     * part of the floor; concurrent batch executors aren't, and chaining them would inflate
+     * it. (Matches readyTime.)
+     */
+    private predecessorsFor;
+    /**
+     * Longest finish time of any chain reaching `id` — its duration plus the best
+     * predecessor's finish estimate — memoized in `ctx`. `ctx.visiting` guards a cycle in
+     * a malformed graph (the back-edge contributes nothing).
+     */
+    private finishEstimate;
+    /**
+     * Earliest this task became eligible, independent of slots: the latest of run
+     * start, dependency ends, any continuous dependency's *start* (an ordering
+     * constraint, not contention), and any earlier batch sibling's end.
+     */
+    private readyTime;
+    /**
+     * Longest critical-path tasks that RAN (desc, capped at 3). Cache hits are excluded
+     * (their duration is just restore time); no-status tasks (synthetic test runs) are
+     * kept.
+     */
+    private computeCriticalPathTop;
+    /** Cache outcome: tasks restored (`cacheHits`) and the total with a cache outcome (`cacheableCount` = hits + ran). No-status tasks count for neither. */
+    private computeCacheStats;
+    /**
+     * The ids of tasks that failed during the run, slowest first, for the GitHub Actions
+     * summary's failed-tasks list. Continuous tasks and tasks without a complete window are
+     * excluded (a failed task ran to a non-zero exit, so it has both timestamps). Duration
+     * orders the list but isn't shown — for a failure, which task failed is what matters.
+     */
+    private computeFailedTasks;
+    /** The structured performance summary, or `null` when no discrete task timings were recorded. */
+    summary(): PerformanceSummary | null;
+}
+/**
+ * Union a set of `[start, end]` intervals into an ordered, non-overlapping set, e.g.
+ * `[[1, 3], [2, 5]]` → `[[1, 5]]`. Sort by start, then sweep once: each interval
+ * either extends the previous merged one (if it overlaps or touches it) or begins a
+ * new one.
+ */
+export declare function mergeIntervals(intervals: Array<[number, number]>): Array<[number, number]>;
+/** Total time [a, b] overlaps the given (unsorted, possibly overlapping) intervals. */
+export declare function overlap(a: number, b: number, intervals: Array<[number, number]>): number;
+/**
+ * Coordinator hashing wall-clock that ran *before* the first task started — the run
+ * window (first task start → last task end) would otherwise miss it. Matters on a
+ * cached run where hashing dominates but the tasks restore in milliseconds.
+ *
+ * `hashWindows` are absolute `[start, end]` spans from nx's `hash*` perf measures.
+ */
+export declare function preDispatchHashTime(firstTaskStart: number, hashWindows: Array<[number, number]>): number;
+/**
+ * The occupancy timeline (contiguous {@link Timespan}s) — single source of truth for
+ * slot contention. A `parallelism: false` task occupies the whole pool. Integrates
+ * over time rather than sampling one instant, so it's robust to when tasks hand off.
+ *
+ * Builds it via a delta sweep: each task bumps a counter up at its start and down at
+ * its end, then we walk the sorted boundaries accumulating the running totals into one
+ * timespan per gap.
+ */
+export declare function buildTimespans(timed: TimedTask[], eligible: Map<string, number>, parallel: number): Timespan[];