AgreedKindtypeno test imports ittype AgreedKind = (typeof PROGRAM_KINDS)[number] | (typeof PROJECTION_KINDS)[number];A kind of the agreed kinds.
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.
AgreedKindtypeno test imports ittype AgreedKind = (typeof PROGRAM_KINDS)[number] | (typeof PROJECTION_KINDS)[number];A kind of the agreed kinds.
Dispositiontypetype 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.
ElementIdtypetype 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.
LayeredModelinterfaceinterface LayeredModelThe layered model of a Kanon library.
| Member | Type | What it is |
|---|---|---|
name | string | Its name and the library it is of, as arca, data. |
library | string | |
title | string | |
summary | string | |
layers | readonly ModelLayer[] | The layers, from Governance down. |
elements | readonly ModelElement[] | |
trace | readonly TraceEdge[] | |
findings | readonly ModelFinding[] | |
dispositions | readonly Disposition[] | |
instances | readonly 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? | ModelVocabulary | What the host declares for the model (0033-kanon FR-028); where absent no kind and no name is checked. |
ModelElementinterfaceinterface ModelElementOne thing a layer says: an action, a verb, an option, a table, a command, a tool, a route.
| Member | Type | What it is |
|---|---|---|
id | ElementId | Stable 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. |
kind | string | |
name | string | |
definition | string | The words the model gives it; empty where it has none, which is a finding of the builder. |
parent? | ElementId | The element that holds it (an option's verb, a column's table). |
instance? | InstanceName | The 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). |
source | SourceLocation | |
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). |
ModelFindinginterfaceno test imports itinterface ModelFindingWhat a model's builder or a check found wrong.
| Member | Type | What it is |
|---|---|---|
rule | string | A rule's code, as kanon/dropped. |
element | ElementId | |
message | string |
ModelLayerinterfaceno test imports itinterface ModelLayerA layer of a model: what it is called, what it is for and the kinds of element it holds.
| Member | Type | What 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). |
title | string | |
summary | string | |
kinds | readonly string[] |
ModelVocabularyinterfaceno test imports itinterface ModelVocabularyWhat 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.
| Member | Type | What it is |
|---|---|---|
kinds | readonly { readonly layer: "governance" | "logical" | "physical"; readonly kinds: readonly string[]; }[] | |
relationKinds | readonly string[] | |
annotations | readonly string[] |
Relationinterfaceinterface RelationA 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).
| Member | Type | What it is |
|---|---|---|
from | ElementId | |
to | ElementId | |
kind | string |
SourceLocationinterfaceno test imports itinterface SourceLocationWhere an element is written: a file of the repository and the line where it is declared.
| Member | Type | What it is |
|---|---|---|
file | string | |
line | number |
TraceEdgeinterfaceno test imports itinterface TraceEdgeAn element of one layer made into an element of the layer below it.
| Member | Type | What it is |
|---|---|---|
from | ElementId | |
to | ElementId | |
how | string | How: projects to, written as, read by. |
cliIdconstconst cliId: (program: string, verbPath: string) => Result<ElementId, string>The id of the command of a verb on the command line.
headlessIdconstconst headlessId: (program: string, verbPath: string) => Result<ElementId, string>The id of a verb of a headless program.
mcpIdconstconst mcpId: (toolName: string) => Result<ElementId, string>The id of the tool of a verb on a tool server.
operandIdconstconst 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.
optionIdconstconst 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.
parseElementIdfunctionfunction 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.
PROGRAM_KINDSconstconst PROGRAM_KINDS: readonly ["action", "verb", "option", "operand", "problem-code", "outcome"]The kinds of element that a program says (0033-kanon FR-013).
PROJECTION_KINDSconstconst PROJECTION_KINDS: readonly ["cli-command", "mcp-tool", "rest-route"]The kinds of element that a surface projects them into.
restIdconstconst restId: (method: string, path: string) => Result<ElementId, string>The id of the route of a verb on a REST surface.