IF Commons GitHub

logical/program

Written to: 3 requirements: 3 proved, 0 partly, 0 failing, 0 with no test recorded. 0003-headless-output FR-008, 0003-headless-output FR-001, 0003-headless-output FR-010

What a program tells Headless about itself (commons headless 0003-headless-output): the mechanisms of the library are configured with the program's own data, never with the library's guesses. Its name and version, the prefix of its environment variables, the name of its folder of state, the catalogue of codes it explains, the patterns of the raw errors it recognizes, where its guides are, which commands its fixes call, its secrets, and its tree. Everything a program keeps for itself (its explanations, its guides, its paths, its prompts) is here as data, and stays its own.

import { programOf } from "./program.ts";
const p = programOf({ name: "tool", summary: "A tool.", version: "1.0.0", children: [] });
p.envPrefix; // "TOOL"

Source: commons/headless/src/logical/program.ts

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

logical.ProgramConfigtypeno test imports it
type ProgramConfig = { readonly name: string; readonly summary: string; readonly version: string; readonly child… (1694 characters)
type ProgramConfig = {
  readonly name: string;
  readonly summary: string;
  readonly version: string;
  readonly children: readonly Node[];
  /** The prefix of the program's environment variables (`TOOL`): default, its name in capitals. */
  readonly envPrefix?: string;
  /** The name of its folder under the system's state folder: default, its name. */
  readonly stateApp?: string;
  /** What its fixes may call. */
  readonly fix?: FixCommands;
  readonly catalogue?: Catalogue;
  readonly patterns?: readonly RawPattern[];
  readonly guide?: GuideLinks;
  readonly generic?: GenericCodes;
  /** The secret values the program holds: redacted wherever they would be written. */
  readonly secrets?: () => readonly string[];
  /** The names of the keys that are secret in this program (`APP_TOKEN`): the value of `KEY=value` is redacted. A sentence that only names a variable is not. */
  readonly secretKeys?: readonly string[];
  /** The targets `--on` can name. */
  readonly targets?: readonly Target[];
  /** How a run over targets is bounded: how many at once (4) and how long each may take (30 s). */
  readonly remote?: { readonly concurrency?: number; readonly perHostTimeoutMs?: number };
  /** The words to run where none are given (`status`); none by default, and the help is shown. */
  readonly defaultCommand?: readonly string[];
  /** The tiers of the program, lowest first, and the tier of a caller who says nothing (0010-audience-tiers): the default ladder where none is given. */
  readonly tiers?: TierLadder;
  /** Who contributed each command, by the words of its id (0009-composition): the run log says it. */
  readonly origins?: Readonly<Record<string, string>>;
};

What a program gives.

logical.Programtypeno test imports it
type Program = { readonly name: string; readonly summary: string; readonly version: string; readonly children: r… (755 characters)
type Program = {
  readonly name: string;
  readonly summary: string;
  readonly version: string;
  readonly children: readonly Node[];
  readonly envPrefix: string;
  readonly stateApp: string;
  readonly nested: NestedNames;
  readonly fix: FixCommands;
  readonly catalogue: Catalogue;
  readonly patterns: readonly RawPattern[];
  readonly guide: GuideLinks | undefined;
  readonly generic: GenericCodes;
  readonly secrets: () => readonly string[];
  readonly secretKeys: readonly string[];
  readonly defaultCommand: readonly string[];
  readonly targets: readonly Target[];
  readonly remote: { readonly concurrency: number; readonly perHostTimeoutMs: number };
  readonly tiers: TierLadder;
  readonly origins: Readonly<Record<string, string>>;
};

A program with every default filled.

logical.programOffunctionno test imports it
function programOf(c: ProgramConfig): Program

The program with the defaults of everything it did not give.

ProgramConfigtype
type ProgramConfig = { readonly name: string; readonly summary: string; readonly version: string; readonly child… (1694 characters)
type ProgramConfig = {
  readonly name: string;
  readonly summary: string;
  readonly version: string;
  readonly children: readonly Node[];
  /** The prefix of the program's environment variables (`TOOL`): default, its name in capitals. */
  readonly envPrefix?: string;
  /** The name of its folder under the system's state folder: default, its name. */
  readonly stateApp?: string;
  /** What its fixes may call. */
  readonly fix?: FixCommands;
  readonly catalogue?: Catalogue;
  readonly patterns?: readonly RawPattern[];
  readonly guide?: GuideLinks;
  readonly generic?: GenericCodes;
  /** The secret values the program holds: redacted wherever they would be written. */
  readonly secrets?: () => readonly string[];
  /** The names of the keys that are secret in this program (`APP_TOKEN`): the value of `KEY=value` is redacted. A sentence that only names a variable is not. */
  readonly secretKeys?: readonly string[];
  /** The targets `--on` can name. */
  readonly targets?: readonly Target[];
  /** How a run over targets is bounded: how many at once (4) and how long each may take (30 s). */
  readonly remote?: { readonly concurrency?: number; readonly perHostTimeoutMs?: number };
  /** The words to run where none are given (`status`); none by default, and the help is shown. */
  readonly defaultCommand?: readonly string[];
  /** The tiers of the program, lowest first, and the tier of a caller who says nothing (0010-audience-tiers): the default ladder where none is given. */
  readonly tiers?: TierLadder;
  /** Who contributed each command, by the words of its id (0009-composition): the run log says it. */
  readonly origins?: Readonly<Record<string, string>>;
};

What a program gives.

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

Programtype
type Program = { readonly name: string; readonly summary: string; readonly version: string; readonly children: r… (755 characters)
type Program = {
  readonly name: string;
  readonly summary: string;
  readonly version: string;
  readonly children: readonly Node[];
  readonly envPrefix: string;
  readonly stateApp: string;
  readonly nested: NestedNames;
  readonly fix: FixCommands;
  readonly catalogue: Catalogue;
  readonly patterns: readonly RawPattern[];
  readonly guide: GuideLinks | undefined;
  readonly generic: GenericCodes;
  readonly secrets: () => readonly string[];
  readonly secretKeys: readonly string[];
  readonly defaultCommand: readonly string[];
  readonly targets: readonly Target[];
  readonly remote: { readonly concurrency: number; readonly perHostTimeoutMs: number };
  readonly tiers: TierLadder;
  readonly origins: Readonly<Record<string, string>>;
};

A program with every default filled.

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

programOffunction
function programOf(c: ProgramConfig): Program

The program with the defaults of everything it did not give.

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

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