cli-kiss 0.2.7 → 0.2.9

package/tests/unit.runner.cycle.ts

@@ -1,4 +1,4 @@
-import { it } from "@jest/globals";
+import { expect, it } from "@jest/globals";
 import {
   command,
   commandWithSubcommands,
@@ -10,23 +10,25 @@ import {
   positionalRequired,
   positionalVariadics,
   runAndExit,
-  type,
   typeChoice,
-  typeConverted,
+  typeMapped,
+  typeString,
   typeUrl,
 } from "../src";
 
 it("run", async function () {
   const rootUsage = [
-    "Usage: my-cli <required1> <subcommand>",
+    "Usage: my-cli <req1> <subcommand>",
     "",
-    "Root Description",
+    "Root Description (Hint for root)",
+    "Root details1",
+    "Root details2",
     "",
     "Positionals:",
-    "  <required1>  Required1 positional description",
+    "  <req1>  Required1 positional description (Hint for req1)",
     "",
     "Subcommands:",
-    "  subcommand  Subcommand Description",
+    "  sub  Subcommand Description (Hint for sub)",
     "",
     "Options:",
     "  -ff, --flag[=no]                    Option flag description",
@@ -34,14 +36,16 @@ it("run", async function () {
     "  -s,  --single-value <enum(number)>  Option single value description",
     "",
   ].join("\n");
-  const subcommandUsage = [
-    "Usage: my-cli <required1> subcommand <required2> [optional] [variadic]...",
+  const subUsage = [
+    "Usage: my-cli <req1> sub <req2> [optional] [variadic]...",
     "",
-    "Subcommand Description",
+    "Subcommand Description (Hint for sub)",
+    "Sub details1",
+    "Sub details2",
     "",
     "Positionals:",
-    "  <required1>    Required1 positional description",
-    "  <required2>    Required2 positional description",
+    "  <req1>         Required1 positional description (Hint for req1)",
+    "  <req2>         Required2 positional description",
     "  [optional]     Optional positional description",
     "  [variadic]...  Variadics positional description",
     "",
@@ -55,78 +59,64 @@ it("run", async function () {
 
   // Test that everything could work normally
   await testCase(
-    ["required1", "subcommand", "required2"],
-    ["Has executed root command", "Has executed subcommand"],
+    ["req1", "sub", "req2"],
+    ["Has executed root command", "Has executed sub"],
     [],
     0,
   );
 
   // Check that version flag takes precedence over execution
   await testCase(["--version"], ["my-cli 1.0.0"], [], 0);
-  await testCase(["required1", "--version"], ["my-cli 1.0.0"], [], 0);
-  await testCase(
-    ["required1", "subcommand", "--version"],
-    ["my-cli 1.0.0"],
-    [],
-    0,
-  );
-  await testCase(
-    ["required1", "subcommand", "required2", "--version"],
-    ["my-cli 1.0.0"],
-    [],
-    0,
-  );
+  await testCase(["req1", "--version"], ["my-cli 1.0.0"], [], 0);
+  await testCase(["req1", "sub", "--version"], ["my-cli 1.0.0"], [], 0);
+  await testCase(["req1", "sub", "req2", "--version"], ["my-cli 1.0.0"], [], 0);
 
   // Check that help flag takes precedence over execution
   await testCase(["--help"], [rootUsage], [], 0);
-  await testCase(["required1", "--help"], [rootUsage], [], 0);
-  await testCase(
-    ["required1", "subcommand", "--help"],
-    [subcommandUsage],
-    [],
-    0,
-  );
-  await testCase(
-    ["required1", "subcommand", "required2", "--help"],
-    [subcommandUsage],
-    [],
-    0,
-  );
+  await testCase(["req1", "--help"], [rootUsage], [], 0);
+  await testCase(["req1", "sub", "--help"], [subUsage], [], 0);
+  await testCase(["req1", "sub", "req2", "--help"], [subUsage], [], 0);
 
   // Help takes precedence over version
   await testCase(["--version", "--help"], [rootUsage], [], 0);
   await testCase(["--help", "--version"], [rootUsage], [], 0);
 
+  // Help still works after failed parsing (should show usage for the right command)
+  await testCase(["--invalid", "--help"], [rootUsage], [], 0);
+  await testCase(["invalid", "--help"], [rootUsage], [], 0);
+  await testCase(["req1", "sub", "--invalid", "--help"], [subUsage], [], 0);
+  await testCase(["req1", "sub", "invalid", "--help"], [subUsage], [], 0);
+
   // Weird help/version values inputs
   await testCase(
     ["--help=invalid"],
     [],
-    [rootUsage, `Error: --help: value: Not a boolean: "invalid"`],
+    [rootUsage, `Error: --help: value: Not a boolean: "invalid".`],
     1,
   );
   await testCase(
     ["--version=invalid"],
     [],
-    [rootUsage, `Error: --version: value: Not a boolean: "invalid"`],
+    [rootUsage, `Error: --version: value: Not a boolean: "invalid".`],
     1,
   );
 
   // Test multiple errors at once (first one should show only)
   await testCase(
-    ["--invalid1", "--invalid2", "required1", "--invalid3"],
+    ["--invalid1", "--invalid2", "req1", "--invalid3"],
     [],
     [
       rootUsage,
-      'Error: Unknown option: "--invalid1": did you mean: --single-value, --help, --version ?',
+      'Error: Unknown option: "--invalid1". Did you mean: --single-value, --help, --version, ... ?',
     ],
     1,
   );
   await testCase(
-    ["required1", "unknown", "-wut", "--flag", "--single-value"],
+    ["req1", "unknown", "-wut", "--flag", "--single-value"],
     [],
     [
       rootUsage,
-      'Error: <subcommand>: Unknown name: "unknown": did you mean: subcommand ?',
+      'Error: <subcommand>: Unknown name: "unknown". Did you mean: sub ?',
     ],
     1,
   );
@@ -135,121 +125,130 @@ it("run", async function () {
   await testCase(
     [],
     [],
-    [rootUsage, "Error: <required1>: Is required, but was not provided"],
+    [
+      rootUsage,
+      "Error: Missing argument: <req1>: Required1 positional description (Hint for req1)",
+    ],
     1,
   );
   await testCase(
-    ["required1"],
+    ["req1"],
     [],
-    [rootUsage, "Error: <subcommand>: Is required, but was not provided"],
+    [rootUsage, "Error: Missing argument: <subcommand>. Did you mean: sub ?"],
     1,
   );
   await testCase(
-    ["required1", "subcommand"],
+    ["req1", "sub"],
     [],
-    [subcommandUsage, "Error: <required2>: Is required, but was not provided"],
+    [
+      subUsage,
+      "Error: Missing argument: <req2>: Required2 positional description",
+    ],
     1,
   );
 
-  // Test that flags become available when subcommand is known
+  // Test that flags become available when sub is known
   await testCase(
     ["--url", "https://example.com"],
     [],
     [
       rootUsage,
-      'Error: Unknown option: "--url": did you mean: --help, -r, --version ?',
+      'Error: Unknown option: "--url". Did you mean: --help, -r, --version, ... ?',
     ],
     1,
   );
   await testCase(
-    ["required1", "--url", "https://example.com"],
+    ["req1", "--url", "https://example.com"],
     [],
     [
       rootUsage,
-      'Error: Unknown option: "--url": did you mean: --help, -r, --version ?',
+      'Error: Unknown option: "--url". Did you mean: --help, -r, --version, ... ?',
     ],
     1,
   );
   await testCase(
-    ["required1", "subcommand", "--url", "https://example.com"],
+    ["req1", "sub", "--url", "https://example.com"],
     [],
-    [subcommandUsage, "Error: <required2>: Is required, but was not provided"],
+    [
+      subUsage,
+      "Error: Missing argument: <req2>: Required2 positional description",
+    ],
     1,
   );
   await testCase(
-    ["required1", "subcommand", "required2", "--url", "https://example.com"],
-    ["Has executed root command", "Has executed subcommand"],
+    ["req1", "sub", "req2", "--url", "https://example.com"],
+    ["Has executed root command", "Has executed sub"],
     [],
     0,
   );
 
   // Test option as flag parsing cases
   await testCase(
-    ["--flag", "--flag", "required1", "subcommand", "required2"],
+    ["--flag", "--flag", "req1", "sub", "req2"],
     [],
-    [subcommandUsage, "Error: --flag: Must not be set multiple times"],
+    [subUsage, "Error: --flag: Must not be set multiple times."],
     1,
   );
   await testCase(
-    ["--flag=42", "required1", "subcommand", "required2"],
+    ["--flag=42", "req1", "sub", "req2"],
     [],
-    [subcommandUsage, 'Error: --flag: value: Not a boolean: "42"'],
+    [subUsage, 'Error: --flag: value: Not a boolean: "42".'],
     1,
   );
   await testCase(
-    ["--flag=no", "required1", "subcommand", "required2"],
-    ["Has executed root command", "Has executed subcommand"],
+    ["--flag=no", "req1", "sub", "req2"],
+    ["Has executed root command", "Has executed sub"],
     [],
     0,
   );
   await testCase(
-    ["--flag=yes", "required1", "subcommand", "required2"],
-    ["Has executed root command", "Has executed subcommand"],
+    ["--flag=yes", "req1", "sub", "req2"],
+    ["Has executed root command", "Has executed sub"],
     [],
     0,
   );
   await testCase(
-    ["--flag", "required1", "subcommand", "required2"],
-    ["Has executed root command", "Has executed subcommand"],
+    ["--flag", "req1", "sub", "req2"],
+    ["Has executed root command", "Has executed sub"],
     [],
     0,
   );
 
   // Test option parsing errors
   await testCase(
-    ["--invalid", "required1", "subcommand", "required2"],
+    ["--invalid", "req1", "sub", "req2"],
     [],
     [
       rootUsage,
-      'Error: Unknown option: "--invalid": did you mean: --single-value, --help, --flag ?',
+      'Error: Unknown option: "--invalid". Did you mean: --single-value, --help, --flag, ... ?',
     ],
     1,
   );
   await testCase(
-    ["required1", "subcommand", "required2", "--nope"],
+    ["req1", "sub", "req2", "--nope"],
     [],
     [
-      subcommandUsage,
-      'Error: Unknown option: "--nope": did you mean: --help, --flag, --repeatable ?',
+      subUsage,
+      'Error: Unknown option: "--nope". Did you mean: --help, --flag, --repeatable, ... ?',
     ],
     1,
   );
   await testCase(
-    ["required1", "subcommand", "required2", "--url"],
+    ["req1", "sub", "req2", "--url"],
     [],
-    [subcommandUsage, "Error: --url: Requires a value, but got end of input"],
+    [subUsage, "Error: --url: Requires a value, but got end of input."],
     1,
   );
   await testCase(
-    ["required1", "subcommand", "required2", "--url", "--", "url"],
+    ["req1", "sub", "req2", "--url", "--", "url"],
     [],
-    [subcommandUsage, 'Error: --url: Requires a value before "--"'],
+    [subUsage, 'Error: --url: Requires a value but got: "--".'],
     1,
   );
   await testCase(
-    ["required1", "subcommand", "required2", "--url", "--url"],
+    ["req1", "sub", "req2", "--url", "--url"],
     [],
-    [subcommandUsage, 'Error: --url: Requires a value, but got: "--url"'],
+    [subUsage, 'Error: --url: Requires a value, but got: "--url".'],
     1,
   );
 
@@ -257,163 +256,140 @@ it("run", async function () {
   await testCase(
     ["invalid"],
     [],
-    [rootUsage, "Error: <subcommand>: Is required, but was not provided"],
+    [rootUsage, "Error: Missing argument: <subcommand>. Did you mean: sub ?"],
     1,
   );
   await testCase(
-    ["invalid", "subcommand"],
+    ["invalid", "sub"],
     [],
     [
-      subcommandUsage,
-      'Error: <required1>: Unknown value: "invalid": did you mean: "required1-bis", "required1" ?',
+      subUsage,
+      'Error: <req1>: Unknown value: "invalid". Did you mean: "req1-bis", "req1" ?',
     ],
     1,
   );
   await testCase(
-    ["invalid", "subcommand", "required2"],
+    ["invalid", "sub", "req2"],
     [],
     [
-      subcommandUsage,
-      'Error: <required1>: Unknown value: "invalid": did you mean: "required1-bis", "required1" ?',
+      subUsage,
+      'Error: <req1>: Unknown value: "invalid". Did you mean: "req1-bis", "req1" ?',
     ],
     1,
   );
   await testCase(
-    ["required1", "subcommand", "invalid"],
+    ["req1", "sub", "invalid"],
     [],
     [
-      subcommandUsage,
-      'Error: <required2>: Unknown value: "invalid": did you mean: "required2-bis", "required2" ?',
+      subUsage,
+      'Error: <req2>: Unknown value: "invalid". Did you mean: "req2-bis", "req2" ?',
     ],
     1,
   );
   await testCase(
-    ["invalid", "subcommand", "invalid"],
+    ["invalid", "sub", "invalid"],
     [],
     [
-      subcommandUsage,
-      'Error: <required1>: Unknown value: "invalid": did you mean: "required1-bis", "required1" ?',
+      subUsage,
+      'Error: <req1>: Unknown value: "invalid". Did you mean: "req1-bis", "req1" ?',
     ],
     1,
   );
 
   // Test root command option invalid values (must not block parsing)
   await testCase(
-    ["--single-value=dodo", "required1", "subcommand", "required2"],
+    ["--single-value=dodo", "req1", "sub", "req2"],
     [],
     [
-      subcommandUsage,
-      'Error: --single-value: <enum(number)>: from: enum(string): Unknown value: "dodo": did you mean: "42", "43" ?',
+      subUsage,
+      'Error: --single-value: <enum(number)>: from: enum(string): Unknown value: "dodo". Did you mean: "42", "43" ?',
     ],
     1,
   );
   await testCase(
-    ["required1", "subcommand", "required2", "--single-value=44"],
+    ["req1", "sub", "req2", "--single-value=44"],
     [],
     [
-      subcommandUsage,
-      'Error: --single-value: <enum(number)>: from: enum(string): Unknown value: "44": did you mean: "42", "43" ?',
+      subUsage,
+      'Error: --single-value: <enum(number)>: from: enum(string): Unknown value: "44". Did you mean: "42", "43" ?',
     ],
     1,
   );
 
-  // Test subcommand-only option failures
+  // Test sub-only option failures
   await testCase(
-    ["--url", "not-a-url", "required1", "subcommand", "required2"],
+    ["--url", "not-a-url", "req1", "sub", "req2"],
     [],
     [
       rootUsage,
-      'Error: Unknown option: "--url": did you mean: --help, -r, --version ?',
+      'Error: Unknown option: "--url". Did you mean: --help, -r, --version, ... ?',
     ],
     1,
   );
   await testCase(
-    ["required1", "subcommand", "required2", "--url", "not-a-url"],
+    ["req1", "sub", "req2", "--url", "not-a-url"],
     [],
-    [subcommandUsage, 'Error: --url: <url>: Not an URL: "not-a-url"'],
+    [subUsage, 'Error: --url: <url>: Not an URL: "not-a-url".'],
     1,
   );
 
   // Test option multiple value parsing cases
   await testCase(
-    [
-      "required1",
-      "subcommand",
-      "required2",
-      "--repeatable=42",
-      "--repeatable",
-      "43",
-    ],
-    ["Has executed root command", "Has executed subcommand"],
+    ["req1", "sub", "req2", "--repeatable=42", "--repeatable", "43"],
+    ["Has executed root command", "Has executed sub"],
     [],
     0,
   );
   await testCase(
-    [
-      "required1",
-      "subcommand",
-      "required2",
-      "--single-value=42",
-      "--single-value",
-      "43",
-    ],
+    ["req1", "sub", "req2", "--single-value=42", "--single-value", "43"],
     [],
-    [subcommandUsage, "Error: --single-value: Must not be set multiple times"],
+    [subUsage, "Error: --single-value: Must not be set multiple times."],
     1,
   );
 
   // Test suggestions
   await testCase(
-    ["required1", "subcommand", "required2", "-f"],
+    ["req1", "sub", "req2", "-f"],
     [],
-    [
-      subcommandUsage,
-      'Error: Unknown option: "-f": did you mean: -ff, -r, -s ?',
-    ],
+    [subUsage, 'Error: Unknown option: "-f". Did you mean: -ff, -r, -s, ... ?'],
     1,
   );
   await testCase(
-    ["required1", "subcommand", "required2", "-flag"],
+    ["req1", "sub", "req2", "-flag"],
     [],
-    [
-      subcommandUsage,
-      'Error: Unknown option: "-flag": did you mean: --flag, -ff, --single-value ?',
-    ],
+    [subUsage, 'Error: Unknown option: "-flag". Did you mean: --flag ?'],
     1,
   );
   await testCase(
-    ["required1", "subcommand", "required2", "--uri"],
+    ["req1", "sub", "req2", "--uri"],
     [],
-    [
-      subcommandUsage,
-      'Error: Unknown option: "--uri": did you mean: --url, --version, -r ?',
-    ],
+    [subUsage, 'Error: Unknown option: "--uri". Did you mean: --url ?'],
     1,
   );
   await testCase(
-    ["required1", "subcommand", "required2", "--single-"],
+    ["req1", "sub", "req2", "--single-"],
     [],
     [
-      subcommandUsage,
-      'Error: Unknown option: "--single-": did you mean: --single-value, --help, --flag ?',
+      subUsage,
+      'Error: Unknown option: "--single-". Did you mean: --single-value ?',
     ],
     1,
   );
   await testCase(
-    ["required-bis1", "subcommand", "required2"],
+    ["1req", "sub", "req2"],
     [],
     [
-      subcommandUsage,
-      'Error: <required1>: Unknown value: "required-bis1": did you mean: "required1-bis", "required1" ?',
+      subUsage,
+      'Error: <req1>: Unknown value: "1req". Did you mean: "req1", "req1-bis" ?',
     ],
     1,
   );
   await testCase(
-    ["required1", "subcomm"],
+    ["req1", "subcomm"],
     [],
     [
       rootUsage,
-      'Error: <subcommand>: Unknown name: "subcomm": did you mean: subcommand ?',
+      'Error: <subcommand>: Unknown name: "subcomm". Did you mean: sub ?',
     ],
     1,
   );
@@ -435,7 +411,11 @@ async function testCase(
   ]);
   const onExit = makeMocked<number, never>([null as never]);
   const cmd = commandWithSubcommands<null, void, void>(
-    { description: "Root Description" },
+    {
+      description: "Root Description",
+      hint: "Hint for root",
+      details: ["Root details1", "Root details2"],
+    },
     operation(
       {
         options: {
@@ -447,25 +427,26 @@ async function testCase(
           optionRepeatable: optionRepeatable({
             long: "repeatable",
             short: "r",
-            type: type(),
+            type: typeString(),
             description: "Option repeatable description",
           }),
           optionSingleValue: optionSingleValue({
             long: "single-value",
             short: "s",
-            type: typeConverted(
+            type: typeMapped(
               "enum(number)",
               typeChoice("enum(string)", ["42", "43"]),
               (value) => Number(value),
             ),
             description: "Option single value description",
-            defaultIfNotSpecified: () => 42,
+            fallbackValueIfAbsent: () => 42,
           }),
         },
         positionals: [
           positionalRequired({
-            type: typeChoice("required1", ["required1", "required1-bis"]),
+            type: typeChoice("req1", ["req1", "req1-bis"]),
             description: "Required1 positional description",
+            hint: "Hint for req1",
           }),
         ],
       },
@@ -474,8 +455,12 @@ async function testCase(
       },
     ),
     {
-      subcommand: command(
-        { description: "Subcommand Description" },
+      sub: command(
+        {
+          description: "Subcommand Description",
+          hint: "Hint for sub",
+          details: ["Sub details1", "Sub details2"],
+        },
         operation(
           {
             options: {
@@ -488,22 +473,22 @@ async function testCase(
             },
             positionals: [
               positionalRequired({
-                type: typeChoice("required2", ["required2", "required2-bis"]),
+                type: typeChoice("req2", ["req2", "req2-bis"]),
                 description: "Required2 positional description",
               }),
               positionalOptional({
-                type: type("optional"),
+                type: typeString("optional"),
                 description: "Optional positional description",
                 default: () => "world !",
               }),
               positionalVariadics({
-                type: type("variadic"),
+                type: typeString("variadic"),
                 description: "Variadics positional description",
               }),
             ],
           },
           async function (_, _inputs) {
-            console.log(`Has executed subcommand`);
+            console.log(`Has executed sub`);
           },
         ),
       ),