cli-kiss 0.1.8 → 0.2.0

package/src/lib/Usage.ts

@@ -12,6 +12,48 @@ import {
   TypoText,
 } from "./Typo";
 
+/**
+ * Converts a {@link CommandUsage} model into an array of styled lines ready to be
+ * joined with `"\n"` and printed to the terminal.
+ *
+ * The output format is:
+ * ```
+ * Usage: <cliName> [breadcrumbs...]
+ *
+ * <description> (<hint>)
+ * <detail lines...>
+ *
+ * Positionals:
+ *   <LABEL>  <description> (<hint>)
+ *
+ * Subcommands:
+ *   <name>  <description> (<hint>)
+ *
+ * Options:
+ *   -s, --long <LABEL>  <description> (<hint>)
+ *
+ * ```
+ * Sections that have no entries are omitted. The trailing empty line is always included.
+ *
+ * Column alignment within each section is handled by {@link TypoGrid}: the widest entry
+ * in each column sets the width for the entire section.
+ *
+ * @param params.cliName - The CLI program name shown at the start of the usage line.
+ * @param params.commandUsage - The usage model produced by {@link CommandFactory.generateUsage}.
+ * @param params.typoSupport - Controls color/styling of the output.
+ * @returns An ordered array of strings, one per output line (including a trailing
+ *   empty string for the blank line at the end).
+ *
+ * @example
+ * ```ts
+ * const lines = usageToStyledLines({
+ *   cliName: "my-cli",
+ *   commandUsage: commandFactory.generateUsage(),
+ *   typoSupport: TypoSupport.tty(),
+ * });
+ * process.stdout.write(lines.join("\n"));
+ * ```
+ */
 export function usageToStyledLines(params: {
   cliName: Lowercase<string>;
   commandUsage: CommandUsage;

package/tests/unit.runner.cycle.ts

@@ -9,7 +9,7 @@ import {
   positionalOptional,
   positionalRequired,
   positionalVariadics,
-  runAsCliAndExit,
+  runAndExit,
   typeConverted,
   typeOneOf,
   typeString,
@@ -324,7 +324,7 @@ async function testCase(
         ],
       },
       async () => {
-        onLogStdOut.call("Has executed root command");
+        console.log("Has executed root command");
       },
     ),
     {
@@ -359,17 +359,17 @@ async function testCase(
             ],
           },
           async () => {
-            onLogStdOut.call("Has executed subcommand");
+            console.log("Has executed subcommand");
           },
         ),
       ),
     },
   );
-  await runAsCliAndExit("my-cli", args, null, cmd, {
+  console.log = onLogStdOut.call;
+  console.error = onLogStdErr.call;
+  await runAndExit("my-cli", args, null, cmd, {
     buildVersion: "1.0.0",
     useTtyColors: false,
-    onLogStdOut: onLogStdOut.call,
-    onLogStdErr: onLogStdErr.call,
     onExit: onExit.call,
   });
   expect({

package/tests/unit.runner.errors.ts

@@ -5,7 +5,7 @@ import {
   optionFlag,
   optionRepeatable,
   optionSingleValue,
-  runAsCliAndExit,
+  runAndExit,
   typeNumber,
   typeUrl,
 } from "../src";
@@ -34,43 +34,43 @@ it("run", async () => {
 });
 
 async function testCase(args: Array<string>, error: string) {
+  const onLogStdOut = makeMocked<string, void>([]);
   const onLogStdErr = makeMocked<string, void>([null as unknown as void]);
   const onExit = makeMocked<number, never>([null as never]);
-  await runAsCliAndExit(
-    "my-cli",
-    args,
-    null,
-    command<void, void>(
-      { description: "" },
-      operation(
-        {
-          options: {
-            optionFlag: optionFlag({ long: "flag" }),
-            optionSingleValue: optionSingleValue({
-              label: "LOCATION",
-              long: "single-value",
-              type: typeUrl,
-              default: () => undefined,
-            }),
-            optionRepeatable: optionRepeatable({
-              label: "INDEX",
-              long: "repeatable",
-              type: typeNumber,
-            }),
-          },
-          positionals: [],
+  const rootCommand = command<void, void>(
+    { description: "" },
+    operation(
+      {
+        options: {
+          optionFlag: optionFlag({
+            long: "flag",
+          }),
+          optionSingleValue: optionSingleValue({
+            label: "LOCATION",
+            long: "single-value",
+            type: typeUrl,
+            default: () => undefined,
+          }),
+          optionRepeatable: optionRepeatable({
+            label: "INDEX",
+            long: "repeatable",
+            type: typeNumber,
+          }),
         },
-        async (_, _inputs) => {},
-      ),
+        positionals: [],
+      },
+      async () => {},
     ),
-    {
-      buildVersion: "1.0.0",
-      usageOnError: false,
-      useTtyColors: "mock",
-      onLogStdErr: onLogStdErr.call,
-      onExit: onExit.call,
-    },
   );
+  console.log = onLogStdOut.call;
+  console.error = onLogStdErr.call;
+  await runAndExit("my-cli", args, null, rootCommand, {
+    buildVersion: "1.0.0",
+    usageOnError: false,
+    useTtyColors: "mock",
+    onExit: onExit.call,
+  });
+  expect(onLogStdOut.history).toEqual([]);
   expect(onLogStdErr.history).toEqual([error]);
   expect(onExit.history).toEqual([1]);
 }