fix: explicit undefined option no longer disables the recursion limits

[MichaelLeeHobbs]

The bug

stderr() spread ...options over the resolved defaults:

const opts: NormalizeOptionsInternal = {
    maxDepth: _maxDepth,
    // ...
    ...options,   // an explicit `undefined` overwrites the default
};

Passing an explicit undefined — e.g. stderr(e, { maxDepth: config.maxDepth }) where the config key is absent, the most natural caller pattern — overwrote the default with undefined instead of falling back to it.

validateOption() returns early on undefined, so the value passed validation. checkDepthLimit then evaluated depth >= undefined, which is always false, disabling the depth guard entirely. Normalization recursed until the stack overflowed, turning the bounded-recursion guarantee (ADR-001, ADR-003) into a RangeError.

The NormalizeOptionsInternal = Required<NormalizeOptions> annotation could not catch this — the spread is type-compatible.

Reproduced against dist/ on main:

=== default (maxDepth=8) ===  [cause]: [Max depth of 8 reached]
=== maxDepth: undefined ===   THREW: RangeError - Maximum call stack size exceeded

The fix

Resolve each field with ?? rather than spreading. Four lines in src/stderr.ts.

Blast radius

Narrower than it first appears, and worth recording: toString() reads maxDepth off the StdError instance (MAX_DEPTH_SYMBOL ?? StdError.defaultMaxDepth, which independently defaults to 8), not off the normalize options. Display therefore stayed bounded either way — only the normalize recursion ran unbounded.

The regression tests assert the normalized structure rather than toString() for exactly this reason; a toString()-based assertion passes even with the bug present.

Tests

Four tests added under Recursion & Depth Limiting. Two reproduce the bug (verified failing with the fix reverted, passing with it applied); two are guards that explicit values and the other two options still resolve correctly.

Full suite: 313/313 passing, 100% coverage, typecheck clean.

Not included

No version bump, no release. package.json untouched at 2.2.0.

[Copilot]

Pull request overview

This PR fixes a recursion-limit bypass in stderr() where explicitly passing undefined in options could overwrite default limits and disable depth guarding, leading to unbounded recursion and potential stack overflows.

Changes:

• Resolve NormalizeOptionsInternal fields with per-option ?? fallback instead of spreading options over defaults.
• Add regression tests to ensure explicitly undefined options fall back to defaults and that explicit values still take effect.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
src/stderr.ts	Fixes option resolution so undefined no longer unsets recursion/normalization limits.
test/stderr.test.ts	Adds regression coverage for explicit-undefined options and default limit behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.