graphify-php 0.0.5__py3-none-any.whl

graphify_php/__init__.py

@@ -0,0 +1,144 @@
+"""PHP member-call resolution for graphify.
+
+graphify ships cross-file member-call resolvers for Swift, Python, Ruby, TypeScript, C#, Java
+and Rust, and none for PHP: its PHP extractor marks `$this->emails->send()` as a member call and
+then the shared pass drops it, because a bare `send` collides across the corpus. The measured
+result on one Symfony application is 2172 `calls` edges against 3426 callable nodes — 24 % of
+callables with an outgoing call edge, 20 % with an incoming one.
+
+This package fills that gap through graphify's own extension seam, without forking it:
+
+    import graphify_php
+    graphify_php.register()
+
+`register()` is idempotent, and it imports graphify lazily so that importing this package — in a
+test, in a linter, in a tool that only wants the ports — never requires graphify to be installed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from importlib import import_module
+
+from .ports import CallTargetSource
+from .resolver import (
+    PHP_SUFFIXES,
+    RESOLVER_NAME,
+    RESOLVER_NAME_ROUTES,
+    make_resolver,
+    make_route_resolver,
+)
+
+__all__ = [
+    "RESOLVER_NAME",
+    "RESOLVER_NAME_ROUTES",
+    "default_route_sources",
+    "default_sources",
+    "register",
+]
+
+_registered = False
+
+
+def default_sources(repo_root: str = ".") -> Sequence[CallTargetSource]:
+    """Assemble the shipped `CallTargetSource` list, in precedence order.
+
+    The one place the concrete sources are named. A third source — a language server, an LSIF
+    index — becomes a line in `graphify_php.sources`, not an edit to `resolver`, which is why
+    `resolver` is handed this list instead of building it.
+
+    Sources are optional at import: this package's only hard requirement is `ports` and
+    `status`, and a build with no sources installed records a skip with a reason rather than
+    raising inside graphify's exception-swallowing driver.
+    """
+    try:
+        from . import sources as _sources
+    except ImportError:
+        return ()
+
+    # A factory inside `sources` wins when there is one: it owns its own assembly, including
+    # any constructor argument a source grows later.
+    for attribute in ("default_sources", "build_sources"):
+        factory = getattr(_sources, attribute, None)
+        if callable(factory):
+            return factory(repo_root)
+    listed = getattr(_sources, "SOURCES", None)
+    if listed:
+        return tuple(listed)
+
+    # Precedence, and the only place it is written down: the type engine knows untyped
+    # properties, chains and docblocks that the parser must refuse, so it answers first.
+    assembled: list[CallTargetSource] = []
+    for module_name, class_name in (
+        ("phpstan_source", "PhpStanSource"),
+        ("tree_sitter_source", "TreeSitterSource"),
+    ):
+        try:
+            module = import_module(f"{__name__}.sources.{module_name}")
+        except ImportError:
+            continue
+        source = getattr(module, class_name, None)
+        if source is not None:
+            assembled.append(source())
+    return tuple(assembled)
+
+
+def default_route_sources(repo_root: str = "."):
+    """The shipped `RouteDeclarationSource` list.
+
+    Separate from `default_sources` because the two ports answer different questions and a
+    source implements one or the other. Same tolerance: a missing `sources` package means an
+    empty list and a recorded skip, not an import error inside graphify's swallowing driver.
+    """
+    try:
+        module = import_module(f"{__name__}.sources.route_source")
+    except ImportError:
+        return ()
+    source = getattr(module, "TreeSitterRouteSource", None)
+    return (source(),) if source is not None else ()
+
+
+def register(
+    sources_factory=default_sources,
+    repo_root: str = ".",
+    route_sources_factory=default_route_sources,
+) -> bool:
+    """Register the PHP resolver with graphify. Returns whether this call did the registering.
+
+    Idempotent by name rather than by a flag alone: a process that imported this package twice
+    under two module paths would otherwise register twice, and graphify runs the registry in
+    order without deduplicating, so the pass would run twice and the second run would find
+    every edge already present and report zero work.
+    """
+    global _registered
+    from graphify import resolver_registry
+
+    if _registered or any(
+        r.name == RESOLVER_NAME for r in resolver_registry.registered_resolvers()
+    ):
+        _registered = True
+        return False
+
+    resolver_registry.register(
+        resolver_registry.LanguageResolver(
+            name=RESOLVER_NAME,
+            suffixes=PHP_SUFFIXES,
+            resolve=make_resolver(sources_factory, repo_root),
+        )
+    )
+    # A second pass, not a stage of the first: routes add nodes rather than connect existing
+    # ones, and a separate registration gives them a status record the build gate can require.
+    resolver_registry.register(
+        resolver_registry.LanguageResolver(
+            name=RESOLVER_NAME_ROUTES,
+            suffixes=PHP_SUFFIXES,
+            resolve=make_route_resolver(route_sources_factory, repo_root),
+        )
+    )
+    # The Symfony configuration pass. Registered here because this is the one registration a
+    # build makes; a pass left out of it never runs, however complete its own `register` is.
+    from . import config_resolver
+
+    config_resolver.register(repo_root)
+    _registered = True
+    return True

graphify_php/cli.py

@@ -0,0 +1,355 @@
+"""`graphify-php-build` — run graphify with this package registered, and gate the publish.
+
+The wrapper exists because graphify's resolver driver is deliberately forgiving:
+
+    except Exception as exc:
+        _LOG.warning("%s resolution failed, skipping: %s", resolver.name, exc)
+
+A resolver that raises is skipped and the build still publishes. A resolver that was never
+registered — because the seam moved in an upgrade, or because an install left this package out —
+is not even logged. Both produce a valid graph with fewer `calls` edges, which is exactly the
+shape of the defect this package was written to fix, so the failure is invisible at the one
+moment it matters.
+
+So the gate is here rather than in the resolver: run the build, then read the record the resolver
+wrote, and refuse to publish unless every expected resolver reported a terminal state. `skipped`
+with a reason is a success — a repository without PHPStan in `vendor/` is a normal skip. `failed`
+is not, and neither is silence.
+
+Exit codes:
+
+    0  every expected resolver reported `completed` or `skipped`
+    2  an expected resolver reported `failed` (or never finished)
+    3  an expected resolver never reported at all, or no record was written
+    4  the shrink guard refused the new graph (see shrink.py); graph and manifest restored
+    *  graphify's own exit code, when graphify itself failed
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import sys
+from collections.abc import Callable, Sequence
+from pathlib import Path
+
+from . import shrink, shrink_cli, status
+from .config_resolver import RESOLVER_NAME as RESOLVER_NAME_CONFIG
+from .resolver import RESOLVER_NAME, RESOLVER_NAME_ROUTES
+
+EXIT_OK = 0
+EXIT_RESOLVER_FAILED = 2
+EXIT_RESOLVER_MISSING = 3
+EXIT_SHRINK_REFUSED = 4
+
+MESH_MANAGED_ENV = "GRAPHIFY_MESH_MANAGED"
+
+_TERMINAL_OK = ("completed", "skipped")
+
+
+def default_graph_path() -> Path:
+    """Where graphify publishes, honouring the same `GRAPHIFY_OUT` override graphify reads."""
+    out = os.environ.get("GRAPHIFY_PHP_GRAPH")
+    if out:
+        return Path(out)
+    return Path(os.environ.get("GRAPHIFY_OUT", "graphify-out")) / "graph.json"
+
+
+def check(record: dict, expected: Sequence[str]) -> tuple[int, str]:
+    """Decide whether this build may publish. Pure, so the gate is testable without a build."""
+    resolvers = {r.get("name"): r for r in (record.get("resolvers") or [])}
+    if not resolvers:
+        return EXIT_RESOLVER_MISSING, (
+            f"no resolver status record at {status.status_path()}: "
+            f"{', '.join(expected)} never reported"
+        )
+    for name in expected:
+        entry = resolvers.get(name)
+        if entry is None:
+            return EXIT_RESOLVER_MISSING, (
+                f"resolver {name!r} never reported; graphify ran without it "
+                f"(registration seam moved, or the package is not installed)"
+            )
+        state = entry.get("state", "")
+        if state not in _TERMINAL_OK:
+            reason = entry.get("reason") or "no reason recorded"
+            return EXIT_RESOLVER_FAILED, f"resolver {name!r} state={state}: {reason}"
+    return EXIT_OK, ""
+
+
+def _run_graphify(args: Sequence[str]) -> int:
+    from graphify.__main__ import main as graphify_main
+
+    # graphify re-execs itself with PYTHONHASHSEED=0 for `update`, `extract`, `cluster-only` and
+    # `label` (__main__.py:486-525), which would replace this process — losing the registration
+    # made a moment ago and the gate that runs after. It skips the re-exec when the caller has
+    # already chosen a seed, so choosing the same one it would have keeps us in-process and
+    # keeps graphify's determinism guarantee intact.
+    os.environ.setdefault("PYTHONHASHSEED", "0")
+
+    argv = sys.argv
+    sys.argv = ["graphify", *args]
+    try:
+        graphify_main()
+        return 0
+    except SystemExit as exc:
+        # graphify exits with a message string in places (`sys.exit("ERROR: ...")`). That is a
+        # failure, and the message is all the caller gets, so it goes to stderr here.
+        code = exc.code
+        if isinstance(code, int):
+            return code
+        if code is None:
+            return 0
+        print(code, file=sys.stderr)
+        return 1
+    finally:
+        sys.argv = argv
+
+
+def _split_argv(argv: Sequence[str]) -> tuple[list[str], list[str]]:
+    """Our options before `--`, graphify's after it.
+
+    A shared namespace would break the moment graphify adds a flag we already use, and the
+    wrapper must stay transparent to every graphify option, present and future.
+    """
+    argv = list(argv)
+    if "--" in argv:
+        cut = argv.index("--")
+        return argv[:cut], argv[cut + 1 :]
+    return [], argv
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="graphify-php-build",
+        description="Run graphify with graphify_php registered, refusing to publish a graph "
+        "whose expected resolvers did not complete.",
+    )
+    parser.add_argument(
+        "--graph",
+        type=Path,
+        default=None,
+        help="graph artifact to protect (default: $GRAPHIFY_OUT/graph.json)",
+    )
+    parser.add_argument(
+        "--expect",
+        action="append",
+        dest="expect",
+        default=None,
+        metavar="RESOLVER",
+        help="resolver that must report (repeatable, default: every resolver "
+        "this package registers)",
+    )
+    parser.add_argument(
+        "--version",
+        action="store_true",
+        help="print this package's and graphify's versions and exit, touching no file",
+    )
+    return parser
+
+
+def _wants_version(ours: Sequence[str], passthrough: Sequence[str]) -> bool:
+    """`--version` before `--`, or alone: a bare flag lands in graphify's half by the split rule."""
+    return "--version" in ours or (not ours and list(passthrough) == ["--version"])
+
+
+def version_line() -> str:
+    """One line a caller can parse: `graphify-php <ver> (graphify <ver>)`."""
+    ours = status.installed_version(status.PRODUCER_NAME)
+    graphify = status.installed_version(status.GRAPHIFY_DISTRIBUTION)
+    return f"{status.PRODUCER_NAME} {ours} (graphify {graphify})"
+
+
+def main(
+    argv: Sequence[str] | None = None, run_graphify: Callable[[Sequence[str]], int] | None = None
+) -> int:
+    ours, passthrough = _split_argv(sys.argv[1:] if argv is None else argv)
+    # Before any path is computed or unlinked: graphify-mesh probes the build interpreter with
+    # this, and it used to fall through to graphify and delete the status record in the cwd.
+    if _wants_version(ours, passthrough):
+        print(version_line())
+        return EXIT_OK
+    opts = _parser().parse_args(ours)
+    expected = opts.expect or [RESOLVER_NAME, RESOLVER_NAME_ROUTES, RESOLVER_NAME_CONFIG]
+    graph = opts.graph or default_graph_path()
+
+    # A record from an earlier build would satisfy this build's gate, which is the one failure
+    # the gate exists to catch. Start from nothing so silence stays visible as silence.
+    record_path = status.status_path()
+    record_path.unlink(missing_ok=True)
+
+    backup = graph.with_suffix(graph.suffix + ".graphify-php-prev")
+    had_previous = graph.exists()
+    if had_previous:
+        shutil.copy2(graph, backup)
+    # graphify 0.9.89/0.9.92 `update` re-extracts every code file and ignores the manifest. The
+    # manifest is still snapshotted and restored with the graph, so the pair stays consistent
+    # and a graphify version with a truly incremental `update` does not skip files a rolled-back
+    # graph lacks.
+    manifest = graph.parent / "manifest.json"
+    manifest_backup = manifest.with_suffix(manifest.suffix + ".graphify-php-prev")
+    had_manifest = manifest.exists()
+    if had_manifest:
+        shutil.copy2(manifest, manifest_backup)
+
+    try:
+        runner = run_graphify or _run_graphify
+        code = runner(passthrough)
+        if code != EXIT_OK:
+            print(f"graphify-php-build: graphify exited {code}", file=sys.stderr)
+            return code
+
+        try:
+            code, message = check(status.read(), expected)
+        except Exception as exc:  # a record the gate cannot read is a record that proves nothing
+            code, message = EXIT_RESOLVER_MISSING, f"status record unreadable: {exc}"
+        if code == EXIT_OK:
+            return _shrink_gate(
+                graph,
+                backup if had_previous else None,
+                manifest,
+                manifest_backup if had_manifest else None,
+                passthrough,
+            )
+
+        # Refusing to publish means the graph a reader would pick up must be the one that was
+        # there before, not the short one this build just wrote.
+        if had_previous:
+            os.replace(backup, graph)
+            restored = f"previous graph at {graph} and its manifest left untouched"
+        else:
+            graph.unlink(missing_ok=True)
+            restored = f"no graph published at {graph}"
+        _restore_manifest(manifest, manifest_backup if had_manifest else None)
+        print(f"graphify-php-build: {message}", file=sys.stderr)
+        print(f"graphify-php-build: refusing to publish; {restored}", file=sys.stderr)
+        return code
+    finally:
+        for left in (backup, manifest_backup):
+            if left.exists():
+                left.unlink(missing_ok=True)
+
+
+def _restore_manifest(manifest: Path, manifest_backup: Path | None) -> None:
+    """Put back the manifest that matches the graph being kept.
+
+    The failed build's manifest lists files as indexed that the kept graph does not hold, and the
+    next incremental `update` would skip them.
+    """
+    if manifest_backup is not None:
+        os.replace(manifest_backup, manifest)
+    else:
+        # No manifest before this build: dropping the new one makes the next build a full one.
+        manifest.unlink(missing_ok=True)
+
+
+def _shrink_gate(
+    graph: Path,
+    graph_backup: Path | None,
+    manifest: Path,
+    manifest_backup: Path | None,
+    passthrough: Sequence[str],
+) -> int:
+    """Refuse a graph that lost nodes or edges nothing on disk explains.
+
+    The resolver gate only proves the resolvers ran. A build can pass it and still publish a
+    graph missing half its call edges, which is the case this guard exists for.
+    """
+    if os.environ.get(MESH_MANAGED_ENV) == "1":
+        print(
+            f"graphify-php-build: {MESH_MANAGED_ENV}=1, shrink guard left to graphify-mesh",
+            file=sys.stderr,
+        )
+        return EXIT_OK
+    policy = shrink_cli.env_policy()
+    if policy == shrink.POLICY_OFF or graph_backup is None:
+        return EXIT_OK
+    if manifest_backup is None and policy == shrink.POLICY_ATTRIBUTED:
+        # With no old manifest every file on disk reads as changed, which explains every loss.
+        # Attribution cannot judge this build, so the legacy count floor does.
+        print(
+            f"graphify-php-build: no previous manifest at {manifest}; shrink guard cannot "
+            f"attribute loss, using the {shrink.POLICY_COUNT} policy",
+            file=sys.stderr,
+        )
+        policy = shrink.POLICY_COUNT
+
+    try:
+        report = shrink.classify_loss(
+            shrink_cli.load_json(graph_backup, missing_ok=False),
+            shrink_cli.load_json(graph, missing_ok=False),
+            shrink_cli.load_json(manifest_backup, missing_ok=False) if manifest_backup else {},
+            shrink_cli.load_json(manifest, missing_ok=True),
+            Path(repo_root_from(passthrough)),
+            policy=policy,
+            tolerance=shrink_cli.env_tolerance(),
+        )
+        verdict = report.verdict
+        summary = (
+            f"shrink guard ({policy}) refused: nodes {report.nodes['old']} -> "
+            f"{report.nodes['new']}, unexplained {report.nodes['unexplained']} "
+            f"(floor {report.nodes['floor']} of {report.nodes['base']}); edges "
+            f"{report.edges['old']} -> {report.edges['new']}, unexplained "
+            f"{report.edges['unexplained']}, resolver lost {report.edges['resolver_lost']} "
+            f"of {report.edges['resolver_old']}"
+        )
+        reasons = report.reasons
+    except Exception as exc:
+        # A guard that cannot judge the build fails closed, like the resolver gate does. Any
+        # exception, not only bad input: one that escaped would leave the short graph published.
+        verdict, reasons = "refuse", []
+        summary = f"shrink guard could not run: {type(exc).__name__}: {exc}"
+    if verdict == "accept":
+        return EXIT_OK
+
+    os.replace(graph_backup, graph)
+    _restore_manifest(manifest, manifest_backup)
+    print(f"graphify-php-build: {summary}", file=sys.stderr)
+    for reason in reasons:
+        print(f"graphify-php-build:   - {reason}", file=sys.stderr)
+    print(
+        f"graphify-php-build: refusing to publish; previous graph at {graph} and its "
+        "manifest restored",
+        file=sys.stderr,
+    )
+    return EXIT_SHRINK_REFUSED
+
+
+def repo_root_from(args: Sequence[str]) -> str:
+    """The repository graphify was pointed at, which is what the type sources resolve against.
+
+    graphify takes it as a positional path (`graphify update <path>`), so the cwd is not it: a
+    build launched from anywhere else would hand the sources a root with no PHP under it.
+    Resolved, so the shrink guard matches graphify's absolute paths through a symlinked root.
+    """
+    for arg in args[1:]:
+        if not arg.startswith("-") and Path(arg).is_dir():
+            return str(Path(arg).resolve())
+    return str(Path.cwd().resolve())
+
+
+def _console_main() -> None:
+    ours, passthrough = _split_argv(sys.argv[1:])
+    # Help needs no graphify, and `register` imports it; an environment without graphify
+    # would otherwise lose `--help` to a ModuleNotFoundError. A bare `--help` with no `--`
+    # lands in graphify's half by the split rule, but nothing else is there to pass on, so it
+    # is ours.
+    help_flags = {"-h", "--help"}
+    if help_flags & set(ours) or (
+        not ours and len(passthrough) == 1 and passthrough[0] in help_flags
+    ):
+        _parser().print_help()
+        sys.exit(0)
+    # `register` imports graphify and binds the resolvers; a version probe needs neither.
+    if _wants_version(ours, passthrough):
+        sys.exit(main())
+
+    from . import register
+
+    register(repo_root=repo_root_from(passthrough))
+    sys.exit(main())
+
+
+if __name__ == "__main__":
+    _console_main()

graphify_php/config/__init__.py

@@ -0,0 +1,47 @@
+"""Configuration facts Symfony declares in YAML and nowhere in PHP.
+
+Two of them today: which transport carries which message, and which environment variable a
+configuration file reads. Both are invisible to a graph built from PHP source — the first exists
+only as a routing key, the second only as a container placeholder — and both are the kind of
+question a text search answers with every file and no direction.
+
+The pieces are separate because a third fact is coming: `ConfigFileFinder` decides what to read,
+`SafeDocumentParser` turns one file into a mapping or a named refusal, a reader turns one mapping
+into facts, and `GraphWriter` turns facts into graph nodes and edges. A new fact is a new reader
+registered in `default_readers`; nothing else changes.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from .discovery import ConfigFileFinder
+from .document import DocumentNodeFactory, file_key
+from .emit import GraphWriter
+from .environment import EnvReferenceReader
+from .facts import ConfigDocument, ConfigEdge, ConfigNode, FactSet, NodeRef
+from .messaging import MessageRoutingReader
+from .ports import ConfigFactReader
+from .safe_yaml import SafeDocumentParser
+
+__all__ = [
+    "ConfigDocument",
+    "ConfigEdge",
+    "ConfigFactReader",
+    "ConfigFileFinder",
+    "ConfigNode",
+    "DocumentNodeFactory",
+    "file_key",
+    "EnvReferenceReader",
+    "FactSet",
+    "GraphWriter",
+    "MessageRoutingReader",
+    "NodeRef",
+    "SafeDocumentParser",
+    "default_readers",
+]
+
+
+def default_readers() -> Sequence[ConfigFactReader]:
+    """The readers a build runs, and the one place they are named."""
+    return (MessageRoutingReader(), EnvReferenceReader())

graphify_php/config/class_lookup.py

@@ -0,0 +1,85 @@
+"""Finding the graph node for a class FQN written in YAML.
+
+graphify labels a class node with its SHORT name — `AbstractCronMessage`, never
+`App\\Cron\\Message\\AbstractCronMessage` — so a routing key cannot be looked up directly. The
+short name is matched and then re-checked against the file path, because two classes sharing a
+short name is ordinary in a Symfony application and binding to the wrong one puts a false edge
+in the graph.
+
+A miss is the expected outcome for a message class that lives in a package outside the indexed
+tree. It is counted, never guessed at: an edge from the wrong class is worse than no edge, which
+is graphify's own bar for its member-call resolvers.
+
+Kept separate from `graph_adapter` deliberately. That module answers "which node is method M of
+class C" for call resolution and is another author's file; this one answers a different question
+for a different pass and has no reason to make them move together.
+"""
+
+from __future__ import annotations
+
+import re
+
+
+def _key(label: str) -> str:
+    """graphify's own label normalisation, so keys made here agree with labels made there."""
+    return re.sub(r"[^a-zA-Z0-9]+", "", str(label)).lower()
+
+
+def _fqn_parts(fqn: str) -> list[str]:
+    return [p for p in str(fqn).replace("/", "\\").split("\\") if p]
+
+
+def _path_parts(source_file: str) -> list[str]:
+    stripped = re.sub(r"\.[^./\\]+$", "", str(source_file or ""))
+    return [p for p in stripped.replace("\\", "/").split("/") if p]
+
+
+def _tail_overlap(a: list[str], b: list[str]) -> int:
+    count = 0
+    # Paths differ in length on purpose; the overlap stops at the shorter one.
+    for left, right in zip(reversed(a), reversed(b), strict=False):
+        if _key(left) != _key(right):
+            break
+        count += 1
+    return count
+
+
+class GraphClassIndex:
+    """Class FQN -> graphify node id, or nothing."""
+
+    def __init__(self, all_nodes: list[dict], all_edges: list[dict]) -> None:
+        # Only a class some file contains is a candidate. graphify also carries synthesised and
+        # external class nodes; an edge into one of those points at nothing a reader can open.
+        contained = {e.get("target") for e in all_edges if e.get("relation") == "contains"}
+        self._by_short: dict[str, list[dict]] = {}
+        for node in all_nodes:
+            if node.get("_callable_class") and node.get("id") in contained:
+                self._by_short.setdefault(_key(node.get("label", "")), []).append(node)
+
+    def node_id(self, class_fqn: str) -> str | None:
+        parts = _fqn_parts(class_fqn)
+        if not parts:
+            return None
+        candidates = self._by_short.get(_key(parts[-1]), [])
+        if not candidates:
+            return None
+
+        # Directories only. The file stem repeats the class name, so including it would score
+        # every candidate identically and decide nothing.
+        namespace = parts[:-1]
+        scored = [
+            (_tail_overlap(namespace, _path_parts(c.get("source_file", ""))[:-1]), c)
+            for c in candidates
+        ]
+        best = max(score for score, _ in scored)
+        winners = [c for score, c in scored if score == best]
+        if best == 0 or len(winners) != 1:
+            return None
+        # A lone candidate is not evidence. `Vendor\Billing\Event\SyncUsers` in messenger.yaml
+        # and the project's own `src/Cron/Message/SyncUsers.php` share a short name and nothing
+        # else, and binding them would be exactly the false edge this module exists to refuse.
+        # The namespace minus its root (`App`, `Vendor`) has to match the path tail; the same
+        # rule `graph_adapter._class_node` applies for call resolution.
+        if len(namespace) >= 2 and best < len(namespace) - 1:
+            return None
+        return winners[0].get("id")

graphify_php/config/discovery.py

@@ -0,0 +1,55 @@
+"""Finding the files to read, and nothing else.
+
+Scope is `config/**/*.yaml` under the repository root. Not a tree walk: the repositories this
+runs against carry `vendor/` and `node_modules/`, where a walk costs seconds and finds YAML that
+belongs to somebody else's package. `config/` is where Symfony puts the declarations this
+package indexes, and a file outside it is out of scope by construction rather than by a filter.
+
+A repository with no `config/` directory is a plain skip. Most repositories graphify indexes are
+not Symfony applications, so this is the common case and must not read as a fault.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+CONFIG_DIRNAME = "config"
+SUFFIX = ".yaml"
+
+
+class ConfigFileFinder:
+    """Lists the configuration files in scope, relative paths and absolute paths together."""
+
+    def __init__(self, repo_root: str | Path, dirname: str = CONFIG_DIRNAME) -> None:
+        self._root = Path(repo_root)
+        self._dirname = dirname
+
+    @property
+    def config_dir(self) -> Path:
+        return self._root / self._dirname
+
+    def available(self) -> tuple[bool, str]:
+        directory = self.config_dir
+        if not directory.is_dir():
+            return False, f"no {self._dirname}/ directory under {self._root}"
+        return True, ""
+
+    def find(self) -> list[tuple[str, Path]]:
+        """`(path relative to the repository root, absolute path)`, sorted.
+
+        Sorted because the node and edge lists this feeds are published and diffed between
+        builds; directory order is not stable across machines and would make every build look
+        changed.
+
+        Symlinks are skipped: a link inside `config/` can point anywhere on the machine, and
+        following one would read a file outside the repository under the repository's name.
+        """
+        directory = self.config_dir
+        if not directory.is_dir():
+            return []
+        found: list[tuple[str, Path]] = []
+        for path in sorted(directory.rglob(f"*{SUFFIX}")):
+            if path.is_symlink() or not path.is_file():
+                continue
+            found.append((path.relative_to(self._root).as_posix(), path))
+        return found