zod-args-parser 1.2.8 → 2.0.0-beta.0

package/src/markdown/generate-markdown.ts

@@ -1,10 +1,11 @@
-import { getCliMetadata } from "../metadata/get-cli-metadata.js";
+import { getCliMetadata } from "../metadata/cli-metadata.ts";
+import { escapeHtmlTags, stripAnsi } from "../utilities.ts";
 
-import type { ArgumentMetadata, OptionMetadata, SubcommandMetadata } from "../metadata/metadata-types.js";
-import type { Cli, Subcommand } from "../types.js";
+import type { Cli } from "../types/definitions-types.ts";
+import type { ArgumentMetadata, OptionMetadata, SubcommandMetadata } from "../types/metadata-types.ts";
 
-export function generateMarkdown(...parameters: [Cli, ...Subcommand[]]): string {
-  const metadata = getCliMetadata(parameters);
+export function generateMarkdown(cliDefinition: Cli): string {
+  const metadata = getCliMetadata(cliDefinition);
 
   let md = "<!-- Auto-generated by zod-args-parser -->\n\n";
 
@@ -12,8 +13,13 @@ export function generateMarkdown(...parameters: [Cli, ...Subcommand[]]): string
   md += `# ${metadata.name}\n\n`;
 
   // Description
-  if (metadata.description) {
-    md += `${metadata.description}\n`;
+  if (metadata.description && !metadata.descriptionMarkdown) {
+    md += `${forceLineBreak(metadata.description)}\n`;
+  }
+
+  // Description Markdown
+  if (metadata.descriptionMarkdown) {
+    md += `${forceLineBreak(metadata.descriptionMarkdown)}\n`;
   }
 
   // Examples
@@ -45,18 +51,15 @@ export function generateMarkdown(...parameters: [Cli, ...Subcommand[]]): string
   return md;
 }
 
-function renderExamples(examples: string, list = false) {
-  let outString = "";
+function renderExamples(examples: string) {
+  let outString = "\n**Example:**\n";
 
   const lang = "bash";
 
-  const listIndent = " ".repeat(list ? 2 : 0);
-
-  outString += "\n" + (list ? "- " : "");
-
+  outString += "\n";
   outString += "```" + lang + "\n";
-  outString += listIndent + examples.replace(/\n/g, "\n" + listIndent);
-  outString += "\n" + listIndent + "```\n";
+  outString += examples;
+  outString += "\n```\n";
 
   return outString;
 }
@@ -66,6 +69,7 @@ function renderOptions(optionsMetadata: OptionMetadata[] = [], h: number) {
 
   for (let index = 0; index < optionsMetadata.length; index++) {
     const metadata = optionsMetadata[index];
+    if (metadata.hidden) continue;
 
     const aliases = [metadata.nameAsArg].concat(metadata.aliasesAsArgs).join(", ");
 
@@ -74,21 +78,25 @@ function renderOptions(optionsMetadata: OptionMetadata[] = [], h: number) {
     outString += `${"#".repeat(h)} \`${aliases + placeholder}\``;
 
     if (metadata.optional) {
-      outString += " **[optional]**";
+      outString += " _optional_";
     }
 
     outString += "\n\n";
 
-    if (metadata.description) {
-      outString += `- ${metadata.description.replace(/(\n+)/g, "  $1  ")}\n`;
+    if (metadata.description && !metadata.descriptionMarkdown) {
+      outString += `${forceLineBreak(metadata.description)}\n`;
+    }
+
+    if (metadata.descriptionMarkdown) {
+      outString += `${forceLineBreak(metadata.descriptionMarkdown)}\n`;
     }
 
     if (metadata.defaultValue !== undefined) {
-      outString += `- **default:** \`${metadata.defaultValueAsString}\`\n`;
+      outString += `\n**default:** \`${metadata.defaultValueAsString}\`\n`;
     }
 
     if (metadata.example) {
-      outString += renderExamples(metadata.example, true);
+      outString += renderExamples(metadata.example);
     }
 
     if (index < optionsMetadata.length - 1) {
@@ -104,21 +112,26 @@ function renderArguments(argumentsMetadata: ArgumentMetadata[] = [], h: number)
 
   for (let index = 0; index < argumentsMetadata.length; index++) {
     const metadata = argumentsMetadata[index];
+    if (metadata.hidden) continue;
 
     outString += `${"#".repeat(h)} \`${metadata.name}\``;
 
     if (metadata.optional) {
-      outString += " **[optional]**";
+      outString += " _optional_";
     }
 
     outString += "\n\n";
 
-    if (metadata.description) {
-      outString += `- ${metadata.description.replace(/(\n+)/g, "  $1  ")}\n`;
+    if (metadata.description && !metadata.descriptionMarkdown) {
+      outString += `${forceLineBreak(metadata.description)}\n`;
+    }
+
+    if (metadata.descriptionMarkdown) {
+      outString += `${forceLineBreak(metadata.descriptionMarkdown)}\n`;
     }
 
     if (metadata.defaultValue !== undefined) {
-      outString += `- **default:** \`${metadata.defaultValueAsString}\`\n`;
+      outString += `\n**default:** \`${metadata.defaultValueAsString}\`\n`;
     }
 
     if (metadata.example) {
@@ -138,6 +151,7 @@ function renderSubcommands(subcommandsMetadata: SubcommandMetadata[]) {
 
   for (let index = 0; index < subcommandsMetadata.length; index++) {
     const metadata = subcommandsMetadata[index];
+    if (metadata.hidden) continue;
 
     const aliases = [metadata.name].concat(metadata.aliases).join(", ");
 
@@ -145,8 +159,12 @@ function renderSubcommands(subcommandsMetadata: SubcommandMetadata[]) {
 
     outString += `### ${aliases + placeholder}\n\n`;
 
-    if (metadata.description) {
-      outString += `${metadata.description}\n`;
+    if (metadata.description && !metadata.descriptionMarkdown) {
+      outString += `${forceLineBreak(metadata.description)}\n`;
+    }
+
+    if (metadata.descriptionMarkdown) {
+      outString += `${forceLineBreak(metadata.descriptionMarkdown)}\n`;
     }
 
     if (metadata.example) {
@@ -171,36 +189,7 @@ function renderSubcommands(subcommandsMetadata: SubcommandMetadata[]) {
   return outString;
 }
 
-function escapeHtmlTags(markdown: string) {
-  return markdown.replace(/(```[\s\S]*?```|`[^`]*`)|(<[^>]+>)/g, (_: string, code: string, html: string) => {
-    if (code) {
-      return code;
-    }
-
-    return html.replace(/[&<>]/g, match => {
-      return { "&": "&amp;", "<": "&lt;", ">": "&gt;" }[match as "&" | "<" | ">"];
-    });
-  });
-}
-
-/** Credits: https://github.com/chalk/ansi-regex */
-function ansiRegex({ onlyFirst = false } = {}) {
-  // Valid string terminator sequences are BEL, ESC\, and 0x9c
-  const ST = String.raw`(?:\u0007|\u001B\u005C|\u009C)`;
-
-  // OSC sequences only: ESC ] ... ST (non-greedy until the first ST)
-  const osc = `(?:\\u001B\\][\\s\\S]*?${ST})`;
-
-  // CSI and related: ESC/C1, optional intermediates, optional params (supports ; and :) then final byte
-  const csi = String.raw`[\u001B\u009B][[\]()#;?]*(?:\d{1,4}(?:[;:]\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~]`;
-
-  const pattern = `${osc}|${csi}`;
-
-  return new RegExp(pattern, onlyFirst ? undefined : "g");
-}
-
-const regex = ansiRegex();
-
-function stripAnsi(string: string): string {
-  return string.replace(regex, "");
+/** Inserts two trailing spaces before newline. In Markdown, a newline that ends with two spaces forces a line break. */
+function forceLineBreak(string: string): string {
+  return string.replace(/(\n+)/g, "  $1");
 }

package/src/metadata/arguments-metadata.ts

@@ -0,0 +1,28 @@
+import { defaultValueAndIsOptional, stringifyValue } from "../utilities.ts";
+
+import type { Argument } from "../types/definitions-types.ts";
+import type { ArgumentMetadata } from "../types/metadata-types.ts";
+
+export function getArgumentsMetadata(argumentsDefinition: Record<string, Argument>): ArgumentMetadata[] {
+  const outputMetadata: ArgumentMetadata[] = [];
+
+  for (const [name, argument] of Object.entries(argumentsDefinition)) {
+    const meta = argument.meta ?? {};
+
+    const { optional, defaultValue } = argument._preparedType ?? defaultValueAndIsOptional(argument.schema);
+
+    outputMetadata.push({
+      name: meta.name ?? name,
+      description: meta.description ?? "",
+      descriptionMarkdown: meta.descriptionMarkdown ?? "",
+      defaultValue,
+      defaultValueAsString: meta.default ?? stringifyValue(defaultValue) ?? "",
+      optional: meta.optional ?? optional,
+      example: meta.example ?? "",
+      schema: argument.schema,
+      hidden: meta.hidden ?? false,
+    });
+  }
+
+  return outputMetadata;
+}

package/src/metadata/cli-metadata.ts

@@ -0,0 +1,26 @@
+import { getArgumentsMetadata } from "./arguments-metadata.ts";
+import { getOptionsMetadata } from "./options-metadata.ts";
+import { getSubcommandsMetadata } from "./subcommands-metadata.ts";
+
+import type { Cli } from "../types/definitions-types.ts";
+import type { CliMetadata } from "../types/metadata-types.ts";
+
+export function getCliMetadata(cliDefinition: Cli): CliMetadata {
+  const subcommands = cliDefinition.subcommands ?? [];
+
+  const meta = cliDefinition.meta ?? {};
+
+  const outputMetadata: CliMetadata = {
+    name: cliDefinition.cliName,
+    description: meta.description ?? "",
+    descriptionMarkdown: meta.descriptionMarkdown ?? "",
+    usage: meta.usage ?? "",
+    example: meta.example ?? "",
+    allowPositionals: cliDefinition.allowPositionals ?? false,
+    options: cliDefinition.options ? getOptionsMetadata(cliDefinition.options) : [],
+    arguments: cliDefinition.arguments ? getArgumentsMetadata(cliDefinition.arguments) : [],
+    subcommands: subcommands ? getSubcommandsMetadata(subcommands) : [],
+  };
+
+  return outputMetadata;
+}

package/src/metadata/options-metadata.ts

@@ -0,0 +1,38 @@
+import { transformOptionToArgument } from "../parse/parser-utilities.ts";
+import { defaultValueAndIsOptional, stringifyValue } from "../utilities.ts";
+
+import type { Option } from "../types/definitions-types.ts";
+import type { OptionMetadata } from "../types/metadata-types.ts";
+
+export function getOptionsMetadata(optionsDefinition: Record<string, Option>): OptionMetadata[] {
+  const outputMetadata: OptionMetadata[] = [];
+
+  if (!optionsDefinition) {
+    return outputMetadata;
+  }
+
+  for (const [optionName, option] of Object.entries(optionsDefinition)) {
+    const aliases = option.aliases ?? [];
+    const meta = option.meta ?? {};
+
+    const { optional, defaultValue } = option._preparedType ?? defaultValueAndIsOptional(option.schema);
+
+    outputMetadata.push({
+      name: optionName,
+      nameAsArg: transformOptionToArgument(optionName),
+      aliases,
+      aliasesAsArgs: aliases.map(alias => transformOptionToArgument(alias)),
+      placeholder: meta.placeholder ?? "",
+      description: meta.description ?? "",
+      descriptionMarkdown: meta.descriptionMarkdown ?? "",
+      optional: meta.optional ?? optional,
+      example: meta.example ?? "",
+      defaultValue,
+      defaultValueAsString: meta.default ?? stringifyValue(defaultValue) ?? "",
+      schema: option.schema,
+      hidden: meta.hidden ?? false,
+    });
+  }
+
+  return outputMetadata;
+}

package/src/metadata/subcommands-metadata.ts

@@ -0,0 +1,35 @@
+import { getArgumentsMetadata } from "./arguments-metadata.ts";
+import { getOptionsMetadata } from "./options-metadata.ts";
+
+import type { Subcommand } from "../types/definitions-types.ts";
+import type { SubcommandMetadata } from "../types/metadata-types.ts";
+
+export function getSubcommandsMetadata(commandDefinition: readonly Subcommand[]): SubcommandMetadata[] {
+  const outputMetadata: SubcommandMetadata[] = [];
+
+  if (!commandDefinition || commandDefinition.length === 0) {
+    return outputMetadata;
+  }
+
+  for (const subcommand of commandDefinition) {
+    const optionsMetadata = subcommand.options ? getOptionsMetadata(subcommand.options) : [];
+    const argumentsMetadata = subcommand.arguments ? getArgumentsMetadata(subcommand.arguments) : [];
+    const meta = subcommand.meta ?? {};
+
+    outputMetadata.push({
+      name: subcommand.name,
+      aliases: subcommand.aliases ?? [],
+      description: meta.description ?? "",
+      descriptionMarkdown: meta.descriptionMarkdown ?? "",
+      placeholder: meta.placeholder ?? "",
+      usage: meta.usage ?? "",
+      example: meta.example ?? "",
+      allowPositionals: subcommand.allowPositionals ?? false,
+      options: optionsMetadata,
+      arguments: argumentsMetadata,
+      hidden: meta.hidden ?? false,
+    });
+  }
+
+  return outputMetadata;
+}

package/src/parse/context/cli-context-builder.ts

@@ -0,0 +1,246 @@
+import {
+  decoupleFlags,
+  findOption,
+  findSubcommandDefinition,
+  isFlagArgument,
+  isOptionArgument,
+  transformOptionToArgument,
+} from "../parser-utilities.ts";
+
+import type { ContextWide } from "../../types/context-types.ts";
+import type { Cli } from "../../types/definitions-types.ts";
+
+/**
+ * Parse argv and create a cli context
+ *
+ * @throws {Error}
+ */
+export function buildCliContext(argv: string[], cliDefinition: Cli) {
+  const subcommandArray = cliDefinition.subcommands ?? [];
+  const allSubcommands = new Set<string>(subcommandArray.flatMap(c => [c.name, ...(c.aliases || [])]));
+
+  // decouple flags E.g. `-rf` -> `-r, -f`
+  argv = decoupleFlags(argv);
+
+  const context: ContextWide = {
+    subcommand: undefined,
+  };
+
+  /** Get the current subcommand definition or cli definition if subcommand name is `undefined` object */
+  const getCommandDefinition = () => findSubcommandDefinition(context.subcommand, cliDefinition);
+
+  for (let index = 0; index < argv.length; index++) {
+    const argvItem = argv[index];
+
+    // * Subcommand check
+    if (index === 0) {
+      context.subcommand = allSubcommands.has(argvItem) ? argvItem : undefined;
+
+      // First argument is a subcommand. Skip to the next argument
+      if (context.subcommand) continue;
+    }
+
+    // * Option check
+
+    const argumentAndValue = argvItem.split("=").filter(Boolean); // E.g --option=value -> ["--option", "value"]
+    const argumentWithEquals = argvItem.includes("="); // E.g --option=value
+    const argument = argumentAndValue[0];
+    const argumentValue: string | undefined = argumentAndValue[1];
+
+    if (isOptionArgument(argument)) {
+      if (isFlagArgument(argument) && argumentWithEquals) {
+        throw new Error(`flag arguments cannot be assigned using "=": "${argvItem}"`);
+      }
+
+      const commandDefinition = getCommandDefinition();
+      if (!commandDefinition) {
+        throw new Error(`unknown subcommand: "${context.subcommand}"`);
+      }
+
+      if (!commandDefinition.options) {
+        if (!context.subcommand) {
+          throw new Error(`options are not allowed here: "${argument}"`);
+        }
+
+        throw new Error(`subcommand "${context.subcommand}" does not accept options: "${argument}"`);
+      }
+
+      const nameOptionTuple = findOption(argument, commandDefinition.options);
+      if (!nameOptionTuple) {
+        throw new Error(`unknown option: "${argument}"`);
+      }
+
+      const [optionName, optionDefinition] = nameOptionTuple;
+
+      if (context.options && optionName in context.options) {
+        throw new Error(`duplicated option: "${argument}"`);
+      }
+
+      if (!optionDefinition._preparedType) {
+        throw new Error(`internal error: missing prepared type for option "${optionName}"`);
+      }
+
+      const { schema, optional, defaultValue, coerceTo } = optionDefinition._preparedType;
+
+      const nextArgument = argv[index + 1];
+
+      let optionValue: string | boolean = argumentWithEquals ? argumentValue : nextArgument;
+
+      // infer value for boolean options
+      if (coerceTo === "boolean") {
+        if (!argumentWithEquals) {
+          optionValue = "true";
+        }
+
+        const isNegated = argument.startsWith("--no-");
+
+        if (isNegated && ["true", "false"].includes(optionValue.toLowerCase())) {
+          optionValue = optionValue === "true" ? "false" : "true";
+        }
+      }
+
+      if (optionValue === undefined) {
+        throw new Error(`expected a value for "${argument}" but got nothing`);
+      }
+
+      if (!argumentWithEquals && isOptionArgument(optionValue)) {
+        throw new Error(`expected a value for "${argument}" but got an argument "${nextArgument}"`);
+      }
+
+      context.options ??= {};
+      context.options[optionName] = {
+        schema,
+        optional,
+        defaultValue,
+        flag: argument,
+        stringValue: optionValue,
+        source: "terminal",
+      };
+
+      // Skip to the next argument if it is the current option's value.
+      if (!argumentWithEquals && coerceTo !== "boolean") {
+        index++;
+      }
+
+      continue;
+    }
+
+    const commandDefinition = getCommandDefinition();
+
+    // * Arguments check
+    if (commandDefinition?.arguments) {
+      context.arguments ??= {};
+
+      const currentArgumentCount = Object.keys(context.arguments).length;
+      const argumentDefinitionEntries = Object.entries(commandDefinition.arguments);
+
+      // The current argument is a typed argument and not a positional
+      if (currentArgumentCount < argumentDefinitionEntries.length) {
+        const [name, argumentDefinition] = argumentDefinitionEntries[currentArgumentCount];
+
+        if (!argumentDefinition._preparedType) {
+          throw new Error(`internal error: missing prepared type for argument "${currentArgumentCount}"`);
+        }
+
+        const { schema, optional, defaultValue } = argumentDefinition._preparedType;
+
+        context.arguments[name] = { schema, optional, defaultValue, stringValue: argvItem, source: "terminal" };
+        continue;
+      }
+    }
+
+    // The current argument is a positional and not a typed argument (when `allowPositionals` is enabled)
+    if (commandDefinition?.allowPositionals) {
+      context.positionals ??= [];
+      context.positionals.push(argvItem);
+      continue;
+    }
+
+    if (!context.subcommand) {
+      throw new Error(`unexpected argument "${argvItem}": positionals arguments are not allowed here`);
+    }
+
+    throw new Error(
+      `unexpected argument "${argvItem}": positionals arguments are not allowed for subcommand "${context.subcommand}"`,
+    );
+  }
+
+  const commandDefinition = getCommandDefinition();
+  if (!commandDefinition) {
+    throw new Error(`unknown subcommand: "${context.subcommand}"`);
+  }
+
+  // Options
+  if (commandDefinition.options) {
+    context.options ??= {};
+
+    for (const [name, optionDefinition] of Object.entries(commandDefinition.options)) {
+      // option already added to the context (found during argument parsing)
+      if (name in context.options) continue;
+
+      if (!optionDefinition._preparedType) {
+        throw new Error(`internal error: missing prepared type for option "${name}"`);
+      }
+
+      const { schema, optional, defaultValue } = optionDefinition._preparedType;
+
+      if (optional) {
+        // optional without default value
+        if (defaultValue === undefined) {
+          continue;
+        }
+
+        // optional with default value
+        context.options[name] = { schema, optional, defaultValue, source: "default" };
+        continue;
+      }
+
+      // required option
+      throw new Error(`missing required option: ${transformOptionToArgument(name)}`);
+    }
+  }
+
+  // Arguments
+  if (commandDefinition.arguments) {
+    context.arguments ??= {};
+
+    const currentArgumentCount = Object.keys(context.arguments).length;
+
+    const argumentDefinitionEntries = Object.entries(commandDefinition.arguments);
+    const argumentsDefinitionLength = argumentDefinitionEntries.length;
+
+    // missing arguments
+    if (currentArgumentCount < argumentsDefinitionLength) {
+      for (let index = currentArgumentCount; index < argumentsDefinitionLength; index++) {
+        const [name, argumentDefinition] = argumentDefinitionEntries[index];
+
+        if (!argumentDefinition._preparedType) {
+          throw new Error(`internal error: missing prepared type for the argument "${name}"`);
+        }
+
+        const { schema, optional, defaultValue } = argumentDefinition._preparedType;
+
+        if (optional) {
+          // optional argument without default value
+          if (defaultValue === undefined) {
+            continue;
+          }
+
+          // optional argument with default value
+          context.arguments[name] = { schema, optional, defaultValue, source: "default" };
+          continue;
+        }
+
+        // required argument
+        throw new Error(`The argument "${name}" is required`);
+      }
+    }
+  }
+
+  // make sure `positionals` is defined when `allowPositionals` is enabled
+  if (commandDefinition.allowPositionals) {
+    context.positionals ??= [];
+  }
+
+  return context;
+}

package/src/parse/context/object-context-builder.ts

@@ -0,0 +1,63 @@
+import type { ContextWide } from "../../types/context-types.ts";
+import type { Argument, Cli, Option, Subcommand } from "../../types/definitions-types.ts";
+import type { InputTypeWide } from "../../types/io-types.ts";
+
+/** @throws {Error} */
+export function buildObjectContext(inputValues: InputTypeWide, commandDefinition: Subcommand | Cli) {
+  const context: ContextWide = {
+    subcommand: "cliName" in commandDefinition ? undefined : commandDefinition.name,
+  };
+
+  if (commandDefinition.options) {
+    buildForOptionsOrArguments(commandDefinition.options, context, inputValues.options, "options");
+  }
+
+  if (commandDefinition.arguments) {
+    buildForOptionsOrArguments(commandDefinition.arguments, context, inputValues.arguments, "arguments");
+  }
+
+  if (commandDefinition.allowPositionals) {
+    context.positionals ??= inputValues.positionals;
+  }
+
+  return context;
+}
+
+function buildForOptionsOrArguments(
+  definitionRecord: Record<string, Option> | Record<string, Argument>,
+  context: ContextWide,
+  inputRecord: Record<string, unknown> | undefined,
+  type: "options" | "arguments",
+) {
+  const definitionEntries = Object.entries(definitionRecord) as [string, Option][] | [string, Argument][];
+
+  for (const [name, definition] of definitionEntries) {
+    if (!definition._preparedType) {
+      throw new Error(`internal error: missing prepared type for ${type.slice(0, -1)} "${name}"`);
+    }
+
+    const { schema, optional, defaultValue } = definition._preparedType;
+
+    // Case the value is passed
+    if (inputRecord && name in inputRecord) {
+      const passedValue = inputRecord[name];
+
+      context[type] ??= {};
+      context[type][name] =
+        passedValue === undefined
+          ? { schema, optional, defaultValue, source: "default" }
+          : { schema, optional, defaultValue, passedValue, source: "programmatic" };
+
+      continue;
+    }
+
+    // case the value is not passed
+    if (!optional) {
+      throw new Error(`the ${type.slice(0, -1)} "${name}" is required`);
+    }
+
+    // case the value is optional
+    context[type] ??= {};
+    context[type][name] = { schema, optional, defaultValue, source: "default" };
+  }
+}