IF Commons GitHub

model

Written to: 2 requirements: 2 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-kanon-checker FR-006, 0001-kanon-checker FR-001

The layered model of a Kanon library (commons 0033-kanon FR-013): what a library that is built in layers gives to be documented, checked and traced, as types and the names of its kinds and the builders of its ids, and no code that a program runs beyond them. It is the shape of the layered model of the documentation generator (commons/docs, 0011-documentation FR-029): the layers, the elements of each, the trace edges between them and the findings, so that the generator reads a LayeredModel of Kanon as its own; it adds dispositions, the account of each annotation of Governance (0033-kanon FR-005).

The kinds are those agreed by Data and Headless: action, verb, option, operand, problem-code and outcome for what a program says, and the projections cli-command, mcp-tool and rest-route. The ids are headless:<program>/<verb-path>, cli:<program> <verb path>, mcp:<tool_name> and rest:<METHOD> <path>; an option or an operand is its verb's id, a # and --flag or the operand's name.

Algebraic types throughout: an ElementId is a branded string made only by parseElementId (parse, don't validate), a layer is the closed union Layer, a Disposition is a sum with one case for each way an annotation can end, everything is readonly, and an id builder returns a Result where its parts can be wrong.

Source: commons/kanon/src/model.ts

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

AgreedKindtypeno test imports it
type AgreedKind = (typeof PROGRAM_KINDS)[number] | (typeof PROJECTION_KINDS)[number];

A kind of the agreed kinds.

Dispositiontype
type Disposition =
  | (DispositionBase & { readonly outcome: "expressed"; readonly target: ElementId })
  | (DispositionBase & { readonly outcome: "carried"; readonly target: ElementId })
  | (DispositionBase & { readonly outcome: "unexpressed"; readonly reason: string });

How an annotation of Governance ends (0033-kanon FR-005, FR-022): expressed by a lower element, carried as data of one, or named as unexpressed with the reason. A sum with one case for each way, which a model gives for each instance, or once for all of them.

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

ElementIdtype
type ElementId = Brand<string, "kanon element id">;

The identity of an element, stable across builds: a scheme, a colon and what names it (headless:arcactl/db migrate). Made only by parseElementId.

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

LayeredModelinterface
interface LayeredModel

The layered model of a Kanon library.

MemberTypeWhat it is
namestringIts name and the library it is of, as arca, data.
librarystring
titlestring
summarystring
layersreadonly ModelLayer[]The layers, from Governance down.
elementsreadonly ModelElement[]
tracereadonly TraceEdge[]
findingsreadonly ModelFinding[]
dispositionsreadonly Disposition[]
instancesreadonly InstanceName[]The instances (dialects) the model has, each of which every annotation of Governance is accounted for (0033-kanon FR-022); none where the model has no instances of a unit kind.
relations?readonly Relation[]The links between elements of one layer (0033-kanon FR-029); none where the model has none.
vocabulary?ModelVocabularyWhat the host declares for the model (0033-kanon FR-028); where absent no kind and no name is checked.

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

ModelElementinterface
interface ModelElement

One thing a layer says: an action, a verb, an option, a table, a command, a tool, a route.

MemberTypeWhat it is
idElementIdStable across builds (0033-kanon FR-003): the key of a link, a trace edge and a diff.
layer"governance" | "logical" | "physical"The layer it is in.
kindstring
namestring
definitionstringThe words the model gives it; empty where it has none, which is a finding of the builder.
parent?ElementIdThe element that holds it (an option's verb, a column's table).
instance?InstanceNameThe instance (a dialect) of a unit kind that it belongs to, for an element of a physical layer that is one instance's (0033-kanon FR-019).
sourceSourceLocation
properties{ readonly [name: string]: string | number | boolean | readonly string[] | null; }What is said of it, by name: for an element of Governance, each property is an annotation that must end expressed, carried or unexpressed (dispositions).

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

ModelFindinginterfaceno test imports it
interface ModelFinding

What a model's builder or a check found wrong.

MemberTypeWhat it is
rulestringA rule's code, as kanon/dropped.
elementElementId
messagestring
ModelLayerinterfaceno test imports it
interface ModelLayer

A layer of a model: what it is called, what it is for and the kinds of element it holds.

MemberTypeWhat it is
id"governance" | "logical" | "physical"Its name: governance, logical or physical (a library's own words for a surface or a dialect are kinds of its Physical layer).
titlestring
summarystring
kindsreadonly string[]
ModelVocabularyinterfaceno test imports it
interface ModelVocabulary

What a host declares for its model (0033-kanon FR-028): the kinds of element of each layer, the kinds of relation and the names of the annotations of Governance.

MemberTypeWhat it is
kindsreadonly { readonly layer: "governance" | "logical" | "physical"; readonly kinds: readonly string[]; }[]
relationKindsreadonly string[]
annotationsreadonly string[]
Relationinterface
interface Relation

A link between two elements of one layer, with a kind of the model's vocabulary: it may be cyclic and is never a trace edge (0033-kanon FR-029).

MemberTypeWhat it is
fromElementId
toElementId
kindstring

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

SourceLocationinterfaceno test imports it
interface SourceLocation

Where an element is written: a file of the repository and the line where it is declared.

MemberTypeWhat it is
filestring
linenumber
TraceEdgeinterfaceno test imports it
interface TraceEdge

An element of one layer made into an element of the layer below it.

MemberTypeWhat it is
fromElementId
toElementId
howstringHow: projects to, written as, read by.
cliIdconst
const cliId: (program: string, verbPath: string) => Result<ElementId, string>

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

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

headlessIdconst
const headlessId: (program: string, verbPath: string) => Result<ElementId, string>

The id of a verb of a headless program.

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

mcpIdconst
const mcpId: (toolName: string) => Result<ElementId, string>

The id of the tool of a verb on a tool server.

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

operandIdconst
const operandId: (verb: ElementId, operand: string) => Result<ElementId, string>

The id of an operand of a verb: the verb's id, a # and the operand's name.

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

optionIdconst
const optionId: (verb: ElementId, flag: string) => Result<ElementId, string>

The id of an option of a verb: the verb's id, a # and the flag, as --force.

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

parseElementIdfunction
function parseElementId(text: string): Result<ElementId, string>

An element id from text, or why the text is not one: the one way an ElementId is made.

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

PROGRAM_KINDSconst
const PROGRAM_KINDS: readonly ["action", "verb", "option", "operand", "problem-code", "outcome"]

The kinds of element that a program says (0033-kanon FR-013).

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

PROJECTION_KINDSconst
const PROJECTION_KINDS: readonly ["cli-command", "mcp-tool", "rest-route"]

The kinds of element that a surface projects them into.

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

restIdconst
const restId: (method: string, path: string) => Result<ElementId, string>

The id of the route of a verb on a REST surface.

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

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