@loomcli/core 0.1.0

package/dist/errors.js

@@ -0,0 +1,261 @@
+/** The routed path names the Command a token fault belongs to; an empty path is the root. */
+function routedSentence(command) {
+    const name = command.at(-1);
+    return name === undefined ? 'The root Command' : commandSentence(name);
+}
+function shortGroupMessage(fault) {
+    return fault.reason === 'value-position'
+        ? `Value option "${fault.token}" must be last in its short group. Supply its value in the next token.`
+        : `Short group "${fault.token}" mixes the global option "-${fault.global}" with "-${fault.other}", which is not a global option. Supply global options as separate tokens, and local options after their command name.`;
+}
+/**
+ * Core's own text for one failure: its message under the category prefix its class carries, with
+ * the trailing newline every renderer's text carries. The four categories are disjoint branches of
+ * the hierarchy, so one ordered test reads every class, and a class without a prefix of its own
+ * writes the sentence alone. A default rendering is the same kind of value as a custom one, so
+ * nothing downstream composes the newline for it.
+ */
+function defaultText(failure) {
+    if (failure instanceof UsageError) {
+        return `Invalid input: ${failure.message}\n`;
+    }
+    if (failure instanceof DeclarationError) {
+        return `Invalid declaration: ${failure.message}\n`;
+    }
+    if (failure instanceof InternalError) {
+        return `Internal error: ${failure.message}\n`;
+    }
+    return `${failure.message}\n`;
+}
+/** Every prototype in a failure's chain, most derived first, so one walk reads the registry. */
+function chainOf(failure) {
+    const chain = [];
+    let prototype = Object.getPrototypeOf(failure);
+    while (prototype !== null) {
+        chain.push(prototype);
+        prototype = Object.getPrototypeOf(prototype);
+    }
+    return chain;
+}
+/** Authored registrations register here, so the public type publishes nothing to reach. */
+const nodes = new WeakMap();
+/** The runtime value `renderFailure` returns. Its pair lives in the registry above. */
+class RegisteredFailure {
+    constructor(registration) {
+        nodes.set(this, registration);
+    }
+}
+/** Reads the pair behind a registered value; anything else is a declaration error. */
+function nodeOf(value) {
+    const registration = nodes.get(value);
+    if (!registration) {
+        throw new DeclarationError('The Application holds a value that is not a failure renderer. Supply the value returned by renderFailure(type, renderer).');
+    }
+    return registration;
+}
+/** How a diagnostic names one Command inside a sentence: by name, or as the unnamed root. */
+export function commandSubject(name) {
+    return name === null ? 'the root Command' : `Command "${name}"`;
+}
+/** The same subject at the start of a sentence. */
+export function commandSentence(name) {
+    const subject = commandSubject(name);
+    return `${subject.slice(0, 1).toUpperCase()}${subject.slice(1)}`;
+}
+/**
+ * Every failure `run()` reports is an instance of a public class. Each class carries the facts its
+ * sentence interpolates, so a renderer reads them instead of parsing prose, and the exit status is
+ * a field of the base, so a subclass inherits it. `message` never carries a category prefix; the
+ * default renderers add it.
+ */
+export class LoomError extends Error {
+    exitCode;
+    constructor(message, exitCode) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = 'LoomError';
+    }
+}
+/** Exit 2: the invocation, not the application, is wrong. */
+export class UsageError extends LoomError {
+    constructor(message) {
+        super(message, 2);
+        this.name = 'UsageError';
+    }
+}
+/** The whole validation phase in authoring order, so one failure reports every rejected input. */
+export class InputError extends UsageError {
+    problems;
+    constructor(message, problems) {
+        super(message);
+        this.name = 'InputError';
+        this.problems = problems;
+    }
+}
+export class UnknownCommandError extends UsageError {
+    token;
+    candidates;
+    constructor(token, candidates) {
+        super(`Unknown command "${token}". Use one of: ${candidates.join(', ')}.`);
+        this.candidates = candidates;
+        this.name = 'UnknownCommandError';
+        this.token = token;
+    }
+}
+/** A group answers no invocation of its own, so the routed path names no callable Command. */
+export class NonCallableCommandError extends UsageError {
+    command;
+    candidates;
+    constructor(command, candidates) {
+        super(`${routedSentence(command)} requires a subcommand. Use one of: ${candidates.join(', ')}.`);
+        this.candidates = candidates;
+        this.command = command;
+        this.name = 'NonCallableCommandError';
+    }
+}
+export class UnexpectedArgumentError extends UsageError {
+    command;
+    accepted;
+    extra;
+    constructor(command, accepted, extra) {
+        super(accepted === 0
+            ? `${routedSentence(command)} accepts no arguments. Remove the supplied values.`
+            : `${routedSentence(command)} accepts ${accepted} ${accepted === 1 ? 'argument' : 'arguments'}. Remove the extra values.`);
+        this.accepted = accepted;
+        this.command = command;
+        this.extra = extra;
+        this.name = 'UnexpectedArgumentError';
+    }
+}
+export class UnknownOptionError extends UsageError {
+    spelling;
+    constructor(spelling) {
+        super(`Unknown option "${spelling}". Supply a declared option; prefix a hyphenated path with "./".`);
+        this.name = 'UnknownOptionError';
+        this.spelling = spelling;
+    }
+}
+export class MissingValueError extends UsageError {
+    spelling;
+    constructor(spelling) {
+        super(`Option "${spelling}" requires a value. Supply a value after "${spelling}".`);
+        this.name = 'MissingValueError';
+        this.spelling = spelling;
+    }
+}
+/** A Boolean spelling takes no value, so the token carried one the declaration cannot accept. */
+export class UnexpectedValueError extends UsageError {
+    spelling;
+    value;
+    constructor(spelling, value) {
+        super(`Boolean option "${spelling}" does not accept a value. Supply the flag alone.`);
+        this.name = 'UnexpectedValueError';
+        this.spelling = spelling;
+        this.value = value;
+    }
+}
+export class RepeatedOptionError extends UsageError {
+    spelling;
+    constructor(spelling) {
+        super(`Option "${spelling}" can be supplied only once. Remove the repeated option.`);
+        this.name = 'RepeatedOptionError';
+        this.spelling = spelling;
+    }
+}
+export class ShortGroupError extends UsageError {
+    token;
+    reason;
+    constructor(fault) {
+        super(shortGroupMessage(fault));
+        this.name = 'ShortGroupError';
+        this.reason = fault.reason;
+        this.token = fault.token;
+    }
+}
+/** Exit 1: the declaration is wrong, so the author reads the diagnostic. */
+export class DeclarationError extends LoomError {
+    constructor(message) {
+        super(message, 1);
+        this.name = 'DeclarationError';
+    }
+}
+/** Exit 1: the application ended the invocation itself. An application may subclass it. */
+export class FatalError extends LoomError {
+    constructor(message) {
+        super(message, 1);
+        this.name = 'FatalError';
+    }
+}
+/** Exit 1: an unexpected exception, a non-error throw, or a renderer that could not answer. */
+export class InternalError extends LoomError {
+    cause;
+    constructor(message, cause) {
+        super(message, 1);
+        this.cause = cause;
+        this.name = 'InternalError';
+    }
+}
+/** What a diagnostic says about an unexpected value, whether or not it was an Error. */
+export function reasonOf(thrown) {
+    return thrown instanceof Error ? thrown.message : 'An unknown error occurred.';
+}
+/**
+ * Why a returned value is not the text a renderer owes. A renderer is synchronous, so a returned
+ * promise is a non-string return like any other, and its rejection is adopted and swallowed here:
+ * an unobserved rejection would end the process before the invocation could report anything.
+ */
+export function notTextReason(value) {
+    void Promise.resolve(value).catch(() => undefined);
+    return `The renderer returned ${typeof value} instead of a string.`;
+}
+/** Every thrown value reaches reporting as a failure class; anything else is internal. */
+export function toFailure(thrown) {
+    return thrown instanceof LoomError ? thrown : new InternalError(reasonOf(thrown), thrown);
+}
+/**
+ * A registration pairing one failure class with a renderer for its instances. The helper is the
+ * typed path for a class-keyed list, because an array literal cannot carry a different type
+ * parameter per element.
+ */
+export function renderFailure(type, renderer) {
+    return new RegisteredFailure({
+        name: 'name' in type && typeof type.name === 'string' ? type.name : 'a failure class',
+        prototype: 'prototype' in type ? type.prototype : undefined,
+        // Resolution reaches this registration through the same class, so the test always holds.
+        render: (failure) => (failure instanceof type ? renderer.render(failure) : undefined),
+    });
+}
+/** One class answers to one renderer, so a second registration for it is a declaration fault. */
+export function buildFailures(failures) {
+    const registry = new Map();
+    for (const failure of failures) {
+        const registration = nodeOf(failure);
+        if (registry.has(registration.prototype)) {
+            throw new DeclarationError(`The Application registers two failure renderers for "${registration.name}". Remove one registration.`);
+        }
+        registry.set(registration.prototype, registration);
+    }
+    return registry;
+}
+/**
+ * The text core writes for one failure. Resolution walks the failure's prototype chain most
+ * derived first through the application's registrations, then falls to core's own text, so a
+ * registration for a base class brands every failure below it.
+ */
+export function describeFailure(registry, failure) {
+    const registration = chainOf(failure)
+        .map((prototype) => registry.get(prototype))
+        .find((entry) => entry !== undefined);
+    if (!registration) {
+        return { kind: 'rendered', text: defaultText(failure) };
+    }
+    try {
+        const text = registration.render(failure);
+        return typeof text === 'string'
+            ? { kind: 'rendered', text }
+            : { kind: 'unrendered', reason: notTextReason(text), text: defaultText(failure) };
+    }
+    catch (error) {
+        return { kind: 'unrendered', reason: reasonOf(error), text: defaultText(failure) };
+    }
+}

package/dist/globals.d.ts

@@ -0,0 +1,36 @@
+import { compileOptions } from './options.js';
+import type { DefaultConstraint, MultipleConstraint, NameConstraint, OptionConfig, OptionValue, ValidateOmittedConstraint } from './types.js';
+import type { InputDeclaration, ValidatedInputs } from './validation.js';
+/** Phantom key. It keeps the declared option types exact and holds no runtime value. */
+declare const declaredTypes: unique symbol;
+/** The compiled global table: one spelling map shared by every Command in the graph. */
+interface BuiltGlobals {
+    inputs: readonly InputDeclaration[];
+    names: ReadonlySet<string>;
+    options: ReturnType<typeof compileOptions>;
+    source: unknown;
+}
+declare class GlobalOptionsBuilder<Options> {
+    #private;
+    readonly [declaredTypes]: Options;
+    constructor(inputs: readonly InputDeclaration[], bind: (values: ValidatedInputs) => Options);
+    option<const Name extends string, const Config extends OptionConfig>(name: Name, config: Config & NameConstraint<Name> & NoInfer<DefaultConstraint<Config>> & NoInfer<MultipleConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): GlobalOptions<Options & Record<Name, OptionValue<Config>>>;
+}
+/**
+ * Application-wide options. `option()` is the whole authoring surface: it returns a new value and
+ * leaves its receiver unchanged. The value the declarations share is the application's globals.
+ * The declarations themselves stay private, so no consumer can read or replace them.
+ */
+type GlobalOptions<Options = {}> = Pick<GlobalOptionsBuilder<Options>, typeof declaredTypes | 'option'>;
+/**
+ * Whether a value is an authored GlobalOptions declaration, whichever call produced it. The
+ * registry is the test, because `option()` returns a new declaration of its own and the exported
+ * constructor is only the first of them.
+ */
+declare function isGlobalOptions(value: unknown): boolean;
+/** Absent globals compile to an empty table whose source is `undefined`, like the declarations. */
+declare function buildGlobals(globals: object | undefined): BuiltGlobals;
+declare function bindGlobals<Options>(globals: GlobalOptions<Options> | undefined, values: ValidatedInputs): Options;
+declare const GlobalOptions: new () => GlobalOptions;
+export type { BuiltGlobals };
+export { bindGlobals, buildGlobals, GlobalOptions, isGlobalOptions };

package/dist/globals.js

@@ -0,0 +1,71 @@
+import { DeclarationError } from './errors.js';
+import { compileOptions } from './options.js';
+import { captureConfig } from './validation.js';
+const globalSubject = 'the global options';
+/** Authored values register here, so the public type publishes no state to reach or replace. */
+const nodes = new WeakMap();
+function compileTable(inputs, source) {
+    return {
+        inputs,
+        names: new Set(inputs.map((input) => input.name)),
+        options: compileOptions(inputs.filter((input) => input.kind === 'option'), globalSubject),
+        source,
+    };
+}
+class GlobalOptionsBuilder {
+    #bind;
+    #inputs;
+    constructor(inputs, bind) {
+        this.#bind = bind;
+        this.#inputs = inputs;
+        nodes.set(this, { bind, build: () => compileTable(inputs, this) });
+    }
+    option(name, config) {
+        const input = {
+            config: captureConfig(config),
+            kind: 'option',
+            name,
+        };
+        const previous = this.#bind;
+        return new GlobalOptionsBuilder([...this.#inputs, input], (values) => ({
+            ...previous(values),
+            ...values.option(input),
+        }));
+    }
+}
+/** Reads the declarations behind an authored value; anything else is a declaration error. */
+function nodeOf(globals) {
+    const node = nodes.get(globals);
+    if (!node) {
+        throw new DeclarationError('The Application holds a value that is not a GlobalOptions declaration. Supply the value returned by new GlobalOptions().');
+    }
+    return node;
+}
+/**
+ * Whether a value is an authored GlobalOptions declaration, whichever call produced it. The
+ * registry is the test, because `option()` returns a new declaration of its own and the exported
+ * constructor is only the first of them.
+ */
+function isGlobalOptions(value) {
+    return typeof value === 'object' && value !== null && nodes.has(value);
+}
+/** Absent globals compile to an empty table whose source is `undefined`, like the declarations. */
+function buildGlobals(globals) {
+    return globals === undefined ? compileTable([], undefined) : nodeOf(globals).build();
+}
+function bindGlobals(globals, values) {
+    const bound = globals === undefined ? {} : nodeOf(globals).bind(values);
+    // Last resort: no typed path exists. The public GlobalOptions type hides its declarations.
+    // The registry is the only bridge from a value to its binder, and a WeakMap cannot carry the
+    // Options type of its key. It holds because the registered binder belongs to this value alone.
+    // Its record composes exactly the declarations that its Options type records.
+    // A declaration without globals publishes `Options = {}`, and the empty record is exactly that.
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+    return bound;
+}
+const GlobalOptions = class extends GlobalOptionsBuilder {
+    constructor() {
+        super([], () => ({}));
+    }
+};
+export { bindGlobals, buildGlobals, GlobalOptions, isGlobalOptions };

package/dist/host.d.ts

@@ -0,0 +1,3 @@
+import type { Writable } from 'node:stream';
+import type { Host, RunOptions } from './types.js';
+export declare function captureHost(overrides: RunOptions['host'], stderr: Writable): Host;

package/dist/host.js

@@ -0,0 +1,37 @@
+// Process stream declarations assume a terminal, but pipes omit isTTY at runtime.
+function isTerminal(stream) {
+    return stream.isTTY === true;
+}
+function dimension(value) {
+    return value === 0 ? undefined : value;
+}
+export function captureHost(overrides, stderr) {
+    const { argv, cwd, env, stdin, stdout, terminal } = overrides ?? {};
+    return {
+        argv: [...(argv ?? process.argv.slice(2))],
+        cwd: cwd ?? process.cwd(),
+        env: { ...(env ?? process.env) },
+        stderr,
+        stdin: stdin ?? process.stdin,
+        stdout: stdout ?? process.stdout,
+        terminal: terminal
+            ? {
+                stderr: { ...terminal.stderr },
+                stdin: { ...terminal.stdin },
+                stdout: { ...terminal.stdout },
+            }
+            : {
+                stderr: {
+                    columns: dimension(process.stderr.columns),
+                    isTTY: isTerminal(process.stderr),
+                    rows: dimension(process.stderr.rows),
+                },
+                stdin: { isTTY: isTerminal(process.stdin) },
+                stdout: {
+                    columns: dimension(process.stdout.columns),
+                    isTTY: isTerminal(process.stdout),
+                    rows: dimension(process.stdout.rows),
+                },
+            },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { Application } from './application.js';
+export { Command } from './command.js';
+export { validationContext, validationContextKey } from './context.js';
+export { DeclarationError, FatalError, InputError, InternalError, LoomError, MissingValueError, NonCallableCommandError, RepeatedOptionError, ShortGroupError, UnexpectedArgumentError, UnexpectedValueError, UnknownCommandError, UnknownOptionError, UsageError, renderFailure, } from './errors.js';
+export { GlobalOptions } from './globals.js';
+export { issuePath } from './validation.js';
+export type { StandardSchemaV1 } from '@standard-schema/spec';
+export type { ApplicationMethod, ApplicationOptions } from './application.js';
+export type { FailureRenderer, InputProblem } from './errors.js';
+export type { CommandMethod } from './command.js';
+export type { ArgumentNode, CommandGraph, CommandNode, OptionNode } from './inspect.js';
+export type { Action, ActionArgs, ActionContext, ActionHandler, ActionOptions, ArgumentConfig, BooleanOption, ExitCode, Host, InputIdentity, InputTerminal, Out, OptionConfig, OutputTerminal, Renderer, RunOptions, ScalarArgument, StringOption, SuppliedInputs, ValidationContext, VariadicArgument, } from './types.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { Application } from './application.js';
+export { Command } from './command.js';
+export { validationContext, validationContextKey } from './context.js';
+export { DeclarationError, FatalError, InputError, InternalError, LoomError, MissingValueError, NonCallableCommandError, RepeatedOptionError, ShortGroupError, UnexpectedArgumentError, UnexpectedValueError, UnknownCommandError, UnknownOptionError, UsageError, renderFailure, } from './errors.js';
+export { GlobalOptions } from './globals.js';
+export { issuePath } from './validation.js';

package/dist/inspect.d.ts

@@ -0,0 +1,61 @@
+import type { BuiltCommand } from './command.js';
+import type { BuiltGlobals } from './globals.js';
+/** One declared argument. `default` wraps the declared value, so an explicit `undefined` shows. */
+interface ArgumentNode {
+    readonly name: string;
+    readonly required: boolean;
+    readonly variadic: boolean;
+    readonly validated: boolean;
+    readonly validateOmitted: boolean;
+    readonly default: {
+        readonly value: unknown;
+    } | undefined;
+}
+/** One declared option, in the shape its type gives it. Spellings are the accepted CLI forms. */
+type OptionNode = {
+    readonly type: 'string';
+    readonly name: string;
+    readonly long: string | null;
+    readonly short: string | null;
+    readonly required: boolean;
+    readonly multiple: boolean;
+    readonly validated: boolean;
+    readonly validateOmitted: boolean;
+    readonly default: {
+        readonly value: unknown;
+    } | undefined;
+} | {
+    readonly type: 'boolean';
+    readonly name: string;
+    readonly long: string | null;
+    readonly short: string | null;
+    readonly negative: string | null;
+    readonly polarity: 'positive' | 'negative' | 'both';
+};
+/**
+ * One Command in the graph. `name` is `null` for the root, and `path` is its route from it.
+ * `aliases` holds the hidden aliases in declaration order, so a Command appears once, under its
+ * canonical name, and `path` never holds an alias.
+ */
+interface CommandNode {
+    readonly name: string | null;
+    readonly aliases: readonly string[];
+    readonly path: readonly string[];
+    readonly hasAction: boolean;
+    readonly arguments: readonly ArgumentNode[];
+    readonly options: readonly OptionNode[];
+    readonly children: readonly CommandNode[];
+}
+/** One built graph as plain data. The globals appear once here and in no `CommandNode`. */
+interface CommandGraph {
+    readonly name: string;
+    readonly globals: readonly OptionNode[];
+    readonly root: CommandNode;
+}
+/** Renders one built graph as frozen plain data. Nothing here reads a host fact or a schema. */
+declare function inspectGraph(name: string, graph: {
+    globals: BuiltGlobals;
+    root: BuiltCommand;
+}): CommandGraph;
+export type { ArgumentNode, CommandGraph, CommandNode, OptionNode };
+export { inspectGraph };

package/dist/inspect.js

@@ -0,0 +1,98 @@
+import { validatesOmission } from './validation.js';
+/**
+ * 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.
+ */
+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;
+}
+/** A structural value core can copy faithfully. Anything else is a library object it leaves alone. */
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/**
+ * A snapshot of one declared value. Arrays and plain objects are copied and frozen to any depth, so
+ * a consumer cannot reach the declaration through the graph, and a later call reports the declared
+ * value again. Primitives and library objects are reported as they are.
+ */
+function snapshot(value) {
+    if (Array.isArray(value)) {
+        return Object.freeze(value.map((entry) => snapshot(entry)));
+    }
+    if (isPlainObject(value)) {
+        return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, snapshot(entry)])));
+    }
+    return value;
+}
+/** 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;
+}
+function optionNode(input, table) {
+    const { config, name } = input;
+    const { long, negative, short } = spellingsOf(table, name);
+    const node = config.type === 'boolean'
+        ? { long, name, negative, polarity: config.polarity ?? 'positive', short, type: 'boolean' }
+        : {
+            default: declaredDefault(config),
+            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,
+            short,
+            type: 'string',
+            validateOmitted: validatesOmission(input),
+            validated: config.validate !== undefined,
+        };
+    return Object.freeze(node);
+}
+/** The built slots already answer presence and arity, so the node repeats no config reading. */
+function argumentNode(slot) {
+    const { config, name } = slot.input;
+    const node = {
+        default: declaredDefault(config),
+        name,
+        required: slot.required,
+        validateOmitted: validatesOmission(slot.input),
+        validated: config.validate !== undefined,
+        variadic: slot.variadic,
+    };
+    return Object.freeze(node);
+}
+function optionNodes(inputs, table) {
+    return Object.freeze(inputs.filter((input) => input.kind === 'option').map((input) => optionNode(input, table)));
+}
+function commandNode(command, path) {
+    const node = {
+        aliases: Object.freeze([...command.aliases]),
+        arguments: Object.freeze(command.arguments.map((slot) => argumentNode(slot))),
+        children: Object.freeze([...command.children].map(([name, child]) => commandNode(child, Object.freeze([...path, name])))),
+        hasAction: command.dispatch !== undefined,
+        name: command.name,
+        options: optionNodes(command.inputs, command.options),
+        path,
+    };
+    return Object.freeze(node);
+}
+/** Renders one built graph as frozen plain data. Nothing here reads a host fact or a schema. */
+function inspectGraph(name, graph) {
+    const inspected = {
+        globals: optionNodes(graph.globals.inputs, graph.globals.options),
+        name,
+        root: commandNode(graph.root, Object.freeze([])),
+    };
+    return Object.freeze(inspected);
+}
+export { inspectGraph };

package/dist/options.d.ts

@@ -0,0 +1,38 @@
+import type { OptionConfig } from './types.js';
+export interface OptionDeclaration {
+    name: string;
+    config: OptionConfig;
+}
+export interface OptionValues {
+    strings: Map<string, string>;
+    lists: Map<string, string[]>;
+    booleans: Map<string, boolean>;
+}
+/** 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 = {
+    type: 'string';
+    name: string;
+    multiple: boolean;
+} | {
+    type: 'boolean';
+    name: string;
+    value: boolean;
+};
+type OptionSpelling = OptionForm & {
+    role: SpellingRole;
+};
+export declare function compileOptions(declarations: readonly OptionDeclaration[], subject: string): Map<string, OptionSpelling>;
+/** Consumes global options anywhere before the passthrough delimiter and leaves the rest routable. */
+export declare function extractGlobals(spellings: ReadonlyMap<string, OptionSpelling>, tokens: readonly string[]): {
+    rest: string[];
+    values: 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;
+export declare function parseInputs(spellings: ReadonlyMap<string, OptionSpelling>, tokens: readonly string[]): {
+    options: OptionValues;
+    passthrough: string[];
+    positionals: string[];
+};
+export {};