Fix annotation injection corrupting undefined state

injectAnnotationsIntoParser() unconditionally spread
parser.initialState into a new object with the annotation key.
When initialState was undefined (as in withDefault() and
optional()), this turned it into { [annotationKey]: annotations },
breaking the typeof state === "undefined" check that
parseOptionalStyleSync() relies on to distinguish the
uninitialized state from a wrapped [TState] tuple.

The fix skips annotation injection when initialState is null or
undefined.  The same guard is applied to all annotation injection
sites in parseSync(), parseAsync(), suggestSync(), suggestAsync(),
and getDocPage().

Fixes #131

Co-Authored-By: Claude <noreply@anthropic.com>

Author: dahlia

CHANGES.md

@@ -10,6 +10,19 @@ To be released.
 
 ### @optique/core
 
+ -  Fixed `runWith()` (and by extension `runWithConfig()`) crashing with
+    `TypeError: Cannot read properties of undefined` when the top-level parser
+    has an `undefined` initial state, such as `withDefault(object({...}))`.
+    The root cause was that `injectAnnotationsIntoParser()` unconditionally
+    spread `parser.initialState` into a new object with the annotation key,
+    turning `undefined` into `{ [annotationKey]: annotations }`.  This corrupted
+    the state for parsers like `withDefault()` and `optional()` that rely on
+    `typeof state === "undefined"` to distinguish the uninitialized state from
+    a wrapped inner state.  The fix skips annotation injection when the initial
+    state is `null` or `undefined`.  The same guard was applied to annotation
+    injection in `parseSync()`, `parseAsync()`, `suggestSync()`,
+    `suggestAsync()`, and `getDocPage()`.  [[#131]]
+
  -  Fixed `formatDocPage()` to respect `maxWidth` when the rendered option
     term is wider than `termWidth` (default: 26).  Previously, the description
     column width was calculated assuming the term occupied exactly `termWidth`
@@ -27,6 +40,7 @@ To be released.
     was appended after `formatMessage()` had already filled the description
     column to capacity, producing lines that were one character too wide.
 
+[#131]: https://github.com/dahlia/optique/issues/131
 [#132]: https://github.com/dahlia/optique/issues/132
 
 

packages/config/src/run.test.ts

@@ -4,7 +4,7 @@ import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { z } from "zod";
 import { object } from "@optique/core/constructs";
-import { option } from "@optique/core/primitives";
+import { flag, option } from "@optique/core/primitives";
 import { integer, string } from "@optique/core/valueparser";
 import { withDefault } from "@optique/core/modifiers";
 import { bindConfig, createConfigContext } from "./index.ts";
@@ -639,4 +639,49 @@ describe("runWithConfig", { concurrency: false }, () => {
       assert.ok(helpOutput.includes("Usage: my-custom-app"));
     });
   });
+
+  test("withDefault(object(...)) returns default on empty args", async () => {
+    // Regression test for https://github.com/dahlia/optique/issues/131
+    // runWithConfig() crashed with TypeError when withDefault(object(...))
+    // took the default path (no tokens consumed).
+    const schema = z.object({});
+    const context = createConfigContext({ schema });
+
+    const parser = withDefault(
+      object({
+        enabled: flag("--enabled"),
+        dependent: option("--dependent", string()),
+      }),
+      { enabled: false as const } as const,
+    );
+
+    const result = await runWithConfig(parser, context, {
+      load: () => ({}),
+      args: [],
+    });
+
+    assert.deepEqual(result, { enabled: false });
+  });
+
+  test("withDefault(object(...)) returns parsed value when args given", async () => {
+    // Companion test for https://github.com/dahlia/optique/issues/131
+    // Verify that when tokens are consumed, the parser works correctly.
+    const schema = z.object({});
+    const context = createConfigContext({ schema });
+
+    const parser = withDefault(
+      object({
+        enabled: flag("--enabled"),
+        dependent: option("--dependent", string()),
+      }),
+      { enabled: false as const } as const,
+    );
+
+    const result = await runWithConfig(parser, context, {
+      load: () => ({}),
+      args: ["--enabled", "--dependent", "foo"],
+    });
+
+    assert.deepEqual(result, { enabled: true, dependent: "foo" });
+  });
 });

packages/core/src/facade.ts

@@ -2650,6 +2650,14 @@ function injectAnnotationsIntoParser<
   parser: Parser<M, TValue, TState>,
   annotations: Annotations,
 ): Parser<M, TValue, TState> {
+  // Skip annotation injection for null/undefined initial states (e.g.,
+  // undefined for withDefault/optional) to preserve their semantic meaning.
+  // Corrupting undefined to { [annotationKey]: ... } breaks parsers that
+  // rely on typeof state === "undefined" checks.
+  if (parser.initialState == null) {
+    return parser;
+  }
+
   // Create a new initial state with annotations
   const newInitialState = {
     ...parser.initialState,

packages/core/src/parser.ts

@@ -383,12 +383,13 @@ export function parseSync<T>(
 ): Result<T> {
   let initialState = parser.initialState;
 
-  // Inject annotations into state if provided
-  if (options?.annotations) {
+  // Inject annotations into state if provided, but skip for null/undefined
+  // initial states (e.g., undefined for withDefault/optional) to preserve
+  // their semantic meaning.  Corrupting undefined to { [annotationKey]: ... }
+  // breaks parsers that rely on typeof state === "undefined" checks.
+  if (options?.annotations && initialState != null) {
     initialState = {
-      ...(typeof initialState === "object" && initialState !== null
-        ? initialState
-        : {}),
+      ...(typeof initialState === "object" ? initialState : {}),
       [annotationKey]: options.annotations,
     } as unknown;
   }
@@ -452,12 +453,13 @@ export async function parseAsync<T>(
 ): Promise<Result<T>> {
   let initialState = parser.initialState;
 
-  // Inject annotations into state if provided
-  if (options?.annotations) {
+  // Inject annotations into state if provided, but skip for null/undefined
+  // initial states (e.g., undefined for withDefault/optional) to preserve
+  // their semantic meaning.  Corrupting undefined to { [annotationKey]: ... }
+  // breaks parsers that rely on typeof state === "undefined" checks.
+  if (options?.annotations && initialState != null) {
     initialState = {
-      ...(typeof initialState === "object" && initialState !== null
-        ? initialState
-        : {}),
+      ...(typeof initialState === "object" ? initialState : {}),
       [annotationKey]: options.annotations,
     } as unknown;
   }
@@ -578,12 +580,13 @@ export function suggestSync<T>(
 
   let initialState = parser.initialState;
 
-  // Inject annotations into state if provided
-  if (options?.annotations) {
+  // Inject annotations into state if provided, but skip for null/undefined
+  // initial states (e.g., undefined for withDefault/optional) to preserve
+  // their semantic meaning.  Corrupting undefined to { [annotationKey]: ... }
+  // breaks parsers that rely on typeof state === "undefined" checks.
+  if (options?.annotations && initialState != null) {
     initialState = {
-      ...(typeof initialState === "object" && initialState !== null
-        ? initialState
-        : {}),
+      ...(typeof initialState === "object" ? initialState : {}),
       [annotationKey]: options.annotations,
     } as unknown;
   }
@@ -650,12 +653,13 @@ export async function suggestAsync<T>(
 
   let initialState = parser.initialState;
 
-  // Inject annotations into state if provided
-  if (options?.annotations) {
+  // Inject annotations into state if provided, but skip for null/undefined
+  // initial states (e.g., undefined for withDefault/optional) to preserve
+  // their semantic meaning.  Corrupting undefined to { [annotationKey]: ... }
+  // breaks parsers that rely on typeof state === "undefined" checks.
+  if (options?.annotations && initialState != null) {
     initialState = {
-      ...(typeof initialState === "object" && initialState !== null
-        ? initialState
-        : {}),
+      ...(typeof initialState === "object" ? initialState : {}),
       [annotationKey]: options.annotations,
     } as unknown;
   }
@@ -916,12 +920,13 @@ function getDocPageSyncImpl(
 ): DocPage | undefined {
   let initialState = parser.initialState;
 
-  // Inject annotations into state if provided
-  if (options?.annotations) {
+  // Inject annotations into state if provided, but skip for null/undefined
+  // initial states (e.g., undefined for withDefault/optional) to preserve
+  // their semantic meaning.  Corrupting undefined to { [annotationKey]: ... }
+  // breaks parsers that rely on typeof state === "undefined" checks.
+  if (options?.annotations && initialState != null) {
     initialState = {
-      ...(typeof initialState === "object" && initialState !== null
-        ? initialState
-        : {}),
+      ...(typeof initialState === "object" ? initialState : {}),
       [annotationKey]: options.annotations,
     } as unknown;
   }
@@ -950,12 +955,13 @@ async function getDocPageAsyncImpl(
 ): Promise<DocPage | undefined> {
   let initialState = parser.initialState;
 
-  // Inject annotations into state if provided
-  if (options?.annotations) {
+  // Inject annotations into state if provided, but skip for null/undefined
+  // initial states (e.g., undefined for withDefault/optional) to preserve
+  // their semantic meaning.  Corrupting undefined to { [annotationKey]: ... }
+  // breaks parsers that rely on typeof state === "undefined" checks.
+  if (options?.annotations && initialState != null) {
     initialState = {
-      ...(typeof initialState === "object" && initialState !== null
-        ? initialState
-        : {}),
+      ...(typeof initialState === "object" ? initialState : {}),
       [annotationKey]: options.annotations,
     } as unknown;
   }