feat: flexible matcher architecture and null/empty array equivalence

[deblockt]

Summary

This PR introduces a more flexible matcher architecture and adds the ability to treat null and empty arrays [] as equivalent.

Closes #17

Breaking Changes

CompositeJsonMatcher API

The constructor now accepts varargs instead of 3 fixed parameters:

// Before
new CompositeJsonMatcher(arrayMatcher, objectMatcher, primitiveMatcher)

// After
new CompositeJsonMatcher(matcher1, matcher2, matcher3, ...)

PartialJsonMatcher interface

New method manage(JsonNode expected, JsonNode received) required to determine if a matcher handles a comparison.

LenientNumberPrimitivePartialMatcher

No longer uses delegation pattern. Must be used alongside StrictPrimitivePartialMatcher:

// Before
new LenientNumberPrimitivePartialMatcher(new StrictPrimitivePartialMatcher())

// After
new LenientNumberPrimitivePartialMatcher(),
new StrictPrimitivePartialMatcher()

New Features

NullEqualsEmptyArrayMatcher

Treats null and [] as equivalent:

final var jsonMatcher = new CompositeJsonMatcher(
    new NullEqualsEmptyArrayMatcher(),     // Must be first
    new LenientJsonArrayPartialMatcher(),
    new LenientJsonObjectPartialMatcher(),
    new LenientNumberPrimitivePartialMatcher(),
    new StrictPrimitivePartialMatcher()
);

// These now match with 100% similarity:
// {"items": null}  vs  {"items": []}

Note: Missing properties do NOT match empty arrays (intentional design decision).

Changes

• CompositeJsonMatcher: Refactored to use varargs and dynamic matcher selection via manage() method
• PartialJsonMatcher: Added manage() method to interface
• LenientNumberPrimitivePartialMatcher: Simplified to only handle numbers
• NullEqualsEmptyArrayMatcher: New matcher for null/empty array equivalence
• README: Complete rewrite with improved structure and documentation
• Tests: Added unit tests and integration tests for all new functionality

Test Plan

• All existing tests pass
• Unit tests for NullEqualsEmptyArrayMatcher
• Integration tests for nested structures
• Tests for LenientNumberPrimitivePartialMatcher refactoring
• Updated CompositeJsonMatcherTest for new API

---

🤖 Generated with Claude Code