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.

feat(ingestion): register unresolved Python imports as external nodes (#2136)

Raghav Chamadiya6d74db2e95c7
diff --git a/packages/core/src/repowise/core/ingestion/resolvers/python.py b/packages/core/src/repowise/core/ingestion/resolvers/python.py
index 441520f1f..8da42b29e 100644
--- a/packages/core/src/repowise/core/ingestion/resolvers/python.py
+++ b/packages/core/src/repowise/core/ingestion/resolvers/python.py
@@ -71,9 +71,20 @@ def resolve_python_import(module_path: str, importer_path: str, ctx: ResolverCon
if c in ctx.path_set:
return c
- # Stem-only fallback
+ # Stem-only fallback, Python files only. The stem map holds every indexed
+ # file, so without the suffix guard ``import httpx`` resolved to a
+ # ``baselines/httpx.json`` fixture; Ruby and PHP guard theirs the same way.
stem = module_path.split(".")[-1].lower()
- return ctx.stem_lookup(stem)
+ for candidate in ctx.stem_map.get(stem, ()):
+ if candidate.endswith((".py", ".pyi")):
+ return candidate
+
+ # Nothing in the repo defines this module, so register it the way every
+ # other language resolver does: the packages tab and the import counts can
+ # only see a third-party or stdlib dependency if the miss becomes a node.
+ # Stdlib is included on purpose, as Go and TypeScript already do, and
+ # io_kind.py seeds stdlib names for exactly this consumer.
+ return ctx.add_external_node(module_path)
def resolve_python_import_all(
diff --git a/packages/core/src/repowise/core/upgrade/version.py b/packages/core/src/repowise/core/upgrade/version.py
index a8825e4cb..6ccb5d6e0 100644
--- a/packages/core/src/repowise/core/upgrade/version.py
+++ b/packages/core/src/repowise/core/upgrade/version.py
@@ -48,7 +48,13 @@ STORE_FORMAT_VERSION: int = 2
#: a Rust macro invocation stopped being extracted as a call. A cache written
#: before that carries neither field, so the scoped-call, chained-call and
#: macro fixes would resolve against stale rows instead of firing.
-PARSER_SCHEMA_VERSION: int = 2
+#:
+#: v3: a Python import that resolves to no repo file now becomes an
+#: ``external:`` node and edge instead of resolving to nothing. The fingerprint
+#: change makes ``persist_incremental_edges`` reconcile every file's edges once
+#: on the next update, so an existing index does not keep half its Python files
+#: without external edges.
+PARSER_SCHEMA_VERSION: int = 3
#: state.json key holding the store format version that wrote the store.
STORE_FORMAT_VERSION_KEY = "store_format_version"
diff --git a/tests/unit/ingestion/test_graph.py b/tests/unit/ingestion/test_graph.py
index 4e6c5e355..bdc899b0c 100644
--- a/tests/unit/ingestion/test_graph.py
+++ b/tests/unit/ingestion/test_graph.py
@@ -209,17 +209,16 @@ class TestPythonImports:
b.build()
assert b.graph().has_edge("main.py", "src/calculator.py")
- def test_unresolvable_import_no_edge(self) -> None:
- """Unresolvable import produces no import edge (no crash)."""
+ def test_unresolvable_import_becomes_external(self) -> None:
+ """An absolute import no repo file defines lands on an external node."""
b = GraphBuilder()
b.add_file(_parsed("main.py", imports=[_imp("nonexistent_external_lib")]))
b.build()
- # Only the defines edge for the synthetic __module__ symbol
import_edges = [
(u, v) for u, v, d in b.graph().edges(data=True)
if d.get("edge_type") == "imports"
]
- assert len(import_edges) == 0
+ assert import_edges == [("main.py", "external:nonexistent_external_lib")]
def test_imported_names_on_edge(self) -> None:
"""Imported names are stored on the edge."""
@@ -339,12 +338,12 @@ class TestStemDisambiguation:
b.add_file(_parsed("__init__.py"))
b.add_file(_parsed("main.py", imports=[_imp("anything")]))
b.build() # must not raise
- # No import edge — stem "anything" is unresolvable
+ # The stem "anything" resolves to no file, so it lands on an external node.
import_edges = [
(u, v) for u, v, d in b.graph().edges(data=True)
if d.get("edge_type") == "imports"
]
- assert len(import_edges) == 0
+ assert import_edges == [("main.py", "external:anything")]
def test_go_stem_collision_prefers_parent_match(self) -> None:
"""Go: `import .../calculator` prefers calculator/calculator.go
diff --git a/tests/unit/ingestion/test_python_resolver_external.py b/tests/unit/ingestion/test_python_resolver_external.py
new file mode 100644
index 000000000..83589407a
--- /dev/null
+++ b/tests/unit/ingestion/test_python_resolver_external.py
@@ -0,0 +1,87 @@
+"""Unresolvable absolute Python imports become ``external:`` nodes.
+
+Pins the tail of ``resolve_python_import``: an absolute import no repo file
+defines registers an external node, a relative miss stays None, and a
+resolvable import is untouched.
+"""
+
+from __future__ import annotations
+
+import networkx as nx
+
+from repowise.core.ingestion.models import Import
+from repowise.core.ingestion.resolvers.context import ResolverContext
+from repowise.core.ingestion.resolvers.python import (
+ resolve_python_import,
+ resolve_python_import_all,
+)
+
+PATHS = {"app.py", "pkg/__init__.py", "pkg/mod.py"}
+
+
+def _ctx() -> ResolverContext:
+ return ResolverContext(path_set=set(PATHS), stem_map={}, graph=nx.DiGraph())
+
+
+def _imp(module_path: str, names: list[str]) -> Import:
+ return Import(
+ raw_statement="",
+ module_path=module_path,
+ imported_names=names,
+ is_relative=False,
+ resolved_file=None,
+ bindings=[],
+ )
+
+
+def test_absolute_miss_registers_external_node() -> None:
+ ctx = _ctx()
+ assert resolve_python_import("requests", "app.py", ctx) == "external:requests"
+ assert ctx.graph.nodes["external:requests"]["language"] == "external"
+
+
+def test_dotted_miss_keeps_the_full_module_path() -> None:
+ ctx = _ctx()
+ resolved = resolve_python_import("requests.adapters", "app.py", ctx)
+ assert resolved == "external:requests.adapters"
+ assert "external:requests.adapters" in ctx.graph.nodes
+
+
+def test_stdlib_miss_is_external_too() -> None:
+ ctx = _ctx()
+ assert resolve_python_import("subprocess", "app.py", ctx) == "external:subprocess"
+ assert ctx.graph.nodes["external:subprocess"]["language"] == "external"
+
+
+def test_relative_miss_stays_none_and_adds_nothing() -> None:
+ ctx = _ctx()
+ assert resolve_python_import(".missing", "app.py", ctx) is None
+ assert list(ctx.graph.nodes) == []
+
+
+def test_resolvable_absolute_import_is_untouched() -> None:
+ ctx = _ctx()
+ assert resolve_python_import("pkg.mod", "app.py", ctx) == "pkg/mod.py"
+ assert list(ctx.graph.nodes) == []
+
+
+def test_resolve_all_returns_the_external_key_without_probing() -> None:
+ ctx = _ctx()
+ targets = resolve_python_import_all(_imp("requests", ["adapters", "Session"]), "app.py", ctx)
+ assert targets == ("external:requests",)
+
+
+def test_stem_fallback_never_lands_on_a_non_python_file() -> None:
+ ctx = ResolverContext(
+ path_set={"app.py", "baselines/httpx.json", "vendor/httpx.py"},
+ stem_map={"httpx": ["baselines/httpx.json", "vendor/httpx.py"]},
+ graph=nx.DiGraph(),
+ )
+ assert resolve_python_import("httpx", "app.py", ctx) == "vendor/httpx.py"
+
+ only_fixture = ResolverContext(
+ path_set={"app.py", "baselines/httpx.json"},
+ stem_map={"httpx": ["baselines/httpx.json"]},
+ graph=nx.DiGraph(),
+ )
+ assert resolve_python_import("httpx", "app.py", only_fixture) == "external:httpx"
diff --git a/tests/unit/ingestion/test_python_resolver_fanout.py b/tests/unit/ingestion/test_python_resolver_fanout.py
index 335863526..d43e3bcc0 100644
--- a/tests/unit/ingestion/test_python_resolver_fanout.py
+++ b/tests/unit/ingestion/test_python_resolver_fanout.py
@@ -87,8 +87,11 @@ def test_relative_package_import_fans_out() -> None:
assert targets == ("pkg/sub/__init__.py", "pkg/sub/handlers.py")
-def test_unresolvable_import_returns_empty() -> None:
- imp = _imp("nonexistent", ["thing"])
+def test_unresolvable_relative_import_returns_empty() -> None:
+ # A relative miss is a repo-local miss and stays unresolved. An absolute
+ # miss becomes an ``external:`` target instead; see
+ # ``test_python_resolver_external.py``.
+ imp = _imp(".nonexistent", ["thing"], relative=True)
assert resolve_python_import_all(imp, "app.py", _ctx(PATHS)) == ()