devlensio 1.0.3 → 1.1.0

package/extractors/python/devlens_extractors_python/edges/calls.py

@@ -1,4 +1,4 @@
-"""CALLS edge resolution — resolves metadata.calls names to node ids.
+"""CALLS edge resolution — resolves metadata.callSites names to node ids.
 
 Consumes the shared LookupMaps (lookup.py). Resolution ladder:
   self./cls.        → same-class method (exact dotted name)
@@ -8,6 +8,11 @@ Consumes the shared LookupMaps (lookup.py). Resolution ladder:
   plain name        → global nodes_by_name → import alias refinement
 Unknown/builtin names resolve to nothing (no edge) — metadata.calls keeps
 them for LLM context.
+
+Overload-aware tiebreak (mirrors src/graph/edges/callEdges.ts): when a lookup
+returns multiple same-name candidates, the call site's argument shape picks
+the target — arity compatibility first, argTypes agreement second, then the
+legacy closest-by-path heuristic. The edge records matchedBy.
 """
 from __future__ import annotations
 
@@ -19,7 +24,97 @@ def _find_in_file(lookup: LookupMaps, rel: str, name: str) -> str | None:
     return lookup.nodes_by_file.get(rel, {}).get(name)
 
 
-def _walk_module(lookup: LookupMaps, alias_target: str, rest: str) -> str | None:
+def _find_all_in_file(lookup: LookupMaps, rel: str, name: str) -> list[tuple[str, str]]:
+    """Every same-name node id in the file, in declaration order."""
+    ids = lookup.nodes_by_file_all.get(rel, {}).get(name, [])
+    return [(node_id, rel) for node_id in ids]
+
+
+def _bound_params(node: dict) -> tuple[list, list]:
+    """(effective_params, effective_parameters) for arity/type matching —
+    bound methods hide self/cls from the call site's argument count."""
+    metadata = node.get("metadata", {})
+    params = metadata.get("params") or []
+    parameters = metadata.get("parameters") or []
+    if node.get("type") == "METHOD" and params and params[0] in ("self", "cls"):
+        params = params[1:]
+        parameters = [p for p in parameters if p.get("name") not in ("self", "cls")]
+    return params, parameters
+
+
+def _arity_matches(node: dict, arg_count: int) -> bool:
+    """A candidate accepts the call when argCount covers every required
+    (non-optional, non-rest) param and does not exceed the declared count
+    unless a rest param (*args/**kwargs) absorbs the extras. Nodes without
+    parameter shape metadata are permissive."""
+    params, parameters = _bound_params(node)
+    if not params and not parameters:
+        return True
+    total = len(parameters) if parameters else len(params)
+    required = sum(1 for p in parameters if not p.get("isOptional") and not p.get("isRest")) \
+        if parameters else total
+    has_rest = any(p.get("isRest") for p in parameters) if parameters else False
+    return arg_count >= required and (has_rest or arg_count <= total)
+
+
+def _type_agrees(arg_type: str, param_type) -> bool:
+    if not arg_type or arg_type == "unknown" or not param_type:
+        return False
+    return param_type == arg_type or arg_type in param_type
+
+
+def _type_score(node: dict, arg_types: list[str]) -> int:
+    _, parameters = _bound_params(node)
+    score = 0
+    for i, t in enumerate(arg_types):
+        if i >= len(parameters):
+            break
+        if _type_agrees(t, parameters[i].get("type")):
+            score += 1
+    return score
+
+
+def _pick(candidates: list[tuple[str, str]], node: dict, call_site: dict | None,
+          lookup: LookupMaps, rel: str) -> tuple[str | None, str]:
+    """Ladder: single hit → name · arity filter → type tiebreak → path.
+    Returns (target_id, matchedBy)."""
+    if not candidates:
+        return None, "name"
+    if len(candidates) == 1:
+        return candidates[0][0], "name"
+
+    usable_shape = (call_site is not None
+                    and not call_site.get("hasSpread")
+                    and isinstance(call_site.get("argCount"), int))
+    if not usable_shape:
+        return closest_by_path(candidates, rel), "name"
+
+    arg_count = call_site["argCount"]
+    pool = [c for c in candidates
+            if _arity_matches(lookup.node_by_id.get(c[0], {}), arg_count)]
+    if not pool:
+        pool = candidates                      # nothing accepts this arity — keep all
+    if len(pool) == 1:
+        return pool[0][0], "arity"
+
+    arg_types = call_site.get("argTypes") or []
+    if any(t and t != "unknown" for t in arg_types):
+        best = pool[0]
+        best_score = _type_score(lookup.node_by_id.get(best[0], {}), arg_types)
+        tie_at_best = 1
+        for cand in pool[1:]:
+            score = _type_score(lookup.node_by_id.get(cand[0], {}), arg_types)
+            if score > best_score:
+                best, best_score, tie_at_best = cand, score, 1
+            elif score == best_score:
+                tie_at_best += 1
+        if best_score > 0 and tie_at_best == 1:
+            return best[0], "signature"
+
+    return closest_by_path(pool, rel), "name"
+
+
+def _walk_module(lookup: LookupMaps, alias_target: str, rest: str) -> list[tuple[str, str]]:
     """'user.User' with alias → file::models/__init__.py: consume submodule
     segments via module_map, then look up the symbol in the final file."""
     current_rel = alias_target[len("file::"):]
@@ -35,11 +130,11 @@ def _walk_module(lookup: LookupMaps, alias_target: str, rest: str) -> str | None
         current_rel, current_module = nxt, candidate
         consumed += 1
 
-    return _find_in_file(lookup, current_rel, ".".join(segments[consumed:]))
+    return _find_all_in_file(lookup, current_rel, ".".join(segments[consumed:]))
 
 
 def _resolve(called: str, node: dict, lookup: LookupMaps,
-             registry: ThirdPartyRegistry) -> str | None:
+             registry: ThirdPartyRegistry, call_site: dict | None) -> tuple[str | None, str]:
     rel = node["filePath"]
     symbols = lookup.symbol_maps.get(rel, {})
 
@@ -47,9 +142,9 @@ def _resolve(called: str, node: dict, lookup: LookupMaps,
     if called.startswith(("self.", "cls.")):
         parent_class = node["metadata"].get("parentClass")
         if parent_class:
-            return _find_in_file(lookup, rel,
-                                 f"{parent_class}.{called.split('.', 1)[1]}")
-        return None
+            return _pick(_find_all_in_file(lookup, rel, f"{parent_class}.{called.split('.', 1)[1]}"),
+                         node, call_site, lookup, rel)
+        return None, "name"
 
     # ── 2. dotted name ──
     if "." in called:
@@ -57,56 +152,62 @@ def _resolve(called: str, node: dict, lookup: LookupMaps,
 
         # 2a. ClassName.method defined in the same file
         if root in lookup.nodes_by_file.get(rel, {}):
-            return _find_in_file(lookup, rel, called)
+            return _pick(_find_all_in_file(lookup, rel, called),
+                         node, call_site, lookup, rel)
 
         # 2b. member access through an import alias
         alias_target = symbols.get(root)
         if not alias_target:
-            return None
+            return None, "name"
         if alias_target.startswith("[pip]/"):
             # third-party chain: requests.get → lazily create [pip]/requests::get
             pkg = alias_target.split("/", 1)[1]
             if "::" in pkg:
                 # chain root is already a named import — current_app.logger.info
                 # → [pip]/flask::current_app (the meaningful hop)
-                return alias_target
+                return alias_target, "name"
             member = registry.method_node(pkg, rest.split(".")[0])
-            return member["id"] if member else None
+            return (member["id"] if member else None), "name"
         if alias_target.startswith("file::"):
-            return _walk_module(lookup, alias_target, rest)
-        return None
+            return _pick(_walk_module(lookup, alias_target, rest),
+                         node, call_site, lookup, rel)
+        return None, "name"
 
-    # ── 3. plain name — global lookup, closest-by-path on collision ──
+    # ── 3. plain name — global lookup, overload ladder on collision ──
     candidates = lookup.nodes_by_name.get(called)
     if candidates:
-        if len(candidates) == 1:
-            return candidates[0][0]
-        return closest_by_path(candidates, rel)
+        return _pick(candidates, node, call_site, lookup, rel)
 
     # ── 4. import alias — refine file targets to the actual symbol ──
     alias_target = symbols.get(called)
     if alias_target:
         if alias_target.startswith("file::"):
-            return _find_in_file(lookup, alias_target[len("file::"):], called)
-        return alias_target   # "[pip]/..." or "path.py::Symbol"
-    return None
+            return _pick(_find_all_in_file(lookup, alias_target[len("file::"):], called),
+                         node, call_site, lookup, rel)
+        return alias_target, "name"   # "[pip]/..." or "path.py::Symbol"
+    return None, "name"
 
 
 def resolve_calls(lookup: LookupMaps, registry: ThirdPartyRegistry) -> list[dict]:
-    """Resolve every FUNCTION/METHOD node's calls → CALLS edges.
-    Also writes metadata.resolvedCalls back onto nodes (JS callEdges.ts mirror)."""
+    """Resolve every FUNCTION/METHOD node's call sites → CALLS edges.
+    Also writes metadata.resolvedCalls back onto nodes (JS callEdges.ts mirror).
+    Each (name, arity, argTypes) call site resolves separately — a caller that
+    invokes two overload siblings of one name gets two edges."""
     edges: list[dict] = []
 
     for node in lookup.node_by_id.values():
         if node["type"] not in ("FUNCTION", "METHOD"):
             continue
+        metadata = node["metadata"]
+        sites = metadata.get("callSites") or [{"name": c} for c in metadata.get("calls", [])]
         resolved: list[dict] = []
-        for called in node["metadata"].get("calls", []):
-            target = _resolve(called, node, lookup, registry)
+        for site in sites:
+            called = site["name"]
+            target, matched_by = _resolve(called, node, lookup, registry, site)
             if target and target != node["id"]:
                 edges.append({"from": node["id"], "to": target, "type": "CALLS",
-                              "metadata": {"calledName": called}})
+                              "metadata": {"calledName": called, "matchedBy": matched_by}})
                 resolved.append({"name": called, "nodeId": target})
-        node["metadata"]["resolvedCalls"] = resolved
+        metadata["resolvedCalls"] = resolved
 
     return edges

package/extractors/python/devlens_extractors_python/exports_map.py

@@ -0,0 +1,263 @@
+"""Exports Map — the flattened public surface of a Python repo.
+
+Mirrors the TypeScript reference (src/parser/exportsMap.ts) and the cross-repo
+design (docs/EXPORTS_MAP.md in devlens-engine). Every value is the FINAL,
+resolved nodeId as it appears in the nodes array — overload suffixes included.
+Consumers of the map never walk import chains.
+
+Python-specific concerns:
+  - The "door" is the package root __init__.py; the map key is the name an
+    importer sees (`from pkg import name`). Python has no package.json-style
+    subpaths, so single-package repos use "." and multi-package repos use
+    "./<pkgname>" per top-level package.
+  - __all__ (when present, plain list assignment) defines membership exactly;
+    otherwise public = non-underscore top-level bindings.
+  - `from .mod import name as alias` binds alias → the definition of `name`
+    (bindings tracked, never string-matched — name-swap safe).
+  - `from .mod import *` expands transitively with cycle guards; underscore
+    names stay excluded per Python semantics; explicit bindings always beat
+    star-collected ones, and a later star overrides an earlier star.
+  - Later bindings override earlier ones (Python semantics: last wins), so
+    duplicate imports resolve deterministically; ambiguousNames stays a
+    safety net that should remain empty for well-formed Python.
+  - Re-export chains through nested __init__.py files are followed
+    recursively; modules re-exported as values map to FILE nodes
+    (file::pkg/submod.py).
+  - Plain variables have no nodes → omitted (never fabricate an id).
+
+Output shape (camelCase, same as the TS extractor):
+    {"exports": {subpath: {name: [nodeId, ...]}},
+     "ambiguousNames": {subpath: [name, ...]}}
+"""
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+_NON_PACKAGE_DIRS = {"tests", "docs", "examples", "scripts", "benchmarks", "node_modules", ".venv", "venv", "build", "dist"}
+
+
+def build_exports_map(repo_path: str, parsed_files: list, lookup) -> dict | None:
+    try:
+        packages = _discover_packages(repo_path)
+        if not packages:
+            return None
+
+        exports: dict[str, dict[str, list[str]]] = {}
+        ambiguous: dict[str, list[str]] = {}
+        parsed_by_rel = {pf.rel_path: pf for pf in parsed_files}
+        single = len(packages) == 1
+
+        for pkg_name, init_rel in packages:
+            subpath = "." if single else f"./{pkg_name}"
+            per_path, amb = _package_surface(pkg_name, init_rel, parsed_by_rel, lookup)
+            if per_path:
+                exports[subpath] = per_path
+            if amb:
+                ambiguous[subpath] = amb
+
+        if not exports:
+            return None
+        return {"exports": exports, "ambiguousNames": ambiguous}
+    except Exception:
+        return None
+
+
+def _discover_packages(repo_path: str) -> list[tuple[str, str]]:
+    root = Path(repo_path)
+    found: list[tuple[str, str]] = []
+    for entry in sorted(root.iterdir()):
+        if not entry.is_dir() or entry.name.startswith(".") or entry.name in _NON_PACKAGE_DIRS:
+            continue
+        if (entry / "__init__.py").exists():
+            found.append((entry.name, f"{entry.name}/__init__.py"))
+    return found
+
+
+def _package_surface(pkg_name: str, init_rel: str, parsed_by_rel: dict, lookup):
+    init_pf = parsed_by_rel.get(init_rel)
+    if init_pf is None:
+        return {}, []
+
+    bindings, star_modules = _collect_bindings(init_pf, pkg_name, lookup.module_map)
+
+    star_names: dict[str, list[tuple[str, str, str]]] = {}
+    for module in star_modules:
+        per_star: dict[str, list[tuple[str, str, str]]] = {}
+        _expand_star(module, per_star, lookup, parsed_by_rel, set())
+        for name, entries in per_star.items():
+            star_names[name] = entries
+
+    for name, entries in star_names.items():
+        if name not in bindings:
+            bindings[name] = entries
+
+    per_path: dict[str, list[str]] = {}
+    ambiguous: list[str] = []
+
+    public = _public_names(init_pf)
+    for name in sorted(set(list(bindings.keys()) + public)):
+        if name.startswith("_"):
+            continue
+        targets = bindings.get(name, [])
+        resolved_ids: list[str] = []
+        definition_files: set[str] = set()
+        for kind, target, original in targets:
+            ids = _resolve_binding(kind, target, original, parsed_by_rel, lookup, set())
+            if ids:
+                resolved_ids.extend(ids)
+                definition_files.add(_definition_file(ids[0]))
+        if not resolved_ids:
+            continue
+        unique_ids = sorted(set(resolved_ids))
+        if len(definition_files) > 1:
+            ambiguous.append(name)
+        per_path[name] = unique_ids
+
+    return per_path, ambiguous
+
+
+def _collect_bindings(pf, pkg_name: str, module_map: dict[str, str]):
+    """One pass over a module's top-level statements → name → binding targets."""
+    bindings: dict[str, list[tuple[str, str, str]]] = {}
+    star_modules: list[str] = []
+
+    for stmt in pf.tree.body:
+        if isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            bindings[stmt.name] = [("def", pf.rel_path, stmt.name)]
+        elif isinstance(stmt, ast.ImportFrom):
+            module = _absolute_module(stmt, pf, pkg_name)
+            if module is None:
+                continue
+            for alias in stmt.names:
+                if alias.name == "*":
+                    if module not in star_modules:
+                        star_modules.append(module)
+                    continue
+                public_name = alias.asname or alias.name
+                bindings[public_name] = [("import", module, alias.name)]
+        elif isinstance(stmt, ast.Import):
+            for alias in stmt.names:
+                public_name = alias.asname or alias.name.split(".")[0]
+                module = alias.name if alias.asname else alias.name.split(".")[0]
+                leaf = module.split(".")[-1]
+                bindings[public_name] = [("import", module, leaf)]
+
+    return bindings, star_modules
+
+
+def _absolute_module(stmt: ast.ImportFrom, pf, pkg_name: str) -> str | None:
+    if stmt.level == 0:
+        return stmt.module or None
+    base_parts = pkg_name.split(".")
+    base_parts = base_parts[: max(0, len(base_parts) - (stmt.level - 1))]
+    base = ".".join(base_parts)
+    if not base:
+        return None
+    return f"{base}.{stmt.module}" if stmt.module else base
+
+
+def _expand_star(
+    module: str,
+    star_names: dict[str, list[tuple[str, str, str]]],
+    lookup,
+    parsed_by_rel: dict,
+    visited: set[str],
+):
+    if module in visited:
+        return
+    visited.add(module)
+
+    rel = lookup.module_map.get(module)
+    pf = parsed_by_rel.get(rel) if rel else None
+    if pf is None:
+        return
+
+    bindings, sub_stars = _collect_bindings(pf, module, lookup.module_map)
+    for sub in sub_stars:
+        _expand_star(sub, star_names, lookup, parsed_by_rel, visited)
+
+    for name, entries in bindings.items():
+        if name.startswith("_") or name == "__all__":
+            continue
+        bucket = star_names.setdefault(name, [])
+        for entry in entries:
+            if entry not in bucket:
+                bucket.append(entry)
+
+
+def _public_names(pf) -> list[str]:
+    for stmt in pf.tree.body:
+        if isinstance(stmt, ast.Assign):
+            for target in stmt.targets:
+                if isinstance(target, ast.Name) and target.id == "__all__":
+                    try:
+                        return [
+                            elt.value
+                            for elt in stmt.value.elts
+                            if isinstance(elt, ast.Constant) and isinstance(elt.value, str)
+                        ]
+                    except AttributeError:
+                        return []
+    return [n for n in _top_level_names(pf) if not n.startswith("_")]
+
+
+def _top_level_names(pf) -> list[str]:
+    names: list[str] = []
+    for stmt in pf.tree.body:
+        if isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            names.append(stmt.name)
+        elif isinstance(stmt, ast.Assign):
+            for target in stmt.targets:
+                if isinstance(target, ast.Name):
+                    names.append(target.id)
+        elif isinstance(stmt, ast.AnnAssign):
+            if isinstance(stmt.target, ast.Name):
+                names.append(stmt.target.id)
+        elif isinstance(stmt, (ast.ImportFrom, ast.Import)):
+            for alias in stmt.names:
+                if isinstance(stmt, ast.ImportFrom) and alias.name == "*":
+                    continue
+                names.append(alias.asname or alias.name.split(".")[0])
+    return names
+
+
+def _resolve_binding(kind, target, original, parsed_by_rel, lookup, visited) -> list[str]:
+    if kind == "def":
+        ids = lookup.nodes_by_file_all.get(target, {}).get(original, [])
+        return list(ids)
+
+    key = (target, original)
+    if key in visited:
+        return []
+    visited.add(key)
+
+    submodule = lookup.module_map.get(f"{target}.{original}")
+    if submodule:
+        return [f"file::{submodule}"]
+
+    rel = lookup.module_map.get(target)
+    if not rel:
+        return []
+
+    ids = lookup.nodes_by_file_all.get(rel, {}).get(original, [])
+    if ids:
+        return list(ids)
+
+    if rel.endswith("__init__.py"):
+        pf = parsed_by_rel.get(rel)
+        if pf is not None:
+            pkg = target
+            bindings, _ = _collect_bindings(pf, pkg, lookup.module_map)
+            for b_kind, b_target, b_original in bindings.get(original, []):
+                deeper = _resolve_binding(b_kind, b_target, b_original, parsed_by_rel, lookup, visited)
+                if deeper:
+                    return deeper
+
+    return [f"file::{rel}"]
+
+
+def _definition_file(node_id: str) -> str:
+    if node_id.startswith("file::"):
+        return node_id[len("file::"):]
+    return node_id.split("::")[0]

package/extractors/python/devlens_extractors_python/extractor.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 
 from . import edges, fingerprint, parser
 from .contract import ExtractorError, Stats
+from .exports_map import build_exports_map
 from .lookup import build_lookup_maps
 from .third_party import ThirdPartyRegistry
 
@@ -97,7 +98,9 @@ def extract(repo_path: str, options: dict) -> dict:
 
     stats = Stats(totalFiles=total_files, totalNodes=len(nodes), skippedFiles=skipped)
 
-    return {
+    exports_map = build_exports_map(repo_path, parsed_files, lookup)
+
+    result = {
         "fingerprint": fp.to_dict(),
         "nodes": nodes,
         "edges": edges_out,
@@ -105,3 +108,6 @@ def extract(repo_path: str, options: dict) -> dict:
         "stats": stats.to_dict(),
         "errors": errors,
     }
+    if exports_map is not None:
+        result["exports"] = exports_map
+    return result

package/extractors/python/devlens_extractors_python/lookup.py

@@ -20,6 +20,9 @@ class LookupMaps:
     nodes_by_name: dict[str, list[tuple[str, str]]] = field(default_factory=dict)
     # rel_path → {node name → node_id} — same-file / refinement lookups
     nodes_by_file: dict[str, dict[str, str]] = field(default_factory=dict)
+    # rel_path → {node name → [node_id]} — ALL same-name ids in the file
+    # (overload-aware call resolution; single map above keeps first-hit)
+    nodes_by_file_all: dict[str, dict[str, list[str]]] = field(default_factory=dict)
     # node_id → node dict — direct access to any parsed node
     node_by_id: dict[str, dict] = field(default_factory=dict)
     # rel_path → FILE/TEST node dict
@@ -47,11 +50,14 @@ def build_lookup_maps(parsed_files: list) -> LookupMaps:
         lookup.node_by_id[pf.file_node["id"]] = pf.file_node
 
         names: dict[str, str] = {}
+        names_all: dict[str, list[str]] = {}
         for n in pf.nodes:
             names.setdefault(n["name"], n["id"])
+            names_all.setdefault(n["name"], []).append(n["id"])
             lookup.node_by_id[n["id"]] = n
             lookup.nodes_by_name.setdefault(n["name"], []).append((n["id"], pf.rel_path))
         lookup.nodes_by_file[pf.rel_path] = names
+        lookup.nodes_by_file_all[pf.rel_path] = names_all
 
     return lookup
 

package/extractors/python/devlens_extractors_python/parser/__init__.py

@@ -13,6 +13,7 @@ from pathlib import Path
 from ..contract import code_hash, file_node
 from .classes import extract_class
 from .functions import extract_function
+from .overloads import apply_overload_disambiguation
 from .walker import is_test_file, walk_python_files
 
 class ParseError(Exception):
@@ -57,6 +58,11 @@ def parse_file(repo_path: str, rel_path: str) -> ParsedFile:
     end_line = len(source.splitlines()) or 1
     file_node_ = file_node(rel_path, end_line, node_type="TEST" if is_test else "FILE")
 
+    # Same-name defs in one file (shadowing) get arity/signature id suffixes;
+    # signature-identical duplicates collapse (mirrors the JS parser).
+    apply_overload_disambiguation(children, rel_path)
+    children = [c for c in children if not c["metadata"].get("isDuplicateOverload")]
+
     if is_test:
         # Test files are leaf nodes in the graph — children become testCases
         # metadata (mirrors the JS parser, which keeps test helpers out).