Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
fix(core): overload stubs are declarations, so lookups serve the implementation (#2696)
Swati Ahujaae0181244ba7
diff --git a/packages/core/src/repowise/core/ingestion/call_resolver.py b/packages/core/src/repowise/core/ingestion/call_resolver.pyindex 624db253e..a4c41d379 100644--- a/packages/core/src/repowise/core/ingestion/call_resolver.py+++ b/packages/core/src/repowise/core/ingestion/call_resolver.py@@ -570,7 +570,8 @@ class CallResolver(LanguageStrategiesMixin, ReceiverTypingMixin):redirects: dict[str, str] = {}for decl_file, decl_id, key in declarations:candidates = definitions.get(key, ())- if not candidates:+ # An overload stub's implementation shares its id: already defined.+ if not candidates or any(sym_id == decl_id for _f, sym_id in candidates):continue# Deduped by symbol id, not by row: an overload set defined in one# file is several definitions sharing one id, and counting rowsdiff --git a/packages/core/src/repowise/core/ingestion/extractors/signatures.py b/packages/core/src/repowise/core/ingestion/extractors/signatures.pyindex 66a470070..4cb3c0337 100644--- a/packages/core/src/repowise/core/ingestion/extractors/signatures.py+++ b/packages/core/src/repowise/core/ingestion/extractors/signatures.py@@ -38,7 +38,10 @@ def build_signature(node_type: str, name: str, params_text: str, def_node: Node,# the same ``name`` / ``parameters`` / ``return_type`` fields, so it# takes this branch rather than the bare-name fallback at the end.return f"fn {name}{params_text}{_ret(('return_type',))}"- if node_type in ("function_declaration", "generator_function_declaration"):+ if node_type in ("function_declaration", "generator_function_declaration") or (+ # TS overload signature; Dart's same-named node has no ``parameters`` field.+ node_type == "function_signature" and def_node.child_by_field_name("parameters")+ ):# TS/JS use return_type; Go uses resultreturn f"function {name}{params_text}{_ret(('return_type', 'result'))}"if node_type in ("class_definition", "class_declaration", "abstract_class_declaration"):@@ -52,7 +55,7 @@ def build_signature(node_type: str, name: str, params_text: str, def_node: Node,return f"type {name}"if node_type == "enum_declaration":return f"enum {name}"- if node_type == "method_definition":+ if node_type in ("method_definition", "method_signature"):# TypeScript/JavaScript class methodreturn f"{name}{params_text}{_ret(('return_type',))}"if node_type == "method_declaration":diff --git a/packages/core/src/repowise/core/ingestion/language_configs.py b/packages/core/src/repowise/core/ingestion/language_configs.pyindex 9e0f78b07..c9e9c5156 100644--- a/packages/core/src/repowise/core/ingestion/language_configs.py+++ b/packages/core/src/repowise/core/ingestion/language_configs.py@@ -127,12 +127,16 @@ LANGUAGE_CONFIGS: dict[str, LanguageConfig] = {# Top-level const/let with a literal value (the .scm pattern is# program-anchored). Refined in the parser like Python assignments."variable_declarator": "constant",+ # Overload signatures (the .scm keeps method ones to class bodies).+ "function_signature": "function",+ "method_signature": "method",},import_node_types=["import_statement"],export_node_types=["export_statement"],visibility_fn=ts_visibility,parent_extraction="nesting",parent_class_types=frozenset({"class_declaration", "abstract_class_declaration"}),+ declaration_node_types=frozenset({"function_signature", "method_signature"}),),"javascript": LanguageConfig(symbol_node_types={diff --git a/packages/core/src/repowise/core/ingestion/models.py b/packages/core/src/repowise/core/ingestion/models.pyindex 069ff51f3..a6ca55247 100644--- a/packages/core/src/repowise/core/ingestion/models.py+++ b/packages/core/src/repowise/core/ingestion/models.py@@ -208,7 +208,9 @@ class Symbol:# declaration in a header. The definition carrying the same name lives in# a .cpp and is the symbol a call should attach to; the call resolver# redirects onto it, and the dead-code pass never reports a declaration,- # since a declaration is not independently deletable.+ # since a declaration is not independently deletable. Python ``@overload``+ # stubs and TypeScript overload signatures are declarations too: they share+ # the implementation's id, and the implementation is the symbol to serve.is_declaration: bool = Falsediff --git a/packages/core/src/repowise/core/ingestion/parser.py b/packages/core/src/repowise/core/ingestion/parser.pyindex f808304b9..a31501c9f 100644--- a/packages/core/src/repowise/core/ingestion/parser.py+++ b/packages/core/src/repowise/core/ingestion/parser.py@@ -493,12 +493,52 @@ def _match_identity(return def_node, name_nodes, name, export_type, start_line+# ``@overload`` stubs are signatures for the type checker; the undecorated def+# that follows under the same id is the one that runs.+def _is_python_overload(def_node: Node, src: str) -> bool:+ parent = def_node.parent+ if parent is None or parent.type != "decorated_definition":+ return False+ for decorator in parent.children:+ if decorator.type != "decorator":+ continue+ # The expression, not the node text: a trailing comment sits inside it.+ expr = next((c for c in decorator.named_children if c.type != "comment"), None)+ # ``overload``, ``typing.overload``, or through an alias (``t.overload``).+ if expr is not None and _node_text(expr, src).rsplit(".", 1)[-1] == "overload":+ return True+ return False+++_TS_OVERLOAD_SIGNATURES = frozenset({"function_signature", "method_signature"})+++def _keep_ts_overloads_beside_a_body(symbols: list[Symbol], node_types: list[str]) -> list[Symbol]:+ """Drop a bodiless TS signature whose id has no implementation in the file.++ That is an ambient declaration (``declare function``, a ``.d.ts``), not an+ overload, and it never was a symbol.+ """+ bodied = {s.id for s, t in zip(symbols, node_types, strict=True) if t not in _TS_OVERLOAD_SIGNATURES}+ return [+ s+ for s, t in zip(symbols, node_types, strict=True)+ if t not in _TS_OVERLOAD_SIGNATURES or s.id in bodied+ ]++def _is_declaration(- def_node: Node, config: LanguageConfig, language: str, export_type: _CppExportType | None+ def_node: Node,+ config: LanguageConfig,+ language: str,+ export_type: _CppExportType | None,+ src: str,) -> bool:node_type = def_node.typeif node_type in config.declaration_node_types:return True+ if language == "python":+ return _is_python_overload(def_node, src)if export_type is not None:return export_type.is_forward_declarationreturn _is_bodiless_cpp_type(language, node_type, def_node)@@ -1313,9 +1353,9 @@ class ASTParser:language = file_info.languagesymbols: list[Symbol] = []seen: set[tuple[int, str]] = set() # (start_line, name) — dedup decorated dupes- # Parallel to ``symbols`` (same indices) -- only populated/consumed- # for Pascal and Objective-C, to dedupe interface-declaration vs.- # implementation method pairs after the loop. See+ # Parallel to ``symbols`` (same indices) -- consumed for Pascal and+ # Objective-C, to dedupe interface-declaration vs. implementation+ # method pairs after the loop, and for TS overload signatures. See# _dedupe_pascal_interface_symbols / _dedupe_objc_interface_symbols.node_types: list[str] = []# Also parallel to ``symbols``, Objective-C only: which of @interface /@@ -1348,6 +1388,9 @@ class ASTParser:if language == "pascal":symbols = _dedupe_pascal_interface_symbols(symbols, node_types)+ if language in _TS_JS_LANGUAGES:+ symbols = _keep_ts_overloads_beside_a_body(symbols, node_types)+# A .m file routinely declares its private methods in a class# extension and defines them below in the @implementation, which# builds each symbol id twice in one file.@@ -1451,7 +1494,7 @@ class ASTParser:language=language,parent_name=parent_name,is_exported_symbol=is_exported_symbol,- is_declaration=_is_declaration(def_node, config, language, export_type),+ is_declaration=_is_declaration(def_node, config, language, export_type, src),)return symbol, def_nodediff --git a/packages/core/src/repowise/core/ingestion/queries/typescript.scm b/packages/core/src/repowise/core/ingestion/queries/typescript.scmindex bfe0f35d4..43b5a9efa 100644--- a/packages/core/src/repowise/core/ingestion/queries/typescript.scm+++ b/packages/core/src/repowise/core/ingestion/queries/typescript.scm@@ -152,6 +152,24 @@))+; Overload signatures: ``function f(a: string): string;`` and a class body's+; ``m(a: string): void;``. Bodiless, so the parser marks them declarations; the+; implementation under the same id is the symbol that is served, and one with+; no implementation (an ambient ``declare``) is dropped there. An interface's+; method_signature is a member shape, not an overload, and stays out.+(function_signature+ name: (identifier) @symbol.name+ parameters: (formal_parameters) @symbol.params+) @symbol.def++(class_body+ (method_signature+ (accessibility_modifier)? @symbol.modifiers+ name: [(property_identifier) (private_property_identifier)] @symbol.name+ parameters: (formal_parameters) @symbol.params+ ) @symbol.def+)+; ---------------------------------------------------------------------------; Imports; ---------------------------------------------------------------------------diff --git a/packages/core/src/repowise/core/persistence/crud/external_systems.py b/packages/core/src/repowise/core/persistence/crud/external_systems.pyindex de76f2bdf..54b5be397 100644--- a/packages/core/src/repowise/core/persistence/crud/external_systems.py+++ b/packages/core/src/repowise/core/persistence/crud/external_systems.py@@ -244,10 +244,12 @@ async def batch_upsert_symbols(Accepts ingestion.models.Symbol dataclass instances (duck-typed)."""+ # One row per id and the last duplicate wins: an overload set's+ # implementation goes last so its body, not a stub, is the stored range.await _batch_upsert_keyed(session,WikiSymbol,- symbols,+ sorted(symbols, key=lambda sym: not getattr(sym, "is_declaration", False)),prefilter=(WikiSymbol.repository_id == repository_id,),item_key_fn=_symbol_id,row_key_fn=lambda row: row.symbol_id,diff --git a/packages/core/src/repowise/core/upgrade/version.py b/packages/core/src/repowise/core/upgrade/version.pyindex 6c6d56298..c72aefd6f 100644--- a/packages/core/src/repowise/core/upgrade/version.py+++ b/packages/core/src/repowise/core/upgrade/version.py@@ -59,7 +59,10 @@ STORE_FORMAT_VERSION: int = 2#: guess, no sibling lookup inside a package, never the importer itself), and#: ``from pkg import a, b`` over submodules no longer edges into#: ``pkg/__init__.py``. Reconciling once drops the stale edges from old stores.-PARSER_SCHEMA_VERSION: int = 4+#:+#: v5: an overload signature (Python ``@overload``, TypeScript function / method+#: overload) is marked ``is_declaration`` so lookups serve the implementation.+PARSER_SCHEMA_VERSION: int = 5#: state.json key holding the store format version that wrote the store.STORE_FORMAT_VERSION_KEY = "store_format_version"diff --git a/packages/server/src/repowise/server/mcp_server/_verify.py b/packages/server/src/repowise/server/mcp_server/_verify.pyindex 893d1306d..033b6bcd3 100644--- a/packages/server/src/repowise/server/mcp_server/_verify.py+++ b/packages/server/src/repowise/server/mcp_server/_verify.py@@ -131,7 +131,9 @@ def relocate_symbol(row: WikiSymbol, source_text: str) -> tuple[int, int] | None_log.warning("re-parse failed for %s: %s", row.file_path, exc)return None- symbols = parsed.symbols or []+ # An overload set is several rows under one id; the implementation (the+ # one non-declaration) goes first so a stub never answers for it.+ symbols = sorted(parsed.symbols or [], key=lambda sym: sym.is_declaration)# Strongest match first: exact symbol_id, then (name, parent), then name.for sym in symbols:if sym.id == row.symbol_id:diff --git a/tests/fixtures/lang_samples/python/py_overload_init.py b/tests/fixtures/lang_samples/python/py_overload_init.pynew file mode 100644index 000000000..9834e97ae--- /dev/null+++ b/tests/fixtures/lang_samples/python/py_overload_init.py@@ -0,0 +1,36 @@+import typing+from typing import overload++import typing_extensions+++class Client:+ @overload # a comment inside the decorator node+ def __init__(self, url: str) -> None: ...++ @typing.overload+ def __init__(self, url: str, timeout: float) -> None: ...++ def __init__(self, url, timeout=None):+ self.url = url+ self.timeout = timeout+ self.connect()++ def connect(self):+ return self.url++ @staticmethod+ def build(url):+ return Client(url)+++@typing_extensions.overload+def parse(raw: str) -> str: ...+++@overload+def parse(raw: bytes) -> bytes: ...+++def parse(raw):+ return rawdiff --git a/tests/fixtures/lang_samples/typescript/ts_overload_fn_method.ts b/tests/fixtures/lang_samples/typescript/ts_overload_fn_method.tsnew file mode 100644index 000000000..47f305386--- /dev/null+++ b/tests/fixtures/lang_samples/typescript/ts_overload_fn_method.ts@@ -0,0 +1,29 @@+export function parse(raw: string): string;+export function parse(raw: Uint8Array): Uint8Array;+export function parse(raw: string | Uint8Array): string | Uint8Array {+ return raw;+}++export class Client {+ send(body: string): void;+ send(body: Uint8Array): void;+ send(body: string | Uint8Array): void {+ this.connect();+ }++ private connect(): void;+ private connect(retries: number): void;+ private connect(retries?: number): void {+ return;+ }+}++export interface Transport {+ open(url: string): void;+}++declare function ambient(x: string): void;++declare class Shim {+ run(x: string): void;+}diff --git a/tests/unit/ingestion/test_overload_declarations.py b/tests/unit/ingestion/test_overload_declarations.pynew file mode 100644index 000000000..61e589ddf--- /dev/null+++ b/tests/unit/ingestion/test_overload_declarations.py@@ -0,0 +1,170 @@+"""Overload stubs are declarations; the implementation is the symbol.++A Python ``@overload`` stub and a TypeScript overload signature share the+implementation's symbol id. Unmarked, any consumer that takes the first row for+an id served the stub's line range next to the implementation's call edges.+The rows are kept, not dropped: the call resolver reads every overload's return+type (``_overload_return_types``), and an overload set is one id with several+rows (``test_overload_set_uniqueness.py``).+"""++from __future__ import annotations++import shutil+from pathlib import Path++import pytest++from repowise.core.ingestion import ASTParser, FileTraverser, GraphBuilder+from repowise.core.ingestion.call_resolver import CallResolver, _overload_return_types++FIXTURES = Path(__file__).resolve().parents[2] / "fixtures" / "lang_samples"+PY_FIXTURE = FIXTURES / "python" / "py_overload_init.py"+TS_FIXTURE = FIXTURES / "typescript" / "ts_overload_fn_method.ts"+++def _parse(tmp_path: Path, fixture: Path):+ shutil.copy(fixture, tmp_path / fixture.name)+ parser = ASTParser()+ parsed = {}+ builder = GraphBuilder(repo_path=tmp_path)+ for fi in FileTraverser(tmp_path).traverse():+ pf = parser.parse_file(fi, Path(fi.abs_path).read_bytes())+ parsed[fi.path] = pf+ builder.add_file(pf)+ return parsed[fixture.name], builder.build()+++def _rows(parsed, sym_id: str) -> list[tuple[int, int, bool]]:+ return [(s.start_line, s.end_line, s.is_declaration) for s in parsed.symbols if s.id == sym_id]+++class TestPythonOverloads:+ @pytest.fixture+ def parsed_graph(self, tmp_path: Path):+ return _parse(tmp_path, PY_FIXTURE)++ def test_stubs_are_declarations_and_implementation_is_not(self, parsed_graph) -> None:+ parsed, _ = parsed_graph+ # ``@overload`` and ``@typing.overload``, then the implementation.+ assert _rows(parsed, "py_overload_init.py::Client::__init__") == [+ (9, 9, True),+ (12, 12, True),+ (14, 17, False),+ ]+ # ``@typing_extensions.overload`` and a bare ``@overload`` at module level.+ assert _rows(parsed, "py_overload_init.py::parse") == [+ (28, 28, True),+ (32, 32, True),+ (35, 36, False),+ ]++ def test_other_decorators_are_not_declarations(self, parsed_graph) -> None:+ parsed, _ = parsed_graph+ assert _rows(parsed, "py_overload_init.py::Client::build") == [(23, 24, False)]+ assert _rows(parsed, "py_overload_init.py::Client::connect") == [(19, 20, False)]++ def test_overload_through_a_module_alias(self, tmp_path: Path) -> None:+ (tmp_path / "m.py").write_text(+ "import typing as t\n\n\[email protected]\ndef f(x: int) -> int: ...\ndef f(x):\n return x\n"+ )+ (fi,) = FileTraverser(tmp_path).traverse()+ parsed = ASTParser().parse_file(fi, Path(fi.abs_path).read_bytes())+ assert _rows(parsed, "m.py::f") == [(5, 5, True), (6, 7, False)]++ def test_graph_node_spans_the_implementation(self, parsed_graph) -> None:+ _, graph = parsed_graph+ node = graph.nodes["py_overload_init.py::Client::__init__"]+ assert (node["start_line"], node["end_line"]) == (14, 17)+ assert node["is_declaration"] is False+ callees = {+ tgt+ for _, tgt, data in graph.out_edges("py_overload_init.py::Client::__init__", data=True)+ if data.get("edge_type") == "calls"+ }+ assert "py_overload_init.py::Client::connect" in callees++ def test_every_overload_return_type_is_kept(self, parsed_graph) -> None:+ parsed, _ = parsed_graph+ types = _overload_return_types({"py_overload_init.py": parsed})+ assert {"str", "bytes"} <= set().union(+ *(v for (_, parent, name, _), v in types.items() if (parent, name) == (None, "parse"))+ )++ def test_stub_is_not_paired_with_a_same_named_definition_elsewhere(+ self, tmp_path: Path+ ) -> None:+ # Its implementation shares its id, so a same-named def in an importing+ # file must not capture the calls aimed at it.+ files = {+ "a.py": PY_FIXTURE.read_text(),+ "b.py": "import a\n\n\ndef parse(raw):\n return a.parse(raw)\n",+ "c.py": "from a import parse\n\n\ndef run():\n return parse('x')\n",+ }+ for name, text in files.items():+ (tmp_path / name).write_text(text)+ parser = ASTParser()+ parsed = {+ fi.path: parser.parse_file(fi, Path(fi.abs_path).read_bytes())+ for fi in FileTraverser(tmp_path).traverse()+ }+ resolver = CallResolver(+ parsed, {"b.py": {"a.py"}, "c.py": {"a.py"}}, repo_path=str(tmp_path)+ )+ assert "a.py::parse" not in resolver.declaration_definitions+ callees = {rc.callee_id for rc in resolver.resolve_file("c.py", parsed["c.py"].calls)}+ assert callees == {"a.py::parse"}+++class TestTypeScriptOverloads:+ @pytest.fixture+ def parsed_graph(self, tmp_path: Path):+ return _parse(tmp_path, TS_FIXTURE)++ def test_function_signatures_are_declarations(self, parsed_graph) -> None:+ parsed, _ = parsed_graph+ assert _rows(parsed, "ts_overload_fn_method.ts::parse") == [+ (1, 1, True),+ (2, 2, True),+ (3, 5, False),+ ]+ sigs = [s.signature for s in parsed.symbols if s.id == "ts_overload_fn_method.ts::parse"]+ assert sigs[0] == "function parse(raw: string) -> string"+ assert all(s.kind == "function" for s in parsed.symbols if s.name == "parse")++ def test_class_overload_signatures_are_declarations(self, parsed_graph) -> None:+ parsed, _ = parsed_graph+ assert _rows(parsed, "ts_overload_fn_method.ts::Client::send") == [+ (8, 8, True),+ (9, 9, True),+ (10, 12, False),+ ]+ connect = [s for s in parsed.symbols if s.id == "ts_overload_fn_method.ts::Client::connect"]+ assert [(s.start_line, s.end_line, s.is_declaration) for s in connect] == [+ (14, 14, True),+ (15, 15, True),+ (16, 18, False),+ ]+ assert {(s.kind, s.parent_name, s.visibility) for s in connect} == {+ ("method", "Client", "private")+ }++ def test_interface_method_signature_is_not_a_symbol(self, parsed_graph) -> None:+ parsed, _ = parsed_graph+ assert not [s for s in parsed.symbols if s.name == "open"]++ def test_ambient_signature_without_a_body_is_not_a_symbol(self, parsed_graph) -> None:+ # ``declare`` signatures have no implementation; they are not overloads.+ parsed, _ = parsed_graph+ assert not [s for s in parsed.symbols if s.name in ("ambient", "run")]+ assert [s.name for s in parsed.symbols if s.name == "Shim"] == ["Shim"]++ def test_graph_node_spans_the_implementation(self, parsed_graph) -> None:+ _, graph = parsed_graph+ for sym_id, span in (+ ("ts_overload_fn_method.ts::parse", (3, 5)),+ ("ts_overload_fn_method.ts::Client::send", (10, 12)),+ ):+ node = graph.nodes[sym_id]+ assert (node["start_line"], node["end_line"]) == span+ assert node["is_declaration"] is Falsediff --git a/tests/unit/persistence/test_crud.py b/tests/unit/persistence/test_crud.pyindex 53212b7be..4c3793ba0 100644--- a/tests/unit/persistence/test_crud.py+++ b/tests/unit/persistence/test_crud.py@@ -479,6 +479,39 @@ async def test_batch_upsert_symbols_inserts(async_session):assert names == {"foo", "bar"}+async def test_batch_upsert_symbols_stores_the_implementation_of_an_overload_set(async_session):+ from types import SimpleNamespace++ from sqlalchemy import select++ from repowise.core.persistence.models import WikiSymbol++ def sym(start: int, end: int, is_declaration: bool) -> SimpleNamespace:+ return SimpleNamespace(+ id="src/a.py::parse",+ name="parse",+ kind="function",+ file_path="src/a.py",+ start_line=start,+ end_line=end,+ is_declaration=is_declaration,+ )++ repo = await insert_repo(async_session)+ # Implementation first: the stored row must not depend on emission order.+ await batch_upsert_symbols(+ async_session, repo.id, [sym(10, 14, False), sym(4, 4, True), sym(7, 7, True)]+ )+ await async_session.commit()++ saved = (+ (await async_session.execute(select(WikiSymbol).where(WikiSymbol.repository_id == repo.id)))+ .scalars()+ .all()+ )+ assert [(s.start_line, s.end_line) for s in saved] == [(10, 14)]++# ---------------------------------------------------------------------------# WebhookEvent CRUD# ---------------------------------------------------------------------------diff --git a/tests/unit/server/mcp/test_verify_bounds.py b/tests/unit/server/mcp/test_verify_bounds.pyindex 770ea210d..2c1d178e7 100644--- a/tests/unit/server/mcp/test_verify_bounds.py+++ b/tests/unit/server/mcp/test_verify_bounds.py@@ -179,6 +179,20 @@ class TestRelocateSymbol:assert located is not Noneassert located[0] == 10+ def test_relocate_serves_the_implementation_not_an_overload_stub(self) -> None:+ source = (+ "from typing import overload\n"+ "\n"+ "\n"+ "@overload\n"+ "def alpha(x: int) -> int: ...\n"+ "@overload\n"+ "def alpha(x: str) -> str: ...\n"+ "def alpha(x):\n"+ " return x\n"+ )+ assert relocate_symbol(_row(), source) == (8, 9)+def test_relocate_returns_none_for_missing_symbol(self) -> None:row = _row(name="ghost", symbol_id="pkg/mod.py::ghost")assert relocate_symbol(row, SHIFTED_SOURCE) is None