Match selectors against the nodes in hand, not their descendants

[jakejackson1]

Collapses #67, #69 and #71 into one branch. They were three PRs because there was one agent per
issue, but they are one defect at three layers, and reviewing them stacked meant reading the same
fix three times. Those PRs are closed in favour of this one.

Fixes #51. Fixes #62. Also fixes the filter() bug that had no issue.

The defect

is(), filter() and the selector-filtered traversal methods asked "does this node contain a
match?" where jQuery asks "is this node a match?". Each ran a descendant search against the
candidate, so anything matching below it kept it:

html5qp('<p><span>foo</span></p>', 'p')->is('span');   // true  — expected false
qp($xml, 'Demographics > Age > Name')->parents('Demographics');
// <Demographics>, <AmplifyReturn>, <ns1:AmplifyResponse>  — expected just <Demographics>
qp($file, 'inner')->filter('li')->count();             // 2     — expected 0

has() does exactly what these used to do and is unchanged — it is the migration path for anyone
depending on the old behaviour.

The fix

The single-node test is extracted into QueryPath\Helpers\NodeMatcher, so the three call paths
cannot drift apart. It builds the traverser in "initialized" mode — treating the supplied nodes as
the candidate set rather than seeding a descendant search — which is machinery the engine already
had; nothing under src/CSS/ changed.

It also leaves the scope node at its default. Passing a candidate as the scope node makes every
candidate match :scope, which is why the selector silently stopped filtering:

qp($xml, 'c')->parents(':scope')     // before: b, a, root   after: root
find('div')->children(':scope')      // before: 3            after: 0

filter() and children() filter their candidates as one set rather than one node at a time.
A per-node pass cannot evaluate a selector describing a position within the set, because each
node is the only member of its own one-element set.

parents()/parentsUntil() now return reverse document order with duplicates removed, per the
jQuery spec quoted in #62.

Breaking changes

Method	Before	After
is($sel)	true if a descendant matched	true if a set member matches
filter($sel)	kept elements containing a match	keeps elements that match
parents(), parentsUntil(), closest(), parent(), next*(), prev*(), siblings(), not()	selector matched containment	selector matches the element
parents(), parentsUntil() ordering	grouped by starting element	reverse document order, deduplicated

is() also no longer fatals on a match set holding non-element nodes — DOMText raised
Call to undefined method DOMText::getElementsByTagName().

The author's comment on filter()

filter() carried this since 2009:

// Seems like this should be right... but it fails unit
// tests. Need to compare to jQuery.
// $query = new \QueryPath\CSS\DOMTraverser($tmp, TRUE, $m);

It fails exactly one test — DOMQueryTest::testFilter, whose two meaningful assertions both pin
the containment result. Rebaselined here, with two tests added: one pinning the filter()/has()
difference so the migration path stays covered, one for set-level evaluation. No other existing
test encoded the old behaviour.

Interaction with #66

#66 documents a known limitation: children() and filter() built a traverser per node, so a
positional pseudo-class saw a one-element set and children('li:first') returned every li child.
Set-level filtering resolves it. Verified by merging #66 into this branch locally — 382 tests pass,
and filter(':first') → a1, filter(':eq(3)') → b1, filter(':odd') → a2,b1,
children('li:first') → x1, all matching jQuery. #66 needs no change; this removes the
reason for its caveat.

#50 (issue #49) conflicts in one assertion: its committed assertTrue($q->is(':text')) holds $q
as the <div> while only its children are :text, and becomes false here. It needs flipping to
assertFalse at merge.

Verification

• vendor/bin/phpunit — 346 tests, 1164 assertions, 0 failures (2 pre-existing create_function skips)
• composer run lint and composer run lint:min-php — clean, PHP 7.1+
• Merged with jQuery positional pseudo-classes (:eq, :first, :lt, :gt, :odd, :even) index siblings instead of the match set; :eq(0) never matches #66 — 382 tests, 0 failures
• New: tests/Issues/Issue51Test.php (11 tests), tests/Issues/Issue62Test.php (14 tests), 3 in DOMQueryTest

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 94.33962% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.57%. Comparing base (296d828) to head (c54f283).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/CSS/DOMTraverser/Util.php	86.84%	5 Missing ⚠️
src/Helpers/NodeMatcher.php	95.23%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main      #72      +/-   ##
============================================
+ Coverage     89.44%   89.57%   +0.12%     
- Complexity     1342     1366      +24     
============================================
  Files            26       27       +1     
  Lines          3023     3070      +47     
============================================
+ Hits           2704     2750      +46     
- Misses          319      320       +1     

☔ 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.