@villedemontreal/caporal 3.1.7

package/src/error/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+export * from "./action"
+export * from "./base"
+export * from "./fatal"
+export * from "./invalid-validator"
+export * from "./missing-argument"
+export * from "./missing-flag"
+export * from "./multi-validation"
+export * from "./no-action"
+export * from "./option-synopsis-syntax"
+export * from "./unknown-option"
+export * from "./unknown-command"
+export * from "./validation"
+export * from "./too-many-arguments"

package/src/error/invalid-validator.ts

@@ -0,0 +1,12 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+
+import { BaseError } from "./base"
+import { Validator } from "../types"
+export class InvalidValidatorError extends BaseError {
+  constructor(validator: Validator) {
+    super("Caporal setup error: Invalid flag validator setup.", { validator })
+  }
+}

package/src/error/missing-argument.ts

@@ -0,0 +1,16 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+
+import { BaseError } from "./base"
+import { Command } from "../command"
+import { Argument } from "../types"
+import chalk from "chalk"
+
+export class MissingArgumentError extends BaseError {
+  constructor(argument: Argument, command: Command) {
+    const msg = `Missing required argument ${chalk.bold(argument.name)}.`
+    super(msg, { argument, command })
+  }
+}

package/src/error/missing-flag.ts

@@ -0,0 +1,16 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+
+import { BaseError } from "./base"
+import { Command } from "../command"
+import { Option } from "../types"
+import chalk from "chalk"
+
+export class MissingFlagError extends BaseError {
+  constructor(flag: Option, command: Command) {
+    const msg = `Missing required flag ${chalk.bold(flag.allNotations.join(" | "))}.`
+    super(msg, { flag, command })
+  }
+}

package/src/error/multi-validation.ts

@@ -0,0 +1,22 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+
+import { BaseError, CommonError } from "./base"
+import chalk from "chalk"
+import { colorize } from "../utils/colorize"
+import type { Command } from "../command"
+
+export class ValidationSummaryError extends BaseError {
+  constructor(cmd: Command, errors: CommonError[]) {
+    const plural = errors.length > 1 ? "s" : ""
+    const msg =
+      `The following error${plural} occured:\n` +
+      errors.map((e) => "- " + e.message.replace(/\n/g, "\n  ")).join("\n") +
+      "\n\n" +
+      chalk.dim("Synopsis: ") +
+      colorize(cmd.synopsis)
+    super(msg, { errors })
+  }
+}

package/src/error/no-action.ts

@@ -0,0 +1,19 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+
+import { BaseError } from "./base"
+import { Command } from "../command"
+
+export class NoActionError extends BaseError {
+  constructor(cmd?: Command) {
+    let message
+    if (cmd && !cmd.isProgramCommand()) {
+      message = `Caporal Error: You haven't defined any action for command '${cmd.name}'.\nUse .action() to do so.`
+    } else {
+      message = `Caporal Error: You haven't defined any action for program.\nUse .action() to do so.`
+    }
+    super(message, { cmd })
+  }
+}

package/src/error/option-synopsis-syntax.ts

@@ -0,0 +1,12 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+
+import { BaseError } from "./base"
+
+export class OptionSynopsisSyntaxError extends BaseError {
+  constructor(synopsis: string) {
+    super(`Syntax error in option synopsis: ${synopsis}`, { synopsis })
+  }
+}

package/src/error/too-many-arguments.ts

@@ -0,0 +1,28 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+
+import { BaseError } from "./base"
+import { ArgumentsRange } from "../types"
+import { Command } from "../command"
+import { format } from "util"
+import c from "chalk"
+
+export class TooManyArgumentsError extends BaseError {
+  constructor(cmd: Command, range: ArgumentsRange, argsCount: number) {
+    const expArgsStr =
+      range.min === range.max
+        ? `exactly ${range.min}.`
+        : `between ${range.min} and ${range.max}.`
+
+    const cmdName = cmd.isProgramCommand() ? "" : `for command ${c.bold(cmd.name)}`
+    const message = format(
+      `Too many argument(s) %s. Got %s, expected %s`,
+      cmdName,
+      c.bold.redBright(argsCount),
+      c.bold.greenBright(expArgsStr),
+    )
+    super(message, { command: cmd })
+  }
+}

package/src/error/unknown-command.ts

@@ -0,0 +1,41 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+
+import { BaseError } from "./base"
+import { getSuggestions, boldDiffString } from "../utils/suggest"
+import chalk from "chalk"
+import type { Program } from "../program"
+import flatMap from "lodash/flatMap"
+import filter from "lodash/filter"
+
+/**
+ * @todo Rewrite
+ */
+export class UnknownOrUnspecifiedCommandError extends BaseError {
+  constructor(program: Program, command?: string) {
+    const possibilities = filter(
+      flatMap(program.getCommands(), (c) => [c.name, ...c.getAliases()]),
+    )
+    let msg = ""
+    if (command) {
+      msg = `Unknown command ${chalk.bold(command)}.`
+      const suggestions = getSuggestions(command, possibilities)
+      if (suggestions.length) {
+        msg +=
+          " Did you mean " +
+          suggestions.map((s) => boldDiffString(command, s)).join(" or maybe ") +
+          " ?"
+      }
+    } else {
+      msg =
+        "Unspecified command. Available commands are:\n" +
+        possibilities.map((p) => chalk.whiteBright(p)).join(", ") +
+        "." +
+        `\n\nFor more help, type ${chalk.whiteBright(program.getBin() + " --help")}`
+    }
+
+    super(msg, { command })
+  }
+}

package/src/error/unknown-option.ts

@@ -0,0 +1,40 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+
+import { BaseError } from "./base"
+import type { Option } from "../types"
+import { getDashedOpt } from "../option/utils"
+import { getGlobalOptions } from "../option"
+import { getSuggestions, boldDiffString } from "../utils/suggest"
+import c from "chalk"
+import type { Command } from "../command"
+import filter from "lodash/fp/filter"
+import map from "lodash/fp/map"
+
+/**
+ * @todo Rewrite
+ */
+export class UnknownOptionError extends BaseError {
+  constructor(flag: string, command: Command) {
+    const longFlags = filter((f: Option) => f.name.length > 1),
+      getFlagNames = map((f: Option) => f.name),
+      possibilities = getFlagNames([
+        ...longFlags(command.options),
+        ...getGlobalOptions().keys(),
+      ]),
+      suggestions = getSuggestions(flag, possibilities)
+
+    let msg = `Unknown option ${c.bold.redBright(getDashedOpt(flag))}. `
+    if (suggestions.length) {
+      msg +=
+        "Did you mean " +
+        suggestions
+          .map((s) => boldDiffString(getDashedOpt(flag), getDashedOpt(s)))
+          .join(" or maybe ") +
+        " ?"
+    }
+    super(msg, { flag, command })
+  }
+}

package/src/error/validation.ts

@@ -0,0 +1,80 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+
+import { format } from "util"
+import c from "chalk"
+import { BaseError } from "./base"
+import { Validator, ParserTypes, Argument, Option, CaporalValidator } from "../types"
+import { isCaporalValidator } from "../validator/utils"
+
+interface ValidationErrorParameters {
+  value: ParserTypes | ParserTypes[]
+  error?: Error | string
+  validator: Validator
+  context: Argument | Option
+}
+
+function isOptionObject(obj: Option | Argument): obj is Option {
+  return "allNotations" in obj
+}
+
+export class ValidationError extends BaseError {
+  constructor({ value, error, validator, context }: ValidationErrorParameters) {
+    let message = error instanceof Error ? error.message : error
+    const varName = isOptionObject(context) ? "option" : "argument"
+    const name = isOptionObject(context)
+      ? context.allNotations.join("|")
+      : context.synopsis
+
+    if (isCaporalValidator(validator)) {
+      switch (validator) {
+        case CaporalValidator.NUMBER:
+          message = format(
+            'Invalid value for %s %s.\nExpected a %s but got "%s".',
+            varName,
+            c.redBright(name),
+            c.underline("number"),
+            c.redBright(value),
+          )
+          break
+        case CaporalValidator.BOOLEAN:
+          message = format(
+            'Invalid value for %s %s.\nExpected a %s (true, false, 0, 1), but got "%s".',
+            varName,
+            c.redBright(name),
+            c.underline("boolean"),
+            c.redBright(value),
+          )
+          break
+        case CaporalValidator.STRING:
+          message = format(
+            'Invalid value for %s %s.\nExpected a %s, but got "%s".',
+            varName,
+            c.redBright(name),
+            c.underline("string"),
+            c.redBright(value),
+          )
+          break
+      }
+    } else if (Array.isArray(validator)) {
+      message = format(
+        'Invalid value for %s %s.\nExpected one of %s, but got "%s".',
+        varName,
+        c.redBright(name),
+        "'" + validator.join("', '") + "'",
+        c.redBright(value),
+      )
+    } else if (validator instanceof RegExp) {
+      message = format(
+        'Invalid value for %s %s.\nExpected a value matching %s, but got "%s".',
+        varName,
+        c.redBright(name),
+        c.whiteBright(validator.toString()),
+        c.redBright(value),
+      )
+    }
+    super(message + "")
+  }
+}

package/src/help/__tests__/__snapshots__/help.spec.ts.snap

@@ -0,0 +1,334 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`help > getHelp() > should display customized program help 1`] = `
+"
+  test-prog  — Description test
+
+  USAGE 
+  
+    ▸ test-prog <command> [ARGUMENTS...] [OPTIONS...]
+
+
+  My custom help
+
+
+  COMMANDS — Type 'test-prog help <command>' to get some help about a command
+
+    test-command                         Test command                                           
+
+  GLOBAL OPTIONS
+
+    -h, --help                           Display global help or command-related help.           
+    -V, --version                        Display version.                                       
+    --no-color                           Disable use of colors in output.                       
+    -v, --verbose                        Verbose mode: will also output debug messages.         
+    --quiet                              Quiet mode - only displays warn and error messages.    
+    --silent                             Silent mode: does not output anything, giving no       
+                                         indication of success or failure other than the exit   
+                                         code.                                                  
+"
+`;
+
+exports[`help > getHelp() > should display customized program help on multiple lines 1`] = `
+"
+  test-prog  — Description test
+
+  USAGE 
+  
+    ▸ test-prog <command> [ARGUMENTS...] [OPTIONS...]
+
+
+  COMMANDS — Type 'test-prog help <command>' to get some help about a command
+
+    test-command                         Test command                                           
+
+  GLOBAL OPTIONS
+
+    -h, --help                           Display global help or command-related help.           
+    -V, --version                        Display version.                                       
+    --no-color                           Disable use of colors in output.                       
+    -v, --verbose                        Verbose mode: will also output debug messages.         
+    --quiet                              Quiet mode - only displays warn and error messages.    
+    --silent                             Silent mode: does not output anything, giving no       
+                                         indication of success or failure other than the exit   
+                                         code.                                                  
+"
+`;
+
+exports[`help > getHelp() > should display help for a basic program 1`] = `
+"
+  test-prog 
+
+  USAGE 
+  
+    ▸ test-prog
+
+
+
+
+  GLOBAL OPTIONS
+
+    -h, --help                           Display global help or command-related help.           
+    -V, --version                        Display version.                                       
+    --no-color                           Disable use of colors in output.                       
+    -v, --verbose                        Verbose mode: will also output debug messages.         
+    --quiet                              Quiet mode - only displays warn and error messages.    
+    --silent                             Silent mode: does not output anything, giving no       
+                                         indication of success or failure other than the exit   
+                                         code.                                                  
+"
+`;
+
+exports[`help > getHelp() > should display help for a program having at least one command (with args & options) 1`] = `
+"
+  test-prog 
+
+  USAGE 
+  
+    ▸ test-prog <command> [ARGUMENTS...] [OPTIONS...]
+
+
+  COMMANDS — Type 'test-prog help <command>' to get some help about a command
+
+    test-command                         Test command                                           
+
+  GLOBAL OPTIONS
+
+    -h, --help                           Display global help or command-related help.           
+    -V, --version                        Display version.                                       
+    --no-color                           Disable use of colors in output.                       
+    -v, --verbose                        Verbose mode: will also output debug messages.         
+    --quiet                              Quiet mode - only displays warn and error messages.    
+    --silent                             Silent mode: does not output anything, giving no       
+                                         indication of success or failure other than the exit   
+                                         code.                                                  
+"
+`;
+
+exports[`help > getHelp() > should display help for a program having at least one command (with args only) 1`] = `
+"
+  test-prog 
+
+  USAGE 
+  
+    ▸ test-prog <command> [ARGUMENTS...] [OPTIONS...]
+
+
+  COMMANDS — Type 'test-prog help <command>' to get some help about a command
+
+    test-command                         Test command                                           
+
+  GLOBAL OPTIONS
+
+    -h, --help                           Display global help or command-related help.           
+    -V, --version                        Display version.                                       
+    --no-color                           Disable use of colors in output.                       
+    -v, --verbose                        Verbose mode: will also output debug messages.         
+    --quiet                              Quiet mode - only displays warn and error messages.    
+    --silent                             Silent mode: does not output anything, giving no       
+                                         indication of success or failure other than the exit   
+                                         code.                                                  
+"
+`;
+
+exports[`help > getHelp() > should display help for a program having at least one command (with options only) 1`] = `
+"
+  test-prog 
+
+  USAGE 
+  
+    ▸ test-prog <command> [ARGUMENTS...] [OPTIONS...]
+
+
+  COMMANDS — Type 'test-prog help <command>' to get some help about a command
+
+    test-command                         Test command                                           
+
+  GLOBAL OPTIONS
+
+    -h, --help                           Display global help or command-related help.           
+    -V, --version                        Display version.                                       
+    --no-color                           Disable use of colors in output.                       
+    -v, --verbose                        Verbose mode: will also output debug messages.         
+    --quiet                              Quiet mode - only displays warn and error messages.    
+    --silent                             Silent mode: does not output anything, giving no       
+                                         indication of success or failure other than the exit   
+                                         code.                                                  
+"
+`;
+
+exports[`help > getHelp() > should display help for a program-command 1`] = `
+"
+  test-prog 
+
+  USAGE 
+  
+    ▸ test-prog <foo> [other] [OPTIONS...]
+
+
+  ARGUMENTS
+
+    <foo>                                Mandarory foo arg                                      
+    [other]                              Other args                                             
+
+  OPTIONS
+
+    -f, --file <file>                    Output file                                            
+
+  GLOBAL OPTIONS
+
+    -h, --help                           Display global help or command-related help.           
+    -V, --version                        Display version.                                       
+    --no-color                           Disable use of colors in output.                       
+    -v, --verbose                        Verbose mode: will also output debug messages.         
+    --quiet                              Quiet mode - only displays warn and error messages.    
+    --silent                             Silent mode: does not output anything, giving no       
+                                         indication of success or failure other than the exit   
+                                         code.                                                  
+"
+`;
+
+exports[`help > getHelp() > should display program description 1`] = `
+"
+  test-prog  — Description test
+
+  USAGE 
+  
+    ▸ test-prog <command> [ARGUMENTS...] [OPTIONS...]
+
+
+  COMMANDS — Type 'test-prog help <command>' to get some help about a command
+
+    test-command                         Test command                                           
+
+  GLOBAL OPTIONS
+
+    -h, --help                           Display global help or command-related help.           
+    -V, --version                        Display version.                                       
+    --no-color                           Disable use of colors in output.                       
+    -v, --verbose                        Verbose mode: will also output debug messages.         
+    --quiet                              Quiet mode - only displays warn and error messages.    
+    --silent                             Silent mode: does not output anything, giving no       
+                                         indication of success or failure other than the exit   
+                                         code.                                                  
+"
+`;
+
+exports[`help > getHelp() > should handle required options 1`] = `
+"
+  test-prog 
+
+  USAGE — test-command
+  
+    ▸ test-prog test-command  <OPTIONS...>
+
+
+
+  OPTIONS
+
+    -f, --file <file>                    Output file                                            
+    required                                                                                    
+
+  GLOBAL OPTIONS
+
+    -h, --help                           Display global help or command-related help.           
+    -V, --version                        Display version.                                       
+    --no-color                           Disable use of colors in output.                       
+    -v, --verbose                        Verbose mode: will also output debug messages.         
+    --quiet                              Quiet mode - only displays warn and error messages.    
+    --silent                             Silent mode: does not output anything, giving no       
+                                         indication of success or failure other than the exit   
+                                         code.                                                  
+"
+`;
+
+exports[`help > getHelp() > should handle type hints 1`] = `
+"
+  test-prog 
+
+  USAGE — test-command
+  
+    ▸ test-prog test-command <foo> <OPTIONS...>
+
+
+  ARGUMENTS
+
+    <foo>                                Desc                                                   
+                                         number                                                 
+
+  OPTIONS
+
+    -f, --file <file>                    Output file                                            
+    required                             number                                                 
+
+  GLOBAL OPTIONS
+
+    -h, --help                           Display global help or command-related help.           
+    -V, --version                        Display version.                                       
+    --no-color                           Disable use of colors in output.                       
+    -v, --verbose                        Verbose mode: will also output debug messages.         
+    --quiet                              Quiet mode - only displays warn and error messages.    
+    --silent                             Silent mode: does not output anything, giving no       
+                                         indication of success or failure other than the exit   
+                                         code.                                                  
+"
+`;
+
+exports[`help > getHelp() > should work with a program without a specified name 1`] = `
+"
+  test-prog 
+
+  USAGE 
+  
+    ▸ test-prog <command> [ARGUMENTS...] [OPTIONS...]
+
+
+  COMMANDS — Type 'test-prog help <command>' to get some help about a command
+
+    test-command                         Test command                                           
+
+  GLOBAL OPTIONS
+
+    -h, --help                           Display global help or command-related help.           
+    -V, --version                        Display version.                                       
+    --no-color                           Disable use of colors in output.                       
+    -v, --verbose                        Verbose mode: will also output debug messages.         
+    --quiet                              Quiet mode - only displays warn and error messages.    
+    --silent                             Silent mode: does not output anything, giving no       
+                                         indication of success or failure other than the exit   
+                                         code.                                                  
+"
+`;
+
+exports[`help > getHelp() > should work with a program without a version 1`] = `
+"
+  test-prog 
+
+  USAGE 
+  
+    ▸ test-prog <command> [ARGUMENTS...] [OPTIONS...]
+
+
+  COMMANDS — Type 'test-prog help <command>' to get some help about a command
+
+    test-command                         Test command                                           
+
+  GLOBAL OPTIONS
+
+    -h, --help                           Display global help or command-related help.           
+    -V, --version                        Display version.                                       
+    --no-color                           Disable use of colors in output.                       
+    -v, --verbose                        Verbose mode: will also output debug messages.         
+    --quiet                              Quiet mode - only displays warn and error messages.    
+    --silent                             Silent mode: does not output anything, giving no       
+                                         indication of success or failure other than the exit   
+                                         code.                                                  
+"
+`;
+
+exports[`help > tpl() > should compile template with given context 1`] = `
+"
+  test-prog 
+
+"
+`;