entrygraph 0.1.0__py3-none-any.whl

entrygraph/queries/java/definitions.scm

@@ -0,0 +1,14 @@
+; Harvest-level queries: find definition nodes; the Java shaper computes
+; qualified names, kinds, annotations (as decorators), and supertypes by
+; walking from these.
+
+(class_declaration
+  name: (identifier) @name) @def.class
+
+(interface_declaration
+  name: (identifier) @name) @def.interface
+
+(method_declaration
+  name: (identifier) @name) @def.method
+
+(field_declaration) @def.field

entrygraph/queries/java/imports.scm

@@ -0,0 +1,2 @@
+(import_declaration) @import
+(package_declaration) @package

entrygraph/queries/javascript/calls.scm

@@ -0,0 +1,4 @@
+(call_expression) @call
+; heritage is harvested in the shaper's _heritage(); a `class_heritage
+; (identifier)` pattern is impossible in the TS grammar (clauses wrap the
+; identifiers there) and would fail to compile the shared query for TypeScript.

entrygraph/queries/javascript/definitions.scm

@@ -0,0 +1,4 @@
+(function_declaration name: (identifier) @name) @def.function
+(class_declaration name: (_) @name) @def.class
+(method_definition name: (property_identifier) @name) @def.method
+(variable_declarator name: (identifier) @name) @def.var

entrygraph/queries/javascript/imports.scm

@@ -0,0 +1,6 @@
+(import_statement) @import
+(call_expression
+  function: (identifier) @req (#eq? @req "require")
+  arguments: (arguments (string) @req.module)) @require
+; re-exports (barrel files): `export { X } from "./y"` / `export * from "./y"`
+(export_statement source: (string)) @export.from

entrygraph/queries/php/calls.scm

@@ -0,0 +1,8 @@
+(function_call_expression) @call
+(member_call_expression) @member_call
+(scoped_call_expression) @scoped_call
+(object_creation_expression) @new
+(include_expression) @include
+(include_once_expression) @include
+(require_expression) @include
+(require_once_expression) @include

entrygraph/queries/php/definitions.scm

@@ -0,0 +1,24 @@
+; Harvest-level queries: find definition nodes; the PHP shaper computes
+; qualified names (namespace-scoped, `\` -> `.`), kinds, attributes (as
+; decorators), and supertypes by walking from these.
+
+(namespace_definition) @namespace
+
+(class_declaration
+  name: (name) @name) @def.class
+
+(interface_declaration
+  name: (name) @name) @def.interface
+
+(trait_declaration
+  name: (name) @name) @def.trait
+
+(function_definition
+  name: (name) @name) @def.function
+
+(method_declaration
+  name: (name) @name) @def.method
+
+(const_declaration) @def.const
+
+(property_declaration) @def.property

entrygraph/queries/php/imports.scm

@@ -0,0 +1 @@
+(namespace_use_declaration) @import

entrygraph/queries/python/calls.scm

@@ -0,0 +1,2 @@
+(call) @call
+(decorator) @decorator

entrygraph/queries/python/definitions.scm

@@ -0,0 +1,11 @@
+; Harvest-level queries: find definition nodes; the Python shaper computes
+; qualified names, kinds, docstrings, and decorators by walking from these.
+
+(class_definition
+  name: (identifier) @name) @def.class
+
+(function_definition
+  name: (identifier) @name) @def.function
+
+(assignment
+  left: (identifier) @name) @def.assign

entrygraph/queries/python/imports.scm

@@ -0,0 +1,2 @@
+(import_statement) @import
+(import_from_statement) @import.from

entrygraph/queries/ruby/calls.scm

@@ -0,0 +1,4 @@
+; Method calls. `method` field is the rightmost identifier; `receiver` (when
+; present) is the object it is called on. Bare calls have no receiver.
+(call
+  method: (identifier) @callee) @call

entrygraph/queries/ruby/definitions.scm

@@ -0,0 +1,20 @@
+; Harvest-level queries: find definition nodes; the Ruby shaper computes
+; qualified names, kinds, and scope chains by walking from these.
+
+(class
+  name: (constant) @name) @def.class
+
+(module
+  name: (constant) @name) @def.module
+
+(method
+  name: (identifier) @name) @def.method
+
+(singleton_method
+  name: (identifier) @name) @def.singleton_method
+
+(assignment
+  left: (constant) @name) @def.assign.constant
+
+(assignment
+  left: (identifier) @name) @def.assign.variable

entrygraph/queries/ruby/imports.scm

@@ -0,0 +1,7 @@
+; Ruby "imports" are method calls: require / require_relative / load. The
+; shaper filters calls by method name; capturing all calls keeps this cheap
+; and avoids brittle string predicates.
+
+(call
+  method: (identifier) @import.method
+  arguments: (argument_list)) @import.call

entrygraph/queries/rust/calls.scm

@@ -0,0 +1,5 @@
+; Both call_expression AND macro_invocation must be captured: without macros,
+; sqlx::query! and route macros are invisible to the sink/entrypoint layer.
+
+(call_expression) @call
+(macro_invocation) @macro

entrygraph/queries/rust/definitions.scm

@@ -0,0 +1,26 @@
+; Harvest-level queries: find definition nodes; the Rust shaper computes
+; qualified names, kinds, impl-receiver methods, attributes (as decorators),
+; and trait conformance by walking from these.
+
+(function_item
+  name: (identifier) @name) @def.function
+
+(struct_item
+  name: (type_identifier) @name) @def.struct
+
+(enum_item
+  name: (type_identifier) @name) @def.enum
+
+(trait_item
+  name: (type_identifier) @name) @def.trait
+
+(impl_item) @def.impl
+
+(const_item
+  name: (identifier) @name) @def.const
+
+(static_item
+  name: (identifier) @name) @def.static
+
+(mod_item
+  name: (identifier) @name) @def.mod

entrygraph/queries/rust/imports.scm

@@ -0,0 +1,4 @@
+; Use-declarations bind names into local scope; the Rust shaper unrolls
+; scoped lists, `use x as y`, and wildcards.
+
+(use_declaration) @import

entrygraph/resolve/externals.py

@@ -0,0 +1,61 @@
+"""Placeholder symbols for callees defined outside the repo.
+
+Sinks are overwhelmingly external calls (subprocess.run, child_process.exec),
+and reachability needs real graph nodes to terminate on — so the first time an
+external qualified name is referenced we mint a Symbol row with kind=external
+and no file. Created lazily from actual references, never pre-seeded.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from entrygraph.kinds import SymbolKind
+
+LANG_PREFIX = {
+    "python": "py",
+    "javascript": "js",
+    "typescript": "js",
+    "tsx": "js",
+    "go": "go",
+    "java": "java",
+    "ruby": "rb",
+    "csharp": "cs",
+    "php": "php",
+    "rust": "rs",
+}
+
+
+class ExternalRegistry:
+    def __init__(self, allocate_id: Callable[[], int]) -> None:
+        self._allocate_id = allocate_id
+        self.by_qname: dict[str, int] = {}
+        self.new_rows: list[dict] = []  # Symbol insert dicts, drained by the writer
+
+    def preload(self, existing: dict[str, int]) -> None:
+        """Seed with external symbols already in the DB (incremental runs)."""
+        self.by_qname.update(existing)
+
+    def get_or_create(self, qname: str) -> int:
+        symbol_id = self.by_qname.get(qname)
+        if symbol_id is not None:
+            return symbol_id
+        symbol_id = self._allocate_id()
+        self.by_qname[qname] = symbol_id
+        self.new_rows.append(
+            {
+                "id": symbol_id,
+                "file_id": None,
+                "kind": SymbolKind.EXTERNAL,
+                "name": qname.split(":", 1)[-1].rsplit(".", 1)[-1],
+                "qname": qname,
+                "parent_id": None,
+                "start_line": 0,
+                "end_line": 0,
+                "start_col": 0,
+                "signature": None,
+                "docstring": None,
+                "is_exported": True,
+            }
+        )
+        return symbol_id

entrygraph/resolve/hierarchy.py

@@ -0,0 +1,152 @@
+"""Class-hierarchy analysis and shared import-map construction.
+
+Runs as an index-time pre-pass (`resolve_hierarchy`) after all symbols are in
+the table but before edge resolution: it expands each class's raw base
+expressions **in the defining file's own import context** and records the
+resolved parents, so `ancestors()` can walk the full chain and `cha_candidates()`
+can enumerate virtual-dispatch targets.
+
+Kept import-free of resolver.py to avoid a cycle; resolver imports from here.
+"""
+
+from __future__ import annotations
+
+from entrygraph.extract.ir import FileExtraction, RawImport
+from entrygraph.kinds import SymbolKind
+from entrygraph.resolve.symbol_table import SymbolTable
+
+_MAX_ANCESTOR_DEPTH = 10
+_MAX_CHA_CANDIDATES = 8
+
+
+def expand_relative(imp: RawImport, module_path: str, is_package: bool) -> str:
+    """Resolve a Python-style relative import against the importing module."""
+    parts = module_path.split(".")
+    if not is_package:
+        parts = parts[:-1]  # level 1 = the containing package
+    drop = imp.relative_level - 1
+    if drop >= len(parts):
+        return imp.module  # over-deep relative import; keep as written
+    if drop:
+        parts = parts[:-drop]
+    base = ".".join(parts)
+    return f"{base}.{imp.module}" if imp.module else base
+
+
+def build_import_map(
+    extraction: FileExtraction, is_package: bool
+) -> tuple[dict[str, str], list[str]]:
+    """Return (alias -> dotted target, wildcard source modules).
+
+    Wildcard (`from x import *`) modules are returned separately so the resolver
+    can try `<module>.<name>` for otherwise-unresolved bare names.
+    """
+    import_map: dict[str, str] = {}
+    wildcard_modules: list[str] = []
+    for imp in extraction.imports:
+        module = (
+            expand_relative(imp, extraction.module_path, is_package)
+            if imp.is_relative
+            else imp.module
+        )
+        if imp.alias == "*" or imp.imported_name == "*":
+            if module:
+                wildcard_modules.append(module)
+            continue
+        if imp.imported_name is None:
+            top = module.split(".")[0]
+            import_map[imp.alias] = module if imp.alias != top else top
+        else:
+            import_map[imp.alias] = f"{module}.{imp.imported_name}" if module else imp.imported_name
+    return import_map, wildcard_modules
+
+
+def resolve_hierarchy(
+    extractions: list[tuple[str, FileExtraction, bool]], table: SymbolTable
+) -> None:
+    """Populate table.class_parents and table.reexports from freshly extracted files."""
+    for _path, x, is_package in extractions:
+        import_map, _wild = build_import_map(x, is_package)
+        for raw in x.symbols:
+            if raw.kind is not SymbolKind.CLASS or not raw.bases:
+                continue
+            parents: list[str] = []
+            for base in raw.bases:
+                resolved = _resolve_type_name(base, import_map, x.module_path, table)
+                if resolved is not None:
+                    parents.append(resolved)
+            if parents:
+                table.class_parents[raw.qualified_name] = parents
+        for rx in x.reexports:
+            if rx.is_star:
+                table.star_reexports.setdefault(x.module_path, []).append(rx.module)
+            elif rx.exported_name is not None:
+                local_name = rx.alias or rx.exported_name
+                table.reexports.setdefault(x.module_path, {})[local_name] = (
+                    rx.module,
+                    rx.exported_name,
+                )
+
+
+def _resolve_type_name(
+    text: str, import_map: dict[str, str], module_path: str, table: SymbolTable
+) -> str | None:
+    """Resolve a base/interface expression to a project FQN, or None if external."""
+    first_seg = text.split(".", 1)[0]
+    if first_seg in import_map:
+        expanded = import_map[first_seg] + text[len(first_seg):]
+        return expanded if expanded in table.by_fqn else None
+    local = f"{module_path}.{text}"
+    if local in table.by_fqn:
+        return local
+    return text if text in table.by_fqn else None
+
+
+def ancestors(class_fqn: str, table: SymbolTable, max_depth: int = _MAX_ANCESTOR_DEPTH) -> list[str]:
+    """Transitive project ancestors of a class, nearest first, cycle-safe."""
+    seen: set[str] = set()
+    order: list[str] = []
+    frontier = [(p, 1) for p in table.class_parents.get(class_fqn, [])]
+    while frontier:
+        parent, depth = frontier.pop(0)
+        if parent in seen or depth > max_depth:
+            continue
+        seen.add(parent)
+        order.append(parent)
+        for grand in table.class_parents.get(parent, []):
+            if grand not in seen:
+                frontier.append((grand, depth + 1))
+    return order
+
+
+def cha_candidates(
+    table: SymbolTable, method_name: str, exclude: set[int] | None = None
+) -> list[int]:
+    """Symbol ids of all method overrides named `method_name` that share a hierarchy.
+
+    Class-hierarchy analysis for virtual dispatch on an unknown receiver: only
+    fires when >=2 classes defining the method are related by inheritance, and
+    bails out past _MAX_CHA_CANDIDATES to avoid common-name blowup (run/get/...).
+    """
+    candidates = [
+        sid
+        for sid in table.by_name.get(method_name, [])
+        if table.kinds.get(sid) is SymbolKind.METHOD
+    ]
+    if exclude:
+        candidates = [c for c in candidates if c not in exclude]
+    if len(candidates) < 2 or len(candidates) > _MAX_CHA_CANDIDATES:
+        return []
+    # Keep methods whose owning classes are connected in the hierarchy — either
+    # one is an ancestor of the other, or they share a common ancestor (siblings
+    # implementing the same interface/base). Both cases mean a virtual call could
+    # dispatch across them.
+    closures = {
+        sid: {table.qname_of[sid].rsplit(".", 1)[0], *ancestors(table.qname_of[sid].rsplit(".", 1)[0], table)}
+        for sid in candidates
+    }
+    related: list[int] = []
+    for sid, closure in closures.items():
+        if any(oid != sid and closure & other for oid, other in closures.items()):
+            related.append(sid)
+    return related if len(related) >= 2 else []

entrygraph/resolve/resolver.py

@@ -0,0 +1,275 @@
+"""Pass-2 reference resolution: raw references -> edge rows.
+
+Resolution order per reference (first hit wins):
+1. import-map expansion (project target -> FQN lookup; external -> placeholder)
+2. module-local lookup (same-module bare names)
+3. self/cls receiver -> method on the enclosing class, then its bases (1 level)
+4. unique-name fuzzy match across the project
+5. unresolved: a language-prefixed guess so sink matching still works
+   ("py:*.execute" for attribute calls, "py:eval" for bare calls)
+
+Every call edge ends at a real symbol id — project symbol or external
+placeholder — except import-expanded references into project modules whose
+target doesn't exist (yet); those keep dst NULL + a project-style dst_qname so
+incremental re-resolution can heal them when the target appears.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from entrygraph.extract.ir import FileExtraction, RawReference
+from entrygraph.kinds import Confidence, EdgeKind, SymbolKind
+from entrygraph.resolve.externals import LANG_PREFIX, ExternalRegistry
+from entrygraph.resolve.hierarchy import (
+    ancestors,
+    build_import_map,
+    cha_candidates,
+    expand_relative,
+)
+from entrygraph.resolve.symbol_table import SymbolTable
+
+# expand_relative re-exported for backward compatibility with callers/tests.
+__all__ = ["FileResolver", "ResolvedEdge", "expand_relative"]
+
+_REF_EDGE_KIND = {
+    "call": EdgeKind.CALLS,
+    "decorator": EdgeKind.CALLS,
+    "inherit": EdgeKind.INHERITS,
+    "implement": EdgeKind.IMPLEMENTS,
+    "annotation": EdgeKind.REFERENCES,
+    "callback": EdgeKind.PASSED_AS_CALLBACK,
+    "dynamic_call": EdgeKind.CALLS,
+}
+
+_SELF_RECEIVERS = frozenset({"self", "cls", "this", "$this"})
+_MAX_REEXPORT_DEPTH = 16
+
+
+@dataclass(slots=True)
+class ResolvedEdge:
+    kind: EdgeKind
+    src_symbol_id: int
+    dst_symbol_id: int | None
+    dst_qname: str
+    line: int
+    confidence: Confidence
+    arg_preview: str | None = None
+    via: str | None = None  # "dynamic" | "reexport" | "cha" | None
+
+
+class FileResolver:
+    def __init__(
+        self,
+        extraction: FileExtraction,
+        module_symbol_id: int,
+        table: SymbolTable,
+        externals: ExternalRegistry,
+        is_package: bool = False,
+    ) -> None:
+        self.x = extraction
+        self.module_symbol_id = module_symbol_id
+        self.table = table
+        self.externals = externals
+        self.prefix = LANG_PREFIX.get(extraction.language, extraction.language)
+        self.import_map, self.wildcard_modules = build_import_map(extraction, is_package)
+
+    # ---------------- edges ----------------
+
+    def resolve(self) -> list[ResolvedEdge]:
+        edges = [*self._import_edges()]
+        for ref in self.x.references:
+            edge = self._resolve_reference(ref)
+            if edge is None:  # callbacks to non-project data args are dropped
+                continue
+            edges.append(edge)
+            edges.extend(self._cha_edges(ref, edge))
+        return edges
+
+    def _cha_edges(self, ref: RawReference, primary: ResolvedEdge) -> list[ResolvedEdge]:
+        """Class-hierarchy virtual-dispatch candidates for an unknown-receiver call.
+
+        Only for method calls that resolved imprecisely (FUZZY or an unresolved
+        `prefix:*.name`). Each candidate is a FUZZY, via="cha" edge, so it is
+        invisible under the default IMPORT confidence floor and only widens
+        results when the caller opts into fuzzy traversal.
+        """
+        if ref.kind != "call" or ref.receiver_text is None:
+            return []
+        if ref.receiver_text in _SELF_RECEIVERS:
+            return []
+        if primary.confidence > Confidence.FUZZY:
+            return []
+        exclude = {primary.dst_symbol_id} if primary.dst_symbol_id is not None else set()
+        out: list[ResolvedEdge] = []
+        for cand in cha_candidates(self.table, ref.callee_name, exclude=exclude):
+            out.append(
+                ResolvedEdge(
+                    EdgeKind.CALLS, primary.src_symbol_id, cand, self.table.qname_of[cand],
+                    ref.span.start_line, Confidence.FUZZY, arg_preview=ref.arg_preview, via="cha",
+                )
+            )
+        return out
+
+    def _import_edges(self) -> list[ResolvedEdge]:
+        edges = []
+        seen: set[str] = set()
+        for imp in self.x.imports:
+            module = (
+                expand_relative(imp, self.x.module_path, False) if imp.is_relative else imp.module
+            )
+            if not module or module in seen:
+                continue
+            seen.add(module)
+            if self.table.is_project_path(module):
+                dst_id = self.table.module_symbol_ids.get(module) or self.table.by_fqn.get(module)
+                edges.append(
+                    ResolvedEdge(EdgeKind.IMPORTS, self.module_symbol_id, dst_id, module,
+                                 imp.span.start_line, Confidence.IMPORT if dst_id else Confidence.UNRESOLVED)
+                )
+            else:
+                qname = f"{self.prefix}:{module}"
+                dst_id = self.externals.get_or_create(qname)
+                edges.append(
+                    ResolvedEdge(EdgeKind.IMPORTS, self.module_symbol_id, dst_id, qname,
+                                 imp.span.start_line, Confidence.IMPORT)
+                )
+        return edges
+
+    def _resolve_reference(self, ref: RawReference) -> ResolvedEdge | None:
+        src_id = self.table.by_fqn.get(ref.caller_qualified_name or "", self.module_symbol_id)
+        kind = _REF_EDGE_KIND.get(ref.kind, EdgeKind.REFERENCES)
+
+        if ref.kind == "callback":
+            # A function name handed to another call. Only a real project
+            # function/method is a meaningful edge; anything else is a data arg.
+            dst_id = self._bind_project_callable(ref.callee_name)
+            if dst_id is None:
+                return None
+            return ResolvedEdge(kind, src_id, dst_id, self.table.qname_of[dst_id],
+                                 ref.span.start_line, Confidence.IMPORT)
+
+        if ref.kind == "dynamic_call":
+            # getattr/computed/send — target isn't statically knowable. Keep a
+            # real placeholder node so the path can flag "may continue".
+            if ref.callee_name in ("<dynamic>", "<computed>"):
+                guess = f"{self.prefix}:<dynamic>"
+            else:
+                guess = f"{self.prefix}:{ref.callee_name}.*"
+            dst_id = self.externals.get_or_create(guess)
+            return ResolvedEdge(kind, src_id, dst_id, guess, ref.span.start_line,
+                                Confidence.UNRESOLVED, arg_preview=ref.arg_preview, via="dynamic")
+
+        dst_id, dst_qname, confidence, via = self._bind(ref)
+        return ResolvedEdge(
+            kind=kind,
+            src_symbol_id=src_id,
+            dst_symbol_id=dst_id,
+            dst_qname=dst_qname,
+            line=ref.span.start_line,
+            confidence=confidence,
+            arg_preview=ref.arg_preview,
+            via=via,
+        )
+
+    def _bind_project_callable(self, name: str) -> int | None:
+        local = f"{self.x.module_path}.{name}"
+        if local in self.table.by_fqn:
+            return self.table.by_fqn[local]
+        if name in self.import_map:
+            target = self.import_map[name]
+            if target in self.table.by_fqn:
+                return self.table.by_fqn[target]
+        return self.table.unique_by_name(name, (SymbolKind.FUNCTION, SymbolKind.METHOD))
+
+    def _bind(self, ref: RawReference) -> tuple[int | None, str, Confidence, str | None]:
+        # 1. import-map expansion (chase re-export chains for project targets)
+        first_seg = ref.callee_text.split(".", 1)[0].split("(", 1)[0]
+        if first_seg in self.import_map:
+            rest = ref.callee_text[len(first_seg):]
+            expanded = self.import_map[first_seg] + rest
+            if self.table.is_project_path(expanded):
+                dst_id = self.table.by_fqn.get(expanded)
+                if dst_id is not None:
+                    return dst_id, expanded, Confidence.IMPORT, None
+                chased = self._chase_reexport(expanded)
+                if chased is not None:
+                    return self.table.by_fqn[chased], chased, Confidence.IMPORT, "reexport"
+                # project target: missing -> healable NULL edge
+                return None, expanded, Confidence.UNRESOLVED, None
+            qname = f"{self.prefix}:{expanded}"
+            return self.externals.get_or_create(qname), qname, Confidence.IMPORT, None
+
+        # 2. module-local bare name
+        if ref.receiver_text is None:
+            local = f"{self.x.module_path}.{ref.callee_name}"
+            dst_id = self.table.by_fqn.get(local)
+            if dst_id is not None:
+                return dst_id, local, Confidence.EXACT, None
+
+        # 3. self/cls/this receiver -> method on the enclosing class, then up the
+        #    full ancestor chain (transitive, cycle-safe; see hierarchy.py).
+        if ref.receiver_text in _SELF_RECEIVERS and ref.caller_qualified_name:
+            class_fqn = ref.caller_qualified_name.rsplit(".", 1)[0]
+            if self.table.kinds.get(self.table.by_fqn.get(class_fqn, -1)) == SymbolKind.CLASS:
+                candidate = f"{class_fqn}.{ref.callee_name}"
+                dst_id = self.table.by_fqn.get(candidate)
+                if dst_id is not None:
+                    return dst_id, candidate, Confidence.EXACT, None
+                for base_fqn in ancestors(class_fqn, self.table):
+                    candidate = f"{base_fqn}.{ref.callee_name}"
+                    dst_id = self.table.by_fqn.get(candidate)
+                    if dst_id is not None:
+                        return dst_id, candidate, Confidence.EXACT, None
+
+        # 3b. bare name via a wildcard import (`from mod import *`)
+        if ref.receiver_text is None:
+            for wmod in self.wildcard_modules:
+                candidate = f"{wmod}.{ref.callee_name}"
+                dst_id = self.table.by_fqn.get(candidate)
+                if dst_id is not None:
+                    return dst_id, candidate, Confidence.IMPORT, None
+
+        # 4. unique-name fuzzy match (project symbols only, never ambiguous).
+        # For attribute calls with an unknown receiver (e.g. `runner.execute()`
+        # where runner is a local variable) this is the only way to recover the
+        # call-graph edge without local type inference — it's the documented
+        # FUZZY tradeoff.
+        kinds = (
+            (SymbolKind.METHOD,)
+            if ref.receiver_text is not None
+            else (SymbolKind.FUNCTION, SymbolKind.CLASS)
+        )
+        dst_id = self.table.unique_by_name(ref.callee_name, kinds)
+        if dst_id is not None:
+            return dst_id, self.table.qname_of[dst_id], Confidence.FUZZY, None
+
+        # 5. unresolved: language-prefixed guess, still a real node for sinks
+        if ref.receiver_text is not None:
+            guess = f"{self.prefix}:*.{ref.callee_name}"
+        else:
+            guess = f"{self.prefix}:{ref.callee_text}"
+        return self.externals.get_or_create(guess), guess, Confidence.UNRESOLVED, None
+
+    def _chase_reexport(self, qname: str) -> str | None:
+        """Follow barrel-file re-export chains to a terminal project symbol."""
+        module, _, name = qname.rpartition(".")
+        seen: set[tuple[str, str]] = set()
+        for _ in range(_MAX_REEXPORT_DEPTH):
+            if not module or (module, name) in seen:
+                return None
+            seen.add((module, name))
+            mapping = self.table.reexports.get(module, {})
+            if name in mapping:
+                tgt_module, tgt_name = mapping[name]
+                candidate = f"{tgt_module}.{tgt_name}"
+                if candidate in self.table.by_fqn:
+                    return candidate
+                module, name = tgt_module, tgt_name
+                continue
+            for src_module in self.table.star_reexports.get(module, []):
+                candidate = f"{src_module}.{name}"
+                if candidate in self.table.by_fqn:
+                    return candidate
+            return None
+        return None