@loomcli/core 0.5.0 → 0.7.0

package/dist/input-rules.js

@@ -0,0 +1,152 @@
+import { registerRule } from './diagnostic-text.js';
+/*
+ * Core's rules for the declaration faults of arguments, options, validators, defaults, global
+ * options, and environment bindings. Each is declared once here and shared by every site that
+ * raises it, as a plugin's rules are.
+ */
+/** An option declared with a type other than string or Boolean. */
+const optionType = registerRule('@loomcli/core/option-type', {
+    explanation: 'The type decides how the parser reads an option: a string option consumes a value, and a Boolean option consumes none. Core reads no other kind.',
+    headline: 'Invalid option type',
+});
+/** A short alias that is not one ASCII letter. */
+const shortAlias = registerRule('@loomcli/core/short-alias', {
+    explanation: 'An operator types a short alias as a hyphen and one letter, and several combine into one short group such as -tm, so each is one ASCII letter the parser can split apart.',
+    headline: 'Invalid short alias',
+});
+/**
+ * A yes-or-no declaration key, such as `required`, `hidden`, or an extension descriptor's
+ * `collect`, that holds a value other than a Boolean.
+ */
+const flagNotBoolean = registerRule('@loomcli/core/flag-not-boolean', {
+    explanation: 'hidden, shortOnly, multiple, required, variadic, validateOmitted, and an extension\'s collect each answer one yes-or-no question about a declaration, so each holds true or false. A value such as the string "false" would read as true.',
+    headline: 'Flag not a Boolean',
+});
+/** `shortOnly` on an option that declares no short alias. */
+const shortOnlyWithoutShort = registerRule('@loomcli/core/short-only-without-short', {
+    explanation: 'shortOnly removes every long spelling of an option, so an option with no short alias would leave an operator no spelling to type.',
+    headline: 'Short only with no short alias',
+});
+/** `multiple` on a Boolean option. */
+const booleanOptionMultiple = registerRule('@loomcli/core/boolean-option-multiple', {
+    explanation: 'A Boolean option reports whether its spelling was supplied, so a repeat has no second value to collect. multiple collects each occurrence of a string option into an array.',
+    headline: 'Boolean option takes one value',
+});
+/** `polarity` on a string option. */
+const polarityOnString = registerRule('@loomcli/core/polarity-on-string', {
+    explanation: 'Polarity chooses which long forms a Boolean option accepts and what its absence means. A string option takes its value from the operator, so it has no polarity.',
+    headline: 'Polarity on a string option',
+});
+/** A polarity outside the three settings. */
+const optionPolarity = registerRule('@loomcli/core/option-polarity', {
+    explanation: "Polarity chooses a Boolean option's long forms and its absent value from three settings: positive, both, and negative.",
+    headline: 'Invalid polarity',
+});
+/** `polarity: 'both'` beside `shortOnly`. */
+const shortOnlyBothPolarities = registerRule('@loomcli/core/short-only-both-polarities', {
+    explanation: 'Polarity both gives an option one spelling that turns it on and one that turns it off. shortOnly leaves the option its short alias alone, and one spelling sets one value.',
+    headline: 'Both polarities with short only',
+});
+/**
+ * One spelling that two options in one scope claim, the application's, a plugin's, or one a
+ * plugin's hook declared.
+ */
+const spellingTaken = registerRule('@loomcli/core/spelling-taken', {
+    explanation: "The parser reads each spelling as one option, and a Command's own options share one invocation with the global options and every installed plugin's options. A spelling two options claim, a short alias or a generated negative form included, would reach only one of them.",
+    headline: 'Spelling used twice',
+});
+/**
+ * Two options with one declared name in one scope, the application's, a plugin's, or one a
+ * plugin's hook declared.
+ */
+const optionDeclaredTwice = registerRule('@loomcli/core/option-declared-twice', {
+    explanation: "An action reads the global options and its Command's own options from one options object, each under its declared name, and the pre-scan reads the global options and every installed plugin's options from one table. Two options with one name in either leave one of them unreadable.",
+    headline: 'Option declared twice',
+});
+/**
+ * An input a plugin's `onCommandAttach` hook declares under a name that an input of the other kind
+ * already holds in the Command's scope: an argument under an option's name, or an option under an
+ * argument's name.
+ */
+const nameSharedAcrossKinds = registerRule('@loomcli/core/name-shared-across-kinds', {
+    explanation: "An onCommandAttach hook adds inputs to a Command whose other inputs the plugin did not declare, so each name a hook declares stays apart from every argument and option in the Command's scope, whichever kind holds it. An author who gives an argument and an option one name does so knowingly, but a hook cannot see the Command's inputs, so a shared name there is an accident the author did not choose.",
+    headline: 'Argument and option share a name',
+});
+/** `required` or `validateOmitted` on a global option. */
+const globalPresenceRule = registerRule('@loomcli/core/global-presence-rule', {
+    explanation: 'A global option is validated on every Command, the Commands of plugins included, so a rule that its value must exist would fail a Command that never reads it. An omitted global option is absent.',
+    headline: 'Presence rule on a global option',
+});
+/** `globalOption()` after the application's own `command()` or `action()`. */
+const globalOptionAfterCommand = registerRule('@loomcli/core/global-option-after-command', {
+    explanation: 'A Command attached with command() and the root action read their types from the global options declared before them, so a global option declared later would reach an action whose types never name it.',
+    headline: 'Global option after a Command',
+});
+/** An environment binding on a multiple option. */
+const envOnMultiple = registerRule('@loomcli/core/env-on-multiple', {
+    explanation: 'A variable holds one string, and core never splits it, so it cannot supply the several values a multiple option collects. The configuration source supplies a list.',
+    headline: 'Environment binding on a list',
+});
+/** An environment binding whose name is outside the variable name grammar. */
+const envName = registerRule('@loomcli/core/env-name', {
+    explanation: 'The input-source stage reads the variable an option binds by its name, and a shell sets a variable only under a name of letters, digits, and underscores that does not start with a digit.',
+    headline: 'Invalid variable name',
+});
+/** An environment binding on an argument. */
+const envOnArgument = registerRule('@loomcli/core/env-on-argument', {
+    explanation: 'An argument is identified by its place among the bare tokens, so no variable can stand in for it. An option names itself on the command line, which lets a variable fill it.',
+    headline: 'Environment binding on an argument',
+});
+/** One variable that two options in one invocation's scope bind. */
+const variableBoundTwice = registerRule('@loomcli/core/variable-bound-twice', {
+    explanation: "Within one invocation's scope a variable fills one option, so two options that bind it would both take the value an operator set for one of them.",
+    headline: 'Variable bound twice',
+});
+/** `validateOmitted` on a declaration whose absence another rule already decides. */
+const omissionAlreadyDecided = registerRule('@loomcli/core/omission-already-decided', {
+    explanation: 'validateOmitted sends an omitted value to its validator, which only an input with no other absence rule needs. An omitted required input fails, a default fills an omitted value, and an omitted multiple option or variadic argument receives an empty array.',
+    headline: 'Absence already decided',
+});
+/** `validateOmitted` on a declaration with no validator. */
+const omissionWithoutValidator = registerRule('@loomcli/core/omission-without-validator', {
+    explanation: "validateOmitted sends an omitted value to the input's validator, so an input with no validator has nothing to receive it.",
+    headline: 'Omission with no validator',
+});
+/** `validate`, `default`, `required`, or `validateOmitted` on a Boolean option. */
+const booleanOptionValueRule = registerRule('@loomcli/core/boolean-option-value-rule', {
+    explanation: 'A Boolean option consumes no value, so there is nothing to validate, and its polarity decides the value an absent option reads. validate, default, required, and validateOmitted belong to inputs that take a value.',
+    headline: 'Value rule on a Boolean option',
+});
+/** A required input that also declares a default. */
+const requiredWithDefault = registerRule('@loomcli/core/required-with-default', {
+    explanation: 'A default fills an omitted value, and a required input fails when it is omitted, so a required input never reads its default.',
+    headline: 'Default on a required input',
+});
+/** A `validate` value that is not a Standard Schema v1 object. */
+const notAValidator = registerRule('@loomcli/core/not-a-validator', {
+    explanation: "Core validates every value through the Standard Schema v1 interface: the object's ~standard property, with version 1, a vendor, and a validate function. It calls nothing else.",
+    headline: 'Not a Standard Schema',
+});
+/** A default of the wrong raw shape for its declaration. */
+const defaultShape = registerRule('@loomcli/core/default-shape', {
+    explanation: "A default stands in for the value an operator would supply. Without a validator it is that raw value, a string or, for an input that takes several values, an array of strings; with one, it is the validator's input, and an input that takes several values still takes an array of them.",
+    headline: 'Default of the wrong shape',
+});
+/** The most arrays and plain objects any path through a declared default may hold. */
+const defaultLevels = 10;
+/** A declared default nested deeper than `defaultLevels`. */
+const defaultDepth = registerRule('@loomcli/core/default-depth', {
+    explanation: `A default stands in for the value an operator would supply, and every reader of the graph, help and the manifest included, walks it. Core keeps every path through a default within ${String(defaultLevels)} levels of arrays and plain objects, and a default that holds itself nests without end, so every reader stays far inside the call stack on every runtime.`,
+    headline: 'Default nested too deep',
+});
+/** A declared default its validator rejected. */
+const invalidDefault = registerRule('@loomcli/core/invalid-default', {
+    explanation: 'Each run passes every declared default through its validator before it reads a token, because a default reaches the action as a validated value. A default the validator rejects would reach no action, whatever the operator supplies.',
+    headline: 'Default rejected',
+});
+/** A validator's JSON Schema converter that threw or returned a value that is not a plain object. */
+const schemaConverterFailed = registerRule('@loomcli/core/schema-converter-failed', {
+    explanation: "Help, the manifest, and completion read what an input accepts from the JSON Schema its validator publishes. A converter that throws or returns anything but a plain object publishes no shape, so a distributed build reads the input's schema as null.",
+    headline: 'Schema converter failed',
+});
+export { booleanOptionMultiple, booleanOptionValueRule, defaultDepth, defaultLevels, defaultShape, envName, envOnArgument, envOnMultiple, flagNotBoolean, globalOptionAfterCommand, globalPresenceRule, invalidDefault, notAValidator, omissionAlreadyDecided, nameSharedAcrossKinds, omissionWithoutValidator, optionDeclaredTwice, optionPolarity, optionType, polarityOnString, requiredWithDefault, schemaConverterFailed, shortAlias, shortOnlyBothPolarities, shortOnlyWithoutShort, spellingTaken, variableBoundTwice, };

package/dist/inspect.d.ts

@@ -1,4 +1,5 @@
 import type { BuiltCommand, BuiltGraph } from './command.js';
+import { InternalError } from './errors.js';
 import type { DeclaredResult } from './types.js';
 /** The plain JSON Schema a validated input publishes, or `null` where the graph holds no shape. */
 type InputSchema = Readonly<Record<string, unknown>> | null;
@@ -109,23 +110,17 @@ interface CommandGraph {
     readonly globals: readonly OptionNode[];
     readonly root: CommandNode;
 }
-/**
- * A snapshot of one value. Arrays and plain objects are copied and frozen to any depth, so a
- * consumer cannot reach the source through the copy, and a later call reports the value again.
- * Primitives and library objects, such as a class instance or a `Date` a schema produced, are
- * reported as they are, because core cannot copy them meaningfully. The graph reads it for a
- * declared value and the chain reads it for the request one middleware holds.
- */
-export declare function snapshot(value: unknown): unknown;
 /** The declared result as plain data, or `null` on a Command that declares none. */
 declare function resultNode(result: DeclaredResult | undefined): ResultNode | null;
 /**
- * Renders one built graph as frozen plain data. Nothing here reads a host fact or a schema. The
- * globals list holds the application's own options, then each installed plugin's in installation
- * order, which is the order the globals table holds them in.
+ * Renders one built graph as frozen plain data. Nothing here reads a host fact; each validated
+ * input's converter is asked for its input schema, and in a development build a converter that
+ * fails is a declaration fault. The globals list holds the application's own options, then each
+ * installed plugin's in installation order, which is the order the globals table holds them in.
  */
 declare function inspectGraph(name: string, graph: BuiltGraph, facts: {
     description: string | undefined;
+    development: boolean;
     version: string;
 }): CommandGraph;
 /**
@@ -142,6 +137,11 @@ interface GraphLink {
  * programming error rather than an invocation fault.
  */
 declare function linkOf(graph: CommandGraph): GraphLink;
+/**
+ * The defect a graph reports when its nodes disagree with the build it was rendered from, so a
+ * node core looked up is missing.
+ */
+declare function graphMismatch(sentence: string): InternalError;
 /**
  * The routed node inside the inspected graph, which routing already proved reachable. A missing
  * segment means the two readings of one graph disagree, so the run stops rather than hand a
@@ -149,4 +149,4 @@ declare function linkOf(graph: CommandGraph): GraphLink;
  */
 declare function nodeAt(graph: CommandGraph, path: readonly string[]): CommandNode;
 export type { ArgumentNode, CommandGraph, CommandNode, OptionNode, ResultNode };
-export { inspectGraph, linkOf, nodeAt, resultNode };
+export { graphMismatch, inspectGraph, linkOf, nodeAt, resultNode };

package/dist/inspect.js

@@ -1,6 +1,9 @@
-import { InternalError } from './errors.js';
-import { isPlainObject } from './facts.js';
-import { validatesOmission } from './validation.js';
+import { asSentence, DeclarationError, InternalError, reasonOf } from './errors.js';
+import { partOf, siteFinding } from './facts.js';
+import { schemaConverterFailed } from './input-rules.js';
+import { isPlainObject, snapshotRecord } from './plain.js';
+import { foreignGraph, foreignGraphCorrection } from './rules.js';
+import { declaringSite, inputPlace, validatesOmission } from './validation.js';
 /** A declaration that carries no extension value publishes one shared, empty frozen record. */
 const noExtensions = Object.freeze({});
 /**
@@ -18,28 +21,12 @@ function spellingsOf(table, name) {
     return spellings;
 }
 /**
- * A snapshot of one value. Arrays and plain objects are copied and frozen to any depth, so a
- * consumer cannot reach the source through the copy, and a later call reports the value again.
- * Primitives and library objects, such as a class instance or a `Date` a schema produced, are
- * reported as they are, because core cannot copy them meaningfully. The graph reads it for a
- * declared value and the chain reads it for the request one middleware holds.
+ * A declared default is wrapped, so `default: undefined` reads apart from no default at all. The
+ * value is the frozen snapshot the declaring call took, the one a run validates, so inspection
+ * copies nothing and every reader sees one value.
  */
-export function snapshot(value) {
-    if (Array.isArray(value)) {
-        return Object.freeze(value.map((entry) => snapshot(entry)));
-    }
-    if (isPlainObject(value)) {
-        return snapshotRecord(value);
-    }
-    return value;
-}
-/** The snapshot of one plain object, under the record type the caller already established. */
-function snapshotRecord(value) {
-    return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, snapshot(entry)])));
-}
-/** A declared default is wrapped, so `default: undefined` reads apart from no default at all. */
 function declaredDefault(config) {
-    return 'default' in config ? Object.freeze({ value: snapshot(config.default) }) : undefined;
+    return 'default' in config ? Object.freeze({ value: config.default }) : undefined;
 }
 /**
  * The JSON Schema draft build asks every converter for, with no library options. Every converter
@@ -57,37 +44,68 @@ function publishesSchema(schema) {
         'output' in props.jsonSchema &&
         typeof props.jsonSchema.output === 'function');
 }
+/**
+ * The converter fault a development build reports for one input, with the way it failed and, when
+ * the converter threw, the thrown value as its cause.
+ */
+function converterFault(input, check, failed) {
+    const site = declaringSite(input, inputPlace(input, check));
+    const parts = {
+        correction: 'Fix the converter so it returns a JSON Schema object, or declare a validator that publishes none.',
+        findings: [siteFinding(site, partOf(site, 'validate'))],
+        sentence: `${site.subject} validator's JSON Schema converter ${failed.failure}`,
+    };
+    return 'cause' in failed
+        ? new DeclarationError(schemaConverterFailed, parts, { cause: failed.cause })
+        : new DeclarationError(schemaConverterFailed, parts);
+}
 /**
  * The input-side schema a declaration's validator publishes, snapshotted the way a declared
  * default is, or `null` where the graph holds no published shape: no validator, a validator with
- * no converter, or a converter that throws or returns anything but a plain object. The contract of
- * 2026-09-19 made that last case a declaration error `inspect()` alone reports; that diagnostic is
- * held while the question of how a run tells development from a distributed application is
- * decided, so it reads `null` on both paths.
+ * no converter, or, in a distributed build, a converter that throws or returns anything but a plain
+ * object. A development build reports that last case as a declaration fault instead.
  */
-function inputSchema(config) {
+function inputSchema(input, check) {
+    const { config } = input;
     const schema = 'validate' in config ? config.validate : undefined;
     if (schema === undefined) {
         return null;
     }
-    // The converter is the library's code from the first property read.
-    // A throw on reaching it and a throw on calling it are one failure.
+    let copied = undefined;
+    // The converter is the library's code from the first property read to the last key of its answer.
+    // A throw on reaching it, on calling it, or on reading what it answered is one failure.
     try {
         if (!publishesSchema(schema)) {
             return null;
         }
         const published = schema['~standard'].jsonSchema.input(schemaTarget);
-        return isPlainObject(published) ? snapshotRecord(published) : null;
+        copied = isPlainObject(published) ? snapshotRecord(published) : undefined;
     }
-    catch {
+    catch (error) {
+        if (check.development) {
+            throw converterFault(input, check, {
+                cause: error,
+                failure: `failed for target "${schemaTarget.target}": ${asSentence(reasonOf(error))}`,
+            });
+        }
         return null;
     }
+    if (copied !== undefined) {
+        return copied;
+    }
+    if (check.development) {
+        throw converterFault(input, check, {
+            failure: `answered target "${schemaTarget.target}" with a value that is not a plain object.`,
+        });
+    }
+    return null;
 }
 /** One declaration's extension record, which is the shared empty one when it carries no value. */
 function extensionsOf(records, declaration) {
     return records.get(declaration) ?? noExtensions;
 }
-function optionNode(input, { records, scope, table }) {
+function optionNode(input, read) {
+    const { check, records, scope, table } = read;
     const { config, name } = input;
     const { long, negative, short } = spellingsOf(table, name);
     const extensions = extensionsOf(records, input);
@@ -119,7 +137,7 @@ function optionNode(input, { records, scope, table }) {
             multiple: config.multiple === true,
             name,
             required: config.required === true,
-            schema: inputSchema(config),
+            schema: inputSchema(input, check),
             scope,
             short,
             type: 'string',
@@ -129,7 +147,8 @@ function optionNode(input, { records, scope, table }) {
     return Object.freeze(node);
 }
 /** The built slots already answer presence and arity, so the node repeats no config reading. */
-function argumentNode(slot, records) {
+function argumentNode(slot, read) {
+    const { check, records } = read;
     const { config, name } = slot.input;
     const node = {
         default: declaredDefault(config),
@@ -137,7 +156,7 @@ function argumentNode(slot, records) {
         extensions: extensionsOf(records, slot.input),
         name,
         required: slot.required,
-        schema: inputSchema(config),
+        schema: inputSchema(slot.input, check),
         validateOmitted: validatesOmission(slot.input),
         validated: config.validate !== undefined,
         variadic: slot.variadic,
@@ -152,18 +171,24 @@ function optionNodes(inputs, read) {
  * and the root reports the Application's, which is why the caller supplies that one.
  */
 function commandNode(command, place) {
-    const { nodes, path, records } = place;
+    const { development, nodes, path, records } = place;
+    const check = { development, global: false, path };
     const node = {
         aliases: Object.freeze([...command.aliases]),
-        arguments: Object.freeze(command.arguments.map((slot) => argumentNode(slot, records))),
-        children: Object.freeze([...command.children].map(([name, child]) => commandNode(child, { nodes, path: Object.freeze([...path, name]), records }))),
+        arguments: Object.freeze(command.arguments.map((slot) => argumentNode(slot, { check, records }))),
+        children: Object.freeze([...command.children].map(([name, child]) => commandNode(child, { development, nodes, path: Object.freeze([...path, name]), records }))),
         deprecated: command.deprecated,
         description: 'description' in place ? place.description : command.description,
         extensions: command.extensions,
         hasAction: command.dispatch !== undefined,
         hidden: command.hidden,
         name: command.name,
-        options: Object.freeze(optionNodes(command.inputs, { records, scope: 'application', table: command.options })),
+        options: Object.freeze(optionNodes(command.inputs, {
+            check,
+            records,
+            scope: 'application',
+            table: command.options,
+        })),
         path,
         result: resultNode(command.result),
     };
@@ -183,23 +208,27 @@ function resultNode(result) {
     });
 }
 /**
- * Renders one built graph as frozen plain data. Nothing here reads a host fact or a schema. The
- * globals list holds the application's own options, then each installed plugin's in installation
- * order, which is the order the globals table holds them in.
+ * Renders one built graph as frozen plain data. Nothing here reads a host fact; each validated
+ * input's converter is asked for its input schema, and in a development build a converter that
+ * fails is a declaration fault. The globals list holds the application's own options, then each
+ * installed plugin's in installation order, which is the order the globals table holds them in.
  */
 function inspectGraph(name, graph, facts) {
+    const { development } = facts;
     const records = graph.extensions;
     const table = graph.globals.options;
     const nodes = new WeakMap();
+    const check = { development, global: true, path: [] };
     const inspected = {
         description: facts.description,
         globals: Object.freeze([
-            ...optionNodes(graph.globals.inputs, { records, scope: 'application', table }),
-            ...graph.globals.plugins.flatMap((installed) => optionNodes(installed.inputs, { records, scope: 'plugin', table })),
+            ...optionNodes(graph.globals.inputs, { check, records, scope: 'application', table }),
+            ...graph.globals.plugins.flatMap((installed) => optionNodes(installed.inputs, { check, records, scope: 'plugin', table })),
         ]),
         name,
         root: commandNode(graph.root, {
             description: facts.description,
+            development,
             nodes,
             path: Object.freeze([]),
             records,
@@ -219,10 +248,25 @@ const links = new WeakMap();
 function linkOf(graph) {
     const link = links.get(graph);
     if (!link) {
-        throw new InternalError('The graph was not produced by inspect(). Pass the graph inspect() returned.', undefined);
+        throw new InternalError(foreignGraph, {
+            cause: undefined,
+            correction: 'Pass the graph inspect() returned.',
+            sentence: 'The graph was not produced by inspect().',
+        });
     }
     return link;
 }
+/**
+ * The defect a graph reports when its nodes disagree with the build it was rendered from, so a
+ * node core looked up is missing.
+ */
+function graphMismatch(sentence) {
+    return new InternalError(foreignGraph, {
+        cause: undefined,
+        correction: foreignGraphCorrection,
+        sentence,
+    });
+}
 /**
  * The routed node inside the inspected graph, which routing already proved reachable. A missing
  * segment means the two readings of one graph disagree, so the run stops rather than hand a
@@ -233,10 +277,10 @@ function nodeAt(graph, path) {
     for (const name of path) {
         const child = node.children.find((entry) => entry.name === name);
         if (!child) {
-            throw new InternalError(`The routed command "${path.join(' ')}" is not in the inspected graph.`, undefined);
+            throw graphMismatch(`The routed command "${path.join(' ')}" is not in the inspected graph.`);
         }
         node = child;
     }
     return node;
 }
-export { inspectGraph, linkOf, nodeAt, resultNode };
+export { graphMismatch, inspectGraph, linkOf, nodeAt, resultNode };

package/dist/lanes.js

@@ -2,7 +2,7 @@ import { routedSubject } from './errors.js';
 import { glyph } from './glyphs.generated.js';
 import { view } from './view.js';
 /**
- * The identity prefix core's own views take, the package name by the plugin-identity convention.
+ * The identity prefix core's own views take, the package name by the plugin identity convention.
  * Core compiles from `src` alone, so the name is spelled here rather than read from the manifest.
  */
 const core = '@loomcli/core';

package/dist/locate.js

@@ -1,6 +1,6 @@
 import { argumentSlot, readsAsChild, route } from './command.js';
-import { InternalError, UsageError } from './errors.js';
-import { linkOf } from './inspect.js';
+import { UsageError } from './errors.js';
+import { graphMismatch, linkOf } from './inspect.js';
 import { isOptionToken, longStringOption, longToken, scanGlobals, scanInputs } from './options.js';
 const none = Object.freeze({ kind: 'none' });
 /**
@@ -57,7 +57,7 @@ function valueOf(scope, name, word) {
     const option = graph.globals.find((entry) => entry.name === name) ??
         command.options.find((entry) => entry.name === name);
     if (!option) {
-        throw new InternalError(`Option "${name}" is not in the inspected graph.`, undefined);
+        throw graphMismatch(`Option "${name}" is not in the inspected graph.`);
     }
     return { command, kind: 'value', lead: word.lead, option, prefix: word.prefix };
 }
@@ -114,7 +114,7 @@ function locate(graph, words) {
     }
     const command = link.nodes.get(earlier.command);
     if (!command) {
-        throw new InternalError('The routed command is not in the inspected graph.', undefined);
+        throw graphMismatch('The routed command is not in the inspected graph.');
     }
     return lastWord({ built: link.graph, command, earlier, graph }, words.at(-1) ?? '');
 }

package/dist/options.d.ts

@@ -1,3 +1,4 @@
+import type { InputSite } from './facts.js';
 import type { OptionConfig } from './types.js';
 export interface OptionDeclaration {
     name: string;
@@ -13,7 +14,7 @@ export interface OptionValues {
 /** Every parsed value lands in one of these maps; `lists` holds the repeated string options. */
 export declare function emptyValues(): OptionValues;
 /** Which accepted form a table entry is. The table owns the convention, so readers never re-derive it. */
-type SpellingRole = 'long' | 'negative' | 'short';
+export type SpellingRole = 'long' | 'negative' | 'short';
 type OptionForm = {
     type: 'string';
     name: string;
@@ -26,6 +27,29 @@ type OptionForm = {
 type OptionSpelling = OptionForm & {
     role: SpellingRole;
 };
+/**
+ * The part of one declaration that yields a spelling of the given role, which a spelling fault
+ * marks: the declared name for the long form, `short` for the short alias, and the `polarity` that
+ * generates a negative form.
+ */
+export declare function spellingMark(site: InputSite, role: SpellingRole): string;
+/** The declared name answers the declared-name rule an argument's name answers. */
+export declare function checkOptionName(name: unknown, site: InputSite): void;
+/** Whether a declared short alias is one ASCII letter, the rule every short spelling answers. */
+export declare function isShortAlias(short: unknown): boolean;
+/** The sentence and correction of the short-alias fault for the option `subject` names. */
+export declare function shortAliasText(subject: string): {
+    sentence: string;
+    correction: string;
+};
+/**
+ * The scope one table compiles: the phrase a repeated name names it by, and where each of its
+ * options was declared, which every fault's findings rebuild.
+ */
+export interface CompileScope<Declaration extends OptionDeclaration> {
+    readonly subject: string;
+    readonly siteOf: (declaration: Declaration) => InputSite;
+}
 /**
  * One Boolean option's value for one invocation: the value the parser consumed, or the value its
  * declared polarity gives an absent option. A negative-only option is absent as `true`, because its
@@ -33,7 +57,11 @@ type OptionSpelling = OptionForm & {
  * declaration answer the same rule.
  */
 export declare function booleanValue(values: OptionValues, name: string, config: OptionConfig): boolean;
-export declare function compileOptions(declarations: readonly OptionDeclaration[], subject: string): Map<string, OptionSpelling>;
+/**
+ * One scope's options compiled into the spelling table the parser reads, with every rule one
+ * declaration answers alone and every rule two of them answer together.
+ */
+export declare function compileOptions<Declaration extends OptionDeclaration>(declarations: readonly Declaration[], scope: CompileScope<Declaration>): Map<string, OptionSpelling>;
 /**
  * Whether a token reads as an option: it starts with a hyphen. Routing stops at one, and a
  * separate value is never one. The parser and `locate` read each token through this rule.