IF Commons GitHub

describe/ids

Written to: 2 requirements: 2 proved, 0 partly, 0 failing, 0 with no test recorded. 0015-describe FR-002, 0015-describe FR-003

The vocabulary of a described program (commons headless 0015-describe FR-002, FR-003): the closed union of the kinds of element a model of Headless holds, the layer each kind is in, and the smart constructors of the id of each kind. Every id is an ElementId of Kanon, made only by a constructor that returns a Result, so that an element is never given a text that is not an id.

The kinds agreed with the data library are action, verb, option, operand, problem-code and outcome for what a program says, and cli-command, mcp-tool and rest-route for what a surface projects it into; Headless adds program and plugin (who contributes a verb) and openapi-document (the document of a REST surface, which holds its routes). The ids of the agreed kinds are headless:<program>/<verb path>, cli:<program> <verb path>, mcp:<tool name>, rest:<METHOD> <path>, and <verb id>#--flag or <verb id>#<operand>; the others are action:<program>/<verb path>, problem-code:<program>/<code>, outcome:<program>/<exit name>, plugin:<owner> and openapi:<program>.

import { verbIdOf } from "./ids.ts";
verbIdOf("tool", ["repos", "add"]).kind; // "ok"

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

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

KINDSconst
const KINDS: readonly ["action", "problem-code", "outcome", "program", "plugin", "verb", "option", "operand", "cli-command", "mcp-tool", "rest-route", "openapi-document"]

The kinds of element of a described program: a closed union.

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

layerOffunction
function layerOf(kind: "action" | "cli-command" | "mcp-tool" | "openapi-document" | "operand" | "option" | "outcome" | "plugin" | "problem-code" | "program" | "rest-route" | "verb"): "governance" | "logical" | "physical"

The layer a kind of element is in: governance says what an action is and may do, the logical layer is the program's own tree, and the surfaces are the physical layer.

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

kindsOffunctionno test imports it
function kindsOf(layer: "governance" | "logical" | "physical"): readonly ("action" | "cli-command" | "mcp-tool" | "openapi-document" | "operand" | "option" | "outcome" | "plugin" | "problem-code" | "program" | "rest-route" | "verb")[]

The kinds of each layer, in the order of KINDS.

programIdOfconstno test imports it
const programIdOf: (program: string) => Result<ElementId, string>

The id of the program.

pluginIdOfconstno test imports it
const pluginIdOf: (owner: string) => Result<ElementId, string>

The id of the plugin that contributes verbs (the owner's name, <program>-<noun>).

actionIdOfconstno test imports it
const actionIdOf: (program: string, words: readonly string[]) => Result<ElementId, string>

The id of the action of a verb, in governance.

verbIdOfconstno test imports it
const verbIdOf: (program: string, words: readonly string[]) => Result<ElementId, string>

The id of a verb.

cliIdOfconstno test imports it
const cliIdOf: (program: string, words: readonly string[]) => Result<ElementId, string>

The id of the command of a verb on the command line.

mcpIdOfconstno test imports it
const mcpIdOf: (toolName: string) => Result<ElementId, string>

The id of the tool of a verb.

restIdOfconstno test imports it
const restIdOf: (method: "GET" | "POST", path: string) => Result<ElementId, string>

The id of a route.

documentIdOfconstno test imports it
const documentIdOf: (program: string) => Result<ElementId, string>

The id of the OpenAPI document of the program.

codeIdOfconstno test imports it
const codeIdOf: (program: string, code: string) => Result<ElementId, string>

The id of a code of the program's catalogue.

exitIdOfconstno test imports it
const exitIdOf: (program: string, name: string) => Result<ElementId, string>

The id of an exit status, by its name.

optionIdOfconstno test imports it
const optionIdOf: (verb: ElementId, flag: string) => Result<ElementId, string>

The id of an option of a verb, by its flag (--force).

operandIdOfconstno test imports it
const operandIdOf: (verb: ElementId, name: string) => Result<ElementId, string>

The id of an operand of a verb.

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