graphify-php 0.0.5__py3-none-any.whl

graphify_php/config_resolver.py

@@ -0,0 +1,164 @@
+"""The configuration pass graphify runs, and the status record that proves it ran.
+
+A `LanguageResolver`, not a `CallTargetSource`. The distinction is not bookkeeping: a
+`CallTargetSource` answers "what does this call site call" and is offered sites by the
+member-call resolver, while this pass reads files no call site mentions and produces nodes that
+do not exist yet. Forcing it into that port would mean inventing call sites to carry facts that
+are not calls.
+
+WHY THE SUFFIX GATE SAYS `.php` WHILE THIS READS `.yaml`
+
+graphify activates a registered resolver only when the corpus it is building holds a file with
+one of the resolver's suffixes (`resolver_registry.run_language_resolvers`). YAML is not in that
+corpus: `detect.py:45` lists `.yaml` and `.yml` in `DOC_EXTENSIONS`, so a YAML file takes the
+document path and never reaches the code extractor. Measured on a fixture of one PHP file and one
+`config/packages/messenger.yaml`, built with two probe resolvers registered: the `.php`-gated
+probe ran, the `.yaml`-gated probe did not, and the published graph held 3 nodes, none of them
+from the YAML file.
+
+So a `.yaml` gate would never fire and this pass would be dead code that looks registered. The
+gate is `.php` — "this is a PHP repository, so it may be a Symfony application" — and the files
+are found by walking `config/` under the repository root rather than by reading the corpus. The
+two are deliberately about different files.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING
+
+from . import status
+from .resolver import PHP_SUFFIXES
+
+if TYPE_CHECKING:
+    from .config import ConfigFileFinder, GraphWriter, SafeDocumentParser
+    from .config.ports import ConfigFactReader
+
+RESOLVER_NAME = "php_symfony_config"
+
+# Reasons this module owns. A reader's own reasons arrive prefixed with the reader's name, so
+# the histogram stays a work list rather than a pile of colliding words.
+REASON_NO_FACTS = "document_held_no_indexed_fact"
+# `config.safe_yaml` imports pyyaml, which graphify does not depend on. The package is therefore
+# imported inside `run`, so that a build without pyyaml records this skip instead of failing
+# at import — before any record could be written.
+REASON_PYYAML_MISSING = "pyyaml-not-installed"
+
+
+def run(
+    per_file: Sequence[dict],
+    all_nodes: list[dict],
+    all_edges: list[dict],
+    *,
+    repo_root: str = ".",
+    readers: Sequence[ConfigFactReader] | None = None,
+    finder: ConfigFileFinder | None = None,
+    parser: SafeDocumentParser | None = None,
+    writer: GraphWriter | None = None,
+) -> status.ResolverStatus:
+    """Index the configuration facts under `repo_root`, and record what happened either way."""
+    record = status.ResolverStatus(name=RESOLVER_NAME)
+    try:
+        try:
+            from . import config as cfg
+        except ImportError as exc:
+            if getattr(exc, "name", None) != "yaml":
+                raise
+            record.state = "skipped"
+            record.reason = REASON_PYYAML_MISSING
+            return record
+
+        finder = finder or cfg.ConfigFileFinder(repo_root)
+        available, why_not = finder.available()
+        if not available:
+            # Most repositories graphify indexes are not Symfony applications. Recording this
+            # as a skip with its reason is what keeps "not applicable here" distinguishable
+            # from "registered but silently did nothing", which are the same artifact otherwise.
+            record.state = "skipped"
+            record.reason = why_not
+            return record
+
+        parser = parser or cfg.SafeDocumentParser()
+        readers = readers if readers is not None else cfg.default_readers()
+        writer = writer or cfg.GraphWriter(all_nodes, all_edges)
+        documents = cfg.DocumentNodeFactory()
+
+        files = finder.find()
+        record.files_seen = len(files)
+        record.eligible_sites = len(files)
+        for relative_path, absolute_path in files:
+            parsed = parser.parse(absolute_path)
+            if parsed.data is None:
+                # A malformed file costs that file. It is counted by name and the pass carries
+                # on, because one bad indent must not decide whether the rest is indexed.
+                record.unresolvable(f"{parser.__class__.__name__.lower()}:{parsed.reason}")
+                continue
+            document = cfg.ConfigDocument(path=relative_path, data=parsed.data)
+            collected = cfg.FactSet()
+            for reader in readers:
+                facts = reader.read(document)
+                for reason, count in facts.unresolved.items():
+                    record.unresolvable(f"{reader.name}:{reason}", count)
+                facts.unresolved.clear()
+                collected.extend(facts)
+            if not collected.nodes and not collected.edges:
+                record.unresolvable(REASON_NO_FACTS)
+                continue
+            # The file node goes in ahead of the readers' own, because every edge they produce
+            # starts at it and the writer resolves an endpoint only to a node already written.
+            collected.nodes.insert(0, documents.node(relative_path))
+            writer.write(collected)
+            record.resolved_sites += 1
+
+        for reason, count in writer.unresolved.items():
+            record.unresolvable(reason, count)
+        record.edges_added = writer.edges_added
+        record.state = "completed"
+        return record
+    except Exception as exc:
+        record.state = "failed"
+        record.reason = f"{type(exc).__name__}: {exc}"
+        raise
+    finally:
+        record.finished_at = time.time()
+        status.write([record])
+
+
+def make_resolver(
+    repo_root: str = ".", readers_factory: Callable[[], Sequence[ConfigFactReader]] | None = None
+):
+    """Wrap `run` in the `(per_file, all_nodes, all_edges) -> None` shape graphify calls.
+
+    The readers are assembled at resolution time, not at registration time: registration happens
+    at import, before the repository under build is settled. `None` means the shipped readers,
+    which `run` names itself so that nothing here imports the config package.
+    """
+
+    def resolve(per_file, all_nodes, all_edges) -> None:
+        readers = readers_factory() if readers_factory is not None else None
+        run(per_file, all_nodes, all_edges, repo_root=repo_root, readers=readers)
+
+    resolve.__name__ = RESOLVER_NAME
+    return resolve
+
+
+def register(repo_root: str = ".") -> bool:
+    """Register this pass with graphify. Returns whether this call did the registering.
+
+    Idempotent by name: graphify runs its registry in order without deduplicating, so a double
+    registration would run the pass twice and the second run would find every node already
+    present and report a build that did nothing.
+    """
+    from graphify import resolver_registry
+
+    if any(r.name == RESOLVER_NAME for r in resolver_registry.registered_resolvers()):
+        return False
+    resolver_registry.register(
+        resolver_registry.LanguageResolver(
+            name=RESOLVER_NAME,
+            suffixes=PHP_SUFFIXES,
+            resolve=make_resolver(repo_root),
+        )
+    )
+    return True

graphify_php/container/__init__.py

@@ -0,0 +1,50 @@
+"""Symfony container overlay: which implementation actually arrives at an injection site.
+
+Measured on the reference application: of 715 injected properties, 652 carry a concrete class
+and 63 an interface. The 652 are already answered from source by the package's existing
+sources. The remaining 63 cannot be — the type engine can only say `LoggerInterface`, and which
+concrete service arrives is decided by the container, not by the code. This package reads that
+decision out of the compiled container and writes it as an overlay, never as graph edges.
+
+Four units, one concern each: `locator` finds the file, `reader` parses one format, `facts`
+models what was found, `overlay` writes the artifact. `layer` composes them and records a
+status. A second container format is a second `ContainerReader`, not a branch in the first.
+"""
+
+from __future__ import annotations
+
+from .facts import (
+    Alias,
+    ArgumentKind,
+    ContainerFacts,
+    Decoration,
+    Injection,
+    Member,
+    Service,
+    TagMembership,
+)
+from .layer import LAYER_NAME, ContainerOverlayLayer
+from .locator import SymfonyCacheLocator
+from .overlay import ARTIFACT_KIND, RELATION, OverlayWriter
+from .ports import ContainerLocator, ContainerReader
+from .reader import SymfonyXmlContainerReader
+
+__all__ = [
+    "ARTIFACT_KIND",
+    "Alias",
+    "ArgumentKind",
+    "ContainerFacts",
+    "ContainerLocator",
+    "ContainerOverlayLayer",
+    "ContainerReader",
+    "Decoration",
+    "Injection",
+    "LAYER_NAME",
+    "Member",
+    "OverlayWriter",
+    "RELATION",
+    "Service",
+    "SymfonyCacheLocator",
+    "SymfonyXmlContainerReader",
+    "TagMembership",
+]

graphify_php/container/facts.py

@@ -0,0 +1,178 @@
+"""What a compiled DI container says, modelled without reference to any file format.
+
+This is the middle of three units: `reader` turns one container format into these objects,
+`overlay` turns these objects into an artifact. A second container format (a Laravel dump, a
+PHP-DI compiled file) is a second reader against this model, never a branch inside the first.
+
+Two rules are carried by the model itself rather than by discipline in the reader.
+
+**No values, ever.** An argument keeps its KIND (`service`, `scalar`, `env`, ...) and, for an
+env reference, only the variable NAME. There is no field to put a DSN, a password, a default
+or an expanded `%env(...)%` in, so a reader cannot leak one by being careless. `eval/canaries.py`
+plants fake secrets and asserts they reach no artifact; the absence of the field is what makes
+that hold by construction.
+
+**Injection-site identity.** Measured on the reference application: 715 injected properties,
+652 with a concrete class (resolved from source by the existing sources) and 63 with an
+interface — 8%. Those 63 are why this exists, and a global interface-to-class map would answer
+them wrongly: named aliases, per-argument bindings, decorators and contextual wiring all make
+the same interface arrive as different classes at different parameters. So the unit of this
+model is `Injection` — consumer, member, position — not "what implements X".
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class ArgumentKind(str, Enum):
+    """The kind of thing wired into one argument slot. Never the thing itself."""
+
+    SERVICE = "service"  # a reference to another service id
+    SERVICE_CLOSURE = "service_closure"  # a lazy reference; same target, deferred
+    TAGGED_ITERATOR = "tagged_iterator"  # every service carrying a tag
+    ITERATOR = "iterator"  # an explicit list of service references
+    COLLECTION = "collection"  # a structured literal; its leaves are scalars
+    ENV = "env"  # a `%env(...)%` reference, name kept, value not
+    SCALAR = "scalar"  # a literal. Recorded as a kind and discarded.
+    ABSTRACT = "abstract"  # an unfilled slot in an abstract definition
+    CONSTANT = "constant"  # a PHP constant reference
+    UNKNOWN = "unknown"
+
+
+class Member(str, Enum):
+    """Where in the consumer the argument lands."""
+
+    CONSTRUCTOR = "constructor"
+    CALL = "call"  # a setter or any other post-construction method call
+    FACTORY = "factory"  # an argument to the factory, not to the constructor
+    PROPERTY = "property"
+
+
+@dataclass(frozen=True)
+class Service:
+    """One service definition. `class_fqn` is None for a synthetic or alias-only entry."""
+
+    service_id: str
+    class_fqn: str | None
+    public: bool = False
+    abstract: bool = False
+    lazy: bool = False
+    synthetic: bool = False
+    factory_class: str | None = None
+    factory_service: str | None = None
+    factory_method: str | None = None
+    # A named constructor (`constructor="fromCallable"`): the class is instantiated through a
+    # static method, so a consumer looking for `__construct` would find the wrong signature.
+    constructor: str | None = None
+
+
+@dataclass(frozen=True)
+class Alias:
+    """`alias_id` resolves to `target_id`. The interface-to-implementation edge, when the
+    alias id happens to be an interface name — which the container never states, so the
+    reader does not claim it either."""
+
+    alias_id: str
+    target_id: str
+    public: bool = False
+
+
+@dataclass(frozen=True)
+class Injection:
+    """One argument slot of one consumer, and what the container puts in it.
+
+    `position` is the 0-based index among the consumer's arguments. `parameter` is the
+    parameter NAME and is almost always None: the compiled XML keeps argument order, not
+    signatures. Recorded as a field anyway because a reader for a format that does keep names
+    can fill it, and a consumer joining on position must be able to tell "unnamed" from
+    "unknown".
+    """
+
+    consumer_id: str
+    consumer_class: str | None
+    member: Member
+    member_name: str | None  # the method for Member.CALL, None for a constructor
+    position: int
+    parameter: str | None
+    kind: ArgumentKind
+    requested_id: str | None = None  # the service id written in the definition
+    resolved_id: str | None = None  # after following aliases
+    resolved_class: str | None = None  # the class that actually arrives here
+    via_alias: bool = False
+    tag: str | None = None  # for TAGGED_ITERATOR, the tag being collected
+    env_name: str | None = None  # for ENV, the variable name. Never its value.
+
+
+@dataclass(frozen=True)
+class TagMembership:
+    tag: str
+    service_id: str
+    class_fqn: str | None
+    attributes: dict = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Decoration:
+    """`decorator_id` wraps `inner_id`, which holds the definition that was displaced.
+
+    The compiled container has no `decorates` attribute: Symfony applies decoration at compile
+    time, renaming the decorated definition to `<id>.inner` and giving its id to the decorator.
+    Measured on the reference application: 0 occurrences of `decorates=`, 28 services whose id
+    ends in `.inner`. So decoration is recovered from that renaming, and the field name says
+    what was observed rather than what was declared.
+    """
+
+    decorator_id: str
+    decorator_class: str | None
+    inner_id: str
+    inner_class: str | None
+
+
+@dataclass
+class ContainerFacts:
+    """Everything one container file states, plus what the reader refused and why."""
+
+    services: dict[str, Service] = field(default_factory=dict)
+    aliases: dict[str, Alias] = field(default_factory=dict)
+    injections: list[Injection] = field(default_factory=list)
+    tags: list[TagMembership] = field(default_factory=list)
+    decorations: list[Decoration] = field(default_factory=list)
+    environment: dict = field(default_factory=dict)
+    skipped: dict[str, int] = field(default_factory=dict)
+
+    def skip(self, reason: str, count: int = 1) -> None:
+        """Count a fact left out, under a fixed reason.
+
+        Free-text reasons produce a histogram of unique strings, which is not a work list.
+        """
+        self.skipped[reason] = self.skipped.get(reason, 0) + count
+
+    def resolve_id(self, service_id: str, _depth: int = 0) -> str:
+        """Follow aliases to the id that is actually instantiated.
+
+        Bounded depth because an alias cycle in a hand-written container would otherwise hang
+        the build, and a build that hangs is indistinguishable from one that is slow.
+        """
+        seen = service_id
+        for _ in range(16):
+            alias = self.aliases.get(seen)
+            if alias is None:
+                return seen
+            seen = alias.target_id
+        return seen
+
+    def class_of(self, service_id: str) -> str | None:
+        service = self.services.get(self.resolve_id(service_id))
+        return service.class_fqn if service else None
+
+    @property
+    def interface_bindings(self) -> list[Alias]:
+        """Aliases whose id looks like a PHP interface name.
+
+        `Interface` suffix only, which is a convention and not a guarantee — the container
+        states no such thing. Kept as a derived view so nothing downstream mistakes it for a
+        fact the container asserted.
+        """
+        return [a for a in self.aliases.values() if a.alias_id.endswith("Interface")]

graphify_php/container/layer.py

@@ -0,0 +1,71 @@
+"""Runs locate -> read -> write, and records the outcome the way every other layer does.
+
+The status record is not bookkeeping. graphify swallows a resolver exception and logs a
+warning, so a layer that dies and a layer that was never registered look the same from outside
+— and both look like a project that simply has little wiring. This layer therefore reports
+`completed`, `skipped` with a reason, or `failed`, exactly as `status.py` intends, and no
+absent container is ever a failure: the XML dump exists only when `kernel.debug` is on.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from ..status import ResolverStatus
+from . import reasons
+from .locator import SymfonyCacheLocator
+from .overlay import DEFAULT_ARTIFACT_NAME, OverlayWriter
+from .ports import ContainerLocator, ContainerReader
+from .reader import SymfonyXmlContainerReader
+
+LAYER_NAME = "php_container_overlay"
+
+
+class ContainerOverlayLayer:
+    """Composition only. Every decision it could make belongs to one of its three parts."""
+
+    def __init__(
+        self,
+        locator: ContainerLocator | None = None,
+        reader: ContainerReader | None = None,
+        writer: OverlayWriter | None = None,
+    ) -> None:
+        self._locator = locator or SymfonyCacheLocator()
+        self._reader = reader or SymfonyXmlContainerReader()
+        self._writer = writer or OverlayWriter()
+
+    def run(
+        self, repo_root: Path, out_dir: Path, name: str = DEFAULT_ARTIFACT_NAME
+    ) -> ResolverStatus:
+        record = ResolverStatus(name=LAYER_NAME)
+        path, reason = self._locator.locate(Path(repo_root))
+        if path is None:
+            return self._skip(record, reason)
+
+        record.files_seen = 1
+        facts = self._reader.read(path)
+        if facts is None:
+            # Unreadable and malformed are one outcome here on purpose: both mean "there is a
+            # file and it did not parse", and the reader is the only thing that could tell
+            # them apart without a second stat call racing the cache being rewritten.
+            return self._skip(record, reasons.SKIP_XML_MALFORMED)
+
+        counts = self._writer.counts(facts)
+        artifact = self._writer.write(facts, Path(out_dir), name)
+        record.eligible_sites = counts["injection_sites"]
+        record.resolved_sites = counts["injection_sites_resolved_to_class"]
+        # Not graph edges. Counted under the same field because the build gate reads that
+        # field; `state`/`reason` and the artifact itself say what these actually are.
+        record.edges_added = counts["injection_sites_resolved_to_class"]
+        record.unresolved = dict(facts.skipped)
+        record.state = "completed"
+        record.reason = f"{artifact}"
+        record.finished_at = time.time()
+        return record
+
+    def _skip(self, record: ResolverStatus, reason: str) -> ResolverStatus:
+        record.state = "skipped"
+        record.reason = reason
+        record.finished_at = time.time()
+        return record

graphify_php/container/locator.py

@@ -0,0 +1,74 @@
+"""Finds the compiled container, and distinguishes the several ways there can be none.
+
+The distinction is the whole job. `var/cache/prod/` on a machine that never ran with
+`kernel.debug` on has no XML dump at all — Symfony writes the human-readable XML only for the
+debug container — so "no file" is the ordinary state of a production checkout and must not be
+reported the same way as "this is not a Symfony project" or "the file is there and broken".
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from . import reasons
+
+# Both halves of a Symfony install: the framework itself, and the bundle that compiles the
+# container the dump comes from. Either one present is enough to call the project Symfony.
+_SYMFONY_MARKERS = (
+    "symfony/framework-bundle",
+    "symfony/http-kernel",
+    "symfony/dependency-injection",
+)
+
+
+class SymfonyCacheLocator:
+    """Looks in `var/cache/*/` for `*Container.xml`."""
+
+    name = "symfony-var-cache"
+
+    def __init__(self, preferred_environments: tuple[str, ...] = ("dev", "test")) -> None:
+        # Preference, not a filter: a project with a custom environment name still gets found,
+        # it just gets picked after the conventional ones.
+        self._preferred = preferred_environments
+
+    def locate(self, repo_root: Path) -> tuple[Path | None, str]:
+        composer = repo_root / "composer.json"
+        if not composer.exists():
+            return None, reasons.SKIP_NOT_PHP_PROJECT
+        if not self._is_symfony(composer):
+            return None, reasons.SKIP_NOT_SYMFONY
+
+        cache_root = repo_root / "var" / "cache"
+        if not cache_root.is_dir():
+            return None, reasons.SKIP_NO_CACHE_DIR
+
+        candidates: list[tuple[int, Path]] = []
+        for environment_dir in sorted(p for p in cache_root.iterdir() if p.is_dir()):
+            rank = (
+                self._preferred.index(environment_dir.name)
+                if environment_dir.name in self._preferred
+                else len(self._preferred)
+            )
+            for candidate in sorted(environment_dir.glob("*Container.xml")):
+                # A link under `var/cache` can point anywhere on the machine; following it
+                # would read a file outside the repository under the repository's name.
+                if candidate.is_symlink():
+                    continue
+                candidates.append((rank, candidate))
+        if not candidates:
+            return None, reasons.SKIP_XML_ABSENT
+        candidates.sort(key=lambda item: (item[0], str(item[1])))
+        return candidates[0][1], ""
+
+    def _is_symfony(self, composer: Path) -> bool:
+        try:
+            manifest = json.loads(composer.read_text(encoding="utf-8", errors="replace"))
+        except (ValueError, OSError):
+            return False
+        required = {}
+        for section in ("require", "require-dev"):
+            value = manifest.get(section)
+            if isinstance(value, dict):
+                required.update(value)
+        return any(marker in required for marker in _SYMFONY_MARKERS)