@loomcli/core 0.4.0 → 0.6.0

package/dist/options.d.ts

@@ -1,3 +1,4 @@
+import type { InputSite } from './facts.js';
 import type { OptionConfig } from './types.js';
 export interface OptionDeclaration {
     name: string;
@@ -7,9 +8,13 @@ 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';
+export type SpellingRole = 'long' | 'negative' | 'short';
 type OptionForm = {
     type: 'string';
     name: string;
@@ -22,6 +27,22 @@ type OptionForm = {
 type OptionSpelling = OptionForm & {
     role: SpellingRole;
 };
+/**
+ * The part of one declaration that yields a spelling of the given role, which a spelling fault
+ * marks: the declared name for the long form, `short` for the short alias, and the `polarity` that
+ * generates a negative form.
+ */
+export declare function spellingMark(site: InputSite, role: SpellingRole): string;
+/** The declared name answers the declared-name rule an argument's name answers. */
+export declare function checkOptionName(name: unknown, site: InputSite): void;
+/**
+ * The scope one table compiles: the phrase a repeated name names it by, and where each of its
+ * options was declared, which every fault's findings rebuild.
+ */
+export interface CompileScope<Declaration extends OptionDeclaration> {
+    readonly subject: string;
+    readonly siteOf: (declaration: Declaration) => InputSite;
+}
 /**
  * One Boolean option's value for one invocation: the value the parser consumed, or the value its
  * declared polarity gives an absent option. A negative-only option is absent as `true`, because its
@@ -29,14 +50,87 @@ type OptionSpelling = OptionForm & {
  * declaration answer the same rule.
  */
 export declare function booleanValue(values: OptionValues, name: string, config: OptionConfig): boolean;
-export declare function compileOptions(declarations: readonly OptionDeclaration[], subject: string): Map<string, OptionSpelling>;
+/**
+ * One scope's options compiled into the spelling table the parser reads, with every rule one
+ * declaration answers alone and every rule two of them answer together.
+ */
+export declare function compileOptions<Declaration extends OptionDeclaration>(declarations: readonly Declaration[], scope: CompileScope<Declaration>): 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,52 +1,123 @@
-import { DeclarationError, MissingValueError, RepeatedOptionError, ShortGroupError, UnexpectedValueError, UnknownOptionError, } from './errors.js';
+import { declaredName } from './command-rules.js';
+import { valueCode } from './diagnostic-text.js';
+import { DeclarationError, MissingValueError, quoted, RepeatedOptionError, ShortGroupError, UnexpectedValueError, UnknownOptionError, } from './errors.js';
+import { factFault, flagFault, siteFinding } from './facts.js';
+import { booleanOptionMultiple, optionDeclaredTwice, optionPolarity, optionType, polarityOnString, shortAlias, shortOnlyBothPolarities, shortOnlyWithoutShort, spellingTaken, } from './input-rules.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 }) {
+/**
+ * The part of one declaration that yields a spelling of the given role, which a spelling fault
+ * marks: the declared name for the long form, `short` for the short alias, and the `polarity` that
+ * generates a negative form.
+ */
+export function spellingMark(site, role) {
+    if (role === 'long') {
+        return site.named;
+    }
+    return `${site.at}.${role === 'short' ? 'short' : 'polarity'}`;
+}
+/** The declared name answers the declared-name rule an argument's name answers. */
+export function checkOptionName(name, site) {
+    const findings = [siteFinding(site, site.named)];
     if (typeof name !== 'string') {
-        throw new DeclarationError('Option names must be strings. Supply a string name.');
+        throw new DeclarationError(declaredName, {
+            correction: 'Supply a string name.',
+            findings,
+            sentence: `Option name ${valueCode(name)} is not a string.`,
+        });
     }
     if (!name || name.startsWith('-') || /[\s=]/u.test(name)) {
-        throw new DeclarationError(`Option name "${name}" is invalid. Use a nonempty name without a leading hyphen, whitespace, or "=".`);
-    }
-    if (!['string', 'boolean'].includes(config.type)) {
-        throw new DeclarationError(`Option "${name}" has an invalid type. Use "string" or "boolean".`);
+        throw new DeclarationError(declaredName, {
+            correction: 'Use a nonempty name without a leading hyphen, whitespace, or "=".',
+            findings,
+            sentence: `Option name ${quoted(name)} is invalid.`,
+        });
     }
+}
+/** The short alias, and `shortOnly`, which leaves the option that alias alone. */
+function checkShortForms(config, site, subject) {
     if (config.short !== undefined &&
         (typeof config.short !== 'string' || !/^[A-Za-z]$/u.test(config.short))) {
-        throw new DeclarationError(`Option "${name}" requires a short alias of one ASCII letter.`);
+        throw factFault(shortAlias, site, {
+            correction: 'Supply one ASCII letter.',
+            fact: 'short',
+            sentence: `${subject} declares a short alias that is not one ASCII letter.`,
+        });
     }
     if (config.shortOnly !== undefined && typeof config.shortOnly !== 'boolean') {
-        throw new DeclarationError(`Option "${name}" shortOnly must be Boolean. Use true or false.`);
+        throw flagFault(site, 'shortOnly');
     }
     if (config.shortOnly && config.short === undefined) {
-        throw new DeclarationError(`Option "${name}" with shortOnly requires a short alias.`);
+        throw factFault(shortOnlyWithoutShort, site, {
+            correction: 'Add short or remove shortOnly.',
+            fact: 'shortOnly',
+            sentence: `${subject} declares shortOnly and no short alias.`,
+        });
+    }
+}
+/** A Boolean option's polarity, which a string option does not declare. */
+function checkPolarity(config, site, subject) {
+    if (config.polarity === undefined) {
+        return;
+    }
+    if (config.type !== 'boolean') {
+        throw factFault(polarityOnString, site, {
+            correction: 'Remove polarity or use type "boolean".',
+            fact: 'polarity',
+            sentence: `${subject} declares polarity but is not Boolean.`,
+        });
+    }
+    if (!['positive', 'both', 'negative'].includes(config.polarity)) {
+        throw factFault(optionPolarity, site, {
+            correction: 'Use "positive", "both", or "negative".',
+            fact: 'polarity',
+            sentence: `${subject} has an invalid polarity.`,
+        });
+    }
+    if (config.polarity === 'both' && config.shortOnly) {
+        throw factFault(shortOnlyBothPolarities, site, {
+            correction: 'Enable long forms or select one polarity.',
+            fact: 'shortOnly',
+            sentence: `${subject} cannot express both polarities with shortOnly.`,
+        });
+    }
+}
+/** Every rule one option declaration answers alone, before the table meets it. */
+function validateDeclaration({ name, config }, site) {
+    checkOptionName(name, site);
+    const subject = `Option ${quoted(name)}`;
+    if (!['string', 'boolean'].includes(config.type)) {
+        throw factFault(optionType, site, {
+            correction: 'Use "string" or "boolean".',
+            fact: 'type',
+            sentence: `${subject} has an invalid type.`,
+        });
     }
+    checkShortForms(config, site, subject);
     if (config.type === 'boolean' && config.multiple !== undefined) {
-        throw new DeclarationError(`Option "${name}" is a boolean option and declares multiple. Remove multiple or declare a string option.`);
+        throw factFault(booleanOptionMultiple, site, {
+            correction: 'Remove multiple or declare a string option.',
+            fact: 'multiple',
+            sentence: `${subject} is a boolean option and declares multiple.`,
+        });
     }
     if (config.multiple !== undefined && typeof config.multiple !== 'boolean') {
-        throw new DeclarationError(`Option "${name}" multiple must be Boolean. Use true or false.`);
-    }
-    if (config.polarity !== undefined) {
-        if (config.type !== 'boolean') {
-            throw new DeclarationError(`Option "${name}" declares polarity but is not Boolean. Remove polarity or use type "boolean".`);
-        }
-        if (!['positive', 'both', 'negative'].includes(config.polarity)) {
-            throw new DeclarationError(`Option "${name}" has an invalid polarity. Use "positive", "both", or "negative".`);
-        }
-        if (config.polarity === 'both' && config.shortOnly) {
-            throw new DeclarationError(`Option "${name}" cannot express both polarities with shortOnly. Enable long forms or select one polarity.`);
-        }
+        throw flagFault(site, 'multiple');
     }
+    checkPolarity(config, site, subject);
 }
-function addSpelling(spellings, spelling, option) {
-    const existing = spellings.get(spelling);
+function addSpelling(claims, spelling, claim) {
+    const existing = claims.get(spelling);
     if (existing) {
-        throw new DeclarationError(`Option spelling "${spelling}" is used by both "${existing.name}" and "${option.name}". Change one declaration.`);
+        throw new DeclarationError(spellingTaken, {
+            correction: 'Change one declaration.',
+            findings: [existing, claim].map(({ option, site }) => siteFinding(site, spellingMark(site, option.role))),
+            sentence: `Option spelling ${quoted(spelling)} is used by both ${quoted(existing.option.name)} and ${quoted(claim.option.name)}.`,
+        });
     }
-    spellings.set(spelling, option);
+    claims.set(spelling, claim);
 }
 /**
  * One Boolean option's value for one invocation: the value the parser consumed, or the value its
@@ -57,37 +128,70 @@ function addSpelling(spellings, spelling, option) {
 export function booleanValue(values, name, config) {
     return values.booleans.get(name) ?? config.polarity === 'negative';
 }
-export function compileOptions(declarations, subject) {
-    const spellings = new Map();
-    const names = new Set();
-    for (const { name, config } of declarations) {
-        validateDeclaration({ config, name });
-        if (names.has(name)) {
-            throw new DeclarationError(`Option "${name}" is declared more than once on ${subject}. Remove or rename the duplicate.`);
+/**
+ * One scope's options compiled into the spelling table the parser reads, with every rule one
+ * declaration answers alone and every rule two of them answer together.
+ */
+export function compileOptions(declarations, scope) {
+    const claims = new Map();
+    const names = new Map();
+    for (const declaration of declarations) {
+        const { name, config } = declaration;
+        const site = scope.siteOf(declaration);
+        validateDeclaration({ config, name }, site);
+        const first = names.get(name);
+        if (first) {
+            const earlier = scope.siteOf(first);
+            throw new DeclarationError(optionDeclaredTwice, {
+                correction: 'Remove or rename the duplicate.',
+                findings: [
+                    siteFinding(earlier, earlier.named, 'the first declaration'),
+                    siteFinding(site, site.named, 'the second declaration'),
+                ],
+                sentence: `Option ${quoted(name)} is declared more than once on ${scope.subject}.`,
+            });
         }
-        names.add(name);
+        names.set(name, declaration);
         const positive = config.type === 'string'
             ? { multiple: config.multiple === true, name, type: 'string' }
             : { name, type: 'boolean', value: config.polarity !== 'negative' };
         if (!config.shortOnly) {
             if (config.type === 'string' || config.polarity !== 'negative') {
-                addSpelling(spellings, `--${name}`, { ...positive, role: 'long' });
+                addSpelling(claims, `--${name}`, { option: { ...positive, role: 'long' }, site });
             }
             if (config.type === 'boolean' &&
                 (config.polarity === 'both' || config.polarity === 'negative')) {
-                addSpelling(spellings, `--no-${name}`, {
-                    name,
-                    role: 'negative',
-                    type: 'boolean',
-                    value: false,
+                addSpelling(claims, `--no-${name}`, {
+                    option: { name, role: 'negative', type: 'boolean', value: false },
+                    site,
                 });
             }
         }
         if (config.short !== undefined) {
-            addSpelling(spellings, `-${config.short}`, { ...positive, role: 'short' });
+            addSpelling(claims, `-${config.short}`, { option: { ...positive, role: 'short' }, site });
         }
     }
-    return spellings;
+    return new Map([...claims].map(([spelling, { option }]) => [spelling, option]));
+}
+/**
+ * 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);
@@ -96,20 +200,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 +237,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,28 +257,52 @@ 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".
+ * The scan stops at a global value option, because the letters after it may be the value the
+ * operator meant to pass: the token then belongs to the globals, and parsing reports the
+ * value-position fault that names that option alone.
  */
 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 = '';
     let other = '';
     for (let index = 0; index < group.length; index += 1) {
         const letter = group.charAt(index);
-        if (spellings.has(`-${letter}`)) {
+        const option = spellings.get(`-${letter}`);
+        if (option) {
             global = global === '' ? letter : global;
+            if (option.type === 'string') {
+                break;
+            }
         }
         else {
             other = other === '' ? letter : other;
@@ -177,52 +317,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

@@ -4,7 +4,7 @@ import type { RenderingPolicy } from './rendering.js';
 import type { Palette } from './style-state.js';
 import type { ActionChannel, Host, OpenResult, Out, ResultBinding, ViewContext } from './types.js';
 import type { ViewRegistry } from './view.js';
-type WriteState = {
+export type WriteState = {
     kind: 'ok';
 } | {
     kind: 'failed';
@@ -19,6 +19,7 @@ export declare class Output {
     private readonly signal;
     private readonly destinations;
     private renderFault;
+    private readonly viewFaults;
     private readonly stops;
     private route;
     /**
@@ -26,6 +27,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;
@@ -54,7 +57,7 @@ export declare class Output {
     private resultFault;
     /** The registry one invocation resolves through, republished as each contributor is read. */
     useViews(registry: ViewRegistry): void;
-    /** The routed path, published once routing resolved it, which an incomplete sequence names. */
+    /** The path routing walked, updated as each name routes, which an incomplete sequence names. */
     useRoute(path: readonly string[]): void;
     /** What this invocation's output raised beside its calls, in the order it was raised. */
     get stopped(): readonly unknown[];
@@ -110,6 +113,12 @@ export declare class Output {
      * awaits the call must not end the process with an unhandled rejection.
      */
     private renderFailed;
+    /**
+     * Whether one value is what a view or a message check failed with during this invocation. A
+     * broken view is a defect in the code that broke the view contract, so an action or a source that
+     * lets its rejection propagate reports it as that defect.
+     */
+    raisedByView(value: unknown): boolean;
     /** What a view failed with during this invocation, if one did. */
     get fault(): {
         cause: unknown;