# progress The stages of a run and the view of it, as the command line shows them: which tasks run before which, where a failure stops the run, and what a terminal is shown while it goes. What the command line shows of a run is built from parts that know nothing of how a task is executed, so a runner of your own can show the same thing. [`assignStages`](https://www.hyperfrontend.dev/docs/libraries/workspace/progress/#api-assignStages) gives every task the first stage that names its target and moves a prerequisite to the earliest stage that needs it. [`runStages`](https://www.hyperfrontend.dev/docs/libraries/workspace/progress/#api-runStages) runs the stages in order through a function you supply and stops after the first that did not succeed whole, answering the tasks that never started. [`createProgressView`](https://www.hyperfrontend.dev/docs/libraries/workspace/progress/#api-createProgressView) writes a line as each task ends, the excerpt of a failed task's log from [`failureExcerpt`](https://www.hyperfrontend.dev/docs/libraries/workspace/progress/#api-failureExcerpt), a sign of life for a task that runs long, and at the end the matrix of [`matrixLines`](https://www.hyperfrontend.dev/docs/libraries/workspace/progress/#api-matrixLines) with the totals. It writes through a [`Terminal`](https://www.hyperfrontend.dev/docs/libraries/workspace/progress/#api-Terminal) from [`createTerminal`](https://www.hyperfrontend.dev/docs/libraries/workspace/progress/#api-createTerminal), which rewrites a status line on a terminal and writes plain lines everywhere else. ```ts import { assignStages, createProgressView, createTerminal, Ending, runStages } from '@hyperfrontend/workspace/progress' const tasks = [ { id: 'lib-core:lint', project: 'lib-core', target: 'lint', needs: [] }, { id: 'lib-core:test', project: 'lib-core', target: 'test', needs: [] }, ] const stages = [['lint'], ['test']] const stageOf = assignStages(tasks, stages) const view = createProgressView({ tasks: tasks.map((task) => ({ ...task, stage: stageOf.get(task.id) ?? 0 })), stages: stages.length, terminal: createTerminal(process.stderr, process.env), now: Date.now, }) const { stopped } = await runStages({ tasks, stageOf, runStage: async (members, stage) => { view.stage(stage) for (const task of members) { view.started(task.id) view.ended({ id: task.id, ending: Ending.Passed, durationMs: 1200, detail: null, excerpt: null, log: null, }) } return true }, }) view.finish(stopped) ``` ## API Reference ### Functions #### assignStages ```typescript function assignStages(tasks: unknown, stages: unknown): Map ``` The stage of every task: the first stage naming its target, or the last stage for a target no stage names; then every prerequisite moves to the earliest stage holding a task that needs it. **Parameters** | Name | Type | Description | | --- | --- | --- | | `tasks` | `unknown` | The tasks, each with its target and the tasks it runs after | | `stages` | `unknown` | The target groups, in the order they run | **Returns** `Map`: The stage of each task by id, counted from 0 **Example: A build one test needs runs with the tests, the other builds after them** ```typescript import { assignStages } from '@hyperfrontend/workspace/progress' assignStages( [ { id: 'lib-core:build', target: 'build', needs: [] }, { id: 'lib-core:test', target: 'test', needs: ['lib-core:build'] }, { id: 'lib-util:lint', target: 'lint', needs: [] }, { id: 'lib-util:build', target: 'build', needs: [] }, ], [['typecheck', 'lint'], ['test'], ['build']] ) // => Map { 'lib-core:build' => 1, 'lib-core:test' => 1, 'lib-util:lint' => 0, 'lib-util:build' => 2 } ``` #### createProgressView ```typescript function createProgressView(options: ViewOptions): ProgressView ``` The view of a run: call it as stages start and tasks start and end, and once at the end. **Parameters** | Name | Type | Description | | --- | --- | --- | | `options` | `ViewOptions` | The tasks, the stages, where to write and the clock | **Returns** `ProgressView`: What the run calls as it goes **Example: One task that fails, and what the run ends on** ```typescript import { createProgressView, createTerminal, Ending } from '@hyperfrontend/workspace/progress' const view = createProgressView({ tasks: [ { id: 'lib-core:lint', project: 'lib-core', target: 'lint', stage: 0 }, { id: 'lib-core:test', project: 'lib-core', target: 'test', stage: 1 }, ], stages: 2, terminal: createTerminal(process.stderr, process.env), now: Date.now, }) view.stage(0) view.started('lib-core:lint') view.ended({ id: 'lib-core:lint', ending: Ending.Failed, durationMs: 4200, detail: null, excerpt: 'src/index.ts:3:1 error no-default-export', log: '.hf/logs/lib-core__lint.log', }) view.finish(0) // stage 1 of 2: lint (1 task) // ✗ lib-core:lint 4.2s [1/2] // src/index.ts:3:1 error no-default-export // log: .hf/logs/lib-core__lint.log // stage 1 (lint) did not succeed: 1 task not run // // lint test // lib-core ✗ · // ✓ passed ✗ failed - skipped · not run // // 2 tasks in 4.2s: 1 failed, 1 not run // ✗ lib-core:lint .hf/logs/lib-core__lint.log ``` #### createTerminal ```typescript function createTerminal(sink: ProgressSink, env: Readonly>): Terminal ``` The terminal a stream is: plain unless the stream is a terminal that can rewrite a line and the environment did not ask for output without colour. **Parameters** | Name | Type | Description | | --- | --- | --- | | `sink` | `ProgressSink` | The stream written to | | `env` | `Readonly>` | The environment: `NO_COLOR` set to anything, or a `TERM` of `dumb`, asks for plain output | **Returns** `Terminal`: How lines and the status are written to it **Example: A stream that is not a terminal gets plain lines and no status** ```typescript import { createTerminal, Style } from '@hyperfrontend/workspace/progress' const terminal = createTerminal(process.stderr, process.env) terminal.status('lib-core:build 42s') terminal.line(`${terminal.paint('✓', Style.Green)} lib-core:build`) // through a pipe: writes '✓ lib-core:build\n' and nothing for the status ``` #### failureExcerpt ```typescript function failureExcerpt(log: string, limit: number): string ``` The part of a failed task's output that explains the failure: from the test runner's list of failing tests up to its coverage table when it printed one, else the last lines. **Parameters** | Name | Type | Description | | --- | --- | --- | | `log` | `string` | Everything the task printed | | `limit` | `number` | The most lines kept (default: `EXCERPT_LINES`) | **Returns** `string`: The lines, or null when the task printed nothing **Example: The end of the output, unless the test runner listed its failing tests** ```typescript import { failureExcerpt } from '@hyperfrontend/workspace/progress' failureExcerpt('one\ntwo\nthree\n', 2) // => 'two\nthree' failureExcerpt('✔ passes\n✖ failing tests:\n✖ breaks\nfile | line %') // => '✖ failing tests:\n✖ breaks' failureExcerpt('') // => null ``` #### formatDuration ```typescript function formatDuration(ms: number): string ``` A duration as a reader sees it. **Parameters** | Name | Type | Description | | --- | --- | --- | | `ms` | `number` | Milliseconds | **Returns** `string`: The duration in the largest units that fit **Example: Tenths under ten seconds, whole seconds under a minute** ```typescript import { formatDuration } from '@hyperfrontend/workspace/progress' formatDuration(800) // => '0.8s' formatDuration(47_000) // => '47s' formatDuration(1_097_000) // => '18m 17s' ``` #### markOf ```typescript function markOf(ending: Ending, paint: (text: string, style: Style) => string): string ``` The mark of an ending, in its style. **Parameters** | Name | Type | Description | | --- | --- | --- | | `ending` | `Ending` | How a task ended | | `paint` | `(text: string, style: Style) => string` | Sets text apart in a style | **Returns** `string`: The mark, painted **Example: The same marks lead a task's line and fill the matrix** ```typescript import { createTerminal, Ending, markOf } from '@hyperfrontend/workspace/progress' markOf(Ending.Failed, createTerminal(process.stderr, process.env).paint) // => '✗', red on a terminal ``` #### matrixLines ```typescript function matrixLines(tasks: unknown, paint: (text: string, style: Style) => string): string[] ``` The lines of the matrix: the targets as a heading in the order of their stages, a row per project by name, and the legend of the marks. **Parameters** | Name | Type | Description | | --- | --- | --- | | `tasks` | `unknown` | Every task of the run with how it ended | | `paint` | `(text: string, style: Style) => string` | Sets text apart in a style | **Returns** `string[]`: The heading, a row per project, and the legend **Example: A failed type check that kept the build from running** ```typescript import { createTerminal, Ending, matrixLines } from '@hyperfrontend/workspace/progress' matrixLines( [ { project: 'lib-core', target: 'typecheck', stage: 0, ending: Ending.Failed }, { project: 'lib-core', target: 'build', stage: 1, ending: Ending.NotRun }, { project: 'lib-util', target: 'typecheck', stage: 0, ending: Ending.Passed }, ], createTerminal(process.stderr, process.env).paint ) // => [ // ' typecheck build', // 'lib-core ✗ ·', // 'lib-util ✓', // '✓ passed ✗ failed - skipped · not run', // ] ``` #### runStages ```typescript function runStages(options: StagedOptions): Promise ``` Runs the stages in order, each to its end, and stops after the first that did not succeed whole. A stage no task belongs to is passed over. **Parameters** | Name | Type | Description | | --- | --- | --- | | `options` | `StagedOptions` | The tasks, the stage of each and how one stage runs | **Returns** `Promise`: The stage that ended the run, if one did, and the tasks that never started **Example: A failed first stage keeps the second from starting** ```typescript import { runStages } from '@hyperfrontend/workspace/progress' const tasks = [{ id: 'lib-core:lint' }, { id: 'lib-core:test' }] const stageOf = new Map([ ['lib-core:lint', 0], ['lib-core:test', 1], ]) await runStages({ tasks, stageOf, runStage: async (stage) => stage.every((task) => task.id !== 'lib-core:lint') }) // => { stopped: 0, notRun: ['lib-core:test'] } ``` #### taskLogPath ```typescript function taskLogPath(id: string, directory: string): string ``` The log file of a task, under a log directory. **Parameters** | Name | Type | Description | | --- | --- | --- | | `id` | `string` | The task, `:` | | `directory` | `string` | The directory, workspace-relative and POSIX | **Returns** `string`: The path, workspace-relative and POSIX **Example: The colon of a task id never reaches a file name** ```typescript import { taskLogPath } from '@hyperfrontend/workspace/progress' taskLogPath('lib-core:build', '.hf/logs') // => '.hf/logs/lib-core__build.log' ``` ### Interfaces #### Identified A task as far as a staged run names it. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly id` | `string` | `:`. | #### MatrixTask One task of the matrix. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly project` | `string` | The row: the project. | | `readonly target` | `string` | The column: the target. | | `readonly stage` | `number` | The stage the task ran in, counted from 0; the columns follow the stages. | | `readonly ending` | `Ending` | How the task ended. | #### ProgressSink A stream the progress is written to, as far as it is read here. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly isTTY?` | `boolean` | Whether the stream is a terminal. | | `readonly columns?` | `number` | The width of the terminal, in columns. | ##### write ```typescript write(text: string): unknown ``` Writes text. **Parameters** | Name | Type | Description | | --- | --- | --- | | `text` | `string` | | #### ProgressView The view of one run. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly stage` | `(stage: number) => void` | Says a stage starts. | | `readonly started` | `(id: string) => void` | Notes that a task started. | | `readonly ended` | `(end: TaskEnd) => void` | Writes the line of a task that ended, and under a failed one its excerpt and where its log is. | | `readonly tick` | `() => void` | Shows what has been running long; meant to be called every second or so. | | `readonly finish` | `(stopped: number) => void` | Writes the matrix and the totals; the tasks that never ended are shown as not run. | #### StagedOptions What a staged run needs. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly tasks` | `unknown` | The tasks, in the order they run inside a stage. | | `readonly stageOf` | `ReadonlyMap` | The stage of each task, by id, counted from 0. | | `readonly runStage` | `(tasks: unknown, stage: number) => Promise` | Runs the tasks of one stage to the end and resolves to whether every one of them succeeded. | #### StagedRun How a staged run ended. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly stopped` | `number` | The stage that did not succeed and ended the run, counted from 0, or null when every stage ran. | | `readonly notRun` | `unknown` | The ids of the tasks of the stages that never started, in the order given. | #### StagedTask What staging reads off a task. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly id` | `string` | `:`. | | `readonly target` | `string` | The target. | | `readonly needs` | `unknown` | The ids of the tasks it runs after. | #### TaskEnd How one task ended. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly id` | `string` | `:`. | | `readonly ending` | `Ending` | Whether it passed, failed, or was skipped. | | `readonly durationMs` | `number` | How long it ran, in milliseconds. | | `readonly detail` | `string` | Why it did not run or did not reach an exit, shown in place of the duration, or null. | | `readonly excerpt` | `string` | The part of a failed task's log that explains the failure, or null. | | `readonly log` | `string` | Where the task's log is, or null when it wrote none. | #### Terminal The lines and the status of a run, as the view writes them. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly plain` | `boolean` | Whether the output takes plain lines alone: no colour, and no line rewritten in place. | | `readonly line` | `(text: string) => void` | Writes a finished line, in place of the status when one is shown. | | `readonly status` | `(text: string) => void` | Shows a status the next line or status replaces; writes nothing on plain output. | | `readonly paint` | `(text: string, style: Style) => string` | Sets text apart in a style; the text itself on plain output. | #### ViewOptions What a view needs. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly tasks` | `unknown` | Every task of the run. | | `readonly stages` | `number` | How many stages the run has. | | `readonly terminal` | `Terminal` | Where the lines and the status go. | | `readonly now` | `() => number` | The current time in milliseconds. | | `readonly thresholdMs?` | `number` | How long a task runs before a terminal shows it as running; 3 seconds unless given. | | `readonly intervalMs?` | `number` | How long a task runs between two lines saying so on plain output; 30 seconds unless given. | #### ViewTask One task of the run, as the view names and places it. **Properties** | Name | Type | Description | | --- | --- | --- | | `readonly id` | `string` | `:`. | | `readonly project` | `string` | The row of the matrix it belongs to. | | `readonly target` | `string` | The column of the matrix it belongs to. | | `readonly stage` | `number` | The stage it runs in, counted from 0. | ### Types #### Ending One of the endings. ```typescript type Ending = indexedAccess ``` #### Style One of the styles. ```typescript type Style = indexedAccess ``` ### Variables #### Ending How a task ended, as a reader is shown it. ```typescript const Ending: Readonly<{ Failed: "failed"; NotRun: "not-run"; Passed: "passed"; Skipped: "skipped" }> ``` **Value** `...` #### ENDINGS The endings in the order a reader is told of them: in the legend and in the totals. ```typescript const ENDINGS: unknown ``` **Value** `...` #### EXCERPT_LINES How many lines of a failed task's output are shown. ```typescript const EXCERPT_LINES: 60 ``` **Value** `60` #### Style The ways a piece of text is set apart on a terminal. ```typescript const Style: Readonly<{ Bold: "1"; Dim: "2"; Green: "32"; Red: "31"; Yellow: "33" }> ``` **Value** `...` --- Canonical page: https://www.hyperfrontend.dev/docs/libraries/workspace/progress/ This file: https://www.hyperfrontend.dev/docs/libraries/workspace/progress.md Documentation index: https://www.hyperfrontend.dev/llms.txt