graphify-php 0.0.5__py3-none-any.whl

graphify_php/syntax/facts.py

@@ -0,0 +1,171 @@
+"""What one PHP file says about the types of its receivers.
+
+Scoped per class AND per method rather than flat. Two classes in one file may both declare
+`$repo`, and two methods may both bind a local `$service`; a flat table silently merges them
+and produces an edge to the wrong class — the same failure the short-name fallback produces,
+reached by a different route.
+
+A scope records two kinds of answer, and the second is the point of the package: a type it
+knows, and a name it deliberately refuses with a reason. A property that is missing from both
+is a gap; a property in `refusals` is a decision, and the reason travels all the way out to
+`Resolution.unresolved` so the gap becomes a work list.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ..ports import Confidence
+from .call_sites import CallSiteIndex
+from .routes import RouteDeclaration
+
+
+@dataclass(frozen=True)
+class TypeFact:
+    """A receiver type, with the evidence that produced it.
+
+    `precedence` is how two sources claiming the same property are settled without either
+    collector knowing the other exists: lowest wins, and the numbers live on the collectors.
+    """
+
+    fqn: str
+    confidence: Confidence
+    via: str
+    precedence: int
+    # `A&B`: every class the object is at once. Empty for an ordinary single type. The one
+    # that owns the called method is chosen at the call site, not here, because which
+    # constituent is the target depends on the method being called.
+    members: tuple[str, ...] = ()
+
+    @property
+    def is_intersection(self) -> bool:
+        return bool(self.members)
+
+
+@dataclass
+class MethodScope:
+    name: str
+    start_line: int
+    end_line: int
+    locals: dict[str, TypeFact] = field(default_factory=dict)
+    refusals: dict[str, str] = field(default_factory=dict)
+    # Every local this method writes to, whether or not the write produced a usable type.
+    # A second write is what revokes a binding, so the ones that produced nothing still count.
+    assigned: set = field(default_factory=set)
+
+    def record_local(self, name: str, fact: TypeFact) -> None:
+        existing = self.locals.get(name)
+        if existing is not None and existing.precedence <= fact.precedence:
+            return
+        self.locals[name] = fact
+
+    def note_write(self, name: str, reason: str, precedence: int) -> bool:
+        """Record a binding of `name`, revoking an earlier one. True when it was the first.
+
+        Every binding form counts — an assignment, a parameter, a `foreach` target, a `catch`
+        variable, a destructuring target — because without flow analysis a second write
+        anywhere in the method is the evidence that the first no longer holds at the call.
+        """
+        rewritten = name in self.assigned
+        self.assigned.add(name)
+        if rewritten:
+            self.refuse_local(name, reason, precedence)
+        return not rewritten
+
+    def refuse_local(self, name: str, reason: str, precedence: int) -> None:
+        """Drop whatever was known about a local and say why.
+
+        Refusal wins over a recorded type of equal or weaker precedence on purpose. The case
+        that forces it is a local reassigned after its binding: the earlier `new Emails()` is
+        still true at the point it was written and false by the time of the call, and there is
+        no flow analysis here to tell the two positions apart. A fact from a strictly stronger
+        source survives, so one collector's doubt cannot erase another's declaration.
+        """
+        existing = self.locals.get(name)
+        if existing is not None and existing.precedence < precedence:
+            return
+        self.locals.pop(name, None)
+        self.refusals[name] = reason
+
+    def contains(self, line: int) -> bool:
+        return self.start_line <= line <= self.end_line
+
+
+@dataclass
+class ClassScope:
+    fqn: str
+    start_line: int
+    end_line: int
+    parent: str | None = None
+    # extends, implements and `use`d traits, all resolved. One list because a method can be
+    # declared in any of them and PHP flattens all three into one class.
+    ancestors: list[str] = field(default_factory=list)
+    properties: dict[str, TypeFact] = field(default_factory=dict)
+    refusals: dict[str, str] = field(default_factory=dict)
+    methods: list[MethodScope] = field(default_factory=list)
+
+    def record_property(self, name: str, fact: TypeFact) -> None:
+        if name in self.refusals:
+            return
+        existing = self.properties.get(name)
+        if existing is not None and existing.precedence <= fact.precedence:
+            return
+        self.properties[name] = fact
+
+    def refuse_property(self, name: str, reason: str, precedence: int) -> None:
+        """See `MethodScope.refuse_local`: a stronger source's fact outranks a weaker doubt."""
+        existing = self.properties.get(name)
+        if existing is not None and existing.precedence < precedence:
+            return
+        self.properties.pop(name, None)
+        self.refusals[name] = reason
+
+    def method_at(self, line: int) -> MethodScope | None:
+        for method in self.methods:
+            if method.contains(line):
+                return method
+        return None
+
+    def contains(self, line: int) -> bool:
+        return self.start_line <= line <= self.end_line
+
+
+@dataclass
+class FileFacts:
+    """Everything one file proves about itself."""
+
+    path: str
+    namespace: str = ""
+    imports: dict[str, str] = field(default_factory=dict)
+    classes: list[ClassScope] = field(default_factory=list)
+    # The receivers graphify does not send: see `call_sites` for why they are read here.
+    calls: CallSiteIndex = field(default_factory=CallSiteIndex)
+    # Route attributes declared in this file. Not a type fact, carried here because the file
+    # is what owns them and one parse should answer every question about it.
+    routes: list[RouteDeclaration] = field(default_factory=list)
+    # Line spans of every `new class { ... }`. The walker reads nothing inside one, so a site
+    # there has no facts of its own and must not be answered with the enclosing class's.
+    anonymous_classes: list[tuple[int, int]] = field(default_factory=list)
+
+    def in_anonymous_class(self, line: int) -> bool:
+        return any(start <= line <= end for start, end in self.anonymous_classes)
+
+    def class_at(self, line: int) -> ClassScope | None:
+        """The innermost class whose body covers `line`.
+
+        Innermost rather than first because a file may declare several classes and the spans
+        are checked, not assumed disjoint.
+        """
+        best: ClassScope | None = None
+        for scope in self.classes:
+            if not scope.contains(line):
+                continue
+            if best is None or scope.start_line >= best.start_line:
+                best = scope
+        return best
+
+    def class_named(self, fqn: str) -> ClassScope | None:
+        for scope in self.classes:
+            if scope.fqn == fqn:
+                return scope
+        return None

graphify_php/syntax/file_scan.py

@@ -0,0 +1,158 @@
+"""The walker: one pass over one file, driving whatever collectors are registered.
+
+This module owns scope and nothing else. It knows that `namespace` and `use` bind names, that
+a class declaration opens a class scope and a method declaration a method scope, and that a
+line number inside the file falls in one of them. It does not know what a type source is, and
+adding a fifth one must not change a line here — that is why the collectors are a registry
+rather than a chain of `elif`s, and why the four that exist are never named in this file.
+"""
+
+from __future__ import annotations
+
+from . import nodes
+from .call_sites import index_calls
+from .collectors import COLLECTORS, ScanContext, by_node_kind
+from .facts import ClassScope, FileFacts, MethodScope
+from .names import NameResolver
+from .routes import collect_routes
+
+
+def scan_source(path: str, source: bytes, collectors=None) -> FileFacts:
+    """Parse one file and return what it proves about its own receivers."""
+    tree = nodes.parse(source)
+    names = NameResolver()
+    facts = FileFacts(path=path, imports=names.imports)
+    registry = by_node_kind(collectors if collectors is not None else COLLECTORS)
+    _walk(tree.root_node, facts, names, registry, klass=None, method=None)
+    facts.namespace = names.namespace
+    # A second pass rather than a hook in `_walk`: locating calls is not scope work, and
+    # keeping it out means the walker still has one reason to change.
+    facts.calls = index_calls(tree.root_node)
+    facts.routes = collect_routes(tree.root_node, names, path)
+    return facts
+
+
+def scan_file(path: str, collectors=None) -> FileFacts:
+    with open(path, "rb") as handle:
+        return scan_source(path, handle.read(), collectors)
+
+
+def _walk(node, facts: FileFacts, names: NameResolver, registry, klass, method) -> None:
+    kind = node.type
+
+    if _is_anonymous_class(node):
+        # Its members belong to a class with no name, so attributing them to the enclosing
+        # class would invent properties the enclosing class does not have. The span is kept
+        # so a call site inside it is refused rather than read against the enclosing class.
+        facts.anonymous_classes.append(nodes.line_span(node))
+        return
+
+    if kind == "namespace_definition":
+        _read_namespace(node, names)
+    elif kind == "namespace_use_declaration":
+        _read_imports(node, names)
+    elif kind in nodes.CLASS_KINDS:
+        klass = _open_class(node, facts, names)
+        method = None
+    elif kind == "method_declaration" and klass is not None:
+        method = _open_method(node, klass)
+    elif kind == "use_declaration" and klass is not None:
+        # A trait `use` inside a class body, not a namespace import: the methods it brings in
+        # are declared by this class as far as any caller can tell.
+        klass.ancestors.extend(_names_in(node, names))
+
+    for collector in registry.get(kind, ()):
+        collector.collect(node, ScanContext(facts=facts, names=names, klass=klass, method=method))
+
+    for child in node.children:
+        _walk(child, facts, names, registry, klass, method)
+
+
+def _is_anonymous_class(node) -> bool:
+    """`new class { ... }`, which the grammar hangs under an `object_creation_expression`."""
+    if node.type == "anonymous_class":
+        return True
+    return (
+        node.type == "object_creation_expression"
+        and nodes.child(node, "declaration_list") is not None
+    )
+
+
+def _read_namespace(node, names: NameResolver) -> None:
+    name_node = nodes.child(node, "namespace_name", "qualified_name", "name")
+    if name_node is None:
+        return
+    # A braced `namespace X { ... }` block is read the same way, which is wrong for the rare
+    # file holding two of them. Two namespaces in one file is disallowed by PSR-4 and absent
+    # from the reference application, so the simpler reading stands until one turns up.
+    names.namespace = nodes.node_text(name_node).strip().strip(";").strip().strip("\\")
+
+
+def _read_imports(node, names: NameResolver) -> None:
+    """`use A\\B\\C;` and `use A\\B\\C as D;`.
+
+    Grouped and function/const imports are not read: a grouped `use A\\{B, C};` nests its
+    clauses differently, and a function import binds a name that is never a call receiver.
+    """
+    for clause in nodes.children(node, "namespace_use_clause"):
+        target = nodes.child(clause, "qualified_name", "name")
+        if target is None:
+            continue
+        fqn = nodes.node_text(target).strip().lstrip("\\")
+        if not fqn:
+            continue
+        names.add_import(_alias_of(clause) or fqn.rsplit("\\", 1)[-1], fqn)
+
+
+def _alias_of(clause) -> str:
+    """The name `use ... as X` binds, or "" when the clause has no alias.
+
+    The alias is read as the last `name` under the clause rather than the first, because
+    `use Foo as Bar;` puts two bare `name` children side by side and the first one is the
+    imported class. Both clause shapes are handled: some grammar builds wrap the alias in a
+    `namespace_aliasing_clause`, others leave the `as` token flat among the children.
+    """
+    aliasing = nodes.child(clause, "namespace_aliasing_clause")
+    if aliasing is not None:
+        return nodes.node_text(nodes.child(aliasing, "name"))
+    if nodes.child(clause, "as") is None:
+        return ""
+    name_children = nodes.children(clause, "name")
+    return nodes.node_text(name_children[-1]) if name_children else ""
+
+
+def _open_class(node, facts: FileFacts, names: NameResolver) -> ClassScope:
+    start, end = nodes.line_span(node)
+    scope = ClassScope(
+        fqn=names.qualify_declaration(nodes.name_of(node)), start_line=start, end_line=end
+    )
+    base = nodes.child(node, "base_clause")
+    if base is not None:
+        inherited = _names_in(base, names)
+        scope.ancestors.extend(inherited)
+        if inherited:
+            scope.parent = inherited[0]
+    implemented = nodes.child(node, "class_interface_clause")
+    if implemented is not None:
+        # An interface declares the method too, so it answers "does this member exist" even
+        # though it never answers "what runs".
+        scope.ancestors.extend(_names_in(implemented, names))
+    facts.classes.append(scope)
+    return scope
+
+
+def _names_in(node, names: NameResolver) -> list[str]:
+    """Every class name listed in a clause, resolved. `extends A, B` and `use T, U` both list."""
+    out = []
+    for child in nodes.children(node, "name", "qualified_name"):
+        text = nodes.node_text(child).strip()
+        if text:
+            out.append(names.resolve(text))
+    return out
+
+
+def _open_method(node, klass: ClassScope) -> MethodScope:
+    start, end = nodes.line_span(node)
+    scope = MethodScope(name=nodes.name_of(node), start_line=start, end_line=end)
+    klass.methods.append(scope)
+    return scope

graphify_php/syntax/names.py

@@ -0,0 +1,49 @@
+"""Turning a source-level type name into a fully qualified one.
+
+Its own module because this is where a resolver fabricates edges. A name written `Emails` in
+one file and `Emails` in another is two different classes unless the file's `namespace` and
+`use` lines say otherwise, and a resolver that matches on the short name links them anyway.
+Six upstream issues across four code-graph projects trace their false edges to exactly that
+fallback, so there is no fallback here: a name this file cannot see stays unqualified against
+the file's own namespace and simply fails to match anything real.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class NameResolver:
+    """The `namespace` and `use` lines of one file, and nothing else.
+
+    Deliberately holds no corpus-wide index. Without one it is not possible to answer "is
+    there a class called `Emails` somewhere?", which is the question whose answer is always a
+    guess.
+    """
+
+    namespace: str = ""
+    imports: dict[str, str] = field(default_factory=dict)  # alias -> FQN
+
+    def resolve(self, name: str) -> str:
+        """PHP's own order: absolute, then alias, then relative to the file's namespace."""
+        if not name:
+            return name
+        if name.startswith("\\"):
+            return name.lstrip("\\")
+        head, _, tail = name.partition("\\")
+        alias = self.imports.get(head)
+        if alias is not None:
+            return f"{alias}\\{tail}" if tail else alias
+        if self.namespace:
+            return f"{self.namespace}\\{name}"
+        return name
+
+    def qualify_declaration(self, short: str) -> str:
+        """The FQN of a class declared in this file."""
+        if not short:
+            return short
+        return f"{self.namespace}\\{short}" if self.namespace else short
+
+    def add_import(self, alias: str, fqn: str) -> None:
+        self.imports[alias] = fqn.lstrip("\\")

graphify_php/syntax/nodes.py

@@ -0,0 +1,209 @@
+"""Tree-sitter primitives shared by the collectors.
+
+Kept separate from the collectors so that a collector is about one type source and nothing
+else: the moment `type_name` lived next to the walker, every new source meant editing the
+walker too.
+
+Nothing here knows what a type source is, and nothing here knows about `ports`. The whole
+module is "ask the grammar a question", so it changes when tree-sitter-php changes and for no
+other reason.
+"""
+
+from __future__ import annotations
+
+try:  # both ship with graphify, so this is reuse rather than a new dependency
+    import tree_sitter as ts
+    import tree_sitter_php as tsp
+except ImportError:  # pragma: no cover - exercised only on a broken install
+    ts = None
+    tsp = None
+
+# Type positions in the grammar. A declaration carries exactly one of these as a child, so the
+# collectors name the set once here instead of repeating it at every declaration site.
+TYPE_KINDS = (
+    "named_type",
+    "union_type",
+    "optional_type",
+    "primitive_type",
+    "intersection_type",
+    "disjunctive_normal_form_type",  # `(A&B)|C`, a disjunction whose branches are intersections
+)
+
+CLASS_KINDS = (
+    "class_declaration",
+    "trait_declaration",
+    "interface_declaration",
+    "enum_declaration",
+)
+
+# A closure's parameters and `use` clause bind names of their own, and its body is not the
+# enclosing method's body. Both grammar names for the `function () {}` form are listed because
+# tree-sitter-php renamed the node between releases and graphify does not pin the version.
+CLOSURE_KINDS = (
+    "anonymous_function",
+    "anonymous_function_creation_expression",
+    "arrow_function",
+)
+
+_PARSER = None
+
+
+def tree_sitter_available() -> tuple[bool, str]:
+    if ts is None or tsp is None:
+        return False, "tree_sitter and tree_sitter_php are not importable"
+    return True, ""
+
+
+def parser():
+    """The one parser instance for this process.
+
+    Reused rather than rebuilt per file: constructing the Language and Parser dominates the
+    cost of parsing a single small file, and a build walks every PHP file in the repository.
+    """
+    global _PARSER
+    if _PARSER is None:
+        ok, why = tree_sitter_available()
+        if not ok:
+            raise RuntimeError(why)
+        _PARSER = ts.Parser(ts.Language(tsp.language_php()))
+    return _PARSER
+
+
+def parse(source: bytes):
+    return parser().parse(source)
+
+
+def node_text(node) -> str:
+    """Source text of a node.
+
+    py-tree-sitter keeps the bytes it parsed on the node, so nothing downstream has to carry
+    the buffer alongside every node it handles.
+    """
+    if node is None:
+        return ""
+    raw = node.text
+    return raw.decode("utf-8", "replace") if raw is not None else ""
+
+
+def child(node, *kinds):
+    """First direct child of any of `kinds`, or None.
+
+    Direct children only. A recursive search would reach into a nested declaration and read a
+    type belonging to another scope, which is the mistake this whole package exists to avoid.
+    """
+    if node is None:
+        return None
+    for candidate in node.children:
+        if candidate.type in kinds:
+            return candidate
+    return None
+
+
+def children(node, *kinds):
+    if node is None:
+        return []
+    return [c for c in node.children if c.type in kinds]
+
+
+def name_of(node) -> str:
+    """The declared identifier of a class or method declaration."""
+    return node_text(child(node, "name"))
+
+
+def variable_of(node) -> str:
+    """The bare name of a `variable_name` child, with the sigil removed."""
+    return node_text(child(node, "variable_name")).lstrip("$")
+
+
+def line_span(node) -> tuple[int, int]:
+    """1-based inclusive line span, matching how every other tool reports a location."""
+    return node.start_point[0] + 1, node.end_point[0] + 1
+
+
+def type_node(node):
+    """The type annotation of a declaration, or None when it is untyped."""
+    return child(node, *TYPE_KINDS)
+
+
+def is_union(node) -> bool:
+    """Is this type position an alternation — the object is ONE OF several classes?
+
+    `A|B` and `(A&B)|C` both are: there are two candidate targets and nothing in the type says
+    which. An intersection is deliberately not here. `A&B` is one object that is both things
+    at once, so a method declared in only one constituent is an unambiguous target, and
+    `intersection_members` handles it instead.
+    """
+    if node is None:
+        return False
+    if node.type in ("union_type", "disjunctive_normal_form_type"):
+        return True
+    if node.type == "optional_type":
+        return any(is_union(c) for c in node.children)
+    return False
+
+
+def intersection_members(node) -> list[str]:
+    """The class names of an `A&B` type, or [] when this is not an intersection.
+
+    Only class names are returned: `A&int` is not expressible in PHP, so a member that reads
+    as a keyword is a parse this code does not understand and is dropped rather than guessed.
+    """
+    if node is None:
+        return []
+    if node.type == "optional_type":
+        for child in node.children:
+            found = intersection_members(child)
+            if found:
+                return found
+        return []
+    if node.type != "intersection_type":
+        return []
+    names = []
+    for child in node.children:
+        name = type_name(child)
+        if name:
+            names.append(name)
+    return names
+
+
+def type_name(node) -> str | None:
+    """Return a single class name from a type node, or None when it is not one class.
+
+    Nullable `?Foo` yields `Foo`: null is not an object target, so the call still reaches
+    `Foo::method` when it happens at all. A union `Foo|Bar` yields None — both alternatives
+    are real targets and this version cannot express two, so it records nothing rather than
+    picking one. `array`, `string`, `int` and friends yield None: they own no methods.
+
+    `self`, `static` and `parent` yield None as well. They name a declaration, not the runtime
+    class, and treating them as a class is how late static binding turns into a wrong edge.
+    """
+    if node is None:
+        return None
+    if node.type in (
+        "union_type",
+        "disjunctive_normal_form_type",
+        "intersection_type",
+        "primitive_type",
+    ):
+        return None
+    if node.type in ("optional_type", "nullable_type"):
+        for candidate in node.children:
+            found = type_name(candidate)
+            if found:
+                return found
+        return None
+    if node.type in ("named_type", "qualified_name", "name"):
+        raw = node_text(node).strip().lstrip("?").strip()
+        if not raw:
+            return None
+        # PHP keyword types and relative scopes are all lower case; user classes conventionally
+        # are not. The check is on the first character so that an unknown future keyword is
+        # refused rather than fabricated into a class.
+        if raw[0].islower():
+            return None
+        return raw
+    for candidate in node.children:
+        found = type_name(candidate)
+        if found:
+            return found
+    return None