IF Commons GitHub

commands/define

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

How a command of ergonex is declared and run on Headless (commons 0001-ergonex FR-007, FR-010, FR-022, FR-023; commons headless 0003-headless-output, 0004-headless-cli): a command is declared once with its action's facts (what it may change, whether repeating it is safe, whether it can preview itself, where it may be reached from), its options and operands, and a body that returns a Report or a Failure. Headless parses the words, decides whether the run proceeds, previews, asks or is refused, draws the output (the report on standard output, the problems and the verdict on standard error), writes the run log and keeps the hints, and ends with the status of its one table; this module is what turns the body's report into Headless' typed outcome and writes the run's evidence record.

A finding of severity Error or Warning is a failure of the run (a status of 1, as the specifications say), and one that is Informational is a warning, which never changes the status; where a report says its own status is Ok (a Git hook lets Git go on with a warning) a warning stays a warning. A body that cannot do what it is asked returns a Failure: a command line that does not fit (usage) or a host that cannot do it (environment), which the program ends with the statuses 2 and 3 (the outcome names its exit, withExit).

Source: commons/ergonex/src/commands/define.ts

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

CommandDefinitiontypeno test imports it
type CommandDefinition<S extends Spec> = { readonly name: string; readonly summary: string; /** Its own options: `… (581 characters)
type CommandDefinition<S extends Spec> = {
  readonly name: string;
  readonly summary: string;
  /** Its own options: `--home` and the ones of the command; the options every command takes by its effect are Headless'. */
  readonly options: S & SpecCheck<S>;
  readonly operands?: readonly Operand[];
  readonly examples?: readonly Example[];
  /** What it is as an action: its kind, effect, whether it is safe to repeat, whether it previews and checks, and its reach policy. */
  readonly action: ActionTraits;
  readonly run: (ctx: Context, args: Args<S>) => Promise<Outcome>;
};

What a command is declared with.

defineCommandfunction
function defineCommand<S extends Spec>(d: CommandDefinition<S>): Make

A command from its declaration: Headless parses its words and options once at the boundary; the body runs on what decoded, and its report is the run's outcome. The run's evidence record is written after the body, for every run that ran (a command line Headless refuses runs nothing and records nothing).

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

Hosttype
type Host = Omit<BaseContext, "interact" | "note"> & {
  /** The whole command line, for the words the evidence record names. */
  readonly argv: readonly string[];
  /** The time in milliseconds since the Unix epoch. */
  readonly now: () => number;
};

What the program holds for every run of its commands: the facts of the host, which a test of the program gives its own.

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

Maketypeno test imports it
type Make = (host: Host) => HeadlessCommand;

A command, once it is given the host it runs on.

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