effect 4.0.0-beta.102 → 4.0.0-beta.103

package/src/unstable/cli/CliError.ts

@@ -25,26 +25,16 @@ const TypeId = "~effect/cli/CliError"
  *
  * **Example** (Checking CLI errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { CliError } from "effect/unstable/cli"
  *
- * const handleError = (error: unknown) => {
- *   if (CliError.isCliError(error)) {
- *     console.log("CLI Error:", error.message)
- *     return Effect.succeed("Handled CLI error")
- *   }
- *   return Effect.fail("Unknown error")
- * }
+ * const error = new CliError.MissingOption({ option: "api-key" })
+ * const program = CliError.isCliError(error)
+ *   ? Effect.succeed(error.message)
+ *   : Effect.fail("Unknown error")
  *
- * // Example usage in error handling
- * const program = Effect.gen(function*() {
- *   const result = yield* Effect.try({
- *     try: () => ({ success: true }),
- *     catch: (error) => error
- *   })
- *   handleError(result)
- * })
+ * await Effect.runPromise(program) // => "Missing required flag: --api-key"
  * ```
  *
  * @category guards
@@ -57,31 +47,28 @@ export const isCliError = (u: unknown): u is CliError => Predicate.hasProperty(u
  *
  * **Example** (Handling CLI errors)
  *
- * ```ts
- * import type { CliError } from "effect/unstable/cli"
+ * ```ts import.meta.vitest
+ * import { CliError } from "effect/unstable/cli"
  *
- * const handleCliError = (error: CliError.CliError): void => {
+ * const describe = (error: CliError.CliError): string => {
  *   switch (error._tag) {
  *     case "UnrecognizedOption":
- *       console.log(`Unknown flag: ${error.option}`)
- *       break
+ *       return `Unknown flag: ${error.option}`
  *     case "MissingOption":
- *       console.log(`Required flag missing: ${error.option}`)
- *       break
+ *       return `Required flag missing: ${error.option}`
  *     case "InvalidValue":
- *       console.log(`Invalid value: ${error.value} for ${error.option}`)
- *       break
+ *       return `Invalid value: ${error.value} for ${error.option}`
  *     case "ShowHelp":
- *       // Display help for the command path
- *       console.log(`Help requested for: ${error.commandPath.join(" ")}`)
- *       break
+ *       return `Help requested for: ${error.commandPath.join(" ")}`
  *     default:
- *       console.log(error.message)
+ *       return error.message
  *   }
  * }
+ *
+ * describe(new CliError.MissingOption({ option: "token" })) // => "Required flag missing: token"
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export type CliError =
@@ -100,7 +87,7 @@ export type CliError =
  *
  * **Example** (Creating unrecognized option errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { CliError } from "effect/unstable/cli"
  *
@@ -111,21 +98,21 @@ export type CliError =
  *   suggestions: ["--verbose", "--force"]
  * })
  *
- * console.log(unrecognizedError.message)
- * // "Unrecognized flag: --unknown-flag in command deploy production
- * //
- * //  Did you mean this?
- * //    --verbose
- * //    --force"
+ * unrecognizedError._tag // => "UnrecognizedOption"
+ * unrecognizedError.option // => "--unknown-flag"
+ * unrecognizedError.command // => ["deploy", "production"]
  *
  * // In CLI parsing context
  * const parseCommand = Effect.gen(function*() {
  *   // If parsing encounters unknown flag
  *   return yield* unrecognizedError
  * })
+ *
+ * const parseError = await Effect.runPromise(Effect.flip(parseCommand))
+ * parseError._tag // => "UnrecognizedOption"
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export class UnrecognizedOption extends Schema.TaggedErrorClass<UnrecognizedOption>(
@@ -163,7 +150,7 @@ export class UnrecognizedOption extends Schema.TaggedErrorClass<UnrecognizedOpti
  *
  * **Example** (Creating duplicate option errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { CliError } from "effect/unstable/cli"
  *
  * const duplicateError = new CliError.DuplicateOption({
@@ -172,12 +159,13 @@ export class UnrecognizedOption extends Schema.TaggedErrorClass<UnrecognizedOpti
  *   childCommand: "deploy"
  * })
  *
- * console.log(duplicateError.message)
- * // "Duplicate flag name "--verbose" in parent command "myapp" and subcommand "deploy".
- * // Parent will always claim this flag (Mode A semantics). Consider renaming one of them to avoid confusion."
+ * duplicateError._tag // => "DuplicateOption"
+ * duplicateError.option // => "--verbose"
+ * duplicateError.parentCommand // => "myapp"
+ * duplicateError.childCommand // => "deploy"
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export class DuplicateOption extends Schema.TaggedErrorClass<DuplicateOption>(
@@ -210,7 +198,7 @@ export class DuplicateOption extends Schema.TaggedErrorClass<DuplicateOption>(
  *
  * **Example** (Creating missing option errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { CliError } from "effect/unstable/cli"
  *
@@ -218,8 +206,7 @@ export class DuplicateOption extends Schema.TaggedErrorClass<DuplicateOption>(
  *   option: "api-key"
  * })
  *
- * console.log(missingOptionError.message)
- * // "Missing required flag: --api-key"
+ * const details = [missingOptionError._tag, missingOptionError.option] // => ["MissingOption", "api-key"]
  *
  * // In validation context
  * const validateRequiredOptions = (options: Record<string, string | undefined>) =>
@@ -230,9 +217,12 @@ export class DuplicateOption extends Schema.TaggedErrorClass<DuplicateOption>(
  *     }
  *     return apiKey
  *   })
+ *
+ * const validationError = await Effect.runPromise(Effect.flip(validateRequiredOptions({})))
+ * validationError._tag // => "MissingOption"
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export class MissingOption extends Schema.TaggedErrorClass<MissingOption>(
@@ -262,7 +252,7 @@ export class MissingOption extends Schema.TaggedErrorClass<MissingOption>(
  *
  * **Example** (Creating missing argument errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { CliError } from "effect/unstable/cli"
  *
@@ -270,8 +260,7 @@ export class MissingOption extends Schema.TaggedErrorClass<MissingOption>(
  *   argument: "target"
  * })
  *
- * console.log(missingArgError.message)
- * // "Missing required argument: target"
+ * const details = [missingArgError._tag, missingArgError.argument] // => ["MissingArgument", "target"]
  *
  * // In argument parsing
  * const parseArguments = (args: Array<string>) =>
@@ -281,9 +270,12 @@ export class MissingOption extends Schema.TaggedErrorClass<MissingOption>(
  *     }
  *     return args[0]
  *   })
+ *
+ * const parseError = await Effect.runPromise(Effect.flip(parseArguments([])))
+ * parseError._tag // => "MissingArgument"
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export class MissingArgument extends Schema.TaggedErrorClass<MissingArgument>(
@@ -314,18 +306,17 @@ export class MissingArgument extends Schema.TaggedErrorClass<MissingArgument>(
  *
  * **Example** (Reporting unexpected arguments)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { CliError } from "effect/unstable/cli"
  *
  * const error = new CliError.UnexpectedArgument({
  *   arguments: ["extra.txt"]
  * })
  *
- * console.log(error.message)
- * // "Unexpected positional argument: \"extra.txt\""
+ * const details = [error._tag, error.arguments] // => ["UnexpectedArgument", ["extra.txt"]]
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export class UnexpectedArgument extends Schema.TaggedErrorClass<UnexpectedArgument>(
@@ -356,8 +347,7 @@ export class UnexpectedArgument extends Schema.TaggedErrorClass<UnexpectedArgume
  *
  * **Example** (Creating invalid value errors)
  *
- * ```ts
- * import { Effect } from "effect"
+ * ```ts import.meta.vitest
  * import { CliError } from "effect/unstable/cli"
  *
  * const invalidValueError = new CliError.InvalidValue({
@@ -367,8 +357,10 @@ export class UnexpectedArgument extends Schema.TaggedErrorClass<UnexpectedArgume
  *   kind: "flag"
  * })
  *
- * console.log(invalidValueError.message)
- * // "Invalid value for flag --port: "abc123". Expected: integer between 1 and 65535"
+ * invalidValueError._tag // => "InvalidValue"
+ * invalidValueError.kind // => "flag"
+ * invalidValueError.option // => "port"
+ * invalidValueError.value // => "abc123"
  *
  * // For positional arguments
  * const invalidArgError = new CliError.InvalidValue({
@@ -378,11 +370,10 @@ export class UnexpectedArgument extends Schema.TaggedErrorClass<UnexpectedArgume
  *   kind: "argument"
  * })
  *
- * console.log(invalidArgError.message)
- * // "Invalid value for argument <count>: "abc". Expected: integer"
+ * const details = [invalidArgError.kind, invalidArgError.option, invalidArgError.value] // => ["argument", "count", "abc"]
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export class InvalidValue extends Schema.TaggedErrorClass<InvalidValue>(
@@ -424,7 +415,7 @@ export class InvalidValue extends Schema.TaggedErrorClass<InvalidValue>(
  *
  * **Example** (Creating unknown subcommand errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { CliError } from "effect/unstable/cli"
  *
@@ -434,12 +425,9 @@ export class InvalidValue extends Schema.TaggedErrorClass<InvalidValue>(
  *   suggestions: ["deploy", "destroy"]
  * })
  *
- * console.log(unknownSubcommandError.message)
- * // "Unknown subcommand "deplyo" for "myapp"
- * //
- * //  Did you mean this?
- * //    deploy
- * //    destroy"
+ * unknownSubcommandError._tag // => "UnknownSubcomand"
+ * unknownSubcommandError.subcommand // => "deplyo"
+ * unknownSubcommandError.parent // => ["myapp"]
  *
  * // In subcommand parsing
  * const parseSubcommand = (subcommand: string) =>
@@ -450,9 +438,12 @@ export class InvalidValue extends Schema.TaggedErrorClass<InvalidValue>(
  *     }
  *     return subcommand
  *   })
+ *
+ * const parseError = await Effect.runPromise(Effect.flip(parseSubcommand("deplyo")))
+ * parseError._tag // => "UnknownSubcomand"
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export class UnknownSubcommand extends Schema.TaggedErrorClass<UnknownSubcommand>(
@@ -489,7 +480,7 @@ export class UnknownSubcommand extends Schema.TaggedErrorClass<UnknownSubcommand
  *
  * **Example** (Wrapping user errors)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { CliError } from "effect/unstable/cli"
  *
@@ -510,14 +501,16 @@ export class UnknownSubcommand extends Schema.TaggedErrorClass<UnknownSubcommand
  * // In error handling
  * const handleError = (error: CliError.CliError): Effect.Effect<number> => {
  *   if (error._tag === "UserError") {
- *     console.log("Command failed:", error.cause)
  *     return Effect.succeed(1) // Exit code 1
  *   }
  *   return Effect.succeed(0)
  * }
+ *
+ * await Effect.runPromise(deployCommand) // => { deployed: true }
+ * await Effect.runPromise(handleError(userError)) // => 1
  * ```
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export class UserError extends Schema.TaggedErrorClass<UserError>(
@@ -541,7 +534,7 @@ export class UserError extends Schema.TaggedErrorClass<UserError>(
  * This excludes `ShowHelp` itself, allowing parse and validation errors to be
  * stored in `ShowHelp.errors` without nesting another help-control value.
  *
- * @category models
+ * @category schemas
  * @since 4.0.0
  */
 export const NonShowHelpErrors: Schema.Union<
@@ -575,7 +568,7 @@ export const NonShowHelpErrors: Schema.Union<
  * runner should display help along with the underlying parse or validation
  * failures.
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export type NonShowHelpErrors = typeof NonShowHelpErrors.Type
@@ -589,7 +582,7 @@ export type NonShowHelpErrors = typeof NonShowHelpErrors.Type
  * that should be shown with help text. When `errors` is non-empty, the runtime
  * exit code is `1`; otherwise it is `0`.
  *
- * @category models
+ * @category errors
  * @since 4.0.0
  */
 export class ShowHelp extends Schema.TaggedErrorClass<ShowHelp>(

package/src/unstable/cli/CliOutput.ts

@@ -22,7 +22,7 @@ import type { HelpDoc } from "./HelpDoc.ts"
  *
  * **Example** (Customizing CLI output formatting)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { CliOutput } from "effect/unstable/cli"
  *
@@ -38,11 +38,12 @@ import type { HelpDoc } from "./HelpDoc.ts"
  * // Use the custom formatter in a program
  * const program = Effect.gen(function*() {
  *   const formatter = yield* CliOutput.Formatter
- *   const helpText = formatter.formatVersion("myapp", "1.0.0")
- *   console.log(helpText)
+ *   return formatter.formatVersion("myapp", "1.0.0")
  * }).pipe(
  *   Effect.provide(CliOutput.layer(customFormatter))
  * )
+ *
+ * await Effect.runPromise(program) // => "myapp (1.0.0)"
  * ```
  *
  * @category models
@@ -54,7 +55,7 @@ export interface Formatter {
    *
    * **Example** (Formatting help documents)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Option as O } from "effect"
    * import { CliOutput } from "effect/unstable/cli"
    * import type { HelpDoc } from "effect/unstable/cli"
@@ -84,8 +85,7 @@ export interface Formatter {
    *
    * const formatter = CliOutput.defaultFormatter()
    * const helpText = formatter.formatHelpDoc(helpDoc)
-   * console.log(helpText)
-   * // Outputs formatted help with sections: DESCRIPTION, USAGE, ARGUMENTS, FLAGS
+   * const sectionsPresent = [helpText.includes("DESCRIPTION"), helpText.includes("FLAGS")] // => [true, true]
    * ```
    *
    * @since 4.0.0
@@ -97,7 +97,7 @@ export interface Formatter {
    *
    * **Example** (Formatting CLI errors)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Data } from "effect"
    * import { CliOutput } from "effect/unstable/cli"
    *
@@ -108,7 +108,7 @@ export interface Formatter {
    * const formatter = CliOutput.defaultFormatter()
    * const error = new InvalidOption({ message: "Unknown flag '--invalid'" })
    * const errorMessage = formatter.formatCliError(error)
-   * console.log(errorMessage) // "Unknown flag '--invalid'"
+   * errorMessage // => "Unknown flag '--invalid'"
    * ```
    *
    * @since 4.0.0
@@ -120,7 +120,7 @@ export interface Formatter {
    *
    * **Example** (Formatting error sections)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Data } from "effect"
    * import { CliOutput } from "effect/unstable/cli"
    *
@@ -134,10 +134,10 @@ export interface Formatter {
    * const error = new ValidationError({ message: "Value must be positive" })
    *
    * const coloredError = colorFormatter.formatError(error)
-   * console.log(coloredError) // "\n\x1b[1m\x1b[31mERROR\x1b[0m\n  Value must be positive\x1b[0m"
+   * coloredError.includes("\u001b[31mERROR") // => true
    *
    * const plainError = noColorFormatter.formatError(error)
-   * console.log(plainError) // "\nERROR\n  Value must be positive"
+   * plainError // => "\nERROR\n  Value must be positive"
    * ```
    *
    * @since 4.0.0
@@ -149,7 +149,7 @@ export interface Formatter {
    *
    * **Example** (Formatting version output)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { CliOutput } from "effect/unstable/cli"
    *
    * const colorFormatter = CliOutput.defaultFormatter({ colors: true })
@@ -159,10 +159,10 @@ export interface Formatter {
    * const version = "1.2.3"
    *
    * const coloredVersion = colorFormatter.formatVersion(appName, version)
-   * console.log(coloredVersion) // "\x1b[1mmy-awesome-tool\x1b[0m \x1b[2mv\x1b[0m\x1b[1m1.2.3\x1b[0m"
+   * coloredVersion // => "\u001b[1mmy-awesome-tool\u001b[0m \u001b[2mv\u001b[0m\u001b[1m1.2.3\u001b[0m"
    *
    * const plainVersion = noColorFormatter.formatVersion(appName, version)
-   * console.log(plainVersion) // "my-awesome-tool v1.2.3"
+   * plainVersion // => "my-awesome-tool v1.2.3"
    * ```
    *
    * @since 4.0.0
@@ -174,7 +174,7 @@ export interface Formatter {
    *
    * **Example** (Formatting grouped errors)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { CliError, CliOutput } from "effect/unstable/cli"
    *
    * const formatter = CliOutput.defaultFormatter({ colors: false })
@@ -189,7 +189,7 @@ export interface Formatter {
    * ]
    *
    * const output = formatter.formatErrors(errors)
-   * // Groups errors by type and displays all at once
+   * const optionsPresent = [output.includes("--foo"), output.includes("--required")] // => [true, true]
    * ```
    *
    * @since 4.0.0
@@ -203,7 +203,7 @@ export interface Formatter {
  *
  * **Example** (Accessing the output formatter)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect } from "effect"
  * import { CliOutput } from "effect/unstable/cli"
  *
@@ -212,14 +212,13 @@ export interface Formatter {
  *   const formatter = yield* CliOutput.Formatter
  *
  *   // Format version information
- *   const versionText = formatter.formatVersion("my-cli", "2.1.0")
- *   console.log(versionText) // "my-cli v2.1.0" (with colors if supported)
- *
- *   return versionText
+ *   return formatter.formatVersion("my-cli", "2.1.0")
  * })
  *
  * // Run with default formatter
- * const result = Effect.runSync(program)
+ * await Effect.runPromise(program.pipe(
+ *   Effect.provide(CliOutput.layer(CliOutput.defaultFormatter({ colors: false })))
+ * )) // => "my-cli v2.1.0"
  * ```
  *
  * @category services
@@ -235,8 +234,8 @@ export const Formatter: Context.Reference<Formatter> = Context.Reference(
  *
  * **Example** (Providing a custom formatter)
  *
- * ```ts
- * import { Console, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect } from "effect"
  * import { CliOutput } from "effect/unstable/cli"
  *
  * // Create a custom formatter without colors
@@ -246,22 +245,12 @@ export const Formatter: Context.Reference<Formatter> = Context.Reference(
  * // Create a program that uses the custom formatter
  * const program = Effect.gen(function*() {
  *   const formatter = yield* CliOutput.Formatter
- *   const versionText = formatter.formatVersion("my-cli", "1.0.0")
- *   yield* Console.log(`Using custom formatter: ${versionText}`)
+ *   return formatter.formatVersion("my-cli", "1.0.0")
  * }).pipe(
  *   Effect.provide(NoColorLayer)
  * )
  *
- * // You can also create completely custom formatters
- * const jsonFormatter: CliOutput.Formatter = {
- *   formatHelpDoc: (doc) => JSON.stringify(doc, null, 2),
- *   formatCliError: (error) => JSON.stringify({ error: error.message }),
- *   formatError: (error) =>
- *     JSON.stringify({ type: "error", message: error.message }),
- *   formatVersion: (name, version) => JSON.stringify({ name, version }),
- *   formatErrors: (errors) => JSON.stringify(errors.map((error) => error.message))
- * }
- * const JsonLayer = CliOutput.layer(jsonFormatter)
+ * await Effect.runPromise(program) // => "my-cli v1.0.0"
  * ```
  *
  * @category layers
@@ -269,13 +258,17 @@ export const Formatter: Context.Reference<Formatter> = Context.Reference(
  */
 export const layer = (formatter: Formatter): Layer.Layer<never> => Layer.succeed(Formatter)(formatter)
 
+const escapeControlCharacters = (text: string): string =>
+  // oxlint-disable-next-line no-control-regex
+  text.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, (character) =>
+    `\\x${character.charCodeAt(0).toString(16).padStart(2, "0")}`)
+
 /**
  * Creates a default formatter with configurable options.
  *
  * **Example** (Creating default formatters)
  *
- * ```ts
- * import { Effect } from "effect"
+ * ```ts import.meta.vitest
  * import { CliError, CliOutput } from "effect/unstable/cli"
  *
  * // Create a formatter without colors for tests or CI environments
@@ -287,23 +280,16 @@ export const layer = (formatter: Formatter): Layer.Layer<never> => Layer.succeed
  * // Auto-detect colors based on terminal support (default behavior)
  * const autoFormatter = CliOutput.defaultFormatter()
  *
- * const program = Effect.gen(function*() {
- *   const formatter = colorFormatter
- *
- *   // Format an error with proper styling
- *   const error = new CliError.InvalidValue({
- *     option: "foo",
- *     value: "bar",
- *     expected: "baz",
- *     kind: "flag"
- *   })
- *   const errorText = formatter.formatError(error)
- *   console.log(errorText)
- *
- *   // Format version information
- *   const versionText = formatter.formatVersion("my-tool", "1.2.3")
- *   console.log(versionText)
+ * const error = new CliError.InvalidValue({
+ *   option: "foo",
+ *   value: "bar",
+ *   expected: "baz",
+ *   kind: "flag"
  * })
+ *
+ * noColorFormatter.formatError(error).includes("Invalid value") // => true
+ * colorFormatter.formatVersion("my-tool", "1.2.3").includes("my-tool") // => true
+ * autoFormatter.formatVersion("my-tool", "1.2.3").includes("1.2.3") // => true
  * ```
  *
  * @category constructors
@@ -349,14 +335,14 @@ export const defaultFormatter = (options?: { colors?: boolean }): Formatter => {
 
   return {
     formatHelpDoc: (doc: HelpDoc): string => formatHelpDocImpl(doc, colors),
-    formatCliError: (error): string => error.message,
+    formatCliError: (error): string => escapeControlCharacters(error.message),
     formatError: (error): string => {
-      return `\n${bold}${red}ERROR${reset}\n  ${error.message}${reset}`
+      return `\n${bold}${red}ERROR${reset}\n  ${escapeControlCharacters(error.message)}${reset}`
     },
     formatErrors: (errors): string => {
       if (errors.length === 0) return ""
       if (errors.length === 1) {
-        return `\n${bold}${red}ERROR${reset}\n  ${errors[0].message}${reset}`
+        return `\n${bold}${red}ERROR${reset}\n  ${escapeControlCharacters(errors[0].message)}${reset}`
       }
 
       // Group errors by _tag
@@ -373,7 +359,7 @@ export const defaultFormatter = (options?: { colors?: boolean }): Formatter => {
 
       for (const [, group] of grouped) {
         for (const error of group) {
-          sections.push(`  ${error.message}${reset}`)
+          sections.push(`  ${escapeControlCharacters(error.message)}${reset}`)
         }
       }