argsbarg 7.0.4 → 7.0.5

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [7.0.5] - 2026-09-15
+
+### Added
+
+- **Interleaved options between positionals** — options (presence flags and value options) can now be placed anywhere between bounded or optional positional arguments (e.g. `cmd file1 --force file2`), matching varargs tail behavior rather than requiring all options to precede or follow all bounded positionals.
+
 ## [7.0.4] - 2026-08-17
 
 ### Changed
@@ -959,7 +965,8 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v7.0.4...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v7.0.5...HEAD
+[7.0.5]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.5
 [7.0.4]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.4
 [7.0.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.3
 [7.0.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "7.0.4",
+  "version": "7.0.5",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "dependencies": {

package/src/core/parse.test.ts

@@ -370,6 +370,184 @@ test("trailing options after bounded positionals", () => {
   expect(pr.opts.verbose).toBe("1");
 });
 
+/** Tests that options can be interleaved between bounded positionals. */
+test("options interleaved between bounded positionals", () => {
+  const root = testProgram({
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "copy",
+        description: "copy",
+        options: [
+          {
+            name: "force",
+            description: "",
+            kind: CliOptionKind.Presence,
+            shortName: "f",
+          },
+          {
+            name: "mode",
+            description: "",
+            kind: CliOptionKind.String,
+          },
+        ],
+        positionals: [
+          {
+            name: "src",
+            description: "",
+            kind: CliOptionKind.String,
+          },
+          {
+            name: "dest",
+            description: "",
+            kind: CliOptionKind.String,
+          },
+        ],
+        handler: () => {},
+      },
+    ],
+  });
+  cliValidateProgram(root);
+
+  // Presence flag interleaved between positionals
+  const prPresence = postParseValidate(root, parse(root, ["copy", "file1", "--force", "file2"]));
+  expect(prPresence.kind).toBe(ParseKind.Ok);
+  expect(prPresence.args).toEqual(["file1", "file2"]);
+  expect(prPresence.opts.force).toBe("1");
+
+  // String option with value interleaved between positionals
+  const prString = postParseValidate(root, parse(root, ["copy", "file1", "--mode", "fast", "file2"]));
+  expect(prString.kind).toBe(ParseKind.Ok);
+  expect(prString.args).toEqual(["file1", "file2"]);
+  expect(prString.opts.mode).toBe("fast");
+
+  // Multiple flags interleaved between positionals
+  const prMulti = postParseValidate(root, parse(root, ["copy", "file1", "--mode", "fast", "-f", "file2"]));
+  expect(prMulti.kind).toBe(ParseKind.Ok);
+  expect(prMulti.args).toEqual(["file1", "file2"]);
+  expect(prMulti.opts.mode).toBe("fast");
+  expect(prMulti.opts.force).toBe("1");
+
+  // Unknown option interleaved between positionals returns error
+  const prUnknown = postParseValidate(root, parse(root, ["copy", "file1", "--unknown", "file2"]));
+  expect(prUnknown.kind).toBe(ParseKind.Error);
+  expect(prUnknown.errorMsg).toContain("Unknown option: --unknown");
+
+  // Interleaved help request triggers contextual help
+  const prHelp = parse(root, ["copy", "file1", "-h"]);
+  expect(prHelp.kind).toBe(ParseKind.Help);
+  expect(prHelp.helpPath).toEqual(["copy"]);
+
+  // Double dash between positionals disables option consumption
+  const prDoubleDash = postParseValidate(root, parse(root, ["copy", "file1", "--", "--force"]));
+  expect(prDoubleDash.kind).toBe(ParseKind.Ok);
+  expect(prDoubleDash.args).toEqual(["file1", "--force"]);
+  expect(prDoubleDash.opts.force).toBeUndefined();
+});
+
+/** Tests that options can be interleaved with optional positionals. */
+test("options interleaved with optional positionals", () => {
+  const root = testProgram({
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "deploy",
+        description: "deploy",
+        options: [
+          {
+            name: "force",
+            description: "",
+            kind: CliOptionKind.Presence,
+          },
+        ],
+        positionals: [
+          {
+            name: "env",
+            description: "",
+            kind: CliOptionKind.String,
+            argMin: 0,
+            argMax: 1,
+          },
+          {
+            name: "target",
+            description: "",
+            kind: CliOptionKind.String,
+            argMin: 0,
+            argMax: 1,
+          },
+        ],
+        handler: () => {},
+      },
+    ],
+  });
+  cliValidateProgram(root);
+
+  // Interleaved between two optional positionals
+  const prBoth = postParseValidate(root, parse(root, ["deploy", "prod", "--force", "us-east"]));
+  expect(prBoth.kind).toBe(ParseKind.Ok);
+  expect(prBoth.args).toEqual(["prod", "us-east"]);
+  expect(prBoth.opts.force).toBe("1");
+
+  // Option after first optional positional when second is omitted
+  const prOne = postParseValidate(root, parse(root, ["deploy", "prod", "--force"]));
+  expect(prOne.kind).toBe(ParseKind.Ok);
+  expect(prOne.args).toEqual(["prod"]);
+  expect(prOne.opts.force).toBe("1");
+
+  // Option before optional positionals when all are omitted
+  const prNone = postParseValidate(root, parse(root, ["deploy", "--force"]));
+  expect(prNone.kind).toBe(ParseKind.Ok);
+  expect(prNone.args).toEqual([]);
+  expect(prNone.opts.force).toBe("1");
+});
+
+/** Tests that options can be interleaved between bounded positional and varargs tail. */
+test("options interleaved between bounded positional and varargs tail", () => {
+  const root = testProgram({
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "upload",
+        description: "upload",
+        options: [
+          {
+            name: "json",
+            description: "",
+            kind: CliOptionKind.Presence,
+          },
+        ],
+        positionals: [
+          {
+            name: "target",
+            description: "",
+            kind: CliOptionKind.String,
+            argMin: 1,
+            argMax: 1,
+          },
+          {
+            name: "files",
+            description: "",
+            kind: CliOptionKind.String,
+            argMin: 1,
+            argMax: 0,
+          },
+        ],
+        handler: () => {},
+      },
+    ],
+  });
+  cliValidateProgram(root);
+
+  // Flag between target and files does not get captured as first file
+  const pr = postParseValidate(root, parse(root, ["upload", "s3", "--json", "a.txt", "b.txt"]));
+  expect(pr.kind).toBe(ParseKind.Ok);
+  expect(pr.args).toEqual(["s3", "a.txt", "b.txt"]);
+  expect(pr.opts.json).toBe("1");
+});
+
 /** Tests that options on routing groups are rejected at schema validation. */
 test("rejects options on routing groups", () => {
   const root = testProgram({

package/src/core/parse.ts

@@ -351,9 +351,47 @@ function finishLeaf(
   const args: string[] = [];
   let forcePositionals = forcePositionalsIn;
 
+  /**
+   * Consumes any pending options, `--`, or help flags at the current argv index.
+   * Sets `forcePositionals = true` when `--` is encountered.
+   * Returns a help or error ParseResult if parsing halts, or null to continue positional consumption.
+   */
+  function consumePendingOptions(): ParseResult | null {
+    while (!forcePositionals && idx < argv.length) {
+      const tok = argv[idx];
+      if (tok === "--") {
+        forcePositionals = true;
+        idx += 1;
+        break;
+      }
+      if (isHelpTok(tok)) {
+        return helpResult(path, true, pathParams);
+      }
+      if (tok.startsWith("-")) {
+        const rep = consumeOptions(optionDefs, false, argv, idx, opts);
+        if (rep.report.err) {
+          return errorResult(rep.report.err, path, [], pathParams);
+        }
+        if (rep.report.sawDoubleDash) {
+          forcePositionals = true;
+        }
+        if (rep.nextIndex > idx) {
+          idx = rep.nextIndex;
+          continue;
+        }
+        return errorResult(`Unexpected option token: ${tok}`, path, [], pathParams);
+      }
+      break;
+    }
+    return null;
+  }
+
   for (const p of node.positionals ?? []) {
     const { argMin = 1, argMax = 1 } = p;
     if (argMax === 1) {
+      const pendingErr = consumePendingOptions();
+      if (pendingErr) return pendingErr;
+
       if (argMin >= 1) {
         if (idx >= argv.length) {
           return errorResult(`Missing positional argument: ${p.name}`, path, [], pathParams);
@@ -361,13 +399,8 @@ function finishLeaf(
         args.push(argv[idx]);
         idx += 1;
       } else if (idx < argv.length) {
-        const tok = argv[idx];
-        if (argMin < 1 && tok.startsWith("-")) {
-          // Optional slot: leave `-` tokens for trailing option parsing.
-        } else {
-          args.push(tok);
-          idx += 1;
-        }
+        args.push(argv[idx]);
+        idx += 1;
       }
       continue;
     }
@@ -375,40 +408,20 @@ function finishLeaf(
     let count = 0;
     if (argMax === 0) {
       while (idx < argv.length) {
-        const tok = argv[idx];
-
-        if (!forcePositionals && tok === "--") {
-          forcePositionals = true;
-          idx++;
-          continue;
-        }
+        const pendingErr = consumePendingOptions();
+        if (pendingErr) return pendingErr;
+        if (idx >= argv.length) break;
 
-        if (!forcePositionals && isHelpTok(tok)) {
-          return helpResult(path, true, pathParams);
-        }
-
-        if (!forcePositionals && tok.startsWith("-")) {
-          // MUST be false — lenient mode swallows unknown flags as positionals silently
-          const tailRep = consumeOptions(optionDefs, false, argv, idx, opts);
-          if (tailRep.report.err) {
-            return errorResult(tailRep.report.err, path, [], pathParams);
-          }
-          if (tailRep.report.sawDoubleDash) {
-            forcePositionals = true;
-          }
-          if (tailRep.nextIndex > idx) {
-            idx = tailRep.nextIndex;
-            continue;
-          }
-          return errorResult(`Unexpected option token: ${tok}`, path, [], pathParams);
-        }
-
-        args.push(tok);
-        idx++;
-        count++;
+        args.push(argv[idx]);
+        idx += 1;
+        count += 1;
       }
     } else {
       while (count < argMax && idx < argv.length) {
+        const pendingErr = consumePendingOptions();
+        if (pendingErr) return pendingErr;
+        if (idx >= argv.length) break;
+
         args.push(argv[idx]);
         idx += 1;
         count += 1;
@@ -419,24 +432,11 @@ function finishLeaf(
     }
   }
 
-  if (idx < argv.length) {
-    if (forcePositionals) {
-      return errorResult("Unexpected extra arguments", path, [], pathParams);
-    }
-
-    if (isHelpTok(argv[idx])) {
-      return helpResult(path, true, pathParams);
-    }
+  const trailingErr = consumePendingOptions();
+  if (trailingErr) return trailingErr;
 
-    const tailRep = consumeOptions(optionDefs, false, argv, idx, opts);
-    if (tailRep.report.err) {
-      return errorResult(tailRep.report.err, path, [], pathParams);
-    }
-    idx = tailRep.nextIndex;
-
-    if (idx < argv.length) {
-      return errorResult("Unexpected extra arguments", path, [], pathParams);
-    }
+  if (idx < argv.length) {
+    return errorResult("Unexpected extra arguments", path, [], pathParams);
   }
 
   return {