graphify-php 0.0.5__py3-none-any.whl

graphify_php/container/overlay.py

@@ -0,0 +1,149 @@
+"""Serialises container facts into an overlay artifact written beside the graph.
+
+**Why this is not graph edges.** The mesh that consumes these graphs enforces one invariant: a
+cross-project overlay is never merged into the structural graph, and a forbidden-edge validator
+checks it. The reason is that the structural graph claims to describe the code, while every
+fact in here is true only of one environment and one build profile — `kernel.environment: dev`,
+with the debug bundle loaded, on the machine that compiled the cache. A `calls` edge asserted
+from a dev container would be a claim about the code that the code does not make.
+
+So: a separate file, a relation name of this layer's own (`binds_injection_to`), the
+environment recorded inside the artifact, and `structural: false` stated rather than implied.
+A consumer joins it against the graph at query time, and a consumer that does not want
+environment-dependent facts simply does not read the file.
+
+**Why there is no value anywhere in the output.** The artifact is assembled only from the
+fields of `facts`, and that model has nowhere to put a value. An env reference contributes its
+variable NAME; a scalar contributes the word `scalar`. `eval/canaries.py` plants fake secrets
+and asserts none reaches an artifact — this writer passes by construction, not by filtering.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import asdict
+from pathlib import Path
+
+from .facts import ArgumentKind, ContainerFacts, Injection
+
+SCHEMA = 1
+RELATION = "binds_injection_to"
+ARTIFACT_KIND = "container-overlay"
+DEFAULT_ARTIFACT_NAME = "container-overlay.json"
+
+# Kinds that name another service, and so make an injection site joinable to a class node.
+_BINDING_KINDS = (
+    ArgumentKind.SERVICE,
+    ArgumentKind.SERVICE_CLOSURE,
+    ArgumentKind.TAGGED_ITERATOR,
+)
+
+
+class OverlayWriter:
+    """Builds the artifact and, separately, writes it.
+
+    Split so a caller can assert on the document without a filesystem, which is what every
+    test here does.
+    """
+
+    def __init__(self, relation: str = RELATION) -> None:
+        self._relation = relation
+
+    def build(self, facts: ContainerFacts) -> dict:
+        bindings = [self._binding(i) for i in facts.injections]
+        return {
+            "schema": SCHEMA,
+            "kind": ARTIFACT_KIND,
+            "producer": "graphify-php.container",
+            "relation": self._relation,
+            # Stated, not implied. The validator on the consuming side rejects an overlay that
+            # claims to be structural, and a future writer that flips this is making a visible
+            # change rather than a quiet one.
+            "structural": False,
+            "generated_at": time.time(),
+            "environment": dict(facts.environment),
+            "counts": self.counts(facts),
+            "aliases": [
+                {
+                    "alias": a.alias_id,
+                    "target": a.target_id,
+                    "target_class": facts.class_of(a.target_id),
+                }
+                for a in sorted(facts.aliases.values(), key=lambda a: a.alias_id)
+            ],
+            "bindings": bindings,
+            "tags": [
+                {
+                    "tag": t.tag,
+                    "service": t.service_id,
+                    "class": t.class_fqn,
+                    "attributes": t.attributes,
+                }
+                for t in facts.tags
+            ],
+            "decorations": [asdict(d) for d in facts.decorations],
+            "factories": [
+                {
+                    "service": s.service_id,
+                    "class": s.class_fqn,
+                    "factory_class": s.factory_class,
+                    "factory_service": s.factory_service,
+                    "factory_method": s.factory_method,
+                    "constructor": s.constructor,
+                }
+                for s in facts.services.values()
+                if s.factory_class or s.factory_service or s.constructor
+            ],
+            "dropped": dict(facts.skipped),
+        }
+
+    def counts(self, facts: ContainerFacts) -> dict:
+        interface_bindings = [
+            a for a in facts.interface_bindings if facts.class_of(a.target_id) is not None
+        ]
+        resolved = [i for i in facts.injections if i.resolved_class]
+        return {
+            "services": len(facts.services),
+            "aliases": len(facts.aliases),
+            "interface_bindings": len(interface_bindings),
+            "injection_sites": len(facts.injections),
+            # The denominator travels with the numerator: "resolved 2900" says nothing without
+            # "out of 8389", and a regression that halves coverage still looks large alone.
+            "injection_sites_resolved_to_class": len(resolved),
+            "tag_memberships": len(facts.tags),
+            "distinct_tags": len({t.tag for t in facts.tags}),
+            "decorations": len(facts.decorations),
+            "env_arguments": len([i for i in facts.injections if i.kind is ArgumentKind.ENV]),
+        }
+
+    def write(
+        self, facts: ContainerFacts, out_dir: Path, name: str = DEFAULT_ARTIFACT_NAME
+    ) -> Path:
+        out_dir.mkdir(parents=True, exist_ok=True)
+        path = out_dir / name
+        path.write_text(json.dumps(self.build(facts), indent=2, sort_keys=False))
+        return path
+
+    def _binding(self, injection: Injection) -> dict:
+        document = {
+            "relation": self._relation,
+            "consumer_service": injection.consumer_id,
+            "consumer_class": injection.consumer_class,
+            "member": injection.member.value,
+            "member_name": injection.member_name,
+            "position": injection.position,
+            "parameter": injection.parameter,
+            "kind": injection.kind.value,
+        }
+        if injection.kind in _BINDING_KINDS or injection.requested_id:
+            document["requested_service"] = injection.requested_id
+            document["resolved_service"] = injection.resolved_id
+            document["resolved_class"] = injection.resolved_class
+            document["via_alias"] = injection.via_alias
+        if injection.tag:
+            document["tag"] = injection.tag
+        if injection.kind is ArgumentKind.ENV:
+            # The name only. There is no branch anywhere in this file that reads a value.
+            document["env_name"] = injection.env_name
+        return document

graphify_php/container/ports.py

@@ -0,0 +1,40 @@
+"""The seam between "read a container format" and "everything else".
+
+Only two protocols, because only two things vary: where the compiled container is, and how to
+parse it. The model (`facts`) and the artifact (`overlay`) do not vary with the format.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from .facts import ContainerFacts
+
+
+@runtime_checkable
+class ContainerLocator(Protocol):
+    """Finds a compiled container in a repository, or says why there is none."""
+
+    name: str
+
+    def locate(self, repo_root: Path) -> tuple[Path | None, str]:
+        """Return (path, reason). A None path always carries a reason from the fixed
+        vocabulary in `reasons.py` — never free text, and never an exception: a repository
+        that is not Symfony, and a production cache built with `kernel.debug` off, both
+        legitimately have no file here."""
+
+
+@runtime_checkable
+class ContainerReader(Protocol):
+    """Turns one container file into facts."""
+
+    name: str
+    format: str  # recorded in the artifact, so a consumer knows which reader spoke
+
+    def read(self, path: Path) -> ContainerFacts | None:
+        """Facts, or None when the file is unreadable or malformed.
+
+        None rather than an exception: a truncated cache file is a normal condition of a
+        cache directory being rewritten under us, and the layer counts it as a skip reason.
+        """

graphify_php/container/reader.py

@@ -0,0 +1,330 @@
+"""Reads a Symfony compiled container dump (`*Container.xml`) into `facts`.
+
+This is the only module that knows the Symfony XML schema. It runs no PHP, boots no kernel and
+opens nothing but the one file it is given: the compiled dump already contains the result of
+every compiler pass, so the answer to "which implementation is injected here" is a parse, not
+an execution. `phpstan-symfony` reads the same file for the same reason.
+
+What the compiled form does to the declarations, and what this reader therefore has to undo:
+
+- Interface bindings survive as `<service id="…Interface" alias="…"/>`. 361 of them in the
+  reference container.
+- Decoration does NOT survive as an attribute. Symfony applies it at compile time: the
+  decorated definition is renamed to `<id>.inner` and the decorator takes the original id.
+  0 occurrences of `decorates=` in the reference container against 28 `.inner` ids.
+- Parameter names do not survive at all. Arguments are positional. This is the single largest
+  gap in what a consumer can join on, and `Injection.parameter` stays None rather than being
+  filled with an index dressed up as a name.
+- `%env(FOO)%` survives unexpanded, which is exactly why only its name is taken.
+"""
+
+from __future__ import annotations
+
+import re
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+from . import reasons
+from .facts import (
+    Alias,
+    ArgumentKind,
+    ContainerFacts,
+    Decoration,
+    Injection,
+    Member,
+    Service,
+    TagMembership,
+)
+
+NS = "{http://symfony.com/schema/dic/services}"
+
+# `%env(bool:default:some_param:APP_DEBUG)%` — processors and defaults are colon-separated and
+# the variable name is always last. Only that last segment is kept; every earlier segment may
+# name a parameter whose value we are not entitled to touch. `[^()%]*` rather than `.*`: a
+# greedy body makes `%env(A)%:%env(B)%` one match with the name `%env(B`, and a DSN that merely
+# ends in `)%` would hand its tail over as a "name".
+_ENV_EXPRESSION = re.compile(r"^%env\(([^()%]*)\)%$")
+
+# What an environment variable can actually be called. Anything else in the last segment is
+# a processor argument or a stray value, and neither belongs in the overlay.
+_ENV_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+_KIND_BY_TYPE = {
+    "service": ArgumentKind.SERVICE,
+    "service_closure": ArgumentKind.SERVICE_CLOSURE,
+    "tagged_iterator": ArgumentKind.TAGGED_ITERATOR,
+    "iterator": ArgumentKind.ITERATOR,
+    "collection": ArgumentKind.COLLECTION,
+    "abstract": ArgumentKind.ABSTRACT,
+    "constant": ArgumentKind.CONSTANT,
+    "string": ArgumentKind.SCALAR,
+}
+
+# The two container parameters recorded as provenance. An allowlist, not a filter: the
+# parameters block holds project paths, mailer DSNs and API keys, so nothing is copied out of
+# it except these two, which say which build profile the overlay describes.
+_ENVIRONMENT_PARAMETERS = ("kernel.environment", "kernel.debug")
+
+
+def env_name(text: str) -> str | None:
+    """The variable name inside a `%env(...)%` expression, or None.
+
+    Returns a name and never a value: the caller has no way to obtain the expansion from here,
+    which is the point.
+    """
+    match = _ENV_EXPRESSION.match(text.strip())
+    if not match:
+        return None
+    name = match.group(1).rsplit(":", 1)[-1].strip()
+    return name if _ENV_NAME.match(name) else None
+
+
+class SymfonyXmlContainerReader:
+    """Parses one `App_*Container.xml`."""
+
+    name = "symfony-container-xml"
+    format = "symfony/compiled-container-xml"
+
+    def read(self, path: Path) -> ContainerFacts | None:
+        try:
+            # expat >= 2.7 rejects entity expansion and external entities; ParseError -> None.
+            root = ET.parse(path).getroot()  # noqa: S314
+        except ET.ParseError:
+            return None
+        except OSError:
+            return None
+        if root.tag != NS + "container":
+            return None
+
+        facts = ContainerFacts()
+        self._read_environment(root, path, facts)
+        services_root = root.find(NS + "services")
+        if services_root is None:
+            return facts
+
+        # Direct children only. A nested `<service>` is an inline anonymous definition owned by
+        # the argument it sits in; treating it as a top-level service would invent an id.
+        for element in services_root.findall(NS + "service"):
+            self._read_service(element, facts)
+
+        self._resolve_injections(facts)
+        self._read_decorations(facts)
+        return facts
+
+    # --- provenance -------------------------------------------------------------------
+
+    def _read_environment(self, root: ET.Element, path: Path, facts: ContainerFacts) -> None:
+        parameters = root.find(NS + "parameters")
+        values: dict[str, str] = {}
+        if parameters is not None:
+            for parameter in parameters.findall(NS + "parameter"):
+                key = parameter.get("key")
+                if key in _ENVIRONMENT_PARAMETERS:
+                    values[key] = (parameter.text or "").strip()
+        facts.environment = {
+            "container_file": str(path),
+            "container_class": path.stem,
+            "format": self.format,
+            "reader": self.name,
+            "kernel_environment": values.get("kernel.environment"),
+            "kernel_debug": values.get("kernel.debug"),
+        }
+
+    # --- services ---------------------------------------------------------------------
+
+    def _read_service(self, element: ET.Element, facts: ContainerFacts) -> None:
+        service_id = element.get("id")
+        if not service_id:
+            facts.skip(reasons.DROP_SERVICE_WITHOUT_ID)
+            return
+
+        alias_target = element.get("alias")
+        if alias_target:
+            facts.aliases[service_id] = Alias(
+                alias_id=service_id,
+                target_id=alias_target,
+                public=element.get("public") == "true",
+            )
+            return
+
+        factory = element.find(NS + "factory")
+        service = Service(
+            service_id=service_id,
+            class_fqn=element.get("class"),
+            public=element.get("public") == "true",
+            abstract=element.get("abstract") == "true",
+            lazy=element.get("lazy") == "true",
+            synthetic=element.get("synthetic") == "true",
+            factory_class=factory.get("class") if factory is not None else None,
+            factory_service=factory.get("service") if factory is not None else None,
+            factory_method=factory.get("method") if factory is not None else None,
+            constructor=element.get("constructor"),
+        )
+        facts.services[service_id] = service
+        if service.class_fqn is None and not service.synthetic:
+            facts.skip(reasons.DROP_SERVICE_WITHOUT_CLASS)
+
+        self._read_tags(element, service, facts)
+        # XmlDumper writes the arguments of a factory-built or named-constructor service at
+        # service level and emits `<factory/>` without children, so service-level arguments
+        # are the factory's whenever there is one. Recording them as constructor arguments
+        # would join them against a `__construct` signature they never reach.
+        if factory is not None:
+            member, member_name = Member.FACTORY, service.factory_method
+        elif service.constructor is not None:
+            member, member_name = Member.FACTORY, service.constructor
+        else:
+            member, member_name = Member.CONSTRUCTOR, None
+        self._read_arguments(element, service, member, member_name, facts)
+        for call in element.findall(NS + "call"):
+            self._read_arguments(call, service, Member.CALL, call.get("method"), facts)
+
+    def _read_tags(self, element: ET.Element, service: Service, facts: ContainerFacts) -> None:
+        for tag in element.findall(NS + "tag"):
+            tag_name = tag.get("name")
+            if not tag_name:
+                facts.skip(reasons.DROP_TAG_WITHOUT_NAME)
+                continue
+            # Tag attributes are wiring metadata — priority, event, command name, alias. They
+            # are identifiers and routing keys, so they are kept; nothing in a tag is a secret
+            # by Symfony's own design, since tags are read by compiler passes, not by code.
+            facts.tags.append(
+                TagMembership(
+                    tag=tag_name,
+                    service_id=service.service_id,
+                    class_fqn=service.class_fqn,
+                    attributes={k: v for k, v in tag.attrib.items() if k != "name"},
+                )
+            )
+
+    # --- arguments --------------------------------------------------------------------
+
+    def _read_arguments(
+        self,
+        parent: ET.Element,
+        service: Service,
+        member: Member,
+        member_name: str | None,
+        facts: ContainerFacts,
+    ) -> None:
+        for position, argument in enumerate(parent.findall(NS + "argument")):
+            facts.injections.append(
+                self._read_argument(argument, service, member, member_name, position, facts)
+            )
+
+    def _read_argument(
+        self,
+        argument: ET.Element,
+        service: Service,
+        member: Member,
+        member_name: str | None,
+        position: int,
+        facts: ContainerFacts,
+    ) -> Injection:
+        declared = argument.get("type")
+        kind = _KIND_BY_TYPE.get(declared) if declared else None
+        requested_id = argument.get("id")
+        tag = argument.get("tag")
+        name: str | None = None
+
+        if kind is None and declared is not None:
+            kind = ArgumentKind.UNKNOWN
+            facts.skip(reasons.DROP_ARGUMENT_UNKNOWN_KIND)
+        elif kind is None:
+            # No `type` attribute: a literal. The text is inspected only to tell an env
+            # reference from an ordinary scalar, and is then dropped.
+            text = argument.text or ""
+            name = env_name(text)
+            if name:
+                kind = ArgumentKind.ENV
+            elif text.strip().startswith("%env("):
+                kind = ArgumentKind.ENV
+                facts.skip(reasons.DROP_ENV_NAME_UNPARSEABLE)
+            else:
+                kind = ArgumentKind.SCALAR
+
+        if kind in (ArgumentKind.SERVICE, ArgumentKind.SERVICE_CLOSURE) and not requested_id:
+            # An inline anonymous definition: the target has no id to bind to.
+            facts.skip(reasons.DROP_INLINE_ANONYMOUS_SERVICE)
+            facts.skip(reasons.DROP_ARGUMENT_WITHOUT_TARGET)
+
+        return Injection(
+            consumer_id=service.service_id,
+            consumer_class=service.class_fqn,
+            member=member,
+            member_name=member_name,
+            position=position,
+            # Compiled Symfony XML carries no parameter names. Left None on purpose; see the
+            # module docstring.
+            parameter=None,
+            kind=kind,
+            requested_id=requested_id,
+            tag=tag,
+            env_name=name,
+        )
+
+    # --- second pass ------------------------------------------------------------------
+
+    def _resolve_injections(self, facts: ContainerFacts) -> None:
+        """Follow aliases once every service is known.
+
+        A second pass rather than resolution in place: the XML lists an alias after its target
+        as often as before it, and resolving eagerly would make the result depend on file order.
+        """
+        resolved: list[Injection] = []
+        for injection in facts.injections:
+            if injection.requested_id is None:
+                resolved.append(injection)
+                continue
+            target = facts.resolve_id(injection.requested_id)
+            service = facts.services.get(target)
+            if service is None and target not in facts.aliases:
+                facts.skip(reasons.DROP_ALIAS_TARGET_UNDEFINED)
+            resolved.append(
+                Injection(
+                    consumer_id=injection.consumer_id,
+                    consumer_class=injection.consumer_class,
+                    member=injection.member,
+                    member_name=injection.member_name,
+                    position=injection.position,
+                    parameter=injection.parameter,
+                    kind=injection.kind,
+                    requested_id=injection.requested_id,
+                    resolved_id=target,
+                    resolved_class=service.class_fqn if service else None,
+                    via_alias=target != injection.requested_id,
+                    tag=injection.tag,
+                    env_name=injection.env_name,
+                )
+            )
+        facts.injections = resolved
+
+    def _read_decorations(self, facts: ContainerFacts) -> None:
+        """Recover decoration from the `.inner` renaming, by finding who holds the reference."""
+        consumers: dict[str, str] = {}
+        for injection in facts.injections:
+            if injection.requested_id and injection.requested_id.endswith(".inner"):
+                # The decorator is the service that took over the original id, so when that
+                # service references `<id>.inner` it wins over a collector that happens to be
+                # listed first and also holds the reference.
+                owner = injection.requested_id[: -len(".inner")]
+                if injection.consumer_id == owner:
+                    consumers[injection.requested_id] = owner
+                else:
+                    consumers.setdefault(injection.requested_id, injection.consumer_id)
+        for service_id, service in facts.services.items():
+            if not service_id.endswith(".inner"):
+                continue
+            decorator_id = consumers.get(service_id)
+            if decorator_id is None:
+                facts.skip(reasons.DROP_INNER_WITHOUT_DECORATOR)
+                continue
+            decorator = facts.services.get(decorator_id)
+            facts.decorations.append(
+                Decoration(
+                    decorator_id=decorator_id,
+                    decorator_class=decorator.class_fqn if decorator else None,
+                    inner_id=service_id,
+                    inner_class=service.class_fqn,
+                )
+            )

graphify_php/container/reasons.py

@@ -0,0 +1,31 @@
+"""The fixed vocabulary for everything this layer declines to do.
+
+Two families, kept apart because they answer different questions. A SKIP_* reason explains why
+the whole layer produced nothing and appears once, in the status record. A DROP_* reason
+explains one fact left out of an artifact that was still produced, and appears as a counter.
+
+Collapsing them would hide the difference between "no container here" and "a container with
+900 unreadable arguments", which look identical in a total of zero.
+"""
+
+from __future__ import annotations
+
+# Layer-level: the overlay was not produced at all.
+SKIP_NOT_PHP_PROJECT = "container-no-composer-json"
+SKIP_NOT_SYMFONY = "container-not-a-symfony-project"
+SKIP_NO_CACHE_DIR = "container-no-cache-directory"
+SKIP_XML_ABSENT = "container-xml-absent"
+SKIP_XML_UNREADABLE = "container-xml-unreadable"
+SKIP_XML_MALFORMED = "container-xml-malformed"
+SKIP_XML_NOT_A_CONTAINER = "container-xml-wrong-root-element"
+
+# Fact-level: the overlay exists, this piece of it does not.
+DROP_SERVICE_WITHOUT_ID = "service-without-id"
+DROP_INLINE_ANONYMOUS_SERVICE = "inline-anonymous-service"
+DROP_SERVICE_WITHOUT_CLASS = "service-without-class"
+DROP_ALIAS_TARGET_UNDEFINED = "alias-target-not-defined"
+DROP_ARGUMENT_WITHOUT_TARGET = "argument-service-without-id"
+DROP_ARGUMENT_UNKNOWN_KIND = "argument-kind-unrecognised"
+DROP_ENV_NAME_UNPARSEABLE = "env-expression-without-name"
+DROP_INNER_WITHOUT_DECORATOR = "inner-service-without-decorator"
+DROP_TAG_WITHOUT_NAME = "tag-without-name"