Stub-shadow fix 1/4: PHP interface/trait/enum declarations mint canonical nodes (RC1 of #46)

[filipechagas]

Parent

#46 — implements RC1 (the primary root cause). #46's body is the canonical spec: file:line evidence, 7-file minimal-repro recipe, class-vs-interface control experiment, corpus metrics.

What to build

PHP interface/trait/enum declarations mint canonical declaration nodes, exactly as class does today: add interface_declaration, trait_declaration, enum_declaration to _PHP_CONFIG.class_types (graphify/extract.py:1065), mirroring Java (extract.py:936) and Groovy (extract.py:952). Also teach the resolution.py:2688 raw-scan (currently class_declaration only) the new types, so interface-extends-interface edges resolve.

Known caveats (from #46's fix direction 1):

• enum bodies parse as enum_declaration_list, not declaration_list — check body_fallback_child_types
• interface/trait/enum methods move from file-scoped to type-scoped ids — assess incremental-rebuild id-shift implications before shipping

Acceptance criteria

• Red-first: on the 7-file minimal repro (recipe inlined in PHP node identity: interfaces/traits/enums get no declaration node — sourceless stubs shadow the real name, absorb its edges, and break lookup (failure mode #3, PE-78803) #46), current v8 mints no FooRepository interface node; after the fix the node exists and implements / imports / references / references_constant all canonicalize onto it — matching the class FooRepository control behavior from PHP node identity: interfaces/traits/enums get no declaration node — sourceless stubs shadow the real name, absorb its edges, and break lookup (failure mode #3, PE-78803) #46
• trait Loggable and enum Status (declared in Extras.php, filename ≠ type name) each get a sourced declaration node; the trait's mixes_in/imports land on it; the enum's imports edge no longer dangles
• _rewire_unique_stub_nodes collapses the bare foorepository implements-stub onto the new interface node (Cascade A gone)
• Interface-extends-interface edges resolve (the raw-scan caveat)
• api-scale check: the 291 interface/trait/enum declarations with no node (pinned corpus, PHP node identity: interfaces/traits/enums get no declaration node — sourceless stubs shadow the real name, absorb its edges, and break lookup (failure mode #3, PE-78803) #46) → 0
• Existing extraction tests green; no other-language baseline changes

Blocked by

None — can start immediately. Highest gate leverage of the three RC slices: per #46, fixing RC1 alone flips gate Q4.

[filipechagas]

Fixed on the fork feature branch fix/stub-shadowing-46 (commit 9c4db41, cherry-picked from fix/47-php-decl-nodes), headed for the single PR into v8.

What landed: interface_declaration/trait_declaration/enum_declaration join class_declaration in _PHP_CONFIG.class_types (mirroring Java/Groovy); body_fallback_child_types learns enum_declaration_list; the _resolve_php_type_references raw-scan reads all four declaration kinds and both body shapes, so interface-extends-interface and enum trait-use resolve as written instead of falling to the same-namespace guess.

Acceptance criteria:

• Minimal 7-file repro: the FooRepository interface mints a sourced canonical node; implements/imports/references/references_constant all canonicalize onto it, matching the class control — zero sourceless nodes survive in the repro graph (verified independently by review with its own dump).
• trait Loggable and enum Status in Extras.php (filename ≠ type name) each get a sourced node; mixes_in/imports land on the trait.
• The enum's imports edge: RC1's half delivered here (sourced node + FQN); the edge itself canonicalizes with Stub-shadow fix 2/4: resolve imports edges from their own target_fqn metadata (RC2 of #46) #48 — verified on the integrated branch, where the cross-slice test now asserts target == status.id.
• Bare foorepository implements-stub collapses onto the interface node (both collapse paths verified: repoint with namespaces, _rewire_unique_stub_nodes without).
• Interface-extends-interface + enum-uses-trait raw-scan: both halves regression-tested; review bisected extract.py-only vs full slice to prove the resolution.py half is load-bearing.
• Existing tests green; zero other-language baseline changes (review byte-diffed an 8-language corpus on base vs slice: identical).
• api-scale (291 missing declarations → 0) — deferred to Stub-shadow fix 4/4: release + acceptance grading on the pinned api corpus #50's grading rebuild, as specced.

Id-shift assessment (spec caveat): interface/trait/enum methods move from file-scoped to type-scoped ids (labels gain the member dot). Full graphify update re-extracts consistently; a hook-driven incremental rebuild against a pre-fix graph drops stale-id edges (loss, never misdirection) and self-heals on the next full update. AST cache is version-namespaced, so the 0.9.38 bump forces re-parse; #50's throwaway rebuild is cache-fresh by construction.

Review verdict: APPROVE (5 minors, all addressed in the amended commit or handled at integration). Follow-up filed separately: the now-redundant _php_pre_scan_non_class_declarations refusal leaves recoverable member-call fan-in unrealized. Full suite on the integrated branch: 4321 passed / 3 skipped.