codemap-python 0.1.0__py3-none-any.whl

analysis/explain/return_analyzer.py

@@ -0,0 +1,114 @@
+# Detect return patterns
+# analysis/explain/return_analyzer.py
+# Phase-5 Step-4.1: Analyze return statements from AST (static)
+
+import ast
+from typing import Any, Dict, Optional, Set, List
+
+
+def _safe_unparse(node: Optional[ast.AST]) -> Optional[str]:
+    if node is None:
+        return None
+    try:
+        return ast.unparse(node)
+    except Exception:
+        return None
+
+
+def _classify_return_value(value: Optional[ast.AST]) -> str:
+    """
+    Classify a return expression node into a simple category.
+    """
+    if value is None:
+        return "none"
+
+    # return None
+    if isinstance(value, ast.Constant) and value.value is None:
+        return "none"
+
+    # return 1 / "x" / True
+    if isinstance(value, ast.Constant):
+        return "constant"
+
+    # return x
+    if isinstance(value, ast.Name):
+        return "name"
+
+    # return obj.attr
+    if isinstance(value, ast.Attribute):
+        return "attribute"
+
+    # return foo(...) or obj.foo(...)
+    if isinstance(value, ast.Call):
+        return "call"
+
+    # Anything else: a+b, f-strings, comprehensions, etc.
+    return "expression"
+
+
+def _analyze_function_returns(fn: ast.FunctionDef) -> Dict[str, Any]:
+    return_nodes: List[ast.Return] = [
+        n for n in ast.walk(fn) if isinstance(n, ast.Return)
+    ]
+
+    kinds: Set[str] = set()
+    examples: List[str] = []
+
+    for r in return_nodes:
+        kind = _classify_return_value(r.value)
+        kinds.add(kind)
+
+        if len(examples) < 3:
+            if r.value is None:
+                examples.append("None")
+            else:
+                ex = _safe_unparse(r.value)
+                examples.append(ex if ex is not None else "<unparse_failed>")
+
+    # If there are no return statements, Python returns None implicitly
+    if not return_nodes:
+        return {
+            "has_return": False,
+            "returns_count": 0,
+            "return_kinds": ["none"],
+            "examples": [],
+        }
+
+    return {
+        "has_return": True,
+        "returns_count": len(return_nodes),
+        "return_kinds": sorted(kinds),
+        "examples": examples,
+    }
+
+
+def analyze_returns(ast_tree: ast.AST) -> Dict[str, Dict[str, Any]]:
+    """
+    Analyze returns for:
+      - top-level functions
+      - class methods
+
+    Returns:
+      {
+        "functions": { "func": return_info },
+        "methods": { "Class.method": return_info }
+      }
+    """
+    result: Dict[str, Dict[str, Any]] = {
+        "functions": {},
+        "methods": {},
+    }
+
+    for node in ast_tree.body:
+        # Top-level functions
+        if isinstance(node, ast.FunctionDef):
+            result["functions"][node.name] = _analyze_function_returns(node)
+
+        # Classes and methods
+        elif isinstance(node, ast.ClassDef):
+            for item in node.body:
+                if isinstance(item, ast.FunctionDef):
+                    key = f"{node.name}.{item.name}"
+                    result["methods"][key] = _analyze_function_returns(item)
+
+    return result

analysis/explain/risk_flags.py

@@ -0,0 +1 @@
+# IO/network/db/recursion/large loops

analysis/explain/signature_extractor.py

@@ -0,0 +1,104 @@
+# Args, defaults, *args/**kwargs
+
+# analysis/explain/signature_extractor.py
+# Phase-5 Step-3.1: Extract function/method signatures from AST
+
+import ast
+from typing import Any, Dict, Optional
+
+
+def _safe_unparse(node: Optional[ast.AST]) -> Optional[str]:
+    if node is None:
+        return None
+    try:
+        return ast.unparse(node)
+    except Exception:
+        return None
+
+
+def _extract_signature_dict(fn: ast.FunctionDef) -> Dict[str, Any]:
+    """
+    Extract a normalized signature dict from a FunctionDef node.
+    """
+    args = fn.args
+
+    # Positional-or-keyword parameters
+    pos_args = [a.arg for a in args.args]
+
+    # Keyword-only parameters
+    kwonly_args = [a.arg for a in args.kwonlyargs]
+
+    # *args / **kwargs
+    vararg = args.vararg.arg if args.vararg else None
+    kwarg = args.kwarg.arg if args.kwarg else None
+
+    # Defaults apply to the LAST N positional-or-keyword params
+    defaults_map: Dict[str, Optional[str]] = {}
+    if args.defaults:
+        default_values = [_safe_unparse(d) for d in args.defaults]
+        default_param_names = pos_args[-len(default_values):]
+        defaults_map = dict(zip(default_param_names, default_values))
+
+    # Keyword-only defaults map (kw_defaults aligns with kwonlyargs)
+    kwonly_defaults_map: Dict[str, Optional[str]] = {}
+    if args.kwonlyargs:
+        for name_node, def_node in zip(args.kwonlyargs, args.kw_defaults):
+            kwonly_defaults_map[name_node.arg] = _safe_unparse(def_node)
+
+    # Type annotations for params + return
+    annotations: Dict[str, Optional[str]] = {}
+    for a in args.args:
+        if a.annotation is not None:
+            annotations[a.arg] = _safe_unparse(a.annotation)
+    for a in args.kwonlyargs:
+        if a.annotation is not None:
+            annotations[a.arg] = _safe_unparse(a.annotation)
+    if args.vararg and args.vararg.annotation is not None:
+        annotations[f"*{args.vararg.arg}"] = _safe_unparse(args.vararg.annotation)
+    if args.kwarg and args.kwarg.annotation is not None:
+        annotations[f"**{args.kwarg.arg}"] = _safe_unparse(args.kwarg.annotation)
+
+    if fn.returns is not None:
+        annotations["return"] = _safe_unparse(fn.returns)
+
+    return {
+        "args": pos_args,
+        "defaults": defaults_map,
+        "kwonlyargs": kwonly_args,
+        "kwonly_defaults": kwonly_defaults_map,
+        "vararg": vararg,
+        "kwarg": kwarg,
+        "annotations": annotations,
+    }
+
+
+def extract_signatures(ast_tree: ast.AST) -> Dict[str, Dict[str, Any]]:
+    """
+    Extract signatures for:
+      - top-level functions
+      - class methods
+
+    Returns:
+      {
+        "functions": { "func": signature_dict },
+        "methods": { "Class.method": signature_dict }
+      }
+    """
+    result: Dict[str, Dict[str, Any]] = {
+        "functions": {},
+        "methods": {},
+    }
+
+    for node in ast_tree.body:
+        # Top-level functions
+        if isinstance(node, ast.FunctionDef):
+            result["functions"][node.name] = _extract_signature_dict(node)
+
+        # Classes and methods
+        elif isinstance(node, ast.ClassDef):
+            for item in node.body:
+                if isinstance(item, ast.FunctionDef):
+                    key = f"{node.name}.{item.name}"
+                    result["methods"][key] = _extract_signature_dict(item)
+
+    return result

analysis/explain/summary_generator.py

@@ -0,0 +1,282 @@
+# Heuristic summary (no LLM yet)
+# analysis/explain/summary_generator.py
+# Phase-5 Step-5.1: Heuristic summary generator (no LLM)
+
+from __future__ import annotations
+
+from collections import Counter
+from typing import Any, Dict, Optional, List
+
+from analysis.indexing.symbol_index import SymbolInfo
+from analysis.graph.callgraph_index import CallGraphIndex
+
+
+def _first_line(text: Optional[str]) -> Optional[str]:
+    if not text:
+        return None
+    line = text.strip().splitlines()[0].strip()
+    return line or None
+
+
+def _humanize_name(name: str) -> str:
+    # snake_case -> words
+    return name.replace("_", " ").strip()
+
+
+def _format_args(sig: Optional[dict]) -> str:
+    if not sig:
+        return "()"
+    args = sig.get("args", [])
+    vararg = sig.get("vararg")
+    kwonly = sig.get("kwonlyargs", [])
+    kwarg = sig.get("kwarg")
+
+    parts: List[str] = []
+    parts.extend(args)
+
+    if vararg:
+        parts.append(f"*{vararg}")
+
+    if kwonly:
+        # show marker for kw-only if not already implied by *args
+        if not vararg:
+            parts.append("*")
+        parts.extend(kwonly)
+
+    if kwarg:
+        parts.append(f"**{kwarg}")
+
+    return "(" + ", ".join(parts) + ")"
+
+
+def _return_phrase(ret_info: Optional[dict]) -> str:
+    if not ret_info:
+        return "Returns: unknown."
+
+    kinds = ret_info.get("return_kinds", [])
+    if kinds == ["none"]:
+        return "Returns: None."
+    if "call" in kinds:
+        return "Returns: result of a call."
+    if "expression" in kinds:
+        return "Returns: computed value."
+    if "name" in kinds:
+        return "Returns: a variable value."
+    if "constant" in kinds:
+        return "Returns: a constant."
+    if "attribute" in kinds:
+        return "Returns: an attribute value."
+    return "Returns: mixed/complex."
+
+
+def _tags_from_callees(callee_fqns: List[str]) -> List[str]:
+    tags: List[str] = []
+    if any(c == "builtins.print" for c in callee_fqns):
+        tags.append("io:print")
+    if any(c == "builtins.open" for c in callee_fqns):
+        tags.append("io:file")
+    if any("read" in c.lower() or "load" in c.lower() for c in callee_fqns):
+        tags.append("io:read")
+    if any("write" in c.lower() or "save" in c.lower() for c in callee_fqns):
+        tags.append("io:write")
+    return tags
+
+
+def _analyze_method_behavior(symbol_info: SymbolInfo, callee_fqns: List[str]) -> str:
+    """Analyze what a method does based on its callees and name patterns."""
+    name = symbol_info.name.lower()
+    
+    # Check for initialization patterns
+    if name in ("__init__", "init", "initialize", "setup"):
+        return "initializes the object"
+    
+    # Check for display/output patterns
+    if any(word in name for word in ["display", "show", "print", "render"]):
+        if any("print" in c for c in callee_fqns):
+            return "displays information to console"
+        return "displays information"
+    
+    # Check for data setting patterns
+    if any(word in name for word in ["set", "update", "assign", "configure"]):
+        return "sets or updates internal state"
+    
+    # Check for data retrieval patterns
+    if any(word in name for word in ["get", "fetch", "retrieve", "load"]):
+        return "retrieves or loads data"
+    
+    # Check for validation patterns
+    if any(word in name for word in ["validate", "check", "verify", "test"]):
+        return "validates or checks conditions"
+    
+    # Check for computation patterns
+    if any(word in name for word in ["calculate", "compute", "process", "transform"]):
+        return "performs calculations or transformations"
+    
+    # Check based on callees
+    if callee_fqns:
+        if any("display" in c.lower() or "show" in c.lower() for c in callee_fqns):
+            return "orchestrates display operations"
+        if any("save" in c.lower() or "write" in c.lower() for c in callee_fqns):
+            return "saves or persists data"
+    
+    return None
+
+
+def generate_symbol_summary(
+    symbol_fqn: str,
+    symbol_info: SymbolInfo,
+    docstrings: dict,
+    signatures: dict,
+    returns: dict,
+    callgraph: CallGraphIndex
+) -> Dict[str, Any]:
+    """
+    Generate a heuristic summary for one symbol.
+    """
+
+    # -------- Docstring lookup --------
+    doc: Optional[str] = None
+    if symbol_info.kind.value in ("method",):
+        # methods dict uses "Class.method"
+        key = symbol_info.qualified_name
+        doc = docstrings.get("methods", {}).get(key)
+    elif symbol_info.kind.value in ("function",):
+        key = symbol_info.name
+        doc = docstrings.get("functions", {}).get(key)
+    elif symbol_info.kind.value in ("class",):
+        key = symbol_info.name
+        doc = docstrings.get("classes", {}).get(key)
+
+    doc_first = _first_line(doc)
+
+    # -------- Signature lookup --------
+    sig: Optional[dict] = None
+    if symbol_info.kind.value == "method":
+        sig = signatures.get("methods", {}).get(symbol_info.qualified_name)
+    elif symbol_info.kind.value == "function":
+        sig = signatures.get("functions", {}).get(symbol_info.name)
+
+    args_str = _format_args(sig)
+
+    # -------- Returns lookup --------
+    ret_info: Optional[dict] = None
+    if symbol_info.kind.value == "method":
+        ret_info = returns.get("methods", {}).get(symbol_info.qualified_name)
+    elif symbol_info.kind.value == "function":
+        ret_info = returns.get("functions", {}).get(symbol_info.name)
+
+    # -------- Callgraph lookup --------
+    callees_sites = callgraph.callees_of(symbol_fqn)
+    callers_sites = callgraph.callers_of(symbol_fqn)
+
+    callee_fqns = [cs.callee_fqn for cs in callees_sites if cs.callee_fqn]
+    caller_fqns = [cs.caller_fqn for cs in callers_sites]
+
+    callee_counts = Counter(callee_fqns)
+
+    # -------- One-liner --------
+    if doc_first:
+        one_liner = doc_first
+    else:
+        # Try to infer behavior from method analysis
+        behavior = _analyze_method_behavior(symbol_info, callee_fqns)
+        
+        if behavior:
+            one_liner = f"{symbol_info.name}{args_str} {behavior}."
+        else:
+            # Heuristic verb phrase from name
+            name_phrase = _humanize_name(symbol_info.name)
+            if symbol_info.name.startswith("get_"):
+                verb = "gets"
+                rest = _humanize_name(symbol_info.name[4:])
+                one_liner = f"{symbol_info.name}{args_str} {verb} {rest}."
+            elif symbol_info.name.startswith("set_"):
+                verb = "sets"
+                rest = _humanize_name(symbol_info.name[4:])
+                one_liner = f"{symbol_info.name}{args_str} {verb} {rest}."
+            elif symbol_info.name.startswith("load_"):
+                verb = "loads"
+                rest = _humanize_name(symbol_info.name[5:])
+                one_liner = f"{symbol_info.name}{args_str} {verb} {rest}."
+            elif symbol_info.name.startswith("save_"):
+                verb = "saves"
+                rest = _humanize_name(symbol_info.name[5:])
+                one_liner = f"{symbol_info.name}{args_str} {verb} {rest}."
+            elif symbol_info.name.startswith("build_"):
+                verb = "builds"
+                rest = _humanize_name(symbol_info.name[6:])
+                one_liner = f"{symbol_info.name}{args_str} {verb} {rest}."
+            else:
+                one_liner = f"{symbol_info.name}{args_str} does work related to '{name_phrase}'."
+
+    # -------- Details --------
+    details: List[str] = []
+    
+    # Location info
+    if symbol_info.file_path and symbol_info.start_line > 0:
+        details.append(
+            f"Defined in {symbol_info.file_path}:{symbol_info.start_line}-{symbol_info.end_line}"
+        )
+    
+    # Signature details
+    if sig:
+        sig_parts = []
+        if sig.get("args"):
+            sig_parts.append(f"Parameters: {', '.join(sig['args'])}")
+        if sig.get("vararg"):
+            sig_parts.append(f"*args: {sig['vararg']}")
+        if sig.get("kwonlyargs"):
+            sig_parts.append(f"Keyword-only: {', '.join(sig['kwonlyargs'])}")
+        if sig.get("kwarg"):
+            sig_parts.append(f"**kwargs: {sig['kwarg']}")
+        if sig_parts:
+            details.append("Signature: " + "; ".join(sig_parts))
+    
+    # Caller info
+    if caller_fqns:
+        unique_callers = sorted(set(caller_fqns))
+        if len(unique_callers) <= 3:
+            details.append("Called by: " + ", ".join(unique_callers))
+        else:
+            details.append(f"Called by: {', '.join(unique_callers[:3])} and {len(unique_callers) - 3} more")
+    else:
+        details.append("Called by: (no callers found)")
+
+    # Callee info with better formatting
+    if callee_counts:
+        calls_list = []
+        for name, cnt in callee_counts.most_common(8):
+            short_name = name.split(".")[-1] if "." in name else name
+            if cnt > 1:
+                calls_list.append(f"{short_name}() x{cnt}")
+            else:
+                calls_list.append(f"{short_name}()")
+        details.append("Calls: " + ", ".join(calls_list))
+    else:
+        details.append("Calls: (no callees found)")
+
+    # Return info
+    ret_phrase = _return_phrase(ret_info)
+    if ret_info and ret_info.get("examples"):
+        examples = ret_info["examples"][:2]
+        ret_phrase += f" Examples: {', '.join(examples)}"
+    details.append(ret_phrase)
+
+    tags = _tags_from_callees(callee_fqns)
+
+
+    location = {
+        "file": symbol_info.file_path,
+        "start_line": symbol_info.start_line,
+        "end_line": symbol_info.end_line,
+    }
+
+
+
+    return {
+        "fqn": symbol_fqn,
+        "one_liner": one_liner,
+        "details": details,
+        "tags": tags,
+        "location":location,
+    }

analysis/graph/__init__.py

@@ -0,0 +1 @@
+# Graph package - Call graph indexing and analysis

analysis/graph/callgraph_index.py

@@ -0,0 +1,117 @@
+# Build caller->callees and reverse index
+# analysis/graph/callgraph_index.py
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import os
+from collections import Counter
+from typing import Dict, List, Optional, Set, Any
+
+
+@dataclass(frozen=True)
+class CallSite:
+    caller_fqn: str
+    callee_fqn: Optional[str]
+    callee_name: str
+    file: str
+    line: int
+
+
+class CallGraphIndex:
+    """Stores forward/reverse call indexes and unresolved call list."""
+
+    def __init__(self):
+        self._forward: Dict[str, List[CallSite]] = {}
+        self._reverse: Dict[str, List[CallSite]] = {}
+        self._unresolved: List[CallSite] = []
+
+    def add_call(self, callsite: CallSite) -> None:
+        self._forward.setdefault(callsite.caller_fqn, []).append(callsite)
+        if callsite.callee_fqn:
+            self._reverse.setdefault(callsite.callee_fqn, []).append(callsite)
+        else:
+            self._unresolved.append(callsite)
+
+    def callees_of(self, caller_fqn: str) -> List[CallSite]:
+        return self._forward.get(caller_fqn, [])
+
+    def callers_of(self, callee_fqn: str) -> List[CallSite]:
+        return self._reverse.get(callee_fqn, [])
+
+    def unresolved_calls(self) -> List[CallSite]:
+        return list(self._unresolved)
+
+    def all_callers(self) -> List[str]:
+        return sorted(self._forward.keys())
+
+    def all_callees(self) -> List[str]:
+        return sorted(self._reverse.keys())
+
+    def stats(self) -> dict:
+        return {
+            "unique_callers": len(self._forward),
+            "unique_callees": len(self._reverse),
+            "unresolved_calls": len(self._unresolved),
+            "total_calls": sum(len(v) for v in self._forward.values()),
+        }
+
+
+def build_caller_fqn(call: dict, current_module: str) -> str:
+    caller = call.get("caller", "<unknown>")
+    cls = call.get("class")
+    if cls:
+        return f"{current_module}.{cls}.{caller}"
+    return f"{current_module}.{caller}"
+
+
+def write_hub_metrics_from_resolved_calls(resolved_calls_path: str, output_path: Optional[str] = None) -> Dict[str, Any]:
+    """Compute simple repository call metrics from resolved_calls.json and optionally write to file."""
+    if not os.path.exists(resolved_calls_path):
+        raise FileNotFoundError(resolved_calls_path)
+
+    with open(resolved_calls_path, "r", encoding="utf-8") as f:
+        rows = json.load(f)
+    if not isinstance(rows, list):
+        rows = []
+
+    fan_in: Counter[str] = Counter()
+    fan_out: Counter[str] = Counter()
+    files: Set[str] = set()
+    unresolved = 0
+
+    for row in rows:
+        if not isinstance(row, dict):
+            continue
+        caller = str(row.get("caller_fqn", "") or "")
+        callee = str(row.get("callee_fqn", "") or "")
+        file_path = str(row.get("file", "") or "")
+        if file_path:
+            files.add(file_path)
+
+        if caller:
+            fan_out[caller] += 1
+        if callee:
+            fan_in[callee] += 1
+        else:
+            unresolved += 1
+
+    critical_apis = [{"fqn": fqn, "fan_in": cnt} for fqn, cnt in fan_in.most_common(25)]
+    orchestrators = [{"fqn": fqn, "fan_out": cnt} for fqn, cnt in fan_out.most_common(25)]
+
+    payload: Dict[str, Any] = {
+        "ok": True,
+        "total_calls": len(rows),
+        "unresolved_calls": unresolved,
+        "total_files": len(files),
+        "critical_apis": critical_apis,
+        "orchestrators": orchestrators,
+    }
+
+    if output_path:
+        os.makedirs(os.path.dirname(output_path), exist_ok=True)
+        with open(output_path, "w", encoding="utf-8") as f:
+            json.dump(payload, f, indent=2)
+
+    return payload

analysis/graph/entrypoint_detector.py

@@ -0,0 +1 @@
+# __main__, click/typer/argparse, etc.