@villedemontreal/caporal 3.1.7

package/src/argument/validate.ts

@@ -0,0 +1,176 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+
+import reduce from "lodash/reduce"
+import {
+  TooManyArgumentsError,
+  MissingArgumentError,
+  BaseError,
+  CommonError,
+} from "../error"
+import type {
+  Argument,
+  ArgumentsRange,
+  ParsedArguments,
+  ParsedArgumentsObject,
+  ParsedArgument,
+  Promisable,
+} from "../types"
+
+import type { Command } from "../command"
+import { validate } from "../validator/validate"
+import { findArgument } from "./find"
+
+/**
+ * Get the number of required argument for a given command
+ *
+ * @param cmd
+ */
+export function getRequiredArgsCount(cmd: Command): number {
+  return cmd.args.filter((a) => a.required).length
+}
+
+export function getArgsObjectFromArray(
+  cmd: Command,
+  args: ParsedArguments,
+): ParsedArgumentsObject {
+  const result: ParsedArgumentsObject = {}
+  return cmd.args.reduce((acc, arg, index) => {
+    if (args[index] !== undefined) {
+      acc[arg.name] = args[index]
+    } else if (arg.default !== undefined) {
+      acc[arg.name] = arg.default
+    }
+    return acc
+  }, result)
+}
+
+/**
+ * Check if the given command has at leat one variadic argument
+ *
+ * @param cmd
+ */
+export function hasVariadicArgument(cmd: Command): boolean {
+  return cmd.args.some((a) => a.variadic)
+}
+
+export function getArgsRange(cmd: Command): ArgumentsRange {
+  const min = getRequiredArgsCount(cmd)
+  const max = hasVariadicArgument(cmd) ? Infinity : cmd.args.length
+  return { min, max }
+}
+
+export function checkRequiredArgs(
+  cmd: Command,
+  args: ParsedArgumentsObject,
+  parsedArgv: ParsedArguments,
+): BaseError[] {
+  const errors = cmd.args.reduce((acc, arg) => {
+    if (args[arg.name] === undefined && arg.required) {
+      acc.push(new MissingArgumentError(arg, cmd))
+    }
+    return acc
+  }, [] as BaseError[])
+
+  // Check if there is more args than specified
+  if (cmd.strictArgsCount) {
+    const numArgsError = checkNumberOfArgs(cmd, parsedArgv)
+    if (numArgsError) {
+      errors.push(numArgsError)
+    }
+  }
+
+  return errors
+}
+
+function checkNumberOfArgs(
+  cmd: Command,
+  args: ParsedArguments,
+): TooManyArgumentsError | void {
+  const range = getArgsRange(cmd)
+  const argsCount = Object.keys(args).length
+  if (range.max !== Infinity && range.max < Object.keys(args).length) {
+    return new TooManyArgumentsError(cmd, range, argsCount)
+  }
+}
+
+export function removeCommandFromArgs(
+  cmd: Command,
+  args: ParsedArguments,
+): ParsedArguments {
+  const words = cmd.name.split(" ").length
+  return args.slice(words)
+}
+
+function validateArg(arg: Argument, value: ParsedArgument): ReturnType<typeof validate> {
+  return arg.validator ? validate(value, arg.validator, arg) : value
+}
+
+type VariadicArgument = ParsedArgument
+type ArgsValidatorAccumulator = Record<string, Promisable<VariadicArgument>>
+
+interface ArgsValidationResult {
+  args: ParsedArgumentsObject
+  errors: CommonError[]
+}
+
+/**
+ *
+ * @param cmd
+ * @param parsedArgv
+ *
+ * @todo Bugs:
+ *
+ *
+ * ts-node examples/pizza/pizza.ts cancel my-order jhazd hazd
+ *
+ * -> result ok, should be too many arguments
+ *
+ */
+export async function validateArgs(
+  cmd: Command,
+  parsedArgv: ParsedArguments,
+): Promise<ArgsValidationResult> {
+  // remove the command from the argv array
+  const formatedArgs = cmd.isProgramCommand()
+    ? parsedArgv
+    : removeCommandFromArgs(cmd, parsedArgv)
+
+  // transfrom args array to object, and set defaults for arguments not passed
+  const argsObj = getArgsObjectFromArray(cmd, formatedArgs)
+  const errors: CommonError[] = []
+
+  const validations = reduce(
+    argsObj,
+    (acc, value, key) => {
+      const arg = findArgument(cmd, key)
+      try {
+        /* istanbul ignore if -- should not happen */
+        if (!arg) {
+          throw new BaseError(`Unknown argumment ${key}`)
+        }
+        acc[key] = validateArg(arg, value)
+      } catch (e) {
+        errors.push(e)
+      }
+      return acc
+    },
+    {} as ArgsValidatorAccumulator,
+  )
+
+  const result = await reduce(
+    validations,
+    async (prevPromise, value, key): Promise<ParsedArgumentsObject> => {
+      const collection = await prevPromise
+      collection[key] = await value
+      return collection
+    },
+    Promise.resolve({}) as Promise<ParsedArgumentsObject>,
+  )
+
+  errors.push(...checkRequiredArgs(cmd, result, formatedArgs))
+
+  return { args: result, errors }
+}

package/src/autocomplete/__fixtures__/prog-autocomplete.ts

@@ -0,0 +1,24 @@
+import { program } from "../.."
+
+program
+  .bin("pizza")
+
+  // First possible command: "order"
+  .command("order", "Order a pizza")
+  .argument("<type>", "Type of pizza", {
+    validator: ["margherita", "caprese", "quattro fromaggi"],
+  })
+  .option("-e, --extra-ingredients <ingredients>", "Extra ingredients")
+
+  // Another command: "cancel"
+  .command("cancel", "Cancel an order")
+  .argument("<order-id>", "Order id")
+  .complete(function () {
+    return ["1234", "5678"]
+  })
+  .option("-c, --cash-out <type>", "Cash out type")
+  .complete(() => {
+    return Promise.resolve(["cash", "paypal", "credit-card"])
+  })
+
+export { program }

package/src/autocomplete/__tests__/autocomplete.spec.ts

@@ -0,0 +1,129 @@
+import { complete } from ".."
+import { program } from "../__fixtures__/prog-autocomplete"
+import filter from "lodash/filter"
+import { expect, it, describe } from "vitest"
+
+/**
+ * Helper to cimulate auto comp env
+ * @param cl Command line
+ * @param opts
+ * @param env
+ */
+function makeFakeEnv(
+  cl: string,
+  opts: Record<string, string> = {},
+  env = process.env,
+): { env: NodeJS.ProcessEnv; argv: string[] } {
+  let cursorPos = cl.indexOf("|")
+  if (cursorPos === -1) {
+    cursorPos = cl.length
+  }
+  cl = cl.replace("|", "")
+  const argv = filter(cl.split(" "))
+
+  env.COMP_CWORD = String(argv.length)
+  env.COMP_LINE = cl
+  env.COMP_POINT = cursorPos === -1 ? "0" : String(cursorPos)
+  env = { ...env, ...opts }
+
+  return { env, argv: [process.execPath, __filename, "completion", "--", ...argv] }
+}
+
+describe("autocomplete", () => {
+  describe("complete()", () => {
+    it("should auto-complete command name if possible", async () => {
+      const argv = "ord|"
+      await expect(complete(program, makeFakeEnv(argv))).resolves.toEqual([
+        {
+          name: "order",
+          description: expect.any(String),
+        },
+      ])
+      await expect(complete(program, makeFakeEnv("c|"))).resolves.toEqual([
+        {
+          name: "cancel",
+          description: expect.any(String),
+        },
+      ])
+    })
+
+    it("should not auto-complete command name if none are available", async () => {
+      await expect(complete(program, makeFakeEnv("wrong|"))).resolves.toEqual([])
+      await expect(complete(program, makeFakeEnv("cancel|"))).resolves.not.toContain(
+        expect.objectContaining({
+          name: "cancel",
+        }),
+      )
+    })
+
+    it("should auto-complete arguments values from choices", async () => {
+      const argv = "order |"
+      await expect(complete(program, makeFakeEnv(argv))).resolves.toEqual([
+        {
+          name: "margherita",
+          description: expect.any(String),
+        },
+        {
+          name: "caprese",
+          description: expect.any(String),
+        },
+        {
+          name: "quattro fromaggi",
+          description: expect.any(String),
+        },
+        {
+          name: "--extra-ingredients",
+          description: expect.any(String),
+        },
+      ])
+    })
+
+    it("should auto-complete arguments values from complete()", async () => {
+      const argv = "cancel |"
+      await expect(complete(program, makeFakeEnv(argv))).resolves.toEqual([
+        {
+          name: "1234",
+          description: expect.any(String),
+        },
+        {
+          name: "5678",
+          description: expect.any(String),
+        },
+        {
+          name: "--cash-out",
+          description: expect.any(String),
+        },
+      ])
+    })
+
+    it("should auto-complete partial options values from complete()", async () => {
+      const argv = "cancel --ca|"
+      await expect(complete(program, makeFakeEnv(argv))).resolves.toEqual([
+        {
+          name: "--cash-out",
+          description: expect.any(String),
+        },
+      ])
+    })
+
+    it("should auto-complete partial long options", async () => {
+      const argv = "order --ex"
+      await expect(complete(program, makeFakeEnv(argv))).resolves.toEqual([
+        {
+          name: "--extra-ingredients",
+          description: expect.any(String),
+        },
+      ])
+    })
+
+    it("should auto-complete a single dash", async () => {
+      const argv = "order -"
+      await expect(complete(program, makeFakeEnv(argv))).resolves.toEqual([
+        {
+          name: "--extra-ingredients",
+          description: expect.any(String),
+        },
+      ])
+    })
+  })
+})

package/src/autocomplete/index.ts

@@ -0,0 +1,225 @@
+/**
+ * @packageDocumentation
+ * @module caporal/autocomplete
+ */
+import tabtab from "tabtab"
+import { parseArgv } from "../parser"
+import { Program } from "../program"
+import { removeCommandFromArgs } from "../argument/validate"
+import { Argument, Option } from "../types"
+import { Command } from "../command"
+import { isOptionObject } from "../option"
+import { findCommand } from "../command/find"
+import filter from "lodash/filter"
+import flatMap from "lodash/flatMap"
+
+import { Completions, Completer, CompletionItem, CompletionContext } from "./types"
+
+const completions: Completions = new Map()
+
+/**
+ * Register a completion handler
+ *
+ * @param {Argument|Option} arg_or_opt argument or option to complete
+ * @param {Function} completer
+ */
+export function registerCompletion(
+  argOrOpt: Argument | Option,
+  completer: Completer,
+): void {
+  completions.set(argOrOpt, completer)
+}
+
+export async function installCompletion(program: Program): Promise<void> {
+  return tabtab.install({
+    name: program.getBin(),
+    completer: program.getBin(),
+  })
+}
+
+export async function uninstallCompletion(program: Program): Promise<void> {
+  return tabtab.uninstall({
+    name: program.getBin(),
+  })
+}
+
+/**
+ * Called by tabtab
+ */
+export async function complete(
+  program: Program,
+  { env, argv } = { env: process.env, argv: process.argv },
+): Promise<CompletionItem[] | false> {
+  const compEnv = tabtab.parseEnv(env)
+  if (!compEnv.complete) {
+    return false
+  }
+
+  const ctx = await getContext(program, compEnv, argv)
+  const compPromises = [
+    getCompCommands(ctx),
+    getCompArgValues(ctx),
+    getCompOptNames(ctx),
+    getCompOptValues(ctx),
+  ]
+
+  const comps = flatMap(await Promise.all(compPromises))
+  tabtab.log(comps)
+
+  return comps
+}
+
+async function getContext(
+  program: Program,
+  compEnv: tabtab.TabtabEnv,
+  argv: string[],
+): Promise<CompletionContext> {
+  const { lastPartial } = compEnv
+  argv = argv.slice(4)
+  const currentCmd = await findCommand(program, argv)
+  const parserResult = parseArgv(currentCmd?.getParserConfig(), argv)
+  const lastPartIsOpt = lastPartial.startsWith("-")
+  const lastPartIsKnownOpt = Boolean(
+    lastPartIsOpt && currentCmd && getLastPartIsKnownOpt(currentCmd, lastPartial),
+  )
+  const currentOpt = currentCmd
+    ? currentCmd.options.find((o) => o.allNames.includes(lastPartial))
+    : undefined
+
+  const ctx = {
+    program,
+    currentCmd,
+    compEnv,
+    parserResult,
+    lastPartIsOpt,
+    lastPartIsKnownOpt,
+    currentOpt,
+  }
+  return ctx
+}
+
+async function getCompCommands(ctx: CompletionContext): Promise<CompletionItem[]> {
+  const {
+    compEnv: { line },
+    program,
+    currentCmd,
+  } = ctx
+  const commandMatch = (cmd: Command, str: string): boolean => {
+    return cmd.name.startsWith(str) || cmd.getAliases().some((a) => a.startsWith(str))
+  }
+  let commands = await program.getAllCommands()
+  commands = filter(commands, (cmd) => commandMatch(cmd, line) && cmd !== currentCmd)
+  return commands.map((cmd) => ({
+    name: cmd.name,
+    description: cmd.description,
+  }))
+}
+
+async function getCompOptNames(ctx: CompletionContext): Promise<CompletionItem[]> {
+  const {
+    compEnv: { lastPartial },
+    currentCmd,
+  } = ctx
+
+  if (!currentCmd) {
+    return []
+  }
+
+  const matchOptionName = (o: Option): boolean => {
+    return Boolean(
+      (o.shortNotation != lastPartial && o.shortNotation?.startsWith(lastPartial)) ||
+        (o.longNotation != lastPartial && o.longNotation?.startsWith(lastPartial)),
+    )
+  }
+
+  return filter(currentCmd.options, matchOptionName).map((opt) => ({
+    name: opt.notation,
+    description: opt.description,
+  }))
+}
+
+async function getCompOptValues(ctx: CompletionContext): Promise<CompletionItem[]> {
+  const { currentOpt } = ctx
+  if (!currentOpt) {
+    return []
+  }
+  // Choices
+  if (currentOpt.choices.length) {
+    return currentOpt.choices.map((choice) => ({
+      name: choice.toString(),
+      description: "Value for option " + currentOpt.synopsis,
+    }))
+  }
+
+  // Promise completion
+  const completer = completions.get(currentOpt)
+  if (completer) {
+    return hanldleCompleter(ctx, completer, currentOpt)
+  }
+
+  return []
+}
+
+async function getCompArgValues(ctx: CompletionContext): Promise<CompletionItem[]> {
+  const {
+    compEnv: { lastPartial },
+    parserResult: { args },
+    currentCmd,
+    lastPartIsOpt,
+  } = ctx
+
+  if (!currentCmd || lastPartIsOpt) {
+    return []
+  }
+
+  const formatedArgs = currentCmd.isProgramCommand()
+    ? args
+    : removeCommandFromArgs(currentCmd, args)
+
+  const argsCount = formatedArgs.length
+  const arg = currentCmd.args[argsCount]
+
+  if (!arg) {
+    return []
+  }
+
+  // Choices
+  if (arg.choices.length) {
+    return arg.choices
+      .map((choice) => ({
+        name: choice.toString(),
+        description: "Value for argument " + arg.synopsis,
+      }))
+      .filter((choice) => !lastPartial || choice.name.toString().startsWith(lastPartial))
+  }
+
+  // Promise completion
+  const completion = completions.get(arg)
+  if (completion) {
+    return hanldleCompleter(ctx, completion, arg)
+  }
+
+  return []
+}
+
+async function hanldleCompleter(
+  ctx: CompletionContext,
+  completer: Completer,
+  argOrOpt: Argument | Option,
+): Promise<CompletionItem[]> {
+  const type = isOptionObject(argOrOpt) ? "option" : "argument"
+  const res = await completer(ctx)
+  return res.map((item) => {
+    if (typeof item === "object") {
+      return item
+    }
+    return {
+      name: "" + item,
+      description: `Value for ${type} ${argOrOpt.synopsis}`,
+    }
+  })
+}
+
+function getLastPartIsKnownOpt(cmd: Command, lastPartial: string): boolean {
+  return cmd.options.some((o) => o.allNames.includes(lastPartial))
+}

package/src/autocomplete/types.ts

@@ -0,0 +1,29 @@
+/**
+ * @packageDocumentation
+ * @module caporal/types
+ */
+import type { Argument, Option, Promisable, ParserResult } from "../types"
+import type tabtab from "tabtab"
+import type { Command } from "../command"
+import type { Program } from "../program"
+
+export interface CompletionItem {
+  name: string
+  description: string
+}
+
+export interface Completer {
+  (ctx: CompletionContext): Promisable<(string | CompletionItem)[]>
+}
+
+export interface CompletionContext {
+  program: Program
+  currentCmd?: Command
+  compEnv: tabtab.TabtabEnv
+  parserResult: ParserResult
+  lastPartIsOpt: boolean
+  lastPartIsKnownOpt: boolean
+  currentOpt?: Option
+}
+
+export type Completions = Map<Argument | Option, Completer>

package/src/command/__fixtures__/example-cmd.ts

@@ -0,0 +1,14 @@
+/**
+ * @packageDocumentation
+ * @ignore
+ */
+/* istanbul ignore file */
+import type { Command } from ".."
+import type { CreateCommandParameters } from "../../types"
+
+export default function ({ createCommand }: CreateCommandParameters): Command {
+  return createCommand("My command").action(({ logger }) => {
+    logger.info("Output of my command")
+    return "hey"
+  })
+}