@villedemontreal/caporal 3.1.7

package/src/types.ts

@@ -0,0 +1,432 @@
+/**
+ * List of Caporal type aliases.
+ *
+ * @packageDocumentation
+ * @module caporal/types
+ */
+//
+import { Logger as WinstonLogger } from "winston"
+import { Program } from "./program"
+import { Command } from "./command"
+import { CommonError } from "./error"
+
+/**
+ * The Caporal logger interface. It extends the [Winston](https://github.com/winstonjs/winston) Logger interface
+ * and adds the following properties & methods.
+ * @noInheritDoc
+ */
+export interface Logger extends WinstonLogger {
+  /**
+   * Allow to force disabling colors.
+   */
+  disableColors(): void
+  /**
+   * Tells Caporal if colors are enabled or not.
+   */
+  colorsEnabled: boolean
+}
+
+export type GlobalOptions = Map<Option, Action | undefined>
+
+/**
+ * Caporal-provided validator flags.
+ */
+export enum CaporalValidator {
+  /**
+   * Number validator. Check that the value looks like a numeric one
+   * and cast the provided value to a javascript `Number`.
+   */
+  NUMBER = 1,
+  /**
+   * Boolean validator. Check that the value looks like a boolean.
+   * It accepts values like `true`, `false`, `yes`, `no`, `0`, and `1`
+   * and will auto-cast those values to `true` or `false`.
+   */
+  BOOLEAN = 2,
+  /**
+   * String validator. Mainly used to make sure the value is a string,
+   * and prevent Caporal auto-casting of numerics values and boolean
+   * strings like `true` or `false`.
+   */
+  STRING = 4,
+  /**
+   * Array validator. Convert any provided value to an array. If a string is provided,
+   * this validator will try to split it by commas.
+   */
+  ARRAY = 8,
+}
+
+type FunctionValidatorArgument = ParsedArgument | ParsedOption
+
+// export type FunctionValidator<T = FunctionValidatorArgument> = (
+//   value: T,
+// ) => FunctionValidatorArgument | Promise<FunctionValidatorArgument>
+
+export interface FunctionValidator<T = FunctionValidatorArgument> {
+  (value: T): Promisable<T>
+}
+
+// export type FunctionValidator<T = FunctionValidatorArgument> = (value: T) => Promisable<T>
+
+export type Validator = RegExp | FunctionValidator | CaporalValidator | ParserTypes[]
+
+/**
+ * @internal
+ */
+export interface ValidatorWrapper {
+  validate(
+    value: ParsedArgument | ParsedOption,
+  ): ParserTypes | ParserTypes[] | Promise<ParserTypes>
+  getChoices(): ParserTypes[]
+}
+
+export interface OptionSynopsis {
+  name: string
+  notation: string
+  shortName?: string
+  shortNotation?: string
+  longName?: string
+  longNotation?: string
+  allNames: string[]
+  allNotations: string[]
+  synopsis: string
+  valueRequired: boolean
+  valueType?: OptionValueType
+  variadic: boolean
+}
+
+/**
+ * Option possible value.
+ *
+ */
+export enum OptionValueType {
+  /**
+   * Value is optional.
+   */
+  Optional,
+  /**
+   * Value is required.
+   */
+  Required,
+  /**
+   * Option does not have any possible value
+   */
+  None,
+}
+
+/**
+ * Option properties
+ */
+export interface CreateOptionCommandOpts {
+  /**
+   * Optional validator
+   */
+  validator?: Validator
+  /**
+   * Default value for the Option
+   */
+  default?: ParsedOption
+  /**
+   * Set the Option as itself required
+   */
+  required?: boolean
+  /**
+   * Hide the option from help
+   */
+  hidden?: boolean
+}
+
+/**
+ * Option properties
+ */
+export interface CreateOptionProgramOpts extends CreateOptionCommandOpts {
+  /**
+   * Set to `true` for a global option.
+   */
+  global?: boolean
+  /**
+   * Action to call when a global-option is passed.
+   * Only available for global options, e.g. when `global` is set to `true`.
+   */
+  action?: Action
+}
+
+export interface CreateArgumentOpts {
+  /**
+   * Argument validator.
+   */
+  validator?: Validator
+  /**
+   * Argument default value.
+   */
+  default?: ParsedArgument
+}
+
+export interface ArgumentSynopsis {
+  /**
+   * Argument name.
+   */
+  readonly name: string
+  /**
+   * Boolean indicating if the argument is required.
+   */
+  readonly required: boolean
+  /**
+   * Synopsis string.
+   */
+  readonly synopsis: string
+  /**
+   * Boolean indicating if the argument is valiadic,
+   * e.g. can be repeated to contain an array of values.
+   */
+  readonly variadic: boolean
+}
+
+export interface Argument extends ArgumentSynopsis {
+  readonly default?: ParsedArgument
+  readonly description: string
+  readonly choices: ParsedArgument[]
+  readonly validator?: Validator
+  typeHint?: string
+  kind: "argument"
+}
+
+export interface Option extends OptionSynopsis {
+  readonly boolean: boolean
+  readonly default?: ParsedOption
+  readonly description: string
+  readonly choices: ParsedOption[]
+  readonly validator?: Validator
+  readonly required: boolean
+  readonly visible: boolean
+  typeHint?: string
+  kind: "option"
+}
+
+/**
+ * A type that could be wrapped in a Promise, or not
+ */
+export type Promisable<T> = T | Promise<T>
+
+/**
+ * Parameters object passed to an {@link Action} function
+ */
+export interface ActionParameters {
+  /**
+   * Parsed command line arguments
+   */
+  args: ParsedArgumentsObject
+  /**
+   * If the `dash` (double dash) config property is enabled,
+   * this *array* will contain all arguments present
+   * after '--'.
+   */
+  ddash: ParsedArguments
+  /**
+   * Parsed command line options
+   */
+  options: ParsedOptions
+  /**
+   * Program instance
+   */
+  program: Program
+  /**
+   * Contextual command, if any
+   */
+  command?: Command
+  /**
+   * Logger instance
+   */
+  logger: Logger
+}
+
+/**
+ * An action is a function that will be executed upon a command call.
+ */
+export interface Action {
+  (params: ActionParameters): unknown
+}
+
+export interface ErrorMetadata {
+  [meta: string]: unknown
+}
+
+export type ParserTypes = string | number | boolean
+
+/**
+ * Available options for the Caporal internal parser.
+ * Arguments must be referenced by their position (0-based) and options by their name (short or long)
+ * in {@link ParserOptions.boolean boolean}, {@link ParserOptions.string string}
+ * and {@link ParserOptions.variadic variadic} parser options.
+ *
+ */
+export interface ParserOptions {
+  /**
+   * List of {@link Argument Arguments} and {@link Options Options} to be casted as *booleans*.
+   * Arguments must be referenced by their position (0-based) and options by their name (short or long).
+   *
+   * **Example**
+   *
+   * ```ts
+   * import { parseArgv } from "caporal/parser"
+   *
+   * parseArgv({
+   *  boolean: [2, 'sendEmail']
+   * })
+   *
+   * // ./my-cli-app first-arg second-arg 3rd-arg --sendEmail=1
+   * // -> "3rd-arg" will be casted to boolean as well as "--sendEmail"
+   * ```
+   */
+  boolean: (string | number)[]
+  /**
+   * List of {@link Argument Arguments} and {@link Options Options} to be casted as *strings*.
+   * Arguments must be referenced by their position (0-based) and options by their name (short or long).
+   *
+   * **Example**
+   *
+   * ```ts
+   * import { parseArgv } from "caporal/parser"
+   *
+   * parseArgv({
+   *  string: [1]
+   * })
+   *
+   * // ./my-cli-app first-arg 2
+   * // -> second arg "2" will be casted to string instead of number
+   * ```
+   */
+  string: (string | number)[]
+  /**
+   * List of variadic {@link Argument Arguments} and {@link Options Options}, meaning
+   * that there value is an `Array`.
+   *
+   * Arguments must be referenced by their position (0-based) and options by their name (short or long).
+   *
+   * **Example**
+   *
+   * ```ts
+   * import { parseArgv } from "caporal/parser"
+   *
+   * parseArgv({
+   *  variadic: [1]
+   * })
+   *
+   * // ./pizza order margherita regina --add sausages --add basil
+   * {
+   *   args: ['order', ['margherita', 'regina']]
+   *   options: {
+   *     add: ['sausages', 'basil']
+   *   }
+   * }
+   * ```
+   */
+  variadic: (string | number)[]
+  /**
+   * Double-dash (--) handling mode. If `true`, the parser will populate the
+   * {@link ParserResult.ddash} property, otherwise, arguments will be added
+   * to {@link ParserResult.args}.
+   */
+  ddash: boolean
+  /**
+   * Option aliases map.
+   */
+  alias: Record<string, string>
+  /**
+   * Enable or disable autocasting of arguments and options. Default to `true`.
+   */
+  autoCast: boolean
+}
+
+export type ParsedArgument = ParserTypes | ParserTypes[]
+export type ParsedArguments = ParsedArgument[]
+export interface ParsedArgumentsObject {
+  [arg: string]: ParsedArgument
+}
+
+export type ParsedOption = ParserTypes | ParserTypes[]
+export interface ParsedOptions {
+  [opt: string]: ParsedOption
+}
+/**
+ * @internal
+ */
+export interface ArgumentsRange {
+  min: number
+  max: number
+}
+
+export interface ParserResult {
+  args: ParsedArguments
+  options: ParsedOptions
+  rawOptions: ParsedOptions
+  line: string
+  rawArgv: string[]
+  ddash: ParsedArguments
+}
+
+export interface ParserProcessedResult extends Omit<ParserResult, "args"> {
+  args: ParsedArgumentsObject
+  errors: CommonError[]
+}
+
+export interface CreateCommandParameters {
+  program: Program
+  createCommand(description?: string): Command
+}
+export interface CommandCreator {
+  (options: CreateCommandParameters): Command
+}
+
+/**
+ * Available configuration properties for the program.
+ */
+export type ProgramConfig = {
+  /**
+   * Strict checking of arguments count. If enabled, any additional argument willl trigger an error.
+   * Default to `true`.
+   */
+  strictArgsCount: boolean
+  /**
+   * Strict checking of options provided. If enabled, any unknown option will trigger an error.
+   * Default to `true`.
+   */
+  strictOptions: boolean
+  /**
+   * Auto-casting of arguments and options.
+   * Default to `true`.
+   */
+  autoCast: boolean
+  /**
+   * Environment variable to check for log level override.
+   * Default to "CAPORAL_LOG_LEVEL".
+   */
+  logLevelEnvVar: string
+}
+export type CommandConfig = {
+  /**
+   * Strict checking of arguments count. If enabled, any additional argument willl trigger an error.
+   */
+  strictArgsCount?: boolean
+  /**
+   * Strict checking of options provided. If enabled, any unknown option will trigger an error.
+   */
+  strictOptions?: boolean
+  /**
+   * Auto-casting of arguments and options.
+   */
+  autoCast?: boolean
+  /**
+   * Visibility of the command in help.
+   */
+  visible: boolean
+}
+
+export type BaseConfig = Record<string, boolean | string>
+
+export interface Configurator<T extends BaseConfig> {
+  get<K extends keyof T>(key: K): T[K]
+  getAll(): T
+  set(props: Partial<T>): T
+  reset(): T
+}

package/src/utils/__tests__/fs.spec.ts

@@ -0,0 +1,14 @@
+import { readdir } from "../fs"
+import { expect, it, describe } from "vitest"
+
+describe("readdir()", () => {
+  it("should resolve to a file list on success", async () => {
+    const files = await readdir(__dirname)
+    return expect(files.sort()).toEqual(
+      ["fs.spec.ts", "levenshtein.spec.ts", "suggest.spec.ts"].sort(),
+    )
+  })
+  it("should reject if directory does note exist", () => {
+    return expect(readdir("/does/not/exist")).rejects.toBeInstanceOf(Error)
+  })
+})

package/src/utils/__tests__/levenshtein.spec.ts

@@ -0,0 +1,16 @@
+import { levenshtein } from "../levenshtein"
+import { expect, it, describe } from "vitest"
+
+describe("levenshtein", () => {
+  it.each([
+    ["hello", "bye", 5],
+    ["some", "sometimes", 5],
+    ["john", "jane", 3],
+    ["exemple", "example", 1],
+    ["", "", 0],
+    ["not-empty", "", 9],
+    ["", "not-empty", 9],
+  ])(".levenshtein('%s', '%s')", (a, b, expected) => {
+    expect(levenshtein(a, b)).toBe(expected)
+  })
+})

package/src/utils/__tests__/suggest.spec.ts

@@ -0,0 +1,30 @@
+import { getSuggestions, boldDiffString } from "../suggest"
+import c from "chalk"
+import { expect, it, describe } from "vitest"
+
+describe("Suggest", () => {
+  describe("getSuggestions()", () => {
+    it("should return proper suggestions", () => {
+      const suggestions = getSuggestions("foo", ["foa", "foab", "foabc", "afoo", "bfoap"])
+      expect(suggestions).toStrictEqual(["foa", "afoo", "foab"])
+    })
+  })
+  describe("boldDiffString()", () => {
+    it("should make the diff bold at the end of the word", () => {
+      expect(boldDiffString("foo", "foob")).toEqual("foo" + c.bold.greenBright("b"))
+    })
+    it("should make the diff bold at the beginning of the word", () => {
+      expect(boldDiffString("foo", "doo")).toBe(c.bold.greenBright("d") + "oo")
+    })
+
+    it("should make the diff bold at the middle of the word", () => {
+      expect(boldDiffString("foo", "fao")).toBe("f" + c.bold.greenBright("a") + "o")
+    })
+
+    it("should make the diff bold anywhere in the word", () => {
+      expect(boldDiffString("minimum", "maximum")).toBe(
+        "m" + c.bold.greenBright("a") + c.bold.greenBright("x") + "imum",
+      )
+    })
+  })
+})

package/src/utils/colorize.ts

@@ -0,0 +1,21 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+import c from "chalk"
+
+export function colorize(text: string): string {
+  return text
+    .replace(/<([^>]+)>/gi, (match) => {
+      return c.hex("#569cd6")(match)
+    })
+    .replace(/<command>/gi, (match) => {
+      return c.hex("#ff9900")(match)
+    })
+    .replace(/\[([^[\]]+)\]/gi, (match) => {
+      return c.hex("#aaa")(match)
+    })
+    .replace(/ --?([^\s,]+)/gi, (match) => {
+      return c.green(match)
+    })
+}

package/src/utils/fs.ts

@@ -0,0 +1,13 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+import { glob } from "glob"
+import fs from "fs"
+
+export function readdir(dirPath: string, extensions = "js,ts"): Promise<string[]> {
+  if (!fs.existsSync(dirPath)) {
+    return Promise.reject(new Error(`'${dirPath}' does not exist!`))
+  }
+  return glob(`**/*.{${extensions}}`, { cwd: dirPath })
+}

package/src/utils/levenshtein.ts

@@ -0,0 +1,28 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+export function levenshtein(a: string, b: string): number {
+  if (a === b) {
+    return 0
+  }
+  if (!a.length || !b.length) {
+    return a.length || b.length
+  }
+  let cell = 0
+  let lcell = 0
+  let dcell = 0
+  const row = [...Array(b.length + 1).keys()]
+  for (let i = 0; i < a.length; i++) {
+    dcell = i
+    lcell = i + 1
+    for (let j = 0; j < b.length; j++) {
+      cell = a[i] === b[j] ? dcell : Math.min(...[dcell, row[j + 1], lcell]) + 1
+      dcell = row[j + 1]
+      row[j] = lcell
+      lcell = cell
+    }
+    row[row.length - 1] = cell
+  }
+  return cell
+}

package/src/utils/suggest.ts

@@ -0,0 +1,52 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+import chalk from "chalk"
+import { levenshtein } from "./levenshtein"
+
+interface Suggestion {
+  distance: number
+  suggestion: string
+}
+
+const MAX_DISTANCE = 2
+
+const sortByDistance = (a: Suggestion, b: Suggestion): number => a.distance - b.distance
+
+const keepMeaningfulSuggestions = (s: Suggestion): boolean => s.distance <= MAX_DISTANCE
+
+const possibilitesMapper = (input: string, p: string): Suggestion => {
+  return { suggestion: p, distance: levenshtein(input, p) }
+}
+
+/**
+ * Get autocomplete suggestions
+ *
+ * @param {String} input - User input
+ * @param {String[]} possibilities - Possibilities to retrieve suggestions from
+ */
+export function getSuggestions(input: string, possibilities: string[]): string[] {
+  return possibilities
+    .map((p) => possibilitesMapper(input, p))
+    .filter(keepMeaningfulSuggestions)
+    .sort(sortByDistance)
+    .map((p) => p.suggestion)
+}
+
+/**
+ * Make diff bolder in a string
+ *
+ * @param from original string
+ * @param to target string
+ */
+export function boldDiffString(from: string, to: string): string {
+  return [...to]
+    .map((char, index) => {
+      if (char != from.charAt(index)) {
+        return chalk.bold.greenBright(char)
+      }
+      return char
+    })
+    .join("")
+}

package/src/utils/version.ts

@@ -0,0 +1,14 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+import path from "path"
+
+export function detectVersion(): string | undefined {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    return require(path.join(__filename, "..", "..", "..", "package.json")).version
+    // eslint-disable-next-line no-empty
+  } catch (e) {}
+  return undefined
+}

package/src/utils/web/autocomplete.ts

@@ -0,0 +1,19 @@
+/**
+ * Autocomplete mock for caporal-web
+ *
+ * @packageDocumentation
+ * @internal
+ */
+import type { Program } from "../../program"
+import type { Argument, Option } from "../../types"
+/* eslint-disable @typescript-eslint/explicit-function-return-type */
+/* eslint-disable @typescript-eslint/no-empty-function */
+/* eslint-disable @typescript-eslint/no-unused-vars */
+export function registerCompletion(
+  argOrOpt: Argument | Option,
+  completer: () => unknown,
+) {}
+
+export async function installCompletion(program: Program): Promise<void> {}
+
+export async function uninstallCompletion(program: Program): Promise<void> {}

package/src/utils/web/process.ts

@@ -0,0 +1,24 @@
+/**
+ * A process mock for the web
+ *
+ * @packageDocumentation
+ * @internal
+ */
+/* eslint-disable @typescript-eslint/explicit-function-return-type */
+/* eslint-disable @typescript-eslint/no-empty-function */
+/* eslint-disable no-console */
+export const version = process.version
+export const argv = ["node", "play.ts"]
+export const execArgv = [] as any[]
+export const exitCode = 0
+export const fake = true
+export const on = () => {}
+export const once = () => {}
+export const exit = function (code = 0) {
+  if (code > 0) {
+    return console.debug(
+      `[playground process exiting with code ${code} - usually a fatal error]`,
+    )
+  }
+  console.debug(`[process exiting with code ${code}]`)
+}