zod-args-parser 1.2.7 → 2.0.0-alpha.0

package/src/markdown/generate-markdown.ts

@@ -3,8 +3,8 @@ import { getCliMetadata } from "../metadata/get-cli-metadata.js";
 import type { ArgumentMetadata, OptionMetadata, SubcommandMetadata } from "../metadata/metadata-types.js";
 import type { Cli, Subcommand } from "../types.js";
 
-export function generateMarkdown(...params: [Cli, ...Subcommand[]]): string {
-  const metadata = getCliMetadata(params);
+export function generateMarkdown(...parameters: [Cli, ...Subcommand[]]): string {
+  const metadata = getCliMetadata(parameters);
 
   let md = "<!-- Auto-generated by zod-args-parser -->\n\n";
 
@@ -22,19 +22,19 @@ export function generateMarkdown(...params: [Cli, ...Subcommand[]]): string {
   }
 
   // Options
-  if (metadata.options.length) {
+  if (metadata.options.length > 0) {
     md += "\n## Options:\n\n";
     md += renderOptions(metadata.options, 3);
   }
 
   // Arguments
-  if (metadata.arguments.length) {
+  if (metadata.arguments.length > 0) {
     md += "\n## Arguments:\n\n";
     md += renderArguments(metadata.arguments, 3);
   }
 
   // Subcommands
-  if (metadata.subcommands.length) {
+  if (metadata.subcommands.length > 0) {
     md += "\n## Subcommands:\n\n";
     md += renderSubcommands(metadata.subcommands);
   }
@@ -46,129 +46,129 @@ export function generateMarkdown(...params: [Cli, ...Subcommand[]]): string {
 }
 
 function renderExamples(examples: string, list = false) {
-  let outStr = "";
+  let outString = "";
 
   const lang = "bash";
 
   const listIndent = " ".repeat(list ? 2 : 0);
 
-  outStr += "\n" + (list ? "- " : "");
+  outString += "\n" + (list ? "- " : "");
 
-  outStr += "```" + lang + "\n";
-  outStr += listIndent + examples.replace(/\n/g, "\n" + listIndent);
-  outStr += "\n" + listIndent + "```\n";
+  outString += "```" + lang + "\n";
+  outString += listIndent + examples.replace(/\n/g, "\n" + listIndent);
+  outString += "\n" + listIndent + "```\n";
 
-  return outStr;
+  return outString;
 }
 
 function renderOptions(optionsMetadata: OptionMetadata[] = [], h: number) {
-  let outStr = "";
+  let outString = "";
 
-  for (let i = 0; i < optionsMetadata.length; i++) {
-    const metadata = optionsMetadata[i];
+  for (let index = 0; index < optionsMetadata.length; index++) {
+    const metadata = optionsMetadata[index];
 
     const aliases = [metadata.nameAsArg].concat(metadata.aliasesAsArgs).join(", ");
 
     const placeholder = metadata.placeholder && ` ${metadata.placeholder}`;
 
-    outStr += `${"#".repeat(h)} \`${aliases + placeholder}\``;
+    outString += `${"#".repeat(h)} \`${aliases + placeholder}\``;
 
     if (metadata.optional) {
-      outStr += " **[optional]**";
+      outString += " **[optional]**";
     }
 
-    outStr += "\n\n";
+    outString += "\n\n";
 
     if (metadata.description) {
-      outStr += `- ${metadata.description.replace(/(\n+)/g, "  $1  ")}\n`;
+      outString += `- ${metadata.description.replace(/(\n+)/g, "  $1  ")}\n`;
     }
 
-    if (typeof metadata.defaultValue !== "undefined") {
-      outStr += `- **default:** \`${metadata.defaultValueAsString}\`\n`;
+    if (metadata.defaultValue !== undefined) {
+      outString += `- **default:** \`${metadata.defaultValueAsString}\`\n`;
     }
 
     if (metadata.example) {
-      outStr += renderExamples(metadata.example, true);
+      outString += renderExamples(metadata.example, true);
     }
 
-    if (i < optionsMetadata.length - 1) {
-      outStr += "\n";
+    if (index < optionsMetadata.length - 1) {
+      outString += "\n";
     }
   }
 
-  return outStr;
+  return outString;
 }
 
-function renderArguments(argsMetadata: ArgumentMetadata[] = [], h: number) {
-  let outStr = "";
+function renderArguments(argumentsMetadata: ArgumentMetadata[] = [], h: number) {
+  let outString = "";
 
-  for (let i = 0; i < argsMetadata.length; i++) {
-    const metadata = argsMetadata[i];
+  for (let index = 0; index < argumentsMetadata.length; index++) {
+    const metadata = argumentsMetadata[index];
 
-    outStr += `${"#".repeat(h)} \`${metadata.name}\``;
+    outString += `${"#".repeat(h)} \`${metadata.name}\``;
 
     if (metadata.optional) {
-      outStr += " **[optional]**";
+      outString += " **[optional]**";
     }
 
-    outStr += "\n\n";
+    outString += "\n\n";
 
     if (metadata.description) {
-      outStr += `- ${metadata.description.replace(/(\n+)/g, "  $1  ")}\n`;
+      outString += `- ${metadata.description.replace(/(\n+)/g, "  $1  ")}\n`;
     }
 
-    if (typeof metadata.defaultValue !== "undefined") {
-      outStr += `- **default:** \`${metadata.defaultValueAsString}\`\n`;
+    if (metadata.defaultValue !== undefined) {
+      outString += `- **default:** \`${metadata.defaultValueAsString}\`\n`;
     }
 
     if (metadata.example) {
-      outStr += renderExamples(metadata.example);
+      outString += renderExamples(metadata.example);
     }
 
-    if (i < argsMetadata.length - 1) {
-      outStr += "\n";
+    if (index < argumentsMetadata.length - 1) {
+      outString += "\n";
     }
   }
 
-  return outStr;
+  return outString;
 }
 
 function renderSubcommands(subcommandsMetadata: SubcommandMetadata[]) {
-  let outStr = "";
+  let outString = "";
 
-  for (let i = 0; i < subcommandsMetadata.length; i++) {
-    const metadata = subcommandsMetadata[i];
+  for (let index = 0; index < subcommandsMetadata.length; index++) {
+    const metadata = subcommandsMetadata[index];
 
     const aliases = [metadata.name].concat(metadata.aliases).join(", ");
 
     const placeholder = metadata.placeholder && ` ${metadata.placeholder}`;
 
-    outStr += `### ${aliases + placeholder}\n\n`;
+    outString += `### ${aliases + placeholder}\n\n`;
 
     if (metadata.description) {
-      outStr += `${metadata.description}\n`;
+      outString += `${metadata.description}\n`;
     }
 
     if (metadata.example) {
-      outStr += renderExamples(metadata.example);
+      outString += renderExamples(metadata.example);
     }
 
-    if (metadata.options.length) {
-      outStr += "\n#### Options:\n\n";
-      outStr += renderOptions(metadata.options, 4);
+    if (metadata.options.length > 0) {
+      outString += "\n#### Options:\n\n";
+      outString += renderOptions(metadata.options, 4);
     }
 
-    if (metadata.arguments.length) {
-      outStr += "\n#### Arguments:\n\n";
-      outStr += renderArguments(metadata.arguments, 4);
+    if (metadata.arguments.length > 0) {
+      outString += "\n#### Arguments:\n\n";
+      outString += renderArguments(metadata.arguments, 4);
     }
 
-    if (i < subcommandsMetadata.length - 1) {
-      outStr += "\n---\n\n";
+    if (index < subcommandsMetadata.length - 1) {
+      outString += "\n---\n\n";
     }
   }
 
-  return outStr;
+  return outString;
 }
 
 function escapeHtmlTags(markdown: string) {
@@ -186,13 +186,13 @@ function escapeHtmlTags(markdown: string) {
 /** Credits: https://github.com/chalk/ansi-regex */
 function ansiRegex({ onlyFirst = false } = {}) {
   // Valid string terminator sequences are BEL, ESC\, and 0x9c
-  const ST = "(?:\\u0007|\\u001B\\u005C|\\u009C)";
+  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 = "[\\u001B\\u009B][[\\]()#;?]*(?:\\d{1,4}(?:[;:]\\d{0,4})*)?[\\dA-PR-TZcf-nq-uy=><~]";
+  const csi = String.raw`[\u001B\u009B][[\]()#;?]*(?:\d{1,4}(?:[;:]\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~]`;
 
   const pattern = `${osc}|${csi}`;
 

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

@@ -1,23 +1,23 @@
-import { stringifyValue } from "../utils.js";
-import { isOptionalSchema, schemaDefaultValue, schemaDescription } from "../zod-utils.js";
+import { stringifyValue } from "../utilities.js";
+import { isOptionalSchema, schemaDefaultValue, schemaDescription } from "../zod-utilities.js";
 
 import type { Argument } from "../types.js";
 import type { ArgumentMetadata } from "./metadata-types.js";
 
-export function getArgumentsMetadata(args: Argument[]): ArgumentMetadata[] {
+export function getArgumentsMetadata(arguments_: Argument[]): ArgumentMetadata[] {
   const outputMetadata: ArgumentMetadata[] = [];
 
-  for (const arg of args) {
-    const defaultValue = schemaDefaultValue(arg.type);
+  for (const argument of arguments_) {
+    const defaultValue = schemaDefaultValue(argument.type);
 
     outputMetadata.push({
-      name: arg.name,
-      description: arg.description ?? schemaDescription(arg.type) ?? "",
+      name: argument.name,
+      description: argument.description ?? schemaDescription(argument.type) ?? "",
       defaultValue,
       defaultValueAsString: stringifyValue(defaultValue),
-      optional: isOptionalSchema(arg.type),
-      example: arg.example ?? "",
-      type: arg.type,
+      optional: isOptionalSchema(argument.type),
+      example: argument.example ?? "",
+      type: argument.type,
     });
   }
 

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

@@ -1,6 +1,6 @@
-import { transformOptionToArg } from "../parser/parse/parser-helpers.js";
-import { stringifyValue } from "../utils.js";
-import { isOptionalSchema, schemaDefaultValue, schemaDescription } from "../zod-utils.js";
+import { transformOptionToArgument } from "../parser/parse/parser-helpers.js";
+import { stringifyValue } from "../utilities.js";
+import { isOptionalSchema, schemaDefaultValue, schemaDescription } from "../zod-utilities.js";
 
 import type { Option } from "../types.js";
 import type { OptionMetadata } from "./metadata-types.js";
@@ -8,7 +8,9 @@ import type { OptionMetadata } from "./metadata-types.js";
 export function getOptionsMetadata(options: Option[]): OptionMetadata[] {
   const outputMetadata: OptionMetadata[] = [];
 
-  if (!options || !options.length) return outputMetadata;
+  if (!options || options.length === 0) {
+    return outputMetadata;
+  }
 
   for (const option of options) {
     const defaultValue = schemaDefaultValue(option.type);
@@ -16,9 +18,9 @@ export function getOptionsMetadata(options: Option[]): OptionMetadata[] {
 
     outputMetadata.push({
       name: option.name,
-      nameAsArg: transformOptionToArg(option.name),
+      nameAsArg: transformOptionToArgument(option.name),
       aliases,
-      aliasesAsArgs: aliases.map(transformOptionToArg),
+      aliasesAsArgs: aliases.map(alias => transformOptionToArgument(alias)),
       placeholder: option.placeholder ?? "",
       description: option.description ?? schemaDescription(option.type) ?? "",
       optional: isOptionalSchema(option.type),

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

@@ -7,7 +7,9 @@ import type { SubcommandMetadata } from "./metadata-types.js";
 export function getSubcommandsMetadata(subcommands: Subcommand[]): SubcommandMetadata[] {
   const outputMetadata: SubcommandMetadata[] = [];
 
-  if (!subcommands || !subcommands.length) return outputMetadata;
+  if (!subcommands || subcommands.length === 0) {
+    return outputMetadata;
+  }
 
   for (const subcommand of subcommands) {
     const optionsMetadata = subcommand.options ? getOptionsMetadata(subcommand.options) : [];

package/src/parser/parse/parse-types.ts

@@ -64,11 +64,11 @@ type ParsedArgument<S extends Schema = Schema> =
       source: "default";
     };
 
-type OptionsArr2Record<T extends Option[] | undefined> = T extends Option[]
+type OptionsArray2Record<T extends Option[] | undefined> = T extends Option[]
   ? { [K in T[number]["name"]]: ParsedOption<Extract<T[number], { name: K }>["type"], K> }
   : Record<never, never>;
 
-type ArgumentsArr2ArrType<T extends Argument[] | undefined> = T extends Argument[]
+type ArgumentsArray2ArrayType<T extends Argument[] | undefined> = T extends Argument[]
   ? { [K in keyof T]: ParsedArgument<T[K] extends { type: Schema } ? T[K]["type"] : never> }
   : never;
 
@@ -76,14 +76,14 @@ export type ParseResult<S extends Partial<Subcommand>[]> = {
   [K in keyof S]: Prettify<{
     subcommand: S[K]["name"] extends string ? S[K]["name"] : undefined;
     positional: S[K]["allowPositional"] extends true ? string[] : never;
-    options: OptionsArr2Record<S[K]["options"]>;
-    arguments: ArgumentsArr2ArrType<S[K]["arguments"]>;
+    options: S[K]["options"] extends Option[] ? OptionsArray2Record<S[K]["options"]> : never;
+    arguments: ArgumentsArray2ArrayType<S[K]["arguments"]>;
   }>;
 }[number];
 
-export type ParseCtx = {
+export type ParsedContext = {
   subcommand: string | undefined;
-  options: Record<string, ParsedOption>;
+  options?: Record<string, ParsedOption>;
   arguments?: ParsedArgument[];
   positional?: string[];
 };

package/src/parser/parse/parse.ts

@@ -1,47 +1,36 @@
-import { generateOrdinalSuffix } from "../../utils.js";
-import { isBooleanSchema, isOptionalSchema, schemaDefaultValue } from "../../zod-utils.js";
+import { generateOrdinalSuffix } from "../../utilities.js";
+import { isBooleanSchema, isOptionalSchema, schemaDefaultValue } from "../../zod-utilities.js";
 import {
   decoupleFlags,
   findOption,
   findSubcommand,
-  isFlagArg,
-  isOptionArg,
-  transformOptionToArg,
+  isFlagArgument,
+  isOptionArgument,
+  transformOptionToArgument,
 } from "./parser-helpers.js";
 
 import type { Cli, Subcommand } from "../../types.js";
-import type { ParseCtx } from "./parse-types.js";
+import type { ParsedContext } from "./parse-types.js";
 
-export function parse(argv: string[], ...params: [Cli, ...Subcommand[]]) {
-  const subcommandArr = params as Subcommand[];
-  const allSubcommands = new Set<string>(subcommandArr.flatMap(c => [c.name, ...(c.aliases || [])]));
+export function parse(argv: string[], ...parameters: [Cli, ...Subcommand[]]) {
+  const subcommandArray = parameters as Subcommand[];
+  const allSubcommands = new Set<string>(subcommandArray.flatMap(c => [c.name, ...(c.aliases || [])]));
 
   argv = decoupleFlags(argv); // decouple flags E.g. `-rf` -> `-r, -f`
 
-  const results: ParseCtx = {
+  const results: ParsedContext = {
     subcommand: undefined,
-    options: {},
   };
 
   /** - Get current subcommand object */
-  const getSubcommandObj = () => findSubcommand(results.subcommand, subcommandArr);
+  const getSubcommandObject = () => findSubcommand(results.subcommand, subcommandArray);
 
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
+  for (let index = 0; index < argv.length; index++) {
+    const argument_ = argv[index];
 
     // * Subcommand check
-    if (i === 0) {
-      results.subcommand = allSubcommands.has(arg) ? arg : undefined;
-
-      // add positional and arguments arrays
-      const subcommandObj = getSubcommandObj();
-      if (subcommandObj && subcommandObj.allowPositional) {
-        results.positional = [];
-      }
-
-      if (subcommandObj && subcommandObj.arguments?.length) {
-        results.arguments = [];
-      }
+    if (index === 0) {
+      results.subcommand = allSubcommands.has(argument_) ? argument_ : undefined;
 
       // First argument is a subcommand. Skip to the next argument
       if (results.subcommand) continue;
@@ -50,22 +39,22 @@ export function parse(argv: string[], ...params: [Cli, ...Subcommand[]]) {
     // * Option check
 
     // Check for `--option=value` or `--option value`
-    const argAndValue = arg.split("=").filter(Boolean);
-    const argWithEquals = arg.includes("=");
-    const argument = argAndValue[0];
-    const argValue: string | undefined = argAndValue[1];
-
-    if (isOptionArg(argument)) {
-      if (isFlagArg(argument) && argWithEquals) {
-        throw new Error(`Flag arguments cannot be assigned using "=": "${arg}"`, { cause: "zod-args-parser" });
+    const argumentAndValue = argument_.split("=").filter(Boolean);
+    const argumentWithEquals = argument_.includes("=");
+    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 "=": "${argument_}"`, { cause: "zod-args-parser" });
       }
 
-      const subcommandObj = getSubcommandObj();
-      if (!subcommandObj) {
+      const subcommandObject = getSubcommandObject();
+      if (!subcommandObject) {
         throw new Error(`Unknown subcommand: "${results.subcommand}"`, { cause: "zod-args-parser" });
       }
 
-      if (!subcommandObj.options) {
+      if (!subcommandObject.options) {
         if (!results.subcommand) {
           throw new Error(`Error: options are not allowed here: "${argument}"`, { cause: "zod-args-parser" });
         }
@@ -75,35 +64,39 @@ export function parse(argv: string[], ...params: [Cli, ...Subcommand[]]) {
         });
       }
 
-      const option = findOption(argument, subcommandObj.options);
+      const option = findOption(argument, subcommandObject.options);
       if (!option) {
         throw new Error(`Unknown option: "${argument}"`, { cause: "zod-args-parser" });
       }
 
-      if (option.name in results.options) {
+      if (results.options && option.name in results.options) {
         throw new Error(`Duplicated option: "${argument}"`, { cause: "zod-args-parser" });
       }
 
       const isTypeBoolean = isBooleanSchema(option.type);
-      const nextArg = argv[i + 1];
+      const nextArgument = argv[index + 1];
 
-      let optionValue: string | boolean = argWithEquals ? argValue : nextArg;
+      let optionValue: string | boolean = argumentWithEquals ? argumentValue : nextArgument;
 
       // infer value for boolean options
-      if (isTypeBoolean && !argWithEquals) {
+      if (isTypeBoolean && !argumentWithEquals) {
         optionValue = "true";
       }
 
-      if (typeof optionValue === "undefined") {
+      if (optionValue === undefined) {
         throw new Error(`Expected a value for "${argument}" but got nothing`, { cause: "zod-args-parser" });
       }
 
-      if (!argWithEquals && isOptionArg(optionValue)) {
-        throw new Error(`Expected a value for "${argument}" but got an argument "${nextArg}"`, {
+      if (!argumentWithEquals && isOptionArgument(optionValue)) {
+        throw new Error(`Expected a value for "${argument}" but got an argument "${nextArgument}"`, {
           cause: "zod-args-parser",
         });
       }
 
+      if (!results.options) {
+        results.options = {};
+      }
+
       results.options[option.name] = {
         name: option.name,
         schema: option.type,
@@ -113,29 +106,29 @@ export function parse(argv: string[], ...params: [Cli, ...Subcommand[]]) {
       };
 
       // Skip to the next argument if it is the current option’s value.
-      if (!argWithEquals && !isTypeBoolean) {
-        i++;
+      if (!argumentWithEquals && !isTypeBoolean) {
+        index++;
       }
 
       continue;
     }
 
-    const subcommandObj = getSubcommandObj();
+    const subcommandObject = getSubcommandObject();
 
     // * Arguments check
-    if (subcommandObj?.arguments?.length) {
+    if (subcommandObject?.arguments) {
       if (!results.arguments) {
         results.arguments = [];
       }
 
-      const currentArgCount = results.arguments.length;
+      const currentArgumentCount = results.arguments.length;
 
       // Any extra arguments are possibly positional
-      if (currentArgCount < subcommandObj.arguments.length) {
-        const argType = subcommandObj.arguments[currentArgCount].type;
+      if (currentArgumentCount < subcommandObject.arguments.length) {
+        const argumentType = subcommandObject.arguments[currentArgumentCount].type;
         results.arguments.push({
-          schema: argType,
-          rawValue: arg,
+          schema: argumentType,
+          rawValue: argument_,
           source: "cli",
         });
         continue;
@@ -143,45 +136,49 @@ export function parse(argv: string[], ...params: [Cli, ...Subcommand[]]) {
     }
 
     // * Positional check
-    if (subcommandObj?.allowPositional) {
+    if (subcommandObject?.allowPositional) {
       if (!results.positional) {
         results.positional = [];
       }
 
-      results.positional.push(arg);
+      results.positional.push(argument_);
       continue;
     }
 
     // * Unexpected
     if (!results.subcommand) {
-      throw new Error(`Unexpected argument "${arg}": positional arguments are not allowed here`, {
+      throw new Error(`Unexpected argument "${argument_}": positional arguments are not allowed here`, {
         cause: "zod-args-parser",
       });
     }
 
     throw new Error(
-      `Unexpected argument "${arg}": positional arguments are not allowed for subcommand "${results.subcommand}"`,
+      `Unexpected argument "${argument_}": positional arguments are not allowed for subcommand "${results.subcommand}"`,
       { cause: "zod-args-parser" },
     );
   }
 
   // * Check for missing options - set defaults - add `source`
-  const subcommandObj = getSubcommandObj();
-  if (!subcommandObj) {
+  const subcommandObject = getSubcommandObject();
+  if (!subcommandObject) {
     throw new Error(`Unknown subcommand: "${results.subcommand}"`, { cause: "zod-args-parser" });
   }
 
   // Options
-  if (subcommandObj.options?.length) {
-    for (const option of subcommandObj.options) {
+  if (subcommandObject.options) {
+    if (!results.options) {
+      results.options = {};
+    }
+
+    for (const option of subcommandObject.options) {
       // option already exists
-      if (option.name in results.options) continue;
+      if (results.options && option.name in results.options) continue;
 
       const optional = isOptionalSchema(option.type);
       const defaultValue = schemaDefaultValue(option.type);
 
       if (optional) {
-        if (typeof defaultValue === "undefined") {
+        if (defaultValue === undefined) {
           continue;
         }
 
@@ -189,24 +186,30 @@ export function parse(argv: string[], ...params: [Cli, ...Subcommand[]]) {
         continue;
       }
 
-      throw new Error(`Missing required option: ${transformOptionToArg(option.name)}`, { cause: "zod-args-parser" });
+      throw new Error(`Missing required option: ${transformOptionToArgument(option.name)}`, {
+        cause: "zod-args-parser",
+      });
     }
   }
 
   // Arguments
-  if (subcommandObj.arguments?.length) {
-    const currentArgCount = results.arguments?.length ?? 0;
-    const subcommandArgCount = subcommandObj.arguments.length;
+  if (subcommandObject.arguments) {
+    if (!results.arguments) {
+      results.arguments = [];
+    }
+
+    const currentArgumentCount = results.arguments.length ?? 0;
+    const subcommandArgumentCount = subcommandObject.arguments.length;
 
     // missing arguments
-    if (currentArgCount < subcommandArgCount) {
-      for (let i = currentArgCount; i < subcommandArgCount; i++) {
-        const argumentType = subcommandObj.arguments[i].type;
+    if (currentArgumentCount < subcommandArgumentCount) {
+      for (let index = currentArgumentCount; index < subcommandArgumentCount; index++) {
+        const argumentType = subcommandObject.arguments[index].type;
         const optional = isOptionalSchema(argumentType);
         const defaultValue = schemaDefaultValue(argumentType);
 
         if (optional) {
-          if (typeof defaultValue === "undefined") {
+          if (defaultValue === undefined) {
             continue;
           }
 
@@ -216,12 +219,17 @@ export function parse(argv: string[], ...params: [Cli, ...Subcommand[]]) {
           continue;
         }
 
-        throw new Error(`the ${generateOrdinalSuffix(i)} argument is required: "${subcommandObj.arguments[i].name}"`, {
-          cause: "zod-args-parser",
-        });
+        throw new Error(
+          `the ${generateOrdinalSuffix(index)} argument is required: "${subcommandObject.arguments[index].name}"`,
+          { cause: "zod-args-parser" },
+        );
       }
     }
   }
 
+  if (subcommandObject.allowPositional && !results.positional) {
+    results.positional = [];
+  }
+
   return results;
 }