@clo4/cli 1.0.0 → 3.0.0

package/dist/testing.d.ts

@@ -34,13 +34,22 @@ type CommandPath = readonly [Spec, ...Subcommand[]];
 interface OptionArgs {
   /** Escape hatch: the underlying map of option names to values. */
   readonly options: Map<string, string[]>;
-  /** Get every argument supplied to a option. */
+  /**
+   * Get every argument supplied to a option, or the defaults of its arguments
+   * if it wasn't supplied.
+   */
   all(name: string): string[] | undefined;
-  /** Get the first argument supplied to a option. */
+  /**
+   * Get the first argument supplied to a option, or the default of its first
+   * argument if it wasn't supplied.
+   */
   get(name: string): string | undefined;
-  /** Check whether a option was supplied. */
+  /** Check whether a option was supplied. Defaults don't count. */
   has(name: string): boolean;
-  /** Count option values, useful for repeatable options. */
+  /**
+   * Count option values, useful for repeatable options. It's 0 for an option
+   * that wasn't supplied, even if its arguments have defaults.
+   */
   count(name: string): number;
 }
 /** The data an action receives. */
@@ -62,7 +71,8 @@ interface ActionInit {
     /** Suggest the closest choice for an incorrect input. */
     didYouMean?: {
       input: string;
-      choices: readonly string[];
+      /** Names to suggest. The names in one array are one command or option. */
+      choices: readonly (string | readonly string[])[];
     };
     /** Alternative command path to render help for. */
     path?: NonEmptyArray<Subcommand>;
@@ -99,14 +109,31 @@ interface Subcommand {
     optionsMustPrecedeArguments?: boolean;
     /** Separators that can attach a option argument to a option token. */
     optionArgSeparators?: SingleOrArrayOrEmpty<string>;
-    /** Match subcommands by shortest unique prefix instead of exact name. */
+    /**
+     * Match subcommands by shortest unique prefix instead of exact name.
+     * Hidden subcommands still only match their exact name.
+     */
     subcommandsMatchUniquePrefix?: boolean;
   };
   /** Hide this command from help. */
   hidden?: true;
-  /** Require a subcommand; without one, print usage. */
+  /**
+   * Allow descendant commands to use this command as a subcommand too, like
+   * `{ ...helpCommand, isPersistent: true }`. There it only matches its exact
+   * name, a descendant's own subcommand with the same name wins, and help
+   * doesn't list it. Where a descendant takes positional arguments, its first
+   * argument can't be this command's name without `--` before it.
+   */
+  isPersistent?: true;
+  /**
+   * Require a subcommand, so the command takes no arguments. Without a
+   * subcommand, the command's action runs, or its help prints if it has none.
+   */
   requiresSubcommand?: true;
-  /** Action to run when this command is selected. */
+  /**
+   * Action to run when this command is selected. A command without an action
+   * prints its help.
+   */
   action?: Action;
   /**
    * This property never exists. It prevents accidental structural assignment
@@ -130,7 +157,12 @@ interface Option {
   hidden?: true;
   /** Only allow arguments to be supplied with a separator. */
   requiresSeparator?: true | string;
-  /** Allow this option to be supplied multiple times. */
+  /**
+   * Allow this option to be supplied multiple times. `true` allows any number
+   * of uses, and a number is the most uses allowed. An option with arguments
+   * collects the values from every use, in order. Without arguments, each use
+   * adds an empty string, so `count()` returns the number of uses.
+   */
   isRepeatable?: true | number;
   /** Require this option to be supplied before the selected action runs. */
   isRequired?: true;
@@ -176,9 +208,8 @@ interface Suggestion {
 /**
  * Generates dynamic completion suggestions.
  *
- * Generators run by re-invoking the CLI's hidden `completion
- * generate-suggestions` command, so `custom` executes in the CLI's own
- * process. Completions only — no effect on parsing.
+ * `custom` runs inside the CLI when the shell asks it for completions. It only
+ * affects completion and has no effect on parsing.
  */
 interface Generator {
   /** Produce suggestions from the current command-line tokens. */
@@ -188,12 +219,29 @@ interface Generator {
 interface Arg {
   /** Name shown in generated help. */
   name?: string;
-  /** Description for documentation or future help output. */
+  /**
+   * Description shown in help. A command's positional arguments are listed
+   * with their descriptions and defaults. An option argument's description
+   * isn't shown.
+   */
   description?: string;
   /** Allow this argument to take unlimited values. */
   isVariadic?: true;
   /** Allow this argument to be omitted. */
   isOptional?: true;
+  /**
+   * The value used when this argument is left out.
+   *
+   * - A positional argument's default is added to `args`, so the argument
+   *   must be optional.
+   * - An optional option argument's default is added when the option is used
+   *   without it, so a bare `--inspect` can mean `--inspect=9229`.
+   * - A required option argument's default is what `get` and `all` return
+   *   when the option isn't used. `has` and `count` still say it wasn't.
+   *
+   * Help shows an option's defaults after its description.
+   */
+  default?: string;
   /** Completions: complete file or folder paths for this argument. */
   template?: Template;
   /** Completions: static suggestions offered while typing this argument. */
@@ -203,36 +251,48 @@ interface Arg {
 }
 /** Asserts that required arguments do not come after an optional argument */
 export declare function assertRequiredArgumentsDoNotFollowOptionalArguments(spec: Subcommand): void;
-/** Asserts that options with `isRepeatable: true` don't have arguments */
-export declare function assertRepeatableOptionsHaveNoArguments(spec: Subcommand): void;
+/**
+ * Asserts that the parser can use every default. A positional argument with a
+ * default must be optional. A required option argument's default is only used
+ * when the option is left out, so every argument before it needs a default
+ * too, and the option can't be required.
+ */
+export declare function assertDefaultsCanBeUsed(spec: Subcommand): void;
 /** Asserts that `isRepeatable` is only assigned a positive integer */
 export declare function assertRepeatableOptionsArePositiveIntegers(spec: Subcommand): void;
 /** Asserts that options have unique names in their scope */
 export declare function assertOptionsHaveLocallyUniqueNames(spec: Subcommand): void;
 /** Asserts that options don't shadow a persistent option */
 export declare function assertOptionsDoNotShadowPersistentOptions(spec: Subcommand): void;
-/** Asserts that subcommands don't share a name with a sibling subcommand */
-export declare function assertSubcommandsHaveLocallyUniqueNames(spec: Subcommand): void;
-/**
- * Asserts that option names starting with a single dash aren't longer
- * than two characters, unless parserDirectives.flagsArePosixNoncompliant is
- * set on an ancestor command.
- */
-export declare function assertLongOptionNamesDoNotStartWithSingleDash(spec: Subcommand): void;
-/**
- * Asserts that all option names start with dashes
- */
-export declare function assertOptionNamesStartWithDashes(spec: Subcommand): void;
 /**
- * Asserts that nothing is named exactly '--'
+ * Asserts that when a subcommand's option and a different option on a parent
+ * share a name, each of them has a name of its own.
+ *
+ * Parsed values are looked up by name, and an option sets every one of its
+ * names when it's used. If every name of the parent's option is also the
+ * subcommand's, using the subcommand's option replaces the parent's value, so
+ * it can't be read. If every name of the subcommand's option is also the
+ * parent's, its names hold the parent's value when it isn't used, so it can't
+ * tell whether it was. Options with the same names are fine when they're
+ * identical, such as an option kept in a constant, because the parser treats
+ * them as one option.
+ *
+ * This skips persistent parent options, because
+ * {@link assertOptionsDoNotShadowPersistentOptions} covers those and
+ * `allowShadowingPersistentOptions` opts out of it.
  */
-export declare function assertNothingIsNamedDashDash(spec: Subcommand): void;
+export declare function assertOptionsHaveDifferentNamesFromParents(spec: Subcommand): void;
+/** Asserts that subcommands don't share a name with a sibling subcommand */
+export declare function assertSubcommandsHaveLocallyUniqueNames(spec: Subcommand): void;
 /**
  * Asserts that no option arg separator is an empty string
  */
 export declare function assertOptionArgSeparatorsHaveCharacters(spec: Subcommand): void;
 /**
- * Asserts that options named "+" or "-" takes one arg
+ * Asserts that the parser reads options named "+" or "-" the way they're
+ * written, which needs them to take one argument.
+ *
+ * @deprecated {@link assertNamesReadBack} checks this for every option.
  */
 export declare function assertPlusMinusOptionsTakeOneArg(spec: Subcommand): void;
 /**
@@ -247,11 +307,25 @@ export declare function assertEverythingHasDescription(spec: Subcommand): void;
  * Asserts that descriptions have line length < 69
  */
 export declare function assertDescriptionLineLengthUnder69(spec: Subcommand): void;
+/**
+ * Asserts that the parser reads options with `requiresSeparator` the way
+ * they're written, which needs them to take at most one argument.
+ *
+ * @deprecated {@link assertNamesReadBack} checks this for every option.
+ */
 export declare function assertRequiresSeparatorTakesOneArg(spec: Subcommand): void;
+/**
+ * Asserts that the parser reads every name the way it's written: each name of
+ * a subcommand enters that subcommand, and each name of an option uses that
+ * option, at every command the option can be used in. Each option is also
+ * written the way help shows it, with every value it takes, and the parser has
+ * to read all of those values as the option's.
+ */
+export declare function assertNamesReadBack(spec: Subcommand): void;
 export declare function assertCommonOptionsArePersistent(spec: Subcommand): void;
 /**
  * Asserts that references to other options by name actually refer to options
- * that exist in scope
+ * that exist in scope, at every command the option can be used in
  */
 export declare function assertOptionNameReferencesExist(spec: Subcommand): void;
 /**