PHP use-import map 3/5: PhpNameResolver decisive refusal (closes #16)

[filipechagas]

Parent

Spec: #18 (ticket 3/5). This ticket closes #16.

What to build

A PhpNameResolver mirroring CsharpNameResolver (graphify/extractors/csharp.py:174-296), returning a (node_id, decisive) verdict, consulted in _resolve_php_member_calls (extract.py:3247-3260) in front of the corpus-wide type_def_nids short-name fallback — exactly like the C# call site (extract.py:2870-2885).

Minimal decisive rules for this ticket:

• Receiver short name matches a use alias/import in the calling file → resolve the aliased FQN against the in-corpus FQN index; hit → (nid, True); miss → (None, True) — refuse, never fall back. (The miss case is PHP: use-alias pointing outside the corpus + one same-short-named in-corpus class mints a wrong INFERRED edge (design risk 6, measured) #16's false edge.)
• No claim on the name → (None, False) → existing fallback runs unchanged.

Strictly subtractive: this ticket may only delete edges relative to v8, never add or re-point.

Repro that must go green (from #16 / probe scenario 10 — the canonical copy lives in spec #18)

Two files: App\Local\Client::send() and a caller in App\Http with use Vendor\Sdk\Client; + private Client $c; + $this->c->send(). Today: false edge App\Http\I::go -> App\Local\Client::send INFERRED 0.8. After: no edge.

Constraints

• Red-first: the repro test must be shown failing before the fix.
• Decoy discipline: add a positive guard — a caller whose use App\Local\Client; points at the real in-corpus class must KEEP its edge (that path may bind via the existing unique-short-name fallback; it must not regress).
• Refusal is correct on both full and incremental runs without new markers (the use map belongs to the freshly-dispatched calling file) — but add a mirrored incremental test per test_php_member_calls.py:1544-1878 (_full_then_incremental) proving it.
• CHANGELOG line naming the deleted-edge class (alias-claimed short names no longer bare-name fallback).

Acceptance criteria

• PHP: use-alias pointing outside the corpus + one same-short-named in-corpus class mints a wrong INFERRED edge (design risk 6, measured) #16 repro yields no calls edge (same-file and cross-file variants)
• In-corpus use alias keeps its edge (positive guard with same-short-named decoy getting NO edge)
• Incremental rebuild behaves identically to full run for both cases
• All tests through the public extract() seam
• Full suite green vs current v8 baseline; CHANGELOG updated
• Close PHP: use-alias pointing outside the corpus + one same-short-named in-corpus class mints a wrong INFERRED edge (design risk 6, measured) #16 with gate evidence when this merges

Blocked by

#19 (needs the captured use metadata). #20 extends coverage to fully-qualified annotations but is not required for the alias case.

[filipechagas]

Implementation report (#21)

Branch feat/php-name-resolver-21, cut from v8 @ e713e02. One commit, 3e148ef. Not pushed; #21 and #16 both left open for the orchestrator gate.

What changed

• graphify/extractors/php.py (new, 279 lines) — the PHP home for name resolution, mirroring extractors/csharp.py. Holds PhpNameResolver with the (node_id, decisive) verdict, _php_fqn_names_another_class, and _php_qualified_corroborates (moved verbatim from extract.py, no behavior change — graphify.extract re-exports it).
• graphify/extract.py — imports the two names; _resolve_php_member_calls builds the resolver after class_fqn_by_file and consults it in front of the type_def_nids fallback, in the shape of the C# call site (resolved → use it; decisive → continue; else fall back).
• tests/test_php_name_resolver.py (new, 15 tests) — all through the public extract() seam.
• CHANGELOG.md — new Fix bullet with an explicit Deletion scope paragraph; the stale "one residual false-positive risk" sentence in the 0.9.34 known-gaps bullet now points at the fix (Java's identical exposure still named).

Test results (exact)

• Red, before the fix: tests/test_php_name_resolver.py → 7 failed, 7 passed (the 6 refusal tests + the incremental refusal failed; the 7 v8-behavior guards passed). The 15th test was added after the fix, together with the leniency change it pins.
• Green, after: tests/test_php_name_resolver.py 15 passed; the four PHP suites (test_php_member_calls, test_php_type_resolution, test_php_use_imports, test_php_qualified_receiver_types) 128 passed.
• Full suite (uv run --frozen --extra ollama pytest): 4087 passed, 36 skipped, 0 failed = 4072 baseline + 15. No flakes seen (test_label_communities_batches_when_over_batch_size passed in both full runs).

Verification beyond the suite

Differential extract() against v8 @ e713e02 over a 34-file corpus covering every receiver-typing shape I could name (bare / aliased / group use, use function / use const, absolute and relative written FQNs, promoted params, params, new-locals, inline new, first-class callables, interface-typed receiver, duplicate short names across namespaces, non-PSR-4 layout, global namespace):

3 edges deleted, 0 added, 0 re-pointed, 0 confidence changes.

The three deletions are the use Vendor\Sdk\Client; case (#16), the \Vendor\Sdk\Client annotation, and Local\Client written inside App\Http.

Acceptance criteria

• PHP: use-alias pointing outside the corpus + one same-short-named in-corpus class mints a wrong INFERRED edge (design risk 6, measured) #16 repro yields no calls edge — cross-file (test_use_alias_outside_corpus_emits_no_edge) and same-file (..._same_file, the stranger declared in a second braced namespace block of the calling file, which is the only spelling of "same file" that is legal PHP: use Vendor\Sdk\Client; beside class Client in one namespace is a fatal error)
• In-corpus use alias keeps its edge, with a decoy declaring an identically named method that gets nothing (test_in_corpus_use_alias_keeps_its_edge)
• Incremental rebuild behaves identically to the full run for both cases (test_alias_refusal_survives_incremental_rebuild, test_in_corpus_alias_still_resolves_incrementally), mirrored on test_php_member_calls.py:1544-1878
• All tests through the public extract() seam
• Full suite green vs the current v8 baseline; CHANGELOG updated naming the deleted-edge class
• Close PHP: use-alias pointing outside the corpus + one same-short-named in-corpus class mints a wrong INFERRED edge (design risk 6, measured) #16 with gate evidence when this merges — left to the orchestrator

Deviations from the ticket, and why

1. The resolver also consumes receiver_type_qualified (PHP use-import map 2/5: keep written qualified receiver types (stop flattening FQNs) #20's field). PHP use-import map 3/5: PhpNameResolver decisive refusal (closes #16) #21's minimal rules only require the alias case, but PHP use-import map 2/5: keep written qualified receiver types (stop flattening FQNs) #20 shipped that field with "the decisive refusal is PHP use-import map 3/5: PhpNameResolver decisive refusal (closes #16) #21" and left the compounding half of PHP: use-alias pointing outside the corpus + one same-short-named in-corpus class mints a wrong INFERRED edge (design risk 6, measured) #16 (private \Vendor\Sdk\Client $c;) live. It is the same deleted-edge class, so it is in. Written forms resolve per PHP rules — absolute on a leading \, else first segment through the use map, else relative to the file's namespace (derived from the php_class_fqns payload; a two-namespace file is left unanswered rather than guessed).
2. The constructor takes type_def_nids and class_fqn_by_file instead of rebuilding its indexes from all_nodes like the C# twin. That is what makes subtractiveness structural: the lookup is by the receiver's written short name in the very index the fallback uses, so a positive verdict can only be the fallback's own answer. It also keeps use App\Local\Client as Api; + private Api $c at "no edge" (v8 behavior) rather than accidentally implementing PHP use-import map 4/5: positive alias binding via namespace index #22 — pinned by test_alias_renaming_to_an_unclaimed_short_name_stays_unresolved.
3. A defining-file path with fewer segments than the written FQN is treated as absent evidence, not a contradiction. My first cut refused there, and a probe showed a real full-vs-incremental divergence: App\Weird\Odd at src/Odd.php (a stripped composer prefix — "App\\Weird\\": "src/") kept its edge on a full run via the declared FQN and lost it on an incremental one, where the declaration is gone. Measured, then fixed; test_non_psr4_layout_keeps_its_edge_incrementally pins it, and the differential above is unchanged by it.

For later tickets

• Residual full-vs-incremental gap, unchanged by (3): when an unchanged defining file's declared namespace disagrees with a path that is long enough to align (e.g. App\Weird\Odd at lib/vendor/odd.php), the full run keeps the edge and an incremental one refuses. Persisting the declared FQNs of unchanged files — spec Spec: PHP use-import-map awareness for member-call resolution (upgrade path for #16) #18's ticket 5 / PHP use-import map 5/5: incremental-rebuild parity marker for declared FQNs #23 — closes it. PHP use-import map 4/5: positive alias binding via namespace index #22 needs that marker anyway.
• PHP use-import map 4/5: positive alias binding via namespace index #22 should extend resolve_type_name's hit path, not the call site. The two things keeping it subtractive today are the written-short-name lookup and the len(candidates) != 1 refusal. Both are exactly what PHP use-import map 4/5: positive alias binding via namespace index #22 must relax, with the marker in hand.
• The use-map keys on metadata.target_fqn / alias and gates on use_kind == "class", so PHP: group-form use function / use const leaks into the class-name map #26's group-form fix is load-bearing for it; test_use_function_import_makes_no_class_claim covers all three spellings.
• Java has the identical use-map exposure (named in the CHANGELOG since 0.9.34 and still open); PhpNameResolver is now a second worked example of the pattern after C#.

[filipechagas]

Closed by PR #32 (merge commit cec9cdd). Orchestrator gate evidence: independent full-suite run reproduced 4087/36 (baseline 4072/36 + 15 new tests). Red state recorded: 7 failures against unfixed code (6 refusals + the mirrored incremental refusal); the 7 v8-behavior guards green as required. Differential extract over a 34-file all-shapes corpus: exactly 3 edges deleted (the #16 false-edge class), 0 added, 0 re-pointed. v8 baseline is now 4087/36. Remaining from spec #18: #22 + #23 (ship together).