@loomcli/core 0.4.0 → 0.6.0

package/dist/input-rules.js

@@ -0,0 +1,145 @@
+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',
+});
+/** 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, 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 { BuiltGraph } from './command.js';
+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;
@@ -30,6 +31,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 +47,7 @@ type OptionNode = {
     readonly validated: boolean;
     readonly validateOmitted: boolean;
     readonly schema: InputSchema;
+    readonly env: string | null;
     readonly default: {
         readonly value: unknown;
     } | undefined;
@@ -61,6 +64,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>>;
 };
 /**
@@ -117,13 +121,40 @@ 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;
+/**
+ * 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 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
+ * 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 { graphMismatch, inspectGraph, linkOf, nodeAt, resultNode };

package/dist/inspect.js

@@ -1,5 +1,9 @@
-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 } 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({});
 /**
@@ -56,37 +60,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);
@@ -94,6 +129,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 +145,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,
@@ -116,7 +153,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',
@@ -126,7 +163,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),
@@ -134,7 +172,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,
@@ -149,22 +187,30 @@ 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 { 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, { 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),
     };
-    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) {
@@ -178,27 +224,79 @@ 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,
         }),
         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(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
+ * 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 graphMismatch(`The routed command "${path.join(' ')}" is not in the inspected graph.`);
+        }
+        node = child;
+    }
+    return node;
 }
-export { inspectGraph, 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.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 { 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' });
+/**
+ * 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 graphMismatch(`Option "${name}" is not in the inspected graph.`);
+    }
+    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 graphMismatch('The routed command is not in the inspected graph.');
+    }
+    return lastWord({ built: link.graph, command, earlier, graph }, words.at(-1) ?? '');
+}
+export { locate };