IF Commons GitHub

describe/describe

Written to: 11 requirements: 11 proved, 0 partly, 0 failing, 0 with no test recorded. 0015-describe FR-001, 0015-describe FR-002, 0015-describe FR-003, 0015-describe FR-004, 0015-describe FR-005, 0015-describe FR-006 and 5 more

A headless program as layered models (commons headless 0015-describe): describe(program) reads a Program and gives one LayeredModel of Kanon for each tier of its ladder, so that a documentation generator, a check or a diff can read what the program says without running it. Pure: values in, models out, no input or output.

The layers are those of Kanon. Governance holds the action of each verb (its kind, effect, idempotency, audience, tier, preview, check, human-only options and reach policy), the problem codes with their explanations and the exit statuses by name. The logical layer holds the program, the plugins that contributed verbs (from Program.origins), the verbs, their options (the command's own and those the model adds by its action's facts) and operands, with the examples and the problems of the model as findings. The physical layer holds what each surface draws for a caller of the tier: the command of a verb on the command line, its tool on a tool server, its route in the OpenAPI document. A verb the tier does not see has no projection, and the model says so: the dispositions of its annotations of tier and audience are unexpressed with the gate's own sentence, and its notProjected property lists each surface that does not draw it and why. Every annotation of every action ends in a disposition, so that droppedFindings of Kanon finds nothing.

import { branch, command, programOf } from "@intellectual-frontiers/headless/logical";
import { describe } from "@intellectual-frontiers/headless/describe";
const status = command({ name: "status", summary: "Show the status.", options: {}, action: { kind: "report" }, run: async () => ({}) as never });
const models = describe(programOf({ name: "tool", summary: "A tool.", version: "1.0.0", children: [branch({ name: "all", summary: "All.", children: [status] })] }));
models.map((m) => m.name); // ["tool-public", "tool-operator", "tool-administrator"]

Source: commons/headless/src/describe/describe.ts

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

Subjecttype
type Subject =
  | { readonly kind: "program" }
  | { readonly kind: "plugin"; readonly owner: string }
  | { readonly kind: "verb"; readonly path: readonly string[] }
  | { readonly kind: "problem-code"; readonly code: string }
  | { readonly kind: "outcome"; readonly name: string };

What a source location is asked for: the closed set of things a model says.

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

DescribeOptionstypeno test imports it
type DescribeOptions = {
  /** Where the subject is written (a file of the repository and a line): the caller's, since a value does not know where it was declared. */
  readonly locate?: (subject: Subject) => SourceLocation | undefined;
};

What describe may be given besides the program.

DescribeProblemtypeno test imports it
type DescribeProblem = { readonly rule: "describe/program-id"; readonly message: string };

Why no model could be made: the program's own id is not an id.

describeCheckedfunction
function describeChecked(program: Program, options?: DescribeOptions): Result<readonly LayeredModel[], readonly DescribeProblem[]>

The models of a program, one for each tier of its ladder, or why none can be made: the id of the program itself is not an id. An element whose own id cannot be made is left out and named by a finding of its model (describe/id).

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

describefunction
function describe(program: Program, options?: DescribeOptions): readonly LayeredModel[]

The layered models of a headless program, one for each tier of its ladder (lowest first), for a documentation generator to read: describe(program). None where the program's name cannot make an id (describeChecked says why).

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

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