codemap-python 0.1.0__py3-none-any.whl

analysis/call_graph/cross_file_resolver.py

@@ -0,0 +1,122 @@
+# Cross-file call resolution
+from typing import Optional
+
+from analysis.indexing.symbol_index import SymbolIndex, SymbolInfo, SymbolKind
+from analysis.indexing.import_resolver import ImportResolver, ResolvedImport
+
+
+class CrossFileResolver:
+    """
+    Resolves a function/method call to its exact SymbolInfo
+    using symbol index and import resolver.
+    """
+
+    def __init__(
+        self,
+        symbol_index: SymbolIndex,
+        import_resolver: ImportResolver
+    ):
+        self.symbol_index = symbol_index
+        self.import_resolver = import_resolver  # ✅ NOW ACTUALLY USED
+
+    # -------------------------------------------------
+    # Public API
+    # -------------------------------------------------
+    def resolve_call(
+        self,
+        call: dict,
+        current_module: str
+    ) -> Optional[SymbolInfo]:
+
+        callee = call["callee"]
+        obj = call.get("object")
+        class_name = call.get("class")
+
+        # 🔹 Get imports for this module
+        import_map = self.import_resolver.get_imports(current_module)
+
+        # 1️⃣ Method call on self
+        if obj == "self" and class_name:
+            symbol = self._resolve_method(
+                current_module, class_name, callee
+            )
+            if symbol:
+                return symbol
+
+        # 2️⃣ Local function
+        symbol = self._resolve_local_function(
+            current_module, callee
+        )
+        if symbol:
+            return symbol
+
+        # 3️⃣ Imported symbol (direct)
+        if callee in import_map:
+            symbol = self._resolve_imported_symbol(
+                import_map[callee]
+            )
+            if symbol:
+                return symbol
+
+        # 4️⃣ Imported module attribute
+        if obj and obj in import_map:
+            symbol = self._resolve_module_attribute(
+                import_map[obj], callee
+            )
+            if symbol:
+                return symbol
+
+        # 5️⃣ Built-in
+        import builtins 
+        if hasattr(builtins,callee):
+            return SymbolInfo(
+                name=callee,
+                qualified_name=callee,
+                kind=SymbolKind.BUILTIN,
+                module="builtins",
+                file_path="",
+                start_line=-1,
+                end_line=-1
+            )
+
+        return None
+
+    # -------------------------------------------------
+    # Helpers
+    # -------------------------------------------------
+
+    def _resolve_method(
+        self,
+        module: str,
+        class_name: str,
+        method_name: str
+    ) -> Optional[SymbolInfo]:
+        return self.symbol_index.get(
+            module, f"{class_name}.{method_name}"
+        )
+
+    def _resolve_local_function(
+        self,
+        module: str,
+        function_name: str
+    ) -> Optional[SymbolInfo]:
+        return self.symbol_index.get(module, function_name)
+
+    def _resolve_imported_symbol(
+        self,
+        resolved: ResolvedImport
+    ) -> Optional[SymbolInfo]:
+        if resolved.symbol:
+            return self.symbol_index.get(
+                resolved.module, resolved.symbol
+            )
+        return None
+
+    def _resolve_module_attribute(
+        self,
+        resolved: ResolvedImport,
+        attr: str
+    ) -> Optional[SymbolInfo]:
+        return self.symbol_index.get(
+            resolved.module, attr
+        )

analysis/call_graph/execution_tracker.py

@@ -0,0 +1 @@
+# Call stack + depth tracking

analysis/call_graph/flow_builder.py

@@ -0,0 +1 @@
+# Execution-ordered flow

analysis/call_graph/models.py

@@ -0,0 +1 @@
+# CallNode / CallEdge

analysis/core/__init__.py

@@ -0,0 +1 @@
+# Core analysis modules - Phase 1 & 2

analysis/core/ast_context.py

@@ -0,0 +1 @@
+# Shared AST symbol context

analysis/core/ast_parser.py

@@ -0,0 +1,8 @@
+# AST Parser Module
+import ast
+def parse_python_file(file_path):
+    with open(file_path, "r", encoding="utf-8") as f:
+        source = f.read()
+
+    return ast.parse(source)
+

analysis/core/class_extractor.py

@@ -0,0 +1,35 @@
+# Class Extractor Module
+import ast
+
+import ast
+
+def extract_classes(ast_tree, file_path):
+    classes = []
+
+    for node in ast.walk(ast_tree):
+        if isinstance(node, ast.ClassDef):
+            base_classes = []
+            methods = []
+
+            # Extract base classes
+            for base in node.bases:
+                if isinstance(base, ast.Name):
+                    base_classes.append(base.id)
+                elif isinstance(base, ast.Attribute):
+                    base_classes.append(base.attr)
+
+            # Extract methods inside class body
+            for item in node.body:
+                if isinstance(item, ast.FunctionDef):
+                    methods.append(item.name)
+
+            classes.append({
+                "name": node.name,
+                "file": file_path,
+                "start_line": node.lineno,
+                "end_line": node.end_lineno,
+                "base_classes": base_classes,
+                "methods": methods
+            })
+
+    return classes

analysis/core/function_extractor.py

@@ -0,0 +1,16 @@
+# Function Extractor Module
+import ast
+
+def extract_functions(ast_tree, file_path):
+    functions = []
+
+    for node in ast.walk(ast_tree):
+        if isinstance(node, ast.FunctionDef):
+            functions.append({
+                "fun_name": node.name,
+                "file_name": file_path,
+                "start_line": node.lineno,
+                "end_line": node.end_lineno
+            })
+
+    return functions

analysis/core/import_extractor.py

@@ -0,0 +1,43 @@
+# Import Extractor Module
+# analysis/import_extractor.py
+
+import ast
+
+def extract_imports(file_path):
+    with open(file_path, "r", encoding="utf-8") as f:
+        source = f.read()
+
+    tree = ast.parse(source)
+    imports = []
+
+    for node in ast.walk(tree):
+
+        # import module
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                imports.append({
+                    "type": "import",
+                    "module": alias.name,
+                    "name": None,
+                    "alias": alias.asname,
+                    "line": node.lineno,
+                    "file": file_path
+                })
+
+        # from module import name
+        elif isinstance(node, ast.ImportFrom):
+            module = node.module
+            level = node.level  # 0 = absolute, >0 = relative
+
+            for alias in node.names:
+                imports.append({
+                    "type": "from_import",
+                    "module": module,
+                    "name": alias.name,
+                    "alias": alias.asname,
+                    "level": level,
+                    "line": node.lineno,
+                    "file": file_path
+                })
+
+    return imports

analysis/explain/__init__.py

@@ -0,0 +1 @@
+# Explain package - Symbol documentation and analysis

analysis/explain/docstring_extractor.py

@@ -0,0 +1,45 @@
+# Get docstrings from AST
+# analysis/explain/docstring_extractor.py
+# Phase-5 Step-2.1: Extract module/class/function/method docstrings from AST
+
+import ast
+from typing import Dict, Optional
+
+
+def extract_docstrings(ast_tree: ast.AST) -> Dict[str, object]:
+    """
+    Extract docstrings from a parsed AST tree.
+
+    Returns:
+        {
+          "module": Optional[str],
+          "classes": Dict[str, Optional[str]],
+          "functions": Dict[str, Optional[str]],
+          "methods": Dict[str, Optional[str]]   # key = "ClassName.method"
+        }
+    """
+    result = {
+        "module": ast.get_docstring(ast_tree),
+        "classes": {},
+        "functions": {},
+        "methods": {},
+    }
+
+    # Only immediate children are needed for docstrings;
+    # ast.walk would include nested defs which we don't want for Phase-5.
+    for node in ast_tree.body:
+        # Top-level functions
+        if isinstance(node, ast.FunctionDef):
+            result["functions"][node.name] = ast.get_docstring(node)
+
+        # Classes
+        elif isinstance(node, ast.ClassDef):
+            result["classes"][node.name] = ast.get_docstring(node)
+
+            # Methods inside class
+            for item in node.body:
+                if isinstance(item, ast.FunctionDef):
+                    key = f"{node.name}.{item.name}"
+                    result["methods"][key] = ast.get_docstring(item)
+
+    return result

analysis/explain/explain_runner.py

@@ -0,0 +1,177 @@
+# Orchestrates per-symbol explain
+# analysis/explain/explain_runner.py
+
+from __future__ import annotations
+
+from typing import Optional, Dict, Any
+
+import ast
+import json
+import os
+
+from analysis.indexing.symbol_index import SymbolIndex, SymbolInfo
+from analysis.graph.callgraph_index import CallGraphIndex, CallSite
+from analysis.explain.docstring_extractor import extract_docstrings
+from analysis.explain.signature_extractor import extract_signatures
+from analysis.explain.return_analyzer import analyze_returns
+from analysis.explain.summary_generator import generate_symbol_summary
+
+
+def collect_python_files(root_dir: str):
+    py_files = []
+    for root, _, files in os.walk(root_dir):
+        for file in files:
+            if file.endswith(".py") and not file.startswith("__"):
+                py_files.append(os.path.join(root, file))
+    return py_files
+
+
+def parse_ast(file_path: str) -> ast.AST:
+    with open(file_path, "r", encoding="utf-8") as f:
+        return ast.parse(f.read())
+
+
+def file_to_module(file_path: str, repo_root: str) -> str:
+    repo_root = os.path.abspath(repo_root)
+    file_path = os.path.abspath(file_path)
+
+    rel = os.path.relpath(file_path, repo_root)
+    rel = rel.replace(os.sep, ".")
+    if rel.endswith(".py"):
+        rel = rel[:-3]
+
+    # Prefix with folder name so symbols don’t collide across repos
+    repo_name = os.path.basename(repo_root.rstrip("\\/"))
+    return f"{repo_name}.{rel}"
+
+
+
+def build_callgraph_from_resolved_calls_json(path: str) -> CallGraphIndex:
+    with open(path, "r", encoding="utf-8") as f:
+        resolved_calls = json.load(f)
+
+    idx = CallGraphIndex()
+    for c in resolved_calls:
+        idx.add_call(
+            CallSite(
+                caller_fqn=c["caller_fqn"],
+                callee_fqn=c.get("callee_fqn"),
+                callee_name=c.get("callee", "<unknown>"),
+                file=c.get("file", ""),
+                line=int(c.get("line", -1)),
+            )
+        )
+    return idx
+
+
+def symbol_fqn(sym: SymbolInfo) -> str:
+    return f"{sym.module}.{sym.qualified_name}"
+
+
+def merge_maps(dst: dict, src: dict):
+    """
+    Merge extractor outputs across files into single dicts.
+    """
+    dst["module"] = dst.get("module")
+    for k in ("classes", "functions", "methods"):
+        dst.setdefault(k, {})
+        dst[k].update(src.get(k, {}))
+
+
+def run(repo_dir: Optional[str] = None, output_dir: Optional[str] = None) -> Dict[str, Any]:
+    """
+    Callable explain pipeline (Phase-5/6), suitable for CLI/VS Code.
+
+    Args:
+        repo_dir: directory to analyze (default: analysis/testing_repo)
+        output_dir: directory to write outputs (default: analysis/output)
+
+    Returns:
+        {
+          "explain_path": ".../explain.json",
+          "symbols": <int>
+        }
+    """
+    analysis_root = os.path.dirname(os.path.dirname(__file__))  # /analysis
+
+    if repo_dir is None:
+        repo_dir = os.path.join(analysis_root, "testing_repo")
+
+    if output_dir is None:
+        output_dir = os.path.join(analysis_root, "output")
+
+    os.makedirs(output_dir, exist_ok=True)
+
+    resolved_calls_json = os.path.join(output_dir, "resolved_calls.json")
+    if not os.path.exists(resolved_calls_json):
+        raise FileNotFoundError(
+            f"Missing: {resolved_calls_json}\nRun Phase-4 first."
+        )
+
+    # 1) Load callgraph
+    callgraph = build_callgraph_from_resolved_calls_json(resolved_calls_json)
+
+    # 2) Collect repo python files
+    python_files = collect_python_files(repo_dir)
+
+    # 3) Build symbol index + extractors across repo
+    symbol_index = SymbolIndex()
+
+    repo_docstrings = {"module": None, "classes": {}, "functions": {}, "methods": {}}
+    repo_signatures = {"functions": {}, "methods": {}}
+    repo_returns = {"functions": {}, "methods": {}}
+
+    for file_path in python_files:
+        tree = parse_ast(file_path)
+        module_path = file_to_module(file_path, repo_dir)
+
+
+        # index symbols
+        symbol_index.index_file(tree, module_path, file_path)
+
+        # extract per-file and merge
+        merge_maps(repo_docstrings, extract_docstrings(tree))
+
+        sigs = extract_signatures(tree)
+        repo_signatures["functions"].update(sigs.get("functions", {}))
+        repo_signatures["methods"].update(sigs.get("methods", {}))
+
+        rets = analyze_returns(tree)
+        repo_returns["functions"].update(rets.get("functions", {}))
+        repo_returns["methods"].update(rets.get("methods", {}))
+
+    # 4) Generate summaries for all symbols
+    explain: Dict[str, dict] = {}
+
+    for sym in symbol_index.all_symbols():
+        fqn = symbol_fqn(sym)
+        explain[fqn] = generate_symbol_summary(
+            symbol_fqn=fqn,
+            symbol_info=sym,
+            docstrings=repo_docstrings,
+            signatures=repo_signatures,
+            returns=repo_returns,
+            callgraph=callgraph,
+        )
+
+    # 5) Save explain.json
+    explain_path = os.path.join(output_dir, "explain.json")
+    with open(explain_path, "w", encoding="utf-8") as f:
+        json.dump(explain, f, indent=2)
+
+    return {
+        "explain_path": explain_path,
+        "symbols": len(explain),
+    }
+
+
+def main():
+    print("\n=== Phase-5 Explain Runner ===\n")
+    result = run()
+    print(f"Saved: {result['explain_path']}")
+    print(f"Symbols explained: {result['symbols']}")
+    print("\n=== Phase-5 Step-6 Complete ===\n")
+
+
+if __name__ == "__main__":
+    main()

analysis/explain/repo_summary_generator.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Dict, List, Tuple
+
+
+def _load_json(path: str, default: Any) -> Any:
+    if not os.path.exists(path):
+        return default
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception:
+        return default
+
+
+def _save_json(path: str, payload: Dict[str, Any]) -> None:
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(payload, f, indent=2)
+
+
+def _short_loc(symbol_meta: Dict[str, Any]) -> Tuple[str, int]:
+    loc = symbol_meta.get("location", {}) if isinstance(symbol_meta.get("location"), dict) else {}
+    return str(loc.get("file", "") or ""), int(loc.get("start_line", 1) or 1)
+
+
+def build_repo_summary_context(repo_cache_dir: str) -> dict:
+    arch = _load_json(os.path.join(repo_cache_dir, "architecture_metrics.json"), {})
+    dep = _load_json(os.path.join(repo_cache_dir, "dependency_cycles.json"), {})
+    analysis = _load_json(os.path.join(repo_cache_dir, "analysis_metrics.json"), {})
+    tree = _load_json(os.path.join(repo_cache_dir, "project_tree.json"), {})
+    risk = _load_json(os.path.join(repo_cache_dir, "risk_radar.json"), {})
+
+    repo = arch.get("repo", {}) if isinstance(arch.get("repo"), dict) else {}
+    symbols = arch.get("symbols", {}) if isinstance(arch.get("symbols"), dict) else {}
+
+    orchestrators = [str(x) for x in (repo.get("orchestrators") or [])][:5]
+    critical = [str(x) for x in (repo.get("critical_symbols") or [])][:5]
+
+    def _shape(items: List[str]) -> List[Dict[str, Any]]:
+        out: List[Dict[str, Any]] = []
+        for fqn in items:
+            meta = symbols.get(fqn, {}) if isinstance(symbols.get(fqn), dict) else {}
+            file_path, line = _short_loc(meta)
+            out.append(
+                {
+                    "fqn": fqn,
+                    "in": int(meta.get("fan_in", 0) or 0),
+                    "out": int(meta.get("fan_out", 0) or 0),
+                    "file": file_path,
+                    "line": line,
+                }
+            )
+        return out
+
+    top_hotspots = risk.get("top_hotspots", []) if isinstance(risk.get("top_hotspots"), list) else []
+    return {
+        "repo_prefix": str(arch.get("repo_prefix", "") or ""),
+        "counts": {
+            "symbols": int(len(symbols)),
+            "calls": int(analysis.get("total_calls", 0) or 0),
+            "files": int(analysis.get("total_files", 0) or 0),
+            "unresolved_calls": int(analysis.get("unresolved_calls", 0) or 0),
+            "cycles_count": int(dep.get("cycle_count", 0) or 0),
+        },
+        "orchestrators": _shape(orchestrators),
+        "critical_apis": _shape(critical),
+        "dead_symbols": [str(x) for x in (repo.get("dead_symbols") or [])][:10],
+        "cycles": dep.get("cycles", [])[:5] if isinstance(dep.get("cycles"), list) else [],
+        "top_tree_entries": tree.get("children", [])[:10] if isinstance(tree, dict) else [],
+        "top_hotspots": top_hotspots[:5],
+    }
+
+
+def _normalize_summary(summary: Dict[str, Any]) -> Dict[str, Any]:
+    bullets = [str(x).strip() for x in (summary.get("bullets") or []) if str(x).strip()][:7]
+    one = str(summary.get("one_liner", "") or "").strip() or (bullets[0] if bullets else "Repository summary unavailable.")
+    notes = [str(x).strip() for x in (summary.get("notes") or []) if str(x).strip()][:5]
+    return {"one_liner": one[:180], "bullets": bullets, "notes": notes}
+
+
+def _deterministic_summary(context: Dict[str, Any]) -> Dict[str, Any]:
+    counts = context.get("counts", {}) if isinstance(context.get("counts"), dict) else {}
+    files = int(counts.get("files", 0) or 0)
+    symbols = int(counts.get("symbols", 0) or 0)
+    calls = int(counts.get("calls", 0) or 0)
+    cycles_count = int(counts.get("cycles_count", 0) or 0)
+    unresolved = int(counts.get("unresolved_calls", 0) or 0)
+    orchestrators = context.get("orchestrators", []) if isinstance(context.get("orchestrators"), list) else []
+    critical = context.get("critical_apis", []) if isinstance(context.get("critical_apis"), list) else []
+    dead = context.get("dead_symbols", []) if isinstance(context.get("dead_symbols"), list) else []
+    hotspots = context.get("top_hotspots", []) if isinstance(context.get("top_hotspots"), list) else []
+
+    top_orchestrators = [str(item.get("fqn", "") or "") for item in orchestrators[:3] if isinstance(item, dict)]
+    top_critical = [str(item.get("fqn", "") or "") for item in critical[:3] if isinstance(item, dict)]
+    top_hotspot_labels = []
+    for item in hotspots[:3]:
+        if isinstance(item, dict):
+            top_hotspot_labels.append(str(item.get("fqn") or item.get("file") or "").strip())
+        elif isinstance(item, str):
+            top_hotspot_labels.append(item)
+    one_liner = f"Scanned {files} files, indexed {symbols} symbols, and resolved {calls} calls."
+    bullets: List[str] = []
+    if top_orchestrators:
+        bullets.append("Top orchestrators: " + ", ".join(top_orchestrators))
+    if top_critical:
+        bullets.append("Critical APIs: " + ", ".join(top_critical))
+    bullets.append(f"Dependency cycles: {cycles_count}")
+    if top_hotspot_labels:
+        bullets.append("Hotspots: " + ", ".join(top_hotspot_labels))
+    if unresolved:
+        bullets.append(f"Unresolved calls: {unresolved}")
+    if dead:
+        bullets.append("Dead symbols: " + ", ".join([str(x) for x in dead[:3]]))
+    if not bullets:
+        bullets.append("No major hotspots detected from cached architecture artifacts.")
+    notes = []
+    if cycles_count:
+        notes.append("Break dependency cycles first to reduce architecture friction.")
+    if hotspots:
+        notes.append("Review top hotspots before making broad refactors.")
+    return _normalize_summary({"one_liner": one_liner, "bullets": bullets, "notes": notes})
+
+
+def generate_repo_summary(repo_cache_dir: str, llm_client=None) -> dict:
+    context = build_repo_summary_context(repo_cache_dir)
+    summary = _deterministic_summary(context)
+    payload = {
+        "ok": True,
+        "cached": False,
+        "provider": "deterministic",
+        "summary": summary,
+        "error": None,
+    }
+    _save_json(os.path.join(repo_cache_dir, "repo_summary.json"), payload)
+    return payload