IF Commons GitHub

logical/model

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

The command model (commons headless 0003-headless-output FR-001): a program is a tree of branches and commands; a command is a verb of the terminal's declaration (its name, summary, options and operands, declared once) with the facts of its action (commons headless 0002-headless-governance) and the function that runs it, which returns a typed outcome and prints nothing. A surface draws the tree: the command line as words and options, a tool server as tools, a REST interface as routes.

The options every command takes by its effect (--json, --quiet, --verbose, --no-color, --non-interactive; --dry-run where it can preview, --check where it can check, --yes where it destroys) are the model's (standardOptions), so that no program redeclares them and none can declare a different meaning for their names.

import { branch, command } from "./model.ts";
const status = command({ name: "status", summary: "Show the status.", action: { kind: "report" }, options: {}, run: async () => ({}) as never });
branch({ name: "repo", summary: "Repositories.", children: [status] }).children.length; // 1

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

13 of 50 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.ActionTraitstypeno test imports it
type ActionTraits = Omit<ActionDefinition, "id" | "summary"> & {
  /** Where it may be reached from and run (commons headless 0005-reach-and-targets): required of every action by the conformance rule `model/no-reach-policy`. */
  readonly reach?: ReachPolicy;
};

What a command is as an action, besides its identity (the path of its words and its summary are the tree's).

logical.Contexttypeno test imports it
type Context = { readonly program: string; /** The words of the command as typed (`work build`). */ readonly comma… (969 characters)
type Context = {
  readonly program: string;
  /** The words of the command as typed (`work build`). */
  readonly command: string;
  readonly facts: ActionFacts;
  readonly mode: Mode;
  readonly verbosity: Verbosity;
  /** Whether the person can be asked a question now. */
  readonly interactive: boolean;
  /** Where the command tells what it is doing, as it does it. */
  readonly progress: Progress;
  /** A question to the person; each answers `undefined` where there is no one to ask. */
  readonly prompt: Prompt;
  /** The credentials of this one command (0011-credential-prompt): asked once each, held in memory until the command ends, refused where there is no person, never logged. */
  readonly credentials: Credentials;
  /** The environment, as a function. */
  readonly env: (name: string) => string | undefined;
  /** Aborted when the person stops the run (SIGINT, SIGTERM): a command that can stop early listens. */
  readonly signal: AbortSignal;
};

What a command is told about its run.

logical.Prompttypeno test imports it
type Prompt = {
  readonly ask: (question: string) => Promise<string | undefined>;
  /** `undefined` where there is no person to ask: the decision is then the governance's (`decide`), never a guess. */
  readonly confirm: (question: string) => Promise<boolean | undefined>;
};

A question to the person.

logical.NO_PROMPTconstno test imports it
const NO_PROMPT: Prompt

A prompt that asks no one.

logical.ProgressEventtypeno test imports it
type ProgressEvent = | { readonly kind: "header"; readonly title: string; readonly subtitle: string } | { readonly k… (640 characters)
type ProgressEvent =
  | { readonly kind: "header"; readonly title: string; readonly subtitle: string }
  | { readonly kind: "phase"; readonly name: string }
  | { readonly kind: "step"; readonly n: number; readonly total: number; readonly label: string }
  | { readonly kind: "item"; readonly item: "ok" | "skip" | "change" | "note"; readonly message: string }
  | { readonly kind: "problem"; readonly problem: Problem }
  | { readonly kind: "outcome"; readonly text: string }
  | { readonly kind: "hint"; readonly hint: Hint }
  | { readonly kind: "live"; readonly message: string }
  | { readonly kind: "done"; readonly result: string };

What a command tells while it runs.

logical.Progresstypeno test imports it
type Progress = (event: ProgressEvent) => void;

Where a command's progress goes.

logical.NO_PROGRESSconstno test imports it
const NO_PROGRESS: Progress

A progress that is told nothing.

logical.PhaseWritertypeno test imports it
type PhaseWriter = { readonly step: (n: number, total: number, label?: string) => void; readonly live: (message: str… (778 characters)
type PhaseWriter = {
  readonly step: (n: number, total: number, label?: string) => void;
  readonly live: (message: string) => void;
  readonly done: (result: string) => void;
  readonly ok: (message: string) => void;
  readonly skip: (message: string) => void;
  readonly change: (message: string) => void;
  readonly note: (message: string) => void;
  readonly warn: (message: string, fields?: ProblemFields) => void;
  readonly fail: (message: string, fields?: ProblemFields) => void;
  readonly pending: (message: string, next: string, fields?: ProblemFields) => void;
  readonly action: (message: string, next: string, fields?: ProblemFields) => void;
  readonly outcome: (text: string) => void;
  readonly hint: (id: string, message: string, command?: string) => void;
};

The ways to tell a phase's progress, as a person writes them.

logical.announcefunctionno test imports it
function announce(progress: Progress, title: string, subtitle?: string): void

Says what the run is, before its first phase: a title and, where there is one, a subtitle.

logical.startPhasefunctionno test imports it
function startPhase(progress: Progress, name: string): PhaseWriter

Starts a phase of the run and gives the writer of what happens in it.

logical.Commandtypeno test imports it
type Command<S extends Spec = Spec> = {
  readonly kind: "command";
  readonly name: string;
  readonly summary: string;
  readonly options: S;
  readonly operands: readonly Operand[];
  readonly examples: readonly Example[];
  readonly action: ActionTraits;
  run(args: Args<S>, ctx: Context): Promise<Outcome>;
};

A command: a verb, its action's traits, and what it does.

logical.commandfunctionno test imports it
function command<S extends Spec>(c: { readonly name: string; readonly summary: string; readonly options: S & SpecCheck<S>; readonly operands?: readonly Operand[] | undefined; readonly examples?: readonly Example[] | undefined; readonly action: ActionTraits; run(args: Args<S>, ctx: Context): Promise<Outcome>; }): Command<S>

A command, declared with its options checked as the terminal checks them.

logical.Branchtypeno test imports it
type Branch = {
  readonly kind: "branch";
  readonly name: string;
  readonly summary: string;
  readonly children: readonly Node[];
};

A word that names more commands.

logical.Nodetypeno test imports it
type Node = Branch | Command;

One node of a program's tree.

logical.branchfunctionno test imports it
function branch(b: { readonly name: string; readonly summary: string; readonly children: readonly Node[]; }): Branch

A branch of nodes.

logical.Placedtypeno test imports it
type Placed = { readonly path: readonly string[]; readonly id: string; readonly command: Command; readonly facts: ActionFacts; readonly reach: ReachPolicy | undefined };

A command together with the path of its words.

logical.placedCommandsfunctionno test imports it
function placedCommands(children: readonly Node[], path?: readonly string[]): readonly Placed[]

The commands of a tree, each with its path and the facts of its action (its id is its words below the program, joined by spaces).

logical.treeOffunctionno test imports it
function treeOf(program: { readonly name: string; readonly summary: string; readonly children: readonly Node[]; }): Group

The terminal's tree of a program: what resolves a command line and renders the help of every level.

logical.verbOffunctionno test imports it
function verbOf(c: Command<Spec>): Verb

The verb of a command as the terminal declares it.

logical.BUILT_IN_WORDSconstno test imports it
const BUILT_IN_WORDS: readonly ["help", "explain", "completions", "man", "run"]

The words of the program's own place that the surface answers itself (help, explain, completions, man): a program's tree may not use them for a command.

logical.STANDARD_KEYSconstno test imports it
const STANDARD_KEYS: readonly ["json", "sarif", "quiet", "verbose", "color", "nonInteractive", "dryRun", "check", "yes", "on", "consent"]

The options of the model, by their keys.

logical.StandardKeytypeno test imports it
type StandardKey = (typeof STANDARD_KEYS)[number];

One of the model's standard option keys.

logical.standardOptionsfunctionno test imports it
function standardOptions(facts: ActionFacts, reach?: ReachPolicy | undefined): Spec

The options every command takes, and those its action's facts add: --dry-run where it can preview, --check where it can check, --yes where it destroys.

logical.ModelProblemtypeno test imports it
type ModelProblem = | { readonly rule: "model/tree"; readonly problem: TreeProblem } | { readonly rule: "model/actio… (710 characters)
type ModelProblem =
  | { readonly rule: "model/tree"; readonly problem: TreeProblem }
  | { readonly rule: "model/action"; readonly id: string; readonly problem: ActionProblem }
  | { readonly rule: "model/reserved-option"; readonly id: string; readonly option: string }
  | { readonly rule: "model/reserved-short"; readonly id: string; readonly option: string; readonly short: string }
  | { readonly rule: "model/built-in-word"; readonly word: string }
  | { readonly rule: "model/no-reach-policy"; readonly id: string }
  | { readonly rule: "model/reach"; readonly id: string; readonly problem: ReachProblem }
  | { readonly rule: "model/human-only-unknown"; readonly id: string; readonly option: string };

What is wrong with a program's model.

logical.modelProblemsfunctionno test imports it
function modelProblems(program: { readonly name: string; readonly summary: string; readonly children: readonly Node[]; }, options?: { readonly requireReach?: boolean | undefined; }): readonly ModelProblem[]

Everything wrong with a program's tree: what the terminal finds in its names (a duplicate, a bad name), what the governance finds in each action's facts, an option of a command named as one of the model's standard options, and a human-only option the command does not declare.

ActionTraitstypeno test imports it
type ActionTraits = Omit<ActionDefinition, "id" | "summary"> & {
  /** Where it may be reached from and run (commons headless 0005-reach-and-targets): required of every action by the conformance rule `model/no-reach-policy`. */
  readonly reach?: ReachPolicy;
};

What a command is as an action, besides its identity (the path of its words and its summary are the tree's).

Contexttype
type Context = { readonly program: string; /** The words of the command as typed (`work build`). */ readonly comma… (969 characters)
type Context = {
  readonly program: string;
  /** The words of the command as typed (`work build`). */
  readonly command: string;
  readonly facts: ActionFacts;
  readonly mode: Mode;
  readonly verbosity: Verbosity;
  /** Whether the person can be asked a question now. */
  readonly interactive: boolean;
  /** Where the command tells what it is doing, as it does it. */
  readonly progress: Progress;
  /** A question to the person; each answers `undefined` where there is no one to ask. */
  readonly prompt: Prompt;
  /** The credentials of this one command (0011-credential-prompt): asked once each, held in memory until the command ends, refused where there is no person, never logged. */
  readonly credentials: Credentials;
  /** The environment, as a function. */
  readonly env: (name: string) => string | undefined;
  /** Aborted when the person stops the run (SIGINT, SIGTERM): a command that can stop early listens. */
  readonly signal: AbortSignal;
};

What a command is told about its run.

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

Prompttypeno test imports it
type Prompt = {
  readonly ask: (question: string) => Promise<string | undefined>;
  /** `undefined` where there is no person to ask: the decision is then the governance's (`decide`), never a guess. */
  readonly confirm: (question: string) => Promise<boolean | undefined>;
};

A question to the person.

NO_PROMPTconstno test imports it
const NO_PROMPT: Prompt

A prompt that asks no one.

ProgressEventtype
type ProgressEvent = | { readonly kind: "header"; readonly title: string; readonly subtitle: string } | { readonly k… (640 characters)
type ProgressEvent =
  | { readonly kind: "header"; readonly title: string; readonly subtitle: string }
  | { readonly kind: "phase"; readonly name: string }
  | { readonly kind: "step"; readonly n: number; readonly total: number; readonly label: string }
  | { readonly kind: "item"; readonly item: "ok" | "skip" | "change" | "note"; readonly message: string }
  | { readonly kind: "problem"; readonly problem: Problem }
  | { readonly kind: "outcome"; readonly text: string }
  | { readonly kind: "hint"; readonly hint: Hint }
  | { readonly kind: "live"; readonly message: string }
  | { readonly kind: "done"; readonly result: string };

What a command tells while it runs.

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

Progresstypeno test imports it
type Progress = (event: ProgressEvent) => void;

Where a command's progress goes.

NO_PROGRESSconst
const NO_PROGRESS: Progress

A progress that is told nothing.

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

PhaseWritertypeno test imports it
type PhaseWriter = { readonly step: (n: number, total: number, label?: string) => void; readonly live: (message: str… (778 characters)
type PhaseWriter = {
  readonly step: (n: number, total: number, label?: string) => void;
  readonly live: (message: string) => void;
  readonly done: (result: string) => void;
  readonly ok: (message: string) => void;
  readonly skip: (message: string) => void;
  readonly change: (message: string) => void;
  readonly note: (message: string) => void;
  readonly warn: (message: string, fields?: ProblemFields) => void;
  readonly fail: (message: string, fields?: ProblemFields) => void;
  readonly pending: (message: string, next: string, fields?: ProblemFields) => void;
  readonly action: (message: string, next: string, fields?: ProblemFields) => void;
  readonly outcome: (text: string) => void;
  readonly hint: (id: string, message: string, command?: string) => void;
};

The ways to tell a phase's progress, as a person writes them.

announcefunction
function announce(progress: Progress, title: string, subtitle?: string): void

Says what the run is, before its first phase: a title and, where there is one, a subtitle.

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

startPhasefunction
function startPhase(progress: Progress, name: string): PhaseWriter

Starts a phase of the run and gives the writer of what happens in it.

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

Commandtypeno test imports it
type Command<S extends Spec = Spec> = {
  readonly kind: "command";
  readonly name: string;
  readonly summary: string;
  readonly options: S;
  readonly operands: readonly Operand[];
  readonly examples: readonly Example[];
  readonly action: ActionTraits;
  run(args: Args<S>, ctx: Context): Promise<Outcome>;
};

A command: a verb, its action's traits, and what it does.

commandfunction
function command<S extends Spec>(c: { readonly name: string; readonly summary: string; readonly options: S & SpecCheck<S>; readonly operands?: readonly Operand[] | undefined; readonly examples?: readonly Example[] | undefined; readonly action: ActionTraits; run(args: Args<S>, ctx: Context): Promise<Outcome>; }): Command<S>

A command, declared with its options checked as the terminal checks them.

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

Branchtypeno test imports it
type Branch = {
  readonly kind: "branch";
  readonly name: string;
  readonly summary: string;
  readonly children: readonly Node[];
};

A word that names more commands.

Nodetype
type Node = Branch | Command;

One node of a program's tree.

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

branchfunction
function branch(b: { readonly name: string; readonly summary: string; readonly children: readonly Node[]; }): Branch

A branch of nodes.

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

Placedtypeno test imports it
type Placed = { readonly path: readonly string[]; readonly id: string; readonly command: Command; readonly facts: ActionFacts; readonly reach: ReachPolicy | undefined };

A command together with the path of its words.

placedCommandsfunction
function placedCommands(children: readonly Node[], path?: readonly string[]): readonly Placed[]

The commands of a tree, each with its path and the facts of its action (its id is its words below the program, joined by spaces).

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

treeOffunction
function treeOf(program: { readonly name: string; readonly summary: string; readonly children: readonly Node[]; }): Group

The terminal's tree of a program: what resolves a command line and renders the help of every level.

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

verbOffunctionno test imports it
function verbOf(c: Command<Spec>): Verb

The verb of a command as the terminal declares it.

BUILT_IN_WORDSconstno test imports it
const BUILT_IN_WORDS: readonly ["help", "explain", "completions", "man", "run"]

The words of the program's own place that the surface answers itself (help, explain, completions, man): a program's tree may not use them for a command.

STANDARD_KEYSconst
const STANDARD_KEYS: readonly ["json", "sarif", "quiet", "verbose", "color", "nonInteractive", "dryRun", "check", "yes", "on", "consent"]

The options of the model, by their keys.

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

StandardKeytypeno test imports it
type StandardKey = (typeof STANDARD_KEYS)[number];

One of the model's standard option keys.

standardOptionsfunction
function standardOptions(facts: ActionFacts, reach?: ReachPolicy | undefined): Spec

The options every command takes, and those its action's facts add: --dry-run where it can preview, --check where it can check, --yes where it destroys.

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

ModelProblemtypeno test imports it
type ModelProblem = | { readonly rule: "model/tree"; readonly problem: TreeProblem } | { readonly rule: "model/actio… (710 characters)
type ModelProblem =
  | { readonly rule: "model/tree"; readonly problem: TreeProblem }
  | { readonly rule: "model/action"; readonly id: string; readonly problem: ActionProblem }
  | { readonly rule: "model/reserved-option"; readonly id: string; readonly option: string }
  | { readonly rule: "model/reserved-short"; readonly id: string; readonly option: string; readonly short: string }
  | { readonly rule: "model/built-in-word"; readonly word: string }
  | { readonly rule: "model/no-reach-policy"; readonly id: string }
  | { readonly rule: "model/reach"; readonly id: string; readonly problem: ReachProblem }
  | { readonly rule: "model/human-only-unknown"; readonly id: string; readonly option: string };

What is wrong with a program's model.

modelProblemsfunction
function modelProblems(program: { readonly name: string; readonly summary: string; readonly children: readonly Node[]; }, options?: { readonly requireReach?: boolean | undefined; }): readonly ModelProblem[]

Everything wrong with a program's tree: what the terminal finds in its names (a duplicate, a bad name), what the governance finds in each action's facts, an option of a command named as one of the model's standard options, and a human-only option the command does not declare.

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

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