codeanalyzer-python 0.3.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

codeanalyzer/schema/py_schema.py

@@ -20,9 +20,8 @@ This module defines the data models used to represent Python code structures
 for static analysis purposes.
 """
 from __future__ import annotations
-import inspect
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Tuple
 import gzip
 
 from pydantic import BaseModel
@@ -120,12 +119,23 @@ def builder(cls):
     # Get type hints and default values for the fields in the model.
     # For example, {file_path: Path, module_name: str, imports: List[PyImport], ...}
     annotations = cls.__annotations__
-    # Get default values for the fields in the model.
-    defaults = {
-        f.name: f.default
-        for f in inspect.signature(cls).parameters.values()
-        if f.default is not inspect.Parameter.empty
-    }
+    # Get default values for the fields in the model. `inspect.signature` is
+    # unreliable for models carrying forward references (e.g. PyCallable's
+    # self-referential ``callables``): Pydantic falls back to a generic
+    # ``(**data)`` signature that drops the per-field defaults, so the builder
+    # would seed those fields with ``None`` and fail validation. Read the declared
+    # defaults straight off the model instead. Required fields are intentionally
+    # omitted (seeded ``None``) — the builder chain must set them.
+    defaults = {}
+    model_fields = getattr(cls, "model_fields", None)  # Pydantic v2
+    if model_fields:
+        for name, field in model_fields.items():
+            if not field.is_required():
+                defaults[name] = field.get_default(call_default_factory=True)
+    else:  # Pydantic v1
+        for name, field in getattr(cls, "__fields__", {}).items():
+            if not field.required:
+                defaults[name] = field.get_default()
     # Create a namespace for the builder class.
     namespace = {}
 
@@ -168,6 +178,71 @@ def builder(cls):
     return cls
 
 
+def byte_offsets(source: str, start_line: int, start_col: int,
+                 end_line: int, end_col: int) -> Tuple[int, int]:
+    """Convert (1-based line, 0-based col) ast positions to utf-8 byte offsets
+    into `source`. `col` is a character offset within the line (ast semantics);
+    we re-encode the line prefix to bytes so multibyte chars are handled."""
+    lines = source.splitlines(keepends=True)
+    def offset(line: int, col: int) -> int:
+        prefix_bytes = len("".join(lines[: line - 1]).encode("utf-8"))
+        col_bytes = len(lines[line - 1][:col].encode("utf-8")) if line - 1 < len(lines) else 0
+        return prefix_bytes + col_bytes
+    return offset(start_line, start_col), offset(end_line, end_col)
+
+
+@builder
+@msgpk
+class Span(BaseModel):
+    """Where a node lives in source. `start`/`end` are [line, col] (1-based line,
+    0-based col, ast semantics); `bytes` are utf-8 offsets into module.source."""
+    start: Tuple[int, int]
+    end: Tuple[int, int]
+    bytes: Tuple[int, int]
+
+
+@builder
+@msgpk
+class BodyNode(BaseModel):
+    """A node in a callable's `body`: an AST region (statement/call/branch/…) or
+    a synthetic analysis vertex (entry/exit/formal_in/out/actual_in/out)."""
+    kind: str
+    span: Optional[Span] = None
+    callee: Optional[str] = None   # only on `call` nodes; the sanctioned null→id slot
+    of: Optional[str] = None       # param vertices: the variable/return they carry
+    parent: Optional[str] = None   # actuals: owning callsite ordinal id
+
+
+@builder
+@msgpk
+class CfgEdge(BaseModel):
+    src: str; dst: str; kind: str = "fallthrough"
+
+
+@builder
+@msgpk
+class CdgEdge(BaseModel):
+    src: str; dst: str
+
+
+@builder
+@msgpk
+class DdgEdge(BaseModel):
+    src: str; dst: str; var: Optional[str] = None; prov: List[str] = []
+
+
+@builder
+@msgpk
+class SummaryEdge(BaseModel):
+    src: str; dst: str
+
+
+@builder
+@msgpk
+class ParamEdge(BaseModel):
+    src: str; dst: str
+
+
 @builder
 @msgpk
 class PyImport(BaseModel):
@@ -176,6 +251,7 @@ class PyImport(BaseModel):
     module: str
     name: str
     alias: Optional[str] = None
+    resolved_module: Optional[str] = None
     start_line: int = -1
     end_line: int = -1
     start_column: int = -1
@@ -216,7 +292,10 @@ class PyVariableDeclaration(BaseModel):
     """Represents a Python variable declaration."""
 
     name: str
-    type: Optional[str]
+    # Optional WITH a default: emission drops None (exclude_none), so a
+    # required-but-nullable field would make the emitted JSON fail its own
+    # model's validation whenever the type is uninferred.
+    type: Optional[str] = None
     initializer: Optional[str] = None
     value: Optional[Any] = None
     scope: Literal["module", "class", "function"] = "module"
@@ -240,6 +319,19 @@ class PyCallableParameter(BaseModel):
     end_column: int = -1
 
 
+@builder
+@msgpk
+class PyCallArgument(BaseModel):
+    """One call-site argument: AST category + inferred type, kept separate.
+
+    The legacy ``PyCallsite.argument_types`` mixed these two vocabularies
+    in one list; this model is the disambiguated replacement (#86).
+    """
+
+    ast_kind: str
+    inferred_type: Optional[str] = None
+
+
 @builder
 @msgpk
 class PyCallsite(BaseModel):
@@ -249,6 +341,7 @@ class PyCallsite(BaseModel):
     receiver_expr: Optional[str] = None
     receiver_type: Optional[str] = None
     argument_types: List[str] = []
+    arguments: List[PyCallArgument] = []
     return_type: Optional[str] = None
     callee_signature: Optional[str] = None
     is_constructor_call: bool = False
@@ -266,20 +359,27 @@ class PyCallable(BaseModel):
     name: str
     path: str
     signature: str  # e.g., module.<class_name>.function_name
+    id: str = ""
+    kind: str = "function"
+    span: Optional[Span] = None
     comments: List[PyComment] = []
     decorators: List[str] = []
     parameters: List[PyCallableParameter] = []
     return_type: Optional[str] = None
-    code: str = None
     start_line: int = -1
     end_line: int = -1
     code_start_line: int = -1
     accessed_symbols: List[PySymbol] = []
     call_sites: List[PyCallsite] = []
-    inner_callables: Dict[str, "PyCallable"] = {}
-    inner_classes: Dict[str, "PyClass"] = {}
+    callables: Dict[str, "PyCallable"] = {}  # nested callables (closures)
+    types: Dict[str, "PyClass"] = {}  # nested (local) classes
     local_variables: List[PyVariableDeclaration] = []
     cyclomatic_complexity: int = 0
+    body: Dict[str, BodyNode] = {}
+    cfg: List[CfgEdge] = []
+    cdg: List[CdgEdge] = []
+    ddg: List[DdgEdge] = []
+    summary: List[SummaryEdge] = []
 
     def __hash__(self) -> int:
         """Generate a hash based on the callable's signature."""
@@ -295,6 +395,7 @@ class PyClassAttribute(BaseModel):
 
     name: str
     type: Optional[str] = None
+    initializer: Optional[str] = None
     comments: List[PyComment] = []
     start_line: int = -1
     end_line: int = -1
@@ -307,12 +408,14 @@ class PyClass(BaseModel):
 
     name: str
     signature: str  # e.g., module.class_name
+    id: str = ""
+    kind: str = "class"
+    span: Optional[Span] = None
     comments: List[PyComment] = []
-    code: str = None
     base_classes: List[str] = []
-    methods: Dict[str, PyCallable] = {}
+    callables: Dict[str, PyCallable] = {}  # methods, keystone containment name
     attributes: Dict[str, PyClassAttribute] = {}
-    inner_classes: Dict[str, "PyClass"] = {}
+    types: Dict[str, "PyClass"] = {}  # inner classes, keystone containment name
     start_line: int = -1
     end_line: int = -1
 
@@ -328,9 +431,12 @@ class PyModule(BaseModel):
 
     file_path: str
     module_name: str
+    id: str = ""
+    kind: str = "module"
+    source: str = ""
     imports: List[PyImport] = []
     comments: List[PyComment] = []
-    classes: Dict[str, PyClass] = {}
+    types: Dict[str, PyClass] = {}  # classes, keystone containment name
     functions: Dict[str, PyCallable] = {}
     variables: List[PyVariableDeclaration] = []
     # Metadata for caching
@@ -342,41 +448,84 @@ class PyModule(BaseModel):
 @builder
 @msgpk
 class PyCallEdge(BaseModel):
-    """Identity-only call-graph edge with weight.
+    """Identity-only call-graph edge with weight (keystone shape: the list name
+    IS the edge type, so there is no ``type`` field).
 
-    Mirrors Java's ``CallDependency``. ``source`` and ``target`` are
-    ``PyCallable.signature`` strings — nodes of the graph are the existing
-    ``PyCallable`` entries in the symbol table, not a separate vertex type.
+    ``src`` and ``dst`` are node ids — the caller's ``can://`` id and the
+    callee's ``can://`` id (a symbol-table callable or an ``@external`` home).
     Rich per-call metadata (receiver, arguments, location, ...) lives on
     ``PyCallsite`` inside the source ``PyCallable.call_sites``.
     """
 
-    source: str  # caller's PyCallable.signature
-    target: str  # callee's PyCallable.signature
-    type: Literal["CALL_DEP"] = "CALL_DEP"
+    src: str  # caller callable id
+    dst: str  # callee callable (or external) id
     weight: int = 1
-    provenance: List[Literal["jedi", "pycg", "joern"]] = []
+    prov: List[Literal["jedi", "pycg", "joern"]] = []
 
 
 @builder
 @msgpk
 class PyExternalSymbol(BaseModel):
     """A call-graph target outside the analyzed project -- an imported library or
-    builtin member. Mirrors codeanalyzer-typescript's ``TSExternalSymbol`` and is
-    keyed in ``PyApplication.external_symbols`` by its call-graph signature."""
+    builtin member. An edge-endpoint id home, not a tree node: keyed in
+    ``PyApplication.external_symbols`` by its ``can://…/@external/…`` id."""
 
+    id: str = ""  # can://python/<app>/@external/<module>/<name>
+    kind: str = "external"
     name: str  # the member/short name, e.g. "get" for "requests.get"
     module: Optional[str] = None  # best-effort owning module, e.g. "requests"
 
 
+@builder
+@msgpk
+class PyRepositoryInfo(BaseModel):
+    """Where the analyzed source came from: git provenance captured at analysis time."""
+
+    uri: Optional[str] = None
+    revision: str
+    dirty: bool = False
+
+
+@builder
+@msgpk
+class PyAnalyzerInfo(BaseModel):
+    """Which analyzer produced this snapshot, and how it was configured.
+    Lives on the ``Analysis`` envelope (keystone ``analyzer{name,version}``;
+    ``config`` rides additively)."""
+
+    name: str = "codeanalyzer-python"
+    version: str = "unknown"
+    config: Dict[str, Any] = {}
+
+
 @builder
 @msgpk
 class PyApplication(BaseModel):
     """Represents a Python application."""
 
     symbol_table: Dict[str, PyModule]
+    id: str = ""
+    kind: str = "application"
     call_graph: List[PyCallEdge] = []
     # Call-graph endpoints not declared in the symbol table (imported library /
     # builtin members), keyed by signature. Populated by the analyzer so every
     # backend (JSON and Neo4j) shares one authoritative external-symbol set.
     external_symbols: Dict[str, PyExternalSymbol] = {}
+    # Git provenance of the analyzed checkout, captured at analysis time.
+    repository: Optional[PyRepositoryInfo] = None
+    # Interprocedural parameter-passing edges (formal↔actual); populated at L4.
+    param_in: List[ParamEdge] = []
+    param_out: List[ParamEdge] = []
+
+
+@builder
+@msgpk
+class Analysis(BaseModel):
+    """v2 payload root: envelope + the application tree node. ``k_limit`` is an
+    L3+ envelope key (None below the dataflow levels; exclude_none drops it)."""
+    schema_version: str = "2.0.0"
+    language: str = "python"
+    max_level: int = 1
+    k_limit: Optional[int] = None
+    analyzer: PyAnalyzerInfo = PyAnalyzerInfo()
+    application: PyApplication

codeanalyzer/semantic_analysis/call_graph.py

@@ -38,24 +38,24 @@ from codeanalyzer.schema.py_schema import (
 
 
 def _walk_class_callables(cls: PyClass) -> Iterator[PyCallable]:
-    for method in cls.methods.values():
+    for method in cls.callables.values():
         yield from _walk_callable(method)
-    for inner in cls.inner_classes.values():
+    for inner in cls.types.values():
         yield from _walk_class_callables(inner)
 
 
 def _walk_callable(c: PyCallable) -> Iterator[PyCallable]:
     yield c
-    for inner in c.inner_callables.values():
+    for inner in c.callables.values():
         yield from _walk_callable(inner)
-    for inner_cls in c.inner_classes.values():
+    for inner_cls in c.types.values():
         yield from _walk_class_callables(inner_cls)
 
 
 def _walk_module_callables(module: PyModule) -> Iterator[PyCallable]:
     for fn in module.functions.values():
         yield from _walk_callable(fn)
-    for cls in module.classes.values():
+    for cls in module.types.values():
         yield from _walk_class_callables(cls)
 
 
@@ -69,18 +69,18 @@ def iter_callables_in_symbol_table(
 
 def _walk_classes_in_class(cls: PyClass) -> Iterator[PyClass]:
     yield cls
-    for inner in cls.inner_classes.values():
+    for inner in cls.types.values():
         yield from _walk_classes_in_class(inner)
     # Classes can live inside methods (e.g. a factory method that defines
     # a helper class). Recurse through every method's callable subtree.
-    for method in cls.methods.values():
+    for method in cls.callables.values():
         yield from _walk_classes_in_callable(method)
 
 
 def _walk_classes_in_callable(c: PyCallable) -> Iterator[PyClass]:
-    for inner_cls in c.inner_classes.values():
+    for inner_cls in c.types.values():
         yield from _walk_classes_in_class(inner_cls)
-    for inner in c.inner_callables.values():
+    for inner in c.callables.values():
         yield from _walk_classes_in_callable(inner)
 
 
@@ -91,7 +91,7 @@ def iter_classes_in_symbol_table(
     inner classes, classes nested in functions, and classes nested in
     class methods."""
     for module in symbol_table.values():
-        for cls in module.classes.values():
+        for cls in module.types.values():
             yield from _walk_classes_in_class(cls)
         for fn in module.functions.values():
             yield from _walk_classes_in_callable(fn)
@@ -118,22 +118,21 @@ def to_digraph(app: PyApplication) -> nx.DiGraph:
     added as **ghost** nodes (``callable=None``, ``ghost=True``) so the
     edges are preserved.
 
-    Edges carry ``type``, ``weight``, and ``provenance`` attributes.
+    Edges carry ``weight`` and ``prov`` attributes.
     """
     g = nx.DiGraph()
     by_sig = callables_by_signature(app)
     for sig, c in by_sig.items():
         g.add_node(sig, callable=c, ghost=False)
     for e in app.call_graph:
-        for sig in (e.source, e.target):
+        for sig in (e.src, e.dst):
             if sig not in g.nodes:
                 g.add_node(sig, callable=None, ghost=True)
         g.add_edge(
-            e.source,
-            e.target,
-            type=e.type,
+            e.src,
+            e.dst,
             weight=e.weight,
-            provenance=list(e.provenance),
+            prov=list(e.prov),
         )
     return g
 
@@ -143,18 +142,16 @@ def from_digraph(g: nx.DiGraph) -> list:
 
     Only edges are extracted; nodes are not serialized here — they are
     expected to already exist as ``PyCallable`` entries in the symbol
-    table. Edge attributes default to ``CALL_DEP`` / weight 1 / empty
-    provenance when missing.
+    table. Edge attributes default to weight 1 / empty prov when missing.
     """
     edges = []
     for src, dst, data in g.edges(data=True):
         edges.append(
             PyCallEdge(
-                source=src,
-                target=dst,
-                type=data.get("type", "CALL_DEP"),
+                src=src,
+                dst=dst,
                 weight=int(data.get("weight", 1)),
-                provenance=list(data.get("provenance", [])),
+                prov=list(data.get("prov", data.get("provenance", []))),
             )
         )
     return edges
@@ -183,7 +180,7 @@ def jedi_call_graph_edges(
             counts[(caller.signature, site.callee_signature)] += 1
 
     return [
-        PyCallEdge(source=src, target=dst, weight=n, provenance=["jedi"])
+        PyCallEdge(src=src, dst=dst, weight=n, prov=["jedi"])
         for (src, dst), n in counts.items()
     ]
 
@@ -255,7 +252,7 @@ def filter_external_edges(
     Edges where an app callable calls a library function (or vice-versa) are
     retained; only lib→lib edges are dropped.  The app symbol set is built by
     walking every callable in the symbol table recursively (including nested
-    functions and closures via ``inner_callables``) plus every class, so
+    functions and closures via ``callables``) plus every class, so
     PyCG-discovered closure nodes are correctly recognised as app symbols.
     """
     app_symbols: set = {c.signature for c in iter_callables_in_symbol_table(symbol_table)}
@@ -263,7 +260,7 @@ def filter_external_edges(
 
     return [
         e for e in edges
-        if e.source in app_symbols or e.target in app_symbols
+        if e.src in app_symbols or e.dst in app_symbols
     ]
 
 
@@ -277,11 +274,11 @@ def merge_edges(*edge_lists: list) -> list:
     by_key: Dict[Tuple[str, str], PyCallEdge] = {}
     for edges in edge_lists:
         for e in edges:
-            k = (e.source, e.target)
+            k = (e.src, e.dst)
             if k in by_key:
                 cur = by_key[k]
                 cur.weight += e.weight
-                cur.provenance = sorted(set(cur.provenance) | set(e.provenance))
+                cur.prov = sorted(set(cur.prov) | set(e.prov))
             else:
                 by_key[k] = e.model_copy()
     return list(by_key.values())

codeanalyzer/semantic_analysis/pycg/pycg_analysis.py

@@ -431,14 +431,14 @@ class PyCG:
         """Sum weights of duplicate ``(source, target)`` pairs across shards."""
         merged: Dict[tuple, PyCallEdge] = {}
         for edge in edges:
-            key = (edge.source, edge.target)
+            key = (edge.src, edge.dst)
             if key in merged:
                 existing = merged[key]
                 merged[key] = PyCallEdge(
                     source=existing.source,
                     target=existing.target,
                     weight=existing.weight + edge.weight,
-                    provenance=existing.provenance,
+                    prov=existing.prov,
                 )
             else:
                 merged[key] = edge
@@ -564,7 +564,7 @@ class PyCG:
             edge_counts[(resolver.resolve(src), resolver.resolve(dst))] += 1
 
         return [
-            PyCallEdge(source=src, target=dst, weight=count, provenance=["pycg"])
+            PyCallEdge(src=src, dst=dst, weight=count, prov=["pycg"])
             for (src, dst), count in edge_counts.items()
         ]
 
@@ -751,7 +751,7 @@ class PyCG:
                     try:
                         triples = ray.get(fut)
                         edges_all.extend(
-                            PyCallEdge(source=s, target=t, weight=w, provenance=["pycg"])
+                            PyCallEdge(src=s, dst=t, weight=w, prov=["pycg"])
                             for s, t, w in triples
                         )
                     except Exception:
@@ -841,14 +841,14 @@ class PyCG:
         # Merge duplicate (source, target) pairs that appear in multiple shards.
         merged: Dict[tuple, PyCallEdge] = {}
         for edge in all_edges:
-            key = (edge.source, edge.target)
+            key = (edge.src, edge.dst)
             if key in merged:
                 existing = merged[key]
                 merged[key] = PyCallEdge(
                     source=existing.source,
                     target=existing.target,
                     weight=existing.weight + edge.weight,
-                    provenance=existing.provenance,
+                    prov=existing.prov,
                 )
             else:
                 merged[key] = edge
@@ -923,7 +923,7 @@ class PyCG:
                 try:
                     triples = ray.get(fut)
                     edges = [
-                        PyCallEdge(source=s, target=t, weight=w, provenance=["pycg"])
+                        PyCallEdge(src=s, dst=t, weight=w, prov=["pycg"])
                         for s, t, w in triples
                     ]
                     all_edges.extend(edges)
@@ -956,14 +956,14 @@ class PyCG:
 
         merged: Dict[tuple, PyCallEdge] = {}
         for edge in all_edges:
-            key = (edge.source, edge.target)
+            key = (edge.src, edge.dst)
             if key in merged:
                 existing = merged[key]
                 merged[key] = PyCallEdge(
                     source=existing.source,
                     target=existing.target,
                     weight=existing.weight + edge.weight,
-                    provenance=existing.provenance,
+                    prov=existing.prov,
                 )
             else:
                 merged[key] = edge
@@ -984,7 +984,7 @@ class PyCG:
         symbol_table: Dict[str, PyModule],
         jedi_edges: Optional[List[PyCallEdge]] = None,
     ) -> List[PyCallEdge]:
-        """Run PyCG and return ``PyCallEdge`` entries with ``provenance=["pycg"]``.
+        """Run PyCG and return ``PyCallEdge`` entries with ``prov=["pycg"]``.
 
         Edges are coalesced on ``(source, target)`` — ``weight`` equals the
         number of times PyCG reports the same (caller, callee) pair (always 1

codeanalyzer/semantic_analysis/pycg/shard_planner.py

@@ -66,17 +66,17 @@ logger = logging.getLogger(__name__)
 
 def _walk_callable_sigs(c: PyCallable) -> Iterator[str]:
     yield c.signature
-    for inner in c.inner_callables.values():
+    for inner in c.callables.values():
         yield from _walk_callable_sigs(inner)
-    for inner_cls in c.inner_classes.values():
+    for inner_cls in c.types.values():
         yield from _walk_class_sigs(inner_cls)
 
 
 def _walk_class_sigs(cls: PyClass) -> Iterator[str]:
     yield cls.signature
-    for method in cls.methods.values():
+    for method in cls.callables.values():
         yield from _walk_callable_sigs(method)
-    for inner in cls.inner_classes.values():
+    for inner in cls.types.values():
         yield from _walk_class_sigs(inner)
 
 
@@ -95,7 +95,7 @@ def _signature_to_file(symbol_table: Dict[str, PyModule]) -> Dict[str, str]:
         for fn in module.functions.values():
             for sig in _walk_callable_sigs(fn):
                 sig_to_file[sig] = module.file_path
-        for cls in module.classes.values():
+        for cls in module.types.values():
             for sig in _walk_class_sigs(cls):
                 sig_to_file[sig] = module.file_path
     return sig_to_file
@@ -152,8 +152,8 @@ def build_module_graph(
         g.add_node(module.file_path, module_name=module.module_name)
 
     for edge in jedi_edges:
-        src = sig_to_file.get(edge.source)
-        dst = sig_to_file.get(edge.target)
+        src = sig_to_file.get(edge.src)
+        dst = sig_to_file.get(edge.dst)
         if src is None or dst is None or src == dst:
             continue
         if g.has_edge(src, dst):

codeanalyzer/syntactic_analysis/import_resolver.py

@@ -0,0 +1,67 @@
+"""Static resolution of import spellings against the analyzed module set.
+
+Pure post-pass over a built ``PyApplication``: no filesystem access, no
+sys.path semantics — a spelling resolves iff it names a module that was
+itself analyzed (issue #82). External/library imports stay unresolved by
+design and keep their :PyPackage projection.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Dict, Optional, Union
+
+from codeanalyzer.schema.py_schema import PyApplication
+
+
+def _dotted_candidates(app: PyApplication, project_dir: Union[Path, str]) -> Dict[str, str]:
+    """dotted module path -> file_key, for every analyzed module.
+
+    ``pkg/util.py`` -> ``pkg.util``; ``pkg/__init__.py`` -> ``pkg``.
+    file_keys share project_dir's form (both come from the same CLI arg),
+    so os.path.relpath keeps mixed absolute/relative setups consistent.
+    """
+    mapping: Dict[str, str] = {}
+    for file_key in app.symbol_table:
+        rel = os.path.relpath(file_key, str(project_dir))
+        if rel.startswith(".."):
+            continue
+        parts = Path(rel).with_suffix("").parts
+        if parts and parts[-1] == "__init__":
+            parts = parts[:-1]
+        if parts:
+            mapping[".".join(parts)] = file_key
+    return mapping
+
+
+def _resolve_one(
+    spelling: str, original_name: str, importer_rel_parts: tuple, candidates: Dict[str, str]
+) -> Optional[str]:
+    if spelling.startswith("."):
+        level = len(spelling) - len(spelling.lstrip("."))
+        suffix = spelling.lstrip(".")
+        # level 1 = the importer's own package; each extra dot walks one up.
+        package_parts = importer_rel_parts[:-1]  # drop the filename
+        if level - 1 > len(package_parts):
+            return None
+        base = package_parts[: len(package_parts) - (level - 1)]
+        stems = list(base) + (suffix.split(".") if suffix else [])
+    else:
+        stems = spelling.split(".")
+    dotted = ".".join(stems)
+    with_name = f"{dotted}.{original_name}" if dotted else original_name
+    return candidates.get(with_name) or candidates.get(dotted)
+
+
+def resolve_imports(app: PyApplication, project_dir: Union[Path, str]) -> None:
+    """Stamp ``resolved_module`` on every import of every module, in place."""
+    candidates = _dotted_candidates(app, project_dir)
+    for file_key, module in app.symbol_table.items():
+        rel = os.path.relpath(file_key, str(project_dir))
+        importer_parts = Path(rel).parts
+        for im in module.imports or []:
+            if not im.module:
+                im.resolved_module = None
+                continue
+            original = im.alias or im.name
+            im.resolved_module = _resolve_one(im.module, original, importer_parts, candidates)