Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

refactor(graph): one implicit-scope scan and one heritage walk (#1638)

Raghav Chamadiya580e17f065fd
diff --git a/docs/reference/COMPUTED_GLOSSARY.md b/docs/reference/COMPUTED_GLOSSARY.md
index 3dcf4a350..40bbe5da4 100644
--- a/docs/reference/COMPUTED_GLOSSARY.md
+++ b/docs/reference/COMPUTED_GLOSSARY.md
@@ -80,7 +80,7 @@ workspace overlays, MCP responses, and CLI output.
| Call confidence | Confidence that a call edge points to the right callee. | `CallResolver` | `0.95` same-file, `0.90` import binding, `0.50` global unique |
| `extends` edge | Class/struct inheritance edge. | `HeritageResolver` | `UserView -> BaseView` |
| `implements` edge | Interface/trait implementation edge. | `HeritageResolver` | `UserRepository -> Repository` |
-| Heritage confidence | Confidence that inheritance/implementation resolved correctly. | `HeritageResolver` | `0.95` same-file, `0.90` imported, `0.50` global unique |
+| Heritage confidence | Confidence that inheritance/implementation resolved correctly. | `HeritageResolver` | `0.95` same-file, `0.90` named import, `0.85` any imported file, `0.50` global unique |
| `framework` edge | Synthetic edge from framework conventions. | `framework_edges.py` | `urls.py -> views.py`, `app.py -> routers/users.py` |
| Dynamic edge | Edge inferred from runtime/dynamic patterns. | `dynamic_hints/*` and `GraphBuilder.add_dynamic_edges()` | `{edge_type: "dynamic_imports", hint_source: "django", weight: 1.0}` |
| `co_changes` edge | File-to-file historical coupling edge. | `GraphBuilder.add_co_change_edges()` from git metadata | `src/a.py -> src/b.py` with `weight: 4.2` |
diff --git a/packages/core/src/repowise/core/ingestion/call_resolver.py b/packages/core/src/repowise/core/ingestion/call_resolver.py
index 22d190a2d..38e9ef576 100644
--- a/packages/core/src/repowise/core/ingestion/call_resolver.py
+++ b/packages/core/src/repowise/core/ingestion/call_resolver.py
@@ -30,7 +30,13 @@ from typing import Any
import structlog
-from .models import CallSite, NamedBinding, ParsedFile, ResolutionOrigin
+from .models import (
+ CallSite,
+ NamedBinding,
+ ParsedFile,
+ ResolutionOrigin,
+ symbol_id_language,
+)
log = structlog.get_logger(__name__)
@@ -76,13 +82,6 @@ _LANGUAGE_CALL_STRATEGIES: dict[str, _LanguageCallStrategies] = {
}
-def _file_language(parsed_files: dict[str, ParsedFile], symbol_id: str) -> str | None:
- """Extract language from a symbol ID's file via the parsed files map."""
- file_path = symbol_id.split("::")[0] if "::" in symbol_id else symbol_id
- parsed = parsed_files.get(file_path)
- return parsed.file_info.language if parsed else None
-
-
@dataclass(frozen=True, slots=True)
class ResolvedCall:
"""A call resolved to concrete symbol IDs with a confidence score."""
@@ -754,8 +753,8 @@ class CallResolver:
# Tier 3: global unique match — only within the same language
candidates = self._global_symbols.get(target_name, [])
if len(candidates) == 1 and candidates[0] != caller_id:
- caller_lang = _file_language(self._parsed_files, caller_id)
- callee_lang = _file_language(self._parsed_files, candidates[0])
+ caller_lang = symbol_id_language(self._parsed_files, caller_id)
+ callee_lang = symbol_id_language(self._parsed_files, candidates[0])
if caller_lang and callee_lang and caller_lang != callee_lang:
return None # reject cross-language Tier 3 match
return ResolvedCall(caller_id, candidates[0], 0.50, call.line, "global_unique")
diff --git a/packages/core/src/repowise/core/ingestion/heritage_resolver.py b/packages/core/src/repowise/core/ingestion/heritage_resolver.py
index 62b7bbde9..3a23c9a52 100644
--- a/packages/core/src/repowise/core/ingestion/heritage_resolver.py
+++ b/packages/core/src/repowise/core/ingestion/heritage_resolver.py
@@ -9,34 +9,72 @@ Resolution tiers (checked in order, first match wins):
Tier 1 — Same-file exact match (confidence 0.95)
The parent name matches a class/interface/trait in the same file.
- Tier 2 — Import-scoped match (confidence 0.90)
- The parent name matches a class/interface/trait in an imported file.
+ Tier 2a — Named import (confidence 0.90)
+ The file imports the parent name, and that file declares it.
+
+ Tier 2b — Any imported file (confidence 0.85)
+ Some imported file declares the name; sorted-path order, first wins.
Tier 3 — Global unique match (confidence 0.50)
The parent name matches exactly one class/interface/trait globally.
Each resolved relation produces a (child_id, parent_id, edge_type, confidence)
tuple that the GraphBuilder converts into graph edges.
+
+Chain-walking a resolved relation is :func:`heritage_ancestors`.
"""
from __future__ import annotations
from collections import defaultdict
+from collections.abc import Callable, Iterable
from dataclasses import dataclass
-from typing import Any
+from typing import Any, TypeVar
import structlog
-from .models import HeritageRelation, ParsedFile
+from .models import HeritageRelation, ParsedFile, symbol_id_language
log = structlog.get_logger(__name__)
+_Anchor = TypeVar("_Anchor")
+
+
+def heritage_ancestors(
+ root: _Anchor,
+ parents_of: Callable[[_Anchor], Iterable[_Anchor]],
+ *,
+ max_expand_depth: int,
+) -> set[_Anchor]:
+ """Every anchor reachable from *root* by following *parents_of*, plus *root*.
+
+ **The anchor must identify a declaration, never a bare type name.** A
+ name-keyed walk unions the parents of every same-named type in the repo and
+ mints edges between unrelated classes, which is precisely the error this
+ exists to make unavailable: pass a symbol id, or a key that is already
+ scoped to one declaration.
+
+ *max_expand_depth* bounds expansion, not reach: an anchor found deeper is
+ returned but not followed. So reach is ``max_expand_depth + 1`` — for
+ ancestors within distance N, pass ``N - 1``.
+
+ An anchor is expanded at most once, which ends cycles but also means a long
+ path reaching it first can truncate what a later short path would have
+ expanded.
+ """
+ reached: set[_Anchor] = set()
+ expanded: set[_Anchor] = set()
+
+ def visit(anchor: _Anchor, depth: int) -> None:
+ reached.add(anchor)
+ if anchor in expanded or depth > max_expand_depth:
+ return
+ expanded.add(anchor)
+ for parent in parents_of(anchor):
+ visit(parent, depth + 1)
-def _file_language(parsed_files: dict[str, ParsedFile], symbol_id: str) -> str | None:
- """Extract language from a symbol ID's file via the parsed files map."""
- file_path = symbol_id.split("::")[0] if "::" in symbol_id else symbol_id
- parsed = parsed_files.get(file_path)
- return parsed.file_info.language if parsed else None
+ visit(root, 0)
+ return reached
# Symbol kinds that can be parents in heritage relationships
@@ -190,8 +228,8 @@ class HeritageResolver:
# Tier 3: global unique match — only within the same language
candidates = self._global_types.get(parent_name, [])
if len(candidates) == 1:
- caller_lang = _file_language(self._parsed_files, child_id)
- callee_lang = _file_language(self._parsed_files, candidates[0])
+ caller_lang = symbol_id_language(self._parsed_files, child_id)
+ callee_lang = symbol_id_language(self._parsed_files, candidates[0])
if caller_lang and callee_lang and caller_lang != callee_lang:
return None # reject cross-language Tier 3 match
return ResolvedHeritage(
diff --git a/packages/core/src/repowise/core/ingestion/languages/csharp_same_namespace.py b/packages/core/src/repowise/core/ingestion/languages/csharp_same_namespace.py
index 38b4dc2b0..14e0c22ea 100644
--- a/packages/core/src/repowise/core/ingestion/languages/csharp_same_namespace.py
+++ b/packages/core/src/repowise/core/ingestion/languages/csharp_same_namespace.py
@@ -12,10 +12,10 @@ produce **no edge at all** under plain import resolution, which makes the
most cohesive parts of a C# codebase (and entire xunit suites) read as
disconnected orphans.
-This pass mirrors the JVM same-package prior art
-(:mod:`.jvm_same_package`): a self-contained, regex-driven scan over raw
-source text that emits conservative ``imports`` edges after the regular
-import-resolution phases ran.
+This is the C# binding of the shared implicit-scope scan
+(:mod:`.scope_scan`). It hands over two scopes in C# lookup order — the file's
+own namespace(s) first, then the project's global usings — and owns the
+namespace index; that module owns the identifier scan and the edge emission.
For each C# file A, every capitalized identifier in A's source is checked
against the types declared in A's *candidate namespaces*: first A's own
@@ -54,14 +54,13 @@ import re
from pathlib import Path
from typing import TYPE_CHECKING
+from .scope_scan import FileScope, ScopeTier, emit_scope_edges
+
if TYPE_CHECKING:
import networkx as nx
from ..resolvers.dotnet.index import DotNetProjectIndex
-# Capitalized identifier — candidate type reference.
-_TYPE_IDENT_RE = re.compile(r"\b[A-Z][A-Za-z0-9_]*\b")
-
# ``using Foo.Bar;`` / ``global using Foo.Bar;`` — namespace usings.
_USING_NS_RE = re.compile(
r"^\s*(?:global\s+)?using\s+(?:static\s+)?([A-Za-z_][\w.]*)\s*;", re.MULTILINE
@@ -159,12 +158,15 @@ def resolve_csharp_same_namespace_refs(
ns_types = build_namespace_type_index(cs_texts)
- count = 0
- for path in sorted(cs_texts):
- text = cs_texts[path]
+ def _declarers(namespaces: list[str], ident: str) -> set[str]:
+ declaring: set[str] = set()
+ for ns in namespaces:
+ declaring.update(ns_types.get(ns, {}).get(ident, ()))
+ return declaring
+
+ def plan(path: str, text: str) -> FileScope | None:
own_namespaces = list(dict.fromkeys(declared_namespaces(text)))
explicit_ns = [m.group(1) for m in _USING_NS_RE.finditer(text)]
- alias_names = {m.group(1) for m in _USING_ALIAS_RE.finditer(text)}
# Project-wide usings (``global using`` files + csproj <Using>
# items + SDK implicit sets), restricted to namespaces that
@@ -182,57 +184,41 @@ def resolve_csharp_same_namespace_refs(
)
if not own_namespaces and not global_ns:
- continue
+ return None
# Types declared in namespaces this file explicitly ``using``s —
# those resolve through the normal import path and shadow the
- # global-using tier.
+ # global-using tier only. An explicit using does *not* shadow the
+ # file's own namespace: C# lookup gives the closest scope priority.
explicit_types: set[str] = set()
for ns in explicit_ns:
explicit_types.update(ns_types.get(ns, ()))
- # target file → (referenced names, hint source)
- found: dict[str, tuple[list[str], str]] = {}
- for ident in sorted(set(_TYPE_IDENT_RE.findall(text))):
- if ident in _BCL_COMMON_TYPES or ident in alias_names:
- continue
- target: str | None = None
- hint = _SAME_NAMESPACE_HINT
- # Tier 1: the file's own namespace(s) — closest scope wins.
- declaring: set[str] = set()
- for ns in own_namespaces:
- declaring.update(ns_types.get(ns, {}).get(ident, ()))
- if declaring:
- if len(declaring) != 1:
- continue # ambiguous — no edge to anyone
- target = next(iter(declaring))
- elif global_ns:
- if ident in explicit_types:
- continue # explicit using already resolved it
- hint = _GLOBAL_USING_HINT
- declaring = set()
- for ns in global_ns:
- declaring.update(ns_types.get(ns, {}).get(ident, ()))
- if len(declaring) != 1:
- continue
- target = next(iter(declaring))
- if target is None or target == path:
- continue
- names, _ = found.setdefault(target, ([], hint))
- names.append(ident)
-
- for target, (names, hint) in sorted(found.items()):
- if not graph.has_node(path) or not graph.has_node(target):
- continue
- if graph.has_edge(path, target):
- continue # a real import (or stronger evidence) wins
- graph.add_edge(
- path,
- target,
- edge_type="imports",
- imported_names=names,
- hint_source=hint,
+ tiers = []
+ if own_namespaces:
+ tiers.append(
+ ScopeTier(
+ hint=_SAME_NAMESPACE_HINT,
+ lookup=lambda ident: _declarers(own_namespaces, ident),
+ )
)
- count += 1
-
- return count
+ if global_ns:
+ tiers.append(
+ ScopeTier(
+ hint=_GLOBAL_USING_HINT,
+ lookup=lambda ident: (
+ set() if ident in explicit_types else _declarers(global_ns, ident)
+ ),
+ )
+ )
+ return FileScope(
+ tiers=tuple(tiers),
+ shadowed=frozenset(m.group(1) for m in _USING_ALIAS_RE.finditer(text)),
+ )
+
+ return emit_scope_edges(
+ graph,
+ ((path, cs_texts[path]) for path in sorted(cs_texts)),
+ plan,
+ skip_names=_BCL_COMMON_TYPES,
+ )
diff --git a/packages/core/src/repowise/core/ingestion/languages/go_interface_satisfaction.py b/packages/core/src/repowise/core/ingestion/languages/go_interface_satisfaction.py
index 9f1178ca8..f82ee54ee 100644
--- a/packages/core/src/repowise/core/ingestion/languages/go_interface_satisfaction.py
+++ b/packages/core/src/repowise/core/ingestion/languages/go_interface_satisfaction.py
@@ -49,6 +49,8 @@ from typing import TYPE_CHECKING, Any
import structlog
+from ..heritage_resolver import heritage_ancestors
+
if TYPE_CHECKING:
import networkx as nx
from tree_sitter import Node
@@ -57,8 +59,9 @@ log = structlog.get_logger(__name__)
_IMPLEMENTS_CONFIDENCE = 0.6
-# Cap on embedded-interface expansion depth — guards against cyclic or
-# pathological embedding chains. Real Go embedding nests only a level or two.
+# Cap on embedded-interface expansion depth — guards against pathological
+# embedding chains. Real Go embedding nests only a level or two. (Cycles are
+# the walk's own business, not this constant's.)
_MAX_EMBED_DEPTH = 6
@@ -244,28 +247,30 @@ def resolve_go_interface_satisfaction(
for key in interface_methods:
name_to_iface_keys.setdefault(key[1], []).append(key)
- def _expand(key: tuple[str, str], depth: int, seen: set) -> set[str]:
- if key in seen or depth > _MAX_EMBED_DEPTH:
- return set(interface_methods.get(key, set()))
- seen.add(key)
- result = set(interface_methods.get(key, set()))
+ def _embedded(key: tuple[str, str]) -> list[tuple[str, str]]:
+ """The interfaces *key* embeds, resolved to keys of their own."""
pkg = key[0]
+ out: list[tuple[str, str]] = []
for bare in interface_embeds.get(key, ()):
- # Prefer an embedded interface in the same package.
- target = None
+ # Prefer an embedded interface in the same package; otherwise take
+ # the name only when the repo holds exactly one interface with it.
if (pkg, bare) in interface_methods:
- target = (pkg, bare)
- else:
- candidates = name_to_iface_keys.get(bare)
- if candidates and len(candidates) == 1:
- target = candidates[0]
- if target is not None:
- result |= _expand(target, depth + 1, seen)
- return result
+ out.append((pkg, bare))
+ continue
+ candidates = name_to_iface_keys.get(bare)
+ if candidates and len(candidates) == 1:
+ out.append(candidates[0])
+ return out
+ # Anchor is (package dir, name), so same-named interfaces in different
+ # packages stay separate.
expanded_iface: dict[tuple[str, str], frozenset[str]] = {}
for key in interface_methods:
- methods = _expand(key, 0, set())
+ methods: set[str] = set()
+ for reached in heritage_ancestors(
+ key, _embedded, max_expand_depth=_MAX_EMBED_DEPTH
+ ):
+ methods |= interface_methods.get(reached, set())
if methods:
expanded_iface[key] = frozenset(methods)
diff --git a/packages/core/src/repowise/core/ingestion/languages/jvm_same_package.py b/packages/core/src/repowise/core/ingestion/languages/jvm_same_package.py
index 8ea252a75..f75ac1078 100644
--- a/packages/core/src/repowise/core/ingestion/languages/jvm_same_package.py
+++ b/packages/core/src/repowise/core/ingestion/languages/jvm_same_package.py
@@ -9,10 +9,10 @@ import resolvers therefore produce **no edge at all** between the files
of a tightly-coupled package, which makes exactly the most cohesive
parts of a Java/Kotlin codebase look disconnected.
-This pass mirrors the C# member-reads prior art
-(:mod:`.csharp_member_reads`): a self-contained, regex-driven scan over
-raw source text that emits conservative graph edges after the regular
-import resolution phases ran.
+This is the JVM binding of the shared implicit-scope scan
+(:mod:`.scope_scan`): that module owns the identifier scan, the
+one-declaring-file rule and the edge emission; this one supplies the package
+index, the default-import skip list and the JVM shadowing rule.
For each JVM file A in a multi-file package, every capitalized
identifier in A's source is checked against the package's declared
@@ -41,16 +41,17 @@ separately and any false positive is diagnosable at the source.
from __future__ import annotations
import re
-from pathlib import Path
from typing import TYPE_CHECKING, Any
+from ..cohesion import SAME_PACKAGE_HINT
+from .scope_scan import FileScope, ScopeTier, collect_source_texts, emit_scope_edges
+
if TYPE_CHECKING:
import networkx as nx
from ..resolvers.jvm_workspace import JvmWorkspaceIndex
-# Capitalized identifier — candidate type reference.
-_TYPE_IDENT_RE = re.compile(r"\b[A-Z][A-Za-z0-9_]*\b")
+_JVM_LANGUAGES = ("java", "kotlin", "scala")
# ``import a.b.C`` / ``import static a.b.C.d`` — collect the simple type
# name so explicitly-imported names never produce a same-package edge.
@@ -99,7 +100,20 @@ _SCALA_DEFAULT_TYPES = frozenset({
"Tuple3", "Range", "App", "Serializable", "Product", "Equals", "Unit",
})
-_SAME_PACKAGE_HINT = "same_package"
+
+def _shadowed_names(text: str) -> frozenset[str]:
+ """Simple names *text* imports explicitly — those shadow a package sibling.
+
+ Wildcard and static-member imports shadow nothing here: neither yields a
+ capitalized simple name.
+ """
+ names = {
+ m.group(1).rstrip(".").rsplit(".", 1)[-1]
+ for m in _IMPORT_LINE_RE.finditer(text)
+ }
+ for m in _IMPORT_BRACES_RE.finditer(text):
+ names.update(re.findall(r"\w+", m.group(1)))
+ return frozenset(names)
def resolve_jvm_same_package_refs(
@@ -116,68 +130,33 @@ def resolve_jvm_same_package_refs(
"""
from ..resolvers.jvm_workspace import _JAVA_LANG_TYPES
- skip_names = _JAVA_LANG_TYPES | _KOTLIN_DEFAULT_TYPES | _SCALA_DEFAULT_TYPES
-
- count = 0
- for path, text in texts.items():
+ def plan(path: str, text: str) -> FileScope | None:
pkg_fqn = jvm_index.package_for_file(path)
if not pkg_fqn:
- continue
+ return None
pkg = jvm_index.packages.get(pkg_fqn)
if pkg is None or len(pkg.files) < 2:
- continue
-
- # Simple names this file already imports explicitly — an explicit
- # import of com.other.Foo shadows a same-package Foo.
- explicit_imports = {
- m.group(1).rstrip(".").rsplit(".", 1)[-1]
- for m in _IMPORT_LINE_RE.finditer(text)
- }
- for m in _IMPORT_BRACES_RE.finditer(text):
- explicit_imports.update(re.findall(r"\w+", m.group(1)))
-
- # target file → referenced type names
- found: dict[str, list[str]] = {}
- for ident in sorted(set(_TYPE_IDENT_RE.findall(text))):
- if ident in skip_names or ident in explicit_imports:
- continue
- declaring = pkg.exported_top_level.get(ident)
- if not declaring or len(declaring) != 1:
- # Unknown in this package, or ambiguous (≥2 declaring
- # files) — no edge to anyone.
- continue
- target = declaring[0]
- if target == path:
- continue
- found.setdefault(target, []).append(ident)
-
- for target, names in sorted(found.items()):
- if not graph.has_node(path) or not graph.has_node(target):
- continue
- if graph.has_edge(path, target):
- continue # a real import (or stronger evidence) wins
- graph.add_edge(
- path,
- target,
- edge_type="imports",
- imported_names=names,
- hint_source=_SAME_PACKAGE_HINT,
- )
- count += 1
-
- return count
+ return None
+ # Not deduped: a file declaring a name twice reads as ambiguous.
+ # Changing that moves edges, so it needs its own measurement.
+ return FileScope(
+ tiers=(
+ ScopeTier(
+ hint=SAME_PACKAGE_HINT,
+ lookup=lambda ident: pkg.exported_top_level.get(ident, ()),
+ ),
+ ),
+ shadowed=_shadowed_names(text),
+ )
+
+ return emit_scope_edges(
+ graph,
+ texts.items(),
+ plan,
+ skip_names=_JAVA_LANG_TYPES | _KOTLIN_DEFAULT_TYPES | _SCALA_DEFAULT_TYPES,
+ )
def collect_jvm_source_texts(parsed_files: dict[str, Any]) -> dict[str, str]:
"""Read each parsed JVM file's source from disk, keyed by repo path."""
- out: dict[str, str] = {}
- for path, parsed in parsed_files.items():
- if parsed.file_info.language not in ("java", "kotlin", "scala"):
- continue
- try:
- out[path] = Path(parsed.file_info.abs_path).read_text(
- encoding="utf-8", errors="ignore"
- )
- except OSError:
- continue
- return out
+ return collect_source_texts(parsed_files, _JVM_LANGUAGES)
diff --git a/packages/core/src/repowise/core/ingestion/languages/scope_scan.py b/packages/core/src/repowise/core/ingestion/languages/scope_scan.py
new file mode 100644
index 000000000..ff87f4dcf
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/languages/scope_scan.py
@@ -0,0 +1,128 @@
+"""One implicit-scope scan, bound to a different declaration index per language.
+
+Several languages let a file name a sibling's type with no import statement:
+JVM same-package, C# same-namespace and ``global using``, Swift same-module.
+What differs between them is which index answers and what shadows a name, so
+those are the parameters; the scan, the one-declaring-file rule and the edge
+emission are shared.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Collection, Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+ import networkx as nx
+
+#: Capitalised identifier — a candidate type reference. Comments and string
+#: literals are deliberately not lexed out: every scope index this drives is
+#: restricted to types declared locally in the file's own scope, which is the
+#: filter that keeps the false-positive surface small, and a lexer would cost
+#: a second pass over every source file to remove a rare miss.
+_TYPE_IDENT_RE = re.compile(r"\b[A-Z][A-Za-z0-9_]*\b")
+
+
+@dataclass(frozen=True, slots=True)
+class ScopeTier:
+ """One scope to consult, and the hint an edge from it carries.
+
+ A tier suppresses a name it *can* see by returning empty for it — C#'s
+ global-using tier does that for names an explicit ``using`` already
+ resolved.
+ """
+
+ hint: str
+ lookup: Callable[[str], Collection[str]]
+
+
+@dataclass(frozen=True, slots=True)
+class FileScope:
+ """The scopes visible to one file, and the names shadowed within it."""
+
+ tiers: tuple[ScopeTier, ...]
+ #: Names that resolve elsewhere in this file — an explicit JVM import, a
+ #: C# ``using`` alias. Checked before any tier, so a shadowed name never
+ #: reaches an index.
+ shadowed: frozenset[str] = field(default_factory=frozenset)
+
+
+def emit_scope_edges(
+ graph: nx.DiGraph,
+ files: Iterable[tuple[str, str]],
+ plan: Callable[[str, str], FileScope | None],
+ *,
+ skip_names: frozenset[str],
+) -> int:
+ """Scan *files* for implicit scope references and add ``imports`` edges.
+
+ *files* yields ``(repo-relative path, source text)``; iteration order is
+ the caller's, since nothing here depends on it. *plan* returns the scopes
+ visible to one file, or ``None`` to skip the file entirely. *skip_names*
+ is the language's stdlib/default-import set, checked before every tier.
+
+ Returns the number of edges added.
+
+ **Ambiguity is terminal, not a fall-through.** A tier that names two or
+ more declaring files ends the search for that identifier rather than
+ consulting the next tier: a name visible-but-ambiguous in the nearest
+ scope is not a reference to a farther one, and a wrong edge is worse than
+ a missing one.
+ """
+ count = 0
+ for path, text in files:
+ scope = plan(path, text)
+ if scope is None:
+ continue
+
+ # target file → (referenced names, hint of the tier that answered)
+ found: dict[str, tuple[list[str], str]] = {}
+ for ident in sorted(set(_TYPE_IDENT_RE.findall(text))):
+ if ident in skip_names or ident in scope.shadowed:
+ continue
+ for tier in scope.tiers:
+ declaring = tier.lookup(ident)
+ if not declaring:
+ continue
+ if len(declaring) == 1:
+ target = next(iter(declaring))
+ if target != path:
+ names, _ = found.setdefault(target, ([], tier.hint))
+ names.append(ident)
+ break
+
+ for target, (names, hint) in sorted(found.items()):
+ if not graph.has_node(path) or not graph.has_node(target):
+ continue
+ if graph.has_edge(path, target):
+ continue # a real import (or stronger evidence) wins
+ graph.add_edge(
+ path,
+ target,
+ edge_type="imports",
+ imported_names=names,
+ hint_source=hint,
+ )
+ count += 1
+
+ return count
+
+
+def collect_source_texts(
+ parsed_files: dict[str, Any], languages: Collection[str]
+) -> dict[str, str]:
+ """Read each parsed file of *languages* from disk, keyed by repo path."""
+ out: dict[str, str] = {}
+ for path, parsed in parsed_files.items():
+ if parsed.file_info.language not in languages:
+ continue
+ try:
+ out[path] = Path(parsed.file_info.abs_path).read_text(
+ encoding="utf-8", errors="ignore"
+ )
+ except OSError:
+ continue
+ return out
diff --git a/packages/core/src/repowise/core/ingestion/languages/swift_same_module.py b/packages/core/src/repowise/core/ingestion/languages/swift_same_module.py
index 236d1d3b3..79398bea8 100644
--- a/packages/core/src/repowise/core/ingestion/languages/swift_same_module.py
+++ b/packages/core/src/repowise/core/ingestion/languages/swift_same_module.py
@@ -8,11 +8,11 @@ target is an edge desert — files connect only through the rare
cross-module ``import``, so exactly the most cohesive unit of a Swift
codebase reads as disconnected files.
-This pass mirrors the JVM same-package prior art
-(:mod:`.jvm_same_package`): a per-target map of declared top-level
-types (class/struct/enum/protocol/actor), then a conservative scan of
-each file's capitalized identifiers. An edge A → B is emitted only
-when ALL of:
+This is the Swift binding of the shared implicit-scope scan
+(:mod:`.scope_scan`): this module supplies a per-target map of declared
+top-level types (class/struct/enum/protocol/actor) and the stdlib skip list,
+and that module runs the identifier scan and emits the edges. An edge A → B
+is emitted only when ALL of:
- the identifier names a top-level type declared in exactly **one**
file B of A's own SPM target (ambiguous names link to no one);
@@ -39,9 +39,10 @@ false positives stay diagnosable.
from __future__ import annotations
import re
-from pathlib import Path
from typing import TYPE_CHECKING, Any
+from .scope_scan import FileScope, ScopeTier, collect_source_texts, emit_scope_edges
+
if TYPE_CHECKING:
import networkx as nx
@@ -54,8 +55,6 @@ _SWIFT_TYPE_DECL_RE = re.compile(
re.MULTILINE,
)
-_TYPE_IDENT_RE = re.compile(r"\b[A-Z][A-Za-z0-9_]*\b")
-
# Ubiquitous Swift stdlib / Foundation names — references are
# overwhelmingly to the framework type even when a target shadows one.
_SWIFT_COMMON_TYPES = frozenset({
@@ -116,52 +115,35 @@ def resolve_swift_same_module_refs(
for m in _SWIFT_TYPE_DECL_RE.finditer(texts[path]):
type_map.setdefault(m.group(1), []).append(path)
- count = 0
- for module, files in files_by_module.items():
- if len(files) < 2:
- continue
+ scannable = {
+ path: module
+ for module, files in files_by_module.items()
+ if len(files) >= 2
+ for path in files
+ }
+
+ def plan(path: str, _text: str) -> FileScope | None:
+ module = scannable.get(path)
+ if module is None:
+ return None
type_map = declared[module]
- for path in files:
- text = texts[path]
- found: dict[str, list[str]] = {}
- for ident in sorted(set(_TYPE_IDENT_RE.findall(text))):
- if ident in _SWIFT_COMMON_TYPES:
- continue
- declaring = type_map.get(ident)
- if not declaring or len(set(declaring)) != 1:
- continue # unknown here, or ambiguous — no edge
- target = declaring[0]
- if target == path:
- continue
- found.setdefault(target, []).append(ident)
-
- for target, names in sorted(found.items()):
- if not graph.has_node(path) or not graph.has_node(target):
- continue
- if graph.has_edge(path, target):
- continue # a declared import (or stronger) wins
- graph.add_edge(
- path,
- target,
- edge_type="imports",
- imported_names=names,
- hint_source=_SAME_MODULE_HINT,
- )
- count += 1
-
- return count
+ return FileScope(
+ tiers=(
+ ScopeTier(
+ hint=_SAME_MODULE_HINT,
+ lookup=lambda ident: set(type_map.get(ident, ())),
+ ),
+ )
+ )
+
+ return emit_scope_edges(
+ graph,
+ ((path, texts[path]) for path in sorted(texts)),
+ plan,
+ skip_names=_SWIFT_COMMON_TYPES,
+ )
def collect_swift_source_texts(parsed_files: dict[str, Any]) -> dict[str, str]:
"""Read each parsed Swift file's source from disk, keyed by repo path."""
- out: dict[str, str] = {}
- for path, parsed in parsed_files.items():
- if parsed.file_info.language != "swift":
- continue
- try:
- out[path] = Path(parsed.file_info.abs_path).read_text(
- encoding="utf-8", errors="ignore"
- )
- except OSError:
- continue
- return out
+ return collect_source_texts(parsed_files, ("swift",))
diff --git a/packages/core/src/repowise/core/ingestion/models.py b/packages/core/src/repowise/core/ingestion/models.py
index 04506f2d9..e10c84170 100644
--- a/packages/core/src/repowise/core/ingestion/models.py
+++ b/packages/core/src/repowise/core/ingestion/models.py
@@ -515,6 +515,17 @@ class ParsedFile:
references: list[CallSite] = field(default_factory=list)
+def symbol_id_language(parsed_files: dict[str, ParsedFile], symbol_id: str) -> str | None:
+ """Language of the file a symbol ID belongs to, or ``None`` if unparsed.
+
+ Lives beside the ID vocabulary rather than in either resolver — both need
+ it for the same cross-language rejection.
+ """
+ file_path = symbol_id.split("::")[0] if "::" in symbol_id else symbol_id
+ parsed = parsed_files.get(file_path)
+ return parsed.file_info.language if parsed else None
+
+
def compute_content_hash(source: bytes) -> str:
"""Return the SHA-256 hex digest of *source*."""
return hashlib.sha256(source).hexdigest()
diff --git a/tests/unit/ingestion/test_heritage_ancestors.py b/tests/unit/ingestion/test_heritage_ancestors.py
new file mode 100644
index 000000000..077f6f108
--- /dev/null
+++ b/tests/unit/ingestion/test_heritage_ancestors.py
@@ -0,0 +1,72 @@
+"""Unit tests for the shared heritage walk.
+
+The rules pinned here are the ones a second copy of this walk would get
+wrong: that the anchor identifies a declaration rather than a name, that a
+cycle terminates, and that the depth cap bounds expansion without hiding
+what a truncated anchor declares itself.
+"""
+
+from __future__ import annotations
+
+from repowise.core.ingestion.heritage_resolver import heritage_ancestors
+
+
+def _walk(edges: dict, root, depth: int = 6) -> set:
+ return heritage_ancestors(root, lambda a: edges.get(a, ()), max_expand_depth=depth)
+
+
+class TestHeritageAncestors:
+ def test_the_root_is_included(self) -> None:
+ assert _walk({}, "a.py::Solo") == {"a.py::Solo"}
+
+ def test_a_chain_is_followed_to_the_end(self) -> None:
+ edges = {"a::A": ["a::B"], "a::B": ["a::C"], "a::C": ["a::D"]}
+ assert _walk(edges, "a::A") == {"a::A", "a::B", "a::C", "a::D"}
+
+ def test_a_diamond_yields_each_anchor_once(self) -> None:
+ edges = {"a::A": ["a::B", "a::C"], "a::B": ["a::D"], "a::C": ["a::D"]}
+ assert _walk(edges, "a::A") == {"a::A", "a::B", "a::C", "a::D"}
+
+ def test_a_cycle_terminates(self) -> None:
+ edges = {"a::A": ["a::B"], "a::B": ["a::C"], "a::C": ["a::A"]}
+ assert _walk(edges, "a::A") == {"a::A", "a::B", "a::C"}
+
+ def test_self_reference_terminates(self) -> None:
+ assert _walk({"a::A": ["a::A"]}, "a::A") == {"a::A"}
+
+
+class TestDepthCap:
+ def test_the_cap_bounds_expansion_not_reach(self) -> None:
+ # At depth 0 the root is expanded, so its parents are reached — they
+ # are simply not followed. A truncated anchor still counts as found,
+ # which is what lets a caller read what it declares itself.
+ edges = {"a::A": ["a::B"], "a::B": ["a::C"]}
+ assert _walk(edges, "a::A", depth=0) == {"a::A", "a::B"}
+ assert _walk(edges, "a::A", depth=1) == {"a::A", "a::B", "a::C"}
+
+ def test_a_deep_chain_stops_at_the_cap(self) -> None:
+ edges = {f"a::N{i}": [f"a::N{i + 1}"] for i in range(20)}
+ assert _walk(edges, "a::N0", depth=6) == {f"a::N{i}" for i in range(8)}
+
+
+class TestAnchorIdentity:
+ def test_same_named_types_in_different_files_do_not_share_parents(self) -> None:
+ # The defect a name-keyed walk has: two unrelated ``Engine`` classes
+ # would union their parents and put ``Diesel`` above the electric one.
+ edges = {
+ "electric.py::Engine": ["electric.py::Motor"],
+ "diesel.py::Engine": ["diesel.py::Diesel"],
+ }
+ assert _walk(edges, "electric.py::Engine") == {
+ "electric.py::Engine",
+ "electric.py::Motor",
+ }
+
+ def test_the_anchor_may_be_any_hashable_identity(self) -> None:
+ # The Go structural pass anchors on (package dir, type name), which is
+ # already scoped to one declaration.
+ edges = {("pkg/a", "Reader"): [("pkg/a", "Seeker")]}
+ assert _walk(edges, ("pkg/a", "Reader")) == {
+ ("pkg/a", "Reader"),
+ ("pkg/a", "Seeker"),
+ }
diff --git a/tests/unit/ingestion/test_scope_scan.py b/tests/unit/ingestion/test_scope_scan.py
new file mode 100644
index 000000000..2f91efe25
--- /dev/null
+++ b/tests/unit/ingestion/test_scope_scan.py
@@ -0,0 +1,192 @@
+"""Unit tests for the shared implicit-scope scan.
+
+The three language bindings each have their own suite; these pin the rules
+that used to live three times and now live once, so a change to the shared
+driver fails here rather than showing up as an edge diff on one language.
+"""
+
+from __future__ import annotations
+
+import networkx as nx
+
+from repowise.core.ingestion.languages.scope_scan import (
+ FileScope,
+ ScopeTier,
+ emit_scope_edges,
+)
+
+_EMPTY: frozenset[str] = frozenset()
+
+
+def _graph(*paths: str) -> nx.DiGraph:
+ g = nx.DiGraph()
+ for p in paths:
+ g.add_node(p, node_type="file")
+ return g
+
+
+def _one_tier(index: dict[str, list[str]], hint: str = "same_scope") -> FileScope:
+ return FileScope(tiers=(ScopeTier(hint=hint, lookup=lambda i: index.get(i, ())),))
+
+
+class TestUniqueDeclarerRule:
+ def test_single_declarer_produces_an_edge_naming_the_identifier(self) -> None:
+ g = _graph("a.x", "b.x")
+ added = emit_scope_edges(
+ g,
+ [("a.x", "Widget w; Widget v;")],
+ lambda p, t: _one_tier({"Widget": ["b.x"]}),
+ skip_names=_EMPTY,
+ )
+ assert added == 1
+ edge = g["a.x"]["b.x"]
+ assert edge["edge_type"] == "imports"
+ assert edge["hint_source"] == "same_scope"
+ # Identifiers are deduplicated and sorted, not counted.
+ assert edge["imported_names"] == ["Widget"]
+
+ def test_two_declarers_produce_no_edge_to_anyone(self) -> None:
+ g = _graph("a.x", "b.x", "c.x")
+ added = emit_scope_edges(
+ g,
+ [("a.x", "Widget w;")],
+ lambda p, t: _one_tier({"Widget": ["b.x", "c.x"]}),
+ skip_names=_EMPTY,
+ )
+ assert added == 0
+
+ def test_self_declaration_produces_no_edge(self) -> None:
+ g = _graph("a.x")
+ added = emit_scope_edges(
+ g,
+ [("a.x", "Widget w;")],
+ lambda p, t: _one_tier({"Widget": ["a.x"]}),
+ skip_names=_EMPTY,
+ )
+ assert added == 0
+
+ def test_lowercase_identifiers_are_never_candidates(self) -> None:
+ g = _graph("a.x", "b.x")
+ added = emit_scope_edges(
+ g,
+ [("a.x", "widget w;")],
+ lambda p, t: _one_tier({"widget": ["b.x"]}),
+ skip_names=_EMPTY,
+ )
+ assert added == 0
+
+
+class TestTierOrder:
+ def _two_tiers(self, near: dict, far: dict) -> FileScope:
+ return FileScope(
+ tiers=(
+ ScopeTier(hint="near", lookup=lambda i: near.get(i, ())),
+ ScopeTier(hint="far", lookup=lambda i: far.get(i, ())),
+ )
+ )
+
+ def test_nearer_scope_wins(self) -> None:
+ g = _graph("a.x", "near.x", "far.x")
+ emit_scope_edges(
+ g,
+ [("a.x", "Widget w;")],
+ lambda p, t: self._two_tiers({"Widget": ["near.x"]}, {"Widget": ["far.x"]}),
+ skip_names=_EMPTY,
+ )
+ assert g.has_edge("a.x", "near.x")
+ assert not g.has_edge("a.x", "far.x")
+ assert g["a.x"]["near.x"]["hint_source"] == "near"
+
+ def test_a_farther_scope_answers_what_the_nearer_cannot_see(self) -> None:
+ g = _graph("a.x", "far.x")
+ emit_scope_edges(
+ g,
+ [("a.x", "Widget w;")],
+ lambda p, t: self._two_tiers({}, {"Widget": ["far.x"]}),
+ skip_names=_EMPTY,
+ )
+ assert g["a.x"]["far.x"]["hint_source"] == "far"
+
+ def test_ambiguity_in_the_nearer_scope_is_terminal(self) -> None:
+ # Visible-but-ambiguous nearby is not a reference to something far
+ # away: the search stops rather than falling through to the next tier.
+ g = _graph("a.x", "n1.x", "n2.x", "far.x")
+ added = emit_scope_edges(
+ g,
+ [("a.x", "Widget w;")],
+ lambda p, t: self._two_tiers(
+ {"Widget": ["n1.x", "n2.x"]}, {"Widget": ["far.x"]}
+ ),
+ skip_names=_EMPTY,
+ )
+ assert added == 0
+
+ def test_one_target_carries_the_hint_of_whichever_tier_answered_first(self) -> None:
+ # Alphabetical identifier order decides, and both names ride the edge.
+ g = _graph("a.x", "t.x")
+ emit_scope_edges(
+ g,
+ [("a.x", "Alpha a; Beta b;")],
+ lambda p, t: self._two_tiers({"Alpha": ["t.x"]}, {"Beta": ["t.x"]}),
+ skip_names=_EMPTY,
+ )
+ edge = g["a.x"]["t.x"]
+ assert edge["hint_source"] == "near"
+ assert edge["imported_names"] == ["Alpha", "Beta"]
+
+
+class TestSuppression:
+ def test_skip_names_are_never_looked_up(self) -> None:
+ g = _graph("a.x", "b.x")
+ added = emit_scope_edges(
+ g,
+ [("a.x", "String s;")],
+ lambda p, t: _one_tier({"String": ["b.x"]}),
+ skip_names=frozenset({"String"}),
+ )
+ assert added == 0
+
+ def test_a_shadowed_name_resolves_elsewhere(self) -> None:
+ g = _graph("a.x", "b.x")
+ added = emit_scope_edges(
+ g,
+ [("a.x", "Widget w;")],
+ lambda p, t: FileScope(
+ tiers=(ScopeTier(hint="h", lookup=lambda i: {"Widget": ["b.x"]}.get(i, ())),),
+ shadowed=frozenset({"Widget"}),
+ ),
+ skip_names=_EMPTY,
+ )
+ assert added == 0
+
+ def test_a_file_with_no_scope_is_skipped(self) -> None:
+ g = _graph("a.x", "b.x")
+ added = emit_scope_edges(
+ g, [("a.x", "Widget w;")], lambda p, t: None, skip_names=_EMPTY
+ )
+ assert added == 0
+
+
+class TestEmission:
+ def test_an_existing_edge_is_left_alone(self) -> None:
+ g = _graph("a.x", "b.x")
+ g.add_edge("a.x", "b.x", edge_type="imports", imported_names=["real"])
+ added = emit_scope_edges(
+ g,
+ [("a.x", "Widget w;")],
+ lambda p, t: _one_tier({"Widget": ["b.x"]}),
+ skip_names=_EMPTY,
+ )
+ assert added == 0
+ assert g["a.x"]["b.x"]["imported_names"] == ["real"]
+ assert "hint_source" not in g["a.x"]["b.x"]
+
+ def test_a_target_outside_the_graph_produces_no_edge(self) -> None:
+ g = _graph("a.x")
+ added = emit_scope_edges(
+ g,
+ [("a.x", "Widget w;")],
+ lambda p, t: _one_tier({"Widget": ["gone.x"]}),
+ skip_names=_EMPTY,
+ )
+ assert added == 0
diff --git a/tests/unit/test_no_bare_type_name_copies.py b/tests/unit/test_no_bare_type_name_copies.py
index 681ee53a1..780f333d9 100644
--- a/tests/unit/test_no_bare_type_name_copies.py
+++ b/tests/unit/test_no_bare_type_name_copies.py
@@ -57,6 +57,9 @@ _SCOPE = (
_INGESTION / "type_ref_resolution.py",
_INGESTION / "call_resolver.py",
_INGESTION / "heritage_resolver.py",
+ # Holds the shared symbol-ID splitter both resolvers used to keep a copy
+ # of; in scope so moving it did not move it out of reach.
+ _INGESTION / "models.py",
)
_PREFIX = "packages/core/src/repowise/core/ingestion/"
@@ -67,9 +70,10 @@ _PREFIX = "packages/core/src/repowise/core/ingestion/"
_KNOWN: dict[str, int] = {
# Splits our own `path::Class::method` symbol IDs, which we mint. The
# separator is ours rather than the language's, so the shared helper would
- # be answering about a type where these ask about an ID.
- _PREFIX + "call_resolver.py": 3,
- _PREFIX + "heritage_resolver.py": 1,
+ # be answering about a type where these ask about an ID. `models.py` holds
+ # the one both resolvers used to duplicate.
+ _PREFIX + "call_resolver.py": 2,
+ _PREFIX + "models.py": 1,
# Normalises the method name out of `#selector(Type.method)`. The last
# segment here is a member, not a type.
_PREFIX + "dynamic_hints/swift.py": 1,