feat: [Command] apply implied options

Signed-off-by: Lexus Drumgold <[email protected]>

Author: unicornware

README.md

@@ -127,6 +127,8 @@
     - [`Parseable#variadic`](#parseablevariadic)
   - [`VersionOption(info)`](#versionoptioninfo)
     - [`VersionOption#version`](#versionoptionversion)
+  - [`keid`](#keid)
+  - [`optionValueSource`](#optionvaluesource)
 - [Types](#types)
   - [`Action`](#action)
   - [`ArgumentData`](#argumentdata)
@@ -170,16 +172,18 @@
   - [`OptionMetadata`](#optionmetadata)
   - [`OptionPriority`](#optionpriority)
   - [`OptionValueSourceMap`](#optionvaluesourcemap)
-  - [`OptionValueSource`](#optionvaluesource)
+  - [`OptionValueSource`](#optionvaluesource-1)
   - [`OptionValueSources`](#optionvaluesources)
   - [`OptionsData`](#optionsdata)
   - [`ParseArg`](#parsearg)
   - [`ParseOptions`](#parseoptions)
+  - [`ParseUnknownResult`](#parseunknownresult)
   - [`ParseableInfo`](#parseableinfo-1)
   - [`ParseableMetadata`](#parseablemetadata)
   - [`ProcessEnv`](#processenv)
   - [`Process`](#process)
   - [`RawOptionValue`](#rawoptionvalue)
+  - [`RawParseValue`](#rawparsevalue)
   - [`SubcommandInfo`](#subcommandinfo)
   - [`SubcommandsData`](#subcommandsdata)
   - [`SubcommandsInfo`](#subcommandsinfo)
@@ -703,7 +707,7 @@ Emit a parsed `option` event.
   — the command option instance
 - `value` ([`RawOptionValue`](#rawoptionvalue))
   — the raw `option` value
-- `source` ([`OptionValueSource`](#optionvaluesource))
+- `source` ([`OptionValueSource`](#optionvaluesource-1))
   — the source of the raw option `value`
 - `flag?` ([`Flags`](#flags), optional)
   — the parsed `option` flag
@@ -951,7 +955,7 @@ Get or set an option value.
   — option key
 - `value` (`unknown`)
   — the parsed option value to store
-- `source` ([`OptionValueSource`](#optionvaluesource) | `null` | `undefined`)
+- `source` ([`OptionValueSource`](#optionvaluesource-1) | `null` | `undefined`)
   — the source of the original option value
 
 ##### Returns
@@ -971,12 +975,12 @@ Get or set an option value source.
 
 - `key` ([`Option['key']`](#optionkey))
   — option key
-- `source` ([`OptionValueSource`](#optionvaluesource) | `null` | `undefined`, optional)
+- `source` ([`OptionValueSource`](#optionvaluesource-1) | `null` | `undefined`, optional)
   — the source of the option value
 
 ##### Returns
 
-([`OptionValueSource`](#optionvaluesource) | [`this`](#commandinfo) | `null` | `undefined`)
+([`OptionValueSource`](#optionvaluesource-1) | [`this`](#commandinfo) | `null` | `undefined`)
 Option value source for `key` or `this` command
 
 #### `Command#options([infos])`
@@ -1424,6 +1428,9 @@ when `this` option is passed, but the implied option is not.
 
 Lone keys (string `implies`) imply `true`, i.e. `{ [implies]: true }`.
 
+The option-argument [`parser`](#parseableparserparser) will be called for implied values
+that are strings and string arrays.
+
 ##### Overloads
 
 - `implies(implies: OptionValues | string | null | undefined): this`
@@ -1531,10 +1538,17 @@ Get the option as a human-readable string.
 
 A parsed option event (`class`).
 
+> 👉 **Note**: For options where the `source` is `'implied'`, the `value` may not be a raw option value.
+
 #### Extends
 
 - [`KronkEvent`](#kronkeventid)
 
+#### Signatures
+
+- `constructor(option: T, value: RawOptionValue, source: OptionValueSource, flag?: Flags | null | undefined)`
+- `constructor(option: T, value: unknown, source: optionValueSource.implied, flag?: Flags | null | undefined)`
+
 ##### Type Parameters
 
 - `T` ([`Option`](#optioninfo), optional)
@@ -1545,9 +1559,9 @@ A parsed option event (`class`).
 - `option` (`T`)
   — the command option instance
 - `value` ([`RawOptionValue`](#rawoptionvalue))
-  — the raw `option` value
-- `source` ([`OptionValueSource`](#optionvaluesource))
-  — the source of the raw option `value`
+  — the `option` value
+- `source` ([`OptionValueSource`](#optionvaluesource-1))
+  — the source of the option `value`
 - `flag` ([`Flags`](#flags), optional)
   — the parsed `option` flag
 
@@ -1571,7 +1585,7 @@ The command [`option`](#optioninfo) instance.
 
 #### `OptionEvent#source`
 
-[`OptionValueSource`](#optionvaluesource)
+[`OptionValueSource`](#optionvaluesource-1)
 
 The source of the raw option [`value`](#optioneventvalue).
 
@@ -1652,13 +1666,13 @@ Get or set the handler used to parse candidate-arguments.
 ##### Overloads
 
 - `parser(parser: ParseArg<any, any> | null | undefined): this`
-- `parser<T, V extends string | string[] = string | string[]>(): ParseArg<T, V>`
+- `parser<T, Value extends RawParseValue = RawParseValue>(): ParseArg<T, Value>`
 
 ##### Type Parameters
 
 - `T` (`any`)
   — parse result
-- `V` (`string | string[]`, optional)
+- `Value` ([`RawParseValue`](#rawparsevalue), optional)
   — the argument or arguments to parse
 
 ##### Parameters
@@ -1668,7 +1682,7 @@ Get or set the handler used to parse candidate-arguments.
 
 ##### Returns
 
-([`ParseArg<T, V>`](#parsearg) | [`this`](#parseableinfo)) The candidate-argument parser or `this` candidate
+([`ParseArg<T, Value>`](#parsearg) | [`this`](#parseableinfo)) The candidate-argument parser or `this` candidate
 
 #### `Parseable#required`
 
@@ -1712,6 +1726,44 @@ A command version option (`class`).
 
 The version of the command.
 
+### `keid`
+
+Default error ids (`const enum`).
+
+```ts
+const enum keid {
+  argument_after_variadic = 'kronk/argument-after-variadic',
+  conflicting_option = 'kronk/conflicting-option',
+  duplicate_option = 'kronk/duplicate-option',
+  duplicate_subcommand = 'kronk/duplicate-subcommand',
+  error = 'kronk/error',
+  excess_arguments = 'kronk/excess-arguments',
+  invalid_argument = 'kronk/invalid-argument',
+  invalid_argument_syntax = 'kronk/invalid-argument-syntax',
+  invalid_flags = 'kronk/invalid-flags',
+  invalid_subcommand_name = 'kronk/invalid-subcommand-name',
+  missing_argument = 'kronk/missing-argument',
+  missing_mandatory_option = 'kronk/missing-mandatory-option',
+  no_flags = 'kronk/no-flags',
+  unknown_implied_option = 'kronk/unknown-implied-option',
+  unknown_option = 'kronk/unknown-option'
+}
+```
+
+### `optionValueSource`
+
+Default option value sources (`const enum`).
+
+```ts
+const enum optionValueSource {
+  cli = 'cli',
+  config = 'config',
+  default = 'default',
+  env = 'env',
+  implied = 'implied'
+}
+```
+
 ## Types
 
 This package is fully typed with [TypeScript][].
@@ -2321,14 +2373,16 @@ Data transfer object for command options (TypeScript interface).
   an error will be displayed if conflicting options are found during parsing
 - `env?` ([`List<string>`](#list) | `string`, optional)
   — the name of the environment variable to check for option value, or a list of names, in order of priority, to check
+- `implies?` ([`OptionValues`](#optionvalues) | `string`, optional)
+  — the key of an implied option, or a map where each key is an implied option key and each value is the value to use
+  when the option is set but the implied option is not.\
+  lone keys imply (string `implies`) `true`, i.e. `{ [implies]: true }`.\
+  the option-argument [`parser`](#parseableparserparser) will be called for implied values
+  that are strings and string arrays
 - `mandatory?` (`boolean`, optional)
   — whether the option is mandatory. mandatory options must have a value after parsing, which usually means the option
   must be specified on the command line
   - default: `false`
-- `implies?` ([`OptionValues`](#optionvalues) | `string`, optional)
-  — the key of an implied option, or a map where each key is an implied option key and each value is the value to use
-  when the option is set but the implied option is not.\
-  lone keys imply (string `implies`) `true`, i.e. `{ [implies]: true }`
 - `preset?` (`string`, optional)
   — for boolean and optional options, the preset to use when the option is specified without an option-argument.
   > 👉 **note**: the option-argument `parser` will be called.
@@ -2467,7 +2521,7 @@ type OptionValueSource = OptionValueSourceMap[keyof OptionValueSourceMap]
 ### `OptionValueSources`
 
 Record, where each key is an option key ([`Option.key`](#optioninfo))
-and each value is an [`OptionValueSource`](#optionvaluesource) (TypeScript type).
+and each value is an [`OptionValueSource`](#optionvaluesource-1) (TypeScript type).
 
 ```ts
 type OptionValueSources = {
@@ -2505,7 +2559,7 @@ type OptionsData =
 Parse a command or option argument `value` (TypeScript type).
 
 ```ts
-type ParseArg<T = any, Value extends string | string[] = string | string[]> = (
+type ParseArg<T = any, Value extends RawParseValue = RawParseValue> = (
   this: void,
   value: Value,
   previous: T | undefined
@@ -2516,7 +2570,7 @@ type ParseArg<T = any, Value extends string | string[] = string | string[]> = (
 
 - `T` (`any`, optional)
   — parse result
-- `Value` (`string | string[]`, optional)
+- `Value` ([`RawParseValue`](#rawparsevalue), optional)
   — the argument or arguments to parse
 
 #### Parameters
@@ -2541,6 +2595,17 @@ Options for parsing command-line arguments (TypeScript interface).
 - `from?` ([`ArgvSource`](#argvsource), optional)
   — the source of the command line arguments
 
+### `ParseUnknownResult`
+
+The result of parsing unknown arguments (TypeScript interface).
+
+#### Properties
+
+- `operands` (`string[]`)
+  — list of arguments that are operands (not options or values)
+- `unknown` (`string[]`)
+  — list containing the first unknown option and any remaining unknown arguments
+
 ### `ParseableInfo`
 
 Data used to create parse candidates (TypeScript interface).
@@ -2613,6 +2678,14 @@ Union of raw option value types (TypeScript type).
 type RawOptionValue = boolean | string | string[] | null
 ```
 
+### `RawParseValue`
+
+The argument or arguments passed to an argument [parser](#parseableparserparser) (TypeScript type).
+
+```ts
+type RawParseValue = string | readonly string[]
+```
+
 ### `SubcommandInfo`
 
 Data used to create subcommands (TypeScript interface).

__fixtures__/commands/grease-bad.mts

@@ -0,0 +1,28 @@
+/**
+ * @file Command Fixtures - greaseBad
+ * @module fixtures/commands/greaseBad
+ */
+
+import grease from '#fixtures/commands/grease'
+import type { SubcommandInfo as CommandInfo } from '@flex-development/kronk'
+
+/**
+ * `grease` program info with invalid configurations.
+ *
+ * @type {CommandInfo}
+ */
+export default Object.assign({}, grease, {
+  options: grease.options.map(info => {
+    if (!info.flags.endsWith('--json')) return info
+    return { ...info, implies: { LEVEL: 'log' } }
+  }),
+  subcommands: Object.assign({}, grease.subcommands, {
+    info: {
+      ...grease.subcommands.info,
+      options: grease.subcommands.info.options.map(info => {
+        if (!info.flags.endsWith('--markdown')) return info
+        return { ...info, implies: { logLevel: 'log' } }
+      })
+    }
+  })
+})

src/enums/keid.mts

@@ -6,12 +6,10 @@
 import type { KronkErrorId } from '@flex-development/kronk'
 
 /**
- * Kronk error ids.
+ * Default error ids.
  *
  * @see {@linkcode KronkErrorId}
  *
- * @internal
- *
  * @enum {KronkErrorId}
  */
 const enum keid {
@@ -28,6 +26,7 @@ const enum keid {
   missing_argument = 'kronk/missing-argument',
   missing_mandatory_option = 'kronk/missing-mandatory-option',
   no_flags = 'kronk/no-flags',
+  unknown_implied_option = 'kronk/unknown-implied-option',
   unknown_option = 'kronk/unknown-option'
 }
 

src/enums/option-value-source.mts

@@ -14,7 +14,8 @@ const enum optionValueSource {
   cli = 'cli',
   config = 'config',
   default = 'default',
-  env = 'env'
+  env = 'env',
+  implied = 'implied'
 }
 
 export default optionValueSource

src/events/option.event.mts

@@ -7,6 +7,7 @@ import KronkEvent from '#events/kronk.event'
 import type {
   Flags,
   Option,
+  optionValueSource,
   OptionValueSource,
   RawOptionValue
 } from '@flex-development/kronk'
@@ -54,9 +55,56 @@ class OptionEvent<T extends Option = Option> extends KronkEvent {
    * @param {Flags | null | undefined} [flag]
    *  The parsed `option` flag
    */
+  constructor(
+    option: T,
+    value: RawOptionValue,
+    source: OptionValueSource,
+    flag?: Flags | null | undefined
+  )
+
+  /**
+   * Create a new implied `option` event.
+   *
+   * @see {@linkcode Flags}
+   * @see {@linkcode optionValueSource}
+   *
+   * @param {T} option
+   *  The command option instance
+   * @param {unknown} value
+   *  The implied `option` value
+   * @param {optionValueSource.implied} source
+   *  The source of the option `value`
+   * @param {Flags | null | undefined} [flag]
+   *  The parsed `option` flag
+   */
+  constructor(
+    option: T,
+    value: unknown,
+    source: optionValueSource.implied,
+    flag?: Flags | null | undefined
+  )
+
+  /**
+   * Create a new parsed `option` event.
+   *
+   * > 👉 **Note**: For options where the `source` is `'implied'`, the `value`
+   * > may not be a raw option value.
+   *
+   * @see {@linkcode Flags}
+   * @see {@linkcode OptionValueSource}
+   *
+   * @param {T} option
+   *  The command option instance
+   * @param {unknown} value
+   *  The raw or implied `option` value
+   * @param {OptionValueSource} source
+   *  The source of the option `value`
+   * @param {Flags | null | undefined} [flag]
+   *  The parsed `option` flag
+   */
   constructor(
     public option: T,
-    public value: RawOptionValue,
+    public value: unknown,
     public source: OptionValueSource,
     public flag?: Flags | null | undefined
   ) {