@loomcli/core 0.4.0 → 0.5.0

package/dist/errors.d.ts

@@ -111,8 +111,8 @@ export declare class InternalError extends LoomError {
     readonly cause: unknown;
     constructor(message: string, cause: unknown);
 }
-/** The four ways the results lane is broken, each named where core meets it. */
-export type ResultFault = 'missing' | 'repeated' | 'undeclared' | 'middleware';
+/** The five ways the results lane is broken, each named where core meets it. */
+export type ResultFault = 'missing' | 'repeated' | 'undeclared' | 'middleware' | 'source';
 /**
  * Exit 1: the promise a declared result makes was not kept. It wraps no thrown value, so its
  * `cause` is `undefined`, and it extends `InternalError`, so an override of that class brands it
@@ -125,6 +125,11 @@ export declare class ResultError extends InternalError {
     readonly cause: undefined;
     constructor(kind: ResultFault, path: readonly string[]);
 }
+/**
+ * One message someone else wrote, as a sentence of its own. A schema or a plugin writes its message
+ * with or without a full stop, so a diagnostic supplies one only where the message carries none.
+ */
+export declare function asSentence(text: string): string;
 /** What a diagnostic says about an unexpected value, whether or not it was an Error. */
 export declare function reasonOf(thrown: unknown): string;
 /**

package/dist/errors.js

@@ -14,7 +14,8 @@ function resultMessage(kind, command) {
     if (kind === 'undeclared') {
         return `${routedSentence(command)} declares no result. Declare one with result() or rows() before action().`;
     }
-    return `A middleware called out.results() on ${routedSubject(command)}. Only the action emits a result.`;
+    const caller = kind === 'source' ? 'A configuration source' : 'A middleware';
+    return `${caller} called out.results() on ${routedSubject(command)}. Only the action emits a result.`;
 }
 /**
  * The clause that offers the candidates, which is absent when there are none: every child of the
@@ -210,6 +211,13 @@ export class ResultError extends InternalError {
         this.path = path;
     }
 }
+/**
+ * One message someone else wrote, as a sentence of its own. A schema or a plugin writes its message
+ * with or without a full stop, so a diagnostic supplies one only where the message carries none.
+ */
+export function asSentence(text) {
+    return text.endsWith('.') ? text : `${text}.`;
+}
 /** What a diagnostic says about an unexpected value, whether or not it was an Error. */
 export function reasonOf(thrown) {
     return thrown instanceof Error ? thrown.message : 'An unknown error occurred.';

package/dist/extension.d.ts

@@ -83,6 +83,8 @@ type ExtensionRead<Schema extends StandardSchemaV1, Collect extends boolean> = C
  * collection order, and an empty list where the node carries none.
  */
 declare function readExtension<Target extends ExtensionTarget, Schema extends StandardSchemaV1, Collect extends boolean = false>(node: NodeFor<Target>, descriptor: Extension<Target, Schema, Collect>): ExtensionRead<Schema, Collect>;
+/** How a diagnostic names the declarations one target covers, such as "Commands". */
+declare function appliesTo(target: ExtensionTarget): string;
 /** The declaration one `extensions` slot belongs to, as its own diagnostics name it. */
 interface ExtensionSubject {
     /** The subject after a preposition, such as `on Command "get"`. */
@@ -152,4 +154,4 @@ declare function storeCommandLayers(slot: Omit<ExtensionSlot, 'declared' | 'targ
     layers: readonly unknown[];
 }): ExtensionStore;
 export type { AnyExtension, DeepReadonly, DescriptorRegistry, Extension, ExtensionRecords, ExtensionStore, ExtensionSubject, ExtensionTarget, ExtensionValue, };
-export { buildExtensions, extendStore, extension, isDescriptor, publishStore, readExtension, registerDescriptor, storeCommandLayers, validateLayer, };
+export { appliesTo, buildExtensions, extendStore, extension, isDescriptor, publishStore, readExtension, registerDescriptor, storeCommandLayers, validateLayer, };

package/dist/extension.js

@@ -1,4 +1,4 @@
-import { DeclarationError, reasonOf } from './errors.js';
+import { asSentence, DeclarationError, reasonOf } from './errors.js';
 import { isPlainObject } from './facts.js';
 /** Authored values register here, so the public brand publishes no state to reach or replace. */
 const values = new WeakMap();
@@ -67,6 +67,10 @@ const applies = {
     command: 'Commands',
     option: 'options',
 };
+/** How a diagnostic names the declarations one target covers, such as "Commands". */
+function appliesTo(target) {
+    return applies[target];
+}
 /**
  * The children one container contributes, or nothing when its own shape is not plain data. An
  * accessor, a symbol key, and a non-enumerable own property are not plain data, and an `undefined`
@@ -231,13 +235,6 @@ function isSchema(value) {
         'validate' in standard &&
         typeof standard.validate === 'function');
 }
-/**
- * One schema message as a sentence of its own. A schema author writes the message with or without a
- * full stop, so the diagnostic supplies one only where the message carries none.
- */
-function sentence(text) {
-    return text.endsWith('.') ? text : `${text}.`;
-}
 /** The message one rejected value reports, with the placeholder a silent schema earns. */
 function issueText(issues) {
     const first = Array.isArray(issues) ? issues[0] : undefined;
@@ -272,7 +269,7 @@ function validated(subject, carried, schema) {
     }
     catch (error) {
         // A schema that throws rejected the value the only way it could, so it reads as a rejection.
-        throw new DeclarationError(`${subject.sentence} holds an invalid "${carried.descriptor.identity}" value: ${sentence(reasonOf(error))} Correct the value.`);
+        throw new DeclarationError(`${subject.sentence} holds an invalid "${carried.descriptor.identity}" value: ${asSentence(reasonOf(error))} Correct the value.`);
     }
 }
 /** Validates one carried value and answers the plain-data output the node stores under it. */
@@ -284,7 +281,7 @@ function validateValue(subject, carried) {
     }
     const issues = 'issues' in result ? result.issues : undefined;
     if (issues !== undefined) {
-        throw new DeclarationError(`${subject.sentence} holds an invalid "${identity}" value: ${sentence(issueText(issues))} Correct the value.`);
+        throw new DeclarationError(`${subject.sentence} holds an invalid "${identity}" value: ${asSentence(issueText(issues))} Correct the value.`);
     }
     const output = plainData('value' in result ? result.value : undefined);
     if (!output) {
@@ -395,4 +392,4 @@ function storeCommandLayers(slot) {
     }
     return store;
 }
-export { buildExtensions, extendStore, extension, isDescriptor, publishStore, readExtension, registerDescriptor, storeCommandLayers, validateLayer, };
+export { appliesTo, buildExtensions, extendStore, extension, isDescriptor, publishStore, readExtension, registerDescriptor, storeCommandLayers, validateLayer, };

package/dist/facts.d.ts

@@ -1,3 +1,8 @@
+/**
+ * One line of prose: a string that holds a character other than whitespace and no line terminator.
+ * Every one-line fact reads this rule, and so does the label a configuration source answers with.
+ */
+export declare function isProseLine(value: unknown): value is string;
 /**
  * The `description` core fact: one line of prose every projection reads. A value that is not a
  * string fails the same way a blank one does, because the author reads one rule for one fact.

package/dist/facts.js

@@ -10,6 +10,13 @@ const prose = /\P{White_Space}/u;
  * The seven are LF, VT, FF, CR, NEL, LS, and PS, each of them `White_Space` too.
  */
 const lineTerminator = /[\n\v\f\r\u0085\u2028\u2029]/u;
+/**
+ * One line of prose: a string that holds a character other than whitespace and no line terminator.
+ * Every one-line fact reads this rule, and so does the label a configuration source answers with.
+ */
+export function isProseLine(value) {
+    return typeof value === 'string' && prose.test(value) && !lineTerminator.test(value);
+}
 /**
  * The `description` core fact: one line of prose every projection reads. A value that is not a
  * string fails the same way a blank one does, because the author reads one rule for one fact.
@@ -19,7 +26,7 @@ export function checkDescription(subject, value) {
     if (value === undefined) {
         return undefined;
     }
-    if (typeof value !== 'string' || !prose.test(value) || lineTerminator.test(value)) {
+    if (!isProseLine(value)) {
         throw new DeclarationError(`${subject} description must hold a character other than whitespace and no line terminator. Supply a one-line summary.`);
     }
     return value;
@@ -48,7 +55,7 @@ export function checkDeprecated(subject, value) {
     if (value === undefined) {
         return undefined;
     }
-    if (typeof value !== 'string' || !prose.test(value) || lineTerminator.test(value)) {
+    if (!isProseLine(value)) {
         throw new DeclarationError(`${subject} deprecated message must hold a character other than whitespace and no line terminator. Supply a one-line migration path, such as "Use get instead.".`);
     }
     return value;
@@ -76,7 +83,7 @@ export function checkVersion(value) {
     if (value === undefined) {
         return '0.0.0';
     }
-    if (typeof value !== 'string' || !prose.test(value) || lineTerminator.test(value)) {
+    if (!isProseLine(value)) {
         throw new DeclarationError('The Application version must be a string that holds a character other than whitespace and no line terminator. Supply a string such as "1.2.0".');
     }
     return value;

package/dist/globals.d.ts

@@ -1,6 +1,8 @@
+import type { BoundOption } from './bindings.js';
 import { DeclarationError } from './errors.js';
+import type { DescriptorRegistry } from './extension.js';
 import { compileOptions } from './options.js';
-import type { BuiltPlugin, PluginBuild } from './plugin.js';
+import type { BuiltPlugin } from './plugin.js';
 import type { OptionConfig, OptionValue } from './types.js';
 import type { InputDeclaration, OptionInput, ValidatedInputs } from './validation.js';
 /**
@@ -28,30 +30,61 @@ declare function keyCollision(name: string, first: OptionOwner, second: OptionOw
 /** One spelling claimed twice, whichever two scopes claimed it. */
 declare function spellingCollision(spelling: string, first: OptionSite, second: OptionSite): DeclarationError;
 /**
- * The compiled global table: one spelling map shared by every Command in the graph. It holds the
+ * The globals table the pre-scan reads, with every rule that pairs two of its options settled: one
+ * spelling map, the scope that owns each key, and the variable each option binds. It holds the
  * application's global options and every installed plugin's options, because the pre-scan reads one
- * table. `inputs` holds the application's declarations alone, because a plugin option is never
- * validated and never reaches an action.
+ * table.
  */
-interface BuiltGlobals {
-    bind: (values: ValidatedInputs) => unknown;
-    inputs: readonly InputDeclaration[];
+interface GlobalTable {
     names: ReadonlyMap<string, OptionOwner>;
     options: ReturnType<typeof compileOptions>;
+    /** The variable each option in the table binds, under the phrase a duplicate names it by. */
+    variables: ReadonlyMap<string, string>;
+}
+/**
+ * The compiled table one graph build shares. `inputs` holds the application's declarations alone,
+ * because a plugin option is never validated and never reaches an action.
+ */
+interface BuiltGlobals extends GlobalTable {
+    bind: (values: ValidatedInputs) => unknown;
+    inputs: readonly OptionInput[];
     plugins: readonly BuiltPlugin[];
 }
-/** The Application's private global declarations and their schema-derived value binder. */
+/** The validated extension record of each declaration, keyed by the declaration itself. */
+type InputRecords = ReadonlyMap<InputDeclaration, Readonly<Record<string, unknown>>>;
+/**
+ * The Application's private global declarations, their schema-derived value binder, and the
+ * extension record each declaration's own call validated.
+ */
 interface GlobalsState<Globals = unknown> {
     bind: (values: ValidatedInputs) => Globals;
     inputs: readonly OptionInput[];
+    records: InputRecords;
 }
 declare function emptyGlobals(): GlobalsState<{}>;
-declare function declareGlobalOption<Globals, Name extends string, Config extends OptionConfig>(state: GlobalsState<Globals>, input: OptionInput<Name, Config>): GlobalsState<Globals & Record<Name, OptionValue<Config>>>;
+/**
+ * One global option's own facts, binding, and extension values, checked at its `globalOption()`
+ * call against the Application's descriptors. The rules that pair it with another option belong to
+ * the table, which the caller rebuilds with it.
+ */
+declare function declareGlobalOption<Globals, Name extends string, Config extends OptionConfig>(state: GlobalsState<Globals>, input: OptionInput<Name, Config>, descriptors: DescriptorRegistry): GlobalsState<Globals & Record<Name, OptionValue<Config>>>;
 /**
  * The one table the pre-scan reads: the application's global options in authoring order, then each
  * installed plugin's options in installation order. Every collision between the two scopes, by key
  * or by spelling, is reported here, so the pre-scan meets a table with one owner per name.
  */
-declare function buildGlobals(node: GlobalsState, plugins: readonly BuiltPlugin[], build: PluginBuild): BuiltGlobals;
-export type { BuiltGlobals, GlobalsState, OptionOwner, OptionSite };
-export { buildGlobals, declareGlobalOption, emptyGlobals, keyCollision, spellingCollision };
+declare function globalTable(inputs: readonly OptionInput[], plugins: readonly BuiltPlugin[]): GlobalTable;
+/** The table one graph build shares, which every earlier call already proved free of collisions. */
+declare function buildGlobals(node: GlobalsState, plugins: readonly BuiltPlugin[]): BuiltGlobals;
+/**
+ * One Command's own options against the globals table, compiled for dispatch. The table holds the
+ * application's globals and every plugin option, so a local collision reads the same sentence
+ * whichever scope on the other side claimed the name, the spelling, or the variable. One
+ * invocation's scope is this Command's own options and the table, so a variable binds one option
+ * there, while a sibling Command may bind it again.
+ */
+declare function checkLocalOptions(declarations: readonly OptionInput[], table: GlobalTable, subject: string): ReturnType<typeof compileOptions>;
+/** The options in one list that bind a variable, each named by the phrase its scope gives it. */
+declare function boundOptions(inputs: readonly OptionInput[], site: (name: string) => string): BoundOption[];
+export type { BuiltGlobals, GlobalsState, GlobalTable, InputRecords, OptionOwner, OptionSite };
+export { boundOptions, buildGlobals, checkLocalOptions, declareGlobalOption, emptyGlobals, globalTable, keyCollision, spellingCollision, };

package/dist/globals.js

@@ -1,8 +1,15 @@
+import { checkEnvBinding, claimVariables } from './bindings.js';
 import { DeclarationError } from './errors.js';
 import { buildExtensions } from './extension.js';
 import { checkDeprecated, checkDescription, checkHidden } from './facts.js';
 import { compileOptions } from './options.js';
 const globalSubject = 'the global options';
+/**
+ * The presence keys a global option may not declare, in the order its diagnostic names them. A
+ * global's validation runs on every Command, plugin Commands included, so a rule that a value must
+ * exist belongs to the Commands that read it.
+ */
+const omissionRules = ['required', 'validateOmitted'];
 /** A collision sentence names a plugin first, then the application's globals, then a local. */
 const ranks = {
     application: 1,
@@ -57,12 +64,34 @@ function spellingCollision(spelling, first, second) {
     return new DeclarationError(`Option spelling "${spelling}" is used by ${usedBy(leading)} and ${usedBy(trailing)}. Change one declaration.`);
 }
 function emptyGlobals() {
-    return { bind: () => ({}), inputs: [] };
+    return { bind: () => ({}), inputs: [], records: new Map() };
 }
-function declareGlobalOption(state, input) {
+/**
+ * One global option's own facts, binding, and extension values, checked at its `globalOption()`
+ * call against the Application's descriptors. The rules that pair it with another option belong to
+ * the table, which the caller rebuilds with it.
+ */
+function declareGlobalOption(state, input, descriptors) {
+    // A global option belongs to the application, not to one Command, so its facts read that way.
+    const sentence = `Global option "${input.name}"`;
+    const rejected = omissionRules.find((key) => key in input.config);
+    if (rejected !== undefined) {
+        throw new DeclarationError(`${sentence} declares ${rejected}. Remove it; an omitted global option is absent, and a Command that needs its value checks for it.`);
+    }
+    checkDescription(sentence, input.config.description);
+    checkHidden(sentence, input.config.hidden);
+    checkDeprecated(sentence, input.config.deprecated);
+    checkEnvBinding(sentence, input.config);
+    const record = buildExtensions({
+        declared: input.config.extensions,
+        descriptors,
+        subject: { phrase: `on the global option "${input.name}"`, sentence },
+        target: 'option',
+    });
     return {
         bind: (values) => ({ ...state.bind(values), ...values.option(input) }),
         inputs: [...state.inputs, input],
+        records: new Map([...state.records, [input, record]]),
     };
 }
 /**
@@ -70,31 +99,58 @@ function declareGlobalOption(state, input) {
  * installed plugin's options in installation order. Every collision between the two scopes, by key
  * or by spelling, is reported here, so the pre-scan meets a table with one owner per name.
  */
-function buildGlobals(node, plugins, build) {
+function globalTable(inputs, plugins) {
     const names = new Map();
     const application = { kind: 'application' };
-    // A global option belongs to the application, not to one Command, so its facts read that way.
-    for (const input of node.inputs) {
-        const sentence = `Global option "${input.name}"`;
-        checkDescription(sentence, input.config.description);
-        checkHidden(sentence, input.config.hidden);
-        checkDeprecated(sentence, input.config.deprecated);
-        build.extensions.set(input, buildExtensions({
-            declared: input.config.extensions,
-            descriptors: build.descriptors,
-            subject: { phrase: `on the global option "${input.name}"`, sentence },
-            target: 'option',
-        }));
+    for (const input of inputs) {
         names.set(input.name, application);
     }
-    const options = compileOptions(node.inputs, globalSubject);
+    const options = compileOptions(inputs, globalSubject);
     plugins.forEach((installed, order) => {
         join({ identity: installed.identity, kind: 'plugin', order }, installed.inputs, {
             names,
             options,
         });
     });
-    return { bind: node.bind, inputs: node.inputs, names, options, plugins };
+    const variables = claimVariables([
+        ...boundOptions(inputs, (name) => `global option "${name}"`),
+        ...plugins.flatMap((installed) => boundOptions(installed.inputs, (name) => `plugin "${installed.identity}" option "${name}"`)),
+    ]);
+    return { names, options, variables };
+}
+/** The table one graph build shares, which every earlier call already proved free of collisions. */
+function buildGlobals(node, plugins) {
+    return { ...globalTable(node.inputs, plugins), bind: node.bind, inputs: node.inputs, plugins };
+}
+/**
+ * One Command's own options against the globals table, compiled for dispatch. The table holds the
+ * application's globals and every plugin option, so a local collision reads the same sentence
+ * whichever scope on the other side claimed the name, the spelling, or the variable. One
+ * invocation's scope is this Command's own options and the table, so a variable binds one option
+ * there, while a sibling Command may bind it again.
+ */
+function checkLocalOptions(declarations, table, subject) {
+    const local = { kind: 'local', subject };
+    const application = { kind: 'application' };
+    for (const declaration of declarations) {
+        const claimed = table.names.get(declaration.name);
+        if (claimed) {
+            throw keyCollision(declaration.name, claimed, local);
+        }
+    }
+    const options = compileOptions(declarations, subject);
+    for (const [spelling, option] of options) {
+        const global = table.options.get(spelling);
+        if (global) {
+            throw spellingCollision(spelling, { name: global.name, owner: table.names.get(global.name) ?? application }, { name: option.name, owner: local });
+        }
+    }
+    claimVariables(boundOptions(declarations, (option) => `${subject} option "${option}"`), table.variables);
+    return options;
+}
+/** The options in one list that bind a variable, each named by the phrase its scope gives it. */
+function boundOptions(inputs, site) {
+    return inputs.flatMap(({ config, name }) => config.env === undefined ? [] : [{ site: site(name), variable: config.env }]);
 }
 /** One plugin's options joining the table the application's globals already hold. */
 function join(owner, inputs, table) {
@@ -114,4 +170,4 @@ function join(owner, inputs, table) {
         options.set(spelling, option);
     }
 }
-export { buildGlobals, declareGlobalOption, emptyGlobals, keyCollision, spellingCollision };
+export { boundOptions, buildGlobals, checkLocalOptions, declareGlobalOption, emptyGlobals, globalTable, keyCollision, spellingCollision, };

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { Command } from './command.js';
 export { validationContext, validationContextKey } from './context.js';
 export { DeclarationError, FatalError, InputError, InternalError, LoomError, MissingValueError, NonCallableCommandError, RepeatedOptionError, ResultError, ShortGroupError, UnexpectedArgumentError, UnexpectedValueError, UnknownCommandError, UnknownOptionError, UsageError, } from './errors.js';
 export { extension, readExtension } from './extension.js';
+export { locate } from './locate.js';
 export { incompleteResult, lanes } from './lanes.js';
 export { override, view } from './view.js';
 export { plugin } from './plugin.js';
@@ -19,9 +20,10 @@ export type { AnyExtension, Extension, ExtensionValue } from './extension.js';
 export type { CommandMethod, CommandOptions } from './command.js';
 export type { CancellationReason } from './signals.js';
 export type { IncompleteResult } from './lanes.js';
+export type { WordPosition } from './locate.js';
 export type { AnyDeclaredView, DeclaredRowView, DeclaredView, DeclaredViewBrand, FailureClass, ViewContribution, ViewOverride, } from './view.js';
 export type { ArgumentNode, CommandGraph, CommandNode, OptionNode, ResultNode } from './inspect.js';
-export type { Middleware, OptionsOf, Plugin, PluginDefinition, PluginOptions, PluginOptionValues, } from './plugin.js';
+export type { Middleware, OptionsOf, Plugin, PluginDefinition, PluginOptions, PluginOptionSpellings, PluginOptionValues, SourceAnswer, SourceContext, SourceResolver, } from './plugin.js';
 export type { Action, ActionArgs, ActionContext, ActionHandler, ActionOptions, ArgumentConfig, AttachedCommand, BooleanOption, CommandAttachHook, ExitCode, Host, InputIdentity, InputTerminal, Out, OptionConfig, OutputTerminal, Request, ResultInput, ResultView, ResultViews, RunOptions, ScalarArgument, StringOption, SuppliedInputs, RowView, RowViews, ValidationContext, VariadicArgument, View, } from './types.js';
 export type { ApplicationEnvironment, EnvironmentOf, Register, RegisteredEnvironment, } from './environment.js';
-export type { Ansi16Color, Ansi256Fallbacks, ColorFallbacks, ConcreteStyle, Style, ThemeMapping, ThemeConstraint, } from './style.js';
+export type { Ansi16Color, Ansi256Fallbacks, ColorFallbacks, ConcreteStyle, ContextualStyle, Style, ThemeMapping, ThemeConstraint, } from './style.js';

package/dist/index.js

@@ -3,6 +3,7 @@ export { Command } from './command.js';
 export { validationContext, validationContextKey } from './context.js';
 export { DeclarationError, FatalError, InputError, InternalError, LoomError, MissingValueError, NonCallableCommandError, RepeatedOptionError, ResultError, ShortGroupError, UnexpectedArgumentError, UnexpectedValueError, UnknownCommandError, UnknownOptionError, UsageError, } from './errors.js';
 export { extension, readExtension } from './extension.js';
+export { locate } from './locate.js';
 export { incompleteResult, lanes } from './lanes.js';
 export { override, view } from './view.js';
 export { plugin } from './plugin.js';

package/dist/inspect.d.ts

@@ -1,4 +1,4 @@
-import type { BuiltGraph } from './command.js';
+import type { BuiltCommand, BuiltGraph } from './command.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;
@@ -30,6 +30,7 @@ interface ArgumentNode {
  * `schema` is the input schema the validator publishes. A Boolean option validates nothing, so its
  * variant carries the field at `null`, and every projection built on the node holds if a later
  * contract lets it validate.
+ * `env` is the variable the option's environment binding names, or `null` when it binds none.
  */
 type OptionNode = {
     readonly type: 'string';
@@ -45,6 +46,7 @@ type OptionNode = {
     readonly validated: boolean;
     readonly validateOmitted: boolean;
     readonly schema: InputSchema;
+    readonly env: string | null;
     readonly default: {
         readonly value: unknown;
     } | undefined;
@@ -61,6 +63,7 @@ type OptionNode = {
     readonly negative: string | null;
     readonly polarity: 'positive' | 'negative' | 'both';
     readonly schema: InputSchema;
+    readonly env: string | null;
     readonly extensions: Readonly<Record<string, unknown>>;
 };
 /**
@@ -125,5 +128,25 @@ declare function inspectGraph(name: string, graph: BuiltGraph, facts: {
     description: string | undefined;
     version: string;
 }): CommandGraph;
+/**
+ * The built graph behind one rendered graph, and each built Command's own node in it. The parser
+ * reads the built tables, so a reader of the rendered graph that must parse as the parser does
+ * reaches them here.
+ */
+interface GraphLink {
+    graph: BuiltGraph;
+    nodes: WeakMap<BuiltCommand, CommandNode>;
+}
+/**
+ * The link of one rendered graph. A graph core did not render has none, which is a caller's
+ * programming error rather than an invocation fault.
+ */
+declare function linkOf(graph: CommandGraph): GraphLink;
+/**
+ * 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
+ * middleware or a configuration source the wrong Command.
+ */
+declare function nodeAt(graph: CommandGraph, path: readonly string[]): CommandNode;
 export type { ArgumentNode, CommandGraph, CommandNode, OptionNode, ResultNode };
-export { inspectGraph, resultNode };
+export { inspectGraph, linkOf, nodeAt, resultNode };

package/dist/inspect.js

@@ -1,3 +1,4 @@
+import { InternalError } from './errors.js';
 import { isPlainObject } from './facts.js';
 import { validatesOmission } from './validation.js';
 /** A declaration that carries no extension value publishes one shared, empty frozen record. */
@@ -94,6 +95,7 @@ function optionNode(input, { records, scope, table }) {
         ? {
             deprecated: config.deprecated,
             description: config.description,
+            env: config.env ?? null,
             extensions,
             hidden: config.hidden === true,
             long,
@@ -109,6 +111,7 @@ function optionNode(input, { records, scope, table }) {
             default: declaredDefault(config),
             deprecated: config.deprecated,
             description: config.description,
+            env: config.env ?? null,
             extensions,
             hidden: config.hidden === true,
             long,
@@ -149,11 +152,11 @@ function optionNodes(inputs, read) {
  * and the root reports the Application's, which is why the caller supplies that one.
  */
 function commandNode(command, place) {
-    const { path, records } = place;
+    const { nodes, path, records } = place;
     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, { path: Object.freeze([...path, name]), records }))),
+        children: Object.freeze([...command.children].map(([name, child]) => commandNode(child, { nodes, path: Object.freeze([...path, name]), records }))),
         deprecated: command.deprecated,
         description: 'description' in place ? place.description : command.description,
         extensions: command.extensions,
@@ -164,7 +167,9 @@ function commandNode(command, place) {
         path,
         result: resultNode(command.result),
     };
-    return Object.freeze(node);
+    const frozen = Object.freeze(node);
+    nodes.set(command, frozen);
+    return frozen;
 }
 /** The declared result as plain data, or `null` on a Command that declares none. */
 function resultNode(result) {
@@ -185,6 +190,7 @@ function resultNode(result) {
 function inspectGraph(name, graph, facts) {
     const records = graph.extensions;
     const table = graph.globals.options;
+    const nodes = new WeakMap();
     const inspected = {
         description: facts.description,
         globals: Object.freeze([
@@ -194,11 +200,43 @@ function inspectGraph(name, graph, facts) {
         name,
         root: commandNode(graph.root, {
             description: facts.description,
+            nodes,
             path: Object.freeze([]),
             records,
         }),
         version: facts.version,
     };
-    return Object.freeze(inspected);
+    const frozen = Object.freeze(inspected);
+    links.set(frozen, { graph, nodes });
+    return frozen;
+}
+/** Every graph core rendered, keyed by the frozen object a caller holds. */
+const links = new WeakMap();
+/**
+ * The link of one rendered graph. A graph core did not render has none, which is a caller's
+ * programming error rather than an invocation fault.
+ */
+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);
+    }
+    return link;
+}
+/**
+ * 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
+ * middleware or a configuration source the wrong Command.
+ */
+function nodeAt(graph, path) {
+    let node = graph.root;
+    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);
+        }
+        node = child;
+    }
+    return node;
 }
-export { inspectGraph, resultNode };
+export { inspectGraph, linkOf, nodeAt, resultNode };

package/dist/locate.d.ts

@@ -0,0 +1,41 @@
+import type { ArgumentNode, CommandGraph, CommandNode, OptionNode } from './inspect.js';
+/**
+ * Where the last word of an unfinished invocation sits. Every node is the given graph's own, so a
+ * reader compares by identity. `prefix` is the part of the word being completed.
+ */
+type WordPosition = {
+    readonly kind: 'command';
+    readonly command: CommandNode;
+    readonly prefix: string;
+} | {
+    readonly kind: 'option';
+    readonly command: CommandNode;
+    readonly prefix: string;
+    readonly supplied: readonly string[];
+} | {
+    readonly kind: 'value';
+    readonly command: CommandNode;
+    readonly option: OptionNode;
+    readonly lead: string;
+    readonly prefix: string;
+} | {
+    readonly kind: 'argument';
+    readonly command: CommandNode;
+    readonly argument: ArgumentNode;
+    readonly prefix: string;
+} | {
+    readonly kind: 'passthrough';
+    readonly command: CommandNode;
+    readonly prefix: string;
+} | {
+    readonly kind: 'none';
+};
+/**
+ * Reads an unfinished invocation against a graph `inspect()` returned and reports where its last
+ * word sits. `words` holds the tokens after the application name; an empty list reads as one empty
+ * word. It runs no validator, input source, or middleware, and a structural fault among the earlier
+ * words reads as `none`.
+ */
+declare function locate(graph: CommandGraph, words: readonly string[]): WordPosition;
+export type { WordPosition };
+export { locate };