fix(jsonpath): return a null object member instead of skipping it on-demand

[linhongyu510]

The bug

GetByJsonPathOnDemand reports no match for a null object member, while GetByJsonPath returns "null" for the same document and path.

json                 path     DOM        on-demand
{"a":null}           $.a      "null"     no match (err 20)
{"a":null,"b":1}     $.a      "null"     no match
{"a":{"b":null}}     $.a.b    "null"     no match

Arrays are not affected — $[0] over [null] already returns "null" — so the two backends disagree based only on whether the null sits under a key or an index. A caller switching to the on-demand API for performance silently loses every explicit-null field.

Root cause

In the object branch, once advanceKey() matches, a null value is skipped unconditionally:

if (found) {
  // if not null
  if (peek() != 'n') {
    return getJsonPath<style, serializeFlags>(path, index + 1, ...);
  } else {
    // skip null
    RETURN_FALSE_IF_PARSE_ERROR(skipOne());
    return false;      // <-- even when the key was the last path step
  }
}

Skipping is right only while the path still has steps left, since nothing can be selected out of null. When the key is the final step, the null is the requested value. The array element path never had this problem because it recurses straight into getJsonPath(), where the path_is_nil branch emits the value through getOne().

The fix, and a trap in it

One condition, plus a style guard that matters:

if (peek() == 'n' && (style != RAW || index + 1 < path.size())) {

My first attempt used only index + 1 < path.size() and broke JsonPath.WildcardFiltersNull, which asserts that $.root[*].a over {"root":[{"a":null},{"a":"foo"},{"a":"bar"}]} yields ["foo","bar"] — nulls dropped, not [null,"foo","bar"]. The same null-skip is doing double duty: guarding traversal and filtering wildcard results. Wildcard collection runs under FLATTEN/QUOTE, so the skip stays unconditional there and only RAW, the single-result style, distinguishes "path ends here" from "path continues". That test now passes unchanged, and I added it to the new test as an explicit guard.

How it was found

A differential fuzzer: generate a random JSON document, record every path that resolves into it, then compare both backends on each. Any disagreement is a bug in one of them, with no oracle needed.

before:  3928 mismatches / 135242 (json, path) pairs   -- all null object members
after:      0 mismatches / 135242

Every one of the 3928 had DOM returning null, which is what reduced the whole class to the one-line cause above.

Verification

Since there is no local gtest here and FetchContent cannot reach the network from this machine, I verified by differential replay rather than running the suite — worth knowing when reading the evidence.

1. Differential fuzzer: 135,242 pairs, 0 mismatches (was 3928).
2. Suite-path replay: all 94 path literals from tests/jsonpath_test.cpp × 11 documents = 1034 rows, byte-identical to upstream. None of those documents pairs a key directly with null, which is precisely why the suite did not catch this.
3. Wildcard behaviour: verified identical to pristine upstream on three wildcard-plus-null shapes. One of them ($.root[*].a where every value is null) returns err 20 rather than [] — I checked, and that is pre-existing upstream behaviour, not something this change introduces. I have left it alone.
4. ASan/UBSan clean on all probes.

The new test asserts all four directions: null returned for a terminal key, both backends agreeing, path-continues-past-null still not matching, and wildcard nulls still filtered.

clang-format clean (14.0.6).

Relationship to #152

Independent. #152 makes the on-demand negative-index limitation reportable (kErrorNoneNoMatch → kUnsupportedJsonPath); this one fixes a case where on-demand returns the wrong answer outright. They touch different functions and can be merged in either order — I kept them as separate branches off master rather than stacking them.

[linhongyu510]

Confirmed these two PRs are safe to merge in either order. I test-merged #152 and #153 onto master together: both hunks auto-merge with no conflicts (they touch getJsonPathArrayIndex() around line 677 and the object-key branch around line 959, plus adjacent test additions).

With both applied, verified the combined behaviour:

• differential fuzzer: 0 mismatches across 135,242 (json, path) pairs
• $[-1] -> kUnsupportedJsonPath (17), $.zz / $[9] -> kErrorNoneNoMatch (20), so the two stay distinguishable
• {"a":null} $.a -> null in both backends
• wildcard null filtering unchanged: $.root[*].a -> ["foo","bar"]

[linhongyu510]

F pushed a small test-only follow-up (381c6a5): KeyNullElementPair still asserted the old on-demand behavior (`` empty) for a null object member. With this PR's change it returns "null" to match the DOM backend, so I updated that stale expectation. Full local `unittest`: 300/300 pass. The workflow runs on this head are still waiting on the fork-PR approval gate.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 69.67%. Comparing base (ee76cf2) to head (381c6a5).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #153   +/-   ##
=======================================
  Coverage   69.67%   69.67%           
=======================================
  Files          27       27           
  Lines        3706     3706           
  Branches     1189     1189           
=======================================
  Hits         2582     2582           
  Misses        211      211           
  Partials      913      913           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.