cli-kiss 0.2.7 → 0.2.8

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,
@@ -20,15 +20,15 @@ import {
  */
 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;
 };
@@ -62,8 +62,8 @@ 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"]);
+const typeBooleanValuesTrue = new Set(["true", "yes", "on", "y"]);
+const typeBooleanValuesFalse = new Set(["false", "no", "off", "n"]);
 
 /**
  * Parses a date/time string via `Date.parse`.
@@ -94,7 +94,7 @@ export function typeDatetime(name?: string): Type<Date> {
 }
 
 /**
- * Parses a string to `number` via `Number()`; `NaN` throws {@link TypoError}.
+ * Parses a string to `number` via `Number()`; `NaN` throws.
  *
  * @example
  * ```ts
@@ -122,7 +122,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
@@ -146,7 +146,7 @@ export function typeInteger(name?: string): Type<bigint> {
 
 /**
  * Parses an absolute URL string to a `URL` object.
- * Relative or malformed URLs throw {@link TypoError}.
+ * Relative or malformed URLs throws.
  *
  * @example
  * ```ts
@@ -315,7 +315,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 +324,50 @@ 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);
     },
   };
 }
 
 /**
  * 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 +379,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 +400,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 +421,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,10 +432,9 @@ 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"]
  * ```
@@ -468,6 +466,7 @@ function throwInvalidValue(kind: string, input: string): never {
     new TypoText(
       new TypoString(`Not ${kind}: `),
       new TypoString(`"${input}"`, typoStyleQuote),
+      new TypoString(`.`),
     ),
   );
 }

package/src/lib/Typo.ts

@@ -1,5 +1,3 @@
-import { typeBooleanValuesFalse } from "./Type";
-
 /**
  * Color names for terminal styling, used by {@link TypoStyle}.
  * `dark*` = standard ANSI (30–37); `bright*` = high-intensity (90–97).
@@ -125,14 +123,14 @@ export const typoStyleRegularWeaker: TypoStyle = {
  */
 export class TypoString {
   #value: string;
-  #typoStyle: TypoStyle | undefined;
+  #style: TypoStyle | undefined;
   /**
    * @param value - Raw text content.
-   * @param typoStyle - Style to apply when rendering. Defaults to `undefined` (no style).
+   * @param style - Style to apply when rendering.
    */
-  constructor(value: string, typoStyle?: TypoStyle) {
+  constructor(value: string, style?: TypoStyle) {
     this.#value = value;
-    this.#typoStyle = typoStyle;
+    this.#style = style;
   }
   /**
    * Returns the text styled by `typoSupport`.
@@ -140,51 +138,75 @@ export class TypoString {
    * @param typoSupport - Rendering mode.
    */
   computeStyledString(typoSupport: TypoSupport): string {
-    return typoSupport.computeStyledString(this.#value, this.#typoStyle);
+    return typoSupport.computeStyledString(this.#value, this.#style);
   }
   /**
    * Returns the raw text.
    */
   getRawString(): string {
+    // TODO - should there be a global config or smthg instead of passing support everywhere?
     return this.#value;
   }
+  /**
+   * Predefined ellipsis segment with subtle styling.
+   */
+  static elipsis = new TypoString("...", typoStyleRegularWeaker);
 }
 
 /**
  * A segment of styled text, a string, or an array of segments.
  */
-export type TypoSegment = TypoText | TypoString | string | Array<TypoSegment>;
+export type TypoSegment = TypoText | TypoString | Array<TypoSegment>;
 
 /**
  * Mutable sequence of {@link TypoString} segments.
  */
 export class TypoText {
-  #typoStrings: Array<TypoString>;
+  #strings: Array<TypoString>;
   /**
    * @param segments - Initial text segments
    */
-  constructor(...segments: TypoSegment[]) {
-    this.#typoStrings = [];
+  constructor(...segments: Array<TypoSegment>) {
+    this.#strings = [];
     for (const segment of segments) {
       this.push(segment);
     }
   }
   /**
    * Appends new text segment(s).
-   *
-   * @param segment - Text segment(s) to append.
    */
-  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.push(typoString);
+  push(...segments: Array<TypoSegment>): void {
+    for (const segment of segments) {
+      if (typeof segment === "string") {
+        this.#strings.push(new TypoString(segment));
+      } else if (segment instanceof TypoString) {
+        this.#strings.push(segment);
+      } else if (segment instanceof TypoText) {
+        this.#strings.push(...segment.#strings);
+      } else if (Array.isArray(segment)) {
+        for (const part of segment) {
+          this.push(part);
+        }
+      }
+    }
+  }
+  /**
+   * Appends separated segments, optionally truncating with an ellipsis.
+   */
+  pushJoined(
+    segments: Array<TypoSegment>,
+    separator: TypoSegment,
+    ellipsisLimit: number,
+  ): void {
+    for (let index = 0; index < segments.length; index++) {
+      if (index > 0) {
+        this.push(separator);
+      }
+      if (ellipsisLimit !== undefined && index >= ellipsisLimit) {
+        this.push(TypoString.elipsis);
+        break;
       }
-    } else {
-      this.#typoStrings.push(segment);
+      this.push(segments[index]!);
     }
   }
   /**
@@ -194,7 +216,7 @@ export class TypoText {
    * @returns Concatenated styled string.
    */
   computeStyledString(typoSupport: TypoSupport): string {
-    return this.#typoStrings
+    return this.#strings
       .map((t) => t.computeStyledString(typoSupport))
       .join("");
   }
@@ -202,32 +224,18 @@ export class TypoText {
    * Returns the concatenated raw text.
    */
   computeRawString(): string {
-    return this.#typoStrings.map((t) => t.getRawString()).join("");
+    return this.#strings.map((t) => t.getRawString()).join("");
   }
   /**
    * Returns the total raw character count.
    */
   computeRawLength(): number {
     let length = 0;
-    for (const typoString of this.#typoStrings) {
+    for (const typoString of this.#strings) {
       length += typoString.getRawString().length;
     }
     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;
-  }
 }
 
 /**
@@ -377,15 +385,6 @@ export class TypoSupport {
    * Auto-detects styling mode from the process environment on best-effort basis.
    */
   static inferFromEnv(): TypoSupport {
-    /*
-    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();
     }
@@ -396,13 +395,17 @@ export class TypoSupport {
     if (envForceColor === "0") {
       return TypoSupport.none();
     }
-    if (envForceColor !== undefined) {
-      if (!typeBooleanValuesFalse.has(envForceColor.toLowerCase())) {
-        return TypoSupport.tty();
-      }
+    if (envForceColor === "1") {
+      return TypoSupport.tty();
+    }
+    if (envForceColor === "2") {
+      return TypoSupport.tty();
+    }
+    if (envForceColor === "3") {
+      return TypoSupport.tty(); // TODO - should there be fancy colors possible?
     }
-    if (readEnvVar("MOCK_COLOR")) {
-      return TypoSupport.mock();
+    if (envForceColor) {
+      return TypoSupport.tty();
     }
     if (!process.stdout.isTTY) {
       return TypoSupport.none();

package/src/lib/Usage.ts

@@ -93,7 +93,7 @@ export type UsageOption = {
   /**
    * Extra annotation appended to the option label in help.
    */
-  annotation?: string | undefined;
+  annotation?: string | undefined; // TODO - maybe prefix/postfix would be more useful
   /**
    * Help text.
    */
@@ -175,7 +175,7 @@ export function usageToStyledLines(params: {
   lines.push("");
   const introText = new TypoText();
   introText.push(textUsageText(usage.information.description));
-  if (usage.information.hint) {
+  if (usage.information.hint !== undefined) {
     introText.push(textDelimiter(" "));
     introText.push(textSubtleInfo(`(${usage.information.hint})`));
   }
@@ -221,7 +221,7 @@ export function usageToStyledLines(params: {
     for (const optionUsage of usage.options) {
       const typoGridRow = new Array<TypoText>();
       typoGridRow.push(new TypoText(textDelimiter("  ")));
-      if (optionUsage.short) {
+      if (optionUsage.short !== undefined) {
         typoGridRow.push(
           new TypoText(
             textConstants(`-${optionUsage.short}`),
@@ -234,11 +234,11 @@ export function usageToStyledLines(params: {
       const longOptionText = new TypoText(
         textConstants(`--${optionUsage.long}`),
       );
-      if (optionUsage.label) {
+      if (optionUsage.label !== undefined) {
         longOptionText.push(textDelimiter(" "));
         longOptionText.push(textUserInput(optionUsage.label));
       }
-      if (optionUsage.annotation) {
+      if (optionUsage.annotation !== undefined) {
         longOptionText.push(textSubtleInfo(optionUsage.annotation));
       }
       typoGridRow.push(longOptionText);
@@ -248,14 +248,14 @@ export function usageToStyledLines(params: {
     lines.push(...typoGrid.computeStyledLines(typoSupport));
   }
 
-  if (usage.information.examples) {
+  if (usage.information.examples !== undefined) {
     lines.push("");
     lines.push(textBlockTitle("Examples:").computeStyledString(typoSupport));
     for (const example of usage.information.examples) {
-      const exampleExplanationText = new TypoText();
-      exampleExplanationText.push(textDelimiter(" "));
-      exampleExplanationText.push(textSubtleInfo(`# ${example.explanation}`));
-      lines.push(exampleExplanationText.computeStyledString(typoSupport));
+      const explanationText = new TypoText();
+      explanationText.push(textDelimiter(" "));
+      explanationText.push(textSubtleInfo(`# ${example.explanation}`));
+      lines.push(explanationText.computeStyledString(typoSupport));
       const commandLineText = new TypoText();
       commandLineText.push(textDelimiter(" "));
       commandLineText.push(textConstants(cliName));
@@ -299,11 +299,11 @@ function createInformationals(usage: {
   hint?: string | undefined;
 }): Array<TypoText> {
   const informationals = [];
-  if (usage.description) {
+  if (usage.description !== undefined) {
     informationals.push(textDelimiter(" "));
     informationals.push(textUsefulInfo(usage.description));
   }
-  if (usage.hint) {
+  if (usage.hint !== undefined) {
     informationals.push(textDelimiter(" "));
     informationals.push(textSubtleInfo(`(${usage.hint})`));
   }