IF Commons GitHub

governance/exits

Written to: 2 requirements: 2 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-headless-governance FR-009, 0002-headless-governance FR-010

The exit statuses of a headless program, one table for every program (commons headless 0002-headless-governance FR-009). A run's own verdicts are 0 to 4 (the statuses of a tool that reports: Ok, Findings, Usage, Environment, and Pending, which is kept apart from a failure); a program that cannot start at all uses the range of sysexits.h (64 and up), which a launcher, a service manager and a shell already know; a signal is 128 plus its number.

Sources reconciled here: ergonex returned 0 to 3; erga's launcher gave its startup failures 4 to 11; stolos returned 0 or 1 and never made pending a status. The run's verdicts keep ergonex's numbers (a script that tests $? -eq 1 for findings keeps working), the launcher's failures move above 63 so that 4 is free for Pending, and nothing below 64 but 0 to 4 is used.

import { exitCodeOf, exitOfRun } from "./exits.ts";
exitCodeOf("usage"); // 2
exitOfRun({ fail: 0, warn: 1, pending: 2, action: 0 }, { pending: "pending" }); // 4

Source: commons/headless/src/governance/exits.ts

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

governance.ExitNametypeno test imports it
type ExitName =
  | "ok"
  | "findings"
  | "usage"
  | "environment"
  | "pending"
  | "startup-usage"
  | "startup-unavailable"
  | "startup-software"
  | "startup-osfile"
  | "startup-config"
  | "interrupted"
  | "terminated";

What a run ended as, by name.

governance.EXIT_NAMESconstno test imports it
const EXIT_NAMES: readonly ExitName[]

Every exit name, in the order of its status.

governance.exitCodeOffunctionno test imports it
function exitCodeOf(name: ExitName): number

The status of a name.

governance.exitNameOffunctionno test imports it
function exitNameOf(code: number): ExitName | undefined

The name of a status, or undefined for one the table does not hold.

governance.exitMeaningfunctionno test imports it
function exitMeaning(name: ExitName): string

What a status means, in one line, for the help and for explain.

governance.exitOfSignalfunctionno test imports it
function exitOfSignal(signal: "SIGINT" | "SIGTERM"): number

The status of the signal a run was stopped by (128 plus its number).

governance.Countstypeno test imports it
type Counts = { readonly fail: number; readonly warn: number; readonly pending: number; readonly action: number };

How many problems of each level a run found.

governance.PendingPolicytypeno test imports it
type PendingPolicy = { readonly pending?: "ok" | "pending" };

What a run does with what is only pending: it is a success (ok, the default of an action), or its own status (pending, for a report that is asked to check).

governance.exitOfRunfunctionno test imports it
function exitOfRun(counts: Counts, policy?: PendingPolicy): number

The status of a run from what it found: findings where anything failed; else pending where the policy says pending is its own status and something is pending; else ok. A warning and a step for the person are not failures and never change the status.

governance.RunExittypeno test imports it
type RunExit = "ok" | "findings" | "usage" | "environment" | "pending";

The verdicts of a run that a command can name for itself: the closed union of the exit names that are a run's own (not a launcher's, not a signal's).

governance.RUN_EXITSconstno test imports it
const RUN_EXITS: readonly RunExit[]

Every run exit, from the least severe to the most.

governance.moreSeverefunctionno test imports it
function moreSevere(a: RunExit | undefined, b: RunExit | undefined): RunExit | undefined

The more severe of two named exits (undefined is no name): usage, then environment, findings, pending, ok.

governance.exitOfNamedfunctionno test imports it
function exitOfNamed(counts: Counts, named: RunExit | undefined, policy?: PendingPolicy): number

The status of a run from what it found and the exit its command named (0008-exit-style-consent FR-001): no name, or ok, is the status of exitOfRun; pending is 4 unless something failed; findings, usage and environment are their own statuses, however little was found. The same status is what the JSON envelope carries, so that the code and the document agree.

ExitNametype
type ExitName =
  | "ok"
  | "findings"
  | "usage"
  | "environment"
  | "pending"
  | "startup-usage"
  | "startup-unavailable"
  | "startup-software"
  | "startup-osfile"
  | "startup-config"
  | "interrupted"
  | "terminated";

What a run ended as, by name.

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

EXIT_NAMESconst
const EXIT_NAMES: readonly ExitName[]

Every exit name, in the order of its status.

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

exitCodeOffunction
function exitCodeOf(name: ExitName): number

The status of a name.

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

exitNameOffunction
function exitNameOf(code: number): ExitName | undefined

The name of a status, or undefined for one the table does not hold.

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

exitMeaningfunction
function exitMeaning(name: ExitName): string

What a status means, in one line, for the help and for explain.

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

exitOfSignalfunction
function exitOfSignal(signal: "SIGINT" | "SIGTERM"): number

The status of the signal a run was stopped by (128 plus its number).

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

Countstype
type Counts = { readonly fail: number; readonly warn: number; readonly pending: number; readonly action: number };

How many problems of each level a run found.

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

PendingPolicytypeno test imports it
type PendingPolicy = { readonly pending?: "ok" | "pending" };

What a run does with what is only pending: it is a success (ok, the default of an action), or its own status (pending, for a report that is asked to check).

exitOfRunfunction
function exitOfRun(counts: Counts, policy?: PendingPolicy): number

The status of a run from what it found: findings where anything failed; else pending where the policy says pending is its own status and something is pending; else ok. A warning and a step for the person are not failures and never change the status.

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

RunExittype
type RunExit = "ok" | "findings" | "usage" | "environment" | "pending";

The verdicts of a run that a command can name for itself: the closed union of the exit names that are a run's own (not a launcher's, not a signal's).

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

RUN_EXITSconst
const RUN_EXITS: readonly RunExit[]

Every run exit, from the least severe to the most.

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

moreSeverefunction
function moreSevere(a: RunExit | undefined, b: RunExit | undefined): RunExit | undefined

The more severe of two named exits (undefined is no name): usage, then environment, findings, pending, ok.

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

exitOfNamedfunction
function exitOfNamed(counts: Counts, named: RunExit | undefined, policy?: PendingPolicy): number

The status of a run from what it found and the exit its command named (0008-exit-style-consent FR-001): no name, or ok, is the status of exitOfRun; pending is 4 unless something failed; findings, usage and environment are their own statuses, however little was found. The same status is what the JSON envelope carries, so that the code and the document agree.

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

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