graphify-php 0.0.5__py3-none-any.whl

graphify_php/resolver.py

@@ -0,0 +1,519 @@
+"""The resolution pass graphify runs, expressed against `ports` alone.
+
+This module imports nothing from `syntax` or `sources`. It is handed a list of `CallTargetSource`
+and asks them in order; adding a PHPStan source, a language server or an LSIF index later is a
+change to the factory that assembles that list, not to anything here.
+
+Precedence is the whole reason the list is ordered. A precise source that ran the project's own
+type engine and a parser that read a declaration will both answer `$this->emails`, and they will
+not always agree. The first source that proves a site owns it, and that site is never offered to
+the next one — so a later, weaker source can add reach but can never overwrite a stronger
+source's answer.
+
+Every path through this function ends in a status record, including the exception path, because
+graphify's driver catches whatever escapes:
+
+    except Exception as exc:
+        _LOG.warning("%s resolution failed, skipping: %s", resolver.name, exc)
+
+The warning goes to graphify's logger. Nothing that runs the build reads it, so without the
+record written below a total failure of this pass and a PHP codebase with few calls produce the
+same artifact.
+"""
+
+from __future__ import annotations
+
+import inspect
+import os
+import re
+import time
+from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass
+
+from . import status
+from .ports import CallSite, CallTarget, CallTargetSource, EdgeSink, NodeIndex, ScopeIndex
+
+RESOLVER_NAME = "php_member_calls"
+PHP_SUFFIXES = frozenset({".php"})
+
+# "1" mints a body-less `external` node per vendor class a proven call targets, instead of
+# dropping the record. Off by default: graphify core refuses stubs for `calls` because they
+# become hub nodes; this plugin opts in per build.
+EXTERNAL_STUBS_ENV = "GRAPHIFY_PHP_EXTERNAL_STUBS"
+
+# The unresolved-reason vocabulary this module owns. Reasons a source reports are prefixed with
+# that source's name, so the two namespaces cannot collide and the histogram stays a work list.
+REASON_NO_SOURCE = "no_source_resolved"
+REASON_NOT_IN_GRAPH = "target_not_in_graph"
+REASON_SELF_CALL = "self_call"
+REASON_SCOPE_NOT_RECOVERED = "scoped_method_not_recovered"
+REASON_SCOPE_AMBIGUOUS = "scoped_method_ambiguous"
+
+_IDENTIFIER = re.compile(r"^[A-Za-z_\\][A-Za-z0-9_\\]*$")
+
+
+def is_vendor_file(path: str, repo_root: str) -> bool:
+    """Whether `path` sits under the repository's `vendor/` directory.
+
+    Only the first segment under the root counts. A project class the build left out (a
+    `Tests\\` class under `.graphifyignore`) is still project code and gets no stub for it.
+    """
+    if not path:
+        return False
+    root = os.path.abspath(repo_root)
+    relative = os.path.relpath(os.path.join(root, path), root)
+    return relative.replace("\\", "/").split("/", 1)[0] == "vendor"
+
+
+@dataclass
+class ScopedGroup:
+    """One scoped call site, and the candidate method names offered on its behalf.
+
+    A group is ONE eligible site however many candidates it takes to find its method, which is
+    why the candidates are accounted separately: counting nine refused probes as nine failures
+    would bury the real unresolved reasons under noise of our own making.
+    """
+
+    scope: str
+    candidates: list[CallSite]
+
+
+def collect_sites(per_file: Sequence[dict]) -> list[CallSite]:
+    """Every `$receiver->method()` graphify left unresolved, as `CallSite`.
+
+    graphify's PHP extractor sets `is_member_call` and the callee name but leaves `receiver`
+    unset (extractors/engine.py, the `tree_sitter_php` branch of the call walk: unlike the C#,
+    Java and C++ branches it never assigns `member_receiver`). The field is carried through
+    when it is there and left empty when it is not; a source that needs the receiver expression
+    re-reads it from `source_file` at `source_location`, which it must parse anyway.
+    """
+    sites: list[CallSite] = []
+    for result in per_file:
+        for raw in result.get("raw_calls", []) or []:
+            if not raw.get("is_member_call"):
+                continue
+            caller, callee = raw.get("caller_nid"), raw.get("callee")
+            source_file = raw.get("source_file") or ""
+            if not caller or not callee or not source_file.endswith(".php"):
+                continue
+            sites.append(
+                CallSite(
+                    caller_nid=caller,
+                    receiver=raw.get("receiver") or "",
+                    method=callee,
+                    source_file=source_file,
+                    source_location=raw.get("source_location") or "",
+                )
+            )
+    return sites
+
+
+def collect_scoped_groups(per_file: Sequence[dict], scopes: ScopeIndex) -> list[ScopedGroup]:
+    """Scoped calls — `self::`, `parent::`, `static::`, `Class::` — as candidate sites.
+
+    graphify records all four with `is_member_call` false and the SCOPE as the callee, the same
+    shape it uses for an ordinary function call. They are told apart by asking the graph whether
+    the callee names a class with methods: `trim` and `error_log` name no class, so they produce
+    no candidates and drop out without a hardcoded list of PHP builtins.
+    """
+    groups: list[ScopedGroup] = []
+    for result in per_file:
+        for raw in result.get("raw_calls", []) or []:
+            if raw.get("is_member_call"):
+                continue
+            caller, scope = raw.get("caller_nid"), raw.get("callee")
+            source_file = raw.get("source_file") or ""
+            if not caller or not scope or not source_file.endswith(".php"):
+                continue
+            if not _IDENTIFIER.match(str(scope)):
+                continue
+            candidates = [
+                CallSite(
+                    caller_nid=caller,
+                    receiver=str(scope),
+                    method=name,
+                    source_file=source_file,
+                    source_location=raw.get("source_location") or "",
+                )
+                for name in scopes.scope_methods(caller, str(scope))
+            ]
+            if candidates:
+                groups.append(ScopedGroup(scope=str(scope), candidates=candidates))
+    return groups
+
+
+def collect_corpus(per_file: Sequence[dict]) -> list[str]:
+    """Every PHP file graphify parsed, as the corpus a source may read declarations from.
+
+    A leaf service class has nothing unresolved in it, so it never appears among the sites and
+    a source indexing only those files cannot tell whether it declares the method being called
+    on it. The fixture shows the shape exactly: `Emails.php` contributes nodes but no
+    `raw_calls`, and it is the class every resolved call points at.
+
+    Bounded by what the build already parsed, never by a filesystem walk: a walk to the nearest
+    `composer.json` measured 4.7 s against 0.16 s and read paths outside the build.
+
+    Paths are taken verbatim from the same dicts the sites come from. During a build they are
+    ABSOLUTE and only relativized at publish time, so rebuilding them from a root here would
+    hand the source the same file under two names and make it parse it twice.
+    """
+    seen: set[str] = set()
+    for result in per_file:
+        for group in ("nodes", "raw_calls"):
+            for item in result.get(group, []) or []:
+                path = item.get("source_file") or ""
+                if path.endswith(".php"):
+                    seen.add(path)
+    return sorted(seen)
+
+
+# Whether a source's `resolve` takes `corpus`, cached per source class. The shim exists because
+# `corpus` was added to `CallTargetSource` after the first sources were written, and a source
+# built against the old signature is still a valid implementation of the protocol. Reading the
+# signature rather than catching `TypeError` on the call: a `TypeError` raised from inside a
+# source's own body would otherwise be misread as "this source is old" and silently retried
+# without the corpus.
+_ACCEPTS_CORPUS: dict[type, bool] = {}
+
+
+def _resolve_with(
+    source: CallTargetSource,
+    repo_root: str,
+    sites: Sequence[CallSite],
+    corpus: Sequence[str] | None,
+):
+    kind = type(source)
+    accepts = _ACCEPTS_CORPUS.get(kind)
+    if accepts is None:
+        try:
+            params = inspect.signature(source.resolve).parameters
+        except (TypeError, ValueError):
+            accepts = False
+        else:
+            accepts = "corpus" in params or any(
+                p.kind is inspect.Parameter.VAR_KEYWORD for p in params.values()
+            )
+        _ACCEPTS_CORPUS[kind] = accepts
+    if corpus is not None and accepts:
+        return source.resolve(repo_root, sites, corpus)
+    return source.resolve(repo_root, sites)
+
+
+def _ask_sources(
+    sources: Sequence[CallTargetSource],
+    repo_root: str,
+    sites: Sequence[CallSite],
+    record: status.ResolverStatus,
+    reason_prefix: str = "",
+    count_unclaimed: bool = True,
+    corpus: Sequence[str] | None = None,
+) -> list[CallTarget]:
+    """Offer each site to the sources in order, stopping at the first that proves it."""
+    pending: list[CallSite] = list(sites)
+    targets: list[CallTarget] = []
+    for source in sources:
+        if not pending:
+            break
+        resolution = _resolve_with(source, repo_root, pending, corpus)
+        record.files_seen = max(record.files_seen, resolution.files_seen)
+        for reason, count in (resolution.unresolved or {}).items():
+            record.unresolvable(f"{reason_prefix}{source.name}:{reason}", count)
+
+        # A site keeps every target a source proved for it: a `Emails|Cache` receiver has two
+        # real arms, and one arm alone is a wrong answer. Only an exact repeat is dropped.
+        claimed: set[CallSite] = set()
+        seen: set[tuple[CallSite, str, str]] = set()
+        for target in resolution.targets:
+            key = (target.site, target.class_fqn, target.method)
+            if key in seen:
+                continue
+            seen.add(key)
+            claimed.add(target.site)
+            targets.append(target)
+        pending = [site for site in pending if site not in claimed]
+
+    if pending and count_unclaimed:
+        record.unresolvable(REASON_NO_SOURCE, len(pending))
+    return targets
+
+
+def _resolve_groups(
+    groups: Sequence[ScopedGroup],
+    sources: Sequence[CallTargetSource],
+    repo_root: str,
+    record: status.ResolverStatus,
+    corpus: Sequence[str] | None = None,
+) -> list[CallTarget]:
+    """Turn each group's candidates into at most one target for that call site.
+
+    A separate pass rather than one flat list with the member sites, so the probes' refusals
+    land under their own `probe:` prefix. Mixed in, a class with nine other methods would report
+    nine `call-site-not-found` against every scoped call and make the histogram useless.
+    """
+    if not groups:
+        return []
+    probes = [site for group in groups for site in group.candidates]
+    found: dict[CallSite, list[CallTarget]] = {}
+    for target in _ask_sources(
+        sources,
+        repo_root,
+        probes,
+        record,
+        reason_prefix="probe:",
+        count_unclaimed=False,
+        corpus=corpus,
+    ):
+        found.setdefault(target.site, []).append(target)
+    targets: list[CallTarget] = []
+    for group in groups:
+        hits = [target for site in group.candidates for target in found.get(site, ())]
+        if len(hits) == 1:
+            targets.append(hits[0])
+        elif not hits:
+            record.unresolvable(REASON_SCOPE_NOT_RECOVERED)
+        else:
+            # Two candidate names verified against one line, or one name with two targets.
+            # Either way nothing here says which body is called, so the site gets no edge.
+            record.unresolvable(REASON_SCOPE_AMBIGUOUS)
+    return targets
+
+
+def _write_edges(
+    targets: Iterable[CallTarget],
+    index: NodeIndex,
+    sink: EdgeSink,
+    record: status.ResolverStatus,
+    stubs=None,
+    repo_root: str = ".",
+) -> None:
+    # `ports.NodeIndex` takes no caller, so an index that can apply the caller's own visibility
+    # offers a wider call and is used when present. The report asks for the caller to be added
+    # to the port; until then this keeps `ports` untouched and fake indexes in tests working.
+    origin_aware = getattr(index, "method_node_for", None)
+    # Counted per target record, not per site: a union site with one arm missing from the graph
+    # still gets its other arm, and the histogram says how many records were lost.
+    for target in targets:
+        callee_nid = (
+            origin_aware(target.site.caller_nid, target.class_fqn, target.method)
+            if callable(origin_aware)
+            else index.method_node(target.class_fqn, target.method)
+        )
+        if callee_nid is None:
+            # Only a class proven to live under `vendor/` gets a stub. Project code the build
+            # excluded is still project code, and a stub for it would shadow the real class.
+            if stubs is not None and is_vendor_file(target.declaring_file, repo_root):
+                stubs.add_call(target.site.caller_nid, stubs.node_for(target.class_fqn), target)
+                record.external_stubbed += 1
+                continue
+            # `NodeIndex` answers one question, so a missing class and a missing method arrive
+            # here indistinguishable. Widening the port to tell them apart would tie this
+            # package to graphify's node schema, which is the part most likely to move.
+            record.unresolvable(REASON_NOT_IN_GRAPH)
+            continue
+        if callee_nid == target.site.caller_nid:
+            record.unresolvable(REASON_SELF_CALL)
+            continue
+        sink.add_call(target.site.caller_nid, callee_nid, target)
+
+
+def run(
+    per_file: Sequence[dict],
+    all_nodes: list[dict],
+    all_edges: list[dict],
+    *,
+    sources: Sequence[CallTargetSource] | Callable[[str], Sequence[CallTargetSource]],
+    repo_root: str = ".",
+    index: NodeIndex | None = None,
+    sink: EdgeSink | None = None,
+    scopes: ScopeIndex | None = None,
+    stubs=None,
+) -> status.ResolverStatus:
+    """Resolve PHP member calls into `calls` edges, and record what happened either way.
+
+    `sources` may be a factory taking the repository root. It is called in here, inside the
+    record's own try, so a factory that raises leaves a `failed` record and not silence.
+    """
+    record = status.ResolverStatus(name=RESOLVER_NAME)
+    try:
+        if callable(sources):
+            sources = sources(repo_root)
+        if index is None or sink is None:
+            from .graph_adapter import GraphEdgeSink, GraphNodeIndex
+
+            built = GraphNodeIndex(all_nodes, all_edges)
+            index = index or built
+            sink = sink or GraphEdgeSink(all_edges, built)
+        if stubs is None and os.environ.get(EXTERNAL_STUBS_ENV) == "1":
+            from .graph_adapter import GraphStubSink
+
+            stubs = GraphStubSink(all_nodes, all_edges)
+        if scopes is None and isinstance(index, ScopeIndex):
+            scopes = index
+
+        unavailable: list[str] = []
+        usable: list[CallTargetSource] = []
+        for source in sources:
+            ok, reason = source.available(repo_root)
+            if ok:
+                usable.append(source)
+            else:
+                unavailable.append(f"{source.name}: {reason}")
+
+        corpus = collect_corpus(per_file)
+        record.files_seen = len(corpus)
+        if not usable:
+            # A repository with no PHPStan in `vendor/` is the normal case, not a fault: the
+            # build publishes, and the record says which layer was missing.
+            record.state = "skipped"
+            record.reason = "; ".join(unavailable) or "no call target sources configured"
+            return record
+
+        sites = collect_sites(per_file)
+        groups = collect_scoped_groups(per_file, scopes) if scopes is not None else []
+        record.eligible_sites = len(sites) + len(groups)
+        targets = _ask_sources(usable, repo_root, sites, record, corpus=corpus)
+        targets += _resolve_groups(groups, usable, repo_root, record, corpus=corpus)
+        record.resolved_sites = len({t.site for t in targets})
+        _write_edges(targets, index, sink, record, stubs=stubs, repo_root=repo_root)
+        record.edges_added = getattr(sink, "added", record.resolved_sites)
+        if stubs is not None:
+            record.stub_nodes_added = stubs.nodes_added
+            record.stub_edges_added = stubs.edges_added
+        record.state = "completed"
+        if unavailable:
+            record.reason = "; ".join(unavailable)
+        return record
+    except Exception as exc:
+        record.state = "failed"
+        record.reason = f"{type(exc).__name__}: {exc}"
+        raise
+    finally:
+        record.finished_at = time.time()
+        status.write([record])
+
+
+def make_resolver(
+    sources_factory: Callable[[str], Sequence[CallTargetSource]], repo_root: str = "."
+):
+    """Wrap `run` in the `(per_file, all_nodes, all_edges) -> None` shape graphify calls.
+
+    The factory is called at resolution time, not at registration time: registering happens at
+    import, when the working directory and the repository under build are not yet settled.
+    """
+
+    def resolve(per_file, all_nodes, all_edges) -> None:
+        run(per_file, all_nodes, all_edges, sources=sources_factory, repo_root=repo_root)
+
+    resolve.__name__ = RESOLVER_NAME
+    return resolve
+
+
+RESOLVER_NAME_ROUTES = "php_routes"
+
+# Reasons the route pass owns. A source's own reasons arrive prefixed with its name.
+REASON_ROUTE_NO_CONTROLLER = "controller_not_in_graph"
+REASON_ROUTE_NO_PATH = "route_had_no_path"
+
+
+def run_routes(
+    per_file: Sequence[dict],
+    all_nodes: list[dict],
+    all_edges: list[dict],
+    *,
+    sources: Sequence[object] | Callable[[str], Sequence[object]],
+    repo_root: str = ".",
+    index: NodeIndex | None = None,
+    sink=None,
+) -> status.ResolverStatus:
+    """Publish route declarations as nodes, each edged to the controller method that serves it.
+
+    A pass of its own rather than a stage of the member-call one, and with its own record, for
+    the reason this package exists: a layer that silently adds nothing is indistinguishable from
+    a codebase that has none of what it looks for. Routes were extracted and measured for a
+    while before anything connected them to the graph, and every test stayed green throughout,
+    because the tests checked extraction and nothing checked publication.
+    """
+    record = status.ResolverStatus(name=RESOLVER_NAME_ROUTES)
+    try:
+        if callable(sources):
+            # Same contract as `run`: a factory, called inside the try so that it reports.
+            sources = sources(repo_root)
+        if index is None or sink is None:
+            from .graph_adapter import GraphNodeIndex, GraphRouteSink
+
+            index = index or GraphNodeIndex(all_nodes, all_edges)
+            sink = sink or GraphRouteSink(all_nodes, all_edges)
+
+        unavailable: list[str] = []
+        usable: list[object] = []
+        for source in sources:
+            ok, reason = source.available(repo_root)
+            if ok:
+                usable.append(source)
+            else:
+                unavailable.append(f"{source.name}: {reason}")
+
+        # The same corpus the call sources get. A route lives in a controller file, which in
+        # practice always carries call sites too — but "in practice" is not a reason to hand a
+        # source a narrower set than the build parsed.
+        corpus = collect_corpus(per_file)
+        record.files_seen = len(corpus)
+        if not usable:
+            record.state = "skipped"
+            record.reason = "; ".join(unavailable) or "no route sources configured"
+            return record
+
+        declarations = []
+        for source in usable:
+            resolution = source.declarations(repo_root, corpus)
+            record.files_seen = max(record.files_seen, resolution.files_seen)
+            for reason, count in (resolution.unresolved or {}).items():
+                record.unresolvable(f"{source.name}:{reason}", count)
+            declarations.extend(resolution.declarations)
+
+        record.eligible_sites = len(declarations)
+        # The declaration names the file it was read from, and the controller class is declared
+        # in that same file. An index that can use it does; `ports.NodeIndex` cannot express it
+        # yet, so the narrow call stays the fallback.
+        in_file = getattr(index, "method_node_in_file", None)
+        for declaration in declarations:
+            controller_nid = (
+                in_file(
+                    declaration.source_file,
+                    declaration.controller_class,
+                    declaration.controller_method,
+                )
+                if callable(in_file)
+                else index.method_node(declaration.controller_class, declaration.controller_method)
+            )
+            if controller_nid is None:
+                # The node still goes in: the declaration is a fact about this codebase whether
+                # or not the controller method survived extraction, and dropping it would hide
+                # the path. Only the edge is withheld.
+                record.unresolvable(REASON_ROUTE_NO_CONTROLLER)
+            if sink.add_route(declaration, controller_nid) is None:
+                record.unresolvable(REASON_ROUTE_NO_PATH)
+
+        record.resolved_sites = sink.nodes_added
+        record.edges_added = sink.edges_added
+        record.state = "completed"
+        if unavailable:
+            record.reason = "; ".join(unavailable)
+        return record
+    except Exception as exc:
+        record.state = "failed"
+        record.reason = f"{type(exc).__name__}: {exc}"
+        raise
+    finally:
+        record.finished_at = time.time()
+        status.write([record])
+
+
+def make_route_resolver(sources_factory: Callable[[str], Sequence[object]], repo_root: str = "."):
+    """Wrap `run_routes` in the shape graphify's registry calls."""
+
+    def resolve(per_file, all_nodes, all_edges) -> None:
+        run_routes(per_file, all_nodes, all_edges, sources=sources_factory, repo_root=repo_root)
+
+    resolve.__name__ = RESOLVER_NAME_ROUTES
+    return resolve