IF Commons GitHub

logical/compose

Written to: 7 requirements: 7 proved, 0 partly, 0 failing, 0 with no test recorded. 0009-composition FR-001, 0009-composition FR-002, 0009-composition FR-003, 0009-composition FR-004, 0009-composition FR-005, 0009-composition FR-006 and 1 more

One program tree built from the branches that several packages contribute (commons headless 0009-composition): a host program (the composition root of a fleet or an application) and plugin packages named <program>-<noun>, each of which contributes nodes only through the value it exports (Plugin, made by definePlugin). compose gives one Program, so that there is one help, one completion script, one man page, one run log and one tier gate for the whole command; where two plugins claim one verb it gives the conflict as a value, never a throw and never a silent winner.

Pure and deterministic: the plugins are placed in the order of their ids, so the tree does not depend on the order in which a program imports its packages. A plugin may place a node at the root only under its own noun (archon-server contributes server), and below another branch (at) where that branch exists; two contributions of the same branch name merge, and the same verb claimed twice is a conflict. A plugin names the plugins it needs, and a missing one is an error. The tier of every command MUST be on the host's ladder: the one gate.

import { branch, command, compose, definePlugin } from "./mod.ts";
const run = async () => ({}) as never;
const list = command({ name: "list", summary: "List.", options: {}, action: { kind: "report" }, run });
const plugin = definePlugin({ program: "tool", noun: "server", version: "1.0.0", summary: "Servers.", contributes: [{ node: branch({ name: "server", summary: "Servers.", children: [list] }) }] });
plugin.kind; // "ok"

Source: commons/headless/src/logical/compose.ts

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

logical.PLUGIN_CONTRACTconstno test imports it
const PLUGIN_CONTRACT: 1

The version of the plugin contract, which a plugin states and a host checks.

logical.PluginIdtypeno test imports it
type PluginId = Brand<string, "plugin id">;

The stable identity of a plugin: the program's name, a hyphen and the noun (archon-server). Made only by parsePluginId.

logical.parsePluginIdfunctionno test imports it
function parsePluginId(program: string, noun: string): Result<PluginId, string>

The id of the plugin of a program for a noun, or why the parts are not one: the one way a PluginId is made.

logical.parsePluginIdTextfunctionno test imports it
function parsePluginIdText(text: string): Result<PluginId, string>

A plugin id from text that already is one (archon-server), for a requirement of another plugin.

logical.Contributiontypeno test imports it
type Contribution = { readonly at: readonly string[]; readonly node: Node };

One thing a plugin contributes: a node, and the path of the branch it is placed in (empty: the root of the program).

logical.Plugintypeno test imports it
type Plugin = {
  readonly contract: number;
  readonly id: PluginId;
  /** The program it extends. */
  readonly program: string;
  readonly noun: string;
  readonly version: string;
  readonly summary: string;
  readonly contributes: readonly Contribution[];
  /** The plugins that must be composed with it. */
  readonly requires: readonly PluginId[];
};

What a package exports to extend a program: its identity, the contract it was written for, and the nodes it contributes.

logical.PluginDefinitiontypeno test imports it
type PluginDefinition = {
  readonly program: string;
  readonly noun: string;
  readonly version: string;
  readonly summary: string;
  readonly contributes: readonly { readonly at?: readonly string[]; readonly node: Node }[];
  readonly requires?: readonly string[];
};

What definePlugin takes.

logical.PluginProblemtypeno test imports it
type PluginProblem = | { readonly rule: "plugin/id"; readonly message: string } | { readonly rule: "plugin/version";… (437 characters)
type PluginProblem =
  | { readonly rule: "plugin/id"; readonly message: string }
  | { readonly rule: "plugin/version"; readonly message: string }
  | { readonly rule: "plugin/summary"; readonly message: string }
  | { readonly rule: "plugin/empty"; readonly message: string }
  | { readonly rule: "plugin/root-claim"; readonly word: string; readonly message: string }
  | { readonly rule: "plugin/requires"; readonly message: string };

What is wrong with a plugin's definition.

logical.definePluginfunctionno test imports it
function definePlugin(d: PluginDefinition): Result<Plugin, readonly PluginProblem[]>

A plugin from its definition, or everything wrong with it.

logical.Ownertypeno test imports it
type Owner = { readonly kind: "host" } | { readonly kind: "plugin"; readonly id: PluginId };

Who put a node in the tree.

logical.ownerNamefunctionno test imports it
function ownerName(o: Owner, program: string): string

The name of an owner as a sentence and as the run log writes it.

logical.ConflictKindtypeno test imports it
type ConflictKind = "claimed-twice" | "command-vs-branch" | "missing-parent" | "parent-is-command";

Why two claims on the tree cannot both stand.

logical.Conflicttypeno test imports it
type Conflict = { readonly kind: ConflictKind; readonly path: readonly string[]; readonly owners: readonly Owner[] };

A conflict between claims: the path claimed and who claimed it (the first owner, then the one that came after).

logical.CompositionErrortypeno test imports it
type CompositionError = | { readonly kind: "duplicate-plugin"; readonly id: PluginId } | { readonly kind: "wrong-pro… (634 characters)
type CompositionError =
  | { readonly kind: "duplicate-plugin"; readonly id: PluginId }
  | { readonly kind: "wrong-program"; readonly id: PluginId; readonly expected: string; readonly found: string }
  | { readonly kind: "contract"; readonly id: PluginId; readonly expected: number; readonly found: number }
  | { readonly kind: "missing-requirement"; readonly id: PluginId; readonly requires: PluginId }
  | { readonly kind: "conflict"; readonly conflict: Conflict }
  | { readonly kind: "tier-not-on-ladder"; readonly path: readonly string[]; readonly tier: string }
  | { readonly kind: "model"; readonly problem: ModelProblem };

What can stop a composition.

logical.Composedtypeno test imports it
type Composed = {
  readonly program: Program;
  readonly plugins: readonly PluginId[];
  /** The owner of each command, by the words of its id (`server list`). */
  readonly owners: Readonly<Record<string, Owner>>;
};

The composed program: the one Program, who owns each command, and the plugins that are in it.

logical.composefunctionno test imports it
function compose(host: ProgramConfig, plugins: readonly Plugin[]): Result<Composed, readonly CompositionError[]>

What compose gives: the host's children are first, then each plugin's in the order of the plugin ids.

logical.verbIdsfunctionno test imports it
function verbIds(program: Program): readonly string[]

The stable identifiers of the verbs of a program: the words of each command below the program's name, sorted, as archon server list. A plugin's test holds them in a snapshot.

logical.ConformanceResulttypeno test imports it
type ConformanceResult = { readonly rule: ConformanceRule; readonly passed: boolean; readonly messages: readonly string[] };

One rule of the conformance suite and whether the plugin passes it.

logical.ConformanceRuletypeno test imports it
type ConformanceRule =
  | "conformance/definition"
  | "conformance/contract"
  | "conformance/program"
  | "conformance/root-claim"
  | "conformance/composes"
  | "conformance/tiers"
  | "conformance/reach"
  | "conformance/deterministic"
  | "conformance/ids";

The rules of the conformance suite a plugin runs, each a named case.

logical.CONFORMANCE_RULESconstno test imports it
const CONFORMANCE_RULES: readonly ConformanceRule[]

Every rule, in the order the suite runs them.

logical.ConformanceReporttypeno test imports it
type ConformanceReport = { readonly plugin: PluginId; readonly results: readonly ConformanceResult[]; readonly passed: boolean };

What pluginConformance gives: a result for every rule, and whether all passed.

logical.pluginConformancefunctionno test imports it
function pluginConformance(plugin: Plugin, host: Omit<ProgramConfig, "children">): ConformanceReport

The conformance suite of a plugin, pure: the plugin composed alone with a host that declares nothing but its name and ladder must give a tree (the host is given with no children of its own, so that nothing but the plugin is judged), and the result is judged by rule. A plugin's own test runs it and asserts passed, which is what a host relies on before it composes the plugin with others.

PLUGIN_CONTRACTconst
const PLUGIN_CONTRACT: 1

The version of the plugin contract, which a plugin states and a host checks.

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

PluginIdtypeno test imports it
type PluginId = Brand<string, "plugin id">;

The stable identity of a plugin: the program's name, a hyphen and the noun (archon-server). Made only by parsePluginId.

parsePluginIdfunction
function parsePluginId(program: string, noun: string): Result<PluginId, string>

The id of the plugin of a program for a noun, or why the parts are not one: the one way a PluginId is made.

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

parsePluginIdTextfunction
function parsePluginIdText(text: string): Result<PluginId, string>

A plugin id from text that already is one (archon-server), for a requirement of another plugin.

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

Contributiontypeno test imports it
type Contribution = { readonly at: readonly string[]; readonly node: Node };

One thing a plugin contributes: a node, and the path of the branch it is placed in (empty: the root of the program).

Plugintype
type Plugin = {
  readonly contract: number;
  readonly id: PluginId;
  /** The program it extends. */
  readonly program: string;
  readonly noun: string;
  readonly version: string;
  readonly summary: string;
  readonly contributes: readonly Contribution[];
  /** The plugins that must be composed with it. */
  readonly requires: readonly PluginId[];
};

What a package exports to extend a program: its identity, the contract it was written for, and the nodes it contributes.

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

PluginDefinitiontypeno test imports it
type PluginDefinition = {
  readonly program: string;
  readonly noun: string;
  readonly version: string;
  readonly summary: string;
  readonly contributes: readonly { readonly at?: readonly string[]; readonly node: Node }[];
  readonly requires?: readonly string[];
};

What definePlugin takes.

PluginProblemtypeno test imports it
type PluginProblem = | { readonly rule: "plugin/id"; readonly message: string } | { readonly rule: "plugin/version";… (437 characters)
type PluginProblem =
  | { readonly rule: "plugin/id"; readonly message: string }
  | { readonly rule: "plugin/version"; readonly message: string }
  | { readonly rule: "plugin/summary"; readonly message: string }
  | { readonly rule: "plugin/empty"; readonly message: string }
  | { readonly rule: "plugin/root-claim"; readonly word: string; readonly message: string }
  | { readonly rule: "plugin/requires"; readonly message: string };

What is wrong with a plugin's definition.

definePluginfunction
function definePlugin(d: PluginDefinition): Result<Plugin, readonly PluginProblem[]>

A plugin from its definition, or everything wrong with it.

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

Ownertypeno test imports it
type Owner = { readonly kind: "host" } | { readonly kind: "plugin"; readonly id: PluginId };

Who put a node in the tree.

ownerNamefunctionno test imports it
function ownerName(o: Owner, program: string): string

The name of an owner as a sentence and as the run log writes it.

ConflictKindtypeno test imports it
type ConflictKind = "claimed-twice" | "command-vs-branch" | "missing-parent" | "parent-is-command";

Why two claims on the tree cannot both stand.

Conflicttypeno test imports it
type Conflict = { readonly kind: ConflictKind; readonly path: readonly string[]; readonly owners: readonly Owner[] };

A conflict between claims: the path claimed and who claimed it (the first owner, then the one that came after).

CompositionErrortypeno test imports it
type CompositionError = | { readonly kind: "duplicate-plugin"; readonly id: PluginId } | { readonly kind: "wrong-pro… (634 characters)
type CompositionError =
  | { readonly kind: "duplicate-plugin"; readonly id: PluginId }
  | { readonly kind: "wrong-program"; readonly id: PluginId; readonly expected: string; readonly found: string }
  | { readonly kind: "contract"; readonly id: PluginId; readonly expected: number; readonly found: number }
  | { readonly kind: "missing-requirement"; readonly id: PluginId; readonly requires: PluginId }
  | { readonly kind: "conflict"; readonly conflict: Conflict }
  | { readonly kind: "tier-not-on-ladder"; readonly path: readonly string[]; readonly tier: string }
  | { readonly kind: "model"; readonly problem: ModelProblem };

What can stop a composition.

Composedtype
type Composed = {
  readonly program: Program;
  readonly plugins: readonly PluginId[];
  /** The owner of each command, by the words of its id (`server list`). */
  readonly owners: Readonly<Record<string, Owner>>;
};

The composed program: the one Program, who owns each command, and the plugins that are in it.

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

composefunction
function compose(host: ProgramConfig, plugins: readonly Plugin[]): Result<Composed, readonly CompositionError[]>

What compose gives: the host's children are first, then each plugin's in the order of the plugin ids.

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

verbIdsfunction
function verbIds(program: Program): readonly string[]

The stable identifiers of the verbs of a program: the words of each command below the program's name, sorted, as archon server list. A plugin's test holds them in a snapshot.

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

ConformanceResulttypeno test imports it
type ConformanceResult = { readonly rule: ConformanceRule; readonly passed: boolean; readonly messages: readonly string[] };

One rule of the conformance suite and whether the plugin passes it.

ConformanceRuletypeno test imports it
type ConformanceRule =
  | "conformance/definition"
  | "conformance/contract"
  | "conformance/program"
  | "conformance/root-claim"
  | "conformance/composes"
  | "conformance/tiers"
  | "conformance/reach"
  | "conformance/deterministic"
  | "conformance/ids";

The rules of the conformance suite a plugin runs, each a named case.

CONFORMANCE_RULESconst
const CONFORMANCE_RULES: readonly ConformanceRule[]

Every rule, in the order the suite runs them.

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

ConformanceReporttypeno test imports it
type ConformanceReport = { readonly plugin: PluginId; readonly results: readonly ConformanceResult[]; readonly passed: boolean };

What pluginConformance gives: a result for every rule, and whether all passed.

pluginConformancefunction
function pluginConformance(plugin: Plugin, host: Omit<ProgramConfig, "children">): ConformanceReport

The conformance suite of a plugin, pure: the plugin composed alone with a host that declares nothing but its name and ladder must give a tree (the host is given with no children of its own, so that nothing but the plugin is judged), and the result is judged by rule. A plugin's own test runs it and asserts passed, which is what a host relies on before it composes the plugin with others.

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

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