@hyperfrontend/workspace/progress

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 gives every task the first stage that names its target and moves a prerequisite to the earliest stage that needs it. 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 writes a line as each task ends, the excerpt of a failed task's log from failureExcerpt, a sign of life for a task that runs long, and at the end the matrix of matrixLines with the totals. It writes through a Terminal from createTerminal, which rewrites a status line on a terminal and writes plain lines everywhere else.

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

§function

assignStages(tasks: unknown, stages: unknown): Map<string, number>

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
NameTypeDescription
§tasks
unknownThe tasks, each with its target and the tasks it runs after
§stages
unknownThe target groups, in the order they run
Returns
Map<string, number>
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

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 }
§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
NameTypeDescription
§options
ViewOptionsThe 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

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
§function

createTerminal(sink: ProgressSink, env: Readonly<Record<string, string | undefined>>): 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
NameTypeDescription
§sink
ProgressSinkThe stream written to
§env
Readonly<Record<string, string | undefined>>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

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
§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
NameTypeDescription
§log
stringEverything the task printed
§limit
numberThe 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

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
§function

formatDuration(ms: number): string

A duration as a reader sees it.
Parameters
NameTypeDescription
§ms
numberMilliseconds
Returns
string
The duration in the largest units that fit
Example

Tenths under ten seconds, whole seconds under a minute

import { formatDuration } from '@hyperfrontend/workspace/progress'

formatDuration(800) // => '0.8s'
formatDuration(47_000) // => '47s'
formatDuration(1_097_000) // => '18m 17s'
§function

markOf(ending: Ending, paint: (text: string, style: Style) => string): string

The mark of an ending, in its style.
Parameters
NameTypeDescription
§ending
EndingHow a task ended
§paint
(text: string, style: Style) => stringSets text apart in a style
Returns
string
The mark, painted
Example

The same marks lead a task's line and fill the matrix

import { createTerminal, Ending, markOf } from '@hyperfrontend/workspace/progress'

markOf(Ending.Failed, createTerminal(process.stderr, process.env).paint) // => '✗', red on a terminal
§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
NameTypeDescription
§tasks
unknownEvery task of the run with how it ended
§paint
(text: string, style: Style) => stringSets 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

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',
// ]
§function

runStages<Task>(options: StagedOptions<Task>): Promise<StagedRun>

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
NameTypeDescription
§options
StagedOptions<Task>The tasks, the stage of each and how one stage runs
Returns
Promise<StagedRun>
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

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'] }
§function

taskLogPath(id: string, directory: string): string

The log file of a task, under a log directory.
Parameters
NameTypeDescription
§id
stringThe task, <project>:<target>
§directory
stringThe 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

import { taskLogPath } from '@hyperfrontend/workspace/progress'

taskLogPath('lib-core:build', '.hf/logs') // => '.hf/logs/lib-core__build.log'

◈ Interfaces

§interface

Identified

A task as far as a staged run names it.
Properties
§readonly id:string<project>:<target>.
§interface

MatrixTask

One task of the matrix.
Properties
§readonly project:stringThe row: the project.
§readonly target:stringThe column: the target.
§readonly stage:numberThe stage the task ran in, counted from 0; the columns follow the stages.
§readonly ending:EndingHow the task ended.
§interface

ProgressSink

A stream the progress is written to, as far as it is read here.
Properties
§readonly isTTY?:booleanWhether the stream is a terminal.
§readonly columns?:numberThe width of the terminal, in columns.
Methods
§write(text: string): unknown
Writes text.

Parameters

NameTypeDescription
§text
string
§interface

ProgressView

The view of one run.
Properties
§readonly stage:(stage: number) => voidSays a stage starts.
§readonly started:(id: string) => voidNotes that a task started.
§readonly ended:(end: TaskEnd) => voidWrites the line of a task that ended, and under a failed one its excerpt and where its log is.
§readonly tick:() => voidShows what has been running long; meant to be called every second or so.
§readonly finish:(stopped: number) => voidWrites the matrix and the totals; the tasks that never ended are shown as not run.
§interface

StagedOptions

What a staged run needs.
Properties
§readonly tasks:unknownThe tasks, in the order they run inside a stage.
§readonly stageOf:ReadonlyMap<string, number>The stage of each task, by id, counted from 0.
§readonly runStage:(tasks: unknown, stage: number) => Promise<boolean>Runs the tasks of one stage to the end and resolves to whether every one of them succeeded.
§interface

StagedRun

How a staged run ended.
Properties
§readonly stopped:numberThe stage that did not succeed and ended the run, counted from 0, or null when every stage ran.
§readonly notRun:unknownThe ids of the tasks of the stages that never started, in the order given.
§interface

StagedTask

What staging reads off a task.
Properties
§readonly id:string<project>:<target>.
§readonly target:stringThe target.
§readonly needs:unknownThe ids of the tasks it runs after.
§interface

TaskEnd

How one task ended.
Properties
§readonly id:string<project>:<target>.
§readonly ending:EndingWhether it passed, failed, or was skipped.
§readonly durationMs:numberHow long it ran, in milliseconds.
§readonly detail:stringWhy it did not run or did not reach an exit, shown in place of the duration, or null.
§readonly excerpt:stringThe part of a failed task's log that explains the failure, or null.
§readonly log:stringWhere the task's log is, or null when it wrote none.
§interface

Terminal

The lines and the status of a run, as the view writes them.
Properties
§readonly plain:booleanWhether the output takes plain lines alone: no colour, and no line rewritten in place.
§readonly line:(text: string) => voidWrites a finished line, in place of the status when one is shown.
§readonly status:(text: string) => voidShows a status the next line or status replaces; writes nothing on plain output.
§readonly paint:(text: string, style: Style) => stringSets text apart in a style; the text itself on plain output.
§interface

ViewOptions

What a view needs.
Properties
§readonly tasks:unknownEvery task of the run.
§readonly stages:numberHow many stages the run has.
§readonly terminal:TerminalWhere the lines and the status go.
§readonly now:() => numberThe current time in milliseconds.
§readonly thresholdMs?:numberHow long a task runs before a terminal shows it as running; 3 seconds unless given.
§readonly intervalMs?:numberHow long a task runs between two lines saying so on plain output; 30 seconds unless given.
§interface

ViewTask

One task of the run, as the view names and places it.
Properties
§readonly id:string<project>:<target>.
§readonly project:stringThe row of the matrix it belongs to.
§readonly target:stringThe column of the matrix it belongs to.
§readonly stage:numberThe stage it runs in, counted from 0.

◆ Types

§type

Ending

One of the endings.
type Ending = indexedAccess
§type

Style

One of the styles.
type Style = indexedAccess

● Variables

§type

Ending

How a task ended, as a reader is shown it.
§type

ENDINGS

The endings in the order a reader is told of them: in the legend and in the totals.
§type

EXCERPT_LINES

How many lines of a failed task's output are shown.
§type

Style

The ways a piece of text is set apart on a terminal.