codebase-explorer 2.2.0__py3-none-any.whl

cbe/graph.py

@@ -0,0 +1,857 @@
+"""Standard ``cbe-graph/1`` analyzer: build and query source-linked code graphs.
+
+This module owns the public graph contract consumed by the generation pipeline
+and the ``cbe graph`` CLI.  It selects open-source backends, merges their
+fragments into one node/edge graph keyed by repo-relative POSIX paths, and
+exposes a pure query over an already-built graph.
+
+Design rules:
+
+* It never re-implements a language analyzer.  Joern provides call, control
+  flow, native REACHING_DEF definition-use edges and import declarations;
+  dependency-cruiser and Grimp resolve JS/TS and Python imports to
+  files/modules.
+* A missing or failed backend is an explicit capability/diagnostic, never a
+  silent empty success: if nothing could run, ``analyze_graph`` raises.
+* Every node/edge that anchors real source carries a repo-relative ``path`` and
+  a resolution ``status`` from ``resolved|ambiguous|unresolved|external|
+  unsupported``.  Unresolved targets keep the raw expression; ambiguous calls
+  keep their candidate list.
+* Provenance binds the analyzed source and the relevant build/resolution
+  configuration.  If either changes during the build the graph is marked
+  unstable so a downstream consumer can refuse it.
+* Coordinates and provenance come from the analyzer.  Joern reports 1-based
+  lines and 1-based UTF-16 columns; this module stores lines as given and
+  leaves byte/char mapping to the chunk layer.  Raw analyzer ids are kept on
+  ``analyzer_id``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+from pathlib import Path, PurePosixPath
+from typing import Any
+from collections.abc import Iterable
+from datetime import datetime, timezone
+
+from cbe.grammars import (
+    ContextError,
+    DEFAULT_EXCLUDE_DIR_NAMES,
+    GraphSourceMismatch,
+    _validate_relative,
+    sha256_bytes,
+    suffix_languages,
+)
+from cbe.graph_backends._paths import canonical_repo_path
+from cbe.graph_backends.identity import repository_files, validate_identities
+from cbe.graph_backends.resolution import resolve_declarations, import_token
+
+BACKEND_FAILURE_CODES = frozenset({"backend_error", "backend_timeout", "frontend_error", "backend_unavailable"})
+
+SCHEMA_GRAPH = "cbe-graph/1"
+
+#: Build/module-resolution files that change what an analyzer sees.
+GRAPH_CONFIG_NAMES = frozenset({
+    "compile_commands.json", "CMakeLists.txt", "Makefile", "tsconfig.json",
+    "package.json", "pyproject.toml", "go.mod", "go.sum", "pom.xml",
+    "build.gradle", "settings.gradle", "Cargo.toml", "composer.json",
+    "Gemfile", "Package.swift", "setup.py", "setup.cfg", "compile_flags.txt",
+    "package-lock.json", "npm-shrinkwrap.json", "yarn.lock", "pnpm-lock.yaml",
+    "Cargo.lock", "composer.lock", "Gemfile.lock", "Package.resolved",
+    "gradle.properties", "gradle.lockfile", "CMakePresets.json", "CMakeUserPresets.json",
+})
+GRAPH_CONFIG_SUFFIXES = (".csproj", ".sln", ".gemspec", ".cmake", ".mk")
+
+GRAPH_KINDS = frozenset({"import", "call", "cfg", "dataflow"})
+_CAPABILITY_RANK = {"resolved": 6, "partial": 5, "empty": 4, "not_requested": 4, "unsupported": 3,
+                    "failed": 2, "unavailable": 1}
+
+
+class GraphError(ValueError):
+    """Raised when no graph could be produced or an input is invalid.
+
+    A failed build may still have written an auditable, non-authoritative graph.
+    """
+
+    def __init__(self, message: str, *, graph: dict | None = None):
+        super().__init__(message)
+        self.graph = graph
+
+
+def discover_sources(repo, languages: list[str] | None = None, *, suffix_map=None) -> list[dict]:
+    """Return ``[{path, language, sha256}]`` for source files under ``repo``."""
+
+    suffix_map = suffix_languages() if suffix_map is None else suffix_map
+    wanted = set(languages) if languages else None
+    manifest: list[dict] = []
+    repo = repo.resolve()
+    for rel in sorted(repository_files(repo)):
+        language = suffix_map.get(os.path.splitext(rel)[1].lower())
+        if language is None or (wanted is not None and language not in wanted):
+            continue
+        with (repo / rel).open("rb") as handle:
+            digest = hashlib.sha256(handle.read()).hexdigest()
+        manifest.append({"path": rel, "language": language, "sha256": digest})
+    manifest.sort(key=lambda entry: entry["path"])
+    return manifest
+
+
+def discover_config(repo) -> list[dict]:
+    """Return ``[{path, sha256}]`` for build/module-resolution files."""
+
+    excluded = DEFAULT_EXCLUDE_DIR_NAMES
+    repo = os.path.abspath(str(repo))
+    found: list[dict] = []
+    for dirpath, dirnames, filenames in os.walk(repo, topdown=True, followlinks=False):
+        dirnames.sort()
+        dirnames[:] = [name for name in dirnames if name not in excluded]
+        for filename in sorted(filenames):
+            if filename not in GRAPH_CONFIG_NAMES and not filename.endswith(GRAPH_CONFIG_SUFFIXES) \
+                    and not (filename.startswith("tsconfig.") and filename.endswith(".json")):
+                continue
+            full = os.path.join(dirpath, filename)
+            if os.path.islink(full) or not os.path.isfile(full):
+                continue
+            rel = os.path.relpath(full, repo).replace(os.sep, "/")
+            with open(full, "rb") as handle:
+                digest = hashlib.sha256(handle.read()).hexdigest()
+            found.append({"path": rel, "sha256": digest})
+    found.sort(key=lambda entry: entry["path"])
+    return found
+
+
+def validate_graph_provenance(repo, graph: dict) -> None:
+    """Reject stale analysis inputs before a graph enters a reading task.
+
+    External graphs without provenance retain their source-manifest contract;
+    their configuration identity is unknown. Our builds additionally bind the
+    complete set of registered source files and recognized configuration files.
+    """
+    from pathlib import Path
+
+    provenance = graph.get("provenance")
+    if provenance is None:
+        return
+    if not isinstance(provenance, dict):
+        raise GraphError("graph provenance must be an object")
+    for flag in ("source_stable", "config_stable"):
+        if flag in provenance and provenance[flag] is not True:
+            raise GraphError(f"graph build was unstable or malformed ({flag}); rebuild the graph")
+    repo = Path(repo).resolve()
+
+    def identities(entries, label: str) -> dict[str, str]:
+        if not isinstance(entries, list):
+            raise GraphError(f"graph {label} must be a manifest list")
+        result = {}
+        for entry in entries:
+            if not isinstance(entry, dict):
+                raise GraphError(f"malformed graph {label} entry")
+            path, digest = entry.get("path"), entry.get("sha256")
+            if not isinstance(path, str) or canonical_repo_path(path) != path \
+                    or not isinstance(digest, str) or not re.fullmatch(r"[0-9a-f]{64}", digest):
+                raise GraphError(f"malformed graph {label} identity")
+            if path in result:
+                raise GraphError(f"duplicate graph {label} path: {path}")
+            result[path] = digest
+        return result
+
+    checks = []
+    if "config_manifest" in provenance:
+        checks.append(("configuration", provenance["config_manifest"], discover_config(repo)))
+    if provenance.get("source_manifest_scope") == "registered_sources":
+        checks.append(("source", graph.get("source_manifest"), discover_sources(repo)))
+    for label, expected_entries, actual_entries in checks:
+        expected, actual = identities(expected_entries, label), identities(actual_entries, label)
+        if expected != actual:
+            changed = sorted(path for path in expected.keys() | actual.keys()
+                             if expected.get(path) != actual.get(path))
+            raise GraphError(f"graph {label} drift: {', '.join(changed[:10])}; rebuild the graph")
+
+
+def _graph_source_anchors(payload: dict[str, Any]):
+    """Yield every node/edge object that could anchor repo source."""
+
+    for key in ("nodes", "edges"):
+        for item in payload.get(key) or []:
+            if isinstance(item, dict):
+                yield item
+
+
+
+def check_graph_source(repo: Path, graph: dict[str, Any], frozen_hashes: dict[str, str]) -> None:
+    """Raise :class:`ContextError` unless ``graph`` can be evidence for the frozen source.
+
+    Provenance must be stable and current. Every manifest entry must name a
+    repository file whose bytes match: ``frozen_hashes`` (path to sha256) is the
+    authority for frozen files, so a file changed between two reads cannot make
+    a stale chunk set look consistent; other (boundary) files are read from
+    disk. Every node or edge that anchors existing repository source must be in
+    the manifest, so a graph cannot mix snapshots. Nodes without a repository
+    path stay external and a valid empty graph stays valid.
+    """
+
+    try:
+        validate_graph_provenance(repo, graph)
+    except (GraphError, OSError) as exc:
+        raise ContextError("graph_provenance_mismatch", str(exc)) from exc
+    manifest = graph.get("source_manifest")
+    if not isinstance(manifest, list):
+        raise ContextError("graph_manifest_missing",
+                           "graph has no source_manifest; cannot prove it matches the source")
+    manifested: set[str] = set()
+    for entry in manifest:
+        if not isinstance(entry, dict) or "path" not in entry or "sha256" not in entry:
+            raise ContextError("graph_manifest_missing", f"malformed source_manifest entry: {entry!r}")
+        raw_rel, expected = str(entry["path"]), str(entry["sha256"])
+        try:
+            rel = _validate_relative(repo, raw_rel)
+        except ContextError as exc:
+            raise ContextError(
+                "graph_source_mismatch",
+                f"graph manifest path is not a valid repo path: {raw_rel}: {exc.message}",
+                path=raw_rel,
+                reason="invalid_path",
+            ) from exc
+        manifested.add(rel)
+        if rel in frozen_hashes:
+            if frozen_hashes[rel] != expected:
+                raise GraphSourceMismatch(rel, expected, frozen_hashes[rel],
+                                          "content hash differs from current source")
+            continue
+        try:
+            actual = sha256_bytes((repo / PurePosixPath(rel)).read_bytes())
+        except OSError:
+            raise GraphSourceMismatch(rel, expected, None,
+                                      "file present in graph manifest is missing on disk") from None
+        if actual != expected:
+            raise GraphSourceMismatch(rel, expected, actual,
+                                      "boundary source drifted: content hash differs from current source")
+    unmanifested: set[str] = set()
+    # A path that is not a non-empty string cannot name repository source; such
+    # anchors stay external, as an unknown path does.
+    anchored = {path for anchor in _graph_source_anchors(graph)
+                if isinstance(path := anchor.get("path"), str) and path}
+    for raw_path in anchored:
+        try:
+            rel = _validate_relative(repo, raw_path)
+        except ContextError:
+            continue
+        if rel not in manifested and (repo / rel).exists():
+            unmanifested.add(rel)
+    if unmanifested:
+        listed = ", ".join(sorted(unmanifested)[:10])
+        raise ContextError(
+            "graph_unmanifested_source",
+            f"graph anchors repo source not covered by source_manifest: {listed}",
+            paths=sorted(unmanifested),
+        )
+
+
+
+def _prune_graph(graph: dict[str, Any] | None, selected: set[str]) -> dict[str, Any] | None:
+    if graph is None:
+        return None
+    nodes = [node for node in graph.get("nodes", []) if isinstance(node, dict)]
+    edges = [edge for edge in graph.get("edges", []) if isinstance(edge, dict)]
+    by_id = {node.get("id"): node for node in nodes}
+
+    kept_ids: set[str] = {node.get("id") for node in nodes if node.get("path") in selected}
+    kept_edges: list[dict[str, Any]] = []
+    for edge in edges:
+        source = edge.get("source")
+        target = edge.get("target")
+        source_node = by_id.get(source)
+        target_node = by_id.get(target)
+        touches = (
+            (source_node is not None and source_node.get("path") in selected)
+            or (target_node is not None and target_node.get("path") in selected)
+        )
+        if touches:
+            kept_edges.append(edge)
+            if source is not None:
+                kept_ids.add(source)
+            if target is not None:
+                kept_ids.add(target)
+
+    kept_nodes = [node for node in nodes if node.get("id") in kept_ids]
+    pruned: dict[str, Any] = {
+        key: value for key, value in graph.items() if key not in {"nodes", "edges", "source_manifest", "quality"}
+    }
+    pruned["nodes"] = kept_nodes
+    pruned["edges"] = kept_edges
+    # Keep the full analysis manifest.  A local slice may reference files
+    # outside the selection because their nodes are boundary endpoints; a
+    # trimmed manifest would misrepresent the provenance of the whole graph.
+    pruned["source_manifest"] = list(graph.get("source_manifest", []))
+    pruned["scope"] = {
+        "paths": sorted(selected),
+        "partial": True,
+        "edge_filter": "incident_to_selected",
+        "note": "Boundary/external nodes kept; relationships outside the selection are not shown.",
+    }
+    return pruned
+
+
+
+def graph_quality(graph: dict, *, existing_paths: Iterable[str] | None = None) -> dict:
+    """Pure audit of a graph and an optional repository-file snapshot.
+
+    Language is the declaration/source language (manifest, then node metadata),
+    never the target language. Null endpoints denote absent external/unresolved
+    targets and are not dangling IDs. With no file snapshot, existence is unknown
+    rather than silently reported as zero; persisted build audits retain it.
+    """
+    nodes, edges = graph.get("nodes", []), graph.get("edges", [])
+    by_id = {n.get("id"): n for n in nodes}
+    manifest = {row["path"]: row.get("language", "unknown")
+                for row in graph.get("source_manifest", [])}
+    capabilities = graph.get("capabilities", [])
+    languages = set(manifest.values()) | {c.get("language") or "unknown" for c in capabilities}
+    statuses = ("resolved", "ambiguous", "unresolved", "external", "unsupported")
+    not_exported = {(c.get("language") or "unknown", "dataflow") for c in capabilities
+                    if c.get("graph") == "dataflow" and c.get("status") == "not_requested"}
+    counts = {(language, kind): dict.fromkeys(statuses, 0)
+              for language in languages for kind in sorted(GRAPH_KINDS)
+              if (language, kind) not in not_exported}  # a row of zeros would claim "no dataflow edges"
+    dangling = []
+    for edge in edges:
+        source = by_id.get(edge.get("source"), {})
+        edge_path, source_path = edge.get("path"), source.get("path")
+        language = (manifest.get(edge_path) if isinstance(edge_path, str) else None)
+        language = (language or (manifest.get(source_path) if isinstance(source_path, str) else None)
+                    or edge.get("language") or source.get("language") or "unknown")
+        key = (language, edge.get("kind") or "unknown")
+        row = counts.setdefault(key, dict.fromkeys(statuses, 0))
+        status = edge.get("status") or "unknown"
+        row[status] = row.get(status, 0) + 1
+        missing = [edge[endpoint] for endpoint in ("source", "target")
+                   if edge.get(endpoint) is not None and edge[endpoint] not in by_id]
+        if missing:
+            dangling.append({"id": edge.get("id"), "missing_endpoints": missing})
+    anchored = [n for n in nodes if isinstance(n.get("path"), str)]
+    outside = [n for n in anchored if n["path"] not in manifest]
+    missing_files = None
+    if existing_paths is not None:
+        existing = set(existing_paths)
+        missing_files = [n for n in anchored if n["path"] not in existing]
+    diagnostics = graph.get("diagnostics", [])
+    no_backend = any(d.get("code") == "no_backend_completed" for d in diagnostics)
+    backend = graph.get("backend") or {}
+    successful = {"resolved", "partial", "empty", "not_requested"}
+    all_failed = bool(capabilities) and all(c.get("status") == "failed" for c in capabilities)
+    successful_component = any(c.get("status") in successful for c in backend.get("components", []))
+    completed = (False if no_backend or backend.get("name") == "none" or (all_failed and not successful_component) else
+                 True if backend.get("components") or any(
+                     c.get("status") in successful for c in capabilities) else None)
+    return {
+        "edge_counts": [{"language": language, "kind": kind, "statuses": row,
+                         "total": sum(row.values())}
+                        for (language, kind), row in sorted(counts.items())],
+        "dangling_edges": {"count": len(dangling), "examples": dangling[:5]},
+        "nodes_outside_manifest": {"count": len(outside), "examples": [n.get("id") for n in outside[:5]]},
+        "nodes_missing_files": {"count": None if missing_files is None else len(missing_files),
+                                "examples": [] if missing_files is None else [n.get("id") for n in missing_files[:5]]},
+        "file_existence_checked": existing_paths is not None,
+        "empty_graph": not nodes and not edges,
+        "backend_completed": completed,
+        "incomplete_capabilities": [dict(c) for c in capabilities
+                                    if c.get("status") not in {"resolved", "empty", "not_requested"}],
+        "frontend_failures": [dict(d) for d in diagnostics if d.get("code") in BACKEND_FAILURE_CODES],
+        "non_call_sites": dict(graph.get("non_call_sites", {})),
+    }
+
+
+def read_graph_quality(graph: dict, *, existing_paths: Iterable[str] | None = None) -> dict:
+    """Read the build's persisted audit; an explicit file snapshot refreshes it."""
+    if "quality" not in graph:
+        raise GraphError("this graph has no quality audit; rebuild it with this version of cbe")
+    if existing_paths is None:
+        return graph["quality"]
+    return graph_quality(graph, existing_paths=existing_paths)
+
+
+NO_DATAFLOW_MESSAGE = ("this graph was built without dataflow; "
+                       "rebuild with `cbe graph build --with-dataflow`")
+
+
+def built_without_dataflow(graph: object) -> bool:
+    """True when the graph says its dataflow was not exported (every dataflow capability is not_requested)."""
+    rows = [c for c in (graph.get("capabilities") or []) if isinstance(c, dict) and c.get("graph") == "dataflow"] \
+        if isinstance(graph, dict) else []
+    return bool(rows) and all(c.get("status") == "not_requested" for c in rows)
+
+
+def graph_state(graph: object, *, quality: dict | None = None) -> tuple[str, str]:
+    """Classify availability once for prompts and quality consumers.
+
+    An explicit failed build takes precedence over unsupported capabilities.
+    A completed backend can produce an empty graph even if another capability failed.
+    """
+    if graph is None:
+        return "absent", "no graph was provided for this run"
+    if not isinstance(graph, dict) or graph.get("schema") != SCHEMA_GRAPH:
+        found = graph.get("schema") if isinstance(graph, dict) else type(graph).__name__
+        return "unsupported", f"graph schema is {found!r}, expected 'cbe-graph/1'"
+    quality = read_graph_quality(graph) if quality is None else quality
+    if quality["backend_completed"] is False:
+        return "failed", "no backend completed; the empty graph is not authoritative"
+    nodes, edges = graph.get("nodes") or [], graph.get("edges") or []
+    if nodes or edges:
+        return "provided", f"{len(nodes)} nodes, {len(edges)} edges"
+    if quality["backend_completed"] is True:
+        return "empty", "the analyzer ran and found no relation"
+    statuses = {c.get("status") for c in quality["incomplete_capabilities"]}
+    if statuses & {"failed", "unavailable"}:
+        return "failed", "backend failed or was unavailable"
+    if "unsupported" in statuses:
+        return "unsupported", "no requested language/graph type is supported"
+    diagnostics = {row.get("code") for row in graph.get("diagnostics") or []}
+    if "no_language_requested" in diagnostics or (
+            "analyzed_languages" in graph and not graph["analyzed_languages"]):
+        return "unsupported", "no language was selected for analysis"
+    return "empty", "the analyzer ran and found no relation"
+
+
+def analyze_graph(
+    repo,
+    output,
+    *,
+    backend: str = "auto",
+    languages: list[str] | None = None,
+    joern_home=None,
+    joern_heap: str | None = None,
+    depcruise_bin=None,
+    timeout: int = 300,
+    max_methods: int | None = None,
+    max_reaching_defs: int | None = None,
+    dataflow_path_methods: list[str] | None = None,
+    max_paths_per_method: int = 5,
+    with_dataflow: bool = False,
+) -> dict:
+    """Build a ``cbe-graph/1`` graph and write it to ``output``.
+
+    ``backend`` is ``auto``, ``joern``, or ``imports``.  Runtime artifacts (CPG,
+    export JSON, script) stay in a sibling run directory next to ``output``;
+    nothing is written into the source tree.
+
+    Dataflow (reaching definitions) is exported only on request: ``with_dataflow``,
+    or giving ``max_reaching_defs`` or ``dataflow_path_methods``, which already
+    mean the caller wants it.  Without it the dataflow capability is ``not_requested``.
+    """
+
+    from pathlib import Path
+
+    from cbe import graph_backends as backends  # noqa: PLC0415
+
+    with_dataflow = bool(with_dataflow or max_reaching_defs is not None or dataflow_path_methods)
+    if max_reaching_defs is None:
+        max_reaching_defs = 50000
+    for name, value in (("timeout", timeout),
+                        ("max_reaching_defs", max_reaching_defs),
+                        ("max_paths_per_method", max_paths_per_method)):
+        if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+            raise GraphError(f"{name} must be a positive integer")
+    if max_methods is not None and (isinstance(max_methods, bool) or not isinstance(max_methods, int) or max_methods <= 0):
+        raise GraphError("max_methods must be a positive integer or None")
+    if joern_heap is not None and not re.fullmatch(r"[1-9][0-9]*[kKmMgG]", joern_heap):
+        raise GraphError("joern_heap must be a positive JVM heap size, such as 8g or 4096m")
+    repo = Path(repo).expanduser().resolve()
+    if not repo.is_dir():
+        raise GraphError(f"repository root is not a directory: {repo}")
+    output = Path(output).expanduser()
+    # Frontends can read sibling languages (for example C/C++ headers or
+    # JS/TS imports). Bind every registered source even for a language filter.
+    suffix_map = suffix_languages()
+    manifest = discover_sources(repo, suffix_map=suffix_map)
+    config_manifest = discover_config(repo)
+    detected = sorted({entry["language"] for entry in manifest})
+    requested = sorted(set(languages)) if languages else detected
+    run_dir = output.parent / (output.stem + ".run")
+    run_dir.mkdir(parents=True, exist_ok=True)
+
+    fragments: list[dict] = []
+    diagnostics: list[dict] = []
+    components: list[dict] = []
+    extra_capabilities: list[dict] = []
+    ran = False
+
+    use_joern = backend in ("auto", "joern")
+    use_imports = backend in ("auto", "imports")
+    joern_missing = False
+
+    if use_joern:
+        joern = backends.find_joern(joern_home)
+        if joern is None:
+            joern_missing = True
+            diagnostics.append({"path": None, "code": "backend_unavailable",
+                                "message": "Joern CLI not found; call/cfg/dataflow/import graph skipped; "
+                                           + backends.setup_hint()})
+            extra_capabilities.extend(_unavailable("joern", requested, ("call", "cfg", "dataflow", "import")))
+        else:
+            try:
+                fragment = backends.build_with_joern(
+                    repo, run_dir / "joern", requested, joern, timeout,
+                    joern_heap=joern_heap, java=backends.find_java(), max_methods=max_methods,
+                    max_reaching_defs=max_reaching_defs, with_dataflow=with_dataflow,
+                    dataflow_path_methods=dataflow_path_methods,
+                    max_paths_per_method=max_paths_per_method)
+            except backends.JoernError as exc:
+                diagnostics.append({"path": None, "code": "backend_error", "message": str(exc)})
+                extra_capabilities.extend(_unavailable("joern", requested, ("call", "cfg", "dataflow")))
+            else:
+                fragments.append(fragment)
+                components.append(fragment["backend"])
+                diagnostics.extend(fragment["diagnostics"])
+                ran = ran or (bool(fragment["raw"]) and any(
+                    c.get("status") in {"resolved", "partial", "empty", "not_requested"}
+                    for c in fragment["capabilities"]))
+
+    # An automatic call-graph build has one failure contract when Joern is
+    # absent. Import-only analysis remains available by explicit selection.
+    if use_imports and not (backend == "auto" and joern_missing):
+        depcruise = backends.find_depcruise(depcruise_bin)
+        import_languages = [lang for lang in requested if lang in backends.DEPCRUISE_LANGUAGES]
+        if depcruise is None and import_languages:
+            diagnostics.append({"path": None, "code": "backend_unavailable",
+                                "message": "dependency-cruiser not found; JS/TS import graph skipped"})
+            extra_capabilities.extend(_unavailable("dependency-cruiser", import_languages, ("import",)))
+        elif depcruise is not None and import_languages:
+            fragment = backends.build_with_depcruise(repo, run_dir / "depcruise", depcruise,
+                                                     timeout, import_languages)
+            if fragment["nodes"] or not fragment["diagnostics"]:
+                components.append({"name": "dependency-cruiser",
+                                   "version": _depcruise_version(depcruise, timeout)})
+                ran = True
+            fragments.append(fragment)
+            diagnostics.extend(fragment["diagnostics"])
+        if "python" in requested:
+            fragment = backends.build_with_grimp(repo, requested, suffix_map)
+            if fragment["nodes"]:
+                components.append({"name": "grimp", "version": _grimp_version()})
+                ran = True
+            fragments.append(fragment)
+            diagnostics.extend(fragment["diagnostics"])
+
+    files = repository_files(repo)
+    nodes, edges = _merge(fragments)
+    nodes, edges = resolve_declarations(repo, nodes, edges, files=files, diagnostics=diagnostics, suffix_map=suffix_map)
+    # The merge boundary validates identities; declaration resolution above
+    # is the only authority for turning an include into a repository file.
+    nodes, edges, identity_diagnostics = validate_identities(nodes, edges, files)
+    diagnostics.extend(identity_diagnostics)
+    edges = _prefer_resolved_imports(edges, suffix_map=suffix_map)
+    capabilities = _merge_capabilities(fragments, requested, extra_capabilities)
+    for capability in capabilities:
+        if capability.get("backend") == "joern" and capability.get("graph") == "import" and capability.get("status") not in {"failed", "unsupported", "unavailable"}:
+            relevant = [e for e in edges if e.get("kind") == "import"
+                        and suffix_map.get(Path(e.get("path") or "").suffix.lower()) == capability.get("language")]
+            counts = {status: sum(e.get("status") == status for e in relevant)
+                      for status in ("resolved", "external", "unresolved")}
+            capability.update(counts)
+            capability["status"] = "partial" if counts["unresolved"] else ("resolved" if relevant else "empty")
+            capability["limitations"] = "; ".join(f"{n} {s}" for s, n in counts.items()) + "; static repository-bounded resolution"
+
+    if not ran:
+        diagnostics.append({"path": None, "code": "no_backend_completed",
+                            "message": "no backend completed; graph is empty and not authoritative"})
+
+    source_stable = discover_sources(repo, suffix_map=suffix_map) == manifest
+    config_stable = discover_config(repo) == config_manifest
+    if not source_stable:
+        diagnostics.append({"path": None, "code": "source_changed_during_build",
+                            "message": "source bytes changed while the analyzers ran; "
+                                       "the graph no longer matches the current source"})
+    if not config_stable:
+        diagnostics.append({"path": None, "code": "config_changed_during_build",
+                            "message": "build/module-resolution configuration changed while the "
+                                       "analyzers ran; the graph's coverage conditions are stale"})
+    provenance = {
+        "source_stable": source_stable,
+        "config_stable": config_stable,
+        "config_manifest": config_manifest,
+        "source_manifest_scope": "registered_sources",
+        "analyzed_languages": requested,
+        "backend_components": components,
+        "analyzed_at": datetime.now(timezone.utc).isoformat(),
+        "fingerprint": _fingerprint(manifest, config_manifest, components),
+    }
+
+    non_call_sites = {}
+    for fragment in fragments:
+        for reason, count in fragment.get("non_call_sites", {}).items():
+            non_call_sites[reason] = non_call_sites.get(reason, 0) + count
+
+    graph = {
+        "schema": SCHEMA_GRAPH,
+        "source_manifest": manifest,
+        "backend": _backend_record(components),
+        "provenance": provenance,
+        "nodes": nodes,
+        "edges": edges,
+        "capabilities": capabilities,
+        "diagnostics": diagnostics,
+        "non_call_sites": dict(sorted(non_call_sites.items())),
+    }
+    graph = _scrub_repository_paths(graph, repo)
+    graph["quality"] = graph_quality(graph, existing_paths=files)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(graph, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    if not ran:
+        causes = "; ".join(d["message"] for d in diagnostics if d.get("code") in BACKEND_FAILURE_CODES)
+        raise GraphError("no graph backend completed" + (f": {causes}" if causes else ""), graph=graph)
+    return graph
+
+
+def _scrub_repository_paths(value, repo):
+    """Remove the repository's absolute prefix from every graph text field."""
+    if isinstance(value, dict):
+        return {key: _scrub_repository_paths(item, repo) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_scrub_repository_paths(item, repo) for item in value]
+    if isinstance(value, tuple):
+        return tuple(_scrub_repository_paths(item, repo) for item in value)
+    if isinstance(value, str):
+        root = str(repo).rstrip(os.sep)
+        return value.replace(root + os.sep, "").replace(root, ".")
+    return value
+
+
+def query_graph(
+    graph: dict,
+    *,
+    paths: list[str] | None = None,
+    kind: str | None = None,
+    direction: str = "both",
+    node_id: str | None = None,
+) -> dict:
+    """Select a local slice of an already-built graph.  Pure; reads no source.
+
+    Paths are canonical repo-relative POSIX paths.  If none of the requested
+    paths exist the result is an explicitly partial, empty slice (with the
+    unmatched paths listed), never the whole graph.
+    """
+
+    if not isinstance(graph, dict) or graph.get("schema") != SCHEMA_GRAPH:
+        raise GraphError("expected a cbe-graph/1 payload")
+    if kind is not None and kind not in GRAPH_KINDS:
+        raise GraphError(f"unknown graph kind {kind!r}; expected one of {sorted(GRAPH_KINDS)}")
+    if kind == "dataflow" and built_without_dataflow(graph):
+        raise GraphError(NO_DATAFLOW_MESSAGE)
+    if direction not in ("both", "in", "out"):
+        raise GraphError(f"unknown direction {direction!r}")
+
+    nodes = [node for node in graph.get("nodes", []) if isinstance(node, dict)]
+    edges = [edge for edge in graph.get("edges", []) if isinstance(edge, dict)]
+    by_id = {node.get("id"): node for node in nodes}
+
+    canonical_paths: list[str] = []
+    invalid_paths: list[str] = []
+    for raw in paths or []:
+        canonical = canonical_repo_path(raw)
+        if canonical is None:
+            invalid_paths.append(str(raw))
+        else:
+            canonical_paths.append(canonical)
+
+    selected: set[str] = set()
+    unmatched: list[str] = []
+    if node_id is not None:
+        if node_id not in by_id:
+            raise GraphError(f"node {node_id!r} is not in this graph")
+        selected.add(node_id)
+    if canonical_paths:
+        present = {node.get("path") for node in nodes}
+        selected |= {node["id"] for node in nodes if node.get("path") in set(canonical_paths)}
+        unmatched = sorted({path for path in canonical_paths if path not in present})
+
+    if kind is not None:
+        edges = [edge for edge in edges if edge.get("kind") == kind]
+
+    def incident(edge: dict) -> bool:
+        source, target = edge.get("source"), edge.get("target")
+        if direction in ("both", "out") and source in selected:
+            return True
+        if direction in ("both", "in") and target in selected:
+            return True
+        return False
+
+    filtered = bool(paths or kind or node_id or invalid_paths)
+    selection_requested = bool(paths or node_id or invalid_paths)
+    if selected:
+        kept_edges = [edge for edge in edges if incident(edge)]
+        kept_ids = set(selected) if kind is None else ({node_id} if node_id else set())
+        for edge in kept_edges:
+            if edge.get("source") is not None:
+                kept_ids.add(edge["source"])
+            if edge.get("target") is not None:
+                kept_ids.add(edge["target"])
+        kept_nodes = [node for node in nodes if node.get("id") in kept_ids]
+    elif selection_requested:
+        # A node selection was requested but matched nothing: respect the empty scope.
+        kept_edges = []
+        kept_nodes = []
+    else:
+        kept_edges = edges
+        endpoint_ids = {edge.get(endpoint) for edge in edges for endpoint in ("source", "target")}
+        kept_nodes = nodes if kind is None else [node for node in nodes if node.get("id") in endpoint_ids]
+
+    diagnostics = list(graph.get("diagnostics", []))
+    if unmatched:
+        diagnostics.append({"path": None, "code": "query_paths_not_found",
+                            "message": "no graph node matches the requested path(s): "
+                                       + ", ".join(unmatched[:10])})
+    if invalid_paths:
+        diagnostics.append({"path": None, "code": "query_paths_invalid",
+                            "message": "query paths must be repo-relative POSIX paths: "
+                                       + ", ".join(invalid_paths[:10])})
+
+    return {
+        "schema": SCHEMA_GRAPH,
+        "backend": graph.get("backend"),
+        "provenance": graph.get("provenance"),
+        "source_manifest": list(graph.get("source_manifest", [])),
+        "nodes": kept_nodes,
+        "edges": kept_edges,
+        "capabilities": graph.get("capabilities", []),
+        "diagnostics": diagnostics,
+        "scope": {
+            "paths": canonical_paths or None,
+            "kind": kind,
+            "direction": direction,
+            "node_id": node_id,
+            "partial": filtered,
+            "edge_filter": ("incident_to_selection" if selected else "empty_selection")
+                           if selection_requested else ("kind_only" if kind else "none"),
+            "unmatched_paths": unmatched or None,
+            "invalid_paths": invalid_paths or None,
+        },
+    }
+
+
+# ---------------------------------------------------------------------------
+# helpers
+# ---------------------------------------------------------------------------
+
+
+def _merge(fragments: list[dict]) -> tuple[list[dict], list[dict]]:
+    nodes: list[dict] = []
+    edges: list[dict] = []
+    seen_nodes: set[str] = set()
+    seen_edges: set[tuple] = set()
+    for fragment in fragments:
+        for node in fragment.get("nodes", []):
+            if node["id"] in seen_nodes:
+                continue
+            seen_nodes.add(node["id"])
+            nodes.append(node)
+        for edge in fragment.get("edges", []):
+            key = (edge.get("id"), edge.get("source"), edge.get("target"), edge.get("kind"))
+            if key in seen_edges:
+                continue
+            seen_edges.add(key)
+            edges.append(edge)
+    return nodes, edges
+
+
+def _prefer_resolved_imports(edges: list[dict], *, suffix_map=None) -> list[dict]:
+    """Merge resolved file evidence by endpoints, retaining every expression."""
+    from pathlib import PurePosixPath
+
+    suffix_map = suffix_languages() if suffix_map is None else suffix_map
+
+    def specifier(edge):
+        return import_token(edge.get("expression") or "", PurePosixPath(edge.get("path") or "").suffix, suffix_map)
+
+    resolved_declarations = {(e.get("source"), specifier(e)) for e in edges
+                             if e.get("kind") == "import" and e.get("status") == "resolved"
+                             and e.get("backend") != "joern" and specifier(e)}
+    groups = {}
+    result = []
+    # Prefer the dedicated resolver as the representative, independent of
+    # fragment ordering. Joern evidence is retained in expressions.
+    ordered = sorted(edges, key=lambda e: e.get("backend") == "joern")
+    for edge in ordered:
+        if (edge.get("kind") == "import" and edge.get("backend") == "joern"
+                and edge.get("status") == "unresolved" and specifier(edge)
+                and (edge.get("source"), specifier(edge)) in resolved_declarations):
+            continue
+        if edge.get("kind") != "import" or edge.get("status") != "resolved" or not edge.get("target"):
+            result.append(edge)
+            continue
+        key = (edge.get("source"), edge.get("target"), edge.get("kind"))
+        if key not in groups:
+            merged = dict(edge)
+            merged["expressions"] = list(edge.get("expressions") or ([edge["expression"]] if edge.get("expression") else []))
+            groups[key] = merged
+            result.append(merged)
+        else:
+            merged = groups[key]
+            if edge.get("resolution_basis") and not merged.get("resolution_basis"):
+                merged["resolution_basis"] = edge["resolution_basis"]
+            for expression in edge.get("expressions") or [edge.get("expression")]:
+                if expression and expression not in merged["expressions"]:
+                    merged["expressions"].append(expression)
+    return result
+
+
+def _unavailable(backend: str, languages: list[str], kinds: tuple[str, ...]) -> list[dict]:
+    return [{"language": language, "graph": kind, "backend": backend,
+             "status": "unavailable", "limitations": f"{backend} was not found"}
+            for language in languages for kind in kinds]
+
+
+def _merge_capabilities(fragments: list[dict], requested: list[str],
+                        extra: list[dict] | None = None) -> list[dict]:
+    merged: dict[tuple, dict] = {}
+    for capability in [item for fragment in fragments for item in fragment.get("capabilities", [])] + list(extra or []):
+        key = (capability.get("language"), capability.get("graph"))
+        current = merged.get(key)
+        if current is None or _CAPABILITY_RANK.get(capability.get("status"), 0) > _CAPABILITY_RANK.get(current.get("status"), 0):
+            merged[key] = capability
+    for language in requested:
+        for kind in ("import", "call", "cfg", "dataflow"):
+            merged.setdefault((language, kind), {
+                "language": language, "graph": kind, "status": "unsupported",
+                "backend": None, "limitations": "no backend reported this language/kind",
+            })
+    return sorted(merged.values(), key=lambda item: (item.get("language") or "", item.get("graph") or ""))
+
+
+def _backend_record(components: list[dict]) -> dict:
+    if not components:
+        return {"name": "none", "version": None, "components": []}
+    if len(components) == 1:
+        return {"name": components[0]["name"], "version": components[0].get("version"),
+                "components": components}
+    names = "+".join(component["name"] for component in components)
+    return {"name": names, "version": None, "components": components}
+
+
+def _fingerprint(manifest: list[dict], config_manifest: list[dict], components: list[dict]) -> str:
+    payload = json.dumps({"source": manifest, "config": config_manifest, "components": components},
+                         sort_keys=True, separators=(",", ":"))
+    return "gp_" + hashlib.sha256(payload.encode("utf-8")).hexdigest()[:32]
+
+
+def _depcruise_version(binary, timeout: int) -> str:
+    import subprocess  # noqa: PLC0415
+
+    try:
+        completed = subprocess.run([str(binary), "--version"], check=False, capture_output=True,
+                                   text=True, timeout=timeout, stdin=subprocess.DEVNULL)
+    except (OSError, subprocess.TimeoutExpired):
+        return "unknown"
+    text = (completed.stdout or completed.stderr).strip()
+    return text.splitlines()[0] if text else "unknown"
+
+
+def _grimp_version() -> str:
+    try:
+        from importlib.metadata import version  # noqa: PLC0415
+
+        return version("grimp")
+    except Exception:
+        return "unknown"