@villedemontreal/caporal 3.1.7

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

@@ -0,0 +1,144 @@
+import { getHelp, tpl, getContext, registerTemplate } from ".."
+import { Program } from "../../program"
+import { createCommand } from "../../command"
+import { findCommand } from "../../command/find"
+import strip from "strip-ansi"
+import { expect, it, describe, beforeEach } from "vitest"
+
+describe("help", () => {
+  let prog = new Program()
+
+  beforeEach(() => {
+    prog = new Program()
+    prog.name("test-prog")
+    prog.bin("test-prog")
+  })
+
+  describe("tpl()", () => {
+    it("should compile template with given context", () => {
+      const cmd = createCommand(prog, "test", "test command")
+      const ctx = getContext(prog, cmd)
+      return expect(tpl("header", ctx)).resolves.toMatchSnapshot()
+    })
+
+    it("should compile a custom template with given context", async () => {
+      const cmd = createCommand(prog, "test", "test command")
+      const ctx = getContext(prog, cmd)
+      registerTemplate("mine", () => "template-contents")
+      expect(await tpl("mine", ctx)).toBe("template-contents")
+    })
+
+    it("should fail if template does not exist", () => {
+      const cmd = createCommand(prog, "test", "test command")
+      const ctx = getContext(prog, cmd)
+      return expect(tpl("unknown", ctx)).rejects.toBeInstanceOf(Error)
+    })
+  })
+
+  describe("getHelp()", () => {
+    it("should display help for a basic program", async () => {
+      return expect(strip(await getHelp(prog))).toMatchSnapshot()
+    })
+
+    it("should display help for a program-command", async () => {
+      prog
+        .argument("<foo>", "Mandarory foo arg")
+        .argument("[other]", "Other args")
+        .option("-f, --file <file>", "Output file")
+
+      return expect(strip(await getHelp(prog))).toMatchSnapshot()
+    })
+
+    it("should display help for a program having at least one command (with args & options)", async () => {
+      prog
+        .command("test-command", "Test command")
+        .argument("<foo>", "Mandarory foo arg")
+        .argument("[other]", "Other args")
+        .option("-f, --file <file>", "Output file")
+      return expect(strip(await getHelp(prog))).toMatchSnapshot()
+    })
+
+    it("should display help for a program having at least one command (with args only)", async () => {
+      prog
+        .command("test-command", "Test command")
+        .argument("<foo>", "Mandarory foo arg")
+        .argument("[other]", "Other args")
+      return expect(strip(await getHelp(prog))).toMatchSnapshot()
+    })
+
+    it("should display help for a program having at least one command (with options only)", async () => {
+      prog
+        .command("test-command", "Test command")
+        .option("-f, --file <file>", "Output file")
+      return expect(strip(await getHelp(prog))).toMatchSnapshot()
+    })
+
+    it("should handle required options", async () => {
+      prog
+        .command("test-command", "Test command")
+        .option("-f, --file <file>", "Output file", { required: true })
+      const cmd = await findCommand(prog, ["test-command"])
+
+      expect(strip(await getHelp(prog, cmd))).toContain("required")
+      return expect(strip(await getHelp(prog, cmd))).toMatchSnapshot()
+    })
+
+    it("should handle type hints", async () => {
+      prog
+        .command("test-command", "Test command")
+        .argument("<foo>", "Desc", { validator: prog.NUMBER })
+        .option("-f, --file <file>", "Output file", {
+          required: true,
+          validator: prog.NUMBER,
+        })
+      const cmd = await findCommand(prog, ["test-command"])
+
+      return expect(strip(await getHelp(prog, cmd))).toMatchSnapshot()
+    })
+
+    it("should work with a program without a specified name", async () => {
+      prog = new Program()
+      prog.bin("test-prog")
+      prog
+        .command("test-command", "Test command")
+        .option("-f, --file <file>", "Output file")
+      return expect(strip(await getHelp(prog))).toMatchSnapshot()
+    })
+
+    it("should work with a program without a version", async () => {
+      prog = new Program()
+      prog.bin("test-prog")
+      prog.version("")
+      prog
+        .command("test-command", "Test command")
+        .option("-f, --file <file>", "Output file")
+      expect(strip(await getHelp(prog))).toMatchSnapshot()
+    })
+
+    it("should display program description", async () => {
+      prog.description("Description test")
+      prog
+        .command("test-command", "Test command")
+        .option("-f, --file <file>", "Output file")
+      expect(strip(await getHelp(prog))).toMatchSnapshot()
+    })
+
+    it("should display customized program help", async () => {
+      prog.description("Description test")
+      prog
+        .help("My custom help")
+        .command("test-command", "Test command")
+        .option("-f, --file <file>", "Output file")
+      expect(strip(await getHelp(prog))).toMatchSnapshot()
+    })
+
+    it("should display customized program help on multiple lines", async () => {
+      prog.description("Description test")
+      prog
+        .command("test-command", "Test command")
+        .option("-f, --file <file>", "Output file")
+        .help("My custom help\nAnother line\nOne last line")
+      expect(strip(await getHelp(prog))).toMatchSnapshot()
+    })
+  })
+})

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

@@ -0,0 +1,14 @@
+import { getDefaultValueHint } from "../utils"
+import { createArgument } from "../../argument"
+import { CaporalValidator } from "../../validator/caporal"
+import { expect, it, describe } from "vitest"
+
+describe("help/utils", () => {
+  it("getDefaultValueHint() should return the correct value hint", () => {
+    const arg = createArgument("<arg>", "My arg", {
+      validator: CaporalValidator.BOOLEAN,
+      default: true,
+    })
+    expect(getDefaultValueHint(arg)).toBe("default: true")
+  })
+})

package/src/help/index.ts

@@ -0,0 +1,107 @@
+/**
+ * @packageDocumentation
+ * @module caporal/help
+ */
+import { Command } from "../command"
+import { Program } from "../program"
+import replace from "lodash/replace"
+import chalk from "chalk"
+import { buildTable } from "./utils"
+import { colorize } from "../utils/colorize"
+import * as allTemplates from "./templates"
+import { getGlobalOptions } from "../option"
+import { CustomizedHelpMap, CustomizedHelpOpts, TemplateContext, Template } from "./types"
+
+const templates = new Map(Object.entries(allTemplates))
+const customHelpMap: CustomizedHelpMap = new Map()
+
+/**
+ * Customize the help
+ *
+ * @param obj
+ * @param text
+ * @param options
+ * @internal
+ */
+export function customizeHelp(
+  obj: Command | Program,
+  text: string,
+  options: Partial<CustomizedHelpOpts>,
+): void {
+  const opts: CustomizedHelpOpts = {
+    sectionName: "",
+    colorize: true,
+    ...options,
+  }
+  const data = customHelpMap.get(obj) || []
+  data.push({ text, options: opts })
+  customHelpMap.set(obj, data)
+}
+
+/**
+ * Register a new help template
+ *
+ * @param name Template name
+ * @param template Template function
+ *
+ */
+export function registerTemplate(
+  name: string,
+  template: Template,
+): Map<string, Template> {
+  return templates.set(name, template)
+}
+
+/**
+ * Helper to be used to call templates from within templates
+ *
+ * @param name Template name
+ * @param ctx Execution context
+ * @internal
+ */
+export async function tpl(name: string, ctx: TemplateContext): Promise<string> {
+  const template = templates.get(name)
+  if (!template) {
+    throw Error(`Caporal setup error: Unknown help template '${name}'`)
+  }
+  return template(ctx)
+}
+
+/**
+ * @internal
+ * @param program
+ * @param command
+ */
+export function getContext(program: Program, command?: Command): TemplateContext {
+  const spaces = " ".repeat(2)
+  const ctx: TemplateContext = {
+    prog: program,
+    cmd: command,
+    chalk: chalk,
+    colorize: colorize,
+    customHelp: customHelpMap,
+    tpl,
+    globalOptions: getGlobalOptions(),
+    table: buildTable,
+    spaces,
+    indent(str: string, sp = spaces) {
+      return sp + replace(str.trim(), /(\r\n|\r|\n)/g, "\n" + sp)
+    },
+    eol: "\n",
+    eol2: "\n\n",
+    eol3: "\n\n\n",
+  }
+  return ctx
+}
+
+/**
+ * Return the help text
+ *
+ * @param program Program instance
+ * @param command Command instance, if any
+ * @internal
+ */
+export async function getHelp(program: Program, command?: Command): Promise<string> {
+  const ctx = getContext(program, command)
+  return [await tpl("header", ctx), await tpl("usage", ctx)].join("")
+}

package/src/help/templates/command.ts

@@ -0,0 +1,27 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+import type { TemplateContext, Template } from "../types"
+import { getOptionsTable, getArgumentsTable } from "../utils"
+import sortBy from "lodash/sortBy"
+
+export const command: Template = async (ctx: TemplateContext) => {
+  const { cmd, globalOptions: globalFlags, eol, eol3, colorize, tpl } = ctx
+
+  const options = sortBy(cmd!.options, "name"),
+    globalOptions = Array.from(globalFlags.keys())
+
+  const help =
+    cmd!.synopsis +
+    eol3 +
+    (await tpl("custom", ctx)) +
+    getArgumentsTable(cmd!.args, ctx) +
+    eol +
+    getOptionsTable(options, ctx) +
+    eol +
+    getOptionsTable(globalOptions, ctx, "GLOBAL OPTIONS")
+
+  return colorize(help)
+}

package/src/help/templates/custom.ts

@@ -0,0 +1,25 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+import type { TemplateContext, Template } from "../types"
+
+export const custom: Template = (ctx: TemplateContext) => {
+  const { prog, cmd, eol2, eol3, chalk, colorize, customHelp, indent } = ctx
+  const data = customHelp.get(cmd || prog)
+  if (data) {
+    const txt = data
+      .map(({ text, options }) => {
+        let str = ""
+        if (options.sectionName) {
+          str += chalk.bold(options.sectionName) + eol2
+        }
+        const subtxt = options.colorize ? colorize(text) : text
+        str += options.sectionName ? indent(subtxt) : subtxt
+        return str + eol3
+      })
+      .join("")
+    return indent(txt) + eol3
+  }
+  return ""
+}

package/src/help/templates/header.ts

@@ -0,0 +1,19 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+import type { TemplateContext, Template } from "../types"
+
+export const header: Template = (ctx: TemplateContext) => {
+  const { prog, chalk: c, spaces, eol, eol2 } = ctx
+  const version = process.env?.NODE_ENV === "test" ? "" : prog.getVersion()
+  return (
+    eol +
+    spaces +
+    (prog.getName() || prog.getBin()) +
+    " " +
+    (version || "") +
+    (prog.getDescription() ? " \u2014 " + c.dim(prog.getDescription()) : "") +
+    eol2
+  )
+}

package/src/help/templates/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+export * from "./command"
+export * from "./header"
+export * from "./program"
+export * from "./usage"
+export * from "./custom"

package/src/help/templates/program.ts

@@ -0,0 +1,21 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+import type { TemplateContext, Template } from "../types"
+import { getOptionsTable, getCommandsTable } from "../utils"
+
+export const program: Template = async (ctx: TemplateContext) => {
+  const { prog, globalOptions, eol, eol3, colorize, tpl } = ctx
+  const commands = await prog.getAllCommands()
+  const options = Array.from(globalOptions.keys())
+  const help =
+    (await prog.getSynopsis()) +
+    eol3 +
+    (await tpl("custom", ctx)) +
+    getCommandsTable(commands, ctx) +
+    eol +
+    getOptionsTable(options, ctx, "GLOBAL OPTIONS")
+
+  return colorize(help)
+}

package/src/help/templates/usage.ts

@@ -0,0 +1,24 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+import type { TemplateContext, Template } from "../types"
+
+export const usage: Template = async (ctx: TemplateContext) => {
+  const { tpl, prog, chalk: c, spaces, eol } = ctx
+  let { cmd } = ctx
+
+  // if help is asked without a `cmd` and that no command exists
+  // within the program, override `cmd` with the program-command
+  if (!cmd && !(await prog.hasCommands())) {
+    ctx.cmd = cmd = prog.progCommand
+  }
+
+  // usage
+  const usage = `${spaces + c.bold("USAGE")} ${cmd?.name ? "— " + c.dim(cmd.name) : ""}
+  ${eol + spaces + spaces + c.dim("\u25B8")} `
+
+  const next = cmd ? await tpl("command", ctx) : await tpl("program", ctx)
+
+  return usage + next
+}

package/src/help/types.ts

@@ -0,0 +1,57 @@
+/**
+ * @packageDocumentation
+ * @module caporal/types
+ */
+import { Command } from "../command"
+import { Program } from "../program"
+import chalk from "chalk"
+import { colorize } from "../utils/colorize"
+import { buildTable } from "./utils"
+import type { GlobalOptions } from "../types"
+
+export interface CustomizedHelpOpts {
+  /**
+   * Name of the section to be added in help.
+   */
+  sectionName: string
+  /**
+   * Enable or disable the automatic coloration of text.
+   */
+  colorize: boolean
+}
+export interface CustomizedHelp {
+  /**
+   * Various display options.
+   */
+  options: CustomizedHelpOpts
+  /**
+   * Help text. Padding of the text is automatically handled for you.
+   */
+  text: string
+}
+
+export type CustomizedHelpMap = Map<Command | Program, CustomizedHelp[]>
+
+export interface Template {
+  (ctx: TemplateContext): Promise<string> | string
+}
+
+export interface TemplateFunction {
+  (name: string, ctx: TemplateContext): Promise<string> | string
+}
+
+export interface TemplateContext {
+  prog: Program
+  cmd?: Command
+  customHelp: CustomizedHelpMap
+  globalOptions: GlobalOptions
+  chalk: typeof chalk
+  colorize: typeof colorize
+  tpl: TemplateFunction
+  table: typeof buildTable
+  indent: (str: string) => string
+  eol: string
+  eol2: string
+  eol3: string
+  spaces: string
+}

package/src/help/utils.ts

@@ -0,0 +1,109 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+import { table, getBorderCharacters } from "table"
+import filter from "lodash/filter"
+import type { TemplateContext } from "./types"
+import type { Option, Argument } from "../types"
+import type { Command } from "../command"
+
+export function buildTable(data: string[][], options = {}): string {
+  return table(data, {
+    border: getBorderCharacters(`void`),
+    columnDefault: {
+      paddingLeft: 0,
+      paddingRight: 2,
+    },
+    columns: {
+      0: {
+        paddingLeft: 4,
+        width: 35,
+      },
+      1: {
+        width: 55,
+        wrapWord: true,
+        paddingRight: 0,
+      },
+    },
+    drawHorizontalLine: () => {
+      return false
+    },
+    ...options,
+  })
+}
+
+export function getDefaultValueHint(obj: Argument | Option): string | undefined {
+  return obj.default !== undefined &&
+    !("boolean" in obj && obj.boolean && obj.default === false)
+    ? "default: " + JSON.stringify(obj.default)
+    : undefined
+}
+
+function getOptionSynopsisHelp(
+  opt: Option,
+  { eol: crlf, chalk: c }: TemplateContext,
+): string {
+  return (
+    opt.synopsis +
+    (opt.required && opt.default === undefined ? crlf + c.dim("required") : "")
+  )
+}
+
+export function getOptionsTable(
+  options: Option[],
+  ctx: TemplateContext,
+  title = "OPTIONS",
+): string {
+  options = filter(options, "visible")
+  if (!options.length) {
+    return ""
+  }
+  const { chalk: c, eol: crlf, table, spaces } = ctx
+  const help = spaces + c.bold(title) + crlf + crlf
+  const rows = options.map((opt) => {
+    const def = getDefaultValueHint(opt)
+    const more = [opt.typeHint, def].filter((d) => d).join(", ")
+    const syno = getOptionSynopsisHelp(opt, ctx)
+    const desc = opt.description + (more.length ? crlf + c.dim(more) : "")
+    return [syno, desc]
+  })
+  return help + table(rows)
+}
+
+export function getArgumentsTable(
+  args: Argument[],
+  ctx: TemplateContext,
+  title = "ARGUMENTS",
+): string {
+  if (!args.length) {
+    return ""
+  }
+  const { chalk: c, eol, eol2, table, spaces } = ctx
+  const help = spaces + c.bold(title) + eol2
+  const rows = args.map((a) => {
+    const def = getDefaultValueHint(a)
+    const more = [a.typeHint, def].filter((d) => d).join(", ")
+    const desc = a.description + (more.length ? eol + c.dim(more) : "")
+    return [a.synopsis, desc]
+  })
+  return help + table(rows)
+}
+
+export function getCommandsTable(
+  commands: Command[],
+  ctx: TemplateContext,
+  title = "COMMANDS",
+): string {
+  const { chalk, prog, eol2, table, spaces } = ctx
+  const cmdHint = `Type '${prog.getBin()} help <command>' to get some help about a command`
+  const help =
+    spaces + chalk.bold(title) + ` ${chalk.dim("\u2014")} ` + chalk.dim(cmdHint) + eol2
+  const rows = commands
+    .filter((c) => c.visible)
+    .map((cmd) => {
+      return [chalk.hex("#ff9900")(cmd.name), cmd.description || ""]
+    })
+
+  return help + table(rows)
+}

package/src/index.ts

@@ -0,0 +1,93 @@
+/**
+ * Main Caporal module.
+ *
+ * ## program
+ *
+ * This represents your program. You don't have to instanciate the {@link Program} class,
+ * it's already done for you.
+ *
+ * **Usage**
+ *
+ * ```ts
+ * // The Program instance generated for you
+ * import program from "@caporal/core"
+ *
+ * program
+ *  .command(...)
+ *  .action(...)
+ * [...]
+ * ```
+ *
+ *
+ * ## parseArgv()
+ *
+ *  This is the command line parser internaly used by Caporal.
+ *
+ * ::: tip Advanced usage
+ * Usually, **you won't need to use the parser** directly, but if you
+ * just want to parse some args without all capabilities brought
+ * by Caporal, feel free to play with it.
+ * :::
+ *
+ * **Usage**
+ *
+ * ```ts
+ * import { parseArgv } from "@caporal/core"
+ *
+ * const {args, options} = parseArgv({
+ *  // ... options
+ * })
+ * ```
+ *
+ * Checkout `parseArgv()` [documentation here](/api/modules/parser.md).
+ *
+ *
+ * ## chalk
+ *
+ * `chalk` npm module re-export
+ *
+ * **Usage**
+ *
+ * ```ts
+ * import { program, chalk } from "caporal"
+ *
+ * program
+ *  .command('pay')
+ *  .argument('<amount>', 'Amount to pay', Validator.NUMBER)
+ *  .action(({logger, args}) => {
+ *    logger.info("You paid $%s", chalk.red(args.amount))
+ *  })
+ * [...]
+ * ```
+ *
+ *
+ * @packageDocumentation
+ * @module @villedemontreal/caporal
+ */
+import { Program } from "./program"
+export { Command } from "./command"
+export * from "./types"
+
+/**
+ * @ignore
+ */
+export { default as chalk } from "chalk"
+/**
+ * @ignore
+ */
+export { parseArgv, parseLine } from "./parser"
+
+/**
+ * @ignore
+ */
+export const program = new Program()
+
+/**
+ * @ignore
+ */
+export default program
+
+/**
+ * @ignore
+ */
+export { Program }