graphify-php 0.0.5__py3-none-any.whl

graphify_php/php/src/CallGraph/CallEdge.php

@@ -0,0 +1,91 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CallGraph;
+
+/**
+ * One resolved `$receiver->method()`: who called, what was called, where.
+ *
+ * This class is the only place in the PHP extension that knows the wire shape. The collector
+ * runs in analyser workers and the rule runs in the main process, so records cross a
+ * serialisation boundary as plain arrays; keeping the key names here means a shape change is
+ * one edit rather than a hunt through two processes.
+ */
+final class CallEdge
+{
+    public const RECEIVER_CLASS = 'class';
+    public const RECEIVER_INTERFACE = 'interface';
+
+    private function __construct(
+        private readonly string $callerClass,
+        private readonly string $callerMethod,
+        private readonly string $calleeClass,
+        private readonly string $calleeMethod,
+        private readonly string $calleeKind,
+        private readonly int $line,
+        private readonly string $file,
+        private readonly int $callPos,
+        private readonly string $calleeFile,
+    ) {
+    }
+
+    public static function create(
+        string $callerClass,
+        string $callerMethod,
+        string $calleeClass,
+        string $calleeMethod,
+        bool $calleeIsInterface,
+        int $line,
+        string $file = '',
+        int $callPos = -1,
+        string $calleeFile = '',
+    ): self {
+        $kind = match ($calleeIsInterface) {
+            true => self::RECEIVER_INTERFACE,
+            false => self::RECEIVER_CLASS,
+        };
+
+        return new self($callerClass, $callerMethod, $calleeClass, $calleeMethod, $kind, $line, $file, $callPos, $calleeFile);
+    }
+
+    /**
+     * @param array<string, mixed> $raw
+     */
+    public static function fromArray(array $raw, string $file): self
+    {
+        return new self(
+            (string) ($raw['callerClass'] ?? ''),
+            (string) ($raw['callerMethod'] ?? ''),
+            (string) ($raw['calleeClass'] ?? ''),
+            (string) ($raw['calleeMethod'] ?? ''),
+            (string) ($raw['calleeKind'] ?? self::RECEIVER_CLASS),
+            (int) ($raw['line'] ?? 0),
+            $file,
+            (int) ($raw['callPos'] ?? -1),
+            (string) ($raw['calleeFile'] ?? ''),
+        );
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function toArray(): array
+    {
+        return [
+            'callerClass' => $this->callerClass,
+            'callerMethod' => $this->callerMethod,
+            'calleeClass' => $this->calleeClass,
+            'calleeMethod' => $this->calleeMethod,
+            'calleeKind' => $this->calleeKind,
+            'line' => $this->line,
+            'file' => $this->file,
+            // Token offset of the called method's name. Two arms of one union receiver share it;
+            // two calls of the same method on one line do not, and the Python half tells them apart.
+            'callPos' => $this->callPos,
+            // Where the declaring class lives, '' for a built-in. The consumer tells a vendor
+            // class from a project class by this path, never by guessing from the namespace.
+            'calleeFile' => $this->calleeFile,
+        ];
+    }
+}

graphify_php/php/src/CallGraph/CallEdgeRule.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CallGraph;
+
+use PhpParser\Node;
+use PHPStan\Analyser\Scope;
+use PHPStan\Node\CollectedDataNode;
+use PHPStan\Rules\Rule;
+
+/**
+ * Turns everything the collector gathered into the output file.
+ *
+ * A rule rather than a second collector because `CollectedDataNode` is delivered once, in the
+ * main process, after every worker has finished — the only point at which the whole set of
+ * edges exists in one place.
+ *
+ * It reports no analysis errors. The output is the file; PHPStan's exit code stays whatever the
+ * project's own rules make it, and the consumer is expected to read the file regardless.
+ *
+ * @implements Rule<CollectedDataNode>
+ */
+final class CallEdgeRule implements Rule
+{
+    public function __construct(private readonly CallEdgeWriter $writer)
+    {
+    }
+
+    public function getNodeType(): string
+    {
+        return CollectedDataNode::class;
+    }
+
+    /**
+     * @param CollectedDataNode $node
+     * @return list<never>
+     */
+    public function processNode(Node $node, Scope $scope): array
+    {
+        $this->writer->write($this->edges($node));
+
+        return [];
+    }
+
+    /**
+     * @return iterable<CallEdge>
+     */
+    private function edges(CollectedDataNode $node): iterable
+    {
+        foreach ($node->get(MethodCallCollector::class) as $file => $perNode) {
+            foreach ($perNode as $records) {
+                foreach ($records as $record) {
+                    // The file comes from the key rather than from the record: the analyser owns
+                    // path normalisation, and a second copy would drift from it.
+                    yield CallEdge::fromArray($record, (string) $file);
+                }
+            }
+        }
+    }
+}

graphify_php/php/src/CallGraph/CallEdgeWriter.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CallGraph;
+
+/**
+ * Where resolved edges go once the analysis is over.
+ *
+ * Separate from the rule so that changing the destination — a different file format, a socket,
+ * a test double — never touches the code that decides which calls are real.
+ */
+interface CallEdgeWriter
+{
+    /**
+     * @param iterable<CallEdge> $edges
+     */
+    public function write(iterable $edges): void;
+}

graphify_php/php/src/CallGraph/JsonLinesWriter.php

@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CallGraph;
+
+use RuntimeException;
+
+/**
+ * Writes one JSON object per line.
+ *
+ * Line-delimited rather than one JSON document: a truncated run — the analyser killed on a
+ * memory limit, a timeout — still leaves every completed record readable, and the consumer
+ * drops the one broken tail line instead of losing the whole file.
+ */
+final class JsonLinesWriter implements CallEdgeWriter
+{
+    /**
+     * Set by whoever launches the analyser, so one checkout can be analysed into different
+     * destinations without editing the committed phpstan.neon.
+     */
+    public const PATH_ENV = 'PHP_CALL_GRAPH_OUT';
+
+    private const DEFAULT_PATH = 'php-call-graph.jsonl';
+
+    private readonly string $path;
+
+    public function __construct(?string $path = null)
+    {
+        $this->path = $path ?? self::pathFromEnvironment();
+    }
+
+    public function write(iterable $edges): void
+    {
+        $handle = @fopen($this->path, 'wb');
+
+        if ($handle === false) {
+            throw new RuntimeException(sprintf('Cannot open %s for writing', $this->path));
+        }
+
+        foreach ($edges as $edge) {
+            $line = json_encode($edge->toArray(), JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
+
+            if ($line === false) {
+                continue;
+            }
+
+            fwrite($handle, $line . "\n");
+        }
+
+        fclose($handle);
+    }
+
+    private static function pathFromEnvironment(): string
+    {
+        $configured = getenv(self::PATH_ENV);
+
+        if (!is_string($configured) || $configured === '') {
+            return self::DEFAULT_PATH;
+        }
+
+        return $configured;
+    }
+}

graphify_php/php/src/CallGraph/MethodCallCollector.php

@@ -0,0 +1,163 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CallGraph;
+
+use PhpParser\Node;
+use PhpParser\Node\Expr\MethodCall;
+use PhpParser\Node\Identifier;
+use PHPStan\Analyser\Scope;
+use PHPStan\Collectors\Collector;
+use PHPStan\Reflection\ClassReflection;
+use PHPStan\Reflection\Php\PhpMethodReflection;
+use PHPStan\Type\IntersectionType;
+use PHPStan\Type\Type;
+use PHPStan\Type\UnionType;
+
+/**
+ * Records every `$receiver->method()` whose receiver the type engine could name.
+ *
+ * A parser can only see types that are written down. The engine also knows the type of a
+ * private property assigned in the constructor, of a local, of a return value and of a
+ * docblock, which is why this exists at all: on the reference application a parser-only
+ * pass left three quarters of callables with no outgoing call edge.
+ *
+ * Nothing here is reported unless the engine produced a class reflection for the receiver.
+ * A name-only fallback — matching `->get()` to any class owning a `get` — manufactures edges
+ * that look identical to real ones, and a wrong edge is worse than a missing one.
+ *
+ * @implements Collector<MethodCall, list<array<string, mixed>>>
+ */
+final class MethodCallCollector implements Collector
+{
+    public function getNodeType(): string
+    {
+        return MethodCall::class;
+    }
+
+    /**
+     * @param MethodCall $node
+     * @return list<array<string, mixed>>|null
+     */
+    public function processNode(Node $node, Scope $scope): ?array
+    {
+        if (!$node->name instanceof Identifier) {
+            return null;
+        }
+
+        $callerClass = $scope->getClassReflection();
+
+        if ($callerClass === null) {
+            return null;
+        }
+
+        $callerMethod = $scope->getFunctionName();
+
+        if ($callerMethod === null) {
+            return null;
+        }
+
+        $methodName = $node->name->toString();
+        $receiverType = $scope->getType($node->var);
+        $edges = [];
+
+        // A union `A|B` is one of two objects, so every arm is a body that can run and each arm
+        // is decided on its own: `(A&B)|C` keeps C and drops the intersection, `(A&B)|null` has
+        // nothing left. Decided on the receiver as a whole, the intersection inside a union was
+        // never seen and A, B and C all went out under one call position.
+        $arms = $receiverType instanceof UnionType ? $receiverType->getTypes() : [$receiverType];
+
+        foreach ($arms as $arm) {
+            foreach ($this->armEdges($arm, $methodName, $callerClass->getName(), $callerMethod, $node, $scope) as $record) {
+                $edges[] = $record;
+            }
+        }
+
+        if ($edges === []) {
+            return null;
+        }
+
+        return $edges;
+    }
+
+    /**
+     * The records for one arm of the receiver type, or none when the arm is ambiguous.
+     *
+     * An intersection `A&B` is one object; when two constituents declare the method the type
+     * does not say which body runs, and emitting both would attribute a call to a body that
+     * never executes. Refused, as the parser layer refuses the same shape. Keyed on the
+     * declaring class so `A&B` with B extending A still resolves to the one body in A.
+     *
+     * @return list<array<string, mixed>>
+     */
+    private function armEdges(
+        Type $arm,
+        string $methodName,
+        string $callerClass,
+        string $callerMethod,
+        MethodCall $node,
+        Scope $scope,
+    ): array {
+        $records = [];
+        $declaringClasses = [];
+
+        foreach ($arm->getObjectClassReflections() as $receiver) {
+            $edge = $this->edgeTo($receiver, $methodName, $callerClass, $callerMethod, $node, $scope);
+
+            if ($edge === null) {
+                continue;
+            }
+
+            $record = $edge->toArray();
+            $records[] = $record;
+            $declaringClasses[$record['calleeClass']] = true;
+        }
+
+        if ($arm instanceof IntersectionType && count($declaringClasses) > 1) {
+            return [];
+        }
+
+        return $records;
+    }
+
+    /**
+     * @return CallEdge|null
+     */
+    private function edgeTo(
+        ClassReflection $receiver,
+        string $methodName,
+        string $callerClass,
+        string $callerMethod,
+        MethodCall $node,
+        Scope $scope,
+    ): ?CallEdge {
+        if (!$receiver->hasMethod($methodName)) {
+            return null;
+        }
+
+        // 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. For a trait method
+        // the declaring class is the class using the trait, whose file holds no such body either,
+        // so the trait is named instead. Only the native reflection knows its trait; a wrapped
+        // reflection falls back to the class, as before.
+        $method = $receiver->getMethod($methodName, $scope);
+        $declaring = $method instanceof PhpMethodReflection
+            ? ($method->getDeclaringTrait() ?? $method->getDeclaringClass())
+            : $method->getDeclaringClass();
+
+        return CallEdge::create(
+            $callerClass,
+            $callerMethod,
+            $declaring->getName(),
+            $methodName,
+            $declaring->isInterface(),
+            $node->getStartLine(),
+            '',
+            // The method name's token, not the expression's: in a chain `$a->get()->get()` every
+            // link starts at `$a`, and the name is the one token each call owns alone.
+            $node->name->getStartTokenPos(),
+            $declaring->getFileName() ?: '',
+        );
+    }
+}

graphify_php/ports.py

@@ -0,0 +1,174 @@
+"""The interfaces this package is built around.
+
+There are two ways to learn that `$this->emails` is an `Emails`: parse the file, or ask a PHP
+type engine that already knows. They have different costs — the parser needs nothing, the
+engine needs the project's `vendor/` and runs PHP — and different reach: the engine resolves
+untyped properties, chains and docblocks that the parser must refuse.
+
+Both are therefore the same thing to the code that builds edges: a source of resolved call
+targets. That is `CallTargetSource` below, and it is the only thing `resolver` depends on.
+Adding a third source later — a language server, an LSIF index — means implementing one
+protocol, not editing the resolver.
+
+`Confidence` is not decoration. graphify already distinguishes EXTRACTED from INFERRED on its
+own edges, and the mesh surfaces that distinction to callers; a target proved by a type engine
+and one guessed from a declaration must not arrive looking alike.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from enum import Enum
+from typing import Protocol, runtime_checkable
+
+
+class Confidence(str, Enum):
+    """How the target was established, in graphify's own vocabulary."""
+
+    EXTRACTED = "EXTRACTED"  # the receiver's type is stated in source and was read there
+    INFERRED = "INFERRED"  # derived: a constructor-body assignment, a `new` binding
+
+
+@dataclass(frozen=True)
+class CallSite:
+    """One `$receiver->method(...)` that graphify could not resolve.
+
+    `caller_nid` is graphify's node id for the enclosing callable, carried through untouched:
+    this package never invents node identity, it only connects nodes graphify already made.
+    """
+
+    caller_nid: str
+    receiver: str  # source text of the receiver expression, e.g. `$this->emails`
+    method: str
+    source_file: str
+    source_location: str
+
+
+@dataclass(frozen=True)
+class CallTarget:
+    """A call site resolved to a class and method, with the evidence that resolved it."""
+
+    site: CallSite
+    class_fqn: str
+    method: str
+    confidence: Confidence
+    via: str  # which type source proved it, for diagnosis and for the status record
+    # Where the declaring class lives, '' when the source does not know. Lets the graph layer
+    # tell a vendor target from a project class the build left out, without guessing from the FQN.
+    declaring_file: str = ""
+
+
+@runtime_checkable
+class CallTargetSource(Protocol):
+    """Anything that can turn unresolved call sites into targets.
+
+    The contract that matters is not in the signature: a source returns a target ONLY when it
+    can prove it. Six upstream issues across four code-graph projects trace their false edges
+    to a name-only fallback — `->get()` wired to an unrelated class, `empty()` wired to a
+    method called `empty`. A source that cannot prove a site leaves it out and says why
+    through `unresolved`, so the gap is counted rather than filled with a guess.
+    """
+
+    name: str
+
+    def available(self, repo_root: str) -> tuple[bool, str]:
+        """Can this source run here? Returns (yes, reason-if-not).
+
+        A repository with no `vendor/bin/phpstan` is a normal, expected "no": the build
+        records a skip and carries on with whatever other sources are available. It is not a
+        failure, and conflating the two is how a missing layer becomes invisible.
+        """
+
+    def resolve(
+        self,
+        repo_root: str,
+        sites: Iterable[CallSite],
+        corpus: Iterable[str] | None = None,
+    ) -> Resolution:
+        """Resolve `sites`, optionally with `corpus` as the set of files that may be read.
+
+        `corpus` exists because a source needs declarations from files that hold no call site
+        of their own. A leaf service class has nothing unresolved in it, so it never appears
+        among `sites`, and a source that indexes only the files it was handed cannot tell
+        whether that class declares the method being called on it. Measured on an intersection
+        type: the same call resolves when the constituent's file happens to carry a site and
+        stays `unknown-receiver-type` when it does not, which makes the answer depend on
+        unrelated code.
+
+        The caller passes the files graphify itself parsed, so the set is bounded by the build
+        rather than by a filesystem walk — an earlier version walked to the nearest
+        `composer.json` and cost 4.7 s against 0.16 s for the site files alone, while also
+        reading paths outside the build.
+
+        `None` means "only the files carrying sites", which stays the honest default for a
+        caller that has no corpus to offer.
+        """
+
+
+@dataclass
+class Resolution:
+    """What a source made of the sites it was given."""
+
+    targets: list[CallTarget]
+    unresolved: dict[str, int]  # reason -> count, a fixed vocabulary per source
+    files_seen: int = 0
+
+
+@runtime_checkable
+class NodeIndex(Protocol):
+    """graphify's nodes, queried the one way this package needs.
+
+    Narrow on purpose: the resolver needs "which node is method M of class C", nothing else.
+    A wider interface would tie this package to graphify's node schema, which is the thing
+    most likely to move under it between releases.
+    """
+
+    def method_node(self, class_fqn: str, method: str) -> str | None: ...
+
+
+@runtime_checkable
+class EdgeSink(Protocol):
+    """Where resolved targets become graph edges."""
+
+    def add_call(self, caller_nid: str, callee_nid: str, target: CallTarget) -> None: ...
+
+
+@runtime_checkable
+class ScopeIndex(Protocol):
+    """What a scoped call needs from the graph, beside `NodeIndex`.
+
+    `Helper::format()` reaches graphify as a call to `Helper` with the method name dropped
+    (`extractors/engine.py`, the `scoped_call_expression` arm), so the site arrives without the
+    one field it exists to carry. The graph knows which methods a class declares, and a type
+    source can check each candidate against the line it came from — so the name is recoverable
+    without the integration layer parsing PHP. A class with ten methods costs ten lookups and
+    yields at most one edge.
+
+    Kept apart from `NodeIndex` because the two answer different questions and an index that
+    can do one need not do the other.
+    """
+
+    def scope_methods(self, caller_nid: str, scope: str) -> list[str]:
+        """Methods the named scope declares, for `self`, `parent`, `static` or a class name."""
+
+
+@runtime_checkable
+class RouteDeclarationSource(Protocol):
+    """Anything that can find route declarations in a codebase.
+
+    Same contract as `CallTargetSource`: a declaration is returned only when it was read, and a
+    route whose path could not be composed is counted under a fixed reason rather than guessed
+    into existence. It is a separate port because a route has no call site — forcing it through
+    `CallTargetSource` would mean inventing a `caller_nid`, and this package never invents node
+    identity.
+    """
+
+    name: str
+
+    def available(self, repo_root: str) -> tuple[bool, str]: ...
+
+    def declarations(self, repo_root: str, files: Iterable[str]) -> object:
+        """Route declarations found in `files`. The concrete result type lives with the source,
+        because the shape of a declaration is the source's business and this port only needs to
+        name the call."""