@starci/cli 1.0.1 → 1.2.0

package/src/validate-args.mjs

@@ -31,6 +31,95 @@ const typedValue = (flag, raw) => {
   return raw;
 };
 
+/** The values a list flag takes after its first one when the verb has no positional slot: every following token that is no option (`--knowledge a b c`), as the contracts write it. */
+const listTail = (argv, index, flag, verb) => {
+  if (flag.type !== 'list' || (verb.positional ?? []).length > 0) return [];
+  const tail = [];
+  while (index + 2 + tail.length < argv.length && !argv[index + 2 + tail.length].startsWith('-')) tail.push(argv[index + 2 + tail.length]);
+  return tail;
+};
+
+/** One `--name[=value]` token: type-check it into values/global, or pass it through to localArgs. */
+const applyOption = (argv, index, token, { known, internal, values, global, localArgs, verb }) => {
+  const name = optionName(token);
+  const flag = known.get(name);
+  if (!flag) throw new Error(internal.has(name) ? `unknown option --${name}: it is a call of the runtime itself, not a CLI option; ${internal.get(name)}` : `unknown option --${name}`);
+  const { value: raw, consumed } = optionValue(argv, index, flag, known);
+  const value = typedValue(flag, raw);
+  const tail = consumed ? listTail(argv, index, flag, verb) : [];
+  if (flag.type === 'list') {
+    values[name] = [...(values[name] ?? []), value, ...tail];
+  } else if (Object.hasOwn(values, name)) {
+    throw new Error(`--${name} may be given only once`);
+  } else {
+    values[name] = value;
+  }
+  if (flag.global) { global[name] = values[name]; }
+  else {
+    localArgs.push(token);
+    if (consumed) localArgs.push(argv[index + consumed]);
+    // each further value of a list flag reaches the handler as a repeated option, the form every list-flag handler parses
+    for (const extra of tail) localArgs.push(token, extra);
+  }
+  return consumed + tail.length;
+};
+
+/** Every required local option must have been given. */
+const requiredCheck = (locals, values) => {
+  for (const flag of locals.values()) {
+    if (flag.required && !Object.hasOwn(values, flag.name)) throw new Error(`missing required option --${flag.name}`);
+  }
+};
+
+/** The values one positional slot holds: a variadic slot's list, a single value, or none. */
+const candidatesOf = (supplied) => {
+  if (Array.isArray(supplied)) return supplied;
+  return supplied === undefined ? [] : [supplied];
+};
+
+/** A slot with an enum accepts only its members. */
+const checkEnum = (schema, candidates) => {
+  for (const candidate of candidates) {
+    if (schema.enum && !schema.enum.includes(candidate)) throw new Error(`${schema.name} expects one of: ${schema.enum.join(', ')}`);
+  }
+};
+
+/** Positional arity and enum checks; passthrough tokens fill free slots first. */
+const checkPositionals = (verb, positionals, passthrough) => {
+  const positionalSchema = verb.positional ?? [];
+  const variadicAt = positionalSchema.findIndex((entry) => entry.variadic === true);
+  const maximum = variadicAt >= 0 ? Infinity : positionalSchema.length;
+  if (positionals.length > maximum) throw new Error(`too many positional arguments for ${verb.verb ?? 'command'}`);
+  positionals.push(...passthrough.slice(0, Math.max(0, maximum - positionals.length)));
+  for (const [index, schema] of positionalSchema.entries()) {
+    const supplied = variadicAt === index ? positionals.slice(index) : positionals[index];
+    const empty = Array.isArray(supplied) ? supplied.length === 0 : supplied === undefined;
+    if (schema.required && empty) throw new Error(`missing required positional ${schema.name}`);
+    checkEnum(schema, candidatesOf(supplied));
+  }
+};
+
+/** Edition availability, --cwd emptiness and --json support. */
+const checkGlobals = (verb, global) => {
+  if (global.edition !== undefined && Array.isArray(verb.editions) && !verb.editions.includes(global.edition)) {
+    throw new Error(`${verb.group ?? 'this command'} ${verb.verb ?? ''}`.trim() + ` is not available in the ${global.edition} edition (editions: ${verb.editions.join(', ')})`);
+  }
+  if (global.cwd === '') throw new Error('--cwd needs a value');
+  if (global.json === true && verb.json === 'none') {
+    throw new Error(`${verb.group ?? 'this command'} ${verb.verb ?? ''}`.trim() + ' has no machine output');
+  }
+};
+
+/** args = supplied locals, else their declared defaults (a list flag's scalar default wraps in an array). */
+const defaultArgs = (locals, values) => {
+  const args = {};
+  for (const flag of locals.values()) {
+    if (Object.hasOwn(values, flag.name)) args[flag.name] = values[flag.name];
+    else if (flag.default !== undefined) args[flag.name] = flag.type === 'list' && !Array.isArray(flag.default) ? [flag.default] : flag.default;
+  }
+  return args;
+};
+
 /**
  * Validate the arguments after a catalog group and verb.
  *
@@ -43,6 +132,8 @@ export function validateArgs(argv, verb, globalFlags = []) {
   const globals = new Map(globalFlags.map((flag) => [flag.name, { ...flag, global: true }]));
   const locals = new Map((verb.flags ?? []).map((flag) => [flag.name, flag]));
   const known = new Map([...globals, ...locals]);
+  // Flags the runtime's own scripts take and the CLI refuses, each with the pointer a person is given instead.
+  const internal = new Map((verb.internalFlags ?? []).map((entry) => [entry.name, entry.pointer]));
   const values = {};
   const global = {};
   const localArgs = [];
@@ -64,24 +155,7 @@ export function validateArgs(argv, verb, globalFlags = []) {
         continue;
       }
       if (token.startsWith('--')) {
-        const name = optionName(token);
-        const flag = known.get(name);
-        if (!flag) throw new Error(`unknown option --${name}`);
-        const { value: raw, consumed } = optionValue(argv, index, flag, known);
-        const value = typedValue(flag, raw);
-        index += consumed;
-        if (flag.type === 'list') {
-          values[name] = [...(values[name] ?? []), value];
-        } else if (Object.hasOwn(values, name)) {
-          throw new Error(`--${name} may be given only once`);
-        } else {
-          values[name] = value;
-        }
-        if (flag.global) global[name] = values[name];
-        else {
-          localArgs.push(token);
-          if (consumed) localArgs.push(argv[index]);
-        }
+        index += applyOption(argv, index, token, { known, internal, values, global, localArgs, verb });
         continue;
       }
       if (token.startsWith('-')) throw new Error(`unknown option ${token}`);
@@ -89,41 +163,10 @@ export function validateArgs(argv, verb, globalFlags = []) {
       localArgs.push(token);
     }
 
-    for (const flag of locals.values()) {
-      if (flag.required && !Object.hasOwn(values, flag.name)) throw new Error(`missing required option --${flag.name}`);
-    }
-
-    const positionalSchema = verb.positional ?? [];
-    const variadicAt = positionalSchema.findIndex((entry) => entry.variadic === true);
-    const maximum = variadicAt >= 0 ? Infinity : positionalSchema.length;
-    if (positionals.length > maximum) throw new Error(`too many positional arguments for ${verb.verb ?? 'command'}`);
-    positionals.push(...passthrough.slice(0, Math.max(0, maximum - positionals.length)));
-    for (let index = 0; index < positionalSchema.length; index += 1) {
-      const schema = positionalSchema[index];
-      const supplied = variadicAt === index ? positionals.slice(index) : positionals[index];
-      const empty = Array.isArray(supplied) ? supplied.length === 0 : supplied === undefined;
-      if (schema.required && empty) throw new Error(`missing required positional ${schema.name}`);
-      const candidates = Array.isArray(supplied) ? supplied : supplied === undefined ? [] : [supplied];
-      for (const candidate of candidates) {
-        if (schema.enum && !schema.enum.includes(candidate)) {
-          throw new Error(`${schema.name} expects one of: ${schema.enum.join(', ')}`);
-        }
-      }
-    }
-
-    if (global.edition !== undefined && Array.isArray(verb.editions) && !verb.editions.includes(global.edition)) {
-      throw new Error(`${verb.group ?? 'this command'} ${verb.verb ?? ''}`.trim() + ` is not available in the ${global.edition} edition (editions: ${verb.editions.join(', ')})`);
-    }
-    if (global.cwd === '') throw new Error('--cwd needs a value');
-    if (global.json === true && verb.json === 'none') {
-      throw new Error(`${verb.group ?? 'this command'} ${verb.verb ?? ''}`.trim() + ' has no machine output');
-    }
-    const args = {};
-    for (const flag of locals.values()) {
-      if (Object.hasOwn(values, flag.name)) args[flag.name] = values[flag.name];
-      else if (flag.default !== undefined) args[flag.name] = flag.type === 'list' && !Array.isArray(flag.default) ? [flag.default] : flag.default;
-    }
-    return { ok: true, values, args, global, localArgs, positionals };
+    requiredCheck(locals, values);
+    checkPositionals(verb, positionals, passthrough);
+    checkGlobals(verb, global);
+    return { ok: true, values, args: defaultArgs(locals, values), global, localArgs, positionals };
   } catch (error) {
     return { ok: false, code: 2, error: String(error?.message ?? error) };
   }