IF Commons GitHub

modules/types

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-ergonex FR-007

The typed values every command of ergonex shares (commons 0001-ergonex FR-007, FR-010, FR-022): what a command's body returns (Report, or a Failure), the facts of the run it is given (Context), and the four statuses of the evidence record. A command is declared once with Headless (commands/define.ts), which parses its words, draws its output and gives its exit status; its body returns a Result of a Report or a Failure. There is no any, and a switch over a union of statuses or sources is exhaustive.

Pure: a command is given everything the host holds (the environment, the working folder, the day, the platform, where to write and whether to ask) in its Context, and does its work through the ports of that context and the host layer it imports, so that the same command is run in a test with a context of the test's making and by the program with the real one.

Source: commons/ergonex/src/modules/types.ts

4 of 10 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

EXIT_STATUSESconst
const EXIT_STATUSES: readonly ExitStatus[]

The statuses, in the order of their numbers.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

ExitStatustypeno test imports it
type ExitStatus = "Ok" | "Findings" | "Usage" | "Environment";

How a run ends: the keys of the code list ergonex:ExitStatus.

exitCodeOffunction
function exitCodeOf(status: ExitStatus): 0 | 1 | 2 | 3

The number a run exits with (ergonex:exitCode).

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

ErgonexModuletypeno test imports it
type ErgonexModule = {
  readonly name: string;
  readonly summary: string;
  /** The words below it, where it is a branch (`worktree create`); none for a command. */
  readonly commands: readonly string[];
};

A command of the program, as the discovery of modules sees it: the built-in modules are the words of the program's own tree.

MODULE_SOURCESconst
const MODULE_SOURCES: readonly ModuleSource[]

The sources, in the order a module is looked for (ergonex:precedence).

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

ModuleSourcetypeno test imports it
type ModuleSource = "BuiltIn" | "Registered" | "Path";

Where a module was found: the keys of the code list ergonex:ModuleSource, looked in in this order.

precedenceOffunction
function precedenceOf(source: ModuleSource): number

The place of a source in the order: 1 is looked in first (ergonex:precedence).

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

Reporttypeno test imports it
type Report = { /** What is written to standard output without `--json`. */ readonly text: string; /** What is wri… (1213 characters)
type Report = {
  /** What is written to standard output without `--json`. */
  readonly text: string;
  /** What is written with `--json`, under `data`. */
  readonly data: Json;
  /** What the run found; its worst severity decides the status. */
  readonly findings: readonly Finding[];
  /** The status where it is not the findings' (`render --check` ends in `Findings` where a file would change). */
  readonly status?: ExitStatus;
  /** What the evidence record of the run names besides the findings. */
  readonly facts?: EvidenceFacts;
  /** The facts of a run whose evidence is the setup module's (`setup/host/evidence.ts`): `setup` and `tools`. Where it is given the controller writes the record from it. */
  readonly runFacts?: RunFacts;
  /** The step the run suggests next, as a command (`ergonex plan`): the closing of an action shows it. */
  readonly next?: readonly string[];
  /** What the verdict says where all is well (`Workspace made`); Headless says `Up to date` where there is none. */
  readonly title?: string;
  /** The run writes no evidence record: `ergonex shell print <shell>` writes no file (0003-host FR-017), and a hook only reads (FR-015). */
  readonly noEvidence?: boolean;
};

What a run did, for a person and as data.

Failuretypeno test imports it
type Failure = {
  readonly kind: "usage" | "environment";
  readonly message: string;
  readonly noEvidence?: boolean;
};

Why a run could not be done: a command line that does not fit, or a host that cannot do it.

Contexttypeno test imports it
type Context = BaseContext & {
  readonly globals: Globals;
  /** The root of the workspace: `--home`, else `$ERGONEX_HOME`, else `$HOME/workspaces`; undefined where none can be found. */
  readonly home: string | undefined;
  /** Whether the run is a preview (`--dry-run`), a check (`--check`) or neither. */
  readonly mode: "apply" | "dry-run" | "check";
};

What a command is given: the base and the options every command has, decoded.

Titles, headings, exports, tables, columns and requirements. Esc closes.