graphify-php 0.0.5__py3-none-any.whl

graphify_php/graph_adapter.py

@@ -0,0 +1,520 @@
+"""`NodeIndex` and `EdgeSink` over graphify's in-memory `all_nodes` / `all_edges`.
+
+This module is the only place that knows graphify's node and edge schema. Everything else in
+the package talks to the two protocols in `ports`, so a schema move between graphify releases
+is repaired here and nowhere else.
+
+The schema this is written against, read from a real build of the reference application
+(6302 nodes / 17886 links, 4012 of them from `.php` files):
+
+- a class node carries `_callable_class: true` and a `label` that is the SHORT class name
+  (`AbstractFrontController`), never the FQN, so an FQN has to be matched down to its last
+  segment and then re-checked against the file path;
+- a method node hangs off its class by a `method` edge and its label is `.methodName()`;
+- a class node hangs off its file node by a `contains` edge;
+- `_origin` is `ast` or `semantic` on both nodes and edges.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+
+from .ports import CallTarget, Confidence
+
+# The marker this package stamps on every edge it adds, so a reader can select ours, count them,
+# or drop them from a published graph without re-running the build.
+#
+# Deliberately NOT `_origin`: graphify overwrites that on every edge with `"ast"` after the
+# resolvers run (extract.py:8285-8289), and it means the eviction tier, not the author. Our
+# edges are regenerated by the AST pass, so `ast` is the right tier for them and claiming that
+# key would both be lost and be wrong. A key of our own survives untouched.
+EDGE_MARKER = "_resolver"
+EDGE_ORIGIN = "graphify-php"
+
+# graphify's own scores for the two confidence levels (extract.py:3534). Matching them keeps
+# our edges comparable with graphify's in any consumer that ranks by score.
+_CONFIDENCE_SCORE = {Confidence.EXTRACTED: 1.0, Confidence.INFERRED: 0.8}
+
+
+def _key(label: str) -> str:
+    """graphify's own label normalisation (extract.py), reproduced so keys agree.
+
+    `.getCurrentUser()` and `getcurrentuser` collapse to the same key, which is what makes a
+    method label from the graph comparable with a method name from PHP source.
+    """
+    return re.sub(r"[^a-zA-Z0-9]+", "", str(label)).lower()
+
+
+def _fqn_parts(class_fqn: str) -> list[str]:
+    return [p for p in str(class_fqn).replace("/", "\\").split("\\") if p]
+
+
+def _path_parts(source_file: str) -> list[str]:
+    stripped = re.sub(r"\.[^./\\]+$", "", str(source_file or ""))
+    return [p for p in stripped.replace("\\", "/").split("/") if p]
+
+
+def _tail_overlap(a: list[str], b: list[str]) -> int:
+    """How many trailing segments the two paths share, compared normalised."""
+    count = 0
+    # Paths differ in length on purpose; the overlap stops at the shorter one.
+    for left, right in zip(reversed(a), reversed(b), strict=False):
+        if _key(left) != _key(right):
+            break
+        count += 1
+    return count
+
+
+class GraphNodeIndex:
+    """Answers "which node is method M of class C" and nothing else.
+
+    Built once per resolver run: the walk is linear in nodes plus edges, and the resolver asks
+    this question once per eligible call site, of which the reference application has thousands.
+    """
+
+    def __init__(self, all_nodes: list[dict], all_edges: list[dict]) -> None:
+        node_by_id: dict[str, dict] = {}
+        for node in all_nodes:
+            nid = node.get("id")
+            if nid:
+                node_by_id[nid] = node
+
+        # Only a class a file actually contains is a candidate. graphify also carries nodes
+        # that no file contains (synthesised, external, semantic); binding a call to one of
+        # those invents a target that has no definition to jump to.
+        contained: set[str] = set()
+        for edge in all_edges:
+            if edge.get("relation") == "contains":
+                target = edge.get("target")
+                if target:
+                    contained.add(target)
+
+        self._classes_by_name: dict[str, list[dict]] = {}
+        for node in all_nodes:
+            if not node.get("_callable_class") or node.get("id") not in contained:
+                continue
+            self._classes_by_name.setdefault(_key(node.get("label", "")), []).append(node)
+
+        self._methods: dict[tuple[str, str], str] = {}
+        # Method NAMES per class, and the class each method belongs to. Both exist for scoped
+        # calls: graphify records `Helper::format()` with the SCOPE as the callee and drops the
+        # method name entirely, so the only way back to `format` without re-parsing PHP here is
+        # to ask the graph which methods that class declares and let the type source check each
+        # candidate against the line it really came from.
+        self._method_names: dict[str, list[str]] = {}
+        self._owner_of: dict[str, str] = {}
+        for edge in all_edges:
+            if edge.get("relation") != "method":
+                continue
+            owner, member = edge.get("source"), edge.get("target")
+            member_node = node_by_id.get(member)
+            if owner and member_node is not None:
+                label = member_node.get("label", "")
+                self._methods[(owner, _key(label))] = member
+                self._owner_of[member] = owner
+                # `.format()` is the label; the bare name is what a call site writes.
+                self._method_names.setdefault(owner, []).append(str(label).strip(". ()"))
+
+        self._parents: dict[str, list[str]] = {}
+        for edge in all_edges:
+            if edge.get("relation") == "inherits":
+                child, parent = edge.get("source"), edge.get("target")
+                if child and parent:
+                    self._parents.setdefault(child, []).append(parent)
+
+        # Origin maps. `contains` puts a class in its file; a method hangs off its class, so it
+        # is folded through to the owning class's file. `imports` targets the imported CLASS
+        # node directly for PHP `use` statements, which is what makes "can the caller see this
+        # class" answerable from the graph rather than guessed from a path.
+        self._file_of: dict[str, str] = {}
+        for edge in all_edges:
+            if edge.get("relation") == "contains":
+                self._file_of[edge.get("target")] = edge.get("source")
+        for method_nid, owner in self._owner_of.items():
+            owner_file = self._file_of.get(owner)
+            if owner_file is not None:
+                self._file_of.setdefault(method_nid, owner_file)
+
+        self._imported_by: dict[str, set[str]] = {}
+        for edge in all_edges:
+            if edge.get("relation") in ("imports", "imports_from"):
+                self._imported_by.setdefault(edge.get("source"), set()).add(edge.get("target"))
+
+    def method_node(self, class_fqn: str, method: str) -> str | None:
+        class_node = self._class_node(class_fqn)
+        if class_node is None:
+            return None
+        return self._methods.get((class_node["id"], _key(method)))
+
+    def method_node_for(self, caller_nid: str, class_fqn: str, method: str) -> str | None:
+        """`method_node`, with the caller's own visibility as the tie-breaker and the gate.
+
+        A short-name match is not evidence the caller can see the matched class: a call that a
+        type source resolved to `Vendor\\Lib\\Emails` must not bind to a project class that
+        merely spells `Emails` the same way. graphify records enough to check rather than guess
+        — `use` statements arrive as `imports` edges pointing straight at the class node — so a
+        candidate is accepted when the caller's file imports it, when it is in the caller's own
+        file, or when it is an ancestor of the caller's class (`parent::`).
+
+        A PSR-4 path match is kept as a second, independent signal, because a class in the
+        caller's own namespace needs no `use` and so produces no import edge. Refuse only when
+        neither signal fires: the bar is graphify's own, an absent edge over a wrong one.
+        """
+        parts = _fqn_parts(class_fqn)
+        if not parts:
+            return None
+        candidates = self._classes_by_name.get(_key(parts[-1]), [])
+        if not candidates:
+            return None
+
+        visible = [c for c in candidates if self._visible_to(caller_nid, c["id"])]
+        chosen = visible[0] if len(visible) == 1 else None
+        if chosen is not None and self._outscored(chosen, candidates, parts[:-1]):
+            # Visibility picked one class, but the namespace the type source proved points
+            # at a different candidate more precisely (a parent `App\Legacy\Emails` is
+            # visible; the property is typed `App\Mail\Emails`). Binding the visible one
+            # would contradict the proof, so the call gets no edge.
+            return None
+        if chosen is None and not visible:
+            chosen = self._class_node(class_fqn)
+        if chosen is None:
+            return None
+        return self._methods.get((chosen["id"], _key(method)))
+
+    @staticmethod
+    def _outscored(chosen: dict, candidates: list[dict], namespace: list[str]) -> bool:
+        def overlap(node: dict) -> int:
+            return _tail_overlap(namespace, _path_parts(node.get("source_file", ""))[:-1])
+
+        own = overlap(chosen)
+        return any(c is not chosen and overlap(c) > own for c in candidates)
+
+    def _visible_to(self, caller_nid: str, class_nid: str) -> bool:
+        caller_class = self._owner_of.get(caller_nid, caller_nid)
+        if class_nid == caller_class:
+            return True
+        caller_file = self._file_of.get(caller_nid) or self._file_of.get(caller_class)
+        if caller_file is not None:
+            if self._file_of.get(class_nid) == caller_file:
+                return True
+            if class_nid in self._imported_by.get(caller_file, ()):
+                return True
+        return class_nid in self._with_ancestors([caller_class])
+
+    def method_node_in_file(self, source_file: str, class_fqn: str, method: str) -> str | None:
+        """`method_node`, resolved against a class declared in a known file.
+
+        A route attribute sits ON the controller class, so the file it was read from names the
+        class exactly — stronger evidence than any namespace-to-path guess, and it is what makes
+        the lookup work for the many real projects whose directory layout does not mirror their
+        namespace. Falls back to the namespace match when the file holds no such class.
+        """
+        parts = _fqn_parts(class_fqn)
+        if not parts:
+            return None
+        in_file = [
+            c
+            for c in self._classes_by_name.get(_key(parts[-1]), [])
+            if c.get("source_file") == source_file
+        ]
+        chosen = in_file[0] if len(in_file) == 1 else self._class_node(class_fqn)
+        if chosen is None:
+            return None
+        return self._methods.get((chosen["id"], _key(method)))
+
+    def owner_class(self, method_nid: str) -> str | None:
+        """The class node a method node hangs off, by its `method` edge."""
+        return self._owner_of.get(method_nid)
+
+    def scope_methods(self, caller_nid: str, scope: str) -> list[str]:
+        """Method names a scoped call `<scope>::?()` from this caller could be naming.
+
+        Candidates, not answers. Each one is offered to a type source, which reads the call
+        site's own line and refuses every name that is not written there, so a wrong candidate
+        costs a lookup and produces nothing. An empty list means the scope names no class this
+        graph knows, which is how an ordinary function call (`trim`, `error_log`) — recorded by
+        graphify in the same shape as a scoped call — is filtered out without special-casing.
+        """
+        classes = self._scope_classes(caller_nid, scope)
+        names: list[str] = []
+        seen: set[str] = set()
+        for class_nid in classes:
+            for name in self._method_names.get(class_nid, ()):
+                if name and name not in seen:
+                    seen.add(name)
+                    names.append(name)
+        return names
+
+    def _scope_classes(self, caller_nid: str, scope: str) -> list[str]:
+        key = _key(scope)
+        if key in ("self", "static"):
+            owner = self._owner_of.get(caller_nid)
+            # Inherited methods are callable through `self::` too, so the ancestry is included.
+            return self._with_ancestors([owner]) if owner else []
+        if key == "parent":
+            owner = self._owner_of.get(caller_nid)
+            return self._with_ancestors(self._parents.get(owner, [])) if owner else []
+        # A written class name: every class that spells it. Ambiguity is harmless here because
+        # the candidate is a method NAME, and the source resolves the class itself from the
+        # file's own namespace and `use` statements.
+        return self._with_ancestors(
+            [
+                n["id"]
+                for n in self._classes_by_name.get(
+                    _key(_fqn_parts(scope)[-1] if _fqn_parts(scope) else ""), []
+                )
+            ]
+        )
+
+    def _with_ancestors(self, class_nids: list[str]) -> list[str]:
+        out: list[str] = []
+        queue = list(class_nids)
+        seen: set[str] = set()
+        while queue:
+            nid = queue.pop(0)
+            if not nid or nid in seen:
+                continue
+            seen.add(nid)
+            out.append(nid)
+            queue.extend(self._parents.get(nid, ()))
+        return out
+
+    def _class_node(self, class_fqn: str) -> dict | None:
+        parts = _fqn_parts(class_fqn)
+        if not parts:
+            return None
+        namespace, short = parts[:-1], parts[-1]
+        candidates = self._classes_by_name.get(_key(short), [])
+        if not candidates:
+            return None
+
+        # Directories only: the file stem is the class name and matching it against the
+        # namespace would score every candidate the same.
+        scored = [
+            (_tail_overlap(namespace, _path_parts(c.get("source_file", ""))[:-1]), c)
+            for c in candidates
+        ]
+        best = max(score for score, _ in scored)
+        winners = [c for score, c in scored if score == best]
+        if len(winners) != 1:
+            # Two project classes share a short name and the namespace did not separate them.
+            # Picking either is a coin flip, and a wrong call edge is worse than a missing one.
+            return None
+
+        # A namespace of two or more segments must show up in the file path, because a FQN
+        # from outside the indexed tree (`Doctrine\ORM\EntityManager`) otherwise binds to
+        # whatever project class happens to share its last segment — a unique match, and
+        # wrong. A single-segment namespace is exempt: the PSR-4 root (`App\`) maps to the
+        # source directory (`src/`) and never appears as a directory itself.
+        # One shared segment is not enough either: `Vendor\Lib\Emails` against
+        # `src/Lib/Emails.php` overlaps by one and is still foreign. Every segment but the
+        # PSR-4 root has to be on the path.
+        if len(namespace) >= 2 and best < len(namespace) - 1:
+            return None
+        return winners[0]
+
+
+class GraphEdgeSink:
+    """Appends `calls` edges to graphify's edge list.
+
+    Deduplicates against the pairs already in the graph, the way graphify's own member-call
+    resolvers do: the shared cross-file pass may already have connected the same two nodes by
+    another route, and a second edge would double that pair's weight in every consumer.
+    """
+
+    def __init__(self, all_edges: list[dict], index: GraphNodeIndex | None = None) -> None:
+        self._all_edges = all_edges
+        self._index = index
+        self._pairs = {(e.get("source"), e.get("target")) for e in all_edges}
+        self._class_calls = {
+            (e.get("source"), e.get("target")) for e in all_edges if e.get("relation") == "calls"
+        }
+        self.added = 0
+
+    def add_call(self, caller_nid: str, callee_nid: str, target: CallTarget) -> None:
+        if (caller_nid, callee_nid) in self._pairs:
+            return
+        self._pairs.add((caller_nid, callee_nid))
+        edge = {
+            "source": caller_nid,
+            "target": callee_nid,
+            "relation": "calls",
+            "context": "call",
+            "confidence": target.confidence.value,
+            "confidence_score": _CONFIDENCE_SCORE[target.confidence],
+            "source_file": target.site.source_file,
+            "source_location": target.site.source_location,
+            "weight": 1.0,
+            EDGE_MARKER: EDGE_ORIGIN,
+            "_via": target.via,
+        }
+        # `Helper::format()` already produced a coarse caller -> Helper-the-CLASS edge, because
+        # graphify records the scope as the callee and resolves that name to the class node. Our
+        # method-level edge is a second, narrower edge between different endpoints, so neither
+        # dedup nor removal applies — a consumer counting `calls` edges will see both. Naming
+        # the coarse edge here is what lets it collapse the pair instead of double-counting it.
+        owner = self._index.owner_class(callee_nid) if self._index is not None else None
+        if owner is not None and (caller_nid, owner) in self._class_calls:
+            edge["_refines"] = owner
+        self._all_edges.append(edge)
+        self.added += 1
+
+
+STUB_ID_PREFIX = "php_external_"
+
+
+def _stub_nid(class_fqn: str) -> str:
+    """One id per external class, derived from the FQN alone so every build agrees.
+
+    `external: True` keeps the id global in `merge-graphs`, so the prefix must not collide with
+    graphify's own project-class ids, which never start this way.
+    """
+    return STUB_ID_PREFIX + re.sub(r"[^a-z0-9_]", "_", class_fqn.lower().replace("\\", "_"))
+
+
+class GraphStubSink:
+    """Mints a body-less node per external declaring class and edges proven calls to it.
+
+    The opt-in graphify core refuses for `calls` (phantom hubs): a `Doctrine\\ORM\\EntityManager`
+    stub will carry hundreds of edges. One stub per CLASS, never per method, so the node count
+    stays at the number of vendor classes the project touches; the method survives on the edge.
+    """
+
+    def __init__(self, all_nodes: list[dict], all_edges: list[dict]) -> None:
+        self._all_nodes = all_nodes
+        self._all_edges = all_edges
+        self._by_id = {n.get("id") for n in all_nodes}
+        self._pairs = {(e.get("source"), e.get("target")) for e in all_edges}
+        self.nodes_added = 0
+        self.edges_added = 0
+
+    def node_for(self, class_fqn: str) -> str:
+        nid = _stub_nid(class_fqn)
+        if nid not in self._by_id:
+            self._by_id.add(nid)
+            # The same shape graphify core gives an import stub (build.py), so every consumer
+            # that already handles those handles these.
+            self._all_nodes.append(
+                {
+                    "id": nid,
+                    "label": class_fqn,
+                    "file_type": "concept",
+                    "type": "external",
+                    "external": True,
+                    "source_file": "",
+                    EDGE_MARKER: EDGE_ORIGIN,
+                }
+            )
+            self.nodes_added += 1
+        return nid
+
+    def add_call(self, caller_nid: str, stub_nid: str, target: CallTarget) -> None:
+        if (caller_nid, stub_nid) in self._pairs:
+            return
+        self._pairs.add((caller_nid, stub_nid))
+        self._all_edges.append(
+            {
+                "source": caller_nid,
+                "target": stub_nid,
+                "relation": "calls",
+                "context": "call",
+                "confidence": target.confidence.value,
+                "confidence_score": _CONFIDENCE_SCORE[target.confidence],
+                "source_file": target.site.source_file,
+                "source_location": target.site.source_location,
+                "weight": 1.0,
+                EDGE_MARKER: EDGE_ORIGIN,
+                "_via": target.via,
+                "_external_target": f"{target.class_fqn}::{target.method}",
+            }
+        )
+        self.edges_added += 1
+
+
+# A route declaration is not a call, so it needs a relation of its own. `routed_to` is already
+# taken by messenger transport routing (config/messaging.py:22) and means something else
+# entirely; reusing it would merge HTTP paths and message transports into one query.
+ROUTE_RELATION = "handled_by"
+ROUTE_NODE_KIND = "http_route"
+
+
+def _route_nid(node_key: str) -> str:
+    """A stable, readable id for a route declaration.
+
+    The slug is for a human reading the graph; the digest is what guarantees identity, because
+    two declarations differing only in punctuation (`/a-b` and `/a_b`) slug to the same string.
+    `hashlib`, not `hash()`, so the id is the same in every process and every build.
+    """
+    slug = re.sub(r"[^a-zA-Z0-9]+", "_", node_key).strip("_").lower()[:80]
+    digest = hashlib.blake2b(node_key.encode("utf-8"), digest_size=4).hexdigest()
+    return f"route_{slug}_{digest}"
+
+
+class GraphRouteSink:
+    """Publishes one node and one edge per route declaration.
+
+    Separate from `GraphEdgeSink` because it adds NODES, which no call-target path ever does:
+    a route is a thing the graph did not previously contain, not a connection between two
+    things it already had. That is also why it is worth a status record of its own — a layer
+    that adds nothing looks exactly like a codebase with no routes.
+    """
+
+    def __init__(self, all_nodes: list[dict], all_edges: list[dict]) -> None:
+        self._all_nodes = all_nodes
+        self._all_edges = all_edges
+        self._by_id = {n.get("id") for n in all_nodes}
+        self._pairs = {(e.get("source"), e.get("target")) for e in all_edges}
+        self.nodes_added = 0
+        self.edges_added = 0
+
+    def add_route(self, declaration, controller_nid: str | None) -> str | None:
+        """Emit the declaration's node, and its edge when the controller method is in the graph.
+
+        Returns the node id, or None when the declaration carries no path at all and so has
+        nothing to label a node with.
+        """
+        path = declaration.path or declaration.method_path
+        if not path:
+            return None
+
+        nid = _route_nid(declaration.node_key)
+        if nid not in self._by_id:
+            self._by_id.add(nid)
+            self._all_nodes.append(
+                {
+                    "id": nid,
+                    "label": path,
+                    "source_file": declaration.source_file,
+                    "source_location": f"L{declaration.line}",
+                    "file_type": "code",
+                    EDGE_MARKER: EDGE_ORIGIN,
+                    "_kind": ROUTE_NODE_KIND,
+                    "route_name": declaration.name or "",
+                    "http_methods": list(declaration.methods),
+                    # A path composed from only one half is a usable partial, not a whole answer,
+                    # and a reader ranking routes needs to know which it is looking at.
+                    "route_complete": declaration.path is not None,
+                }
+            )
+            self.nodes_added += 1
+
+        if controller_nid and (nid, controller_nid) not in self._pairs:
+            self._pairs.add((nid, controller_nid))
+            self._all_edges.append(
+                {
+                    "source": nid,
+                    "target": controller_nid,
+                    "relation": ROUTE_RELATION,
+                    "context": "route",
+                    "confidence": Confidence.EXTRACTED.value,
+                    "confidence_score": 1.0,
+                    "source_file": declaration.source_file,
+                    "source_location": f"L{declaration.line}",
+                    "weight": 1.0,
+                    EDGE_MARKER: EDGE_ORIGIN,
+                    "_via": "attribute",
+                }
+            )
+            self.edges_added += 1
+        return nid

graphify_php/php/README.md

@@ -0,0 +1,106 @@
+# PHPStan call-graph extension
+
+A PHPStan collector and rule that write one JSON record per resolved method call. It knows
+nothing about whatever consumes the file — no node ids, no graph schema — so it can be adopted
+by anything that wants a call graph out of PHPStan.
+
+Nothing is installed. There is no composer package and no dependency to resolve; the extension
+is analysed inside somebody else's project, whose lockfile is not ours to move.
+
+## Wiring
+
+Add this to the project's `phpstan.neon`:
+
+```neon
+services:
+	-
+		class: CallGraph\JsonLinesWriter
+	-
+		class: CallGraph\MethodCallCollector
+		tags:
+			- phpstan.collector
+	-
+		class: CallGraph\CallEdgeRule
+		tags:
+			- phpstan.rules.rule
+```
+
+Then make the `CallGraph\` classes loadable. PHPStan builds its DI container before
+`parameters.bootstrapFiles` run, so a bootstrap file is too late and fails with
+`Class 'CallGraph\JsonLinesWriter' not found`. Use the `--autoload-file` option instead:
+
+```sh
+PHP_CALL_GRAPH_OUT=/tmp/calls.jsonl \
+  vendor/bin/phpstan analyse --autoload-file=/path/to/graphify-php/php/autoload.php
+```
+
+A project that would rather own the autoloading can add `"CallGraph\\": "php/src/CallGraph/"`
+to its composer `autoload-dev` and drop the option.
+
+`graphify-php`'s `phpstan` source needs neither step from the adopter: it passes
+`--autoload-file` itself and writes the `services:` block into a wrapper config in its own
+temporary directory that `includes:` the project's `phpstan.neon`. The block is deliberately not
+committed to the project, because the `CallGraph\` classes arrive only through that option and
+a plain `vendor/bin/phpstan` — the one CI runs — would fail on
+`Class 'CallGraph\JsonLinesWriter' not found` before analysing anything. A project that adds
+the block to its own config anyway is run on that config untouched; registering the collector
+twice duplicates every record.
+
+Verified against PHPStan 2.2.8 on PHP 8.4.
+
+## Output
+
+`PHP_CALL_GRAPH_OUT` names the destination; without it the file lands at `php-call-graph.jsonl`
+in the working directory. One JSON object per line:
+
+```json
+{"callerClass":"App\\Controller","callerMethod":"run","calleeClass":"App\\Mailer","calleeMethod":"send","calleeKind":"interface","line":21,"file":"/srv/app/src/Controller.php","callPos":148,"calleeFile":"/srv/app/src/Mailer.php"}
+```
+
+`callPos` is the token offset of the called method's name, `-1` when the parser did not record
+one. A union receiver (`Emails|Cache`) yields one record per arm with the same `callPos`; two
+calls of one method on one line yield different values, so a consumer can tell the two apart.
+
+`calleeKind` is `interface` when the method is declared on an interface. That edge names a
+contract, not a body: there is no code behind `App\Mailer::send`, and a consumer that treats it
+as a call into an implementation acquires a path that was never executed.
+
+`calleeClass` is the *declaring* class, not the receiver. An inherited method lives in the
+parent, and an edge to the child would point at a body that does not exist there. When the
+body lives in a trait, `calleeClass` is the trait: PHPStan's declaring class for a trait
+method is the class using it, whose file holds no such body.
+
+`calleeFile` is the file that declares `calleeClass`, `''` when PHPStan has no file for it (a
+built-in class). A consumer uses it to tell a `vendor/` class from project code the graph left
+out, without guessing from the namespace.
+
+## What it refuses to report
+
+Nothing is emitted unless PHPStan produced a class reflection for the receiver. A name-only
+fallback — matching `->get()` to any class that happens to own a `get` — manufactures edges
+indistinguishable from real ones, and a wrong edge is worse than a missing one. So these
+produce no record:
+
+- a receiver PHPStan types as `mixed`, which includes an **untyped property**, even one assigned
+  from a typed constructor parameter: PHPStan reports `missingType.property` rather than
+  inferring it. Give the property a native type or a `@var` docblock and the call resolves.
+- a dynamic method name, `$obj->$method()`;
+- a receiver on a class the analysis cannot load;
+- an intersection receiver (`A&B`) whose constituents resolve to more than one declaring class
+  for the method. One object, two declarations: the type does not say which body runs, so
+  neither is emitted. This matches the parser layer's `ambiguous-intersection` refusal. A union
+  receiver (`A|B`) is different: one of two objects, so every arm is emitted, and each arm is
+  decided on its own — `(A&B)|C` emits `C` and drops the ambiguous intersection, `(A&B)|null`
+  emits nothing. The parser layer is stricter there and refuses `(A&B)|C` wholesale as
+  `union-type`.
+
+Also out of scope in this version, by omission rather than by refusal: `?->` nullsafe calls,
+`Foo::bar()` static calls, and `new Foo` construction edges. Each is a different node type and
+would be a second collector.
+
+## Cost
+
+PHPStan loads project classes through the composer autoloader, so an analysis executes some
+project code at class-load time — attribute constructors, static initialisers, and anything the
+project's own bootstrap does. Run it the way any analysis is run: with a timeout, a memory
+limit, and no terminal to prompt at.

graphify_php/php/autoload.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * PSR-4 registrar for the CallGraph namespace.
+ *
+ * Shipped instead of a composer package so adopting this costs a `bootstrapFiles` line and no
+ * dependency resolution: it is analysed inside somebody else's project, whose lockfile is not
+ * ours to move.
+ */
+spl_autoload_register(static function (string $class): void {
+    $prefix = 'CallGraph\\';
+
+    if (!str_starts_with($class, $prefix)) {
+        return;
+    }
+
+    $relative = substr($class, strlen($prefix));
+    $path = __DIR__ . '/src/CallGraph/' . str_replace('\\', '/', $relative) . '.php';
+
+    if (!is_file($path)) {
+        return;
+    }
+
+    require_once $path;
+});