ci library

A framework for a CI run by hand from the repository.

Stages run strictly one after another, past any red; every child process runs under the workspace flutter lock (CiLock) with each line of its output written to its log as it arrives (CiProcessRunner); every log is kept in one timestamped folder; and the run ends with one summary line (ciSummaryLine) naming every red step and the log that holds it. What a stage does is the repository's: a CiStageRunner handed to CiRun. ciToolDefinition and ciToolRunner put the stages on this package's command-line framework.

Nothing here schedules a run: it is started by a person.

Classes

CiCommand

One command to run.

CiLock

An advisory, directory-based lock.

CiOutcome

The result of one step of one stage.

CiPackage

One package a stage runs over.

CiProcessRunner

Runs commands one at a time under the workspace lock, each line of their output to a log file as it arrives.

CiRun

A whole run: the stages it was asked for, into one timestamped log folder.

CiStepResult

How a run of one or more commands into one log ended.

CiTestCounts

What a test run reported in its last progress line: +passed ~skipped -failed.

Functions

ciDartExecutable() → String

The Dart running this tool when it is a dart VM (it is, under dart run), else dart from PATH.

ciFlutterExecutable({Map<String, String>? environment}) → String?

FLUTTER_ROOT's flutter, else the SDK this Dart belongs to, else PATH, else null.

ciFlutterLockPath({required String repositoryRoot, String? workspaceRoot, Map<String, String>? environment}) → String

The workspace flutter lock: override when set (TOM_FLUTTER_LOCK), else <workspace>/ztmp/flutter.lock, else — a repository checked out on its own — <repository>/ztmp/flutter.lock.

ciIsFlutterPackage(String directory) → bool

Whether the package in directory declares a flutter SDK dependency.

ciSummaryLine({required List<String> stages, required List<CiOutcome> outcomes, required Duration elapsed, required String runDir, required String relativeTo}) → String

The single line every run ends with. One line — a person reading the end of a terminal and a script reading the last line of output get the same answer: green or red, and for each red, the log that holds the finding.

ciTestTagsOf(String directory, List<String> candidates) → List<String>

The tags among candidates that some test file under directory/test declares in an @Tags([...]) annotation, in candidates' order.

ciTimestamp(DateTime t) → String

YYYYMMDD-HHMMSS, the name of a run's log folder.

ciToolDefinition({required String name, required String description, required String version, required List<String> stages, required Map<String, String> descriptions, String? helpFooter, String examplePrefix = 'ci.sh'}) → ToolDefinition

The tool definition of a CI tool: one command per stage in stages, plus all, each described by descriptions (which must hold all too).

ciToolRunner({required ToolDefinition tool, required Future<String> runStages(List<String> stages, StringSink console), StringSink? console}) → ToolRunner

Builds the runner of a CI tool.

formatCiDuration(Duration d) → String

14m02s, 9s.

parseCiTestCounts(Iterable<String> lines) → CiTestCounts?

The counts of the last dart test / flutter test progress line among lines, or null when there is none (the run died before testing).

resolveCiStages(Iterable<String> requested, {required List<String> stages, bool inAll(String stage)?}) → List<String>

Expands all into stages, keeps the given order and drops repeats. Unknown names throw.

Typedefs

CiStageRunner = Future<void> Function(CiRun run, String stage)

What a stage does: given the run, it calls CiRun.step, CiRun.fail and CiRun.skip for each of its steps.