logical.PLUGIN_CONTRACTconstno test imports itconst PLUGIN_CONTRACT: 1The version of the plugin contract, which a plugin states and a host checks.
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"logical.PLUGIN_CONTRACTconstno test imports itconst PLUGIN_CONTRACT: 1The version of the plugin contract, which a plugin states and a host checks.
logical.PluginIdtypeno test imports ittype 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 itfunction 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 itfunction 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 ittype 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 ittype 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 ittype 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 ittype 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 itfunction definePlugin(d: PluginDefinition): Result<Plugin, readonly PluginProblem[]>A plugin from its definition, or everything wrong with it.
logical.Ownertypeno test imports ittype Owner = { readonly kind: "host" } | { readonly kind: "plugin"; readonly id: PluginId };Who put a node in the tree.
logical.ownerNamefunctionno test imports itfunction ownerName(o: Owner, program: string): stringThe name of an owner as a sentence and as the run log writes it.
logical.ConflictKindtypeno test imports ittype ConflictKind = "claimed-twice" | "command-vs-branch" | "missing-parent" | "parent-is-command";Why two claims on the tree cannot both stand.
logical.Conflicttypeno test imports ittype 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 ittype 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 ittype 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 itfunction 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 itfunction 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 ittype 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 ittype 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 itconst CONFORMANCE_RULES: readonly ConformanceRule[]Every rule, in the order the suite runs them.
logical.ConformanceReporttypeno test imports ittype 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 itfunction pluginConformance(plugin: Plugin, host: Omit<ProgramConfig, "children">): ConformanceReportThe 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_CONTRACTconstconst PLUGIN_CONTRACT: 1The version of the plugin contract, which a plugin states and a host checks.
PluginIdtypeno test imports ittype 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.
parsePluginIdfunctionfunction 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.
parsePluginIdTextfunctionfunction parsePluginIdText(text: string): Result<PluginId, string>A plugin id from text that already is one (archon-server), for a requirement of another plugin.
Contributiontypeno test imports ittype 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).
Plugintypetype 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.
PluginDefinitiontypeno test imports ittype 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 ittype 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.
definePluginfunctionfunction definePlugin(d: PluginDefinition): Result<Plugin, readonly PluginProblem[]>A plugin from its definition, or everything wrong with it.
Ownertypeno test imports ittype Owner = { readonly kind: "host" } | { readonly kind: "plugin"; readonly id: PluginId };Who put a node in the tree.
ownerNamefunctionno test imports itfunction ownerName(o: Owner, program: string): stringThe name of an owner as a sentence and as the run log writes it.
ConflictKindtypeno test imports ittype ConflictKind = "claimed-twice" | "command-vs-branch" | "missing-parent" | "parent-is-command";Why two claims on the tree cannot both stand.
Conflicttypeno test imports ittype 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 ittype 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.
Composedtypetype 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.
composefunctionfunction 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.
verbIdsfunctionfunction 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.
ConformanceResulttypeno test imports ittype 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 ittype 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_RULESconstconst CONFORMANCE_RULES: readonly ConformanceRule[]Every rule, in the order the suite runs them.
ConformanceReporttypeno test imports ittype ConformanceReport = { readonly plugin: PluginId; readonly results: readonly ConformanceResult[]; readonly passed: boolean };What pluginConformance gives: a result for every rule, and whether all passed.
pluginConformancefunctionfunction pluginConformance(plugin: Plugin, host: Omit<ProgramConfig, "children">): ConformanceReportThe 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.