fix(php): consolidated PHP support — member-call resolution, use-import handling, node identity, cross-language isolation, query seeding (#1682, #2615)

docs/how-it-works.md

@@ -48,6 +48,12 @@ EXTRACTED edges always have confidence 1.0. INFERRED edges use a discrete rubric
 - **0.65** — weak (naming similarity only)
 - **0.55** — speculative
 
+That rubric describes edges Claude inferred. The per-language member-call resolvers are a separate, deterministic source of INFERRED edges: they read the receiver's declared type out of the AST and bind at a fixed **0.8**, reserving EXTRACTED (1.0) for a receiver whose type is named in the source at the call site.
+
+**PHP member calls refuse rather than guess.** `$this->prop->method()`, `$obj?->method()`, a typed parameter and a `$var = new T()` local all bind to the receiver's declared type as INFERRED 0.8; `(new Service())->method()` is EXTRACTED 1.0, but only when the namespace written at the call site corroborates the class that was found. When the type is not provably one concrete in-corpus class, no edge is emitted at all — untyped, union- and intersection-typed receivers, a short name that matches two classes, a method the receiver's class does not declare, chained and array-element receivers, a local rebound or shadowed anywhere in the method, anonymous classes, and `self`/`static`/`parent`. A receiver typed by an `interface`, `enum` or `trait` binds to that declaration's own method only; implementations are never guessed — `MailNotifier implements Notifier` gets nothing from a `Notifier`-typed receiver. A Laravel corpus has many identically named `search()`/`log()`/`handle()` methods, so an absent edge is worth more than a guessed one.
+
+A PHP 8.1 first-class callable — `$obj->method(...)`, including the nullsafe and `$this` forms — resolves by exactly those rules but is emitted as **`indirect_call`**, not `calls`: the syntax creates a `Closure` and names the method without invoking it, the same shape the resolver already labels `indirect_call` for a callback passed by name. `calls` therefore keeps meaning "control flow transfers here". The spread form `$obj->method(...$args)` is a real invocation and stays `calls`.
+
 ---
 
 ## Token benchmark

graphify/affected.py

@@ -102,6 +102,22 @@ def _prefer_file_node(
     return None
 
 
+def _is_sourced(graph: nx.Graph, node_id: str) -> bool:
+    return bool(str(graph.nodes[node_id].get("source_file") or ""))
+
+
+def _prefer_sourced_node(graph: nx.Graph, node_ids: list[str]) -> str | None:
+    """Return the one node with a source file among label rivals, else None.
+
+    Mirrors serve's `_find_node_tiers` exact-tier rule (#49): a sourceless node is
+    an unresolved-reference placeholder, so a real declaration sharing its label is
+    the answer rather than a tie. Without this, `explain` resolved the sourced node
+    while `affected` refused with "No unique node match" — #46's symptom.
+    """
+    sourced = [node_id for node_id in node_ids if _is_sourced(graph, node_id)]
+    return sourced[0] if len(sourced) == 1 else None
+
+
 def resolve_seed(graph: nx.Graph, query: str) -> str | None:
     # A trailing path separator must not change a source-file match — serve's
     # _find_node tokenizes the path (which drops it), so strip it here for parity
@@ -115,8 +131,17 @@ def resolve_seed(graph: nx.Graph, query: str) -> str | None:
         for node_id, data in graph.nodes(data=True)
         if _normalize_label(str(data.get("label", ""))) == query_lower
     ]
-    if len(exact_label_matches) == 1:
+    if len(exact_label_matches) == 1 and _is_sourced(graph, exact_label_matches[0]):
         return exact_label_matches[0]
+    if exact_label_matches:
+        sourced = _prefer_sourced_node(graph, exact_label_matches)
+        if sourced is not None:
+            return sourced
+        # A lone match that is a sourceless stub is NOT yet an answer: the real
+        # declaration may carry a decorated label ("handle()") that only the
+        # bare-name pass below reaches, and serve's exact tier — which matches
+        # both forms — would prefer it (#49). That pass is a superset of this
+        # one, so a stub with no sourced rival still resolves there.
     # Callable labels are decorated ("name()"), so a bare "name" query falls
     # through exact matching and then ties with any "name*" sibling in the
     # contains pass. Match on the undecorated name before giving up.
@@ -128,6 +153,10 @@ def resolve_seed(graph: nx.Graph, query: str) -> str | None:
     ]
     if len(bare_name_matches) == 1:
         return bare_name_matches[0]
+    if bare_name_matches:
+        sourced = _prefer_sourced_node(graph, bare_name_matches)
+        if sourced is not None:
+            return sourced
     exact_source_matches = [
         str(node_id)
         for node_id, data in graph.nodes(data=True)

graphify/cli.py

@@ -3373,7 +3373,20 @@ def _ctx_identity(source_file) -> str | None:
                             "file_type": _node.get("file_type"),
                             "type": _node.get("type"),
                         }
-                        for _marker in ("_callable", "_callable_class"):
+                        # `_php_non_class_types` (#11, #12) rides the same
+                        # marker channel as the callability flags: it records
+                        # which of an unchanged PHP file's declarations are
+                        # interfaces, enums or traits rather than classes. It
+                        # drove a receiver refusal until #53 lifted it, and is
+                        # still carried; `_php_interfaces` is the pre-#12
+                        # spelling, kept for older graphs. `_php_class_fqns`
+                        # (#23) is what resolution reads today: the declared
+                        # FQNs that let a claimed `use` import bind into an
+                        # unchanged defining file (#22), and let the guard
+                        # refuse a vendor import that only shares a short name.
+                        for _marker in ("_callable", "_callable_class",
+                                        "_php_non_class_types", "_php_interfaces",
+                                        "_php_class_fqns"):
                             if _node.get(_marker):
                                 _ctx_node[_marker] = _node[_marker]
                         _ctx_nodes.append(_ctx_node)