cli-kiss 0.1.8 → 0.2.0

package/src/lib/Type.ts

@@ -6,11 +6,53 @@ import {
   TypoText,
 } from "./Typo";
 
+/**
+ * Describes how to decode a raw CLI string token into a typed TypeScript value.
+ *
+ * A `Type` is a pair of:
+ * - a `content` string — a human-readable name shown in help/error messages (e.g.
+ *   `"String"`, `"Number"`, `"Url"`).
+ * - a `decoder` function — converts the raw string or throws a {@link TypoError} on
+ *   invalid input.
+ *
+ * Built-in types: {@link typeString}, {@link typeBoolean}, {@link typeNumber},
+ * {@link typeInteger}, {@link typeDate}, {@link typeUrl}.
+ *
+ * Composite types: {@link typeOneOf}, {@link typeConverted}, {@link typeTuple},
+ * {@link typeList}.
+ *
+ * @typeParam Value - The TypeScript type that the decoder produces.
+ */
 export type Type<Value> = {
+  /**
+   * Human-readable name for this type, used in help text and error messages.
+   * Examples: `"String"`, `"Number"`, `"Url"`.
+   */
   content: string;
+  /**
+   * Decodes a raw string token into a `Value`.
+   *
+   * @param value - The raw string from the command line.
+   * @returns The decoded value.
+   * @throws {@link TypoError} if the value cannot be decoded.
+   */
   decoder(value: string): Value;
 };
 
+/**
+ * A {@link Type} that decodes `"true"` / `"yes"` to `true` and `"false"` / `"no"` to
+ * `false` (case-insensitive). Any other value throws a {@link TypoError}.
+ *
+ * Primarily used internally by {@link optionFlag} for the `--flag=<value>` syntax, but
+ * can also be used in positionals or valued options.
+ *
+ * @example
+ * ```ts
+ * typeBoolean.decoder("yes")   // → true
+ * typeBoolean.decoder("false") // → false
+ * typeBoolean.decoder("1")     // throws TypoError
+ * ```
+ */
 export const typeBoolean: Type<boolean> = {
   content: "Boolean",
   decoder(value: string) {
@@ -30,6 +72,21 @@ export const typeBoolean: Type<boolean> = {
   },
 };
 
+/**
+ * A {@link Type} that parses a date/time string using `Date.parse`.
+ *
+ * Accepts any format supported by the JavaScript `Date.parse` API, including ISO 8601
+ * strings (e.g. `"2024-01-15"`, `"2024-01-15T10:30:00Z"`). Non-parseable values throw
+ * a {@link TypoError}.
+ *
+ * Produces a `Date` object. The decoded value is the result of `new Date(Date.parse(value))`.
+ *
+ * @example
+ * ```ts
+ * typeDate.decoder("2024-01-15") // → Date object for 2024-01-15
+ * typeDate.decoder("not a date") // throws TypoError
+ * ```
+ */
 export const typeDate: Type<Date> = {
   content: "Date",
   decoder(value: string) {
@@ -50,6 +107,20 @@ export const typeDate: Type<Date> = {
   },
 };
 
+/**
+ * A {@link Type} that parses a string into a JavaScript `number` using the `Number()`
+ * constructor.
+ *
+ * Accepts integers, floating-point values, and scientific notation (e.g. `"3.14"`,
+ * `"-1"`, `"1e10"`). Values that produce `NaN` throw a {@link TypoError}.
+ *
+ * @example
+ * ```ts
+ * typeNumber.decoder("3.14")  // → 3.14
+ * typeNumber.decoder("-1")    // → -1
+ * typeNumber.decoder("hello") // throws TypoError
+ * ```
+ */
 export const typeNumber: Type<number> = {
   content: "Number",
   decoder(value: string) {
@@ -70,6 +141,20 @@ export const typeNumber: Type<number> = {
   },
 };
 
+/**
+ * A {@link Type} that parses a string into a JavaScript `bigint` using the `BigInt()`
+ * constructor.
+ *
+ * Only accepts valid integer strings (e.g. `"42"`, `"-100"`, `"9007199254740993"`).
+ * Floating-point strings or non-numeric values throw a {@link TypoError}.
+ *
+ * @example
+ * ```ts
+ * typeInteger.decoder("42")   // → 42n
+ * typeInteger.decoder("3.14") // throws TypoError
+ * typeInteger.decoder("abc")  // throws TypoError
+ * ```
+ */
 export const typeInteger: Type<bigint> = {
   content: "Integer",
   decoder(value: string) {
@@ -86,6 +171,18 @@ export const typeInteger: Type<bigint> = {
   },
 };
 
+/**
+ * A {@link Type} that parses a string into a `URL` object using the `URL` constructor.
+ *
+ * The string must be a valid absolute URL (e.g. `"https://example.com/path?q=1"`).
+ * Relative URLs and malformed strings throw a {@link TypoError}.
+ *
+ * @example
+ * ```ts
+ * typeUrl.decoder("https://example.com") // → URL { href: "https://example.com/", ... }
+ * typeUrl.decoder("not-a-url")           // throws TypoError
+ * ```
+ */
 export const typeUrl: Type<URL> = {
   content: "Url",
   decoder(value: string) {
@@ -102,6 +199,17 @@ export const typeUrl: Type<URL> = {
   },
 };
 
+/**
+ * A {@link Type} that passes the raw string through unchanged (identity decoder).
+ *
+ * This is the simplest type and accepts any string value without validation.
+ *
+ * @example
+ * ```ts
+ * typeString.decoder("hello") // → "hello"
+ * typeString.decoder("")      // → ""
+ * ```
+ */
 export const typeString: Type<string> = {
   content: "String",
   decoder(value: string) {
@@ -109,6 +217,40 @@ export const typeString: Type<string> = {
   },
 };
 
+/**
+ * Creates a new {@link Type} by chaining a `before` type decoder with an `after`
+ * transformation.
+ *
+ * The raw string is first decoded by `before.decoder`; its result is then passed to
+ * `after.decoder`. Errors from `before` are wrapped with a "from: <content>" context
+ * prefix so that the full decoding path is visible in error messages.
+ *
+ * Use this when an existing type (e.g. {@link typeString}, {@link typeOneOf}) produces
+ * an intermediate value that needs a further transformation (e.g. parsing a
+ * string-keyed enum into a number).
+ *
+ * @typeParam Before - The intermediate type produced by `before.decoder`.
+ * @typeParam After - The final type produced by `after.decoder`.
+ *
+ * @param before - The base type that decodes the raw CLI string.
+ * @param after - The transformation applied to the `Before` value.
+ * @param after.content - Human-readable name for the resulting type (shown in errors).
+ * @param after.decoder - Function that converts a `Before` value into `After`.
+ * @returns A new {@link Type}`<After>` whose `content` is `after.content`.
+ *
+ * @example
+ * ```ts
+ * const typePort = typeConverted(typeNumber, {
+ *   content: "Port",
+ *   decoder: (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
+ * ```
+ */
 export function typeConverted<Before, After>(
   before: Type<Before>,
   after: { content: string; decoder: (value: Before) => After },
@@ -130,6 +272,27 @@ export function typeConverted<Before, After>(
   };
 }
 
+/**
+ * Creates a {@link Type}`<string>` that only accepts a fixed set of string values.
+ *
+ * The decoder performs an exact (case-sensitive) lookup in `values`. If the input is
+ * not in the set, a {@link TypoError} is thrown listing up to 5 of the valid options.
+ *
+ * Combine with {@link typeConverted} to map the accepted strings to a richer type.
+ *
+ * @param content - Human-readable name for this type shown in help text and error
+ *   messages (e.g. `"Environment"`, `"LogLevel"`).
+ * @param values - The ordered list of accepted string values. The order is preserved in
+ *   the error message preview.
+ * @returns A {@link Type}`<string>` that validates membership in `values`.
+ *
+ * @example
+ * ```ts
+ * const typeEnv = typeOneOf("Environment", ["dev", "staging", "prod"]);
+ * typeEnv.decoder("prod")    // → "prod"
+ * typeEnv.decoder("unknown") // throws TypoError: Invalid value: "unknown" (expected one of: "dev" | "staging" | "prod")
+ * ```
+ */
 export function typeOneOf(
   content: string,
   values: Array<string>,
@@ -165,6 +328,33 @@ export function typeOneOf(
   };
 }
 
+/**
+ * Creates a {@link Type} that decodes a single delimited string into a fixed-length
+ * tuple of typed elements.
+ *
+ * The raw string is split on `separator` into exactly `elementTypes.length` parts.
+ * Each part is decoded by its corresponding element type. If the number of splits does
+ * not match, or if any element's decoder fails, a {@link TypoError} is thrown with the
+ * index and element type context.
+ *
+ * The resulting `content` is the element types' `content` values joined by `separator`
+ * (e.g. `"Number,String"` for a `[number, string]` tuple with `","` separator).
+ *
+ * @typeParam Elements - The tuple type of decoded element values (inferred from
+ *   `elementTypes`).
+ *
+ * @param elementTypes - An ordered array of {@link Type}s, one per tuple element.
+ * @param separator - The string used to split the raw value (default: `","`).
+ * @returns A {@link Type}`<Elements>` tuple type.
+ *
+ * @example
+ * ```ts
+ * const typePoint = typeTuple([typeNumber, typeNumber]);
+ * 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"
+ * ```
+ */
 export function typeTuple<const Elements extends Array<any>>(
   elementTypes: { [K in keyof Elements]: Type<Elements[K]> },
   separator: string = ",",
@@ -199,6 +389,39 @@ export function typeTuple<const Elements extends Array<any>>(
   };
 }
 
+/**
+ * Creates a {@link Type} that decodes a single delimited string into an array of
+ * homogeneous typed elements.
+ *
+ * The raw string is split on `separator` and each part is decoded by `elementType`.
+ * If any element's decoder fails, a {@link TypoError} is thrown with the index and
+ * element type context.
+ *
+ * Unlike {@link typeTuple}, the number of elements is not fixed; the result array
+ * length equals the number of `separator`-delimited parts in the input string. To pass
+ * an empty array, the user must pass an empty string (`""`), which splits into one
+ * empty-string element — consider using {@link optionRepeatable} instead if you want a
+ * naturally empty default.
+ *
+ * The `content` is formatted as `"<elementContent>[<sep><elementContent>]..."` to
+ * signal repeatability.
+ *
+ * @typeParam Value - The TypeScript element type produced by `elementType.decoder`.
+ *
+ * @param elementType - The {@link Type} used to decode each element.
+ * @param separator - The string used to split the raw value (default: `","`).
+ * @returns A {@link Type}`<Array<Value>>`.
+ *
+ * @example
+ * ```ts
+ * const typeNumbers = typeList(typeNumber);
+ * typeNumbers.decoder("1,2,3")  // → [1, 2, 3]
+ * typeNumbers.decoder("1,x,3")  // throws TypoError: at 1: Number: Unable to parse: "x"
+ *
+ * const typePaths = typeList(typeString, ":");
+ * typePaths.decoder("/usr/bin:/usr/local/bin") // → ["/usr/bin", "/usr/local/bin"]
+ * ```
+ */
 export function typeList<Value>(
   elementType: Type<Value>,
   separator: string = ",",

package/src/lib/Typo.ts

@@ -1,3 +1,12 @@
+/**
+ * Available foreground and background color names for terminal styling.
+ *
+ * Colors are divided into two groups:
+ * - **dark** variants correspond to standard ANSI colors (codes 30–37 / 40–47).
+ * - **bright** variants correspond to high-intensity ANSI colors (codes 90–97 / 100–107).
+ *
+ * Used by {@link TypoStyle}'s `fgColor` and `bgColor` fields.
+ */
 export type TypoColor =
   | "darkBlack"
   | "darkRed"
@@ -16,68 +25,130 @@ export type TypoColor =
   | "brightCyan"
   | "brightWhite";
 
+/**
+ * Describes the visual styling to apply to a text segment when rendered by a
+ * {@link TypoSupport} instance.
+ *
+ * All fields are optional. When `TypoSupport` is in `"none"` mode, no styling is
+ * applied and the raw text is returned unchanged. In `"tty"` mode the corresponding
+ * ANSI escape codes are emitted. In `"mock"` mode a deterministic textual representation
+ * is produced (useful for snapshot tests).
+ */
 export type TypoStyle = {
+  /** Foreground (text) color. */
   fgColor?: TypoColor;
+  /** Background color. */
   bgColor?: TypoColor;
+  /** Render the text with reduced intensity. */
   dim?: boolean;
+  /** Render the text in bold. */
   bold?: boolean;
+  /** Render the text in italic. */
   italic?: boolean;
+  /** Render the text with an underline. */
   underline?: boolean;
+  /** Render the text with a strikethrough. */
   strikethrough?: boolean;
 };
 
+/**
+ * Pre-defined {@link TypoStyle} for section titles in the usage output (e.g.
+ * `"Positionals:"`, `"Options:"`).
+ * Rendered in bold dark-green.
+ */
 export const typoStyleTitle: TypoStyle = {
   fgColor: "darkGreen",
   bold: true,
 };
+/** Pre-defined {@link TypoStyle} for logic/type identifiers in error messages. Rendered in bold dark-magenta. */
 export const typoStyleLogic: TypoStyle = {
   fgColor: "darkMagenta",
   bold: true,
 };
+/** Pre-defined {@link TypoStyle} for quoted user-supplied values in error messages. Rendered in bold dark-yellow. */
 export const typoStyleQuote: TypoStyle = {
   fgColor: "darkYellow",
   bold: true,
 };
 
+/** Pre-defined {@link TypoStyle} for failure/error labels (e.g. `"Error:"`). Rendered in bold dark-red. */
 export const typoStyleFailure: TypoStyle = {
   fgColor: "darkRed",
   bold: true,
 };
 
+/** Pre-defined {@link TypoStyle} for CLI flag/option/command constant names. Rendered in bold dark-cyan. */
 export const typoStyleConstants: TypoStyle = {
   fgColor: "darkCyan",
   bold: true,
 };
+/** Pre-defined {@link TypoStyle} for positional placeholders and user-input labels. Rendered in bold dark-blue. */
 export const typoStyleUserInput: TypoStyle = {
   fgColor: "darkBlue",
   bold: true,
 };
 
+/** Pre-defined {@link TypoStyle} for strong regular text (e.g. command descriptions). Rendered in bold. */
 export const typoStyleRegularStrong: TypoStyle = {
   bold: true,
 };
+/** Pre-defined {@link TypoStyle} for subtle supplementary text (e.g. hints). Rendered in italic and dim. */
 export const typoStyleRegularWeaker: TypoStyle = {
   italic: true,
   dim: true,
 };
 
+/**
+ * An immutable styled string segment consisting of a raw text value and an associated
+ * {@link TypoStyle}.
+ *
+ * Multiple `TypoString`s are composed into a {@link TypoText} for multi-part messages.
+ * Rendering is deferred until {@link TypoString.computeStyledString} is called with a
+ * {@link TypoSupport} instance.
+ */
 export class TypoString {
   #value: string;
   #typoStyle: TypoStyle;
+  /**
+   * @param value - The raw text content.
+   * @param typoStyle - The style to apply when rendering. Defaults to `{}` (no style).
+   */
   constructor(value: string, typoStyle: TypoStyle = {}) {
     this.#value = value;
     this.#typoStyle = typoStyle;
   }
+  /** Returns the unstyled raw text content. */
   getRawString(): string {
     return this.#value;
   }
+  /**
+   * Returns the text with ANSI escape codes (or mock markers) applied by `typoSupport`.
+   *
+   * @param typoSupport - Controls how styles are rendered (tty colors, mock, or none).
+   */
   computeStyledString(typoSupport: TypoSupport): string {
     return typoSupport.computeStyledString(this.#value, this.#typoStyle);
   }
 }
 
+/**
+ * A mutable sequence of {@link TypoString} segments that together form a styled
+ * multi-part message.
+ *
+ * `TypoText` is used throughout the library to build error messages and usage output
+ * that carry styling information without being coupled to a specific output mode.
+ * Rendering is deferred to {@link TypoText.computeStyledString}.
+ */
 export class TypoText {
   #typoStrings: Array<TypoString>;
+  /**
+   * Creates a `TypoText` pre-populated with the provided parts. Each part can be a
+   * `TypoText` (flattened by value), a `TypoString`, or a plain `string` (wrapped in an
+   * unstyled `TypoString`).
+   *
+   * @param typoParts - Initial parts to append. Can be any mix of `TypoText`,
+   *   `TypoString`, and `string`.
+   */
   constructor(...typoParts: Array<TypoText | TypoString | string>) {
     this.#typoStrings = [];
     for (const typoPart of typoParts) {
@@ -90,22 +161,48 @@ export class TypoText {
       }
     }
   }
+  /**
+   * Appends a single {@link TypoString} segment to the end of this text.
+   *
+   * @param typoString - The segment to append.
+   */
   pushString(typoString: TypoString) {
     this.#typoStrings.push(typoString);
   }
+  /**
+   * Appends all segments from another {@link TypoText} to the end of this text
+   * (shallow copy of segments).
+   *
+   * @param typoText - The text whose segments are appended.
+   */
   pushText(typoText: TypoText) {
     for (const typoString of typoText.#typoStrings) {
       this.#typoStrings.push(typoString);
     }
   }
+  /**
+   * Renders all segments into a single string, applying styles via `typoSupport`.
+   *
+   * @param typoSupport - Controls how styles are rendered.
+   * @returns The concatenated, optionally styled string.
+   */
   computeStyledString(typoSupport: TypoSupport): string {
     return this.#typoStrings
       .map((t) => t.computeStyledString(typoSupport))
       .join("");
   }
+  /**
+   * Returns the concatenation of all segments' raw (unstyled) text.
+   * Equivalent to calling {@link TypoText.computeStyledString} with
+   * {@link TypoSupport.none}.
+   */
   computeRawString(): string {
     return this.#typoStrings.map((t) => t.getRawString()).join("");
   }
+  /**
+   * Returns the total character length of the raw (unstyled) text.
+   * Used by {@link TypoGrid} to compute column widths for alignment.
+   */
   computeRawLength(): number {
     let length = 0;
     for (const typoString of this.#typoStrings) {
@@ -115,14 +212,38 @@ export class TypoText {
   }
 }
 
+/**
+ * A grid of {@link TypoText} cells that renders with column-aligned padding.
+ *
+ * Each row is an array of `TypoText` cells. When {@link TypoGrid.computeStyledGrid} is
+ * called, each column is padded to the width of its widest cell (measured in raw
+ * characters). The last column in each row is **not** padded.
+ *
+ * Used internally by {@link usageToStyledLines} to render the `Positionals:`,
+ * `Subcommands:`, and `Options:` sections with neat alignment.
+ */
 export class TypoGrid {
   #typoRows: Array<Array<TypoText>>;
   constructor() {
     this.#typoRows = [];
   }
+  /**
+   * Appends a row of cells to the grid.
+   *
+   * @param cells - An ordered array of {@link TypoText} cells for this row. All rows
+   *   should have the same number of cells for alignment to be meaningful.
+   */
   pushRow(cells: Array<TypoText>) {
     this.#typoRows.push(cells);
   }
+  /**
+   * Renders the grid into a 2-D array of styled strings, with space padding added
+   * between columns (except after the last column).
+   *
+   * @param typoSupport - Controls how styles are rendered.
+   * @returns A 2-D array where each inner array is the styled (and padded) cells of
+   *   one row. Join the inner arrays with `""` to get a single line string.
+   */
   computeStyledGrid(typoSupport: TypoSupport): Array<Array<string>> {
     const widths = new Array<number>();
     const printableGrid = new Array<Array<string>>();
@@ -164,8 +285,26 @@ export class TypoGrid {
   }
 }
 
+/**
+ * An `Error` subclass that carries a {@link TypoText} styled message in addition to
+ * the plain-text `Error.message` used by the standard JS error chain.
+ *
+ * `TypoError` is used throughout `cli-kiss` to report parsing failures (unknown option,
+ * type decoding error, missing required argument, etc.). Its styled representation is
+ * rendered by {@link TypoSupport.computeStyledErrorMessage} when outputting errors to
+ * the terminal.
+ *
+ * Errors can be chained: if `source` is a `TypoError`, its styled text is appended
+ * after `": "` to form the full message context chain.
+ */
 export class TypoError extends Error {
   #typoText: TypoText;
+  /**
+   * @param currentTypoText - The styled message for this error level.
+   * @param source - An optional cause. If it is a `TypoError`, its styled text is
+   *   appended (chained context). If it is a plain `Error`, its `.message` is appended
+   *   as a plain string. Any other value is stringified with `String()`.
+   */
   constructor(currentTypoText: TypoText, source?: unknown) {
     const typoText = new TypoText();
     typoText.pushText(currentTypoText);
@@ -180,9 +319,31 @@ export class TypoError extends Error {
     super(typoText.computeRawString());
     this.#typoText = typoText;
   }
+  /**
+   * Renders this error's styled message as a string.
+   *
+   * @param typoSupport - Controls how ANSI styles are applied.
+   * @returns The full styled error message (without a leading `"Error:"` prefix).
+   */
   computeStyledString(typoSupport: TypoSupport): string {
     return this.#typoText.computeStyledString(typoSupport);
   }
+  /**
+   * Executes `thrower` and returns its result. If `thrower` throws any error, the error
+   * is re-thrown as a new `TypoError` whose message is `context()` with the original
+   * error chained as the source.
+   *
+   * This is a convenience helper for adding contextual information to errors that arise
+   * deep in a call chain (e.g. "at 0: Number: Unable to parse: ...").
+   *
+   * @typeParam Value - The return type of `thrower`.
+   * @param thrower - A zero-argument function whose return value is passed through on
+   *   success.
+   * @param context - A zero-argument factory that produces the {@link TypoText} context
+   *   prepended to the caught error. Called only when `thrower` throws.
+   * @returns The value returned by `thrower`.
+   * @throws `TypoError` wrapping the original error with the provided context prepended.
+   */
   static tryWithContext<Value>(
     thrower: () => Value,
     context: () => TypoText,
@@ -195,20 +356,61 @@ export class TypoError extends Error {
   }
 }
 
+/**
+ * Controls whether and how ANSI terminal styling is applied when rendering
+ * {@link TypoString}, {@link TypoText}, and error messages.
+ *
+ * Instances are created via the static factory methods:
+ * - {@link TypoSupport.none} — strips all styling (plain text).
+ * - {@link TypoSupport.tty} — applies ANSI escape codes for color terminals.
+ * - {@link TypoSupport.mock} — applies a deterministic textual representation useful
+ *   for snapshot tests.
+ * - {@link TypoSupport.inferFromProcess} — auto-detects based on `process.stdout.isTTY`
+ *   and the `FORCE_COLOR` / `NO_COLOR` environment variables.
+ *
+ * `TypoSupport` is consumed by {@link runAndExit} (via the `useTtyColors` option)
+ * and can also be used directly when building custom usage renderers with {@link usageToStyledLines}.
+ */
 export class TypoSupport {
   #kind: "none" | "tty" | "mock";
   private constructor(kind: "none" | "tty" | "mock") {
     this.#kind = kind;
   }
+  /**
+   * Returns a `TypoSupport` that strips all styling — every styled string is returned
+   * as-is (plain text, no ANSI codes).
+   */
   static none(): TypoSupport {
     return new TypoSupport("none");
   }
+  /**
+   * Returns a `TypoSupport` that applies ANSI escape codes.
+   * Use this when writing to a color-capable terminal (`stdout.isTTY === true`).
+   */
   static tty(): TypoSupport {
     return new TypoSupport("tty");
   }
+  /**
+   * Returns a `TypoSupport` that applies a deterministic mock styling representation.
+   *
+   * Instead of real ANSI codes, each style flag is expressed as a readable suffix:
+   * `{text}@color`, `{text}+` (bold), `{text}-` (dim), `{text}*` (italic),
+   * `{text}_` (underline), `{text}~` (strikethrough). Useful for snapshot testing.
+   */
   static mock(): TypoSupport {
     return new TypoSupport("mock");
   }
+  /**
+   * Selects a `TypoSupport` mode automatically based on the current process environment:
+   *
+   * 1. `FORCE_COLOR=0` or `NO_COLOR` env var set → {@link TypoSupport.none}.
+   * 2. `FORCE_COLOR` env var set (any truthy value) → {@link TypoSupport.tty}.
+   * 3. `process.stdout.isTTY === true` → {@link TypoSupport.tty}.
+   * 4. Otherwise → {@link TypoSupport.none}.
+   *
+   * Falls back to {@link TypoSupport.none} if `process` is not available (e.g. in a
+   * non-Node environment).
+   */
   static inferFromProcess(): TypoSupport {
     if (!process) {
       return TypoSupport.none();
@@ -229,6 +431,17 @@ export class TypoSupport {
     }
     return TypoSupport.none();
   }
+  /**
+   * Applies the given {@link TypoStyle} to `value` and returns the styled string.
+   *
+   * - In `"none"` mode: returns `value` unchanged.
+   * - In `"tty"` mode: wraps `value` in ANSI escape codes and appends a reset code.
+   * - In `"mock"` mode: wraps `value` in a deterministic textual representation.
+   *
+   * @param value - The raw text to style.
+   * @param typoStyle - The style to apply.
+   * @returns The styled string.
+   */
   computeStyledString(value: string, typoStyle: TypoStyle): string {
     if (this.#kind === "none") {
       return value;
@@ -269,6 +482,18 @@ export class TypoSupport {
     }
     throw new Error(`Unknown TypoSupport kind: ${this.#kind}`);
   }
+  /**
+   * Formats an error value as a styled `"Error: <message>"` string.
+   *
+   * - If `error` is a {@link TypoError}, its styled text is used for the message part.
+   * - If `error` is a plain `Error`, its `.message` property is used.
+   * - Otherwise `String(error)` is used.
+   *
+   * The `"Error:"` prefix is always styled with {@link typoStyleFailure}.
+   *
+   * @param error - The error to format (any value thrown by a handler).
+   * @returns A styled error string ready to print to stderr.
+   */
   computeStyledErrorMessage(error: unknown): string {
     return [
       this.computeStyledString("Error:", typoStyleFailure),