@loomcli/core 0.7.0 → 0.8.0

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.
@@ -110,13 +128,19 @@ interface CommandGraph {
     readonly globals: readonly OptionNode[];
     readonly root: CommandNode;
 }
+/**
+ * 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 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,24 +1,20 @@
 import { asSentence, DeclarationError, InternalError, reasonOf } from './errors.js';
 import { partOf, siteFinding } from './facts.js';
 import { schemaConverterFailed } from './input-rules.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 declared default is wrapped, so `default: undefined` reads apart from no default at all. The
@@ -49,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 })
@@ -104,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) {
@@ -172,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 }))),
@@ -183,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),
     };
@@ -210,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 };