cli-kiss 0.2.5 → 0.2.7

package/src/lib/Type.ts

@@ -1,4 +1,5 @@
 import { statSync } from "fs";
+import { similaritySort } from "./Similarity";
 import {
   TypoError,
   TypoString,
@@ -50,24 +51,19 @@ export function typeBoolean(name?: string): Type<boolean> {
   return {
     content: name ?? "boolean",
     decoder(input: string) {
-      const lower = input.toLowerCase();
-      if (booleanValuesTrue.has(lower)) {
+      const lowerInput = input.toLowerCase();
+      if (typeBooleanValuesTrue.has(lowerInput)) {
         return true;
       }
-      if (booleanValuesFalse.has(lower)) {
+      if (typeBooleanValuesFalse.has(lowerInput)) {
         return false;
       }
-      throw new TypoError(
-        new TypoText(
-          new TypoString(`Not a boolean: `),
-          new TypoString(`"${input}"`, typoStyleQuote),
-        ),
-      );
+      throwInvalidValue("a boolean", input);
     },
   };
 }
-const booleanValuesTrue = new Set(["true", "yes", "on", "1", "y", "t"]);
-const booleanValuesFalse = new Set(["false", "no", "off", "0", "n", "f"]);
+export const typeBooleanValuesTrue = new Set(["true", "yes", "on", "y"]);
+export const typeBooleanValuesFalse = new Set(["false", "no", "off", "n"]);
 
 /**
  * Parses a date/time string via `Date.parse`.
@@ -91,12 +87,7 @@ export function typeDatetime(name?: string): Type<Date> {
         }
         return new Date(timestampMs);
       } catch {
-        throw new TypoError(
-          new TypoText(
-            new TypoString(`Not a valid ISO_8601 datetime: `),
-            new TypoString(`"${input}"`, typoStyleQuote),
-          ),
-        );
+        throwInvalidValue("a valid ISO_8601 datetime", input);
       }
     },
   };
@@ -109,7 +100,7 @@ export function typeDatetime(name?: string): Type<Date> {
  * ```ts
  * typeNumber("my-number").decoder("3.14")  // → 3.14
  * typeNumber("my-number").decoder("-1")    // → -1
- * typeNumber("my-number").decoder("hello") // throws TypoError
+ * typeNumber("my-number").decoder("hello") // throws
  * ```
  */
 export function typeNumber(name?: string): Type<number> {
@@ -123,12 +114,7 @@ export function typeNumber(name?: string): Type<number> {
         }
         return parsed;
       } catch {
-        throw new TypoError(
-          new TypoText(
-            new TypoString(`Not a number: `),
-            new TypoString(`"${input}"`, typoStyleQuote),
-          ),
-        );
+        throwInvalidValue("a number", input);
       }
     },
   };
@@ -141,8 +127,8 @@ export function typeNumber(name?: string): Type<number> {
  * @example
  * ```ts
  * typeInteger("my-integer").decoder("42")   // → 42n
- * typeInteger("my-integer").decoder("3.14") // throws TypoError
- * typeInteger("my-integer").decoder("abc")  // throws TypoError
+ * typeInteger("my-integer").decoder("3.14") // throws
+ * typeInteger("my-integer").decoder("abc")  // throws
  * ```
  */
 export function typeInteger(name?: string): Type<bigint> {
@@ -152,12 +138,7 @@ export function typeInteger(name?: string): Type<bigint> {
       try {
         return BigInt(input);
       } catch {
-        throw new TypoError(
-          new TypoText(
-            new TypoString(`Not an integer: `),
-            new TypoString(`"${input}"`, typoStyleQuote),
-          ),
-        );
+        throwInvalidValue("an integer", input);
       }
     },
   };
@@ -170,7 +151,7 @@ export function typeInteger(name?: string): Type<bigint> {
  * @example
  * ```ts
  * typeUrl("my-url").decoder("https://example.com") // → URL { href: "https://example.com/", ... }
- * typeUrl("my-url").decoder("not-a-url")           // throws TypoError
+ * typeUrl("my-url").decoder("not-a-url")           // throws
  * ```
  */
 export function typeUrl(name?: string): Type<URL> {
@@ -180,12 +161,7 @@ export function typeUrl(name?: string): Type<URL> {
       try {
         return new URL(input);
       } catch {
-        throw new TypoError(
-          new TypoText(
-            new TypoString(`Not an URL: `),
-            new TypoString(`"${input}"`, typoStyleQuote),
-          ),
-        );
+        throwInvalidValue("an URL", input);
       }
     },
   };
@@ -296,7 +272,20 @@ export function typePath(
         throw new Error(`Path cannot contain null characters`);
       }
       if (checks?.checkSyncExistAs !== undefined) {
-        const stats = statSync(input);
+        function safeStatSync(path: string) {
+          try {
+            return statSync(path);
+          } catch (error) {
+            throw new TypoError(
+              new TypoText(
+                new TypoString(`Path does not exist: `),
+                new TypoString(`"${path}"`, typoStyleQuote),
+              ),
+              error,
+            );
+          }
+        }
+        const stats = safeStatSync(input);
         const preview = stats.isDirectory()
           ? "directory"
           : stats.isFile()
@@ -305,7 +294,7 @@ export function typePath(
         if (checks.checkSyncExistAs === "file" && !stats.isFile()) {
           throw new TypoError(
             new TypoText(
-              new TypoString(`Expected a 'file' but found '${preview}': `),
+              new TypoString(`Expected a file but found: ${preview}: `),
               new TypoString(`"${input}"`, typoStyleQuote),
             ),
           );
@@ -313,7 +302,7 @@ export function typePath(
         if (checks.checkSyncExistAs === "directory" && !stats.isDirectory()) {
           throw new TypoError(
             new TypoText(
-              new TypoString(`Expected a 'directory' but found '${preview}': `),
+              new TypoString(`Expected a directory but found: ${preview}: `),
               new TypoString(`"${input}"`, typoStyleQuote),
             ),
           );
@@ -344,38 +333,37 @@ export function typeChoice<const Value extends string>(
   values: Array<Value>,
   caseSensitive: boolean = false,
 ): Type<Value> {
+  if (values.length === 0) {
+    throw new Error("At least one value is required");
+  }
   const normalize = caseSensitive
     ? (s: string) => s
     : (s: string) => s.toLowerCase();
-  const valueMap = new Map(values.map((value) => [normalize(value), value]));
+  const valueByNormalizedKey = new Map(
+    values.map((value) => [normalize(value), value]),
+  );
   return {
     content: name,
     decoder(input: string) {
-      const normalized = normalize(input);
-      const original = valueMap.get(normalized);
-      if (original !== undefined) {
-        return original;
+      const normalizedKey = normalize(input);
+      const value = valueByNormalizedKey.get(normalizedKey);
+      if (value !== undefined) {
+        return value;
       }
-      const valuesPreview = [];
-      for (const value of values) {
-        if (valuesPreview.length >= 5) {
-          valuesPreview.push(new TypoString(`...`));
-          break;
-        }
-        if (valuesPreview.length > 0) {
-          valuesPreview.push(new TypoString(` | `));
-        }
-        valuesPreview.push(new TypoString(`"${value}"`, typoStyleQuote));
-      }
-      throw new TypoError(
-        new TypoText(
-          new TypoString(`Invalid value: `),
-          new TypoString(`"${input}"`, typoStyleQuote),
-          new TypoString(` (expected one of: `),
-          ...valuesPreview,
-          new TypoString(`)`),
-        ),
-      );
+      const text = new TypoText();
+      text.push(new TypoString(`Unknown value: `));
+      text.push(new TypoString(`"${input}"`, typoStyleQuote));
+      const suggestions = similaritySort(
+        normalizedKey,
+        [...valueByNormalizedKey.entries()].map(([normalizedKey, value]) => ({
+          key: normalizedKey,
+          value: new TypoString(`"${value}"`, typoStyleQuote),
+        })),
+      ).slice(0, 3);
+      text.push(new TypoString(`: did you mean: `));
+      text.push(TypoText.join(suggestions, new TypoString(`, `)));
+      text.push(new TypoString(` ?`));
+      throw new TypoError(text);
     },
   };
 }
@@ -474,3 +462,12 @@ export function typeList<Value>(
     },
   };
 }
+
+function throwInvalidValue(kind: string, input: string): never {
+  throw new TypoError(
+    new TypoText(
+      new TypoString(`Not ${kind}: `),
+      new TypoString(`"${input}"`, typoStyleQuote),
+    ),
+  );
+}

package/src/lib/Typo.ts

@@ -1,3 +1,5 @@
+import { typeBooleanValuesFalse } from "./Type";
+
 /**
  * Color names for terminal styling, used by {@link TypoStyle}.
  * `dark*` = standard ANSI (30–37); `bright*` = high-intensity (90–97).
@@ -123,12 +125,12 @@ export const typoStyleRegularWeaker: TypoStyle = {
  */
 export class TypoString {
   #value: string;
-  #typoStyle: TypoStyle;
+  #typoStyle: TypoStyle | undefined;
   /**
    * @param value - Raw text content.
-   * @param typoStyle - Style to apply when rendering. Defaults to `{}` (no style).
+   * @param typoStyle - Style to apply when rendering. Defaults to `undefined` (no style).
    */
-  constructor(value: string, typoStyle: TypoStyle = {}) {
+  constructor(value: string, typoStyle?: TypoStyle) {
     this.#value = value;
     this.#typoStyle = typoStyle;
   }
@@ -148,6 +150,11 @@ export class TypoString {
   }
 }
 
+/**
+ * A segment of styled text, a string, or an array of segments.
+ */
+export type TypoSegment = TypoText | TypoString | string | Array<TypoSegment>;
+
 /**
  * Mutable sequence of {@link TypoString} segments.
  */
@@ -156,12 +163,10 @@ export class TypoText {
   /**
    * @param segments - Initial text segments
    */
-  constructor(
-    ...segments: Array<TypoText | Array<TypoString> | TypoString | string>
-  ) {
+  constructor(...segments: TypoSegment[]) {
     this.#typoStrings = [];
-    for (const typoPart of segments) {
-      this.push(typoPart);
+    for (const segment of segments) {
+      this.push(segment);
     }
   }
   /**
@@ -169,14 +174,14 @@ export class TypoText {
    *
    * @param segment - Text segment(s) to append.
    */
-  push(segment: TypoText | Array<TypoString> | TypoString | string) {
+  push(segment: TypoSegment) {
     if (typeof segment === "string") {
       this.#typoStrings.push(new TypoString(segment));
     } else if (segment instanceof TypoText) {
       this.#typoStrings.push(...segment.#typoStrings);
     } else if (Array.isArray(segment)) {
       for (const typoString of segment) {
-        this.#typoStrings.push(typoString);
+        this.push(typoString);
       }
     } else {
       this.#typoStrings.push(segment);
@@ -209,6 +214,20 @@ export class TypoText {
     }
     return length;
   }
+  /**
+   * Joins multiple segments with a separator.
+   * @returns A new {@link TypoText} containing the joined segments.
+   */
+  static join(segments: Array<TypoSegment>, separator: TypoSegment): TypoText {
+    const result = new TypoText();
+    for (let index = 0; index < segments.length; index++) {
+      if (index > 0) {
+        result.push(separator);
+      }
+      result.push(segments[index]!);
+    }
+    return result;
+  }
 }
 
 /**
@@ -332,8 +351,8 @@ export class TypoError extends Error {
  * Controls ANSI terminal styling. Create via the static factory methods.
  */
 export class TypoSupport {
-  #kind: "none" | "tty" | "mock";
-  private constructor(kind: "none" | "tty" | "mock") {
+  #kind: TypoSupportKind;
+  private constructor(kind: TypoSupportKind) {
     this.#kind = kind;
   }
   /**
@@ -358,27 +377,38 @@ export class TypoSupport {
    * Auto-detects styling mode from the process environment on best-effort basis.
    */
   static inferFromEnv(): TypoSupport {
-    if (!process || !process.env) {
+    /*
+    console.warn({
+      no: readEnvVar("NO_COLOR"),
+      force: readEnvVar("FORCE_COLOR"),
+      mock: readEnvVar("MOCK_COLOR"),
+      term: readEnvVar("TERM"),
+      tty: process.stdout.isTTY,
+    });
+    */
+    if (!process || !process.env || !process.stdout) {
       return TypoSupport.none();
     }
-    function readEnvVar(name: string) {
-      if (!(name in process.env)) {
-        return undefined;
-      }
-      return process.env[name];
+    if (readEnvVar("NO_COLOR")) {
+      return TypoSupport.none();
     }
     const envForceColor = readEnvVar("FORCE_COLOR");
     if (envForceColor === "0") {
       return TypoSupport.none();
     }
     if (envForceColor !== undefined) {
-      TypoSupport.tty();
+      if (!typeBooleanValuesFalse.has(envForceColor.toLowerCase())) {
+        return TypoSupport.tty();
+      }
+    }
+    if (readEnvVar("MOCK_COLOR")) {
+      return TypoSupport.mock();
     }
-    if (readEnvVar("NO_COLOR") !== undefined) {
+    if (!process.stdout.isTTY) {
       return TypoSupport.none();
     }
-    if (readEnvVar("MOCK_COLOR") !== undefined) {
-      return TypoSupport.mock();
+    if (readEnvVar("TERM")?.toLowerCase() === "dumb") {
+      return TypoSupport.none();
     }
     return TypoSupport.tty();
   }
@@ -389,7 +419,10 @@ export class TypoSupport {
    * @param typoStyle - Style to apply.
    * @returns Styled string.
    */
-  computeStyledString(value: string, typoStyle: TypoStyle): string {
+  computeStyledString(value: string, typoStyle: TypoStyle | undefined): string {
+    if (typoStyle === undefined) {
+      return value;
+    }
     let styledValue = value;
     if (typoStyle.case === "upper") {
       styledValue = styledValue.toUpperCase();
@@ -496,3 +529,12 @@ const ttyCodeBgColors: Record<TypoColor, string> = {
   brightCyan: "\x1b[106m",
   brightWhite: "\x1b[107m",
 };
+
+function readEnvVar(name: string) {
+  if (!(name in process.env)) {
+    return undefined;
+  }
+  return process.env[name];
+}
+
+type TypoSupportKind = "none" | "tty" | "mock";

package/src/lib/Usage.ts

@@ -116,16 +116,16 @@ export type UsageOption = {
  * <detail lines...>
  *
  * Positionals:
- *   <LABEL>  <description> (<hint>)
+ *   <label>  <description> (<hint>)
  *
  * Subcommands:
  *   <name>  <description> (<hint>)
  *
  * Options:
- *   -s, --long <LABEL><annotation>  <description> (<hint>)
+ *   -s, --long <label><annotation>  <description> (<hint>)
  *
  * Examples:
- *   <description>
+ *   <explanation>
  *   <command line>
  *
  * ```
@@ -262,7 +262,7 @@ export function usageToStyledLines(params: {
       for (const commandArg of example.commandArgs) {
         commandLineText.push(textDelimiter(" "));
         if (typeof commandArg === "string") {
-          commandLineText.push(commandArg);
+          commandLineText.push(new TypoString(commandArg));
         } else if ("positional" in commandArg) {
           commandLineText.push(textUserInput(commandArg.positional));
         } else if ("subcommand" in commandArg) {

package/tests/unit.command.execute.ts

@@ -47,7 +47,7 @@ const rootCommand = commandChained(
           string: optionSingleValue({
             long: "string-option",
             type: type(),
-            defaultWhenNotDefined: () => undefined,
+            defaultIfNotSpecified: () => undefined,
           }),
           number: optionRepeatable({
             long: "number-option",

package/tests/unit.command.usage.ts

@@ -39,8 +39,8 @@ const rootCommand = commandChained<any, any, any>(
           long: "choice-option",
           type: typeChoice("choice", ["unset", "empty", "choice1", "choice2"]),
           description: "choice-option description",
-          defaultWhenNotInlined: () => "empty",
-          defaultWhenNotDefined: () => "unset",
+          valueIfNothingInlined: () => "empty",
+          defaultIfNotSpecified: () => "unset",
         }),
         booleanFlag: optionFlag({
           short: "b",
@@ -81,7 +81,7 @@ const rootCommand = commandChained<any, any, any>(
             short: "s",
             long: "string-option",
             type: type("cool-stuff"),
-            defaultWhenNotDefined: () => undefined,
+            defaultIfNotSpecified: () => undefined,
             description: "string-option description",
           }),
           complexOption: optionRepeatable({
@@ -174,7 +174,7 @@ const rootCommand = commandChained<any, any, any>(
               duduValue: optionSingleValue({
                 long: "dudu",
                 type: type("dudu-value"),
-                defaultWhenNotDefined: () => "duduDefault",
+                defaultIfNotSpecified: () => "duduDefault",
                 hint: "Dudu option hint",
                 description: "Dudu option description",
               }),

package/tests/unit.fuzzed.alternatives.ts

@@ -0,0 +1,34 @@
+import { it } from "@jest/globals";
+import { similaritySort } from "../src/lib/Similarity";
+
+it("run", async function () {
+  expect(
+    orderBySimilarity("--inst", ["--flag", "--blah", "--install"]),
+  ).toStrictEqual(["--install", "--flag", "--blah"]);
+
+  expect(
+    orderBySimilarity("instlal", ["install", "dudu", "--blah"]),
+  ).toStrictEqual(["install", "--blah", "dudu"]);
+
+  expect(
+    orderBySimilarity("cat", ["cats", "catz", "cut", "kat", "hello", "world"]),
+  ).toStrictEqual(["cats", "catz", "cut", "kat", "hello", "world"]);
+
+  expect(orderBySimilarity("cat", ["cut", "kat"])).toStrictEqual([
+    "cut",
+    "kat",
+  ]);
+
+  expect(orderBySimilarity("acb", ["abc", "ac", "ab"])).toStrictEqual([
+    "abc",
+    "ac",
+    "ab",
+  ]);
+});
+
+function orderBySimilarity(reference: string, candidates: Array<string>) {
+  return similaritySort(
+    reference,
+    candidates.map((key) => ({ key, value: key })),
+  );
+}