codemap-python 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

analysis/architecture/architecture_engine.py

@@ -2,6 +2,7 @@
 
 from collections import defaultdict
 from typing import Dict, Any, Optional, Set
+from analysis.graph.entrypoint_detector import detect_entry_points
 
 
 def _kind_for_fqn(fqn: str, repo_prefix: str) -> str:
@@ -52,6 +53,7 @@ def _infer_repo_prefix(nodes: Set[str]) -> str:
 def compute_architecture_metrics(
     callgraph,
     symbol_index,
+    repo_dir: Optional[str] = None,
     repo_prefix: Optional[str] = None,
     top_k: int = 25,
     fanout_threshold: int = 10,
@@ -134,6 +136,8 @@ def compute_architecture_metrics(
             "edges": int(edges_per_file.get(fp, 0)),
         }
 
+    entry_points = detect_entry_points(repo_dir=repo_dir, repo_prefix=prefix) if repo_dir else []
+
     return {
         "ok": True,
         "repo_prefix": prefix,
@@ -142,6 +146,7 @@ def compute_architecture_metrics(
             "dead_symbols": sorted(dead_symbols),
             "orchestrators": sorted(orchestrators),
             "critical_symbols": sorted(critical),
+            "entry_points": entry_points,
             "top_fan_in": top_fan_in,
             "top_fan_out": top_fan_out,
         },

analysis/call_graph/call_extractor.py

@@ -85,8 +85,11 @@ class FunctionCallVisitor(ast.NodeVisitor):
 def extract_function_calls(file_path):
     source = read_source_file(file_path)
     tree = parse_source_to_ast(source, file_path=file_path)
-
-    visitor = FunctionCallVisitor(file_path)
-    visitor.visit(tree)
-
-    return visitor.calls
+    return extract_function_calls_from_tree(tree, file_path)
+
+
+def extract_function_calls_from_tree(tree, file_path):
+    visitor = FunctionCallVisitor(file_path)
+    visitor.visit(tree)
+
+    return visitor.calls

analysis/core/import_extractor.py

@@ -3,43 +3,47 @@
 
 import ast
 from analysis.utils.bom_handler import read_source_file, parse_source_to_ast
-
-
+
+
+def extract_imports_from_tree(tree, file_path):
+    """Extract imports from an already-parsed AST tree."""
+    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
+
+
 def extract_imports(file_path):
     """Extract imports from a Python file with automatic encoding and BOM handling."""
     source = read_source_file(file_path)
     tree = parse_source_to_ast(source, file_path=file_path)
-    
-    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
+    return extract_imports_from_tree(tree, file_path)

analysis/explain/explain_runner.py

@@ -7,22 +7,24 @@ from typing import Optional, Dict, Any
 
 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
+
+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
+from analysis.utils.repo_walk import filter_skipped_dirs
+
+
+def collect_python_files(root_dir: str):
+    py_files = []
+    for root, dirs, files in os.walk(root_dir):
+        dirs[:] = filter_skipped_dirs(dirs)
+        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):
@@ -78,7 +80,11 @@ def merge_maps(dst: dict, src: dict):
         dst[k].update(src.get(k, {}))
 
 
-def run(repo_dir: Optional[str] = None, output_dir: Optional[str] = None) -> Dict[str, Any]:
+def run(
+    repo_dir: Optional[str] = None,
+    output_dir: Optional[str] = None,
+    symbol_snapshot: Optional[list] = None,
+) -> Dict[str, Any]:
     """
     Callable explain pipeline (Phase-5/6), suitable for CLI/VS Code.
 
@@ -114,23 +120,25 @@ def run(repo_dir: Optional[str] = None, output_dir: Optional[str] = None) -> Dic
     # 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))
+    # 3) Build symbol index + extractors across repo
+    symbol_index = SymbolIndex()
+    loaded_snapshot = False
+    if isinstance(symbol_snapshot, list) and symbol_snapshot:
+        symbol_index.load_snapshot(symbol_snapshot)
+        loaded_snapshot = True
+
+    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)
+        if not loaded_snapshot:
+            module_path = file_to_module(file_path, repo_dir)
+            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", {}))

analysis/explain/summary_generator.py

@@ -11,11 +11,14 @@ 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 _first_line(text: Optional[str]) -> Optional[str]:
+    if not text:
+        return None
+    stripped = text.strip()
+    if not stripped:
+        return None
+    line = stripped.splitlines()[0].strip()
+    return line or None
 
 
 def _humanize_name(name: str) -> str:

analysis/graph/entrypoint_detector.py

@@ -1 +1,217 @@
-# __main__, click/typer/argparse, etc.
+from __future__ import annotations
+
+import ast
+import os
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+from analysis.utils.bom_handler import read_and_parse_python_file
+from analysis.utils.repo_walk import filter_skipped_dirs
+
+
+_ROUTE_DECORATORS = {
+    "get",
+    "post",
+    "put",
+    "delete",
+    "patch",
+    "options",
+    "head",
+    "websocket",
+    "route",
+    "api_route",
+}
+
+_CLI_DECORATOR_SUFFIXES = {
+    ".command",
+    ".group",
+    ".callback",
+}
+
+
+def _collect_python_files(repo_dir: str) -> List[str]:
+    py_files: List[str] = []
+    for root, dirs, files in os.walk(repo_dir):
+        dirs[:] = filter_skipped_dirs(dirs)
+        for file_name in files:
+            if not file_name.endswith(".py"):
+                continue
+            if file_name.startswith("__") and file_name != "__main__.py":
+                continue
+            py_files.append(os.path.join(root, file_name))
+    return sorted(py_files)
+
+
+def _file_to_module(file_path: str, repo_root: str, repo_prefix: str) -> str:
+    rel = os.path.relpath(os.path.abspath(file_path), os.path.abspath(repo_root)).replace(os.sep, ".")
+    if rel.endswith(".py"):
+        rel = rel[:-3]
+    prefix = str(repo_prefix or os.path.basename(os.path.abspath(repo_root).rstrip("\\/"))).strip()
+    return f"{prefix}.{rel}" if prefix else rel
+
+
+def _dotted_name(node: ast.AST) -> str:
+    if isinstance(node, ast.Call):
+        return _dotted_name(node.func)
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        parent = _dotted_name(node.value)
+        return f"{parent}.{node.attr}" if parent else node.attr
+    return ""
+
+
+def _str_constant(node: Optional[ast.AST]) -> str:
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+    return ""
+
+
+def _main_guard(node: ast.AST) -> bool:
+    if not isinstance(node, ast.If):
+        return False
+    test = node.test
+    if not isinstance(test, ast.Compare) or len(test.ops) != 1 or len(test.comparators) != 1:
+        return False
+    left = test.left
+    right = test.comparators[0]
+    if not isinstance(test.ops[0], ast.Eq):
+        return False
+    return (
+        isinstance(left, ast.Name)
+        and left.id == "__name__"
+        and isinstance(right, ast.Constant)
+        and right.value == "__main__"
+    )
+
+
+class _EntryPointVisitor(ast.NodeVisitor):
+    def __init__(self, module: str, file_path: str):
+        self.module = module
+        self.file_path = file_path
+        self.class_stack: List[str] = []
+        self.entries: List[Dict[str, Any]] = []
+        self._seen: Set[Tuple[str, str, int]] = set()
+
+    def _fqn_for(self, name: str) -> str:
+        if self.class_stack:
+            return f"{self.module}.{'.'.join(self.class_stack)}.{name}"
+        return f"{self.module}.{name}"
+
+    def _add_entry(
+        self,
+        *,
+        kind: str,
+        title: str,
+        reason: str,
+        line: int,
+        fqn: Optional[str] = None,
+    ) -> None:
+        key = (str(kind), str(fqn or title), int(line or 1))
+        if key in self._seen:
+            return
+        self._seen.add(key)
+        self.entries.append(
+            {
+                "kind": kind,
+                "title": title,
+                "reason": reason,
+                "fqn": fqn or "",
+                "file": self.file_path,
+                "line": int(line or 1),
+            }
+        )
+
+    def _record_function_entrypoints(self, node: ast.AST, name: str, decorators: List[ast.AST]) -> None:
+        fqn = self._fqn_for(name)
+        for decorator in decorators:
+            dotted = _dotted_name(decorator)
+            if not dotted:
+                continue
+            last = dotted.split(".")[-1].lower()
+            if last in _ROUTE_DECORATORS:
+                path = ""
+                if isinstance(decorator, ast.Call) and decorator.args:
+                    path = _str_constant(decorator.args[0])
+                method_label = "Web route" if last in {"route", "api_route"} else last.upper()
+                title = f"{method_label} {path}".strip()
+                reason = "This function looks like a web request entry point."
+                self._add_entry(
+                    kind="api_route",
+                    title=title,
+                    reason=reason,
+                    line=getattr(node, "lineno", 1),
+                    fqn=fqn,
+                )
+            if any(dotted.endswith(suffix) for suffix in _CLI_DECORATOR_SUFFIXES) or dotted.startswith("click.") or dotted.startswith("typer."):
+                self._add_entry(
+                    kind="cli_command",
+                    title=f"CLI command: {name}",
+                    reason="This function looks like a command-line entry point.",
+                    line=getattr(node, "lineno", 1),
+                    fqn=fqn,
+                )
+
+        if not self.class_stack and name == "main":
+            self._add_entry(
+                kind="script_start",
+                title="Script start: main()",
+                reason="This is a common starting function for running the file directly.",
+                line=getattr(node, "lineno", 1),
+                fqn=fqn,
+            )
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        self.class_stack.append(node.name)
+        self.generic_visit(node)
+        self.class_stack.pop()
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        self._record_function_entrypoints(node, node.name, list(node.decorator_list or []))
+        self.generic_visit(node)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        self._record_function_entrypoints(node, node.name, list(node.decorator_list or []))
+        self.generic_visit(node)
+
+    def visit_If(self, node: ast.If) -> None:
+        if _main_guard(node):
+            module_fqn = f"{self.module}.<module>"
+            self._add_entry(
+                kind="script_start",
+                title="Run this file directly",
+                reason="This file has a __main__ block, so it can start execution directly.",
+                line=getattr(node, "lineno", 1),
+                fqn=module_fqn,
+            )
+            for child in ast.walk(node):
+                if isinstance(child, ast.Call) and isinstance(child.func, ast.Name):
+                    called_name = child.func.id
+                    if called_name:
+                        self._add_entry(
+                            kind="script_start",
+                            title=f"Script start: {called_name}()",
+                            reason="This function is called from the file's __main__ block.",
+                            line=getattr(child, "lineno", getattr(node, "lineno", 1)),
+                            fqn=f"{self.module}.{called_name}",
+                        )
+        self.generic_visit(node)
+
+
+def detect_entry_points(repo_dir: str, repo_prefix: str = "") -> List[Dict[str, Any]]:
+    repo_root = os.path.abspath(repo_dir)
+    prefix = str(repo_prefix or os.path.basename(repo_root.rstrip("\\/"))).strip()
+    rows: List[Dict[str, Any]] = []
+
+    for file_path in _collect_python_files(repo_root):
+        try:
+            tree = read_and_parse_python_file(file_path)
+        except Exception:
+            continue
+        module = _file_to_module(file_path, repo_root, prefix)
+        visitor = _EntryPointVisitor(module=module, file_path=file_path)
+        visitor.visit(tree)
+        rows.extend(visitor.entries)
+
+    order = {"api_route": 0, "cli_command": 1, "script_start": 2}
+    rows.sort(key=lambda item: (order.get(str(item.get("kind", "")), 99), str(item.get("file", "")), int(item.get("line", 1))))
+    return rows[:50]

analysis/runners/phase4_runner.py

@@ -5,25 +5,25 @@ from typing import Optional, Dict, Any, List
 
 import os
 import json
-from analysis.indexing.symbol_index import SymbolIndex
-from analysis.indexing.import_resolver import ImportResolver
-from analysis.call_graph.cross_file_resolver import CrossFileResolver
-from analysis.call_graph.call_extractor import extract_function_calls
-from analysis.core.import_extractor import extract_imports
-from analysis.graph.callgraph_index import build_caller_fqn
+from analysis.indexing.symbol_index import SymbolIndex
+from analysis.indexing.import_resolver import ImportResolver
+from analysis.call_graph.cross_file_resolver import CrossFileResolver
+from analysis.call_graph.call_extractor import extract_function_calls_from_tree
+from analysis.core.import_extractor import extract_imports_from_tree
+from analysis.graph.callgraph_index import build_caller_fqn
+from analysis.utils.repo_walk import filter_skipped_dirs
 
 
 PROJECT_ROOT = os.path.dirname(os.path.dirname(__file__))
 
 
-def collect_python_files(root_dir: str) -> List[str]:
-    ignore_dirs = {".git", "__pycache__", ".codemap_cache", "node_modules", ".venv", "venv"}
-    py_files: List[str] = []
-    for root, dirs, files in os.walk(root_dir):
-        dirs[:] = [d for d in dirs if d not in ignore_dirs]
-        for file in files:
-            if file.endswith(".py") and not file.startswith("__"):
-                py_files.append(os.path.join(root, file))
+def collect_python_files(root_dir: str) -> List[str]:
+    py_files: List[str] = []
+    for root, dirs, files in os.walk(root_dir):
+        dirs[:] = filter_skipped_dirs(dirs)
+        for file in files:
+            if file.endswith(".py") and not file.startswith("__"):
+                py_files.append(os.path.join(root, file))
     return py_files
 
 
@@ -75,25 +75,27 @@ def run(repo_dir: Optional[str] = None, output_dir: Optional[str] = None, force_
 
     os.makedirs(output_dir, exist_ok=True)
 
-    python_files = collect_python_files(repo_dir)
-    symbol_index = SymbolIndex()
-    file_module_map: Dict[str, str] = {}
-
-    for file_path in python_files:
-        module_path = file_to_module(file_path, repo_dir)
-        file_module_map[file_path] = module_path
-        tree = parse_ast(file_path)
-        symbol_index.index_file(tree, module_path, file_path)
-
-    import_resolver = ImportResolver(symbol_index)
-    for file_path in python_files:
-        module_path = file_module_map[file_path]
-        imports = extract_imports(file_path)
-        import_resolver.index_module_imports(module_path, imports)
-
-    all_calls = []
-    for file_path in python_files:
-        all_calls.extend(extract_function_calls(file_path))
+    python_files = collect_python_files(repo_dir)
+    symbol_index = SymbolIndex()
+    file_module_map: Dict[str, str] = {}
+    parsed_trees: Dict[str, Any] = {}
+
+    for file_path in python_files:
+        module_path = file_to_module(file_path, repo_dir)
+        file_module_map[file_path] = module_path
+        tree = parse_ast(file_path)
+        parsed_trees[file_path] = tree
+        symbol_index.index_file(tree, module_path, file_path)
+
+    import_resolver = ImportResolver(symbol_index)
+    for file_path in python_files:
+        module_path = file_module_map[file_path]
+        imports = extract_imports_from_tree(parsed_trees[file_path], file_path)
+        import_resolver.index_module_imports(module_path, imports)
+
+    all_calls = []
+    for file_path in python_files:
+        all_calls.extend(extract_function_calls_from_tree(parsed_trees[file_path], file_path))
 
     cross_resolver = CrossFileResolver(symbol_index, import_resolver)
     resolved_calls = []

analysis/utils/cache_manager.py

@@ -5,15 +5,15 @@ import json
 import os
 import shutil
 import tempfile
-from datetime import datetime, timezone
-from threading import RLock
-from typing import Any, Dict, List, Optional, Tuple
-
-from security_utils import redact_secrets
-
-_LOCK = RLock()
-_SENSITIVE_KEYS = ("api_key", "token", "authorization", "bearer", "basic", "secret", "password")
-_SKIP_DIRS = {".git", "__pycache__", ".codemap_cache", ".venv", "venv", "node_modules"}
+from datetime import datetime, timezone
+from threading import RLock
+from typing import Any, Dict, List, Optional, Tuple
+
+from analysis.utils.repo_walk import filter_skipped_dirs
+from security_utils import redact_secrets
+
+_LOCK = RLock()
+_SENSITIVE_KEYS = ("api_key", "token", "authorization", "bearer", "basic", "secret", "password")
 
 
 def _project_root() -> str:
@@ -195,14 +195,14 @@ def save_policy(policy: Dict[str, Any], base_dir: Optional[str] = None) -> Dict[
 
 def collect_fingerprints(repo_dir: str) -> Dict[str, Dict[str, int]]:
     repo_root = os.path.abspath(repo_dir)
-    out: Dict[str, Dict[str, int]] = {}
-    if not os.path.isdir(repo_root):
-        return out
-    for root, dirs, files in os.walk(repo_root):
-        dirs[:] = [d for d in dirs if d not in _SKIP_DIRS]
-        for name in files:
-            if not name.endswith(".py"):
-                continue
+    out: Dict[str, Dict[str, int]] = {}
+    if not os.path.isdir(repo_root):
+        return out
+    for root, dirs, files in os.walk(repo_root):
+        dirs[:] = filter_skipped_dirs(dirs)
+        for name in files:
+            if not name.endswith(".py"):
+                continue
             fp = os.path.join(root, name)
             try:
                 st = os.stat(fp)
@@ -250,16 +250,21 @@ def save_manifest(repo_dir: str, manifest: Dict[str, Any], base_dir: Optional[st
         _atomic_json_write(_manifest_path(repo_dir, base_dir), _scrub_payload(payload))
 
 
-def should_rebuild(repo_dir: str, analysis_version: str = "2.2", base_dir: Optional[str] = None) -> bool:
+def should_rebuild(
+    repo_dir: str,
+    analysis_version: str = "2.2",
+    base_dir: Optional[str] = None,
+    current_fingerprints: Optional[Dict[str, Any]] = None,
+) -> bool:
     manifest = load_manifest(repo_dir, base_dir=base_dir)
     if not manifest:
         return True
     if str(manifest.get("analysis_version", "") or "") != str(analysis_version or ""):
         return True
     previous = manifest.get("fingerprints", {}) if isinstance(manifest.get("fingerprints"), dict) else {}
-    current = collect_fingerprints(repo_dir)
-    delta = diff_fingerprints(previous, current)
-    return bool(delta.get("changed_count", 0))
+    current = current_fingerprints if isinstance(current_fingerprints, dict) else collect_fingerprints(repo_dir)
+    delta = diff_fingerprints(previous, current)
+    return bool(delta.get("changed_count", 0))
 
 
 def _default_metadata(repo_hash: str) -> Dict[str, Any]:

analysis/utils/repo_walk.py

@@ -0,0 +1,27 @@
+"""Shared repository walking rules for source analysis."""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+
+SKIP_DIR_NAMES = {
+    ".git",
+    "__pycache__",
+    ".codemap_cache",
+    ".venv",
+    "venv",
+    "env",
+    "ENV",
+    ".env",
+    "node_modules",
+    "site-packages",
+    "dist-packages",
+    ".tox",
+    ".nox",
+}
+
+
+def filter_skipped_dirs(dir_names: Iterable[str]) -> list[str]:
+    """Return directory names that should still be traversed."""
+    return [name for name in dir_names if name not in SKIP_DIR_NAMES]