cli-kiss 0.2.7 → 0.2.9

package/src/lib/Suggest.ts

@@ -0,0 +1,78 @@
+import { TypoSegment, TypoString, TypoText } from "./Typo";
+
+export function suggestTextPushMessage(
+  text: TypoText,
+  query: string,
+  candidates: Array<{ reference: string; hint: TypoSegment }>,
+) {
+  const reasonableHints = suggestReasonablePayloads(
+    query,
+    candidates.map(({ reference, hint }) => ({ reference, payload: hint })),
+  );
+  if (reasonableHints.length === 0) {
+    return;
+  }
+  text.push(new TypoString(" Did you mean: "));
+  text.pushJoined(reasonableHints, new TypoString(", "), 3);
+  text.push(new TypoString(` ?`));
+}
+
+function suggestReasonablePayloads<Payload>(
+  query: string,
+  candidates: Array<{ reference: string; payload: Payload }>,
+): Array<Payload> {
+  if (candidates.length === 0) {
+    return [];
+  }
+  const sortedAlternatives = computeAndSortByDivergences(query, candidates);
+  const divergenceThreshold = sortedAlternatives[0]!.divergence + 0.25;
+  const acceptablePayloads = new Array<Payload>();
+  for (const { divergence, payload } of sortedAlternatives) {
+    if (divergence > divergenceThreshold) {
+      break;
+    }
+    acceptablePayloads.push(payload);
+  }
+  return acceptablePayloads;
+}
+
+function computeAndSortByDivergences<Payload>(
+  query: string,
+  candidates: Array<{ reference: string; payload: Payload }>,
+): Array<{ divergence: number; payload: Payload }> {
+  const queryNormalized = query.toLowerCase().slice(0, 100);
+  const scored = candidates.map(({ reference, payload }) => {
+    const referenceNormalized = reference.toLowerCase().slice(0, 100);
+    const divergence =
+      distanceDamerauLevenshtein(queryNormalized, referenceNormalized) /
+      Math.max(queryNormalized.length, referenceNormalized.length);
+    return { divergence, reference, payload };
+  });
+  return scored.sort((a, b) => a.divergence - b.divergence);
+}
+
+function distanceDamerauLevenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => Array<number>(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) {
+    dp[i]![0] = i;
+  }
+  for (let j = 0; j <= n; j++) {
+    dp[0]![j] = j;
+  }
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i]![j] = Math.min(
+        dp[i - 1]![j]! + 1,
+        dp[i]![j - 1]! + 1,
+        dp[i - 1]![j - 1]! + cost,
+      );
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        dp[i]![j] = Math.min(dp[i]![j]!, dp[i - 2]![j - 2]! + cost);
+      }
+    }
+  }
+  return dp[m]![n]!;
+}

package/src/lib/Type.ts

@@ -1,5 +1,5 @@
 import { statSync } from "fs";
-import { similaritySort } from "./Similarity";
+import { suggestTextPushMessage } from "./Suggest";
 import {
   TypoError,
   TypoString,
@@ -12,27 +12,54 @@ import {
  * Decodes a raw CLI string into a typed value.
  * A pair of a human-readable `content` name and a `decoder` function.
  *
- * Built-in: {@link type}, {@link typeBoolean}, {@link typeNumber},
- * {@link typeInteger}, {@link typeDatetime}, {@link typeUrl}.
- * Composite: {@link typeChoice}, {@link typeConverted}, {@link typeTuple}, {@link typeList}.
+ * Primitive Types:
+ * - {@link typeString}
+ * - {@link typeBoolean}
+ * - {@link typeNumber},
+ * - {@link typeInteger}
+ * - {@link typeDatetime}
+ * - {@link typeUrl}
+ * - {@link typePath}
+ * - {@link typeChoice}
+ *
+ * Composed Types:
+ * - {@link typeMapped}
+ * - {@link typeTuple}
+ * - {@link typeList}
  *
  * @typeParam Value - Type produced by the decoder.
  */
 export type Type<Value> = {
   /**
-   * Human-readable name shown in help and errors (e.g. `"name"`, `"number"`).
+   * Human-readable name shown in help and errors (e.g. `"name"`, `"context"`).
    */
-  content: string;
+  content: string; // TODO - add an enforcement mechanism for casing ?
   /**
    * Decodes a raw CLI string into `Value`.
    *
    * @param input - Raw string from the command line.
    * @returns The decoded value.
-   * @throws {@link TypoError} on invalid input.
+   * @throws on invalid input.
    */
   decoder(input: string): Value;
 };
 
+/**
+ * A named type that accepts any string as input.
+ * @param name - Name shown in help and errors (e.g. `"my-value"`).
+ * @example
+ * ```ts
+ * typeString("greeting").decoder("hello") // → "hello"
+ * typeString("greeting").decoder("")      // → ""
+ * ```
+ */
+export function typeString(name?: string): Type<string> {
+  return {
+    content: name ?? "string",
+    decoder: (input: string) => input,
+  };
+}
+
 /**
  * Decodes a string to `boolean` (case-insensitive).
  * Used by {@link optionFlag} for `--flag=<value>`.
@@ -41,10 +68,11 @@ export type Type<Value> = {
  * ```ts
  * typeBoolean("flag").decoder("true")  // → true
  * typeBoolean("flag").decoder("yes")   // → true
- * typeBoolean("flag").decoder("y")     // → true
- * typeBoolean("flag").decoder("false") // → false
- * typeBoolean("flag").decoder("no")    // → false
+ * typeBoolean("flag").decoder("Y")     // → true
+ * typeBoolean("flag").decoder("FALSE") // → false
+ * typeBoolean("flag").decoder("NO")    // → false
  * typeBoolean("flag").decoder("n")     // → false
+ * typeBoolean("flag").decoder("maybe") // throws
  * ```
  */
 export function typeBoolean(name?: string): Type<boolean> {
@@ -62,39 +90,9 @@ export function typeBoolean(name?: string): Type<boolean> {
     },
   };
 }
-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`.
- * Accepts any format supported by `Date.parse`, including ISO 8601.
- *
- * @example
- * ```ts
- * typeDatetime("my-datetime").decoder("2024-01-15") // → Date object for 2024-01-15
- * typeDatetime("my-datetime").decoder("2024-01-15T13:45:30Z") // → Date object for 2024-01-15 13:45:30 UTC
- * typeDatetime("my-datetime").decoder("not a date") // throws TypoError
- * ```
- */
-export function typeDatetime(name?: string): Type<Date> {
-  return {
-    content: name ?? "datetime",
-    decoder(input: string) {
-      try {
-        const timestampMs = Date.parse(input);
-        if (isNaN(timestampMs)) {
-          throw new Error();
-        }
-        return new Date(timestampMs);
-      } catch {
-        throwInvalidValue("a valid ISO_8601 datetime", input);
-      }
-    },
-  };
-}
 
 /**
- * Parses a string to `number` via `Number()`; `NaN` throws {@link TypoError}.
+ * Parses a string to `number` via `Number()`; `NaN` throws.
  *
  * @example
  * ```ts
@@ -122,7 +120,7 @@ export function typeNumber(name?: string): Type<number> {
 
 /**
  * Parses an integer string to `bigint` via `BigInt()`.
- * Floats and non-numeric strings throw {@link TypoError}.
+ * Floats and non-numeric strings throws.
  *
  * @example
  * ```ts
@@ -145,118 +143,68 @@ export function typeInteger(name?: string): Type<bigint> {
 }
 
 /**
- * Parses an absolute URL string to a `URL` object.
- * Relative or malformed URLs throw {@link TypoError}.
+ * Parses a date/time string via `Date.parse`.
+ * Accepts any format supported by `Date.parse`, including ISO 8601.
  *
  * @example
  * ```ts
- * typeUrl("my-url").decoder("https://example.com") // → URL { href: "https://example.com/", ... }
- * typeUrl("my-url").decoder("not-a-url")           // throws
+ * typeDatetime("start").decoder("2024-01-15") // → Date object for 2024-01-15
+ * typeDatetime("start").decoder("2024-01-15T13:45:30Z") // → Date object for 2024-01-15 13:45:30 UTC
+ * typeDatetime("start").decoder("not a date") // throws
  * ```
  */
-export function typeUrl(name?: string): Type<URL> {
+export function typeDatetime(name?: string): Type<Date> {
   return {
-    content: name ?? "url",
+    content: name ?? "datetime",
     decoder(input: string) {
       try {
-        return new URL(input);
+        const timestampMs = Date.parse(input);
+        if (isNaN(timestampMs)) {
+          throw new Error();
+        }
+        return new Date(timestampMs);
       } catch {
-        throwInvalidValue("an URL", input);
+        throwInvalidValue("a valid ISO_8601 datetime", input);
       }
     },
   };
 }
 
 /**
- * A named type that accepts any string as input.
- * @param name - Name shown in help and errors (e.g. `"my-value"`).
- * @example
- * ```ts
- * type("greeting").decoder("hello") // → "hello"
- * type("greeting").decoder("")      // → ""
- * ```
- */
-export function type(name?: string): Type<string> {
-  return {
-    content: name ?? "string",
-    decoder: (input: string) => input,
-  };
-}
-
-/**
- * Chains `before`'s decoder with an `after` transformation.
- * `before` errors are prefixed with `"from: <content>"` for traceability.
- *
- * @typeParam Before - Intermediate type from `before.decoder`.
- * @typeParam After - Final type from `after.decoder`.
- *
- * @param name - Name shown in help and errors (e.g. `"my-value"`).
- * @param before - Base type to decode the raw string.
- * @param mapper - Transforms `before`'s output to the final value; errors are wrapped with context.
- * @returns A {@link Type}`<After>`.
+ * Parses an absolute URL string to a `URL` object.
+ * Relative or malformed URLs throws.
  *
  * @example
  * ```ts
- * const typePort = typeConverted("port", typeNumber(), (n) => {
- *   if (n < 1 || n > 65535) throw new Error("Out of range");
- *   return n;
- * });
- * // "--port 8080"   →  8080
- * // "--port 99999"  →  TypoError: --port: <PORT>: Port: Out of range
+ * typeUrl("my-url").decoder("https://example.com") // → URL { href: "https://example.com/", ... }
+ * typeUrl("my-url").decoder("not-a-url")           // throws
  * ```
  */
-export function typeConverted<Before, After>(
-  name: string,
-  before: Type<Before>,
-  mapper: (value: Before) => After,
-): Type<After> {
-  return {
-    content: name,
-    decoder: (input: string) => {
-      return mapper(
-        TypoError.tryWithContext(
-          () => before.decoder(input),
-          () =>
-            new TypoText(
-              new TypoString("from: "),
-              new TypoString(before.content, typoStyleLogic),
-            ),
-        ),
-      );
-    },
-  };
-}
-
-/**
- * Adds a name to a {@link Type} for clearer error messages and help text.
- *
- * @param name - Name to use for the type.
- * @param type - Base type to name.
- * @returns A {@link Type} with the given name.
- */
-export function typeRenamed<Value>(
-  type: Type<Value>,
-  name: string,
-): Type<Value> {
+export function typeUrl(name?: string): Type<URL> {
   return {
-    content: name,
-    decoder: (input: string) => {
-      return TypoError.tryWithContext(
-        () => type.decoder(input),
-        () =>
-          new TypoText(
-            new TypoString("from: "),
-            new TypoString(type.content, typoStyleLogic),
-          ),
-      );
+    content: name ?? "url",
+    decoder(input: string) {
+      try {
+        return new URL(input);
+      } catch {
+        throwInvalidValue("an URL", input);
+      }
     },
   };
 }
 
 /**
  * Creates a {@link Type} for filesystem paths with optional existence checks.
+ *
  * @param checks - Optional checks for path existence and type (file/directory).
  * @returns A {@link Type}`<string>` representing the path.
+ *
+ * @example
+ * ```ts
+ * const typeInputFile = typePath("input-file", { checkSyncExistAs: "file" });
+ * typeInputFile.decoder("data.txt"); // → "data.txt" if it exists and is a file, otherwise throws
+ * typeInputFile.decoder("somedir");  // throws if "somedir" exists and is a directory
+ * ```
  */
 export function typePath(
   name?: string,
@@ -315,7 +263,6 @@ export function typePath(
 
 /**
  * Creates a {@link Type}`<string>` that only accepts a fixed set of values.
- * Out-of-set inputs throw {@link TypoError} listing up to 5 valid options.
  *
  * @param name - Name shown in help and errors.
  * @param values - Ordered list of accepted values.
@@ -325,52 +272,122 @@ export function typePath(
  * ```ts
  * const typeEnv = typeChoice("environment", ["dev", "staging", "prod"]);
  * typeEnv.decoder("prod")    // → "prod"
- * typeEnv.decoder("unknown") // throws TypoError: Invalid value: "unknown" (expected one of: "dev" | "staging" | "prod")
+ * typeEnv.decoder("unknown") // throws
  * ```
  */
 export function typeChoice<const Value extends string>(
   name: string,
   values: Array<Value>,
-  caseSensitive: boolean = false,
+  caseSensitive: boolean = true,
 ): 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 valueByNormalizedKey = new Map(
+    ? (input: string) => input
+    : (input: string) => input.toLowerCase();
+  const valueByNormalized = new Map(
     values.map((value) => [normalize(value), value]),
   );
   return {
     content: name,
     decoder(input: string) {
-      const normalizedKey = normalize(input);
-      const value = valueByNormalizedKey.get(normalizedKey);
+      const value = valueByNormalized.get(normalize(input));
       if (value !== undefined) {
         return value;
       }
-      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),
+      const errorText = new TypoText();
+      errorText.push(new TypoString(`Unknown value: `));
+      errorText.push(new TypoString(`"${input}"`, typoStyleQuote));
+      errorText.push(new TypoString(`.`));
+      suggestTextPushMessage(
+        errorText,
+        input,
+        values.map((value) => ({
+          reference: value,
+          hint: 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);
+      );
+      throw new TypoError(errorText);
+    },
+  };
+}
+
+/**
+ * Chains `before`'s decoder with an `after` transformation.
+ * `before` errors are prefixed with `"from: <content>"` for traceability.
+ *
+ * @typeParam Before - Intermediate type from `before.decoder`.
+ * @typeParam After - Final type from `after.decoder`.
+ *
+ * @param name - Name shown in help and errors (e.g. `"my-value"`).
+ * @param before - Base type to decode the raw string.
+ * @param mapper - Transforms `before`'s output to the final value; errors are wrapped with context.
+ * @returns A {@link Type}`<After>`.
+ *
+ * @example
+ * ```ts
+ * const typePort = typeMapped("port", typeNumber(), (n) => {
+ *   if (n < 1 || n > 65535) {
+ *     throw new Error("Out of range");
+ *   }
+ *   return n;
+ * });
+ * typePort.decoder("8080");  // → 8080
+ * typePort.decoder("70000"); // throws
+ * ```
+ */
+export function typeMapped<Before, After>(
+  name: string,
+  before: Type<Before>,
+  mapper: (value: Before) => After,
+): Type<After> {
+  return {
+    content: name,
+    decoder: (input: string) => {
+      return mapper(
+        TypoError.tryWithContext(
+          () => before.decoder(input),
+          () =>
+            new TypoText(
+              new TypoString("from: "),
+              new TypoString(before.content, typoStyleLogic),
+            ),
+        ),
+      );
+    },
+  };
+}
+
+/**
+ * Adds a name to a {@link Type} for clearer error messages and help text.
+ *
+ * @param name - Name to use for the type.
+ * @param type - Base type to name.
+ * @returns A {@link Type} with the given name.
+ */
+export function typeRenamed<Value>(
+  type: Type<Value>,
+  name: string,
+): Type<Value> {
+  return {
+    content: name,
+    decoder: (input: string) => {
+      return TypoError.tryWithContext(
+        () => type.decoder(input),
+        () =>
+          new TypoText(
+            new TypoString("from: "),
+            new TypoString(type.content, typoStyleLogic),
+          ),
+      );
     },
   };
 }
 
 /**
  * Splits a delimited string into a typed tuple.
- * Each part is decoded by the corresponding element type; wrong count or decode failure throws {@link TypoError}.
+ * Each part is decoded by the corresponding element type; wrong count or decode failure throws.
  *
  * @typeParam Elements - Tuple of decoded value types (inferred from `elementTypes`).
  *
@@ -382,8 +399,9 @@ export function typeChoice<const Value extends string>(
  * ```ts
  * const typePoint = typeTuple([typeNumber("x"), typeNumber("y")]);
  * typePoint.decoder("3.14,2.71") // → [3.14, 2.71]
- * typePoint.decoder("1,2,3")     // → [1, 2]
- * typePoint.decoder("x,2")       // throws TypoError: at 0: Number: Unable to parse: "x"
+ * typePoint.decoder("1")         // throws
+ * typePoint.decoder("1,2,3")     // throws
+ * typePoint.decoder("x,2")       // throws
  * ```
  */
 export function typeTuple<const Elements extends Array<any>>(
@@ -402,6 +420,7 @@ export function typeTuple<const Elements extends Array<any>>(
             new TypoString(`Found ${splits.length} splits: `),
             new TypoString(`Expected ${elementTypes.length} splits from: `),
             new TypoString(`"${input}"`, typoStyleQuote),
+            new TypoString(`.`),
           ),
         );
       }
@@ -422,7 +441,7 @@ export function typeTuple<const Elements extends Array<any>>(
 
 /**
  * Splits a delimited string into a typed array.
- * Each part is decoded by `elementType`; failed decodes throw {@link TypoError}.
+ * Each part is decoded by `elementType`; failed decodes throws.
  * Note: splitting an empty string yields one empty element — prefer {@link optionRepeatable} for a zero-default.
  *
  * @typeParam Value - Element type produced by `elementType.decoder`.
@@ -433,12 +452,13 @@ export function typeTuple<const Elements extends Array<any>>(
  *
  * @example
  * ```ts
- * const typeNumbers = typeList(typeNumber);
+ * const typeNumbers = typeList(typeNumber("v"));
  * typeNumbers.decoder("1,2,3")  // → [1, 2, 3]
- * typeNumbers.decoder("1,x,3")  // throws TypoError: at 1: Number: Unable to parse: "x"
- *
+ * typeNumbers.decoder("1,x,3")  // throws
  * const typePaths = typeList(typePath(), ":");
- * typePaths.decoder("/usr/bin:/usr/local/bin") // → ["/usr/bin", "/usr/local/bin"]
+ * typePaths.decoder("/bin:/usr") // → ["/bin", "/usr"]
+ * typePaths.decoder("/usr/bin")  // → ["/usr/bin"]
+ * typePaths.decoder("")          // → throws
  * ```
  */
 export function typeList<Value>(
@@ -468,6 +488,10 @@ function throwInvalidValue(kind: string, input: string): never {
     new TypoText(
       new TypoString(`Not ${kind}: `),
       new TypoString(`"${input}"`, typoStyleQuote),
+      new TypoString(`.`),
     ),
   );
 }
+
+const typeBooleanValuesTrue = new Set(["true", "yes", "on", "y"]);
+const typeBooleanValuesFalse = new Set(["false", "no", "off", "n"]);