IF Commons GitHub

physical/define

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0006-repoctl-surfaces FR-001

How a verb of repoctl is declared on Headless (commons repoctl 0006-repoctl-surfaces FR-001, FR-004; commons headless 0003-headless-output, 0004-headless-cli): a verb is declared once with its words, options, operands and examples, and its action's traits come from the facts table of Governance (VERBS), so that what the command line, the tool server and the documentation say of it is one fact. The body returns the findings and the data of the run; this turns them into Headless' outcome, with the code and the fix of each finding as the problem it is.

import { traitsOf } from "@intellectual-frontiers/repoctl/physical";
traitsOf("release publish").reach?.confirmation; // "person"

Source: commons/repoctl/src/physical/define.ts

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

physical.Hosttypeno test imports it
type Host = { readonly env: (name: string) => string | undefined; readonly world: () => Result<World, string>; /**… (751 characters)
type Host = {
  readonly env: (name: string) => string | undefined;
  readonly world: () => Result<World, string>;
  /** The repository's configuration, read and checked: everything the verbs know of it. Where there is none (or it is wrong) it is the bare one and `configProblem` says why. */
  readonly config: Config;
  /** Why the configuration could not be had: a verb that needs it ends with this, and `doctor` reports it. */
  readonly configProblem?: { readonly code: "E-CONFIG-MISSING" | "E-CONFIG-LOAD" | "E-CONFIG-INVALID"; readonly message: string };
  /** What `release apply` runs besides the planner (the generators of the release and the tests that pack): the real ones where it is not given. */
  readonly releasing?: ReleasingHost;
};

What the program holds for every run of its verbs: the environment, and the world, made where it is needed (it needs the repository's root, which a documentation lens has not got).

physical.generatorsOffunctionno test imports it
function generatorsOf(host: Host): readonly Generator[]

The generators a host runs: those of the configuration, in the order it declared them.

physical.Maketypeno test imports it
type Make = (host: Host) => Command;

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

physical.traitsOffunctionno test imports it
function traitsOf(id: VerbId): ActionTraits

The traits of a verb as an action: its facts and its reach, from the one table.

physical.problemOffunctionno test imports it
function problemOf(f: Finding): Problem

A finding as the problem of a run: its level, its code and the fix.

physical.Donetypeno test imports it
type Done = {
  readonly data: unknown;
  readonly text: string;
  readonly findings: readonly Finding[];
  readonly next?: readonly string[];
  readonly title?: string;
};

What a verb's body gives: the data (what --json carries), the text for a person, the findings, and what to run next.

physical.outcomeOfDonefunctionno test imports it
function outcomeOfDone(d: Done): Outcome

A run that ends well or with its findings.

physical.outcomeOfEnvironmentfunctionno test imports it
function outcomeOfEnvironment(message: string): Outcome

A run that could not be made: the checkout is not found, or the host cannot do it.

physical.outcomeOfConfigfunctionno test imports it
function outcomeOfConfig(p: { readonly code: "E-CONFIG-INVALID" | "E-CONFIG-LOAD" | "E-CONFIG-MISSING"; readonly message: string; }): Outcome

A run that cannot be made because the repository has no usable configuration.

physical.outcomeOfUsagefunctionno test imports it
function outcomeOfUsage(message: string, code?: "E-COMMIT-IMPACT" | "E-COMMIT-REFS" | "E-COMMIT-SESSION" | "E-COMMIT-SUBJECT" | "E-LIBRARY-NAME" | "E-USAGE", fix?: string): Outcome

A run whose command line does not fit what the verb takes.

physical.VerbDefinitiontypeno test imports it
type VerbDefinition<S extends Spec> = { readonly name: string; readonly id: VerbId; readonly options: S & SpecChec… (492 characters)
type VerbDefinition<S extends Spec> = {
  readonly name: string;
  readonly id: VerbId;
  readonly options: S & SpecCheck<S>;
  readonly operands?: readonly Operand[];
  readonly examples: readonly Example[];
  readonly run: (args: Args<S>, ctx: Context, world: World, host: Host) => Promise<Outcome>;
  /** Whether the verb is run only where the repository has a valid configuration (the default); `doctor` is not, since it is what says there is none. */
  readonly needsConfig?: boolean;
};

What a verb is declared with.

physical.defineVerbfunctionno test imports it
function defineVerb<S extends Spec>(d: VerbDefinition<S>): Make

A verb from its declaration: its summary and traits are the table's, and its body runs in the world of the host, or ends with the sentence that says the checkout was not found.

Hosttypeno test imports it
type Host = { readonly env: (name: string) => string | undefined; readonly world: () => Result<World, string>; /**… (751 characters)
type Host = {
  readonly env: (name: string) => string | undefined;
  readonly world: () => Result<World, string>;
  /** The repository's configuration, read and checked: everything the verbs know of it. Where there is none (or it is wrong) it is the bare one and `configProblem` says why. */
  readonly config: Config;
  /** Why the configuration could not be had: a verb that needs it ends with this, and `doctor` reports it. */
  readonly configProblem?: { readonly code: "E-CONFIG-MISSING" | "E-CONFIG-LOAD" | "E-CONFIG-INVALID"; readonly message: string };
  /** What `release apply` runs besides the planner (the generators of the release and the tests that pack): the real ones where it is not given. */
  readonly releasing?: ReleasingHost;
};

What the program holds for every run of its verbs: the environment, and the world, made where it is needed (it needs the repository's root, which a documentation lens has not got).

generatorsOffunctionno test imports it
function generatorsOf(host: Host): readonly Generator[]

The generators a host runs: those of the configuration, in the order it declared them.

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

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

traitsOffunction
function traitsOf(id: VerbId): ActionTraits

The traits of a verb as an action: its facts and its reach, from the one table.

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

problemOffunctionno test imports it
function problemOf(f: Finding): Problem

A finding as the problem of a run: its level, its code and the fix.

Donetypeno test imports it
type Done = {
  readonly data: unknown;
  readonly text: string;
  readonly findings: readonly Finding[];
  readonly next?: readonly string[];
  readonly title?: string;
};

What a verb's body gives: the data (what --json carries), the text for a person, the findings, and what to run next.

outcomeOfDonefunctionno test imports it
function outcomeOfDone(d: Done): Outcome

A run that ends well or with its findings.

outcomeOfEnvironmentfunctionno test imports it
function outcomeOfEnvironment(message: string): Outcome

A run that could not be made: the checkout is not found, or the host cannot do it.

outcomeOfConfigfunctionno test imports it
function outcomeOfConfig(p: { readonly code: "E-CONFIG-INVALID" | "E-CONFIG-LOAD" | "E-CONFIG-MISSING"; readonly message: string; }): Outcome

A run that cannot be made because the repository has no usable configuration.

outcomeOfUsagefunctionno test imports it
function outcomeOfUsage(message: string, code?: "E-COMMIT-IMPACT" | "E-COMMIT-REFS" | "E-COMMIT-SESSION" | "E-COMMIT-SUBJECT" | "E-LIBRARY-NAME" | "E-USAGE", fix?: string): Outcome

A run whose command line does not fit what the verb takes.

VerbDefinitiontypeno test imports it
type VerbDefinition<S extends Spec> = { readonly name: string; readonly id: VerbId; readonly options: S & SpecChec… (492 characters)
type VerbDefinition<S extends Spec> = {
  readonly name: string;
  readonly id: VerbId;
  readonly options: S & SpecCheck<S>;
  readonly operands?: readonly Operand[];
  readonly examples: readonly Example[];
  readonly run: (args: Args<S>, ctx: Context, world: World, host: Host) => Promise<Outcome>;
  /** Whether the verb is run only where the repository has a valid configuration (the default); `doctor` is not, since it is what says there is none. */
  readonly needsConfig?: boolean;
};

What a verb is declared with.

defineVerbfunctionno test imports it
function defineVerb<S extends Spec>(d: VerbDefinition<S>): Make

A verb from its declaration: its summary and traits are the table's, and its body runs in the world of the host, or ends with the sentence that says the checkout was not found.

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