sourcecode 1.72.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

sourcecode/__init__.py

@@ -1,3 +1,7 @@
-"""sourcecode — Deterministic codebase context maps for AI coding agents."""
+"""ASK Engine (CLI: ``ask``) — Deterministic codebase context maps for AI coding agents.
 
-__version__ = "1.72.0"
+ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode`` is
+the legacy compatibility alias and the Python/PyPI package name. See
+docs/PRODUCT_IDENTITY.md (normative)."""
+
+__version__ = "2.0.0"

sourcecode/architecture_analyzer.py

@@ -960,75 +960,83 @@ class ArchitectureAnalyzer:
     # Java annotation / base-class secondary scanner (C4)
     # ------------------------------------------------------------------
 
-    _ANNOTATION_DECL_RE = re.compile(
-        r"@interface\s+([A-Z][A-Za-z0-9_]+)", re.MULTILINE
-    )
-    _ANNOTATION_USAGE_RE = re.compile(
-        r"@([A-Z][A-Za-z0-9_]+)(?:\s*\(([^)]*)\))?", re.MULTILINE
-    )
-    _EXTENDS_RE = re.compile(
-        r"class\s+\w+\s+extends\s+([A-Z][A-Za-z0-9_]+)", re.MULTILINE
-    )
-    _ANNOTATION_PARAM_RE = re.compile(r"(\w+)\s*=\s*[\"']?([^,\"')]+)[\"']?")
-    _MAX_JAVA_SCAN = 2000  # cap files to avoid runaway scanning
+    # Annotations never reported as "custom": Java/Spring/JPA/bean-validation
+    # built-ins. (Kept from the historical text scan; the counts now come from
+    # the ContextGraph's node-grounded `annotated_with` relations.)
+    _BUILTIN_ANNOTATIONS: frozenset = frozenset({
+        "Override", "SuppressWarnings", "Deprecated", "FunctionalInterface",
+        "SafeVarargs", "Retention", "Target", "Documented", "Inherited",
+        "RestController", "Service", "Repository", "Component", "Controller",
+        "Autowired", "Value", "Bean", "Configuration", "SpringBootApplication",
+        "EnableAutoConfiguration", "Transactional", "RequestMapping",
+        "GetMapping", "PostMapping", "PutMapping", "DeleteMapping",
+        "PathVariable", "RequestBody", "RequestParam", "ResponseBody",
+        "NotNull", "NotBlank", "Size", "Min", "Max", "Valid",
+    })
+    # @interface member return types the historical scan reported as parameters.
+    _ANNOTATION_PARAM_TYPES: frozenset = frozenset({"String", "int", "boolean", "Class"})
 
     def _scan_java_patterns(
         self,
         root: Path,
         java_paths: list[str],
     ) -> tuple[list[dict], list[dict]]:
-        """Scan Java source files for custom @interface annotations and common base classes.
+        """Derive custom @interface annotations and common base classes from the
+        ContextGraph (the single structural access layer — no source parsing).
+
+        Counts are node-grounded: an annotation usage is an `annotated_with`
+        relation on a real symbol, and a subclass is an `extends` relation —
+        occurrences inside string literals, comments, or dead text never count
+        (the historical text scan could).
 
         Returns (custom_annotations, base_classes) lists for ArchitectureAnalysis.
         """
-        from sourcecode.tree_utils import safe_read_text
+        from sourcecode.context_graph import ContextGraph
+
+        graph = ContextGraph.build(java_paths, root)
 
-        annotation_decls: dict[str, dict] = {}  # name → {params, files, usage_count}
-        annotation_usage: dict[str, int] = {}    # name → total usages across codebase
+        annotation_decls: dict[str, dict] = {}  # name → {params, usage_count, purpose}
+        annotation_usage: dict[str, int] = {}    # name → node-grounded usages
         extends_counts: dict[str, int] = {}      # base_class_name → subclass count
 
-        for path_str in java_paths[:self._MAX_JAVA_SCAN]:
-            abs_path = root / path_str
-            try:
-                content = safe_read_text(abs_path)
-            except OSError:
+        # Custom annotation declarations: @interface nodes + their members with
+        # the historically-reported parameter return types.
+        for ann in graph.annotation_types():
+            ann_name = ann.fqn.rsplit(".", 1)[-1]
+            if ann_name in annotation_decls:
                 continue
+            prefix = ann.fqn + "#"
+            # Member return type from the node signature "(params)->ReturnType".
+            params = [
+                m.fqn[len(prefix):]
+                for m in graph.symbols(kind="method")
+                if m.fqn.startswith(prefix)
+                and (m.signature or "").rsplit("->", 1)[-1] in self._ANNOTATION_PARAM_TYPES
+            ]
+            annotation_decls[ann_name] = {
+                "name": ann_name,
+                "parameters": params,
+                "usage_count": 0,
+                "purpose": "",
+            }
 
-            # Custom annotation declarations: `public @interface FooAnnotation`
-            for m in self._ANNOTATION_DECL_RE.finditer(content):
-                ann_name = m.group(1)
-                if ann_name not in annotation_decls:
-                    # Extract parameters from the annotation body (next ~500 chars)
-                    body_start = m.end()
-                    body = content[body_start:body_start + 500]
-                    params = re.findall(r"(?:String|int|boolean|Class)\s+(\w+)\s*\(\)", body)
-                    annotation_decls[ann_name] = {
-                        "name": ann_name,
-                        "parameters": params,
-                        "usage_count": 0,
-                        "purpose": "",
-                    }
-
-            # Annotation usage frequency
-            for m in self._ANNOTATION_USAGE_RE.finditer(content):
-                ann_name = m.group(1)
-                # Skip common Java built-ins
-                if ann_name in {
-                    "Override", "SuppressWarnings", "Deprecated", "FunctionalInterface",
-                    "SafeVarargs", "Retention", "Target", "Documented", "Inherited",
-                    "RestController", "Service", "Repository", "Component", "Controller",
-                    "Autowired", "Value", "Bean", "Configuration", "SpringBootApplication",
-                    "EnableAutoConfiguration", "Transactional", "RequestMapping",
-                    "GetMapping", "PostMapping", "PutMapping", "DeleteMapping",
-                    "PathVariable", "RequestBody", "RequestParam", "ResponseBody",
-                    "NotNull", "NotBlank", "Size", "Min", "Max", "Valid",
-                }:
-                    continue
-                annotation_usage[ann_name] = annotation_usage.get(ann_name, 0) + 1
-
-            # extends BaseClass — count subclasses per base
-            for m in self._EXTENDS_RE.finditer(content):
-                base = m.group(1)
+        # Annotation usage frequency — one count per annotated_with relation.
+        for rel in graph.relations(kind="annotated_with"):
+            ann_name = rel.target.lstrip("@").rsplit(".", 1)[-1]
+            if not ann_name or not ann_name[0].isupper():
+                continue
+            if ann_name in self._BUILTIN_ANNOTATIONS:
+                continue
+            annotation_usage[ann_name] = annotation_usage.get(ann_name, 0) + 1
+
+        # extends BaseClass — count subclasses per base (class extends only,
+        # matching the historical `class X extends Y` scan).
+        class_fqns = {s.fqn for s in graph.symbols(kind="class")}
+        for rel in graph.relations(kind="extends"):
+            if rel.source not in class_fqns:
+                continue  # interface-extends-interface is not a subclass count
+            base = re.sub(r"<.*", "", rel.target).rsplit(".", 1)[-1].strip()
+            if base and base[0].isupper():
                 extends_counts[base] = extends_counts.get(base, 0) + 1
 
         # Merge usage counts into annotation_decls

sourcecode/ast_extractor.py

@@ -940,171 +940,136 @@ def _extract_python(path: str, source: str) -> FileContract:
 
 
 # ---------------------------------------------------------------------------
+# Java extraction — projected from ContextGraph (single source of truth)
 # ---------------------------------------------------------------------------
-# Enhanced Java extraction (regex-based, annotation-aware)
-# ---------------------------------------------------------------------------
+#
+# The per-file Java contract is no longer parsed with a private regex pass.
+# It is projected from the ContextGraph symbol/relation model — the same model
+# repository_ir already builds — so the codebase carries exactly one Java parse
+# path. ContractPipeline builds one repo-level graph and injects it via
+# `AstExtractor.set_repo_graph`; a standalone `extract()` (no injected graph)
+# falls back to a single-file graph build. Either way the projection below is
+# the only code path, so behaviour is identical whether shared or per-file.
 
-_JAVA_IMPORT_RE = re.compile(r'^import\s+(?:static\s+)?([^;\s]+)\s*;', re.MULTILINE)
-
-# Single annotation on one line (captures name + optional parens args)
-_JAVA_ANNO_LINE_RE = re.compile(r'^\s*(@[\w.]+(?:\s*\([^)]*\))?)\s*$')
-# Class/interface/enum declaration line (public or package-private)
-_JAVA_CLASS_LINE_RE = re.compile(
-    r'(?:public\s+)?(?:(?:abstract|final|static|sealed)\s+)*'
-    r'(class|interface|enum|@interface)\s+(\w+)'
-    r'(?:\s+extends\s+([\w.]+))?'
-    r'(?:\s+implements\s+([\w.,\s<>]+?))?'
-    r'(?=\s*[\{<])'
-)
-# Public method: up to 12 leading spaces, return type, name, open paren
-_JAVA_PUB_METHOD_LINE_RE = re.compile(
-    r'^\s{0,12}public\s+(?:(?:static|final|synchronized|abstract|default)\s+)*'
-    r'[\w<>\[\]?,\s]+?\s+(\w+)\s*\(',
-    re.MULTILINE,
-)
-# @Autowired or @Inject field
-_JAVA_FIELD_DECL_RE = re.compile(
-    r'^\s*(?:private|protected|public)?\s*'
-    r'([\w<>.,\[\]? ]+?)\s+(\w+)\s*[;=]'
-)
+_JAVA_DI_FIELD_ANNS: frozenset[str] = frozenset({"@Autowired", "@Inject"})
 
 
-def _java_collect_preceding_annotations(lines: list[str], decl_idx: int) -> list[str]:
-    """Walk back from decl_idx and collect @annotation lines immediately before it."""
-    annotations: list[str] = []
-    i = decl_idx - 1
-    while i >= 0:
-        stripped = lines[i].strip()
-        if not stripped or stripped.startswith("//") or stripped.startswith("*"):
-            i -= 1
-            continue
-        m = re.match(r'(@[\w.]+(?:\s*\([^)]*\))?)', stripped)
-        if m:
-            annotations.insert(0, m.group(1))
-            i -= 1
-        else:
-            break
-    return annotations
+def _java_simple_name(fqn: str) -> str:
+    """Declared name from a symbol FQN. For a member (`pkg.Type#member`) keep
+    the part after `#`; for a type or field keep the last dotted segment."""
+    return fqn.rsplit("#", 1)[-1].rsplit(".", 1)[-1]
 
 
-def _extract_java(path: str, source: str) -> FileContract:
-    exports: list[ExportRecord] = []
-    types: list[TypeDefinition] = []
-    functions: list[FunctionSignature] = []
-    imports: list[ImportRecord] = []
-    autowired_fields: list[dict] = []
+def _java_contract_from_graph(rel_path: str, graph: "Any") -> FileContract:
+    """Project a Java FileContract for one file from the ContextGraph.
 
-    lines = source.splitlines()
+    Structural facts (types, members, imports, DI fields) are read from graph
+    nodes/edges instead of re-parsing source. Method signatures are the graph's
+    canonical compact form (`(Type)->Return`); annotations are node-grounded.
+    """
+    file_syms = [s for s in graph.symbols() if s.source_file == rel_path]
+    type_syms = [s for s in file_syms if s.kind in ("class", "interface", "enum", "annotation")]
+    type_fqns = {s.fqn for s in type_syms}
+
+    # extends / implements edges out of this file's types (targets are simple
+    # names for out-of-repo supertypes, resolved FQNs for in-repo ones — the
+    # same forms the old regex captured for the unresolved case).
+    extends_of: dict[str, list[str]] = {}
+    implements_of: dict[str, list[str]] = {}
+    import_targets: set[str] = set()
+    for r in graph.relations():
+        if r.source not in type_fqns:
+            continue
+        if r.kind == "extends":
+            extends_of.setdefault(r.source, []).append(r.target)
+        elif r.kind == "implements":
+            implements_of.setdefault(r.source, []).append(r.target)
+        elif r.kind == "imports":
+            import_targets.add(r.target)
 
-    # Pass 1: collect imports
-    seen_sources: set[str] = set()
-    for m in _JAVA_IMPORT_RE.finditer(source):
-        full_import = m.group(1).strip()
-        if full_import not in seen_sources:
-            seen_sources.add(full_import)
-            imports.append(ImportRecord(source=full_import, kind="named", symbols=[]))
+    exports: list[ExportRecord] = []
+    types: list[TypeDefinition] = []
+    for s in sorted(type_syms, key=lambda s: s.fqn):
+        name = _java_simple_name(s.fqn)
+        export_kind = "class" if s.kind == "annotation" else s.kind
+        parents = extends_of.get(s.fqn, [])
+        impls = sorted(implements_of.get(s.fqn, []))
+        exports.append(ExportRecord(
+            name=name,
+            kind=export_kind,
+            annotations=list(s.annotations),
+            extends=parents[0] if parents else None,
+            implements=impls,
+        ))
+        types.append(TypeDefinition(
+            name=name,
+            kind=export_kind,
+            fields=[],
+            extends=sorted(parents),
+        ))
 
-    # Pass 2: line-by-line scan for classes, methods, @Autowired fields
-    class_names: set[str] = set()
+    # Public methods (match the historical `public`-keyword scope). Constructors
+    # are a distinct node kind and stay excluded, as the old return-type regex
+    # excluded them. Dedup by name, keeping first in FQN order.
+    functions: list[FunctionSignature] = []
     seen_methods: set[str] = set()
-    autowired_pending = False
-
-    for idx, line in enumerate(lines):
-        stripped = line.strip()
-
-        # Detect @Autowired / @Inject annotations
-        if stripped.startswith("@Autowired") or stripped.startswith("@Inject"):
-            autowired_pending = True
+    for s in sorted((m for m in file_syms if m.kind == "method"), key=lambda s: s.fqn):
+        if "public" not in s.modifiers:
             continue
-
-        # Capture autowired field on next non-annotation, non-blank line
-        if autowired_pending and stripped and not stripped.startswith("@"):
-            autowired_pending = False
-            fm = _JAVA_FIELD_DECL_RE.match(line)
-            if fm:
-                type_name = fm.group(1).strip().split()[-1]  # last word = simple type
-                field_name = fm.group(2).strip()
-                if field_name and type_name and field_name not in {"class", "interface"}:
-                    autowired_fields.append({"type": type_name, "name": field_name})
-        elif stripped and not stripped.startswith("@"):
-            autowired_pending = False
-
-        # Class/interface/enum declaration
-        cm = _JAVA_CLASS_LINE_RE.search(stripped)
-        if cm and ("class " in stripped or "interface " in stripped or "enum " in stripped):
-            kind_kw = cm.group(1)  # class | interface | enum | @interface
-            name = cm.group(2)
-            extends_str = cm.group(3)
-            implements_str = cm.group(4)
-
-            annotations = _java_collect_preceding_annotations(lines, idx)
-            all_extends: list[str] = []
-            if extends_str:
-                all_extends.append(extends_str.strip())
-
-            implements_list: list[str] = []
-            if implements_str:
-                implements_list = [i.strip() for i in implements_str.split(",") if i.strip()]
-
-            export_kind = "class" if kind_kw in ("class", "@interface") else kind_kw
-            exports.append(ExportRecord(
-                name=name,
-                kind=export_kind,
-                annotations=annotations,
-                extends=extends_str.strip() if extends_str else None,
-                implements=implements_list,
-            ))
-            types.append(TypeDefinition(
-                name=name,
-                kind=export_kind,
-                fields=[],
-                extends=all_extends,
-            ))
-            class_names.add(name)
-
-    # Pass 3: public methods with their preceding annotations
-    for m in _JAVA_PUB_METHOD_LINE_RE.finditer(source):
-        sig_text = m.group(0).strip()
-        mname = m.group(1)
-        if (mname in class_names or mname in seen_methods
-                or mname in {"if", "for", "while", "switch", "return", "new"}):
+        mname = _java_simple_name(s.fqn)
+        if mname in seen_methods:
             continue
         seen_methods.add(mname)
-        # Find line index for this match to collect preceding annotations
-        line_start = source.count("\n", 0, m.start())
-        annotations = _java_collect_preceding_annotations(lines, line_start)
         exports.append(ExportRecord(
             name=mname,
             kind="method",
-            annotations=annotations,
-            signature=sig_text,
+            annotations=list(s.annotations),
+            signature=s.signature or None,
         ))
         functions.append(FunctionSignature(
             name=mname,
-            signature=sig_text,
+            signature=s.signature or "",
             async_=False,
             exported=True,
             return_type=None,
         ))
 
+    # DI fields: @Autowired / @Inject field nodes → {type, name}. The field
+    # node's signature is "Type name"; take the type's simple last token.
+    autowired_fields: list[dict] = []
+    for s in sorted((f for f in file_syms if f.kind == "field"), key=lambda s: s.fqn):
+        if not any(a in _JAVA_DI_FIELD_ANNS for a in s.annotations):
+            continue
+        sig = s.signature or ""
+        type_tok = sig.split()[0] if sig else ""
+        type_name = re.sub(r"<.*", "", type_tok).rsplit(".", 1)[-1]
+        field_name = _java_simple_name(s.fqn)
+        if field_name and type_name:
+            autowired_fields.append({"type": type_name, "name": field_name})
+
+    imports = [
+        ImportRecord(source=fqn, kind="named", symbols=[])
+        for fqn in sorted(import_targets)
+    ]
+
     # External deps: top-2 package segments, skip java.* / javax.*
     deps = sorted({
-        ".".join(imp.source.split(".")[:2])
-        for imp in imports
-        if not imp.source.startswith("java.") and not imp.source.startswith("javax.")
-        and len(imp.source.split(".")) >= 2
+        ".".join(fqn.split(".")[:2])
+        for fqn in import_targets
+        if not fqn.startswith("java.") and not fqn.startswith("javax.")
+        and len(fqn.split(".")) >= 2
     })
 
     return FileContract(
-        path=path,
+        path=rel_path,
         language="java",
         exports=exports,
-        imports=sorted(imports, key=lambda i: i.source)[:30],
+        imports=imports[:30],
         functions=sorted(functions, key=lambda f: f.name)[:20],
         types=sorted(types, key=lambda t: t.name),
         dependencies=deps[:20],
         autowired_fields=autowired_fields[:20],
-        extraction_method="heuristic",
+        extraction_method="graph",
     )
 
 
@@ -1245,6 +1210,26 @@ class AstExtractor:
         self.max_file_size = max_file_size
         self._ts_checked = False
         self._ts_ok = False
+        # Repo-level ContextGraph for Java projection, injected by
+        # ContractPipeline so all files share one parse. (root, graph).
+        self._repo_graph_root: Optional[Path] = None
+        self._repo_graph: Optional[Any] = None
+
+    def set_repo_graph(self, graph: "Any", root: Path) -> None:
+        """Inject a pre-built repo-level ContextGraph so per-file Java contracts
+        project from it instead of each building a single-file graph."""
+        self._repo_graph = graph
+        self._repo_graph_root = root
+
+    def _java_graph_for(self, root: Path) -> "Any":
+        """Return the shared graph when it covers `root`, else build a
+        single-file-scope graph for standalone extraction."""
+        if self._repo_graph is not None and self._repo_graph_root == root:
+            return self._repo_graph
+        from sourcecode.context_graph import ContextGraph
+        from sourcecode.repository_ir import find_java_files
+        files = find_java_files(root)
+        return ContextGraph.build(files, root)
 
     def _ensure_ts(self) -> bool:
         if not self._ts_checked:
@@ -1268,12 +1253,13 @@ class AstExtractor:
         if language is None:
             return None
 
+        rel_path = str(path.relative_to(root)).replace("\\", "/") if root else path.name
+
         try:
             stat = path.stat()
             if stat.st_size > self.max_file_size:
-                rel = str(path.relative_to(root)) if root else path.name
                 return FileContract(
-                    path=rel,
+                    path=str(path.relative_to(root)) if root else path.name,
                     language=language,
                     extraction_method="heuristic",
                     limitations=[f"file_too_large: {stat.st_size} bytes > {self.max_file_size}"],
@@ -1281,17 +1267,26 @@ class AstExtractor:
         except OSError:
             return None
 
+        # Java is projected from the ContextGraph, not re-parsed from source.
+        # Use the repo-level graph ContractPipeline injected when it covers this
+        # root; otherwise build a single-file graph (standalone `extract`).
+        if language == "java" and root is not None:
+            graph = self._java_graph_for(root)
+            contract = _java_contract_from_graph(rel_path, graph)
+            contract.role = _detect_role(rel_path, contract)
+            return contract
+
         try:
             source = path.read_text(encoding="utf-8", errors="replace")
         except OSError:
             return None
 
-        rel_path = str(path.relative_to(root)).replace("\\", "/") if root else path.name
-
         if language == "python":
             contract = _extract_python(rel_path, source)
         elif language == "java":
-            contract = _extract_java(rel_path, source)
+            # No root to resolve a graph against — degrade to an empty contract
+            # rather than reintroduce a regex parser.
+            contract = FileContract(path=rel_path, language="java", extraction_method="graph")
         else:
             if self._ensure_ts():
                 lang_obj = _get_ts_lang(language)

sourcecode/call_surface.py

@@ -0,0 +1,112 @@
+"""Outgoing call surface — the first consumer built on the Semantic IR P-A
+primitives (ADR-0001 §6, P5.1 proof point).
+
+An *outgoing call surface* is, for one method/constructor body, the complete set
+of things it calls and instantiates — in source order, with receiver, argument
+count, and resolution status. Computing it naively requires parsing method
+bodies; here it is a pure query over the Body-Reference atoms
+(`ContextGraph.invocations_in` / `instantiations_in`). This module reads **no
+source** (INV-1): its only input is a built `ContextGraph`.
+
+Why this is not already derivable from the L1 `calls` edge set: L1 edges are
+dedup, class/method-level, and record only *resolved* links — an external call
+like `repo.save(o)` (where `repo` is an injected field of a type outside the
+module) produces **no** `calls` edge, yet it is part of the method's real call
+surface. The P-A atoms retain exactly that discarded knowledge: unresolved
+external calls, call ordering, argument counts, and duplicate call sites. This
+module surfaces it.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:  # avoid import cycle; only a type hint
+    from sourcecode.context_graph import ContextGraph
+
+
+@dataclass(frozen=True)
+class OutgoingCall:
+    """One method-call occurrence leaving a body. `resolved` is True when the IR
+    could bind the callee to a concrete symbol (`resolved_fqn` set); False for
+    honest-unresolved external / overloaded / dynamic calls."""
+
+    callee: str
+    receiver: Optional[str]
+    arg_count: int
+    resolved_fqn: Optional[str]
+    occurrence: int
+
+    @property
+    def resolved(self) -> bool:
+        return self.resolved_fqn is not None
+
+
+@dataclass(frozen=True)
+class OutgoingInstantiation:
+    """One `new Type(...)` occurrence leaving a body."""
+
+    type: str
+    arg_count: int
+    resolved_fqn: Optional[str]
+    occurrence: int
+
+    @property
+    def resolved(self) -> bool:
+        return self.resolved_fqn is not None
+
+
+@dataclass(frozen=True)
+class CallSurface:
+    """The full outgoing surface of one owner (method/constructor), ordered by
+    source occurrence within each stream."""
+
+    owner_fqn: str
+    calls: tuple[OutgoingCall, ...]
+    instantiations: tuple[OutgoingInstantiation, ...]
+
+    @property
+    def resolved_calls(self) -> tuple[OutgoingCall, ...]:
+        return tuple(c for c in self.calls if c.resolved)
+
+    @property
+    def unresolved_calls(self) -> tuple[OutgoingCall, ...]:
+        """External / overloaded / dynamic calls the IR does not bind — the
+        blind spot the L1 `calls` edge set drops entirely."""
+        return tuple(c for c in self.calls if not c.resolved)
+
+    @property
+    def is_empty(self) -> bool:
+        return not self.calls and not self.instantiations
+
+
+def outgoing_call_surface(graph: "ContextGraph", owner_fqn: str) -> CallSurface:
+    """Outgoing call surface for a single method/constructor owner. Returns an
+    empty (non-None) surface when the owner has no body atoms."""
+    calls = tuple(
+        OutgoingCall(
+            callee=i.callee, receiver=i.receiver, arg_count=i.arg_count,
+            resolved_fqn=i.resolved_fqn, occurrence=i.occurrence,
+        )
+        for i in graph.invocations_in(owner_fqn)
+    )
+    insts = tuple(
+        OutgoingInstantiation(
+            type=n.type, arg_count=n.arg_count,
+            resolved_fqn=n.resolved_fqn, occurrence=n.occurrence,
+        )
+        for n in graph.instantiations_in(owner_fqn)
+    )
+    return CallSurface(owner_fqn=owner_fqn, calls=calls, instantiations=insts)
+
+
+def call_surfaces(graph: "ContextGraph") -> dict[str, CallSurface]:
+    """Outgoing call surface for every method/constructor with body atoms, keyed
+    by owner FQN and sorted for determinism. Owners with an empty surface are
+    omitted."""
+    out: dict[str, CallSurface] = {}
+    for s in graph.symbols(kind="method") + graph.symbols(kind="constructor"):
+        surface = outgoing_call_surface(graph, s.fqn)
+        if not surface.is_empty:
+            out[s.fqn] = surface
+    return {k: out[k] for k in sorted(out)}