graphify-php 0.0.5__py3-none-any.whl

graphify_php/syntax/call_sites.py

@@ -0,0 +1,117 @@
+"""Where the member calls are, and what each one is called on.
+
+This exists because graphify does not tell us. Its PHP branch marks a call as a member call
+and records the method name, but never the receiver: `extractors/engine.py:6152-6157` sets
+`is_member_call` and `callee_name` and stops, while the C++, Java, C# and Ruby branches beside
+it all assign `member_receiver`. The entry built at `engine.py:6403` is
+`"receiver": swift_receiver or member_receiver`, so every PHP call site arrives with an empty
+receiver and a source that trusted the field would resolve nothing at all.
+
+Reading the receiver out of the tree is better than the string graphify would have handed over
+anyway: the tree gives the exact extent of the receiver expression, so `$this->a->b()` as the
+receiver of `->c()` is visibly a call rather than a name that happens to contain brackets.
+
+Indexed by (line, method) because that is the only handle a `CallSite` carries —
+`engine.py:6402` writes the location as `L<line>` off the call node's own start point.
+
+Scoped calls are indexed here too, and for a sharper reason than member calls. graphify does
+not leave `self::save()` unresolved, it records the wrong callee: `engine.py:6147-6152` reads
+`scoped_call_expression`'s **scope** as the callee name, so `parent::run()` arrives as a call
+to something named `parent` and the method never reaches the record at all. The method name
+exists only in the source, so the line is the only way back to it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from . import nodes
+
+# `$a?->b()` binds to the same class as `$a->b()`; null is not a separate call target.
+CALL_KINDS = ("member_call_expression", "nullsafe_member_call_expression")
+SCOPED_KIND = "scoped_call_expression"
+
+# `self`, `parent` and `static` arrive under this node kind; anything else in scope position
+# is either a class name or an expression.
+RELATIVE_SCOPE = "relative_scope"
+
+
+@dataclass(frozen=True)
+class ScopedCall:
+    """`Scope::method()` — the scope as written, and the grammar's verdict on its shape."""
+
+    scope: str
+    kind: str
+
+    @property
+    def is_dynamic(self) -> bool:
+        """`$class::m()` and `{$expr}::m()`: the class is a runtime value, not a name."""
+        return self.kind not in (RELATIVE_SCOPE, "name", "qualified_name")
+
+
+@dataclass
+class CallSiteIndex:
+    """Every member call in one file, keyed by the line it starts on and its method name."""
+
+    receivers: dict[tuple[int, str], list[str]] = field(default_factory=dict)
+    scopes: dict[tuple[int, str], list[ScopedCall]] = field(default_factory=dict)
+
+    def receiver_for(self, line: int, method: str) -> tuple[str | None, int]:
+        """The receiver expression for that call, plus how many calls matched.
+
+        The count is returned rather than resolved here so the caller owns the refusal
+        vocabulary: two calls to the same method on one line is a real shape (`$a->run();
+        $b->run();`) and picking either one is a coin toss between two different classes.
+        """
+        found = self.receivers.get((line, method)) or []
+        if len(found) != 1:
+            return None, len(found)
+        return found[0], 1
+
+    def scope_for(self, line: int, method: str) -> tuple[ScopedCall | None, int]:
+        """The scope expression for a `Scope::method()` on that line, and how many matched."""
+        found = self.scopes.get((line, method)) or []
+        if len(found) != 1:
+            return None, len(found)
+        return found[0], 1
+
+
+def index_calls(root) -> CallSiteIndex:
+    index = CallSiteIndex()
+    _walk(root, index)
+    return index
+
+
+def _walk(node, index: CallSiteIndex) -> None:
+    if node.type in CALL_KINDS:
+        _record(node, index)
+    elif node.type == SCOPED_KIND:
+        _record_scoped(node, index)
+    for child in node.children:
+        _walk(child, index)
+
+
+def _record_scoped(node, index: CallSiteIndex) -> None:
+    name_node = node.child_by_field_name("name")
+    scope_node = node.child_by_field_name("scope")
+    if name_node is None or scope_node is None:
+        return
+    method = nodes.node_text(name_node)
+    if not method:
+        return
+    key = (node.start_point[0] + 1, method)
+    call = ScopedCall(scope=nodes.node_text(scope_node).strip(), kind=scope_node.type)
+    index.scopes.setdefault(key, []).append(call)
+
+
+def _record(node, index: CallSiteIndex) -> None:
+    name_node = node.child_by_field_name("name")
+    object_node = node.child_by_field_name("object")
+    if name_node is None or object_node is None:
+        return
+    method = nodes.node_text(name_node)
+    if not method:
+        return
+    # The call node's own start line, because that is what graphify records as the location.
+    key = (node.start_point[0] + 1, method)
+    index.receivers.setdefault(key, []).append(nodes.node_text(object_node))

graphify_php/syntax/class_index.py

@@ -0,0 +1,121 @@
+"""Which classes exist in the corpus, and what each one declares.
+
+The receiver's type is only half of a call target. Resolving `$this->magic` to
+`Eval\\Dynamic\\Magic` and then emitting whatever method name the call site wrote produces an
+edge to a member that does not exist — right class, invented method. That is the softer form
+of the failure the six upstream issues describe, and a consumer cannot tell it from a real
+edge, so it has to be checked rather than assumed.
+
+The check has three answers, not two, and keeping them apart is the whole point:
+
+- the method is declared, somewhere in the class's own ancestry — emit;
+- the class is in the corpus, its whole ancestry is in the corpus, and none of them declares
+  the method — a real refusal;
+- the class or one of its ancestors was never read — absence is not proved, so the caller
+  emits the target and lets `GraphNodeIndex.method_node` settle it against the whole corpus.
+
+A class that declares `__call` answers every method name at runtime, so a name missing from it
+is dispatched, not absent. That is `indirect-dispatch`, the reason that already exists for it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# What the lookup concluded. Strings rather than an enum so they read plainly in a debugger.
+DECLARED = "declared"
+NOT_DECLARED = "not-declared"
+UNKNOWN = "unknown"
+MAGIC = "magic"
+
+MAGIC_METHODS = ("__call", "__callStatic")
+
+
+@dataclass(frozen=True)
+class ClassRecord:
+    """One declaration: what it declares itself, and where else to look."""
+
+    fqn: str
+    methods: frozenset[str]
+    # extends, implements and `use`d traits together. The lookup does not care which is which:
+    # all three are places a method can be declared, and PHP resolves them into one class.
+    ancestors: tuple[str, ...]
+
+
+@dataclass
+class ClassIndex:
+    classes: dict[str, ClassRecord] = field(default_factory=dict)
+    # The scopes themselves, for the property walk. Kept beside the records rather than folded
+    # into them because a record is a summary and this needs the declarations as parsed.
+    scopes: dict[str, object] = field(default_factory=dict)
+
+    def add(self, record: ClassRecord, scope=None) -> None:
+        self.classes[record.fqn] = record
+        if scope is not None:
+            self.scopes[record.fqn] = scope
+
+    def property_fact(self, fqn: str, name: str):
+        """The nearest declaration of `$name` in the ancestry, as (fact, refusal reason).
+
+        Breadth-first so the nearest declaration wins: a subclass that redeclares `$emails`
+        with a narrower type beats the ancestor's, which is the whole reason PHP allows the
+        redeclaration. Within one level the order is `extends`, then `implements`, then traits.
+
+        An ancestor in a file this run never read simply is not here, so its properties are
+        neither found nor disproved and the caller reports the type as unknown. Same principle
+        as the method check: disprove only what was seen.
+        """
+        level = [fqn]
+        seen: set[str] = set()
+        while level:
+            following: list[str] = []
+            for current in level:
+                if current in seen:
+                    continue
+                seen.add(current)
+                scope = self.scopes.get(current)
+                if scope is None:
+                    continue
+                refusal = scope.refusals.get(name)
+                if refusal:
+                    return None, refusal
+                fact = scope.properties.get(name)
+                if fact is not None:
+                    return fact, None
+                following.extend(scope.ancestors)
+            level = following
+        return None, None
+
+    def declares(self, fqn: str, method: str) -> str:
+        """Walk the ancestry for `method` and report which of the three answers applies."""
+        seen: set[str] = set()
+        pending = [fqn]
+        saw_unknown = False
+        saw_magic = False
+        while pending:
+            current = pending.pop()
+            if current in seen:
+                continue
+            seen.add(current)
+            record = self.classes.get(current)
+            if record is None:
+                saw_unknown = True
+                continue
+            if method in record.methods:
+                return DECLARED
+            if any(magic in record.methods for magic in MAGIC_METHODS):
+                saw_magic = True
+            pending.extend(record.ancestors)
+        if saw_magic:
+            return MAGIC
+        return UNKNOWN if saw_unknown else NOT_DECLARED
+
+
+def record_for(scope, methods: frozenset[str]) -> ClassRecord:
+    return ClassRecord(fqn=scope.fqn, methods=methods, ancestors=tuple(scope.ancestors))
+
+
+def index_from_facts(index: ClassIndex, facts) -> None:
+    """Fold one file's declarations into the index."""
+    for scope in facts.classes:
+        index.add(record_for(scope, frozenset(m.name for m in scope.methods if m.name)), scope)

graphify_php/syntax/collectors.py

@@ -0,0 +1,351 @@
+"""One class per type source.
+
+Each collector handles exactly one grammar node kind and writes exactly one kind of fact.
+They are registered in `COLLECTORS` at the bottom, so a fifth type source — docblocks, an
+attribute, a container definition — is a new class and one list entry, never a new branch in
+the walker. `file_scan` imports the registry and has no idea what is in it.
+
+The four here, in the precedence they settle conflicts by (lowest number wins):
+
+1. Promoted constructor parameters — `__construct(private readonly Emails $emails)`. Measured
+   on one Symfony application: 652 of 715 injected properties carry a concrete class type and
+   63 an interface (92 % / 8 %), so this one source covers most of the receivers that matter.
+2. Typed property declarations — `private readonly Emails $legacy;`.
+3. Constructor-body assignment from a typed parameter — `$this->legacy = $x;` where the
+   constructor declares `Emails $x`. The case pure declaration reading misses; it predates
+   promoted properties, so it is common in older code rather than exotic.
+4. `new` bindings for locals — `$mailer = new Emails();`.
+
+Docblocks are not read at all in this version. A `@var` that contradicts a native type is a
+bug in the code, and resolving one correctly needs scope tracking these collectors do not do.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from ..ports import Confidence
+from . import nodes
+from .facts import TypeFact
+
+# Fixed reasons, shared with the resolver so that a refusal recorded while scanning and a
+# refusal decided at the call site cannot drift into two spellings of the same thing.
+UNION_TYPE = "union-type"
+REASSIGNED_LOCAL = "reassigned-local"
+
+
+@dataclass
+class ScanContext:
+    """Where the walker currently is. Collectors read it; they never change it."""
+
+    facts: object  # FileFacts, kept untyped here to avoid an import cycle
+    names: object  # NameResolver
+    klass: object | None  # ClassScope
+    method: object | None  # MethodScope
+
+
+class TypeCollector(Protocol):
+    """A source of receiver types.
+
+    `node_kind` is what the walker dispatches on, `via` is what lands in `CallTarget.via`, and
+    `precedence` settles a conflict with another collector without either knowing the other.
+    """
+
+    node_kind: str
+    via: str
+    confidence: Confidence
+    precedence: int
+
+    def collect(self, node, ctx: ScanContext) -> None: ...
+
+
+def _fact(collector: TypeCollector, fqn: str, members: tuple = ()) -> TypeFact:
+    return TypeFact(
+        fqn=fqn,
+        confidence=collector.confidence,
+        via=collector.via,
+        precedence=collector.precedence,
+        members=members,
+    )
+
+
+def _declared_type(
+    collector: TypeCollector, node, ctx: ScanContext
+) -> tuple[str | None, tuple, str | None]:
+    """Read a declaration's type annotation as (fqn, intersection members, refusal reason).
+
+    Four outcomes. A concrete class is a fact. An intersection `A&B` is a fact with several
+    constituents, resolved at the call site by which one declares the method. A union is a
+    refusal that must be counted, because both alternatives are real targets and this version
+    cannot express two. Anything else — untyped, `int`, `self` — is none of them, because it
+    names no call target at all.
+    """
+    annotation = nodes.type_node(node)
+    if nodes.is_union(annotation):
+        return None, (), UNION_TYPE
+    members = nodes.intersection_members(annotation)
+    if members:
+        return None, tuple(ctx.names.resolve(m) for m in members), None
+    short = nodes.type_name(annotation)
+    if not short:
+        return None, (), None
+    return ctx.names.resolve(short), (), None
+
+
+class PromotedParameterCollector:
+    """`__construct(private readonly Emails $emails)`.
+
+    The dominant source in modern PHP: constructor promotion states the property's type and
+    its injection in one place, which is why 92 % of the reference application's injected
+    properties resolve from this collector alone.
+    """
+
+    node_kind = "property_promotion_parameter"
+    via = "promoted-parameter"
+    confidence = Confidence.EXTRACTED
+    precedence = 10
+
+    def collect(self, node, ctx: ScanContext) -> None:
+        if ctx.klass is None:
+            return
+        prop = nodes.variable_of(node)
+        if not prop:
+            return
+        fqn, members, refusal = _declared_type(self, node, ctx)
+        if refusal:
+            ctx.klass.refuse_property(prop, refusal, self.precedence)
+        elif fqn or members:
+            ctx.klass.record_property(prop, _fact(self, fqn or "", members))
+
+
+class TypedPropertyCollector:
+    """`private readonly Emails $legacy;`, including the multi-element form."""
+
+    node_kind = "property_declaration"
+    via = "typed-property"
+    confidence = Confidence.EXTRACTED
+    precedence = 20
+
+    def collect(self, node, ctx: ScanContext) -> None:
+        if ctx.klass is None:
+            return
+        fqn, members, refusal = _declared_type(self, node, ctx)
+        if not fqn and not members and not refusal:
+            return
+        for element in nodes.children(node, "property_element"):
+            prop = nodes.variable_of(element)
+            if not prop:
+                continue
+            if refusal:
+                ctx.klass.refuse_property(prop, refusal, self.precedence)
+            else:
+                ctx.klass.record_property(prop, _fact(self, fqn or "", members))
+
+
+class ConstructorAssignmentCollector:
+    """`$this->legacy = $x;` where the constructor declares `Emails $x`.
+
+    Registered on the constructor rather than on the assignment so that the parameter types
+    and the statements that use them are read in one place; an assignment node on its own
+    cannot see the signature it draws from without walking back up the tree.
+
+    INFERRED, not EXTRACTED: the property itself states no type, and the link from parameter
+    to property is a reading of one statement, not a declaration.
+    """
+
+    node_kind = "method_declaration"
+    via = "constructor-assignment"
+    confidence = Confidence.INFERRED
+    precedence = 30
+
+    def collect(self, node, ctx: ScanContext) -> None:
+        if ctx.klass is None or nodes.name_of(node) != "__construct":
+            return
+        params = self._parameter_types(node, ctx)
+        if not params:
+            return
+        body = nodes.child(node, "compound_statement")
+        for assignment in self._assignments(body):
+            prop, source_var = self._this_assignment(assignment)
+            if not prop or source_var not in params:
+                continue
+            fqn, members, refusal = params[source_var]
+            if refusal:
+                ctx.klass.refuse_property(prop, refusal, self.precedence)
+            elif fqn or members:
+                ctx.klass.record_property(prop, _fact(self, fqn or "", members))
+
+    def _parameter_types(self, ctor, ctx: ScanContext) -> dict[str, tuple]:
+        out: dict[str, tuple] = {}
+        params = nodes.child(ctor, "formal_parameters")
+        for param in nodes.children(params, "simple_parameter", "property_promotion_parameter"):
+            name = nodes.variable_of(param)
+            if not name:
+                continue
+            fqn, members, refusal = _declared_type(self, param, ctx)
+            if fqn or members or refusal:
+                out[name] = (fqn, members, refusal)
+        return out
+
+    def _assignments(self, node):
+        """Every assignment in the constructor body, nested ones included.
+
+        A guarded assignment inside an `if` is still the only thing that ever sets the
+        property in the overwhelming majority of constructors, so restricting this to
+        top-level statements would drop real facts for no gain in precision.
+        """
+        if node is None or node.type in nodes.CLOSURE_KINDS:
+            # A closure's `$x` is the closure's own parameter or capture, not the
+            # constructor's, so an assignment inside one draws from a signature not read here.
+            return
+        if node.type == "assignment_expression":
+            yield node
+        for candidate in node.children:
+            yield from self._assignments(candidate)
+
+    def _this_assignment(self, assignment) -> tuple[str | None, str | None]:
+        """`$this->prop = $var` as (prop, var), or (None, None) for anything else.
+
+        `$this->$prop = ...` falls out here because the property side is a `variable_name`
+        rather than a `name`, which is the shape of a dynamic property and not something a
+        static read can name.
+        """
+        left = assignment.children[0] if assignment.children else None
+        right = assignment.children[-1] if len(assignment.children) > 2 else None
+        if left is None or right is None:
+            return None, None
+        if left.type != "member_access_expression" or right.type != "variable_name":
+            return None, None
+        receiver = left.children[0] if left.children else None
+        prop_node = left.children[-1] if len(left.children) > 1 else None
+        if receiver is None or prop_node is None or prop_node.type != "name":
+            return None, None
+        if nodes.node_text(receiver) != "$this":
+            return None, None
+        return nodes.node_text(prop_node), nodes.node_text(right).lstrip("$")
+
+
+class LocalConstructionCollector:
+    """`$mailer = new Emails();`, and the reassignment that invalidates it.
+
+    Aliasing a property into a local (`$e = $this->emails;`) is deliberately not tracked: it
+    needs flow analysis to know the local was not reassigned before the call, and a binding
+    that survives its own reassignment is exactly how a resolver starts lying. For the same
+    reason every other assignment to a bound local revokes the binding rather than being
+    ignored — the second write is the evidence that the first no longer holds.
+    """
+
+    node_kind = "assignment_expression"
+    via = "new-binding"
+    confidence = Confidence.INFERRED
+    precedence = 40
+
+    def collect(self, node, ctx: ScanContext) -> None:
+        if ctx.method is None:
+            return
+        left = node.children[0] if node.children else None
+        right = node.children[-1] if len(node.children) > 2 else None
+        if left is None or right is None or left.type != "variable_name":
+            return
+        local = nodes.node_text(left).lstrip("$")
+        if not local or local == "this":
+            return
+
+        # Any second write revokes the binding, in either order. Without flow analysis there is
+        # no way to tell a call placed before the second write from one placed after it, and
+        # only one of those two readings is true.
+        if not ctx.method.note_write(local, REASSIGNED_LOCAL, self.precedence):
+            return
+        if right.type != "object_creation_expression":
+            return
+        # `new $class()` and `new class {...}` write no class name, so there is none to read.
+        created = nodes.type_name(nodes.child(right, "qualified_name", "name"))
+        if not created:
+            return
+        ctx.method.record_local(local, _fact(self, ctx.names.resolve(created)))
+
+
+class LocalRebindCollector:
+    """A construct that binds a local without an `=`: it revokes a `new` binding all the same.
+
+    A `foreach` target, a closure's parameters and `use` clause, a `catch` variable, a
+    destructuring target and the method's own parameters all write the name. Left uncounted,
+    `$m = new Emails(); foreach ($caches as $m) { $m->get(); }` resolves a call on a cache to
+    `Emails::get`. One instance per grammar node kind, so the walker dispatches as it does for
+    every other collector; none of them records a type, they only revoke.
+    """
+
+    via = "rebinding"
+    confidence = Confidence.INFERRED
+    # The same rank as the `new` binding it revokes: a stronger source's fact survives it.
+    precedence = LocalConstructionCollector.precedence
+
+    def __init__(self, node_kind: str) -> None:
+        self.node_kind = node_kind
+
+    def collect(self, node, ctx: ScanContext) -> None:
+        if ctx.method is None:
+            return
+        for name in _bound_names(node):
+            ctx.method.note_write(name, REASSIGNED_LOCAL, self.precedence)
+
+
+def _bound_names(node) -> list[str]:
+    """The locals a binding construct writes, read from its direct children only.
+
+    Direct children, because a nested `list_literal` is dispatched to its own collector and
+    reading it twice would count one write as two. In a `foreach` only the part after `as`
+    is a target; the subject before it is read, not written.
+    """
+    if node.type == "formal_parameters":
+        params = nodes.children(
+            node, "simple_parameter", "variadic_parameter", "property_promotion_parameter"
+        )
+        return [name for name in (nodes.variable_of(p) for p in params) if name]
+    if node.type == "foreach_statement":
+        seen_as = False
+        targets = []
+        for child in node.children:
+            if not child.is_named and nodes.node_text(child) == "as":
+                seen_as = True
+            elif seen_as:
+                targets.append(child)
+        node_list = targets
+    else:
+        node_list = node.children
+    names = []
+    for child in node_list:
+        if child.type == "pair":
+            names.extend(_bound_names(child))
+        elif child.type == "by_ref":
+            names.extend(_bound_names(child))
+        elif child.type == "variable_name":
+            name = nodes.node_text(child).lstrip("$")
+            if name and name != "this":
+                names.append(name)
+    return names
+
+
+# The registry. Adding a type source means adding a class above and one entry here.
+COLLECTORS: list[TypeCollector] = [
+    PromotedParameterCollector(),
+    TypedPropertyCollector(),
+    ConstructorAssignmentCollector(),
+    LocalConstructionCollector(),
+    LocalRebindCollector("formal_parameters"),
+    LocalRebindCollector("anonymous_function_use_clause"),
+    LocalRebindCollector("foreach_statement"),
+    LocalRebindCollector("catch_clause"),
+    LocalRebindCollector("list_literal"),
+]
+
+
+def by_node_kind(collectors: list[TypeCollector] | None = None) -> dict[str, list[TypeCollector]]:
+    """Group the registry so the walker dispatches by node kind instead of testing each one."""
+    registry: dict[str, list[TypeCollector]] = {}
+    for collector in collectors if collectors is not None else COLLECTORS:
+        registry.setdefault(collector.node_kind, []).append(collector)
+    for bucket in registry.values():
+        bucket.sort(key=lambda c: c.precedence)
+    return registry