test(sanitize): add regression suite for getByPath nullish traversal and boundary contracts

[eteonninob-arch]

Closes #1045
Hardens and exercises the path-traversal failure and empty-result branch in src/lib/sanitize.ts:171 (if (cur == null) return undefined;). Adds comprehensive NatSpec/JSDoc documentation to getByPath and setByPath, exports both helper methods without modifying existing public contracts, and establishes an exhaustive regression test suite in src/lib/sanitize.test.ts achieving 100% statement, branch, function, and line coverage.

Problem & Evidence

• Evidence: src/lib/sanitize.ts:171 contains if (cur == null) return undefined; inside getByPath.
• Root Cause & Behavior: When traversing a dot-separated path (e.g. 'user.profile.bio'), intermediate nullish properties (null or undefined) short-circuit traversal and return undefined. Prior to this change, this empty-result / failure path lacked deterministic boundary tests and explicit contract assertions, leaving the codebase susceptible to silent regressions during path resolution or object sanitation.

Solution & Key Changes

1. Contract Hardening & Documentation (src/lib/sanitize.ts):

   • Added developer-focused NatSpec/JSDoc annotations detailing security assumptions, empty-result contracts, and the distinction between intermediate nullish traversal (undefined) vs terminal leaf null values (null).
   • Exported getByPath and setByPath for direct observability and unit verification while fully preserving the existing module contract for all consumers of sanitizeObject and sanitizeString.
   • Resolved static linting annotations (no-control-regex and explicit any tags).

2. Deterministic Regression Suite (src/lib/sanitize.test.ts):

   • Branch Evidence Coverage (if (cur == null) return undefined;):
     • Immediate child of intermediate null: { user: null } with path 'user.profile' -> undefined.
     • Immediate child of intermediate undefined: { user: undefined } with path 'user.profile' -> undefined.
     • Deeply nested intermediate null: { a: { b: { c: null } } } with path 'a.b.c.d.e' -> undefined.
     • Deeply nested intermediate undefined: { a: { b: { c: undefined } } } with path 'a.b.c.d' -> undefined.
     • Missing intermediate property: { a: {} } with path 'a.b.c' -> undefined.
     • Intermediate primitive scalars: { a: 42 }, { a: false }, and { a: 'scalar' } with path 'a.b.c' -> undefined.
     • Null/undefined root objects: getByPath(null, 'a.b') and getByPath(undefined, 'a.b') -> undefined.
   • Neighboring Normal & Leaf Path Contracts:
     • Leaf null contract distinction: verifies that { a: { b: null } } with path 'a.b' preserves explicit null, while 'a.b.c' yields undefined.
     • Normal nested leaf resolution across strings, numbers, booleans, and arrays.
   • Boundary Path Inputs:
     • Empty path string "", consecutive dots 'a..b', leading dots '.a', and trailing dots 'a.'.
   • setByPath Container Creation & Mutation Safeguards:
     • Replacing intermediate null or primitive scalars (typeof cur[p] !== 'object') with clean object containers ({}).
     • Preserving adjacent sibling properties during nested assignments.
   • sanitizeObject Integration Tests:
     • Intermediate null with optional rule -> preserved as null without mutation.
     • Intermediate null with required and default rule -> reparented to object container with sanitized fallback.
     • Intermediate undefined with required and default rule -> populated with sanitized nested default.
     • Primitive intermediate scalar with required rule -> converted to object with default leaf.
     • Array sanitization with type: 'string[]' vs non-array inputs.

Validation & Test Results

• Focused Unit & Coverage Suite (src/lib/sanitize.test.ts):
  • 44 tests passed (44 total)
  • 100% Statements, 100% Branches, 100% Functions, 100% Lines
• Surrounding Suite (src/middleware/offeringSanitize.test.ts):
  • 3 tests passed (3 total)
• Static Analysis & Type Checking:
  • tsc --noEmit src/lib/sanitize.ts src/lib/sanitize.test.ts -> 0 errors
  • eslint src/lib/sanitize.ts src/lib/sanitize.test.ts -> 0 errors, 0 warnings

[drips-wave]

@eteonninob-arch Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits