@loomcli/core 0.4.0 → 0.5.0

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 };

package/dist/options.d.ts

@@ -7,7 +7,11 @@ export interface OptionValues {
     strings: Map<string, string>;
     lists: Map<string, string[]>;
     booleans: Map<string, boolean>;
+    /** The spelling of the token that supplied each parsed option, which no input source writes. */
+    spellings: Map<string, string>;
 }
+/** Every parsed value lands in one of these maps; `lists` holds the repeated string options. */
+export declare function emptyValues(): OptionValues;
 /** Which accepted form a table entry is. The table owns the convention, so readers never re-derive it. */
 type SpellingRole = 'long' | 'negative' | 'short';
 type OptionForm = {
@@ -30,13 +34,82 @@ type OptionSpelling = OptionForm & {
  */
 export declare function booleanValue(values: OptionValues, name: string, config: OptionConfig): boolean;
 export declare function compileOptions(declarations: readonly OptionDeclaration[], subject: string): Map<string, OptionSpelling>;
+/**
+ * Whether a token reads as an option: it starts with a hyphen. Routing stops at one, and a
+ * separate value is never one. The parser and `locate` read each token through this rule.
+ */
+export declare function isOptionToken(token: string): boolean;
+/** A long option token and the inline value it carries after its first `=`, if any. */
+export interface LongToken {
+    spelling: string;
+    inline: string | undefined;
+}
+/**
+ * A token that starts with `--` split at its first `=` into the spelling and the inline value, or
+ * `undefined` for any other token. The parser and `locate` split long tokens through this rule.
+ */
+export declare function longToken(token: string): LongToken | undefined;
+/**
+ * The name of the string option one long spelling names in a table, which takes its value after
+ * `=`, or `undefined` for a Boolean, negative, short, or unknown spelling.
+ */
+export declare function longStringOption(spellings: ReadonlyMap<string, OptionSpelling>, spelling: string): string | undefined;
+/**
+ * A string option whose value the next token supplies, where the tokens ended first. A complete
+ * invocation reports it as a missing value; a partial one reads the next word as that value.
+ */
+export interface AwaitingValue {
+    name: string;
+    spelling: string;
+}
+/** One option name a token newly supplied, with the index of that token in the list read. */
+export interface SuppliedOption {
+    name: string;
+    token: number;
+}
+/**
+ * The pre-scan's reading of a token list that may stop short. `positions` holds the index in
+ * `tokens` of each `rest` token, and `awaiting` is the global option the last token left without
+ * its value.
+ */
+export interface GlobalScan {
+    awaiting: AwaitingValue | undefined;
+    positions: number[];
+    rest: string[];
+    supplied: SuppliedOption[];
+    values: OptionValues;
+}
 /** Consumes global options anywhere before the passthrough delimiter and leaves the rest routable. */
+export declare function scanGlobals(spellings: ReadonlyMap<string, OptionSpelling>, tokens: readonly string[]): GlobalScan;
+/** The pre-scan of a complete invocation, where a global still waiting for its value is a fault. */
 export declare function extractGlobals(spellings: ReadonlyMap<string, OptionSpelling>, tokens: readonly string[]): {
     rest: string[];
     values: OptionValues;
 };
+/**
+ * Whether one option holds a value a tier supplied: a token in any spelling it accepts, or a fill
+ * from an input source. A declared default is never in these maps, so it never counts.
+ */
+export declare function isSupplied(values: OptionValues, name: string): boolean;
+/** One run's own copy of parsed values, which the input-source stage fills without touching argv's. */
+export declare function copyValues(values: OptionValues): OptionValues;
 /** Global and local keys never overlap, so one merged view feeds a single validation pass. */
 export declare function mergeValues(globals: OptionValues, locals: OptionValues): OptionValues;
+/**
+ * One Command's reading of its own tokens, which may stop short. `delimited` says a bare `--` was
+ * read, and `awaiting` is the option the last token left without its value.
+ */
+export interface InputScan {
+    awaiting: AwaitingValue | undefined;
+    delimited: boolean;
+    options: OptionValues;
+    passthrough: string[];
+    positionals: string[];
+    supplied: SuppliedOption[];
+}
+/** Reads one Command's tokens into options, positionals, and the passthrough tail. */
+export declare function scanInputs(spellings: ReadonlyMap<string, OptionSpelling>, tokens: readonly string[]): InputScan;
+/** Parses a complete invocation's local tokens, where a waiting option is a missing value. */
 export declare function parseInputs(spellings: ReadonlyMap<string, OptionSpelling>, tokens: readonly string[]): {
     options: OptionValues;
     passthrough: string[];

package/dist/options.js

@@ -1,7 +1,7 @@
 import { DeclarationError, MissingValueError, RepeatedOptionError, ShortGroupError, UnexpectedValueError, UnknownOptionError, } from './errors.js';
 /** Every parsed value lands in one of these maps; `lists` holds the repeated string options. */
-function emptyValues() {
-    return { booleans: new Map(), lists: new Map(), strings: new Map() };
+export function emptyValues() {
+    return { booleans: new Map(), lists: new Map(), spellings: new Map(), strings: new Map() };
 }
 function validateDeclaration({ name, config }) {
     if (typeof name !== 'string') {
@@ -89,6 +89,26 @@ export function compileOptions(declarations, subject) {
     }
     return spellings;
 }
+/**
+ * Whether a token reads as an option: it starts with a hyphen. Routing stops at one, and a
+ * separate value is never one. The parser and `locate` read each token through this rule.
+ */
+export function isOptionToken(token) {
+    return token.startsWith('-');
+}
+/**
+ * A token that starts with `--` split at its first `=` into the spelling and the inline value, or
+ * `undefined` for any other token. The parser and `locate` split long tokens through this rule.
+ */
+export function longToken(token) {
+    if (!token.startsWith('--')) {
+        return undefined;
+    }
+    const equals = token.indexOf('=');
+    return equals === -1
+        ? { inline: undefined, spelling: token }
+        : { inline: token.slice(equals + 1), spelling: token.slice(0, equals) };
+}
 function lookup(spellings, spelling) {
     const option = spellings.get(spelling);
     if (!option) {
@@ -96,20 +116,33 @@ function lookup(spellings, spelling) {
     }
     return option;
 }
+/**
+ * The name of the string option one long spelling names in a table, which takes its value after
+ * `=`, or `undefined` for a Boolean, negative, short, or unknown spelling.
+ */
+export function longStringOption(spellings, spelling) {
+    const option = spellings.get(spelling);
+    return option?.type === 'string' && option.role === 'long' ? option.name : undefined;
+}
 function acceptValue({ option, spelling, values, next, inline, }) {
     const repeatable = option.type === 'string' && option.multiple;
     if (!repeatable && (values.strings.has(option.name) || values.booleans.has(option.name))) {
         throw new RepeatedOptionError(spelling);
     }
+    // A repeatable option records its last occurrence, because each one overwrites the entry.
+    values.spellings.set(option.name, spelling);
     if (option.type === 'boolean') {
         if (inline !== undefined) {
             throw new UnexpectedValueError(spelling, inline);
         }
         values.booleans.set(option.name, option.value);
-        return false;
+        return 'alone';
     }
     const value = inline ?? next;
-    if (value === undefined || (inline === undefined && value.startsWith('-'))) {
+    if (value === undefined) {
+        return { name: option.name, spelling };
+    }
+    if (inline === undefined && isOptionToken(value)) {
         throw new MissingValueError(spelling);
     }
     if (repeatable) {
@@ -120,14 +153,13 @@ function acceptValue({ option, spelling, values, next, inline, }) {
     else {
         values.strings.set(option.name, value);
     }
-    return inline === undefined;
+    return inline === undefined ? 'next' : 'alone';
 }
 function parseOption(spellings, input, values) {
     const { token, next } = input;
-    if (token.startsWith('--')) {
-        const equals = token.indexOf('=');
-        const spelling = equals === -1 ? token : token.slice(0, equals);
-        const inline = equals === -1 ? undefined : token.slice(equals + 1);
+    const long = longToken(token);
+    if (long) {
+        const { inline, spelling } = long;
         return acceptValue({ inline, next, option: lookup(spellings, spelling), spelling, values });
     }
     if (token === '-') {
@@ -141,20 +173,37 @@ function parseOption(spellings, input, values) {
             throw new ShortGroupError({ reason: 'value-position', token: spelling });
         }
         const inline = suffix.startsWith('=') ? suffix.slice(1) : undefined;
-        if (acceptValue({ inline, next, option, spelling, values })) {
-            return true;
+        const reading = acceptValue({ inline, next, option, spelling, values });
+        if (reading !== 'alone') {
+            return reading;
         }
     }
-    return false;
+    return 'alone';
+}
+/**
+ * Reads one option token into the scan and answers whether it took the next token too. The names
+ * it newly supplied join `supplied` in the order the values map first recorded them, so a repeated
+ * option keeps its first position.
+ */
+function readOption(spellings, input, state) {
+    const known = state.values.spellings.size;
+    const reading = parseOption(spellings, input, state.values);
+    for (const name of [...state.values.spellings.keys()].slice(known)) {
+        state.supplied.push({ name, token: input.index });
+    }
+    if (typeof reading === 'object') {
+        state.awaiting = reading;
+    }
+    return reading === 'next';
 }
 /**
  * A hyphen token belongs to the globals when its long spelling or every short letter does. The
  * pre-scan reads the globals alone, so a letter it does not own is only "not a global option".
  */
 function isGlobalToken(spellings, token) {
-    if (token.startsWith('--')) {
-        const equals = token.indexOf('=');
-        return spellings.has(equals === -1 ? token : token.slice(0, equals));
+    const long = longToken(token);
+    if (long) {
+        return spellings.has(long.spelling);
     }
     const group = token.slice(1).split('=')[0] ?? '';
     let global = '';
@@ -177,52 +226,100 @@ function isGlobalToken(spellings, token) {
     return true;
 }
 /** Consumes global options anywhere before the passthrough delimiter and leaves the rest routable. */
-export function extractGlobals(spellings, tokens) {
-    const values = emptyValues();
+export function scanGlobals(spellings, tokens) {
+    const state = { awaiting: undefined, supplied: [], values: emptyValues() };
     const rest = [];
+    const positions = [];
     for (let index = 0; index < tokens.length; index += 1) {
         const token = tokens[index];
         if (token === undefined) {
             break;
         }
         if (token === '--') {
-            rest.push(...tokens.slice(index));
-            return { rest, values };
+            // One push per token, because a spread call would overflow the stack on a long list.
+            for (const [offset, tail] of tokens.slice(index).entries()) {
+                rest.push(tail);
+                positions.push(index + offset);
+            }
+            break;
         }
-        if (!token.startsWith('-') || !isGlobalToken(spellings, token)) {
+        if (!isOptionToken(token) || !isGlobalToken(spellings, token)) {
             rest.push(token);
+            positions.push(index);
         }
-        else if (parseOption(spellings, { next: tokens[index + 1], token }, values)) {
+        else if (readOption(spellings, { index, next: tokens[index + 1], token }, state)) {
             index += 1;
         }
     }
+    return { ...state, positions, rest };
+}
+/** The pre-scan of a complete invocation, where a global still waiting for its value is a fault. */
+export function extractGlobals(spellings, tokens) {
+    const { awaiting, rest, values } = scanGlobals(spellings, tokens);
+    if (awaiting) {
+        throw new MissingValueError(awaiting.spelling);
+    }
     return { rest, values };
 }
+/**
+ * Whether one option holds a value a tier supplied: a token in any spelling it accepts, or a fill
+ * from an input source. A declared default is never in these maps, so it never counts.
+ */
+export function isSupplied(values, name) {
+    return values.strings.has(name) || values.lists.has(name) || values.booleans.has(name);
+}
+/** One run's own copy of parsed values, which the input-source stage fills without touching argv's. */
+export function copyValues(values) {
+    return {
+        booleans: new Map(values.booleans),
+        lists: new Map([...values.lists].map(([name, list]) => [name, [...list]])),
+        spellings: new Map(values.spellings),
+        strings: new Map(values.strings),
+    };
+}
 /** Global and local keys never overlap, so one merged view feeds a single validation pass. */
 export function mergeValues(globals, locals) {
     return {
         booleans: new Map([...globals.booleans, ...locals.booleans]),
         lists: new Map([...globals.lists, ...locals.lists]),
+        spellings: new Map([...globals.spellings, ...locals.spellings]),
         strings: new Map([...globals.strings, ...locals.strings]),
     };
 }
-export function parseInputs(spellings, tokens) {
-    const options = emptyValues();
+/** Reads one Command's tokens into options, positionals, and the passthrough tail. */
+export function scanInputs(spellings, tokens) {
+    const state = { awaiting: undefined, supplied: [], values: emptyValues() };
     const positionals = [];
+    const read = (passthrough, delimited) => ({
+        awaiting: state.awaiting,
+        delimited,
+        options: state.values,
+        passthrough,
+        positionals,
+        supplied: state.supplied,
+    });
     for (let index = 0; index < tokens.length; index += 1) {
         const token = tokens[index];
         if (token === undefined) {
             break;
         }
         if (token === '--') {
-            return { options, passthrough: tokens.slice(index + 1), positionals };
+            return read(tokens.slice(index + 1), true);
         }
-        if (!token.startsWith('-')) {
+        if (!isOptionToken(token)) {
             positionals.push(token);
         }
-        else if (parseOption(spellings, { next: tokens[index + 1], token }, options)) {
+        else if (readOption(spellings, { index, next: tokens[index + 1], token }, state)) {
             index += 1;
         }
     }
-    return { options, passthrough: [], positionals };
+    return read([], false);
+}
+/** Parses a complete invocation's local tokens, where a waiting option is a missing value. */
+export function parseInputs(spellings, tokens) {
+    const { awaiting, options, passthrough, positionals } = scanInputs(spellings, tokens);
+    if (awaiting) {
+        throw new MissingValueError(awaiting.spelling);
+    }
+    return { options, passthrough, positionals };
 }

package/dist/output.d.ts

@@ -26,6 +26,8 @@ export declare class Output {
      * declaration a call answers to is checked where the action was authored.
      */
     readonly out: Out<OpenResult>;
+    /** The channel a configuration source receives: `out` with the results call naming a source. */
+    readonly sourceOut: Out<OpenResult>;
     private palette;
     private policy;
     private registry;

package/dist/output.js

@@ -155,6 +155,8 @@ export class Output {
      * declaration a call answers to is checked where the action was authored.
      */
     out;
+    /** The channel a configuration source receives: `out` with the results call naming a source. */
+    sourceOut;
     palette = new Map();
     policy = {};
     // The contributors this invocation resolves a declared view through, published once they build.
@@ -179,6 +181,8 @@ export class Output {
             success: (message) => this.emit('success', message, 'stderr'),
             warn: (message) => this.emit('warn', message, 'stderr'),
         };
+        // A configuration source writes through the same channel, and its results call names it.
+        this.sourceOut = { ...this.out, results: () => this.resultFault('source') };
     }
     /**
      * The channel one action receives. On a Command that declares a result nothing the action writes
@@ -238,7 +242,7 @@ export class Output {
             });
         }
         if (typeof view.row === 'function') {
-            // Build rejects a row view on a value result, so reaching one here is core's own fault.
+            // The result() call rejects a row view on a value result, so reaching one here is core's own fault.
             return this.renderFailed(new Error(`The view "${selected}" renders rows, not a value.`));
         }
         return this.rendered(() => resolveView(bare, view)(erased(value), this.context('stdout')));