@villedemontreal/caporal 3.1.7

package/src/logger/__tests__/logger.spec.ts

@@ -0,0 +1,65 @@
+/* eslint-disable no-console */
+import { program } from "../../index"
+import { Program } from "../../program"
+import { logger } from ".."
+import c from "chalk"
+import stripAnsi from "strip-ansi"
+import { expect, it, describe, beforeEach, vi } from "vitest"
+import { EOL } from "os"
+
+describe("logger", () => {
+  // @ts-expect-error TS says _stdout does note exist on console but it does
+  const logStdoutSpy = vi.spyOn(console._stdout, "write") // winston use this
+  let prog = program
+
+  beforeEach(() => {
+    prog = new Program()
+    prog.name("test-prog")
+    prog.bin("test-prog")
+    prog.version("xyz")
+    logStdoutSpy.mockClear()
+    logger.level = "info"
+  })
+
+  it("logger should handle metadata", () => {
+    logger.info("foo", { blabla: "joe" })
+    expect(stripAnsi(logStdoutSpy.mock.calls[0][0] as unknown as string)).toBe(
+      `info: foo${EOL}info: { blabla: 'joe' }${EOL}`,
+    )
+  })
+
+  it("level string should be colorized by default", () => {
+    logger.info("my-info")
+    expect(logStdoutSpy).toHaveBeenLastCalledWith(
+      `${c.hex("#569cd6")("info")}: my-info${EOL}`,
+    )
+    logger.warn("my-warn")
+    expect(logStdoutSpy).toHaveBeenLastCalledWith(
+      `${c.hex("#FF9900")("warn")}: my-warn${EOL}`,
+    )
+    logger.error("my-error")
+    expect(logStdoutSpy).toHaveBeenLastCalledWith(
+      `${EOL}${c.bold.redBright("error")}: my-error${EOL}${EOL}`,
+    )
+    // set level to "debug" for the next test
+    logger.level = "debug"
+    logger.debug("my-debug")
+    expect(logStdoutSpy).toHaveBeenLastCalledWith(`${c.dim("debug")}: my-debug${EOL}`)
+
+    // set level to "silly" for the next test
+    logger.level = "silly"
+    logger.silly("my-silly")
+    expect(logStdoutSpy).toHaveBeenLastCalledWith(`${c.dim("silly")}: my-silly${EOL}`)
+
+    logger.http("foo")
+    expect(logStdoutSpy).toHaveBeenLastCalledWith(`http: foo${EOL}`)
+  })
+
+  it("logger.disableColors() should disable colors", () => {
+    logger.disableColors()
+    logger.info("my-info")
+    expect(logStdoutSpy).toHaveBeenLastCalledWith(`info: my-info${EOL}`)
+    // revert back
+    logger.colorsEnabled = true
+  })
+})

package/src/logger/index.ts

@@ -0,0 +1,97 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+import { createLogger as winstonCreateLogger, transports, format } from "winston"
+import { inspect } from "util"
+import { default as chalk, supportsColor } from "chalk"
+import type { Logger } from "../types"
+import replace from "lodash/replace"
+import { EOL } from "os"
+
+const caporalFormat = format.printf((data) => {
+  const { level, ...meta } = data
+  let { message } = data
+  let prefix = ""
+
+  const levelStr = getLevelString(level)
+  const metaStr = formatMeta(meta)
+
+  if (metaStr !== "") {
+    message += `${EOL}${levelStr}: ${metaStr}`
+  }
+
+  if (level === "error") {
+    const spaces = " ".repeat(Number(meta.paddingLeft) || 7)
+    prefix = EOL
+    message = `${replace(message.toString(), new RegExp(EOL, "g"), EOL + spaces)}${EOL}`
+  }
+
+  return `${prefix}${levelStr}: ${message}`
+})
+
+function formatMeta(meta: Record<string, unknown>): string {
+  delete meta.message
+  delete meta[Symbol.for("level") as unknown as string]
+  delete meta[Symbol.for("message") as unknown as string]
+  delete meta[Symbol.for("splat") as unknown as string]
+  if (Object.keys(meta).length) {
+    return inspect(meta, {
+      showHidden: false,
+      colors: logger.colorsEnabled,
+    })
+  }
+  return ""
+}
+
+function getLevelString(level: string): string {
+  if (!logger.colorsEnabled) {
+    return level
+  }
+  let levelStr = level
+  switch (level) {
+    case "error":
+      levelStr = chalk.bold.redBright(level)
+      break
+    case "warn":
+      levelStr = chalk.hex("#FF9900")(level)
+      break
+    case "info":
+      levelStr = chalk.hex("#569cd6")(level)
+      break
+    case "debug":
+    case "silly":
+      levelStr = chalk.dim(level)
+      break
+  }
+  return levelStr
+}
+
+export let logger: Logger = createDefaultLogger()
+
+export function setLogger(loggerObj: Logger): void {
+  logger = loggerObj
+}
+
+export function getLogger(): Logger {
+  return logger
+}
+
+export function createDefaultLogger(): Logger {
+  const logger = winstonCreateLogger({
+    transports: [
+      new transports.Console({
+        format: format.combine(format.splat(), caporalFormat),
+      }),
+    ],
+  }) as Logger
+  // disableColors() disable on the logger level,
+  // while chalk supports the --color/--no-color flag
+  // as well as the FORCE_COLOR env var
+  logger.disableColors = () => {
+    logger.transports[0].format = caporalFormat
+    logger.colorsEnabled = false
+  }
+  logger.colorsEnabled = supportsColor !== false
+  return logger
+}

package/src/option/__tests__/global.spec.ts

@@ -0,0 +1,141 @@
+/* eslint-disable no-console */
+import { program } from "../../index"
+import { Program } from "../../program"
+import { logger } from "../../logger"
+import { Action } from "../../types"
+import { disableGlobalOption, findGlobalOption, resetGlobalOptions } from ".."
+import { expect, it, describe, vi, beforeEach, afterAll } from "vitest"
+
+let prog = program
+
+describe("option / global", () => {
+  const logSpy = vi.spyOn(console, "log")
+  // @ts-expect-error TS says _stdout does note exist on console but it does
+  const logStdoutSpy = vi.spyOn(console._stdout, "write") // winston use this
+  const loggerInfoSpy = vi.spyOn(logger, "info")
+
+  beforeEach(() => {
+    prog = new Program()
+    prog.name("test-prog")
+    prog.bin("test-prog")
+    prog.version("xyz")
+    logSpy.mockClear()
+    logStdoutSpy.mockClear()
+    logger.level = "info"
+    logger.colorsEnabled = true
+    resetGlobalOptions()
+  })
+
+  afterAll(() => {
+    logger.colorsEnabled = true
+  })
+
+  it("-V should show program version and exit", async () => {
+    await prog.run(["-V"])
+    expect(logSpy).toHaveBeenLastCalledWith("xyz")
+  })
+
+  it("--version should show program version and exit", async () => {
+    await prog.run(["--version"])
+    expect(logSpy).toHaveBeenLastCalledWith("xyz")
+  })
+
+  it("--no-color should disable colors in output", async () => {
+    const action: Action = function ({ logger }) {
+      logger.info("Hey!")
+    }
+    prog.argument("[first-arg]", "First argument").action(action)
+    await prog.run(["--no-color", "foo"])
+    expect(loggerInfoSpy).toHaveBeenLastCalledWith("Hey!")
+  })
+
+  it("--color false should disable colors in output", async () => {
+    const action: Action = function ({ logger }) {
+      logger.info("Joe!")
+    }
+    prog.argument("[first-arg]", "First argument").action(action)
+    await prog.run(["--color", "false", "foo"])
+    expect(loggerInfoSpy).toHaveBeenLastCalledWith("Joe!")
+  })
+
+  it("-v should enable verbosity", async () => {
+    const action: Action = function ({ logger }) {
+      logger.info("my-info")
+      logger.debug("my-debug")
+    }
+    prog.argument("[first-arg]", "First argument").action(action)
+
+    await prog.run(["foo"])
+    expect(logStdoutSpy).toHaveBeenLastCalledWith(expect.stringContaining("my-info"))
+
+    await prog.run(["foo", "-v"])
+    expect(logStdoutSpy).toHaveBeenLastCalledWith(expect.stringContaining("my-debug"))
+  })
+
+  it("--verbose should enable verbosity", async () => {
+    const action: Action = function ({ logger }) {
+      logger.info("my-info")
+      logger.debug("my-debug")
+    }
+    prog.argument("[first-arg]", "First argument").action(action)
+
+    await prog.run(["foo"])
+    expect(logStdoutSpy).toHaveBeenLastCalledWith(expect.stringContaining("my-info"))
+
+    await prog.run(["foo", "--verbose"])
+    expect(logStdoutSpy).toHaveBeenLastCalledWith(expect.stringContaining("my-debug"))
+  })
+
+  it("--quiet should make the program only output warnings and errors", async () => {
+    const action: Action = function ({ logger }) {
+      logger.info("my-info")
+      logger.debug("my-debug")
+      logger.warn("my-warn")
+      logger.error("my-error")
+    }
+    prog.argument("[first-arg]", "First argument").action(action)
+
+    await prog.run(["foo", "--quiet"])
+    expect(logStdoutSpy).not.toHaveBeenCalledWith(expect.stringContaining("my-info"))
+    expect(logStdoutSpy).not.toHaveBeenCalledWith(expect.stringContaining("my-debug"))
+    expect(logStdoutSpy).toHaveBeenCalledWith(expect.stringContaining("my-warn"))
+    expect(logStdoutSpy).toHaveBeenCalledWith(expect.stringContaining("my-error"))
+  })
+
+  it("--silent should output nothing", async () => {
+    const action: Action = function ({ logger }) {
+      logger.info("my-info")
+      logger.debug("my-debug")
+      logger.warn("my-warn")
+      logger.error("my-error")
+    }
+    prog.argument("[first-arg]", "First argument").action(action)
+
+    await prog.run(["foo", "--silent"])
+    expect(logStdoutSpy).not.toHaveBeenCalled()
+  })
+
+  it("disableGlobalOption() should disable a global option by name or notation", async () => {
+    // by notation
+    expect(findGlobalOption("version")).toBeTruthy()
+    const result = disableGlobalOption("-V")
+    expect(result).toBe(true)
+    expect(findGlobalOption("version")).toBeUndefined()
+
+    // by name
+    expect(findGlobalOption("help")).toBeTruthy()
+    const result2 = disableGlobalOption("help")
+    expect(result2).toBe(true)
+    expect(findGlobalOption("help")).toBeUndefined()
+  })
+
+  it("disableGlobalOption() should return false for an unknown global option", async () => {
+    // by notation
+    const result = disableGlobalOption("--unknown")
+    expect(result).toBe(false)
+
+    // by name
+    const result2 = disableGlobalOption("unknown")
+    expect(result2).toBe(false)
+  })
+})

package/src/option/__tests__/option.spec.ts

@@ -0,0 +1,115 @@
+import { createOption } from ".."
+import { OptionSynopsisSyntaxError } from "../../error"
+import { expect, it, describe } from "vitest"
+
+describe("createOption()", () => {
+  it("should create a basic short option", () => {
+    const opt = createOption("-f <file>", "My simple option")
+    expect(opt).toMatchObject({
+      allNames: ["f"],
+      allNotations: ["-f"],
+      shortName: "f",
+      shortNotation: "-f",
+      description: "My simple option",
+      choices: [],
+      name: "f",
+      valueType: 1,
+      boolean: false,
+      valueRequired: true,
+      required: false,
+      synopsis: "-f <file>",
+      variadic: false,
+      visible: true,
+    })
+  })
+  it("should create a basic long option", () => {
+    const opt = createOption("--file <file>", "My simple option")
+    expect(opt).toMatchObject({
+      allNames: ["file"],
+      allNotations: ["--file"],
+      longName: "file",
+      longNotation: "--file",
+      description: "My simple option",
+      choices: [],
+      name: "file",
+      valueType: 1,
+      boolean: false,
+      valueRequired: true,
+      required: false,
+      synopsis: "--file <file>",
+      variadic: false,
+      visible: true,
+    })
+  })
+  it("should create a short option without value", () => {
+    const opt = createOption("-f", "My simple option")
+    expect(opt).toMatchObject({
+      allNames: ["f"],
+      allNotations: ["-f"],
+      shortName: "f",
+      shortNotation: "-f",
+      description: "My simple option",
+      choices: [],
+      name: "f",
+      boolean: true,
+      valueRequired: false,
+      valueType: 2,
+      default: false,
+      required: false,
+      synopsis: "-f",
+      variadic: false,
+      visible: true,
+    })
+  })
+  it("should create a short option with optional value", () => {
+    const opt = createOption("-p [mean]", "My simple option")
+    expect(opt).toMatchObject({
+      allNames: ["p"],
+      allNotations: ["-p"],
+      shortName: "p",
+      shortNotation: "-p",
+      description: "My simple option",
+      choices: [],
+      name: "p",
+      boolean: false,
+      valueRequired: false,
+      valueType: 0,
+      required: false,
+      synopsis: "-p [mean]",
+      variadic: false,
+      visible: true,
+    })
+  })
+  it("should set choices if validator is an array", () => {
+    const opt = createOption("-p [mean]", "My simple option", {
+      validator: ["card", "cash"],
+    })
+    expect(opt).toMatchObject({
+      allNames: ["p"],
+      allNotations: ["-p"],
+      shortName: "p",
+      shortNotation: "-p",
+      description: "My simple option",
+      choices: ["card", "cash"],
+      name: "p",
+      boolean: false,
+      typeHint: 'one of "card","cash"',
+      valueRequired: false,
+      validator: ["card", "cash"],
+      valueType: 0,
+      required: false,
+      synopsis: "-p [mean]",
+      variadic: false,
+      visible: true,
+    })
+  })
+
+  it.each([["bad synopsis"], ["another"], ["---fooo"]])(
+    "should throw for a malformed synopsis '%s'",
+    (a) => {
+      expect(() => createOption(a, "My simple option")).toThrowError(
+        OptionSynopsisSyntaxError,
+      )
+    },
+  )
+})

package/src/option/find.ts

@@ -0,0 +1,17 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+
+import type { Command } from "../command"
+import type { Option } from "../types"
+
+/**
+ * Find an option from its name for a given command
+ *
+ * @param cmd Command object
+ * @param name Option name, short or long, camel-cased
+ */
+export function findOption(cmd: Command, name: string): Option | undefined {
+  return cmd.options.find((o) => o.allNames.find((opt) => opt === name))
+}