@loomcli/core 0.3.0 → 0.5.0

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';
@@ -11,7 +12,7 @@ export type { RenderingPolicy } from './rendering.js';
 export type { ViewContext } from './types.js';
 export { pad, style } from './style.js';
 export { issuePath } from './validation.js';
-export type { StandardSchemaV1 } from '@standard-schema/spec';
+export type { StandardJSONSchemaV1, StandardSchemaV1 } from '@standard-schema/spec';
 export type { ApplicationMethod, ApplicationOptions } from './application.js';
 export type { ChainOutcome, MiddlewareContext } from './chain.js';
 export type { InputProblem, ResultFault } from './errors.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,6 +1,11 @@
-import type { BuiltGraph } from './command.js';
+import type { BuiltCommand, BuiltGraph } from './command.js';
 import type { DeclaredResult } from './types.js';
-/** One declared argument. `default` wraps the declared value, so an explicit `undefined` shows. */
+/** The plain JSON Schema a validated input publishes, or `null` where the graph holds no shape. */
+type InputSchema = Readonly<Record<string, unknown>> | null;
+/**
+ * One declared argument. `default` wraps the declared value, so an explicit `undefined` shows, and
+ * `schema` is the input schema its validator publishes through the Standard JSON Schema converter.
+ */
 interface ArgumentNode {
     readonly name: string;
     readonly description: string | undefined;
@@ -8,6 +13,7 @@ interface ArgumentNode {
     readonly variadic: boolean;
     readonly validated: boolean;
     readonly validateOmitted: boolean;
+    readonly schema: InputSchema;
     readonly default: {
         readonly value: unknown;
     } | undefined;
@@ -21,6 +27,10 @@ interface ArgumentNode {
  * `hidden` is `false` unless the declaration says `true`, and `deprecated` is the declared
  * migration message or `undefined`. A listing projection omits a hidden node and marks a
  * deprecated one; parsing binds without reading either.
+ * `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';
@@ -35,6 +45,8 @@ type OptionNode = {
     readonly multiple: boolean;
     readonly validated: boolean;
     readonly validateOmitted: boolean;
+    readonly schema: InputSchema;
+    readonly env: string | null;
     readonly default: {
         readonly value: unknown;
     } | undefined;
@@ -50,6 +62,8 @@ type OptionNode = {
     readonly short: string | null;
     readonly negative: string | null;
     readonly polarity: 'positive' | 'negative' | 'both';
+    readonly schema: InputSchema;
+    readonly env: string | null;
     readonly extensions: Readonly<Record<string, unknown>>;
 };
 /**
@@ -114,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. */
@@ -28,14 +29,60 @@ export function snapshot(value) {
         return Object.freeze(value.map((entry) => snapshot(entry)));
     }
     if (isPlainObject(value)) {
-        return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, snapshot(entry)])));
+        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;
 }
+/**
+ * The JSON Schema draft build asks every converter for, with no library options. Every converter
+ * receives this one object, so it is frozen against a library that writes to its argument.
+ */
+const schemaTarget = Object.freeze({ target: 'draft-2020-12' });
+/** Whether a validator declares the Standard JSON Schema converter, both sides, beside `validate`. */
+function publishesSchema(schema) {
+    const props = schema['~standard'];
+    return ('jsonSchema' in props &&
+        typeof props.jsonSchema === 'object' &&
+        props.jsonSchema !== null &&
+        'input' in props.jsonSchema &&
+        typeof props.jsonSchema.input === 'function' &&
+        'output' in props.jsonSchema &&
+        typeof props.jsonSchema.output === 'function');
+}
+/**
+ * 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.
+ */
+function inputSchema(config) {
+    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.
+    try {
+        if (!publishesSchema(schema)) {
+            return null;
+        }
+        const published = schema['~standard'].jsonSchema.input(schemaTarget);
+        return isPlainObject(published) ? snapshotRecord(published) : null;
+    }
+    catch {
+        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;
@@ -48,12 +95,14 @@ function optionNode(input, { records, scope, table }) {
         ? {
             deprecated: config.deprecated,
             description: config.description,
+            env: config.env ?? null,
             extensions,
             hidden: config.hidden === true,
             long,
             name,
             negative,
             polarity: config.polarity ?? 'positive',
+            schema: null,
             scope,
             short,
             type: 'boolean',
@@ -62,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,
@@ -69,6 +119,7 @@ function optionNode(input, { records, scope, table }) {
             multiple: config.multiple === true,
             name,
             required: config.required === true,
+            schema: inputSchema(config),
             scope,
             short,
             type: 'string',
@@ -86,6 +137,7 @@ function argumentNode(slot, records) {
         extensions: extensionsOf(records, slot.input),
         name,
         required: slot.required,
+        schema: inputSchema(config),
         validateOmitted: validatesOmission(slot.input),
         validated: config.validate !== undefined,
         variadic: slot.variadic,
@@ -100,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,
@@ -115,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) {
@@ -136,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([
@@ -145,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 };

package/dist/locate.js

@@ -0,0 +1,121 @@
+import { argumentSlot, readsAsChild, route } from './command.js';
+import { InternalError, UsageError } from './errors.js';
+import { linkOf } from './inspect.js';
+import { isOptionToken, longStringOption, longToken, scanGlobals, scanInputs } from './options.js';
+const none = Object.freeze({ kind: 'none' });
+/**
+ * The option names the earlier words supplied, globals and locals merged into token order.
+ * Routing consumed the first `offset` rest tokens, so local token `i` is rest token `i + offset`.
+ */
+function suppliedOrder(count, scans) {
+    const { globals, local, offset } = scans;
+    const byToken = Array.from({ length: count }, () => []);
+    for (const { name, token } of globals.supplied) {
+        byToken[token]?.push(name);
+    }
+    for (const { name, token } of local.supplied) {
+        byToken[globals.positions[token + offset] ?? count]?.push(name);
+    }
+    return byToken.flat();
+}
+/**
+ * The parser's own pre-scan, routing, and local scan over the complete words. An earlier
+ * positional that no slot accepts is the unexpected-argument fault, so it reads as no position.
+ */
+function readStructure(graph, earlier) {
+    const globals = scanGlobals(graph.globals.options, earlier);
+    const routed = route(graph.root, globals.rest);
+    const local = scanInputs(routed.command.options, routed.tokens);
+    const positionals = local.positionals.length;
+    if (positionals > 0 && !argumentSlot(routed.command.arguments, positionals - 1)) {
+        return undefined;
+    }
+    return {
+        awaiting: globals.awaiting ?? local.awaiting,
+        command: routed.command,
+        committed: routed.tokens.length > 0,
+        delimited: local.delimited,
+        positionals,
+        supplied: suppliedOrder(earlier.length, { globals, local, offset: routed.path.length }),
+    };
+}
+/** Every structural fault the grammar raises is a usage error, and it reads as no position. */
+function readEarlier(graph, earlier) {
+    try {
+        return readStructure(graph, earlier);
+    }
+    catch (error) {
+        if (error instanceof UsageError) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+/** The value position of one option in scope: a global, or the routed Command's own. */
+function valueOf(scope, name, word) {
+    const { command, graph } = scope;
+    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);
+    }
+    return { command, kind: 'value', lead: word.lead, option, prefix: word.prefix };
+}
+/** A long token with an inline value is that option's value when it names a string option. */
+function inlineValue(scope, spelling, inline) {
+    const name = longStringOption(scope.built.globals.options, spelling) ??
+        longStringOption(scope.earlier.command.options, spelling);
+    return name === undefined ? none : valueOf(scope, name, { lead: `${spelling}=`, prefix: inline });
+}
+/** The word after a string option that ended the earlier words is that option's value. */
+function awaitedValue(scope, awaiting, last) {
+    return isOptionToken(last) ? none : valueOf(scope, awaiting.name, { lead: '', prefix: last });
+}
+/** A bare word names a child until routing commits, and fills the next positional after. */
+function bareWord(scope, last) {
+    const { command, earlier } = scope;
+    if (!earlier.committed && readsAsChild(earlier.command, last)) {
+        return { command, kind: 'command', prefix: last };
+    }
+    const slot = argumentSlot(earlier.command.arguments, earlier.positionals);
+    const argument = slot && command.arguments[earlier.command.arguments.indexOf(slot)];
+    return argument ? { argument, command, kind: 'argument', prefix: last } : none;
+}
+/** An option token: a long token's inline value, or else an option spelling being completed. */
+function optionWord(scope, last) {
+    const long = longToken(last);
+    if (long?.inline !== undefined) {
+        return inlineValue(scope, long.spelling, long.inline);
+    }
+    return { command: scope.command, kind: 'option', prefix: last, supplied: scope.earlier.supplied };
+}
+/** The last word, read as the parser would read the next token. */
+function lastWord(scope, last) {
+    const { command, earlier } = scope;
+    if (earlier.delimited) {
+        return { command, kind: 'passthrough', prefix: last };
+    }
+    if (earlier.awaiting) {
+        return awaitedValue(scope, earlier.awaiting, last);
+    }
+    return isOptionToken(last) ? optionWord(scope, last) : bareWord(scope, last);
+}
+/**
+ * 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`.
+ */
+function locate(graph, words) {
+    const link = linkOf(graph);
+    const earlier = readEarlier(link.graph, words.slice(0, -1));
+    if (!earlier) {
+        return none;
+    }
+    const command = link.nodes.get(earlier.command);
+    if (!command) {
+        throw new InternalError('The routed command is not in the inspected graph.', undefined);
+    }
+    return lastWord({ built: link.graph, command, earlier, graph }, words.at(-1) ?? '');
+}
+export { locate };