codegraph-brain 0.6.0__py3-none-any.whl

cgis/query/analysis/suggest_service.py

@@ -0,0 +1,221 @@
+"""Package-cohesion orchestration shared by the CLI and the MCP server (#242)."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from cgis.core.models import EdgeType
+
+if TYPE_CHECKING:
+    from cgis.core.models import Edge, Node
+
+from cgis.query.analysis.cohesion import (
+    THRESHOLDS,
+    build_file_graph,
+    classify_verdict,
+    greedy_modularity,
+    layout_direction,
+    partition_divergence,
+)
+from cgis.storage.sqlite_store import SQLiteStore
+
+_ROOT_GROUP = "<root>"
+
+
+@dataclass(frozen=True)
+class Community:
+    """One detected community: an id and its member files (last FQN segment)."""
+
+    id: int
+    files: list[str]
+
+
+@dataclass(frozen=True)
+class Bridge:
+    """A cross-community edge — the cost of splitting (file names, last segment)."""
+
+    source: str
+    target: str
+    weight: float
+
+
+@dataclass(frozen=True)
+class SuggestReport:
+    """Full suggest-packages result; serialized verbatim to CLI-json and MCP."""
+
+    package: str
+    layer: str
+    file_count: int
+    edge_count: int
+    modularity_q: float
+    divergence: float
+    direction: str
+    verdict: str
+    communities: list[Community]
+    bridges: list[Bridge]
+    thresholds: dict[str, float]
+    # Fraction of files with at least one intra-package edge. A split is only
+    # trusted above thresholds["min_connected"] — below it, a high Q is a
+    # sparse-graph artifact (most files are independent). 0.0 for no_signal.
+    connected_fraction: float = 0.0
+    note: str | None = None
+
+
+def _leaf(fqn: str) -> str:
+    """Return the last FQN segment (the module name) for readable output."""
+    return fqn.rsplit(".", 1)[-1]
+
+
+def _dir_group(fqn: str, prefix: str) -> str:
+    """Return the file's directory group relative to the package root.
+
+    A single remaining segment after the prefix maps to the shared ``"<root>"``
+    group; two or more map to the first remaining segment (a real sub-directory).
+    The package node itself (``fqn == prefix``, e.g. an ``__init__``) is ``<root>``.
+    """
+    if fqn == prefix:
+        return _ROOT_GROUP
+    remainder = fqn[len(prefix) + 1 :] if fqn.startswith(prefix + ".") else fqn
+    parts = remainder.split(".")
+    return _ROOT_GROUP if len(parts) <= 1 else parts[0]
+
+
+def _empty_report(package: str, layer: str, note: str, file_count: int = 0) -> SuggestReport:
+    """Return a no_signal report carrying a diagnostic note (never a silent green).
+
+    ``file_count`` is passed through for the mis-rooted / flat-leaf-bag cases —
+    files WERE found, there were just no intra-package edges to score, so a JSON
+    consumer should see the real count, not a misleading 0.
+    """
+    return SuggestReport(
+        package=package,
+        layer=layer,
+        file_count=file_count,
+        edge_count=0,
+        modularity_q=0.0,
+        divergence=0.0,
+        direction="matched",
+        verdict="no_signal",
+        communities=[],
+        bridges=[],
+        thresholds=dict(THRESHOLDS),
+        note=note,
+    )
+
+
+def suggest_packages(
+    db_path: str, prefix: str | None, with_calls: bool = False, min_q: float = 0.35
+) -> SuggestReport:
+    """Detect a package's communities and score layout divergence (#242).
+
+    ``prefix`` is normalized once here: a ``None`` or blank value (a CLI/MCP
+    client may send either) collapses to a ``no_signal`` report rather than a
+    crash, so every downstream helper receives a clean non-empty string.
+
+    Raises:
+        FileNotFoundError: if ``db_path`` is not an existing file (run ingest first).
+    """
+    if not Path(db_path).is_file():
+        msg = f"Graph database not found: {db_path}"
+        raise FileNotFoundError(msg)
+
+    layer = "imports+calls" if with_calls else "imports"
+    package = (prefix or "").strip()
+    if not package:
+        return _empty_report("", layer, "no fqn_prefix given")
+
+    with SQLiteStore(db_path) as store:
+        nodes: list[Node] = store.get_all_nodes()
+        edges: list[Edge] = store.get_all_edges()
+
+    graph = build_file_graph(nodes, edges, package, with_calls)
+    if not graph.files:
+        return _empty_report(package, layer, f"fqn_prefix '{package}' matched 0 nodes")
+
+    if len(graph.files) < 2:
+        # A single matched file is a module (or a one-file package), not something
+        # to split. Guard BEFORE the no-internal-edges check below — otherwise the
+        # lone module's outbound imports trip the 'mis-rooted' diagnostic falsely
+        # (it has import edges, none of which can resolve inside a 1-file set).
+        return _empty_report(
+            package,
+            layer,
+            f"'{package}' matched a single module, not a multi-file package — nothing to split",
+            file_count=len(graph.files),
+        )
+
+    internal_edges = sum(len(v) for v in graph.adj.values()) // 2
+    if internal_edges == 0:
+        had_import_attempts = any(
+            e.source.startswith(package + ".") or e.source == package
+            for e in edges
+            if e.type == EdgeType.IMPORTS
+        )
+        note = (
+            f"{package}: files found but no import resolves inside the package — the "
+            "graph looks mis-rooted or imports are unresolved; try ingesting the "
+            "package's parent directory"
+            if had_import_attempts
+            else f"{package}: no intra-package imports (a flat leaf bag)"
+        )
+        return _empty_report(package, layer, note, file_count=len(graph.files))
+
+    communities, q = greedy_modularity(graph)
+    comm_of = {f: i for i, c in enumerate(communities) for f in c}
+    dir_of = {f: _dir_group(f, package) for f in graph.files}
+    # Clamp to [0, 1]: NMI is mathematically in range, but float error can leak
+    # a tiny negative / >1 value that looks odd in JSON.
+    divergence = max(0.0, min(1.0, partition_divergence(comm_of, dir_of)))
+    direction = layout_direction(comm_of, dir_of)
+    thresholds = {**THRESHOLDS, "split": min_q}
+    verdict = classify_verdict(q=q, d=divergence, direction=direction, thresholds=thresholds)
+
+    # Sparse-graph guard: modularity Q is unreliable when most files have no
+    # intra-package edge — a single tiny cluster then inflates Q on a package of
+    # otherwise-independent helpers (owner-api/utils: 3 edges over 12 files, Q=0.44,
+    # 58% isolated → a false 'split'). Only act on it when enough files are coupled.
+    # build_file_graph only adds non-empty adjacency entries (keyed by files under
+    # the prefix), so adj keys ARE exactly the files with an intra-package edge.
+    connected_fraction = len(graph.adj) / len(graph.files)
+    sparse_note: str | None = None
+    if verdict in ("split", "borderline") and connected_fraction < thresholds["min_connected"]:
+        sparse_note = (
+            f"only {len(graph.adj)}/{len(graph.files)} ({connected_fraction:.0%}) of files "
+            f"are coupled to a sibling — mostly independent helpers, so the Q={q:.2f} is a "
+            "sparse-graph artifact, not real community structure; nothing to split"
+        )
+        verdict = "leave"
+
+    bridges = sorted(
+        (
+            Bridge(source=_leaf(a), target=_leaf(b), weight=w)
+            for a in graph.adj
+            for b, w in graph.adj[a].items()
+            if a < b and comm_of[a] != comm_of[b]
+        ),
+        key=lambda br: (-br.weight, br.source, br.target),
+    )
+    return SuggestReport(
+        package=package,
+        layer=layer,
+        file_count=len(graph.files),
+        edge_count=internal_edges,
+        modularity_q=round(q, 4),
+        divergence=round(divergence, 4),
+        direction=direction,
+        verdict=verdict,
+        communities=[
+            Community(id=i, files=[_leaf(f) for f in c]) for i, c in enumerate(communities)
+        ],
+        bridges=bridges,
+        thresholds=thresholds,
+        connected_fraction=round(connected_fraction, 4),
+        note=sparse_note,
+    )
+
+
+def report_to_dict(report: SuggestReport) -> dict[str, object]:
+    """Return a plain-dict view for JSON (CLI --format json and MCP share this)."""
+    return asdict(report)

cgis/query/context/audit.py

@@ -0,0 +1,134 @@
+"""Reachability/coverage audit — does every source reach a required checkpoint? (#172).
+
+The headline use is **authorization coverage**: of all the route handlers, which
+ones never transitively reach the ownership check (``verify_resource_ownership``)?
+That's the IDOR-class gap that previously took manual ``impact`` diffing to find.
+
+The shape generalizes — handlers that touch storage but never reach a validator,
+mutations that never reach event tracking, routes that bypass the service layer.
+
+Reachability follows **enforcement** edges by default — invocation (CALLS) and
+runtime wiring (DEPENDS_ON, AUTHORIZES) — *not* every behavioral edge. This is
+deliberate and load-bearing for a security primitive: merely *importing* or
+*referencing* the guard (IMPORTS/IMPORTS_SYMBOL/REFERENCES) is not enforcing it,
+so counting those as coverage would hide real IDOR gaps (a false "covered" is the
+dangerous direction). Callers can pass a wider ``allowed_edge_types`` explicitly.
+A guard wired via FastAPI ``Depends()`` (a DEPENDS_ON edge, #161) counts — *when
+the resolver uplifts that wiring to the guard node*; an unresolved dynamic
+provider (``raw_dep:``/``raw_call:`` at confidence 0.1) can't be proven and shows
+as a gap.
+"""
+
+from dataclasses import dataclass
+
+from cgis.core.models import EdgeType, Node, NodeNamespace, NodeType
+from cgis.query.engine import QueryEngine
+from cgis.storage.sqlite_store import SQLiteStore
+
+# Edges that mean the source *enforces* (invokes / wires) the checkpoint, as
+# opposed to merely importing or naming it. The default for an authz audit:
+# false coverage (import-only) is worse than a false gap for a security linter.
+_ENFORCEMENT_EDGE_TYPES: frozenset[EdgeType] = frozenset(
+    {EdgeType.CALLS, EdgeType.DEPENDS_ON, EdgeType.AUTHORIZES}
+)
+
+
+@dataclass(frozen=True)
+class NodeRef:
+    """A located reference to a graph node — enough to jump to it in an editor."""
+
+    fqn: str
+    file: str
+    line: int
+
+
+@dataclass(frozen=True)
+class ReachabilityAudit:
+    """Audit outcome: which sources reach ``target`` and which don't."""
+
+    target: str
+    covered: list[NodeRef]
+    gaps: list[NodeRef]
+
+
+def _prefix_matches(fqn: str, prefix: str) -> bool:
+    """Dot-boundary prefix match — ``app.routes`` matches ``app.routes.x``, not ``app.routesX``."""
+    return fqn == prefix or fqn.startswith(f"{prefix}.")
+
+
+def _select_sources(
+    store: SQLiteStore, from_type: NodeType | None, from_prefix: str | None
+) -> list[Node]:
+    """Select INTERNAL source nodes by node type and/or dot-boundary FQN prefix (AND-combined).
+
+    Restricted to INTERNAL nodes so the audit never flags stdlib/third-party
+    code, and the prefix is boundary-aware so a name overlap (``app.routesX``)
+    can't sneak into an ``app.routes`` selection.
+    """
+    return [
+        node
+        for node in store.get_all_nodes()
+        if node.namespace == NodeNamespace.INTERNAL
+        and (from_type is None or node.type == from_type)
+        and (from_prefix is None or _prefix_matches(node.id, from_prefix))
+    ]
+
+
+def _ref(node: Node) -> NodeRef:
+    """Build a located reference from a node."""
+    return NodeRef(fqn=node.id, file=node.file_path, line=node.start_line)
+
+
+def audit_reachability(
+    store: SQLiteStore,
+    *,
+    target_fqn: str,
+    from_type: NodeType | None = None,
+    from_prefix: str | None = None,
+    max_depth: int = 5,
+    allowed_edge_types: frozenset[EdgeType] | None = None,
+) -> ReachabilityAudit:
+    """Split the selected sources into those that reach ``target_fqn`` and those that don't.
+
+    Sources are chosen by ``from_type`` and/or ``from_prefix`` (at least one is
+    required; an empty/whitespace ``from_prefix`` is treated as unset). Coverage
+    is decided by a **single upstream traversal** from the checkpoint
+    (``get_impact_graph``) up to ``max_depth`` over ``allowed_edge_types``
+    (**enforcement** edges — CALLS/DEPENDS_ON/AUTHORIZES — by default, so an
+    import-only or reference-only link never counts as coverage): every node that
+    reaches the checkpoint within the depth is in that set, so a source is
+    *covered* iff it appears there, otherwise a *gap*. One BFS for the whole
+    audit, not one per source.
+
+    ``max_depth`` bounds the proof: a source that only reaches the checkpoint via
+    a chain longer than ``max_depth`` is reported as a gap even though it is
+    covered at runtime — raise it for deep route→service→crud→…→guard stacks. The
+    checkpoint node itself is never audited as its own source.
+
+    Note on ``target_fqn`` granularity: reaching a node means a behavioral edge
+    *to that node*. For a checkpoint that callers invoke (a FUNCTION/METHOD like
+    ``verify_resource_ownership``) this is exactly right. Pointing it at a CLASS
+    measures *instantiation* (a call to the constructor), NOT method use on an
+    already-injected instance — so a dependency-injected collaborator looks like
+    a gap. Target the specific method (or the constructor) when auditing "does X
+    use this collaborator".
+    """
+    from_prefix = from_prefix.strip() or None if from_prefix is not None else None
+    if from_type is None and from_prefix is None:
+        msg = "audit_reachability requires from_type or a non-empty from_prefix to select sources."
+        raise ValueError(msg)
+    engine = QueryEngine(store)
+    # `is not None`, not `or`: an explicit empty frozenset (no-traversal, target-only)
+    # is a valid intent and must not be overridden by the enforcement default.
+    edge_types = allowed_edge_types if allowed_edge_types is not None else _ENFORCEMENT_EDGE_TYPES
+    upstream_nodes, _ = engine.get_impact_graph(
+        target_fqn, max_depth=max_depth, allowed_edge_types=edge_types
+    )
+    reaching = {node.id for node in upstream_nodes}
+    covered: list[NodeRef] = []
+    gaps: list[NodeRef] = []
+    for source in sorted(_select_sources(store, from_type, from_prefix), key=lambda n: n.id):
+        if source.id == target_fqn:
+            continue
+        (covered if source.id in reaching else gaps).append(_ref(source))
+    return ReachabilityAudit(target=target_fqn, covered=covered, gaps=gaps)

cgis/query/context/context_service.py

@@ -0,0 +1,129 @@
+"""Orchestrate the GraphRAG context package for a focal FQN (#19).
+
+This is the impure seam between the graph (``QueryEngine``/``SQLiteStore``), the
+filesystem (``snippet.py``) and the pure renderer (``prompt.py``) — mirroring the
+``drift_service`` split. It fetches the focal node's direct CALLS neighbourhood
+and enclosing class, reads its source, and hands everything to
+``compile_context``.
+
+Callers/callees are restricted to CALLS edges so structural noise
+(CONTAINS/DECLARES) stays out of the "who calls / what it calls" lists; the
+enclosing class is recovered separately from the structural layer.
+"""
+
+from cgis.core.models import EdgeType, Node, NodeNamespace, NodeType
+from cgis.query.context.prompt import compile_context
+from cgis.query.context.snippet import extract_snippet, resolve_source_path
+from cgis.query.engine import QueryEngine
+from cgis.storage.sqlite_store import RAW_CALL_PREFIX, SQLiteStore
+
+_CALLS: frozenset[EdgeType] = frozenset({EdgeType.CALLS})
+_STRUCTURAL: frozenset[EdgeType] = frozenset({EdgeType.CONTAINS, EdgeType.DECLARES})
+
+
+def _sorted_neighbours(nodes: list[Node], focus_fqn: str) -> list[Node]:
+    """Keep only INTERNAL neighbours (drop self/builtins/third-party), ordered by location.
+
+    Resolved EXTERNAL/STDLIB calls (``len``, ``pathlib.Path``, ``ValueError`` …)
+    are pure noise in an agent context — the model already knows them — so the
+    lists carry only repo-internal nodes. Truly unknown calls still surface via
+    the unresolved ``raw_call:`` list.
+    """
+    return sorted(
+        (n for n in nodes if n.id != focus_fqn and n.namespace == NodeNamespace.INTERNAL),
+        key=lambda n: (n.file_path, n.start_line, n.id),
+    )
+
+
+def _collect_callers(engine: QueryEngine, focus_fqn: str, depth: int) -> list[Node]:
+    """Upstream CALLS neighbours within ``depth`` hops — who reaches the focal node."""
+    nodes, _ = engine.get_impact_graph(focus_fqn, max_depth=depth, allowed_edge_types=_CALLS)
+    return _sorted_neighbours(nodes, focus_fqn)
+
+
+def _collect_callees(
+    engine: QueryEngine, focus_fqn: str, depth: int
+) -> tuple[list[Node], list[str]]:
+    """Downstream CALLS neighbours within ``depth`` hops, split into resolved + unresolved.
+
+    Unresolved ``raw_call:`` targets are collected across the whole traversal
+    (not just the focal node's own edges) so that at depth>1 they stay symmetric
+    with the resolved set — a transitive callee's unknown call surfaces too.
+    """
+    nodes, edges = engine.get_flow_graph(focus_fqn, max_depth=depth, allowed_edge_types=_CALLS)
+    resolved = _sorted_neighbours(nodes, focus_fqn)
+    unresolved = sorted(
+        {
+            edge.target[len(RAW_CALL_PREFIX) :]
+            for edge in edges
+            if edge.target.startswith(RAW_CALL_PREFIX)
+        }
+    )
+    return resolved, unresolved
+
+
+def _structural_parent(store: SQLiteStore, focus_fqn: str) -> Node | None:
+    """Return the focal node's structural parent, preferring a CLASS over a FILE/MODULE.
+
+    A node may have several incoming structural edges (a method is DECLARED by a
+    class which is itself CONTAINED by a file). We collect every resolvable
+    parent — skipping any whose node is missing from the store — then prefer the
+    enclosing CLASS so a method's class context is never lost to an earlier
+    file-level edge.
+    """
+    candidates = (
+        store.get_node(edge.source)
+        for edge in store.get_incoming_edges(focus_fqn)
+        if edge.type in _STRUCTURAL
+    )
+    parents = [node for node in candidates if node is not None]
+    for parent in parents:
+        if parent.type == NodeType.CLASS:
+            return parent
+    return parents[0] if parents else None
+
+
+def _class_context(store: SQLiteStore, focus: Node) -> tuple[Node | None, list[Node]]:
+    """Recover the enclosing class and its sibling members (empty for free functions)."""
+    parent = _structural_parent(store, focus.id)
+    if parent is None or parent.type != NodeType.CLASS:
+        return None, []
+    members, _ = store.get_structural_subgraph(parent.id, 1)
+    siblings = _sorted_neighbours([n for n in members if n.id != parent.id], focus.id)
+    return parent, siblings
+
+
+def build_context(store: SQLiteStore, focus_fqn: str, depth: int = 1, source_root: str = "") -> str:
+    """Compile the agent-facing context package for an already-resolved ``focus_fqn``.
+
+    ``depth`` controls how far the CALLS traversal reaches. The default of 1
+    lists only *direct* callers/callees — the honest, high-signal neighbourhood
+    for a focused edit. Higher values pull in transitive neighbours; the
+    rendered notes state the hop bound rather than calling them "direct" (a
+    future adaptive strategy, #220, will scale depth by the node's out-degree).
+    ``source_root`` locates the file on disk when the graph was ingested from a
+    sub-directory (e.g. ``cgis ingest ./src`` stores ``cgis/...`` paths); see
+    ``resolve_source_path`` for the candidate order that also covers a stored
+    path already carrying the root segment (#228). Raises ``ValueError`` if the
+    FQN is absent.
+    """
+    focus = store.get_node(focus_fqn)
+    if focus is None:
+        msg = f"FQN not found in graph: {focus_fqn}"
+        raise ValueError(msg)
+    engine = QueryEngine(store)
+    file_path = resolve_source_path(focus.file_path, source_root)
+    source = extract_snippet(file_path, focus.start_line, focus.end_line)
+    callers = _collect_callers(engine, focus_fqn, depth)
+    callees, unresolved = _collect_callees(engine, focus_fqn, depth)
+    class_node, siblings = _class_context(store, focus)
+    return compile_context(
+        focus=focus,
+        source=source,
+        class_node=class_node,
+        siblings=siblings,
+        callers=callers,
+        callees=callees,
+        unresolved_callees=unresolved,
+        depth=depth,
+    )

cgis/query/context/prompt.py

@@ -0,0 +1,184 @@
+"""Compile a focal node's subgraph into an agent-facing context package (#19).
+
+This is the machine-facing sibling of ``mermaid.py`` (human diagrams) and
+``graph_json.py`` (joinable JSON): ``cgis context <fqn>`` feeds an LLM coding
+agent a compact, XML-tagged prompt about the node it is about to edit — the
+exact source, the enclosing class, who calls it (upstream ripple) and what it
+calls (downstream dependencies).
+
+The shape is deliberately token-lean. Adjacency is rendered as FQN + location
+bullet lists rather than Mermaid (a visual format an LLM parses at several times
+the token cost), and only the focal node's source is inlined — never whole
+files. XML tags give the model unambiguous section boundaries, which mitigates
+the "lost in the middle" failure mode on larger contexts.
+
+This module is **pure**: it takes already-fetched nodes/edges and a pre-read
+source string, so it can be unit-tested in isolation. Graph traversal and file
+I/O live in ``context_service.py`` and ``snippet.py`` respectively.
+"""
+
+import re
+
+from cgis.core.models import Node
+
+_BACKTICK_RUN = re.compile(r"`+")
+# Only the closing tags this module itself emits — so neutralising them in source
+# defeats prompt-injection without corrupting unrelated markup (e.g. TS/JSX `</div>`).
+_OWN_TAGS = ("source", "context", "class", "domain", "callers", "callees")
+# ``\s*`` before ``>`` matches the whitespace XML allows in an end tag (``</source >``).
+_OWN_CLOSING_TAG = re.compile(r"</(" + "|".join(_OWN_TAGS) + r")\s*>")
+
+
+def _escape_xml_attr(value: str) -> str:
+    """Escape a value for safe inclusion in an XML attribute (``&`` first)."""
+    return (
+        value.replace("&", "&amp;").replace('"', "&quot;").replace("<", "&lt;").replace(">", "&gt;")
+    )
+
+
+def _callers_note(depth: int) -> str:
+    """Honest <callers> note: 'direct' only at depth 1, hop-bounded above it."""
+    if depth <= 1:
+        return "direct callers — who calls this (changes here ripple from here)"
+    return f"callers within {depth} hops upstream (transitive ripple set)"
+
+
+def _callees_note(depth: int) -> str:
+    """Honest <callees> note: 'direct' only at depth 1, hop-bounded above it."""
+    if depth <= 1:
+        return "direct callees — what this calls"
+    return f"callees within {depth} hops downstream (transitive execution flow)"
+
+
+def _basename(file_path: str) -> str:
+    """Return the file name portion of a (possibly slash-separated) path."""
+    return file_path.replace("\\", "/").rsplit("/", maxsplit=1)[-1]
+
+
+def _loc(node: Node) -> str:
+    """Render a compact ``basename:line`` location for a node."""
+    return f"{_basename(node.file_path)}:{node.start_line}"
+
+
+def _fence(code: str) -> str:
+    """Wrap ``code`` in a python code fence wide enough to survive inner backticks.
+
+    Per CommonMark, a fenced block ends only on a backtick run at least as long
+    as its opener. Choosing one more backtick than the longest run inside the
+    source keeps embedded triple-backticks (or ``</source>``-style strings) from
+    prematurely closing the block — the prompt-injection watch-out in #19.
+    """
+    longest = max((len(run) for run in _BACKTICK_RUN.findall(code)), default=0)
+    fence = "`" * max(3, longest + 1)
+    body = code if code.endswith("\n") else code + "\n"
+    return f"{fence}python\n{body}{fence}"
+
+
+def _caller_line(node: Node) -> str:
+    """Bullet for a caller/callee: full FQN + type + location (joinable)."""
+    return f"- {node.id} ({node.type.value}, {_loc(node)})"
+
+
+def _sibling_line(node: Node) -> str:
+    """Bullet for a class sibling: short name + type + location (compact)."""
+    return f"- {node.name} ({node.type.value}, {_loc(node)})"
+
+
+def _neutralize_closing_tags(code: str) -> str:
+    """Escape only *this module's* closing tags in source so it can't close the prompt.
+
+    The adaptive backtick fence stops a code block from closing early, but a file
+    literally containing ``</source>``/``</context>`` could otherwise close the
+    surrounding XML tag and inject instructions (#19 watch-out #2). We neutralise
+    exactly the closing tags this module emits — leaving unrelated markup such as
+    TS/JSX ``</div>``, return arrows (``->``) and generics verbatim for the agent.
+    """
+    return _OWN_CLOSING_TAG.sub(r"&lt;/\1>", code)
+
+
+def _source_section(source: str) -> str:
+    """Render the <source> tag, fencing real code (closing-tag-safe) or noting its absence."""
+    if not source.strip():
+        return "<source>(source unavailable)</source>"
+    return f"<source>\n{_fence(_neutralize_closing_tags(source))}\n</source>"
+
+
+def _class_section(class_node: Node | None, siblings: list[Node]) -> str:
+    """Render the <class> tag with sibling members, or a standalone-function note."""
+    if class_node is None:
+        return "<class>none — module-level function</class>"
+    members = "\n".join(_sibling_line(s) for s in siblings) or "(no other members)"
+    name = _escape_xml_attr(class_node.id)
+    file_attr = _escape_xml_attr(f"{class_node.file_path}:{class_node.start_line}")
+    header = f'<class name="{name}" file="{file_attr}">'
+    return f"{header}\n{members}\n</class>"
+
+
+def _domain_section(focus: Node) -> str | None:
+    """Render the L3 <domain> boundary block, or ``None`` when the node has no domain tags.
+
+    Surfacing the focal node's architectural domain lets an agent respect
+    boundary rules during refactoring (the two-layer-context insight from #19).
+    Gated on ``focus.domains`` — the real semantic signal — so the structural
+    ``ontology_class`` fallback (``"Function"``/``"Method"``/``"Class"``) that
+    every node carries does not emit a meaningless boundary block.
+    """
+    if not focus.domains:
+        return None
+    ontology = _escape_xml_attr(focus.ontology_class or "-")
+    domains = _escape_xml_attr(", ".join(focus.domains))
+    return (
+        f'<domain ontology_class="{ontology}" domains="{domains}">'
+        "respect these architectural boundaries when refactoring"
+        "</domain>"
+    )
+
+
+def _callers_section(callers: list[Node], depth: int) -> str:
+    """Render the <callers> tag, with an explicit note when there are none."""
+    body = "\n".join(_caller_line(c) for c in callers) or "none — no upstream callers"
+    return f'<callers note="{_callers_note(depth)}">\n{body}\n</callers>'
+
+
+def _callees_section(callees: list[Node], unresolved_callees: list[str], depth: int) -> str:
+    """Render the <callees> tag: resolved deps plus flagged unresolved targets."""
+    lines = [_caller_line(c) for c in callees]
+    lines += [f"- {name} (unresolved)" for name in unresolved_callees]
+    body = "\n".join(lines) or "none"
+    return f'<callees note="{_callees_note(depth)}">\n{body}\n</callees>'
+
+
+def compile_context(
+    focus: Node,
+    source: str,
+    class_node: Node | None,
+    siblings: list[Node],
+    callers: list[Node],
+    callees: list[Node],
+    unresolved_callees: list[str],
+    depth: int = 1,
+) -> str:
+    """Assemble the XML-tagged context package for ``focus``.
+
+    ``source`` is the focal node's raw code (already read from disk, may be
+    empty). ``class_node``/``siblings`` describe the enclosing class (``None``
+    for a module-level function). ``callers``/``callees`` are the CALLS
+    neighbours reached within ``depth`` hops; ``unresolved_callees`` are
+    raw_call target names that never resolved to a node, listed so the agent
+    knows the dependency exists but is external/dynamic. ``depth`` is carried
+    only to label the caller/callee notes honestly — at depth 1 they are
+    "direct", above it the note states the hop bound rather than claiming
+    directness.
+    """
+    focal = _escape_xml_attr(focus.id)
+    file_attr = _escape_xml_attr(f"{focus.file_path}:{focus.start_line}-{focus.end_line}")
+    header = f'<context focal="{focal}" type="{focus.type.value}" file="{file_attr}">'
+    sections = [
+        _source_section(source),
+        _class_section(class_node, siblings),
+        _domain_section(focus),
+        _callers_section(callers, depth),
+        _callees_section(callees, unresolved_callees, depth),
+    ]
+    body = "\n\n".join(section for section in sections if section)
+    return f"{header}\n\n{body}\n\n</context>"