zod-args-parser 1.0.13 → 1.0.14

package/src/autocomplete-scripts/powershell-autocomplete-script.ts

@@ -0,0 +1,78 @@
+import { transformOptionToArg } from "../utils.js";
+
+import type { Cli, Subcommand } from "../types.js";
+
+/**
+ * - Generates a PowerShell autocomplete script for your CLI.
+ * - The script assumes that your CLI is available as a `.ps1` file in the environment variable. For example:
+ *   `cliName.ps1`.
+ * - This should return a path to your script: `(Get-Command <cliName>.ps1).Source`
+ * - The generated script should be added to your `profile.ps1` file:
+ *
+ *   - Run: `notepad $profile`
+ *   - Add the following line: `. "<generated script path>"`
+ *   - Save and reopen powershell to take effect
+ */
+export function generatePowerShellAutocompleteScript(...params: [Cli, ...Subcommand[]]): string {
+  const [cli, ...subcommands] = params;
+
+  type MappedCommands = Record<string, { options: string[]; aliases: string[] }>;
+
+  const mappedCommands = subcommands.reduce((acc: MappedCommands, subcommand) => {
+    acc[subcommand.name] = {
+      options: subcommand.options?.map(option => transformOptionToArg(option.name)) ?? [],
+      aliases: subcommand.aliases ?? [],
+    };
+    return acc;
+  }, {});
+
+  const subcommandsStr = Object.keys(mappedCommands)
+    .map(key => `'${key}'`)
+    .join(", ");
+  const cliOptionsStr = cli.options?.map(option => `'${transformOptionToArg(option.name)}'`).join(", ") || "";
+
+  let switchCase = "switch ($subcommand) {\n";
+  for (const [key, { options, aliases }] of Object.entries(mappedCommands)) {
+    const optionsStr = options.map(option => `'${option}'`).join(", ");
+    switchCase += `        '${key}' { @(${optionsStr}) }\n`;
+    aliases.forEach(a => (switchCase += `        '${a}' { @(${optionsStr}) }\n`));
+  }
+  switchCase += `        default { @(${cliOptionsStr}) }\n    }`;
+
+  let functionInfo = "";
+  if (cli.description) {
+    functionInfo = `<#\n.DESCRIPTION\n${cli.description}\n${cli.example ? `\n.EXAMPLE\n${cli.example}` : ""}\n#>`;
+  }
+
+  return `# Auto-generated by zod-args-parser
+
+${functionInfo}
+function ${cli.cliName} {
+    param(
+        [Parameter(Position = 0, Mandatory = $false)]
+        [string]$subcommand,
+        [Parameter(Position = 1, ValueFromRemainingArguments = $true)]
+        [string[]]$arguments
+    )
+    $scriptPath = (Get-Command '${cli.cliName}.ps1').Source
+    if ($scriptPath) {
+        $argumentList = @($subcommand) + ($arguments | Where-Object { $_ -notin '--', '--%' }) | Where-Object { $_ -ne '' }
+        & $scriptPath @argumentList
+        return
+    }
+    Write-Error "Could not find '${cli.cliName}.ps1' script"
+}
+
+Register-ArgumentCompleter -CommandName '${cli.cliName}' -ParameterName 'subcommand' -ScriptBlock {
+    param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)
+    $subcommands = @(${subcommandsStr}${subcommandsStr && cliOptionsStr ? ", " : ""}${cliOptionsStr})
+    $subcommands | Where-Object { $_ -like "$wordToComplete*" }
+}
+
+Register-ArgumentCompleter -CommandName '${cli.cliName}' -ParameterName 'arguments' -ScriptBlock {
+    param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)
+    $subcommand = $commandAst.CommandElements[1].Value
+    $arguments = ${switchCase}
+    $arguments | Where-Object { $_ -like "$wordToComplete*" }
+}`;
+}

package/src/autocomplete-scripts/zsh-autocomplete-script.ts

@@ -0,0 +1,69 @@
+import { transformOptionToArg } from "../utils.js";
+
+import type { Cli, Option, Subcommand } from "../types.js";
+
+/**
+ * - Generates a ZSH autocomplete script for your CLI.
+ * - The generated script should be added to your `~/.zshrc` or `~/.zsh_profile` file:
+ *
+ *   - Run: `nano $HOME/.zshrc` or `nano $HOME/.zsh_profile`
+ *   - Add the following line: `source <generated script path>`
+ *   - Save and reopen zsh to take effect
+ */
+export function generateZshAutocompleteScript(...params: [Cli, ...Subcommand[]]): string {
+  const [cli, ...subcommands] = params;
+
+  const genArguments = (options: Option[]) => {
+    return options
+      ?.map(option => `'${transformOptionToArg(option.name)}[${option.description ?? ""}]'`)
+      .join(" \\\n            ");
+  };
+
+  const genSubCommand = (subcommand: Subcommand) => {
+    const options = subcommand.options;
+    if (!options || options.length === 0) return "";
+    return `${subcommand.name})
+          _arguments \\
+            ${genArguments(options)} \\
+            '*: :_files' \\
+            && ret=0
+          ;;`;
+  };
+
+  return `# Auto-generated by zod-args-parser
+
+_${cli.cliName}_autocomplete() {
+  local ret=1
+
+  _arguments -C \\
+    '1: :_${cli.cliName}_commands' \\
+    '*:: :->subcmds' \\
+    && ret=0
+
+  case $state in
+    subcmds)
+      case "$words[1]" in
+        ${subcommands.map(genSubCommand).filter(Boolean).join("\n        ")}
+        *)
+          _arguments \\
+            '*: :_files' \\
+            && ret=0
+          ;;
+      esac
+      ;;
+  esac
+
+  return $ret
+}
+  
+_${cli.cliName}_commands() {
+  local -a commands=(
+    ${subcommands.map(subcommand => `"${subcommand.name}:${subcommand.description ?? ""}"`).join("\n    ")}
+  )
+
+  _describe -t subcommands 'subcommand' commands
+}
+
+compdef _${cli.cliName}_autocomplete ${cli.cliName}
+`;
+}

package/src/help-message/colors.ts

@@ -0,0 +1,24 @@
+import chalk from "chalk";
+import type { PrintHelpOpt } from "../types.js";
+
+export type PrintHelpColors = NonNullable<Required<PrintHelpOpt["customColors"]>>;
+
+export const printColors: PrintHelpColors = {
+  title: chalk.bold.blue,
+  description: chalk.white,
+  default: chalk.dim.italic,
+  optional: chalk.dim.italic,
+  exampleTitle: chalk.yellow,
+  example: chalk.dim,
+  command: chalk.yellow,
+  option: chalk.cyan,
+  argument: chalk.green,
+  placeholder: chalk.hex("#FF9800"),
+  punctuation: chalk.white.dim,
+};
+
+export const noColors = new Proxy(printColors, {
+  get: () => {
+    return (...str: string[]) => str.join(" ");
+  },
+});

package/src/help-message/print-arguments.ts

@@ -0,0 +1,35 @@
+import { indent, print, println } from "./utils.js";
+
+import type { ArgumentMetadata } from "../types.js";
+import type { PrintHelpColors } from "./colors.js";
+
+export function printPreparedArguments(argsMetadata: ArgumentMetadata[], c: PrintHelpColors, longest: number) {
+  if (!argsMetadata.length) return;
+
+  print(c.title(" ARGUMENTS "));
+
+  println();
+
+  for (const metadata of argsMetadata) {
+    const defaultStr =
+      typeof metadata.defaultValue !== "undefined" ? `(default: ${metadata.defaultValueAsString})` : "";
+
+    const spacing = longest + 2 - metadata.name.length;
+    const normalizeDesc = metadata.description.replace(/\n/g, "\n" + indent(longest + 6) + c.punctuation("└"));
+
+    println(
+      indent(2),
+      c.argument(metadata.name),
+      indent(spacing),
+      c.description(normalizeDesc),
+      defaultStr ? c.default(defaultStr) : c.optional(metadata.optional),
+    );
+
+    if (metadata.example) {
+      const normalizeExample = metadata.example.replace(/\n/g, "\n" + indent(longest + 16));
+      println(indent(longest + 5), c.punctuation("└") + c.exampleTitle("Example:"), c.example(normalizeExample));
+    }
+  }
+
+  println();
+}

package/src/help-message/print-help-message.ts

@@ -0,0 +1,126 @@
+import { getCliMetadata } from "../metadata/get-cli-metadata.js";
+import { noColors, printColors } from "./colors.js";
+import { printPreparedArguments } from "./print-arguments.js";
+import { printOptions } from "./print-options.js";
+import { printSubcommands } from "./print-subcommands.js";
+import { concat, indent, ln, print, println } from "./utils.js";
+
+import type { Cli, PrintHelpOpt, Subcommand } from "../types.js";
+
+export function printCliHelp(params: [Cli, ...Subcommand[]], printConfig: PrintHelpOpt = {}) {
+  printConfig.colors ??= true;
+
+  const c = printConfig.colors ? printColors : noColors;
+
+  const metadata = getCliMetadata(params);
+
+  if (printConfig.customColors) {
+    Object.assign(c, printConfig.customColors);
+  }
+
+  /** Print a styled title */
+  const printTitle = (title: string) => {
+    print(c.title(` ${title.toUpperCase()} `));
+  };
+
+  // Print CLI usage
+  const usage =
+    metadata.usage ||
+    concat(
+      c.punctuation("$"),
+      metadata.name,
+      metadata.subcommands.length ? c.command("[command]") : "",
+      metadata.options.length ? c.option("[options]") : "",
+      metadata.arguments.length || metadata.allowPositional ? c.argument("<arguments>") : "",
+    );
+  printTitle("Usage");
+  println();
+  println(indent(2), usage, ln(1));
+
+  // Print CLI description
+  if (metadata.description) {
+    printTitle("Description");
+    println();
+    println(indent(2), c.description(metadata.description), ln(1));
+  }
+
+  let longest = 0;
+
+  // Prepare CLI options
+  const optionsMetadata = metadata.options;
+
+  const longestOptionTitle = optionsMetadata.reduce((acc, metadata) => {
+    const names = metadata.aliasesAsArgs.concat([metadata.nameAsArg]).join(", ");
+    const optLength = names.length + metadata.placeholder.length;
+    return optLength > acc ? optLength : acc;
+  }, 0);
+
+  if (longestOptionTitle > longest) {
+    longest = longestOptionTitle;
+  }
+
+  // Prepare CLI commands
+  const subcommandsMetadata = metadata.subcommands;
+
+  const longestSubcommandTitle = subcommandsMetadata.reduce((acc, metadata) => {
+    const names = metadata.aliases.concat([metadata.name]).join(", ");
+    const placeholder =
+      metadata.placeholder || (metadata.options.length ? "[options]" : metadata.allowPositional ? "<args>" : " ");
+    const optLength = names.length + placeholder.length;
+    return optLength > acc ? optLength : acc;
+  }, 0);
+
+  if (longestSubcommandTitle > longest) {
+    longest = longestSubcommandTitle;
+  }
+
+  // Prepare CLI arguments
+  const argsMetadata = metadata.arguments;
+
+  const longestArgTitle = argsMetadata.reduce((acc, arg) => (arg.name.length > acc ? arg.name.length : acc), 0);
+
+  if (longestArgTitle > longest) {
+    longest = longestArgTitle;
+  }
+
+  // Print CLI options
+  printOptions(optionsMetadata, c, longest);
+
+  // Print CLI commands
+  printSubcommands(subcommandsMetadata, c, longest);
+
+  // Print CLI arguments
+  printPreparedArguments(argsMetadata, c, longest);
+
+  // Print CLI example
+  if (metadata.example) {
+    printTitle("Example");
+    println();
+    const normalizeExample = metadata.example.replace(/\n/g, "\n" + indent(3));
+    println(indent(2), c.example(normalizeExample), ln(1));
+  }
+}
+
+export function printSubcommandHelp(subcommand: Subcommand, printConfig: PrintHelpOpt = {}, cliName = "") {
+  printConfig.colors ??= true;
+
+  const c = printConfig.colors ? printColors : noColors;
+
+  const usage =
+    subcommand.usage ||
+    concat(
+      c.punctuation("$"),
+      cliName,
+      c.command(subcommand.name),
+      subcommand.options?.length ? c.option("[options]") : "",
+      subcommand.arguments?.length || subcommand.allowPositional ? c.argument("<arguments>") : "",
+    );
+
+  const asCli: Cli = {
+    cliName,
+    usage,
+    ...subcommand,
+  };
+
+  printCliHelp([asCli], printConfig);
+}

package/src/help-message/print-options.ts

@@ -0,0 +1,40 @@
+import { indent, print, println } from "./utils.js";
+
+import type { PrintHelpColors } from "./colors.js";
+import type { OptionMetadata } from "../types.js";
+
+export function printOptions(optionsMetadata: OptionMetadata[], c: PrintHelpColors, longest: number) {
+  if (!optionsMetadata.length) return;
+
+  print(c.title(" OPTIONS "));
+
+  println();
+
+  for (const metadata of optionsMetadata) {
+    const names = metadata.aliasesAsArgs.concat([metadata.nameAsArg]);
+    const normalizeDesc = metadata.description.replace(/\n/g, "\n" + indent(longest + 7) + c.punctuation("└"));
+    const defaultStr =
+      typeof metadata.defaultValue !== "undefined" ? `(default: ${metadata.defaultValueAsString})` : "";
+
+    const optLength = names.join(", ").length + metadata.placeholder.length;
+    const spacing = longest + 1 - optLength;
+
+    const coloredNames = names.map(name => c.option(name)).join(c.punctuation(", "));
+
+    println(
+      indent(2),
+      coloredNames,
+      c.placeholder(metadata.placeholder),
+      indent(spacing),
+      c.description(normalizeDesc),
+      defaultStr ? c.default(defaultStr) : c.optional(metadata.optional),
+    );
+
+    if (metadata.example) {
+      const normalizeExample = metadata.example.replace(/\n/g, "\n" + indent(longest + 17));
+      println(indent(longest + 6), c.punctuation("└") + c.exampleTitle("Example:"), c.example(normalizeExample));
+    }
+  }
+
+  println();
+}

package/src/help-message/print-subcommands.ts

@@ -0,0 +1,28 @@
+import { indent, print, println } from "./utils.js";
+
+import type { SubcommandMetadata } from "src/types.js";
+import type { PrintHelpColors } from "./colors.js";
+
+export function printSubcommands(subcommandsMetadata: SubcommandMetadata[], c: PrintHelpColors, longest: number) {
+  if (!subcommandsMetadata.length) return;
+
+  print(c.title(" COMMANDS "));
+
+  println();
+
+  for (const metadata of subcommandsMetadata) {
+    const names = metadata.aliases.concat([metadata.name]);
+    const placeholder =
+      metadata.placeholder || (metadata.options.length ? "[options]" : metadata.allowPositional ? "<args>" : " ");
+    const normalizeDesc = metadata.description.replace(/\n/g, "\n" + indent(longest + 7) + c.punctuation("└"));
+
+    const optLength = names.join(", ").length + placeholder.length;
+    const spacing = longest + 1 - optLength;
+
+    const coloredNames = names.map(name => c.command(name)).join(c.punctuation(", "));
+
+    println(indent(2), coloredNames, c.placeholder(placeholder), indent(spacing), c.description(normalizeDesc));
+  }
+
+  println();
+}

package/src/help-message/utils.ts

@@ -0,0 +1,31 @@
+/** Print */
+export function print(...messages: string[]) {
+  return process.stdout.write(messages.join(" "));
+}
+
+/** Print line */
+export function println(...messages: string[]) {
+  messages = messages.filter(Boolean);
+  return console.log(...messages);
+}
+
+/** New line */
+export function ln(count: number) {
+  return "\n".repeat(count);
+}
+
+/** Space */
+export function indent(count: number) {
+  return " ".repeat(count);
+}
+
+/** Add indent before each new line */
+export function addIndentLn(message: string, indent: string = "") {
+  return message.replace(/\n/g, `\n${indent}`);
+}
+
+/** Concat strings */
+export function concat(...messages: string[]) {
+  messages = messages.filter(Boolean);
+  return messages.join(" ");
+}

package/src/index.ts

@@ -1,5 +1,3 @@
-import { help } from "./help.js";
-
 import type {
   ActionFn,
   Argument,
@@ -74,15 +72,20 @@ export function createArguments<const T extends [Argument, ...Argument[]]>(args:
   return args;
 }
 
-const { printCliHelp, printSubcommandHelp } = help;
-export { printCliHelp, printSubcommandHelp };
+export { printCliHelp, printSubcommandHelp } from "./help-message/print-help-message.js";
+
+export { parse } from "./parser/parse.js";
+export { safeParse } from "./parser/safe-parse.js";
+
+export { generateBashAutocompleteScript } from "./autocomplete-scripts/bash-autocomplete-script.js";
+export { generatePowerShellAutocompleteScript } from "./autocomplete-scripts/powershell-autocomplete-script.js";
+export { generateZshAutocompleteScript } from "./autocomplete-scripts/zsh-autocomplete-script.js";
 
-export { parse, safeParse } from "./parser.js";
+export { getArgumentsMetadata } from "./metadata/get-arguments-metadata.js";
+export { getCliMetadata } from "./metadata/get-cli-metadata.js";
+export { getOptionsMetadata } from "./metadata/get-options-metadata.js";
+export { getSubcommandsMetadata } from "./metadata/get-subcommands-metadata.js";
 
-export {
-  generateBashAutocompleteScript,
-  generateZshAutocompleteScript,
-  generatePowerShellAutocompleteScript,
-} from "./autocomplete.js";
+export { generateMarkdown } from "./markdown/generate-markdown.js";
 
 export type * from "./types.js";

package/src/markdown/generate-markdown.ts

@@ -0,0 +1,172 @@
+import { getCliMetadata } from "../metadata/get-cli-metadata.js";
+
+import type { ArgumentMetadata, Cli, OptionMetadata, Subcommand, SubcommandMetadata } from "../types.js";
+
+export function generateMarkdown(...params: [Cli, ...Subcommand[]]): string {
+  const metadata = getCliMetadata(params);
+
+  let md = "<!-- Auto-generated by zod-args-parser -->\n\n";
+
+  // Title
+  md += `# ${metadata.name}\n\n`;
+
+  // Description
+  if (metadata.description) {
+    md += `${metadata.description}\n`;
+  }
+
+  // Examples
+  if (metadata.example) {
+    md += renderExamples(metadata.example);
+  }
+
+  // Options
+  if (metadata.options.length) {
+    md += "\n## Options:\n\n";
+    md += renderOptions(metadata.options, 3);
+  }
+
+  // Arguments
+  if (metadata.arguments.length) {
+    md += "\n## Arguments:\n\n";
+    md += renderArguments(metadata.arguments, 3);
+  }
+
+  // Subcommands
+  if (metadata.subcommands.length) {
+    md += "\n## Subcommands:\n\n";
+    md += renderSubcommands(metadata.subcommands);
+  }
+
+  return md;
+}
+
+function renderExamples(examples: string, list = false) {
+  let outStr = "";
+
+  const lang = "bash";
+
+  const listIndent = " ".repeat(list ? 2 : 0);
+
+  outStr += "\n" + (list ? "- " : "");
+
+  outStr += "```" + lang + "\n";
+  outStr += listIndent + examples.replace(/\n/g, "\n" + listIndent);
+  outStr += "\n" + listIndent + "```\n";
+
+  return outStr;
+}
+
+function renderOptions(optionsMetadata: OptionMetadata[] = [], h: number) {
+  let outStr = "";
+
+  for (let i = 0; i < optionsMetadata.length; i++) {
+    const metadata = optionsMetadata[i];
+
+    const aliases = [metadata.nameAsArg].concat(metadata.aliasesAsArgs).join(", ");
+
+    const placeholder = metadata.placeholder && ` ${metadata.placeholder}`;
+
+    outStr += `${"#".repeat(h)} \`${aliases + placeholder}\``;
+
+    if (metadata.optional) {
+      outStr += " **[optional]**";
+    }
+
+    outStr += "\n\n";
+
+    if (metadata.description) {
+      outStr += `- ${metadata.description}\n`;
+    }
+
+    if (typeof metadata.defaultValue !== "undefined") {
+      outStr += `- **default:** \`${metadata.defaultValueAsString}\`\n`;
+    }
+
+    if (metadata.example) {
+      outStr += renderExamples(metadata.example, true);
+    }
+
+    if (i < optionsMetadata.length - 1) {
+      outStr += "\n";
+    }
+  }
+
+  return outStr;
+}
+
+function renderArguments(argsMetadata: ArgumentMetadata[] = [], h: number) {
+  let outStr = "";
+
+  for (let i = 0; i < argsMetadata.length; i++) {
+    const metadata = argsMetadata[i];
+
+    outStr += `${"#".repeat(h)} \`${metadata.name}\``;
+
+    if (metadata.optional) {
+      outStr += " **[optional]**";
+    }
+
+    outStr += "\n\n";
+
+    if (metadata.description) {
+      outStr += `- ${metadata.description}\n`;
+    }
+
+    if (typeof metadata.defaultValue !== "undefined") {
+      outStr += `- **default:** \`${metadata.defaultValueAsString}\`\n`;
+    }
+
+    if (metadata.example) {
+      outStr += renderExamples(metadata.example);
+    }
+
+    if (i < argsMetadata.length - 1) {
+      outStr += "\n";
+    }
+  }
+
+  return outStr;
+}
+
+function renderSubcommands(subcommandsMetadata: SubcommandMetadata[]) {
+  let outStr = "";
+
+  for (let i = 0; i < subcommandsMetadata.length; i++) {
+    const metadata = subcommandsMetadata[i];
+
+    const aliases = [metadata.name].concat(metadata.aliases).join(", ");
+
+    const placeholder = metadata.placeholder && ` ${escapeTags(metadata.placeholder)}`;
+
+    outStr += `### ${aliases + placeholder}\n\n`;
+
+    if (metadata.description) {
+      outStr += `${metadata.description}\n`;
+    }
+
+    if (metadata.example) {
+      outStr += renderExamples(metadata.example);
+    }
+
+    if (metadata.options.length) {
+      outStr += "\n#### Options:\n\n";
+      outStr += renderOptions(metadata.options, 4);
+    }
+
+    if (metadata.arguments.length) {
+      outStr += "\n#### Arguments:\n\n";
+      outStr += renderArguments(metadata.arguments, 4);
+    }
+
+    if (i < subcommandsMetadata.length - 1) {
+      outStr += "\n---\n\n";
+    }
+  }
+
+  return outStr;
+}
+
+function escapeTags(str: string) {
+  return str.replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/src/metadata/get-arguments-metadata.ts

@@ -0,0 +1,23 @@
+import { getDefaultValueFromSchema } from "../utils.js";
+
+import type { Argument, ArgumentMetadata } from "../types.js";
+
+export function getArgumentsMetadata(args: Argument[]): ArgumentMetadata[] {
+  const outputMetadata: ArgumentMetadata[] = [];
+
+  for (const arg of args) {
+    const defaultValue = getDefaultValueFromSchema(arg.type);
+
+    outputMetadata.push({
+      name: arg.name,
+      description: arg.description ?? arg.type.description ?? "",
+      defaultValue,
+      defaultValueAsString: JSON.stringify(defaultValue),
+      optional: arg.type.isOptional(),
+      example: arg.example ?? "",
+      type: arg.type,
+    });
+  }
+
+  return outputMetadata;
+}

package/src/metadata/get-cli-metadata.ts

@@ -0,0 +1,23 @@
+import { getOptionsMetadata } from "./get-options-metadata.js";
+import { getArgumentsMetadata } from "./get-arguments-metadata.js";
+import { getSubcommandsMetadata } from "./get-subcommands-metadata.js";
+
+import type { Cli, CliMetadata, Subcommand } from "../types.js";
+
+export function getCliMetadata(inputData: [Cli, ...Subcommand[]]): CliMetadata {
+  const [cli, ...subcommands] = inputData;
+
+  const outputMetadata: CliMetadata = {
+    name: cli.cliName,
+    description: cli.description ?? "",
+    placeholder: cli.placeholder ?? "",
+    usage: cli.usage ?? "",
+    example: cli.example ?? "",
+    allowPositional: cli.allowPositional ?? false,
+    options: cli.options ? getOptionsMetadata(cli.options) : [],
+    arguments: cli.arguments ? getArgumentsMetadata(cli.arguments) : [],
+    subcommands: subcommands ? getSubcommandsMetadata(subcommands) : [],
+  };
+
+  return outputMetadata;
+}