fix(php): interface/trait/enum declarations mint canonical nodes; sourced declarations win over sourceless lookup rivals; refuse relative-scope callees

[filipechagas]

Three PHP fixes for one failure family — node identity: types that never mint a declaration node leave sourceless stubs to shadow the real name, absorb its fan-in, and poison both lookup and call edges. Found and measured on a 46k-node Laravel corpus; adapted from lawnstarter#51 (each commit carries the provenance line).

1. fix(extract): PHP interface/trait/enum declarations mint canonical nodes (325d614)

_PHP_CONFIG.class_types held class_declaration alone, so none of the three ever minted a node — 291 declarations with no node on the measured corpus (142 interfaces / 30 traits / 119 enums). Their fan-in scattered: implements/extends/trait-use minted a bare sourceless stub that shadowed the real name; Foo::CONST fan-in fragmented across per-file stubs; imports/parameter-type references parked on the file node or an FQN stub. The three kinds join class_declaration (mirroring Java/Groovy, which always had interface_declaration), with two grammar details: enum bodies are enum_declaration_list, and the _resolve_php_type_references raw-scan now reads all four declaration kinds and both body shapes — so interface Reader extends Sub\Repo resolves as written instead of falling to a same-namespace guess.

Not backward compatible with an existing graph: interface/trait/enum methods move from file-scoped to type-scoped ids (labels gain the member dot). A full graphify update . lands it consistently; a hook-driven incremental rebuild against a pre-fix graph drops (never repoints) stale-id edges until the next full update. Since AST cache entries are content-hash-keyed within the version namespace, a same-version rebuild replays pre-fix nodes — this PR deliberately does not bump the version (matching #2502/#2503 convention), so you may want to pair the merge with one.

Behavior consequence worth stating: a member-call receiver typed by an interface/trait/enum can now bind (there is now a definition to find) — consistent with how Java/Groovy interfaces already behave here.

2. fix(serve): find_node_ambiguity must not collapse sourceless rivals into one group (9e73fc0)

The ambiguity check groups the winning tier by source_file — but every extractor-minted stub carries source_file == "", so N stubs collapsed into one bucket, no ambiguity was reported, and explain silently answered with matches[0] (graph-iteration order), while affected on the same name refused with "No unique node match". Now: the exact tier prefers a sourced declaration over sourceless rivals; a tier of only stubs reports each stub as its own rival instead of picking one silently; and affected.resolve_seed learns the same rule so the two commands agree on every shape. Sourced-vs-sourced ties and lone-stub resolution are unchanged. Independent of #2516 (different functions).

3. fix(engine): refuse relative-scope names as PHP scoped-call callees (088ce5c)

The scoped_call_expression handler took the scope text as the callee name, so every parent::__construct() / parent::setUp() in the corpus emitted a raw call named parent — and the cross-file label pass then bound them all to whatever callable happened to be named parent(): 1,698 fabricated calls edges into one model accessor on the measured corpus. parent/self/static are now refused as callee names (resolution would need inheritance context the raw-call facts don't carry — refusal over guessing). Legit Helper::format() scoped calls are unaffected.

Tests

Full suite on this branch (based on v8 @ 9f25a3a): 4,109 passed / 3 skipped / 0 failed. Three new test files (+26 tests); each was re-verified red against clean v8 before the fix commit, not just green after. Zero pre-existing tests modified.

Two sibling fixes deliberately not in this PR

• Resolving imports edges from their own target_fqn metadata (kills ~19k dangling import edges on the measured corpus) requires the use-statement metadata capture proposed in fix(php): preserve use-statement facts and stop group-form use function/const from claiming class names #2502; it is a ~60-line follow-up once that merges.
• Binding this.<prop> receivers from constructor-body assignment of a typed param requires the PHP receiver-typing subsystem proposed in fix(php): resolve instance-method calls edges from typed receivers (#1682) #2492 (with follow-ups fix(php): member-call follow-ups — FCC relation, union refusal, qualified receiver types, use-claim refusal #2505/feat(php): bind claimed receiver types to their declared FQNs, with incremental-rebuild parity #2506).

🤖 Generated with Claude Code

[graphify-labs]

Graphify reviewed this change.

Worth a look — the grounded gate found no coupling regressions or blocking issues, but 1 advisory finding(s) below merit a look before merge.

---

Graphify review — findings

This PR appears to make several changes to PHP extraction and node resolution in a code-graph tool (graphify): 1. PHP relative-scope call handling: Modifies the scoped_call_expression handler so that parent::, self::, and static:: calls no longer emit the scope keyword as the callee name (previously they minted raw calls to callees literally named e.g. parent). 2. PHP declaration kinds: Adds interface_declaration, trait_declaration, and enum_declaration to PHP's class_types so these mint declaration nodes like class does, plus supporting grammar adjustments (enum_declaration_list body type, extended raw-scan coverage). This shifts interface/trait/enum method ids and labels to a type-scoped form. 3. Sourceless-stub resolution: Introduces _is_sourced/_prefer_sourced_node helpers in affected.py and adjusts tier/ambiguity logic in serve so a sourceless stub no longer shadows a real declaration and so explain and affected resolve/refuse consistently. The surface area spans extract.py, extractors/engine.py, extractors/resolution.py, affected.py, serve.py, the CHANGELOG, and associated tests. The changelog notes these are extraction-side changes requiring PHP corpus re-extraction. Note: the diff was truncated in the prompt, so my summary of serve.py, resolution.py, and the test files is inferred from the changelog and symbol names rather than read directly.

Worth a look

• Relative-scope PHP calls (parent::/self::/static::) silently dropped — graphify/extractors/engine.py:582 · Escalate · medium
  • agreed by 2 of 2 members but NOT verified (no proof, no reproducing execution) — consensus is not a verdict; needs human review

Analysis details — impact, health, verification

Impact & health

Graphify review

Impact — 2219 functions depend on the 850 functions this change touches.

Health — this change adds coupling hotspots:

• worse: extract() — 378 callers, 39 callees
• worse: resolve_seed() — 16 callers, 5 callees

Verification — 2219 functions in the blast radius were not formally verified this run (proofs are advisory here).

Gate & verification

graphify gate

PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.

Advisory (not blocking):

• verification_scope: 2155 function(s) in the blast radius were not formally verified this run

· 2 grounded finding(s) anchored inline below; 1 more finding(s) on lines outside this diff (see the check run).

[graphify-labs]

Relative-scope PHP calls (parent::/self::/static::) silently dropped — agreed by 2 of 2 members but NOT verified (no proof, no reproducing execution) — consensus is not a verdict; needs human review

Graphify suggests a fix:

Suggested change

	return _read_text(node, source).rsplit("\\", 1)[-1] or None
	text = _read_text(node, source).rsplit("\\", 1)[-1]
	if not text:
	return None
	# PHP keywords are case-insensitive; relative scopes (parent::/self::/static::)
	# name no concrete class, so report them as "no scope" and let the caller emit
	# an unqualified call instead of dropping the fact entirely.
	if text.lower() in _PHP_RELATIVE_SCOPE_NAMES:
	return None
	return text

[filipechagas]

Looked into this properly — measured rather than reasoned about — and I'd like to decline it, for two independent reasons.

The suggested edit is anchored on a function this path never calls. It patches _php_name_text (engine.py:579-586), but the scoped_call_expression branch reads its scope through _read_text(scope_node, source) at engine.py:4386; _php_name_text is called only at 600, 606, 2715, 2720 and 2734. Applied literally, the edit changes _php_collect_type_refs and _php_emit_base and leaves relative-scope calls untouched — while removing the references edges that function make(): static currently mints for static/self/parent, as an unreviewed side effect.

Applied as intended, it reintroduces the defect in a different place. I patched the actual branch so a relative scope emits the method name as an unqualified callee, and re-ran extraction on a PHPUnit-shaped corpus (base class out of corpus, one unrelated in-corpus setUp). Baseline: 0 edges. With the change: one INFERRED calls edge, FooTest::prepare() → App\Models\ServiceCategory::setUp(). The raw call has is_member_call=False, so it is not skipped at extract.py:5572 and is not claimed by any typed resolver — it falls to the shared normalized-label loop at extract.py:5564+, whose index keys .setUp() and setUp() identically, making a single same-named method anywhere in the corpus an unconditional single-candidate bind. That is the same fabricated-edge shape as the bug this commit fixes, aimed at a different label. A corpus with two same-named candidates produced 0 edges in both trees, so the damage lands precisely where the bind is most confident.

And it cannot be resolved correctly at that point. The raw-call record carries caller, callee, receiver and receiver type — no enclosing or base class. The inherits edges that would answer "which class does parent denote" are never consulted by that loop, so an unqualified callee can only be name-matched. Refusing is also what the pipeline already does with every PHP member call it cannot type (extract.py:5572), so this keeps the existing policy rather than introducing a new class of drop.

On "silently": fair as a description of runtime behaviour, and the drop has no diagnostic counter. It is not undocumented, though — four tests in tests/test_php_relative_scope_calls.py pin it (including a positive control that absolute scoped calls still resolve), and the changelog entry states it outright. Binding a relative scope to its real target needs a base-class-aware resolution pass; I've opened that as its own issue on our fork rather than land an edge that is wrong in a different direction, and I'm happy to pick it up here if you'd want it.

[graphify-labs]

⚠️ Health regression — resolve_seed()

16 callers depend on it (afferent coupling).

Grounded coupling-delta finding (deterministic), not an LLM guess.

[filipechagas]

On the automated coupling thread for resolve_seed() (graphify/affected.py:115, "16 callers depend on it") — I think this one is misfiled, and the numbers argue the opposite way.

Audited against base 9f25a3a, head 325d614:

• Production fan-in is unchanged at 1. The only production caller is graphify/affected.py::format_affected, at both base and head. An AST scan across every .py in the tree counts 9 distinct calling functions at base and 14 at head; all five additions are test functions in the new tests/test_stub_shadow_ambiguity.py. (The tool reports 16 — I can't reproduce that exactly; it likely counts the from graphify.affected import resolve_seed statements as well.)
• The callee bump is a decomposition, not accretion. The function goes 45 → 58 lines (+14 / −1), and its call targets 8 → 10. The two new targets are _is_sourced() and _prefer_sourced_node() (affected.py:100-113) — named module-level helpers extracted so the sourced-beats-sourceless rule is stated once and shared with _find_node_tiers, rather than inlined twice into the tier logic. The metric counts that as coupling; I'd call it the readability fix the alternative would have needed anyway.

So there's nothing to act on here that I can see. The one thread on this PR I do think deserves a real answer is the relative-scope one on engine.py:584, which I've replied to separately with measurements.