Release 0.9.10

Author: dahlia

CHANGES.md

@@ -4,7 +4,22 @@ Optique changelog
 Version 0.9.10
 --------------
 
-To be released.
+Released on February 19, 2026.
+
+### @optique/core
+
+ -  Fixed meta commands (`help`, `version`, `completion`, `completions`)
+    disappearing from the subcommand list in help output when the parser uses
+    a `withDefault(or(...))` construct.  The root cause was that
+    `getDocPage()` used a `do...while` loop, which ran the parser at least
+    once even with an empty argument buffer.  Because `withDefault(or(...))`
+    allows the inner parser to succeed without consuming any tokens, the
+    `longestMatch` combinator would record the user's parser as "selected"
+    and subsequently return only that parser's doc fragments—silently
+    dropping the meta command entries.  The loop is now a `while` loop that
+    skips parsing entirely when the buffer is empty.  [[#121]]
+
+[#121]: https://github.com/dahlia/optique/issues/121
 
 
 Version 0.9.9
@@ -539,6 +554,26 @@ remotes) using [isomorphic-git].  [[#71], [#72]]
 [#72]: https://github.com/dahlia/optique/pull/72
 
 
+Version 0.8.16
+--------------
+
+Released on February 19, 2026.
+
+### @optique/core
+
+ -  Fixed meta commands (`help`, `version`, `completion`, `completions`)
+    disappearing from the subcommand list in help output when the parser uses
+    a `withDefault(or(...))` construct.  The root cause was that
+    `getDocPage()` used a `do...while` loop, which ran the parser at least
+    once even with an empty argument buffer.  Because `withDefault(or(...))`
+    allows the inner parser to succeed without consuming any tokens, the
+    `longestMatch` combinator would record the user's parser as "selected"
+    and subsequently return only that parser's doc fragments—silently
+    dropping the meta command entries.  The loop is now a `while` loop that
+    skips parsing entirely when the buffer is empty.  [[#121]]
+
+[#121]: https://github.com/dahlia/optique/issues/121
+
 
 Version 0.8.15
 --------------
@@ -968,6 +1003,26 @@ parsing strategies.
 [LogTape]: https://logtape.org/
 
 
+Version 0.7.18
+--------------
+
+Released on February 19, 2026.
+
+### @optique/core
+
+ -  Fixed meta commands (`help`, `version`, `completion`, `completions`)
+    disappearing from the subcommand list in help output when the parser uses
+    a `withDefault(or(...))` construct.  The root cause was that
+    `getDocPage()` used a `do...while` loop, which ran the parser at least
+    once even with an empty argument buffer.  Because `withDefault(or(...))`
+    allows the inner parser to succeed without consuming any tokens, the
+    `longestMatch` combinator would record the user's parser as "selected"
+    and subsequently return only that parser's doc fragments—silently
+    dropping the meta command entries.  The loop is now a `while` loop that
+    skips parsing entirely when the buffer is empty.  [[#121]]
+
+[#121]: https://github.com/dahlia/optique/issues/121
+
 
 Version 0.7.17
 --------------

packages/core/src/parser.test.ts

@@ -13,7 +13,13 @@ import {
 } from "@optique/core/message";
 import { multiple, optional, withDefault } from "@optique/core/modifiers";
 import { getDocPage, parse } from "@optique/core/parser";
-import { argument, command, constant, option } from "@optique/core/primitives";
+import {
+  argument,
+  command,
+  constant,
+  flag,
+  option,
+} from "@optique/core/primitives";
 import { integer, string } from "@optique/core/valueparser";
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
@@ -1825,3 +1831,74 @@ describe("merge() should propagate brief/description/footer from inner parsers",
     );
   });
 });
+
+describe("getDocPage regression: meta commands with withDefault(or(...))", () => {
+  // Regression test for https://github.com/dahlia/optique/issues/121
+  // Meta commands were missing from the command list when the user parser
+  // included withDefault(or(...)), because getDocPage's do...while loop
+  // ran the parser once even with an empty buffer, causing longestMatch to
+  // record the user parser as "selected" and skip all other parsers in
+  // getDocFragments.
+  it("should include all commands when longestMatch wraps a parser with withDefault(or(...))", () => {
+    // Reproduce the issue: a user parser where withDefault(or(...)) allows
+    // the merge to succeed with zero consumed tokens.
+    const configOption = withDefault(
+      or(
+        object({ ignoreConfig: flag("--ignore-config") }),
+        object({ configPath: option("--config", string({ metavar: "PATH" })) }),
+      ),
+      { ignoreConfig: false, configPath: undefined } as {
+        readonly ignoreConfig: boolean;
+        readonly configPath: string | undefined;
+      },
+    );
+
+    const userParser = merge(
+      or(
+        command("foo", object({}), { description: message`foo cmd` }),
+        command("bar", object({}), { description: message`bar cmd` }),
+      ),
+      configOption,
+    );
+
+    // Simulate what run() does: combine the user parser with meta commands
+    // via longestMatch.
+    const helpCmd = command("help", object({}));
+    const versionCmd = command("version", object({}));
+    const combined = longestMatch(helpCmd, versionCmd, userParser);
+
+    // Root-level help: getDocPage called with empty args (no subcommand selected).
+    const doc = getDocPage(combined, []);
+    assert.ok(doc, "doc should not be undefined");
+
+    const allEntries = doc.sections.flatMap((s) => s.entries);
+    const commandNames = allEntries
+      .filter((e) => e.term.type === "command")
+      .map((e) => (e.term.type === "command" ? e.term.name : ""));
+
+    assert.ok(
+      commandNames.includes("help"),
+      `"help" should appear in the command list, got: [${
+        commandNames.join(", ")
+      }]`,
+    );
+    assert.ok(
+      commandNames.includes("version"),
+      `"version" should appear in the command list, got: [${
+        commandNames.join(", ")
+      }]`,
+    );
+    assert.ok(
+      commandNames.includes("foo"),
+      `"foo" should appear in the command list, got: [${
+        commandNames.join(", ")
+      }]`,
+    );
+    assert.ok(
+      commandNames.includes("bar"),
+      `"bar" should appear in the command list, got: [${
+        commandNames.join(", ")
+      }]`,
+    );
+  });
+});

packages/core/src/parser.ts

@@ -816,11 +816,11 @@ function getDocPageSyncImpl(
     state: parser.initialState,
     usage: parser.usage,
   };
-  do {
+  while (context.buffer.length > 0) {
     const result = parser.parse(context);
     if (!result.success) break;
     context = result.next;
-  } while (context.buffer.length > 0);
+  }
   return buildDocPage(parser, context, args);
 }
 
@@ -837,11 +837,11 @@ async function getDocPageAsyncImpl(
     state: parser.initialState,
     usage: parser.usage,
   };
-  do {
+  while (context.buffer.length > 0) {
     const result = await parser.parse(context);
     if (!result.success) break;
     context = result.next;
-  } while (context.buffer.length > 0);
+  }
   return buildDocPage(parser, context, args);
 }