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.

fix(ingestion): use the importable module for Python qualified names (#2612)

Amanb968a5fbfd5c
diff --git a/packages/core/src/repowise/core/ingestion/graph/builder.py b/packages/core/src/repowise/core/ingestion/graph/builder.py
index 71dc82051..1bc35dcf9 100644
--- a/packages/core/src/repowise/core/ingestion/graph/builder.py
+++ b/packages/core/src/repowise/core/ingestion/graph/builder.py
@@ -15,6 +15,7 @@ import networkx as nx
import structlog
from ..cohesion import SAME_PACKAGE_HINT, UNIT_FANOUT_LANGUAGES
+from ..languages.python_modules import dotted_module_for
from ..models import ParsedFile
from ..resolvers import ResolverContext, resolve_import
from ..resolvers.go import read_go_module_path, read_go_modules
@@ -302,6 +303,30 @@ class GraphBuilder(MetricsMixin, ResolveMixin, EdgesMixin, SerializeMixin, Rehyd
)
self._graph.add_edge(path, module_sym_id, edge_type="defines")
+ def _qualify_python_symbols(self) -> None:
+ """Rename Python symbols to their importable dotted module.
+
+ The parser sees one file, so it dots the raw repository path and a
+ src-layout symbol carries the layout prefix
+ (``packages.core.src.pkg.mod.f``). The importable name needs every
+ repository path, which only exists here. A file with no derivable
+ module keeps the path form. Derived from the path each time, so
+ re-running it, or running it on a cached parse, gives the same names.
+ ``Symbol.id`` is untouched.
+ """
+ path_set = set(self._parsed_files)
+ for path, parsed in self._parsed_files.items():
+ if parsed.file_info.language != "python":
+ continue
+ module = dotted_module_for(path, path_set)
+ if module is None:
+ module = PurePosixPath(path).with_suffix("").as_posix().replace("/", ".")
+ for sym in parsed.symbols:
+ prefix = f"{module}.{sym.parent_name}" if sym.parent_name else module
+ sym.qualified_name = f"{prefix}.{sym.name}"
+ if sym.id in self._graph:
+ self._graph.nodes[sym.id]["qualified_name"] = sym.qualified_name
+
def build(self, progress: Any | None = None) -> nx.DiGraph:
"""Resolve imports and calls, add edges. Returns the finalized graph.
@@ -311,6 +336,7 @@ class GraphBuilder(MetricsMixin, ResolveMixin, EdgesMixin, SerializeMixin, Rehyd
instead of a single opaque "0/1" bar over the whole build.
"""
self._invalidate_metric_caches()
+ self._qualify_python_symbols()
# Clear import/call edges but keep structural edges (defines, has_method)
edges_to_remove = [
diff --git a/tests/unit/ingestion/test_python_qualified_names.py b/tests/unit/ingestion/test_python_qualified_names.py
new file mode 100644
index 000000000..a2ab0985b
--- /dev/null
+++ b/tests/unit/ingestion/test_python_qualified_names.py
@@ -0,0 +1,90 @@
+"""Python ``qualified_name`` is the importable dotted module, not the repo path.
+
+The parser sees one file, so it dots the raw path. ``GraphBuilder.build`` runs
+after every file is parsed and rewrites Python names from the repository's
+package layout. ``Symbol.id`` is a separate identifier and must not move.
+"""
+
+from __future__ import annotations
+
+from repowise.core.ingestion.graph import GraphBuilder
+from repowise.core.ingestion.parser import ASTParser
+from tests.unit.ingestion.parser._helpers import _make_file_info
+
+_PY = b"class Widget:\n def run(self):\n pass\n\n\ndef helper():\n pass\n"
+_GO = b"package main\n\nfunc Helper() {}\n"
+
+
+def _build(files: dict[str, tuple[str, bytes]]) -> tuple[dict[str, dict[str, str]], GraphBuilder]:
+ parser = ASTParser()
+ builder = GraphBuilder()
+ parsed_by_path = {}
+ for path, (language, source) in files.items():
+ parsed = parser.parse_file(_make_file_info(path, language), source)
+ parsed_by_path[path] = parsed
+ builder.add_file(parsed)
+ builder.build()
+ names = {
+ path: {s.id: s.qualified_name for s in parsed.symbols}
+ for path, parsed in parsed_by_path.items()
+ }
+ return names, builder
+
+
+def test_python_names_use_importable_module_and_others_are_unchanged():
+ names, _ = _build(
+ {
+ "src/mypkg/__init__.py": ("python", b""),
+ "src/mypkg/core.py": ("python", _PY),
+ "packages/core/src/repowise/core/persist.py": ("python", _PY),
+ "flat/__init__.py": ("python", b""),
+ "flat/mod.py": ("python", _PY),
+ "scripts/tool.py": ("python", _PY),
+ "cmd/main.go": ("go", _GO),
+ }
+ )
+
+ assert names["src/mypkg/core.py"]["src/mypkg/core.py::helper"] == "mypkg.core.helper"
+ assert names["src/mypkg/core.py"]["src/mypkg/core.py::Widget::run"] == "mypkg.core.Widget.run"
+ assert (
+ names["packages/core/src/repowise/core/persist.py"][
+ "packages/core/src/repowise/core/persist.py::helper"
+ ]
+ == "repowise.core.persist.helper"
+ )
+ assert names["flat/mod.py"]["flat/mod.py::helper"] == "flat.mod.helper"
+ # A loose script has no importable module, so it keeps the path form.
+ assert names["scripts/tool.py"]["scripts/tool.py::helper"] == "scripts.tool.helper"
+ # Other languages keep the path form.
+ assert names["cmd/main.go"]["cmd/main.go::Helper"] == "cmd.main.Helper"
+
+
+def test_graph_nodes_carry_the_new_name_and_symbol_id_is_stable():
+ _, builder = _build({"src/mypkg/core.py": ("python", _PY)})
+ node = builder.graph().nodes["src/mypkg/core.py::helper"]
+ assert node["qualified_name"] == "mypkg.core.helper"
+ assert "src/mypkg/core.py::Widget::run" in builder.graph()
+
+
+def test_rebuilding_is_idempotent():
+ names, builder = _build({"src/mypkg/core.py": ("python", _PY)})
+ builder.build()
+ assert (
+ builder.graph().nodes["src/mypkg/core.py::helper"]["qualified_name"] == "mypkg.core.helper"
+ )
+ assert names["src/mypkg/core.py"]["src/mypkg/core.py::helper"] == "mypkg.core.helper"
+
+
+def test_two_files_deriving_one_module_keep_distinct_symbol_ids():
+ # Two source roots can both derive ``pkg.mod``. The names collide, the
+ # ids (which carry the path) do not, so both symbols stay in the graph.
+ names, builder = _build(
+ {
+ "a/src/pkg/mod.py": ("python", _PY),
+ "b/src/pkg/mod.py": ("python", _PY),
+ }
+ )
+ assert names["a/src/pkg/mod.py"]["a/src/pkg/mod.py::helper"] == "pkg.mod.helper"
+ assert names["b/src/pkg/mod.py"]["b/src/pkg/mod.py::helper"] == "pkg.mod.helper"
+ assert "a/src/pkg/mod.py::helper" in builder.graph()
+ assert "b/src/pkg/mod.py::helper" in builder.graph()
diff --git a/tests/unit/server/mcp/test_search.py b/tests/unit/server/mcp/test_search.py
index 4fac64d03..2162f3811 100644
--- a/tests/unit/server/mcp/test_search.py
+++ b/tests/unit/server/mcp/test_search.py
@@ -639,6 +639,14 @@ class TestSymbolSearch:
ids = [r["symbol_id"] for r in result["results"]]
assert "src/auth/service.py::login" in ids
+ @pytest.mark.asyncio
+ async def test_importable_module_path_finds_its_symbols(self, setup_mcp):
+ from repowise.server.mcp_server import search_codebase
+
+ result = await search_codebase("auth.service.AuthService.login", mode="symbol")
+ assert result["results"][0]["symbol_id"] == "src/auth/service.py::login"
+ assert result["results"][0]["qualified_name"] == "auth.service.AuthService.login"
+
@pytest.mark.asyncio
async def test_symbol_kind_filter(self, setup_mcp):
from repowise.server.mcp_server import search_codebase
diff --git a/tests/unit/server/test_tool_symbol.py b/tests/unit/server/test_tool_symbol.py
index e1e30ec04..1619ccb6c 100644
--- a/tests/unit/server/test_tool_symbol.py
+++ b/tests/unit/server/test_tool_symbol.py
@@ -166,3 +166,25 @@ def test_order_candidates_prefers_matching_file_path() -> None:
# No file_path hint: lowest id leads.
ordered = _order_candidates(rows, None) # type: ignore[arg-type]
assert [r.id for r in ordered] == ["aaaa", "zzzz"]
+
+
+async def test_resolve_symbol_by_importable_qualified_name(client, app, session_factory) -> None:
+ # Python names are the importable dotted module, not the src-layout path.
+ repo = await create_test_repo(client)
+ path = "packages/core/src/repowise/core/pipeline/persist.py"
+ await _add(
+ session_factory,
+ repo["id"],
+ file_path=path,
+ symbol_id=f"{path}::save",
+ name="save",
+ qualified_name="repowise.core.pipeline.persist.save",
+ )
+
+ async with get_session(session_factory) as session:
+ rows = await _resolve_symbol(
+ session, repo["id"], f"{path}::repowise.core.pipeline.persist.save"
+ )
+
+ assert [r.name for r in rows] == ["save"]