argsbarg 0.1.0 → 1.0.1

package/src/index.test.ts

@@ -7,31 +7,33 @@ It keeps the CLI contract stable by catching routing, option handling, and gener
 shell output regressions.
 */
 
-import {
-  CliCommand,
-  createOption,
-  CliOptionKind,
-  CliFallbackMode,
-  cliValidateRoot,
-  parse,
-  postParseValidate,
-  completionBashScript,
-  completionZshScript,
-  ParseKind,
-} from "./index.ts";
+import { completionBashScript, completionZshScript } from "./completion.ts";
+import { CliCommand, CliFallbackMode, CliOptionKind } from "./index.ts";
+import { ParseKind, parse, postParseValidate } from "./parse.ts";
+import { cliValidateRoot } from "./validate.ts";
 import { expect, test } from "bun:test";
 
 test("bundled short presence flags", () => {
   const root: CliCommand = {
     key: "app",
     description: "",
-    children: [
+    commands: [
       {
         key: "x",
         description: "cmd",
         options: [
-          createOption("a", "", { kind: CliOptionKind.Presence, shortName: "a" }),
-          createOption("b", "", { kind: CliOptionKind.Presence, shortName: "b" }),
+          {
+            name: "a",
+            description: "",
+            kind: CliOptionKind.Presence,
+            shortName: "a",
+          },
+          {
+            name: "b",
+            description: "",
+            kind: CliOptionKind.Presence,
+            shortName: "b",
+          },
         ],
         handler: () => {},
       },
@@ -48,11 +50,17 @@ test("long option equals", () => {
   const root: CliCommand = {
     key: "app",
     description: "",
-    children: [
+    commands: [
       {
         key: "x",
         description: "cmd",
-        options: [createOption("name", "", { kind: CliOptionKind.String })],
+        options: [
+          {
+            name: "name",
+            description: "",
+            kind: CliOptionKind.String,
+          },
+        ],
         handler: () => {},
       },
     ],
@@ -67,11 +75,17 @@ test("fallback missing or unknown root flags", () => {
   const root: CliCommand = {
     key: "app",
     description: "",
-    children: [
+    commands: [
       {
         key: "hello",
         description: "Say hi.",
-        options: [createOption("name", "", { kind: CliOptionKind.String })],
+        options: [
+          {
+            name: "name",
+            description: "",
+            kind: CliOptionKind.String,
+          },
+        ],
         handler: () => {},
       },
     ],
@@ -89,7 +103,7 @@ test("unknown command", () => {
   const root: CliCommand = {
     key: "app",
     description: "",
-    children: [{ key: "hello", description: "", handler: () => {} }],
+    commands: [{ key: "hello", description: "", handler: () => {} }],
   };
   cliValidateRoot(root);
   const pr = parse(root, ["nope"]);
@@ -101,7 +115,7 @@ test("implicit help empty", () => {
   const root: CliCommand = {
     key: "app",
     description: "",
-    children: [{ key: "x", description: "", handler: () => {} }],
+    commands: [{ key: "x", description: "", handler: () => {} }],
   };
   cliValidateRoot(root);
   const pr = parse(root, []);
@@ -113,11 +127,17 @@ test("invalid number post validate", () => {
   const root: CliCommand = {
     key: "app",
     description: "",
-    children: [
+    commands: [
       {
         key: "x",
         description: "",
-        options: [createOption("n", "", { kind: CliOptionKind.Number })],
+        options: [
+          {
+            name: "n",
+            description: "",
+            kind: CliOptionKind.Number,
+          },
+        ],
         handler: () => {},
       },
     ],
@@ -133,11 +153,17 @@ test("supports scientific notation in numbers", () => {
   const root: CliCommand = {
     key: "app",
     description: "",
-    children: [
+    commands: [
       {
         key: "x",
         description: "",
-        options: [createOption("n", "", { kind: CliOptionKind.Number })],
+        options: [
+          {
+            name: "n",
+            description: "",
+            kind: CliOptionKind.Number,
+          },
+        ],
         handler: () => {},
       },
     ],
@@ -153,7 +179,7 @@ test("root must not have handler", () => {
   const root: CliCommand = {
     key: "app",
     description: "",
-    children: [{ key: "x", description: "", handler: () => {} }],
+    commands: [{ key: "x", description: "", handler: () => {} }],
     handler: () => {},
   };
   expect(() => cliValidateRoot(root)).toThrow(/Program root must not set handler/);
@@ -164,9 +190,15 @@ test("root must not have positionals", () => {
     key: "app",
     description: "",
     positionals: [
-      createOption("p", "", { kind: CliOptionKind.String, positional: true }),
+      {
+        name: "p",
+        description: "",
+        kind: CliOptionKind.String,
+        argMin: 1,
+        argMax: 1,
+      },
     ],
-    children: [{ key: "x", description: "", handler: () => {} }],
+    commands: [{ key: "x", description: "", handler: () => {} }],
   };
   expect(() => cliValidateRoot(root)).toThrow(/Program root must not declare positionals/);
 });
@@ -175,7 +207,7 @@ test("completion scripts contain app name", () => {
   const root: CliCommand = {
     key: "myapp",
     description: "Test",
-    children: [{ key: "hello", description: "Say hello.", handler: () => {} }],
+    commands: [{ key: "hello", description: "Say hello.", handler: () => {} }],
   };
   cliValidateRoot(root);
   const bash = completionBashScript(root);
@@ -192,7 +224,7 @@ test("completion scripts do not emit invalid bash substitutions", () => {
   const root: CliCommand = {
     key: "app",
     description: "Test",
-    children: [{ key: "hello", description: "Say hello.", handler: () => {} }],
+    commands: [{ key: "hello", description: "Say hello.", handler: () => {} }],
   };
   cliValidateRoot(root);
   const bash = completionBashScript(root);
@@ -203,7 +235,7 @@ test("completion scripts escape shell-sensitive command text in zsh", () => {
   const root: CliCommand = {
     key: "app",
     description: "Test",
-    children: [
+    commands: [
       {
         key: "quote'cmd",
         description: "Say 'hello' and keep going.",
@@ -220,7 +252,7 @@ test("completion scripts keep dotted app names in registration names", () => {
   const root: CliCommand = {
     key: "minimal.ts",
     description: "Test",
-    children: [{ key: "hello", description: "Say hello.", handler: () => {} }],
+    commands: [{ key: "hello", description: "Say hello.", handler: () => {} }],
   };
   cliValidateRoot(root);
 
@@ -235,13 +267,25 @@ test("stops parsing options at --", () => {
   const root: CliCommand = {
     key: "app",
     description: "",
-    children: [
+    commands: [
       {
         key: "x",
         description: "cmd",
-        options: [createOption("name", "", { kind: CliOptionKind.String })],
+        options: [
+          {
+            name: "name",
+            description: "",
+            kind: CliOptionKind.String,
+          },
+        ],
         positionals: [
-          createOption("files", "", { kind: CliOptionKind.String, positional: true, argMax: 0, argMin: 0 })
+          {
+            name: "files",
+            description: "",
+            kind: CliOptionKind.String,
+            argMin: 0,
+            argMax: 0,
+          },
         ],
         handler: () => {},
       },

package/src/index.ts

@@ -7,18 +7,7 @@ It gives consumers one stable import path without forcing them to know the inter
 module layout.
 */
 
-export { cliBuiltinCompletionGroup, completionBashScript, completionZshScript } from "./completion.ts";
-export { cliRun, cliErrWithHelp } from "./runtime";
 export { CliContext } from "./context.ts";
-export { cliOptionLabel, cliHelpRender } from "./help.ts";
-export { ParseKind, parse, postParseValidate } from "./parse.ts";
-export type { ParseResult } from "./parse.ts";
-export {
-  CliOptionKind,
-  CliFallbackMode,
-  CliSchemaValidationError,
-  createOption,
-} from "./types.ts";
-export type { CliOptionDef, CliCommand, CliHandler } from "./types.ts";
-export { fullStringIsDouble, strictParseDouble } from "./utils.ts";
-export { cliValidateRoot } from "./validate.ts";
+export { cliErrWithHelp, cliRun } from "./runtime";
+export { CliFallbackMode, CliOptionKind, CliSchemaValidationError } from "./types.ts";
+export type { CliCommand, CliHandler, CliOption, CliPositional } from "./types.ts";

package/src/parse.ts

@@ -10,30 +10,43 @@ across every entry path.
 import { CliContext } from "./context.ts";
 import {
   CliCommand,
-  CliOptionDef,
-  CliOptionKind,
   CliFallbackMode,
+  CliOption,
+  CliOptionKind,
 } from "./types.ts";
 import { fullStringIsDouble } from "./utils.ts";
 
 // ── Parse Result ──────────────────────────────────────────────────────────────
 
-/** Outcome of a parse: success, help request, or fatal user error. */
+/**
+ * Outcome of a parse: success, help request, or fatal user error.
+ */
 export enum ParseKind {
+  /** Parsed successfully; options and positionals are valid. */
   Ok = "ok",
+  /** User requested help (explicit or implicit). */
   Help = "help",
+  /** User error (unknown command, bad option, etc.). */
   Error = "error",
 }
 
 /** Structured parse output: routed path, merged options, positional args, and help/error metadata. */
 export interface ParseResult {
+  /** Parse outcome (ok, help, or error). */
   kind: ParseKind;
+  /** Routed subcommand keys from the program root (e.g. `["hello"]`). */
   path: string[];
+  /** Merged long/short option values as string values (presence → `"1"`). */
   opts: Record<string, string>;
+  /** Positional arguments for the leaf command, in order. */
   args: string[];
+  /** True when the user passed `-h` / `--help` explicitly. */
   helpExplicit: boolean;
+  /** Path segments for scoped help (empty for root help). */
   helpPath: string[];
+  /** User-facing error message when `kind === Error`. */
   errorMsg: string;
+  /** Help path to render next to an error (for contextual help). */
   errorHelpPath: string[];
 }
 
@@ -42,32 +55,41 @@ export interface ParseResult {
 const helpShort = "-h";
 const helpLong = "--help";
 
+/** Returns true if the argv token is `-h` or `--help`. */
 function isHelpTok(tok: string): boolean {
   return tok === helpShort || tok === helpLong;
 }
 
+/** Looks up a subcommand or routing node by `key`. */
 function findChild(cmds: CliCommand[], name: string): CliCommand | undefined {
   return cmds.find((c) => c.key === name);
 }
 
-function findOptionByName(defs: CliOptionDef[], name: string): CliOptionDef | undefined {
+/** Resolves a long-option definition by name (without leading `--`). */
+function findOptionByName(defs: CliOption[], name: string): CliOption | undefined {
   return defs.find((o) => o.name === name);
 }
 
-function findOptionDefByShort(defs: CliOptionDef[], short: string): CliOptionDef | undefined {
-  return defs.find((o) => !o.positional && o.shortName === short);
+/** Resolves a short-option definition by its single character. */
+function findOptionDefByShort(defs: CliOption[], short: string): CliOption | undefined {
+  return defs.find((o) => o.shortName === short);
 }
 
 // ── Option Consumption ────────────────────────────────────────────────────────
 
+/** State from scanning argv for flags: error text, lenient early exit, or `--` seen. */
 interface ConsumeReport {
+  /** User-facing error when option parsing failed; null on success. */
   err: string | null;
+  /** True when lenient mode stopped on an unknown option token. */
   stoppedOnUnknown: boolean;
+  /** True when `--` was read (remaining argv is positional-only). */
   sawDoubleDash: boolean;
 }
 
+/** Consumes argv from index `i` for long/short options, updating `opts` until a non-option or `--`. */
 function consumeOptions(
-  defs: CliOptionDef[],
+  defs: CliOption[],
   lenientUnknown: boolean,
   argv: string[],
   i: number,
@@ -75,6 +97,7 @@ function consumeOptions(
 ): { report: ConsumeReport; nextIndex: number } {
   let idx = i;
 
+  /** Parses a single `--name` or `--name=value` token. Returns an error string, `""` if unknown and lenient, or `null` on success. */
   function consumeLong(tok: string): string | null {
     const body = tok.slice(2);
     let optName: string;
@@ -118,6 +141,7 @@ function consumeOptions(
     return null;
   }
 
+  /** Parses a bundled or single `-x` / `-nval` short token. */
   function consumeShort(tok: string): string | null {
     if (tok.length < 2) return `Unexpected option token: ${tok}`;
     const shorts = tok.slice(1);
@@ -183,6 +207,7 @@ function consumeOptions(
 
 // ── Positional Collection ─────────────────────────────────────────────────────
 
+/** Fills `args` for a leaf from `startIdx` according to `node.positionals`. */
 function finishLeaf(
   node: CliCommand,
   startIdx: number,
@@ -190,6 +215,7 @@ function finishLeaf(
   path: string[],
   opts: Record<string, string>,
 ): ParseResult {
+  /** Builds a parse error for positional consumption failures. */
   function errorResult(msg: string): ParseResult {
     const pr: ParseResult = {
       kind: ParseKind.Error,
@@ -208,10 +234,9 @@ function finishLeaf(
   const args: string[] = [];
 
   for (const p of node.positionals ?? []) {
-    if (!p.positional) continue;
-
-    if (p.argMax === 1) {
-      if (p.argMin >= 1) {
+    const { argMin = 1, argMax = 1 } = p;
+    if (argMax === 1) {
+      if (argMin >= 1) {
         if (idx >= argv.length) {
           return errorResult(`Missing positional argument: ${p.name}`);
         }
@@ -225,21 +250,21 @@ function finishLeaf(
     }
 
     let count = 0;
-    if (p.argMax === 0) {
+    if (argMax === 0) {
       while (idx < argv.length) {
         args.push(argv[idx]);
         idx += 1;
         count += 1;
       }
     } else {
-      while (count < p.argMax && idx < argv.length) {
+      while (count < argMax && idx < argv.length) {
         args.push(argv[idx]);
         idx += 1;
         count += 1;
       }
     }
-    if (count < p.argMin) {
-      return errorResult(`Expected at least ${p.argMin} argument(s) for ${p.name}, got ${count}`);
+    if (count < argMin) {
+      return errorResult(`Expected at least ${argMin} argument(s) for ${p.name}, got ${count}`);
     }
   }
 
@@ -252,6 +277,7 @@ function finishLeaf(
 
 // ── Main Parser ───────────────────────────────────────────────────────────────
 
+/** Builds a help-request result for the current routing path. */
 function helpResult(p: string[], explicit: boolean): ParseResult {
   return {
     kind: ParseKind.Help,
@@ -265,6 +291,9 @@ function helpResult(p: string[], explicit: boolean): ParseResult {
   };
 }
 
+/**
+ * Parses `argv` against the program root, routing into subcommands and filling `opts` / `args`.
+ */
 export function parse(root: CliCommand, argv: string[]): ParseResult {
   let i = 0;
   const path: string[] = [];
@@ -302,7 +331,7 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
   if (i >= argv.length) {
     if (root.fallbackCommand !== undefined && ((root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOnly || (root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOrUnknown)) {
       cmdName = root.fallbackCommand;
-      node = findChild(root.children ?? [], cmdName);
+      node = findChild(root.commands ?? [], cmdName);
       if (!node) {
         return { kind: ParseKind.Error, path: [], opts: {}, args: [], helpExplicit: false, helpPath: [], errorMsg: `Unknown command: ${cmdName}`, errorHelpPath: path };
       }
@@ -311,7 +340,7 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
     }
   } else {
     const peek = argv[i];
-    const childPick = !forcePositionals ? findChild(root.children ?? [], peek) : undefined;
+    const childPick = !forcePositionals ? findChild(root.commands ?? [], peek) : undefined;
 
     if (childPick !== undefined) {
       cmdName = peek;
@@ -325,14 +354,14 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
 
       if (canRouteUnknown) {
         cmdName = root.fallbackCommand!;
-        node = findChild(root.children ?? [], cmdName);
+        node = findChild(root.commands ?? [], cmdName);
         if (!node) {
           return { kind: ParseKind.Error, path: [], opts: {}, args: [], helpExplicit: false, helpPath: [], errorMsg: `Unknown command: ${cmdName}`, errorHelpPath: path };
         }
       } else {
         cmdName = peek;
         if (!forcePositionals) i += 1;
-        node = findChild(root.children ?? [], cmdName);
+        node = findChild(root.commands ?? [], cmdName);
         if (!node) {
           return {
             kind: ParseKind.Error,
@@ -379,7 +408,7 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
     }
 
     if (i >= argv.length) {
-      if ((current.children ?? []).length > 0) {
+      if ((current.commands ?? []).length > 0) {
         return helpResult(path, false);
       }
       return finishLeaf(current, i, argv, path, opts);
@@ -400,7 +429,7 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
     }
 
     if (!forcePositionals) {
-      const childOpt = findChild(current.children ?? [], tok);
+      const childOpt = findChild(current.commands ?? [], tok);
       if (childOpt !== undefined) {
         i += 1;
         path.push(tok);
@@ -409,7 +438,7 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
       }
     }
 
-    if ((current.children ?? []).length > 0) {
+    if ((current.commands ?? []).length > 0) {
       return {
         kind: ParseKind.Error,
         path,
@@ -428,11 +457,14 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
 
 // ── Post-Parse Validation ─────────────────────────────────────────────────────
 
+/**
+ * Validates option keys and numeric values for an Ok parse, merging in-scope options along `pr.path`.
+ */
 export function postParseValidate(root: CliCommand, pr: ParseResult): ParseResult {
   if (pr.kind !== ParseKind.Ok) return pr;
 
   let defs = [...(root.options ?? [])];
-  let cmds = root.children ?? [];
+  let cmds = root.commands ?? [];
 
   for (const seg of pr.path) {
     const ch = findChild(cmds, seg);
@@ -449,8 +481,7 @@ export function postParseValidate(root: CliCommand, pr: ParseResult): ParseResul
       };
     }
     defs.push(...(ch.options ?? []));
-    defs.push(...(ch.positionals ?? []));
-    cmds = ch.children ?? [];
+    cmds = ch.commands ?? [];
   }
 
   for (const [k, v] of Object.entries(pr.opts)) {

package/src/runtime.ts

@@ -19,7 +19,7 @@ import { cliValidateRoot } from "./validate.ts";
  */
 function cliRootMergedWithBuiltins(root: CliCommand): CliCommand {
   const merged = { ...root };
-  merged.children = [...(root.children ?? []), cliBuiltinCompletionGroup(root.key)];
+  merged.commands = [...(root.commands ?? []), cliBuiltinCompletionGroup(root.key)];
   return merged;
 }
 
@@ -76,7 +76,7 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
 
   let current = merged;
   for (const seg of pr.path) {
-    const ch = (current.children ?? []).find((candidate: CliCommand) => candidate.key === seg);
+    const ch = (current.commands ?? []).find((candidate: CliCommand) => candidate.key === seg);
     if (!ch) {
       process.stderr.write("Internal error: missing handler for path.\n");
       process.exit(1);

package/src/types.ts

@@ -1,5 +1,5 @@
 /*
-This module defines the CLI schema, option kinds, fallback modes, and helpers.
+This module defines the CLI schema, option kinds, and fallback modes.
 It is the shared declarative model that parsing, validation, help, and completion all
 read from, so the package has one source of truth.
 
@@ -12,8 +12,11 @@ import type { CliContext } from "./context.ts";
  * Option kinds: presence (boolean flag), string (free-form text), or number (strict double).
  */
 export enum CliOptionKind {
+  /** Boolean flag: no value token (may be implicit `"1"` when set). */
   Presence = "presence",
+  /** Free-form string value. */
   String = "string",
+  /** Strict floating-point value (parsed at validation time). */
   Number = "number",
 }
 
@@ -22,18 +25,25 @@ export enum CliOptionKind {
  * Only the program root may set a non-default mode or a non-nil fallbackCommand.
  */
 export enum CliFallbackMode {
-  /** Use the fallback only when argv has no first subcommand token. */
+  /**
+   * If argv has no first subcommand, route to `fallbackCommand`; if the first token is unknown, error.
+   */
   MissingOnly = "missingOnly",
-  /** Use the fallback when the first token is missing or not a known child name. */
+  /**
+   * If argv has no first subcommand or the first token is not a known child, route to `fallbackCommand`.
+   */
   MissingOrUnknown = "missingOrUnknown",
-  /** Use the fallback only when the first token is not a known child name. */
+  /**
+   * If the first token is present but not a known child, route to `fallbackCommand`.
+   * When the first subcommand token is missing (empty argv), do not use fallback (implicit root help).
+   */
   UnknownOnly = "unknownOnly",
 }
 
 /**
- * One CLI flag, option, or positional definition.
+ * A named flag or value option (`--long`, `-short`), listed on `CliCommand.options`.
  */
-export interface CliOptionDef {
+export interface CliOption {
   /** Option name (e.g., "name", "verbose"). */
   name: string;
   /** Description shown in help. */
@@ -42,19 +52,35 @@ export interface CliOptionDef {
   kind: CliOptionKind;
   /** Short option character (e.g., 'n' for -n). */
   shortName?: string;
-  /** Whether this is a positional argument (true) or a flag/option (false). */
-  positional: boolean;
-  /** Minimum number of values required (for positionals). */
-  argMin: number;
-  /** Maximum number of values allowed (0 = unlimited, for positionals). */
-  argMax: number;
 }
 
 /**
- * A command node: routing group (has children) or leaf (has handler).
+ * An ordered positional argument slot, listed on `CliCommand.positionals`.
+ */
+export interface CliPositional {
+  /** Positional name (used in help and error messages). */
+  name: string;
+  /** Description shown in help. */
+  description: string;
+  /** Value kind for each consumed token. */
+  kind: CliOptionKind;
+  /**
+   * Minimum number of values required (default 1).
+   * Use `0` for an optional slot when paired with `argMax: 1`, or a varargs tail with `argMax: 0`.
+   */
+  argMin?: number;
+  /**
+   * Maximum number of values (`1` = a single required or optional word; default 1). Use `0` for an
+   * unbounded varargs tail (must be the last slot in the command’s `positionals` list).
+   */
+  argMax?: number;
+}
+
+/**
+ * A command node: routing group (has commands) or leaf (has handler).
  *
  * The value passed to cliRun is the program root: name is the app/binary name,
- * children are top-level subcommands, options are global flags.
+ * commands are top-level subcommands, options are global flags.
  * The root must not set handler or declare positionals (validated at startup).
  */
 export interface CliCommand {
@@ -65,11 +91,11 @@ export interface CliCommand {
   /** Additional notes shown in help (supports {app} placeholder). */
   notes?: string;
   /** Global or command-level flags/options. */
-  options?: CliOptionDef[];
+  options?: CliOption[];
   /** Positional argument definitions. */
-  positionals?: CliOptionDef[];
-  /** Child subcommands (empty for leaf commands). */
-  children?: CliCommand[];
+  positionals?: CliPositional[];
+  /** Nested subcommands (empty for leaf commands). */
+  commands?: CliCommand[];
   /** Handler function for leaf commands. */
   handler?: CliHandler;
   /** Default top-level subcommand when argv omits a command or uses an unknown first token (root only). */
@@ -88,27 +114,9 @@ export type CliHandler = (ctx: CliContext) => void | Promise<void>;
  * Error thrown when the static CliCommand tree violates ArgsBarg rules.
  */
 export class CliSchemaValidationError extends Error {
+  /** Creates a schema validation error with a human-readable rule violation. */
   constructor(message: string) {
     super(message);
     this.name = "CliSchemaValidationError";
   }
 }
-
-/**
- * Creates a new CliOptionDef with sensible defaults.
- */
-export function createOption(
-  name: string,
-  description: string,
-  options?: Partial<CliOptionDef>,
-): CliOptionDef {
-  return {
-    name,
-    description,
-    kind: options?.kind ?? CliOptionKind.Presence,
-    shortName: options?.shortName,
-    positional: options?.positional ?? false,
-    argMin: options?.argMin ?? 1,
-    argMax: options?.argMax ?? 1,
-  };
-}