graphify-php 0.0.5__py3-none-any.whl

graphify_php/sources/route_source.py

@@ -0,0 +1,105 @@
+"""Route declarations as a source, beside the call-target one.
+
+## Why this is a second port rather than a `CallTargetSource`
+
+`CallTargetSource.resolve` returns `CallTarget`s: a call site paired with the class and method
+it reaches. A route declaration is not that shape and cannot be forced into it without lying
+about one end — there is no `CallSite`, nothing calls the controller from inside this codebase,
+and `caller_nid` would have to be invented. `ports.CallSite` says "this package never invents
+node identity"; squeezing a route through it would break exactly that promise.
+
+So the protocol below is deliberately separate and deliberately tiny: one method, returning
+declarations. It is defined here rather than in `ports.py` because `ports.py` belongs to
+another agent. **Proposed change, for whoever owns it:** move `RouteDeclarationSource` and
+`RouteResolution` into `ports.py` unchanged and have the resolver discover sources by it, the
+same way it discovers `CallTargetSource`. Nothing here needs to change when that happens —
+this module would import them instead of defining them.
+
+## What the resolver has to do with a declaration
+
+Each declaration is one node and one edge:
+
+- a node keyed by `RouteDeclaration.node_key`, labelled with the path template, carrying the
+  name and the HTTP methods;
+- an edge from that node to `NodeIndex.method_node(controller_class, controller_method)` — the
+  existing narrow port, which already answers exactly this question and adds no edge when the
+  method is not in the graph.
+
+A declaration whose `path` is None is still worth a node when `method_path` survived, and the
+resolver should treat `reason` the way it treats `Resolution.unresolved`: a counted gap.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+
+from ..ports import RouteDeclarationSource  # noqa: F401  the port this module implements
+from ..syntax import nodes
+from ..syntax.facts import FileFacts
+from ..syntax.file_scan import scan_source
+from ..syntax.routes import RouteDeclaration
+
+UNREADABLE_FILE = "unreadable-file"
+
+
+@dataclass
+class RouteResolution:
+    """What a source made of the files it was given."""
+
+    declarations: list[RouteDeclaration] = field(default_factory=list)
+    unresolved: dict[str, int] = field(default_factory=dict)
+    files_seen: int = 0
+
+    @property
+    def resolved(self) -> list[RouteDeclaration]:
+        return [d for d in self.declarations if d.resolved]
+
+
+class TreeSitterRouteSource:
+    """Route declarations read from PHP attributes.
+
+    A declaration proves that this codebase declares the path and names this controller method
+    to serve it. It does not prove that any deployed ingress sends that path here, nor that a
+    given environment loads the route — Symfony filters on `env`, and a reverse proxy or a
+    different service may answer first. The graph gains "who in this code claims this path",
+    which is the question that has no symbol in it and is therefore unanswerable today.
+    """
+
+    name = "tree_sitter_routes"
+
+    def available(self, repo_root: str) -> tuple[bool, str]:
+        return nodes.tree_sitter_available()
+
+    def declarations(self, repo_root: str, files: Iterable[str]) -> RouteResolution:
+        resolution = RouteResolution()
+        seen: set[str] = set()
+        for path in files:
+            full = path if os.path.isabs(path) else os.path.join(repo_root, path)
+            full = os.path.realpath(full)
+            if full in seen:
+                continue
+            seen.add(full)
+            facts = self._facts(path, full)
+            if facts is None:
+                _count(resolution, UNREADABLE_FILE)
+                continue
+            resolution.files_seen += 1
+            for declaration in facts.routes:
+                resolution.declarations.append(declaration)
+                if declaration.reason:
+                    _count(resolution, declaration.reason)
+        return resolution
+
+    def _facts(self, path: str, full: str) -> FileFacts | None:
+        try:
+            with open(full, "rb") as handle:
+                source = handle.read()
+        except OSError:
+            return None
+        return scan_source(path, source)
+
+
+def _count(resolution: RouteResolution, reason: str) -> None:
+    resolution.unresolved[reason] = resolution.unresolved.get(reason, 0) + 1

graphify_php/sources/tree_sitter_source.py

@@ -0,0 +1,428 @@
+"""The parser-backed `CallTargetSource`.
+
+Needs nothing but the source text: no `vendor/`, no PHP binary, no composer autoloader. That
+is what makes it the source that always runs, and what bounds what it can prove. Measured on
+one Symfony application before this package existed: 2172 `calls` edges against 3426 callable
+nodes, 24 % of callables with an outgoing call edge and 20 % with an incoming one. Most of the
+missing edges are `$this->someInjectedService->method()`, and the type is written in the same
+file, in the constructor.
+
+Every site it cannot prove is counted under a fixed reason instead of guessed at. Six upstream
+issues across four code-graph projects trace their false edges to a name-only fallback — one
+of them after `empty()` was wired to a method named `empty` and `->get()` to an unrelated
+class. A false edge is worse than a missing one, because a missing edge looks missing.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Iterable
+
+from ..ports import CallSite, CallTarget, Confidence, Resolution
+from ..syntax import nodes
+from ..syntax.class_index import DECLARED, MAGIC, NOT_DECLARED, ClassIndex, index_from_facts
+from ..syntax.collectors import REASSIGNED_LOCAL, UNION_TYPE
+from ..syntax.facts import FileFacts
+from ..syntax.file_scan import scan_source
+from ..syntax.names import NameResolver
+
+
+class Reason:
+    """The fixed vocabulary of refusals.
+
+    Constants rather than literals at the call sites: these counts are the work list for the
+    next version of this package, and a histogram of near-duplicate free-text strings is not a
+    work list.
+    """
+
+    DYNAMIC_NAME = "dynamic-name"
+    CHAINED_CALL = "chained-call"
+    NESTED_PROPERTY = "nested-property-access"
+    STATIC_BINDING = "static-binding"
+    INDIRECT_DISPATCH = "indirect-dispatch"
+    REASSIGNED_LOCAL = REASSIGNED_LOCAL
+    UNION_TYPE = UNION_TYPE
+    UNSUPPORTED_RECEIVER = "unsupported-receiver"
+    UNKNOWN_RECEIVER_TYPE = "unknown-receiver-type"
+    UNLOCATABLE_SITE = "unlocatable-call-site"
+    UNREADABLE_FILE = "unreadable-file"
+    AMBIGUOUS_SITE = "ambiguous-call-site"
+    CALL_SITE_NOT_FOUND = "call-site-not-found"
+    METHOD_NOT_DECLARED = "method-not-declared"
+    AMBIGUOUS_INTERSECTION = "ambiguous-intersection"
+    DYNAMIC_SCOPE = "dynamic-scope"
+    UNRESOLVABLE_SCOPE = "unresolvable-scope"
+    ANONYMOUS_CLASS_SCOPE = "anonymous-class-scope"
+
+
+# Types whose methods dispatch somewhere else at runtime. Resolving `$container->get('x')` to
+# `ContainerInterface::get` is true and useless: the edge that matters goes to whatever the
+# container returns, which is not written at the call site. Reflection is the same shape.
+DISPATCH_BARRIER_TYPES = frozenset(
+    {
+        "Psr\\Container\\ContainerInterface",
+        "Symfony\\Component\\DependencyInjection\\ContainerInterface",
+        "Symfony\\Component\\DependencyInjection\\Container",
+        "ReflectionClass",
+        "ReflectionMethod",
+        "ReflectionProperty",
+        "ReflectionFunction",
+        "ReflectionObject",
+        "Closure",
+    }
+)
+
+# Methods that are a dispatch mechanism rather than a destination.
+DISPATCH_BARRIER_METHODS = frozenset({"__call", "__callStatic", "__invoke", "__get", "__set"})
+
+_IDENTIFIER = re.compile(r"^[A-Za-z_\x80-\xff][A-Za-z0-9_\x80-\xff]*$")
+_THIS_PROPERTY = re.compile(r"^\$this\s*->\s*([A-Za-z_\x80-\xff][A-Za-z0-9_\x80-\xff]*)$")
+_LOCAL = re.compile(r"^\$([A-Za-z_\x80-\xff][A-Za-z0-9_\x80-\xff]*)$")
+# `L6` is graphify's own shape (engine.py:6402); the bare number covers the rest.
+_LEADING_LINE = re.compile(r"\s*L?(\d+)")
+
+
+class TreeSitterSource:
+    """Resolves `$this->prop->method()` and `$local->method()` from the file's own text."""
+
+    name = "tree_sitter"
+
+    def available(self, repo_root: str) -> tuple[bool, str]:
+        """True wherever the parser imports. No `vendor/`, so no repository can be too bare."""
+        return nodes.tree_sitter_available()
+
+    def resolve(
+        self,
+        repo_root: str,
+        sites: Iterable[CallSite],
+        corpus: Iterable[str] | None = None,
+    ) -> Resolution:
+        resolution = Resolution(targets=[], unresolved={})
+        # One cache for the whole call, keyed by real path, so a file that is both a corpus
+        # entry and a site file is parsed once.
+        cache: dict[str, FileFacts | None] = {}
+        # Built before any site is answered, because "this class declares no such method" is
+        # only honest once the files that could have declared it have been read. The same
+        # cache serves the sites below, so each file is parsed once.
+        by_file: dict[str, list[CallSite]] = {}
+        for site in sites:
+            by_file.setdefault(site.source_file, []).append(site)
+        index = self._corpus_index(repo_root, list(by_file), corpus, cache)
+
+        for path, file_sites in by_file.items():
+            facts = self._facts(repo_root, path, cache)
+            if facts is None:
+                _count(resolution, Reason.UNREADABLE_FILE, len(file_sites))
+                continue
+            resolution.files_seen += 1
+            for site in file_sites:
+                target, reason = self._resolve_site(site, facts, index)
+                if target is not None:
+                    resolution.targets.append(target)
+                else:
+                    _count(resolution, reason, 1)
+        return resolution
+
+    def _corpus_index(
+        self,
+        repo_root: str,
+        site_paths,
+        corpus: Iterable[str] | None,
+        cache: dict[str, FileFacts | None],
+    ) -> ClassIndex:
+        """Declarations from every file this run may read, which is what it can disprove with.
+
+        `corpus` is what the caller parsed for the build; without it only the files carrying
+        call sites are read. The difference is not cosmetic: a leaf service class holds no
+        unresolved call of its own, so it never appears among the sites, and without a corpus
+        whether its methods are known depends on whether some unrelated file happens to have a
+        site in it. The site files are always included, because a site file is readable by
+        definition and a caller may pass a corpus that does not list it.
+
+        Never a filesystem walk. The set is bounded by what the build already parsed, so this
+        reads nothing the build did not.
+        """
+        index = ClassIndex()
+        paths = list(site_paths)
+        if corpus is not None:
+            paths.extend(corpus)
+        for path in paths:
+            facts = self._facts(repo_root, path, cache)
+            if facts is not None:
+                index_from_facts(index, facts)
+        return index
+
+    def _facts(
+        self, repo_root: str, path: str, cache: dict[str, FileFacts | None]
+    ) -> FileFacts | None:
+        full = path if os.path.isabs(path) else os.path.join(repo_root, path)
+        full = os.path.realpath(full)
+        if full in cache:
+            return cache[full]
+        try:
+            with open(full, "rb") as handle:
+                source = handle.read()
+        except OSError:
+            cache[full] = None
+            return None
+        facts = scan_source(path, source)
+        cache[full] = facts
+        return facts
+
+    def _resolve_site(
+        self, site: CallSite, facts: FileFacts, index: ClassIndex
+    ) -> tuple[CallTarget | None, str]:
+        method = (site.method or "").strip()
+        if not _IDENTIFIER.match(method):
+            return None, Reason.DYNAMIC_NAME
+        if method in DISPATCH_BARRIER_METHODS:
+            return None, Reason.INDIRECT_DISPATCH
+
+        line = line_of(site.source_location)
+        if line is None:
+            return None, Reason.UNLOCATABLE_SITE
+        klass = facts.class_at(line)
+        if klass is None:
+            return None, Reason.UNLOCATABLE_SITE
+        if facts.in_anonymous_class(line):
+            # `class_at` finds the enclosing class, but `$this->emails` here is a property of
+            # the `new class { ... }` the walker read nothing of, so the enclosing class's
+            # `$emails` would be the wrong one.
+            return None, Reason.ANONYMOUS_CLASS_SCOPE
+
+        resolved, reason = self._receiver_target(site, facts, klass, line, method, index)
+        if resolved is None and facts.calls.receiver_for(line, method)[1] == 0:
+            # Only a line with no member call of this name can be a scoped call. The resolver
+            # hands a scoped site its scope text (`self`, `Helper`) as the receiver, which the
+            # member path refuses and the scoped path answers. A member call that is there is
+            # answered by the member path alone: `Other::foo()` sitting in the argument list
+            # of `$x->foo(...)` must not stand in for a receiver that could not be typed.
+            resolved, reason = self._scoped_target(facts, klass, line, method)
+        if resolved is None:
+            return None, reason
+        class_fqn, confidence, via = resolved
+
+        if class_fqn in DISPATCH_BARRIER_TYPES:
+            return None, Reason.INDIRECT_DISPATCH
+
+        # The receiver's type is only half a target. Emitting the call site's method name
+        # without checking the class declares it is how a resolver invents a member.
+        #
+        # Only a class this package actually parsed can be disproved. When the class was never
+        # read, the target is emitted: `GraphNodeIndex.method_node` looks the method up across
+        # the whole corpus and adds no edge when it finds none, so an unprovable target dies
+        # there anyway. Refusing here would drop real edges to buy nothing.
+        verdict = index.declares(class_fqn, method)
+        if verdict == MAGIC:
+            return None, Reason.INDIRECT_DISPATCH
+        if verdict == NOT_DECLARED:
+            return None, Reason.METHOD_NOT_DECLARED
+
+        # First-class callable syntax, `$this->emails->reminderSubmitWeek(...)`, produces a
+        # Closure rather than invoking anything, so this edge is arguably a reference and not a
+        # call. It is emitted as a call deliberately: the question the graph is built to answer
+        # is "what breaks if I change this method", and for that the edge is worth more than
+        # its absence. The grammar makes no distinction here, so nothing downstream can tell
+        # the two apart — which is the cost of the choice, recorded rather than hidden.
+        return CallTarget(
+            site=site,
+            class_fqn=class_fqn,
+            method=method,
+            confidence=confidence,
+            via=f"{TreeSitterSource.name}:{via}",
+        ), ""
+
+    def _receiver_target(self, site, facts, klass, line, method, index):
+        """`$this->prop->m()` and `$local->m()`, as (class, confidence, via) or (None, reason)."""
+        receiver, reason = self._receiver(site, facts, line, method)
+        if receiver is None:
+            return None, reason
+        kind, key, reason = classify_receiver(receiver)
+        if kind is None:
+            return None, reason
+
+        if kind == "self":
+            # `$this->m()` is provable when `m` is declared anywhere in an ancestry this run
+            # actually read — the class itself, a trait it uses, a parent in a file with call
+            # sites. When the owner is in an unread file the answer is not known, and naming
+            # this class anyway would put the wrong class on a real edge.
+            verdict = index.declares(klass.fqn, method)
+            if verdict == DECLARED:
+                return (klass.fqn, Confidence.EXTRACTED, "self-receiver"), ""
+            if verdict == MAGIC:
+                return None, Reason.INDIRECT_DISPATCH
+            return None, Reason.UNSUPPORTED_RECEIVER
+
+        if kind == "property":
+            fact, refusal = index.property_fact(klass.fqn, key)
+            if refusal:
+                return None, refusal
+        else:
+            scope = klass.method_at(line)
+            if scope is None:
+                return None, Reason.UNLOCATABLE_SITE
+            if key in scope.refusals:
+                return None, scope.refusals[key]
+            fact = scope.locals.get(key)
+
+        if fact is None:
+            # The type is not in this file. Inherited from a parent class in another file, set
+            # by a container, or simply untyped — and any of those could be a class with this
+            # short name anywhere in the corpus, which is precisely the match not to make.
+            return None, Reason.UNKNOWN_RECEIVER_TYPE
+        if fact.is_intersection:
+            return self._intersection_target(fact, method, index)
+        return (fact.fqn, fact.confidence, fact.via), ""
+
+    def _intersection_target(self, fact, method: str, index: ClassIndex):
+        """`A&B`: one object that is both, so the constituent declaring the method is the target.
+
+        This is why an intersection is not a union. With `A|B` the object is one of two things
+        and there are two candidate targets, so there is nothing to choose between. With `A&B`
+        there is one object, and a method declared in only one constituent names it without
+        ambiguity.
+        """
+        verdicts = {member: index.declares(member, method) for member in fact.members}
+        declaring = [m for m, v in verdicts.items() if v == DECLARED]
+        if len(declaring) == 1:
+            return (declaring[0], Confidence.EXTRACTED, f"{fact.via}+intersection"), ""
+        if len(declaring) > 1:
+            # One call, one object, two declarations. Which body runs depends on the concrete
+            # class, which the type does not name, so the graph cannot say.
+            return None, Reason.AMBIGUOUS_INTERSECTION
+        if any(v == MAGIC for v in verdicts.values()):
+            return None, Reason.INDIRECT_DISPATCH
+        if all(v == NOT_DECLARED for v in verdicts.values()):
+            return None, Reason.METHOD_NOT_DECLARED
+        # A constituent sits in a file this run never read, so the method may well be there.
+        return None, Reason.UNKNOWN_RECEIVER_TYPE
+
+    def _scoped_target(self, facts, klass, line, method):
+        """`self::`, `parent::`, `static::` and `Class::`, each on its own terms.
+
+        graphify records the scope text as the callee for these (`engine.py:6147-6152`), so the
+        method name is only in the source and the line is the only way back to it.
+        """
+        scoped, matches = facts.calls.scope_for(line, method)
+        if scoped is None:
+            return None, Reason.AMBIGUOUS_SITE if matches > 1 else Reason.CALL_SITE_NOT_FOUND
+        if scoped.is_dynamic:
+            # `$class::m()`: the class is a runtime value, and no name is written to resolve.
+            return None, Reason.DYNAMIC_SCOPE
+
+        written = scoped.scope
+        if written == "self":
+            return (klass.fqn, Confidence.EXTRACTED, "self-scope"), ""
+        if written == "parent":
+            if not klass.parent:
+                return None, Reason.UNRESOLVABLE_SCOPE
+            # The parent's body is in another file, so whether it declares the method is not a
+            # question this file can answer; the class identity is what is proved here.
+            return (klass.parent, Confidence.EXTRACTED, "parent-scope"), ""
+        if written == "static":
+            # Late static binding names the lexical class, but the runtime class may be a
+            # subclass that overrides the method, so this edge points at a declaration that
+            # may not be the one that executes. INFERRED says so. Subclasses are deliberately
+            # not enumerated: that is a closed-world assumption nothing here supports, and it
+            # turns one honest edge into one per subclass, all but one of them wrong.
+            return (klass.fqn, Confidence.INFERRED, "static-binding"), ""
+
+        resolver = NameResolver(namespace=facts.namespace, imports=facts.imports)
+        target = resolver.resolve(written)
+        if not target:
+            return None, Reason.UNRESOLVABLE_SCOPE
+        return (target, Confidence.EXTRACTED, "class-scope"), ""
+
+    def _receiver(
+        self, site: CallSite, facts: FileFacts, line: int, method: str
+    ) -> tuple[str | None, str]:
+        """The receiver expression for this site, read from the tree when the site has none.
+
+        graphify's PHP branch never fills the field — `extractors/engine.py:6152-6157` sets
+        `is_member_call` and the callee name and stops, so `engine.py:6403` writes
+        `"receiver": swift_receiver or member_receiver` as None for every PHP site. A source
+        that trusted the field would resolve nothing in production while passing every test
+        that supplies one.
+
+        A non-empty `site.receiver` still wins, so a later graphify that does fill it is used
+        rather than second-guessed.
+        """
+        given = (site.receiver or "").strip()
+        if given:
+            return given, ""
+        found, matches = facts.calls.receiver_for(line, method)
+        if found is not None:
+            return found, ""
+        if matches > 1:
+            # `$a->run(); $b->run();` on one line: two receivers, two classes, and the
+            # location is not precise enough to say which. Picking either is a coin toss.
+            return None, Reason.AMBIGUOUS_SITE
+        return None, Reason.CALL_SITE_NOT_FOUND
+
+
+def classify_receiver(receiver: str) -> tuple[str | None, str, str]:
+    """Read a receiver expression as ("property"|"local", name, "") or (None, "", reason).
+
+    Ordered so that the refusals are decided before any shape is accepted. A receiver that
+    almost matches `$this->prop` is not a `$this->prop`, and treating it as one is how an
+    unrelated class ends up on the other end of an edge.
+    """
+    text = (receiver or "").strip()
+    if not text:
+        return None, "", Reason.UNSUPPORTED_RECEIVER
+    if "(" in text:
+        # `$this->a->b()` as a receiver means the target is the return type of `b()`, which
+        # this version does not track.
+        return None, "", Reason.CHAINED_CALL
+    if text == "static" or text.startswith("static::"):
+        # Late static binding names the declaration, not the runtime class.
+        return None, "", Reason.STATIC_BINDING
+    if "::" in text:
+        return None, "", Reason.UNSUPPORTED_RECEIVER
+    if "->" in text:
+        head, _, rest = text.partition("->")
+        if head.strip() != "$this":
+            return None, "", Reason.NESTED_PROPERTY
+        if "->" in rest:
+            return None, "", Reason.NESTED_PROPERTY
+        if rest.strip().startswith("$") or rest.strip().startswith("{"):
+            return None, "", Reason.DYNAMIC_NAME
+        match = _THIS_PROPERTY.match(text)
+        if match is None:
+            return None, "", Reason.UNSUPPORTED_RECEIVER
+        return "property", match.group(1), ""
+    if text.startswith("$$"):
+        return None, "", Reason.DYNAMIC_NAME
+    match = _LOCAL.match(text)
+    if match is None:
+        return None, "", Reason.UNSUPPORTED_RECEIVER
+    if match.group(1) == "this":
+        return "self", "", ""
+    return "local", match.group(1), ""
+
+
+def line_of(location: str) -> int | None:
+    """The 1-based line from whatever graphify put in `source_location`.
+
+    graphify writes `L<line>` — `extractors/engine.py:6402` builds it as
+    `f"L{node.start_point[0] + 1}"` — so the `L` prefix is the shape that actually arrives and
+    is stripped here. The others (`12`, `12:4`, `path.php:12`, `12-30`) are tolerated because
+    the field is a plain string in `ports` and this package does not own its format.
+
+    The first number-leading segment wins, so `12:4` yields the line rather than the column,
+    and path segments are skipped rather than mined for digits.
+    """
+    if not location:
+        return None
+    for part in location.split(":"):
+        if "/" in part or "." in part:
+            continue
+        match = _LEADING_LINE.match(part)
+        if match:
+            return int(match.group(1))
+    return None
+
+
+def _count(resolution: Resolution, reason: str, count: int) -> None:
+    resolution.unresolved[reason] = resolution.unresolved.get(reason, 0) + count

graphify_php/status.py

@@ -0,0 +1,136 @@
+"""Build-scoped status record for every resolver this package registers.
+
+Why this exists before any resolution code. graphify runs registered resolvers like this:
+
+    try:
+        resolver.resolve(per_file, all_nodes, all_edges)
+    except Exception as exc:
+        _LOG.warning("%s resolution failed, skipping: %s", resolver.name, exc)
+
+A resolver that raises is skipped, the build succeeds, and the graph is published without its
+edges. A resolver that is never registered — because the seam moved in an upgrade — behaves
+identically. Both failures look exactly like a codebase that happens to have few calls, which
+is the shape of the defect this package exists to fix, so the failure would be invisible
+precisely where it matters.
+
+The log line is not a usable signal: it goes to graphify's logger, not to whatever runs the
+build. So each resolver writes its own record here, and `graphify-php-build` refuses to publish
+a graph whose expected resolvers did not complete.
+
+The record separates three outcomes on purpose:
+
+- `completed` — ran, and the counters say what it did.
+- `skipped` — ran and decided there was nothing to do, with a reason. A repository with no
+  PHPStan in `vendor/` is a normal skip, not a fault.
+- `failed` — raised. The build must not publish.
+
+Counters are per resolver and deliberately include the denominator (`eligible`), because
+"resolved 400 calls" means nothing without "out of how many", and a regression that halves
+coverage keeps producing a large, healthy-looking number.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import asdict, dataclass, field
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _package_version
+from pathlib import Path
+
+# The build writes here; the wrapper reads it. An environment variable rather than a fixed
+# path because one machine indexes ~20 repositories and their builds must not share a file.
+STATUS_PATH_ENV = "GRAPHIFY_PHP_STATUS"
+DEFAULT_STATUS_PATH = "graphify-out/.graphify-php-status.json"
+
+# Distribution names, not import names: graphify is published on PyPI as `graphifyy`.
+PRODUCER_NAME = "graphify-php"
+GRAPHIFY_DISTRIBUTION = "graphifyy"
+
+
+def installed_version(distribution: str) -> str:
+    """Installed version of `distribution`, or "unknown" when it carries no metadata."""
+    try:
+        return _package_version(distribution)
+    except (PackageNotFoundError, ValueError):
+        return "unknown"
+
+
+@dataclass
+class ResolverStatus:
+    name: str
+    state: str = "started"  # started | completed | skipped | failed
+    reason: str = ""  # why it skipped, or the exception text
+    files_seen: int = 0
+    eligible_sites: int = 0  # member calls this resolver could have resolved
+    resolved_sites: int = 0  # ... and did
+    edges_added: int = 0
+    # Target records bound to an external stub node instead of being dropped as
+    # `target_not_in_graph`, and the stub nodes and edges that produced. Zero with the flag off.
+    external_stubbed: int = 0
+    stub_nodes_added: int = 0
+    stub_edges_added: int = 0
+    # reason -> count. The unit differs by reason: source reasons count sites, `probe:` reasons
+    # count candidate names, `scoped_method_*` count scoped groups, and the graph-lookup reasons
+    # (`target_not_in_graph`, `self_call`) count target records, so a two-arm site can appear twice.
+    unresolved: dict = field(default_factory=dict)
+    started_at: float = field(default_factory=time.time)
+    finished_at: float = 0.0
+
+    def unresolvable(self, reason: str, count: int = 1) -> None:
+        """Record a call site left alone, and why.
+
+        Reasons are a fixed vocabulary in the resolvers, never free text: they are the work
+        list for the next version, and a histogram of unique strings is not a work list.
+        """
+        self.unresolved[reason] = self.unresolved.get(reason, 0) + count
+
+
+def status_path() -> Path:
+    return Path(os.environ.get(STATUS_PATH_ENV) or DEFAULT_STATUS_PATH)
+
+
+def write(records: list[ResolverStatus]) -> Path:
+    """Write the build record, merging with anything already there.
+
+    Merging rather than overwriting because resolvers run one after another and each writes as
+    it finishes; a crash after the second of three still leaves the first two on disk, which is
+    what makes the failure diagnosable.
+    """
+    path = status_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    existing: dict[str, dict] = {}
+    if path.exists():
+        # This runs inside the resolver's `finally`. A file that is not a record — a list,
+        # a row without a name — must not raise here and replace the resolver's own exception.
+        try:
+            previous = json.loads(path.read_text())
+            rows = previous.get("resolvers", []) if isinstance(previous, dict) else []
+            existing = {
+                r["name"]: r for r in rows if isinstance(r, dict) and isinstance(r.get("name"), str)
+            }
+        except (ValueError, OSError, TypeError, AttributeError, KeyError):
+            existing = {}
+    for record in records:
+        existing[record.name] = asdict(record)
+    payload = {
+        "schema": 1,
+        "written_at": time.time(),
+        # Which build of this package wrote the record, so a reader can tell an upgrade apart.
+        "producer": {"name": PRODUCER_NAME, "version": installed_version(PRODUCER_NAME)},
+        "resolvers": list(existing.values()),
+    }
+    path.write_text(json.dumps(payload, indent=2))
+    return path
+
+
+def read() -> dict:
+    path = status_path()
+    if not path.exists():
+        return {}
+    try:
+        record = json.loads(path.read_text())
+    except (ValueError, OSError):
+        return {}
+    return record if isinstance(record, dict) else {}