@loomcli/core 0.6.0 → 0.8.0

package/dist/input-rules.js

@@ -4,9 +4,9 @@ import { registerRule } from './diagnostic-text.js';
  * 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. */
+/** An option declared with a type other than string, Boolean, or count. */
 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.',
+    explanation: 'The type decides how the parser reads an option: a string option consumes a value, a Boolean option consumes none, and a counted option consumes none and counts its occurrences. Core reads no other kind.',
     headline: 'Invalid option type',
 });
 /** A short alias that is not one ASCII letter. */
@@ -27,11 +27,36 @@ const shortOnlyWithoutShort = registerRule('@loomcli/core/short-only-without-sho
     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',
 });
+/** `aliases` on an option that declares `shortOnly`. */
+const shortOnlyWithAliases = registerRule('@loomcli/core/short-only-with-aliases', {
+    explanation: 'shortOnly removes every long spelling of an option, and each alias adds a long spelling, so an option cannot declare both.',
+    headline: 'Short only with aliases',
+});
 /** `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',
 });
+/** `multiple` on a counted option. */
+const countOptionMultiple = registerRule('@loomcli/core/count-option-multiple', {
+    explanation: 'A counted option already counts every occurrence of every spelling, so it has no values to collect. multiple collects each occurrence of a string option into an array.',
+    headline: 'Counted option takes no values',
+});
+/** `polarity` on a counted option. */
+const polarityOnCount = registerRule('@loomcli/core/polarity-on-count', {
+    explanation: 'Polarity chooses which long forms a Boolean option accepts and what its absence means. A counted option reads how many times it was supplied, so it has no negative form and no polarity.',
+    headline: 'Polarity on a counted option',
+});
+/** `implied` on a Boolean or counted option. */
+const impliedOnBooleanOrCount = registerRule('@loomcli/core/implied-on-boolean-or-count', {
+    explanation: 'An implied value is the value a bare spelling of a string option supplies. A Boolean option and a counted option take no value, so a bare spelling already says everything they read.',
+    headline: 'Implied on a valueless option',
+});
+/** An `implied` value that is not a string. */
+const impliedNotAString = registerRule('@loomcli/core/implied-not-a-string', {
+    explanation: "An implied value stands in for the string an operator would otherwise attach to the spelling, so it is a string, in the validator's input type.",
+    headline: 'Implied value not a string',
+});
 /** `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.',
@@ -52,7 +77,7 @@ const shortOnlyBothPolarities = registerRule('@loomcli/core/short-only-both-pola
  * 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.",
+    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, an alias, or a generated negative form included, would reach only one of them.",
     headline: 'Spelling used twice',
 });
 /**
@@ -60,7 +85,7 @@ const spellingTaken = registerRule('@loomcli/core/spelling-taken', {
  * 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.",
+    explanation: "An action reads the global options and its Command's own options from one options object, each under its declared name, and the global options, the application's and every installed plugin's, share every Command's one table of spellings. Two options with one name in either leave one of them unreadable.",
     headline: 'Option declared twice',
 });
 /**
@@ -117,6 +142,11 @@ const booleanOptionValueRule = registerRule('@loomcli/core/boolean-option-value-
     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',
 });
+/** `validate`, `default`, `required`, or `validateOmitted` on a counted option. */
+const countOptionValueRule = registerRule('@loomcli/core/count-option-value-rule', {
+    explanation: 'A counted option consumes no value and reads how many times it was supplied, 0 when nothing supplied it, so there is nothing to validate and no absence to decide. validate, default, required, and validateOmitted belong to inputs that take a value.',
+    headline: 'Value rule on a counted 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.',
@@ -132,14 +162,26 @@ const defaultShape = registerRule('@loomcli/core/default-shape', {
     explanation: "A default stands in for the value an operator would supply. Without a validator it is that raw value, a string or, for an input that takes several values, an array of strings; with one, it is the validator's input, and an input that takes several values still takes an array of them.",
     headline: 'Default of the wrong shape',
 });
+/** The most arrays and plain objects any path through a declared default may hold. */
+const defaultLevels = 10;
+/** A declared default nested deeper than `defaultLevels`. */
+const defaultDepth = registerRule('@loomcli/core/default-depth', {
+    explanation: `A default stands in for the value an operator would supply, and every reader of the graph, help and the manifest included, walks it. Core keeps every path through a default within ${String(defaultLevels)} levels of arrays and plain objects, and a default that holds itself nests without end, so every reader stays far inside the call stack on every runtime.`,
+    headline: 'Default nested too deep',
+});
 /** A declared default its validator rejected. */
 const invalidDefault = registerRule('@loomcli/core/invalid-default', {
     explanation: 'Each run passes every declared default through its validator before it reads a token, because a default reaches the action as a validated value. A default the validator rejects would reach no action, whatever the operator supplies.',
     headline: 'Default rejected',
 });
+/** A declared implied value its validator rejected. */
+const invalidImplied = registerRule('@loomcli/core/invalid-implied', {
+    explanation: 'Each run passes every implied value through its validator before it reads a token, because a bare spelling supplies it to the action as a validated value. An implied value the validator rejects is the declaration at fault, whatever the operator supplies, so the run reports it whether or not a bare spelling was typed.',
+    headline: 'Implied value 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, };
+export { booleanOptionMultiple, booleanOptionValueRule, countOptionMultiple, countOptionValueRule, defaultDepth, defaultLevels, defaultShape, envName, envOnArgument, envOnMultiple, flagNotBoolean, globalOptionAfterCommand, globalPresenceRule, impliedNotAString, impliedOnBooleanOrCount, invalidDefault, invalidImplied, notAValidator, omissionAlreadyDecided, nameSharedAcrossKinds, omissionWithoutValidator, optionDeclaredTwice, optionPolarity, optionType, polarityOnCount, polarityOnString, requiredWithDefault, schemaConverterFailed, shortAlias, shortOnlyBothPolarities, shortOnlyWithAliases, shortOnlyWithoutShort, spellingTaken, variableBoundTwice, };

package/dist/inspect.d.ts

@@ -21,17 +21,22 @@ interface ArgumentNode {
     readonly extensions: Readonly<Record<string, unknown>>;
 }
 /**
- * One declared option, in the shape its type gives it. Spellings are the accepted CLI forms, and
- * `scope` tells an application's own option from a plugin option, which reaches no action. An
- * option a plugin's lifecycle hook declared on a Command is that Command's own in every respect, so
- * it reads `application` and names no plugin.
+ * One declared option, in the shape its type gives it. Spellings are the accepted CLI forms. A
+ * global option reads the same whether the application or a plugin declared it, and an option a
+ * plugin's lifecycle hook declared on a Command is that Command's own in every respect, so neither
+ * names a plugin.
  * `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.
+ * `schema` is the input schema the validator publishes. A Boolean option and a counted option
+ * validate nothing, so their variants carry the field at `null`, and every projection built on the
+ * node holds if a later contract lets a Boolean option validate. A counted option has no negative
+ * spelling, polarity, default, or validator, so its variant carries none of them. A string option's
+ * `implied` is the value a bare spelling supplies, or `null` when it declares none.
  * `env` is the variable the option's environment binding names, or `null` when it binds none.
+ * `aliases` holds the declared aliases as bare names in declaration order. An alias is
+ * unadvertised, so the spellings above are the ones the declared name derives and no listing reads
+ * `aliases`; parsing and `locate` read the table, which holds every alias's spellings.
  */
 type OptionNode = {
     readonly type: 'string';
@@ -39,9 +44,9 @@ type OptionNode = {
     readonly description: string | undefined;
     readonly hidden: boolean;
     readonly deprecated: string | undefined;
-    readonly scope: 'application' | 'plugin';
     readonly long: string | null;
     readonly short: string | null;
+    readonly aliases: readonly string[];
     readonly required: boolean;
     readonly multiple: boolean;
     readonly validated: boolean;
@@ -51,6 +56,7 @@ type OptionNode = {
     readonly default: {
         readonly value: unknown;
     } | undefined;
+    readonly implied: string | null;
     readonly extensions: Readonly<Record<string, unknown>>;
 } | {
     readonly type: 'boolean';
@@ -58,14 +64,26 @@ type OptionNode = {
     readonly description: string | undefined;
     readonly hidden: boolean;
     readonly deprecated: string | undefined;
-    readonly scope: 'application' | 'plugin';
     readonly long: string | null;
     readonly short: string | null;
     readonly negative: string | null;
+    readonly aliases: readonly string[];
     readonly polarity: 'positive' | 'negative' | 'both';
     readonly schema: InputSchema;
     readonly env: string | null;
     readonly extensions: Readonly<Record<string, unknown>>;
+} | {
+    readonly type: 'count';
+    readonly name: string;
+    readonly description: string | undefined;
+    readonly hidden: boolean;
+    readonly deprecated: string | undefined;
+    readonly long: string | null;
+    readonly short: string | null;
+    readonly aliases: readonly string[];
+    readonly schema: null;
+    readonly env: string | null;
+    readonly extensions: Readonly<Record<string, unknown>>;
 };
 /**
  * One Command in the graph. `name` is `null` for the root, and `path` is its route from it.
@@ -111,20 +129,18 @@ interface CommandGraph {
     readonly root: CommandNode;
 }
 /**
- * A snapshot of one value. Arrays and plain objects are copied and frozen to any depth, so a
- * consumer cannot reach the source through the copy, and a later call reports the value again.
- * Primitives and library objects, such as a class instance or a `Date` a schema produced, are
- * reported as they are, because core cannot copy them meaningfully. The graph reads it for a
- * declared value and the chain reads it for the request one middleware holds.
+ * The spelling every reported problem names one option by, the one core's own validation reports:
+ * its long form, a negative-only Boolean option's negative form, and otherwise its short form. A
+ * plugin that reports a problem for an option, such as an input source, names it this way too.
  */
-export declare function snapshot(value: unknown): unknown;
+export declare function reportedSpelling(option: OptionNode): string;
 /** 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; 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.
+ * fails is a declaration fault. The globals list holds every global option, the application's own
+ * and then each installed plugin's in installation order, which is the order the table holds them.
  */
 declare function inspectGraph(name: string, graph: BuiltGraph, facts: {
     description: string | undefined;

package/dist/inspect.js

@@ -1,48 +1,28 @@
 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 { reportedOf, spellingsOf } from './options.js';
+import { isPlainObject, snapshotRecord } from './plain.js';
 import { foreignGraph, foreignGraphCorrection } from './rules.js';
-import { declaringSite, inputPlace, validatesOmission } from './validation.js';
+import { declarationSubject, declaringSite, inputPlace, validatesOmission } from './validation.js';
 /** A declaration that carries no extension value publishes one shared, empty frozen record. */
 const noExtensions = Object.freeze({});
 /**
- * Reads the spellings out of the compiled table the parser uses, so inspection cannot report a
- * form the parser does not accept. Each entry carries its own role, so the naming convention has
- * one owner: the table that writes it.
+ * The spelling every reported problem names one option by, the one core's own validation reports:
+ * its long form, a negative-only Boolean option's negative form, and otherwise its short form. A
+ * plugin that reports a problem for an option, such as an input source, names it this way too.
  */
-function spellingsOf(table, name) {
-    const spellings = { long: null, negative: null, short: null };
-    for (const [spelling, option] of table) {
-        if (option.name === name) {
-            spellings[option.role] = spelling;
-        }
-    }
-    return spellings;
+export function reportedSpelling(option) {
+    const negative = option.type === 'boolean' ? option.negative : null;
+    return reportedOf({ long: option.long, negative, short: option.short }, option.name);
 }
 /**
- * A snapshot of one value. Arrays and plain objects are copied and frozen to any depth, so a
- * consumer cannot reach the source through the copy, and a later call reports the value again.
- * Primitives and library objects, such as a class instance or a `Date` a schema produced, are
- * reported as they are, because core cannot copy them meaningfully. The graph reads it for a
- * declared value and the chain reads it for the request one middleware holds.
+ * A declared default is wrapped, so `default: undefined` reads apart from no default at all. The
+ * value is the frozen snapshot the declaring call took, the one a run validates, so inspection
+ * copies nothing and every reader sees one value.
  */
-export function snapshot(value) {
-    if (Array.isArray(value)) {
-        return Object.freeze(value.map((entry) => snapshot(entry)));
-    }
-    if (isPlainObject(value)) {
-        return snapshotRecord(value);
-    }
-    return value;
-}
-/** The snapshot of one plain object, under the record type the caller already established. */
-function snapshotRecord(value) {
-    return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, snapshot(entry)])));
-}
-/** A declared default is wrapped, so `default: undefined` reads apart from no default at all. */
 function declaredDefault(config) {
-    return 'default' in config ? Object.freeze({ value: snapshot(config.default) }) : undefined;
+    return 'default' in config ? Object.freeze({ value: config.default }) : undefined;
 }
 /**
  * The JSON Schema draft build asks every converter for, with no library options. Every converter
@@ -65,11 +45,11 @@ function publishesSchema(schema) {
  * the converter threw, the thrown value as its cause.
  */
 function converterFault(input, check, failed) {
-    const site = declaringSite(input, inputPlace(input, check));
+    const site = check.siteOf(input);
     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}`,
+        findings: site === undefined ? [] : [siteFinding(site, partOf(site, 'validate'))],
+        sentence: `${declarationSubject(input)} validator's JSON Schema converter ${failed.failure}`,
     };
     return 'cause' in failed
         ? new DeclarationError(schemaConverterFailed, parts, { cause: failed.cause })
@@ -120,47 +100,58 @@ function inputSchema(input, check) {
 function extensionsOf(records, declaration) {
     return records.get(declaration) ?? noExtensions;
 }
+/**
+ * One option's node, in the shape its kind gives it. Every kind publishes the listing facts and the
+ * spellings the declared name derives; a string option adds its value facts, a Boolean option its
+ * negative spelling and polarity, and a counted option nothing more.
+ */
 function optionNode(input, read) {
-    const { check, records, scope, table } = read;
+    const { check, records, table } = read;
     const { config, name } = input;
     const { long, negative, short } = spellingsOf(table, name);
-    const extensions = extensionsOf(records, input);
-    const node = config.type === 'boolean'
-        ? {
-            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',
+    const shared = {
+        aliases: Object.freeze([...(config.aliases ?? [])]),
+        deprecated: config.deprecated,
+        description: config.description,
+        env: config.env ?? null,
+        extensions: extensionsOf(records, input),
+        hidden: config.hidden === true,
+        long,
+        name,
+        short,
+    };
+    switch (config.type) {
+        case 'string': {
+            return Object.freeze({
+                ...shared,
+                default: declaredDefault(config),
+                implied: config.implied ?? null,
+                // The parser reads the same test, so a collection reports as one here and there.
+                multiple: config.multiple === true,
+                required: config.required === true,
+                schema: inputSchema(input, check),
+                type: 'string',
+                validateOmitted: validatesOmission(input),
+                validated: config.validate !== undefined,
+            });
         }
-        : {
-            default: declaredDefault(config),
-            deprecated: config.deprecated,
-            description: config.description,
-            env: config.env ?? null,
-            extensions,
-            hidden: config.hidden === true,
-            long,
-            // The parser reads the same test, so a collection reports as one here and there.
-            multiple: config.multiple === true,
-            name,
-            required: config.required === true,
-            schema: inputSchema(input, check),
-            scope,
-            short,
-            type: 'string',
-            validateOmitted: validatesOmission(input),
-            validated: config.validate !== undefined,
-        };
-    return Object.freeze(node);
+        case 'boolean': {
+            return Object.freeze({
+                ...shared,
+                negative,
+                polarity: config.polarity ?? 'positive',
+                schema: null,
+                type: 'boolean',
+            });
+        }
+        case 'count': {
+            return Object.freeze({ ...shared, schema: null, type: 'count' });
+        }
+        default: {
+            const exhaustive = config;
+            return exhaustive;
+        }
+    }
 }
 /** The built slots already answer presence and arity, so the node repeats no config reading. */
 function argumentNode(slot, read) {
@@ -188,7 +179,10 @@ function optionNodes(inputs, read) {
  */
 function commandNode(command, place) {
     const { development, nodes, path, records } = place;
-    const check = { development, global: false, path };
+    const check = {
+        development,
+        siteOf: (input) => declaringSite(input, inputPlace(input, path)),
+    };
     const node = {
         aliases: Object.freeze([...command.aliases]),
         arguments: Object.freeze(command.arguments.map((slot) => argumentNode(slot, { check, records }))),
@@ -199,12 +193,7 @@ function commandNode(command, place) {
         hasAction: command.dispatch !== undefined,
         hidden: command.hidden,
         name: command.name,
-        options: Object.freeze(optionNodes(command.inputs, {
-            check,
-            records,
-            scope: 'application',
-            table: command.options,
-        })),
+        options: Object.freeze(optionNodes(command.inputs, { check, records, table: command.table })),
         path,
         result: resultNode(command.result),
     };
@@ -226,21 +215,19 @@ function resultNode(result) {
 /**
  * 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.
+ * fails is a declaration fault. The globals list holds every global option, the application's own
+ * and then each installed plugin's in installation order, which is the order the table holds them.
  */
 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 { sites } = graph.globals;
+    const check = { development, siteOf: (input) => sites.get(input) };
     const inspected = {
         description: facts.description,
-        globals: Object.freeze([
-            ...optionNodes(graph.globals.inputs, { check, records, scope: 'application', table }),
-            ...graph.globals.plugins.flatMap((installed) => optionNodes(installed.inputs, { check, records, scope: 'plugin', table })),
-        ]),
+        globals: Object.freeze(optionNodes(graph.globals.inputs, { check, records, table })),
         name,
         root: commandNode(graph.root, {
             description: facts.description,

package/dist/locate.js

@@ -1,48 +1,17 @@
-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';
+import { argumentSlot, isOptionWord, readOptionWord, readWords, refusesValue } from './parse.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`.
+ * The words before the last, as the parser reads them, stopped before any validation. Every
+ * structural fault among them, an unknown Command included, reads as no position. When they run
+ * out at a Command with children, the last word may still continue routing, whatever it holds, so
+ * routing has not ended and a parent's own option among them stays unbound.
  */
-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) {
+function readEarlier(graph, words) {
     try {
-        return readStructure(graph, earlier);
+        const read = readWords(graph, words.slice(0, -1), { partial: true });
+        return read.fault === undefined ? read : undefined;
     }
     catch (error) {
         if (error instanceof UsageError) {
@@ -61,35 +30,55 @@ function valueOf(scope, name, word) {
     }
     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 });
+    return refusesValue(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) {
+/** A plain word names a child until routing ends, and fills the next positional after. */
+function plainWord(scope, last) {
     const { command, earlier } = scope;
-    if (!earlier.committed && readsAsChild(earlier.command, last)) {
+    if (!earlier.committed && earlier.command.children.size > 0) {
         return { command, kind: 'command', prefix: last };
     }
-    const slot = argumentSlot(earlier.command.arguments, earlier.positionals);
+    const slot = argumentSlot(earlier.command.arguments, earlier.positionals.length);
     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);
+/**
+ * A word the walk reads against the routed Command's table and the earlier words' values, as the
+ * parser reads it: no position where the walk faults, a repeat of an earlier option included, the
+ * value a long spelling carries after `=` or a short value letter carries after it, and otherwise
+ * `undefined`, an option spelling.
+ */
+function carriedValue(scope, last) {
+    const { earlier } = scope;
+    const context = { table: earlier.command.table, values: earlier.values };
+    const { occurrences } = readOptionWord(context, last, undefined);
+    for (const occurrence of occurrences) {
+        if (occurrence.kind !== 'value' && occurrence.kind !== 'awaiting') {
+            return none;
+        }
+        if (occurrence.kind === 'value' && occurrence.lead !== undefined) {
+            const { lead, option } = occurrence;
+            return valueOf(scope, option.name, { lead, prefix: last.slice(lead.length) });
+        }
     }
-    return { command: scope.command, kind: 'option', prefix: last, supplied: scope.earlier.supplied };
+    return undefined;
 }
-/** The last word, read as the parser would read the next token. */
+/**
+ * An option word. A long spelling without `=` is still being typed, so it is an option spelling
+ * whatever it names; any other word is read by the walk.
+ */
+function optionWord(scope, last) {
+    const typing = last.startsWith('--') && !last.includes('=');
+    return ((typing ? undefined : carriedValue(scope, last)) ?? {
+        command: scope.command,
+        kind: 'option',
+        prefix: last,
+        supplied: scope.earlier.supplied,
+    });
+}
+/** The last word, read as the parser would read the next word. */
 function lastWord(scope, last) {
     const { command, earlier } = scope;
     if (earlier.delimited) {
@@ -98,7 +87,10 @@ function lastWord(scope, last) {
     if (earlier.awaiting) {
         return awaitedValue(scope, earlier.awaiting, last);
     }
-    return isOptionToken(last) ? optionWord(scope, last) : bareWord(scope, last);
+    if (last === '-' || last === '--') {
+        return { command, kind: 'option', prefix: last, supplied: earlier.supplied };
+    }
+    return isOptionWord(last) ? optionWord(scope, last) : plainWord(scope, last);
 }
 /**
  * Reads an unfinished invocation against a graph `inspect()` returned and reports where its last
@@ -108,7 +100,7 @@ function lastWord(scope, last) {
  */
 function locate(graph, words) {
     const link = linkOf(graph);
-    const earlier = readEarlier(link.graph, words.slice(0, -1));
+    const earlier = readEarlier(link.graph, words);
     if (!earlier) {
         return none;
     }
@@ -116,6 +108,6 @@ function locate(graph, words) {
     if (!command) {
         throw graphMismatch('The routed command is not in the inspected graph.');
     }
-    return lastWord({ built: link.graph, command, earlier, graph }, words.at(-1) ?? '');
+    return lastWord({ command, earlier, graph }, words.at(-1) ?? '');
 }
 export { locate };