codemap-python 0.1.5__tar.gz → 0.1.6__tar.gz

{codemap_python-0.1.5 → codemap_python-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codemap-python
-Version: 0.1.5
+Version: 0.1.6
 Summary: Local Python code analysis tool - understand architecture, dependencies, and call graphs
 Author-email: ADITYA <aditykushwaha69@gmail.com>
 License-Expression: MIT

{codemap_python-0.1.5 → codemap_python-0.1.6}/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,
         },

codemap_python-0.1.6/analysis/graph/entrypoint_detector.py

@@ -0,0 +1,217 @@
+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]

{codemap_python-0.1.5 → codemap_python-0.1.6}/codemap_app.py

@@ -1410,12 +1410,13 @@ def api_analyze(args) -> int:
             if symbol_snapshot:
                 symbol_index.load_snapshot(symbol_snapshot)
 
-            repo_prefix = os.path.basename(os.path.abspath(repo_dir).rstrip("\\/"))
-            arch_payload = compute_architecture_metrics(
-                callgraph=callgraph,
-                symbol_index=symbol_index,
-                repo_prefix=repo_prefix,
-            )
+            repo_prefix = os.path.basename(os.path.abspath(repo_dir).rstrip("\\/"))
+            arch_payload = compute_architecture_metrics(
+                callgraph=callgraph,
+                symbol_index=symbol_index,
+                repo_dir=repo_dir,
+                repo_prefix=repo_prefix,
+            )
             dep_payload = compute_dependency_cycle_metrics(
                 resolved_calls=resolved_calls,
                 repo_prefix=repo_prefix,

{codemap_python-0.1.5 → codemap_python-0.1.6}/codemap_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codemap-python
-Version: 0.1.5
+Version: 0.1.6
 Summary: Local Python code analysis tool - understand architecture, dependencies, and call graphs
 Author-email: ADITYA <aditykushwaha69@gmail.com>
 License-Expression: MIT

{codemap_python-0.1.5 → codemap_python-0.1.6}/codemap_python.egg-info/SOURCES.txt

@@ -59,6 +59,7 @@ tests/test_cache_cli_commands.py
 tests/test_cache_retention.py
 tests/test_cli_invalid_escape_warnings.py
 tests/test_codemap_cli_entrypoint.py
+tests/test_entrypoint_detector.py
 tests/test_explain_runner_collection.py
 tests/test_no_key_persistence.py
 tests/test_registry_session_mode.py

{codemap_python-0.1.5 → codemap_python-0.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codemap-python"
-version = "0.1.5"
+version = "0.1.6"
 description = "Local Python code analysis tool - understand architecture, dependencies, and call graphs"
 readme = "README.md"
 requires-python = ">=3.10"

codemap_python-0.1.6/tests/test_entrypoint_detector.py

@@ -0,0 +1,60 @@
+import os
+import shutil
+import unittest
+
+from analysis.graph.entrypoint_detector import detect_entry_points
+
+
+PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+
+
+class TestEntrypointDetector(unittest.TestCase):
+    def test_detects_routes_cli_and_script_starts(self):
+        repo_dir = os.path.join(PROJECT_ROOT, "tests", "_tmp_entrypoint_repo")
+        shutil.rmtree(repo_dir, ignore_errors=True)
+        try:
+            os.makedirs(os.path.join(repo_dir, "api"), exist_ok=True)
+            os.makedirs(os.path.join(repo_dir, "cli"), exist_ok=True)
+
+            with open(os.path.join(repo_dir, "api", "routes.py"), "w", encoding="utf-8") as f:
+                f.write(
+                    "from fastapi import APIRouter\n"
+                    "router = APIRouter()\n\n"
+                    "@router.get('/items')\n"
+                    "def list_items():\n"
+                    "    return []\n"
+                )
+
+            with open(os.path.join(repo_dir, "cli", "commands.py"), "w", encoding="utf-8") as f:
+                f.write(
+                    "import click\n\n"
+                    "@click.command()\n"
+                    "def run():\n"
+                    "    return 1\n"
+                )
+
+            with open(os.path.join(repo_dir, "__main__.py"), "w", encoding="utf-8") as f:
+                f.write(
+                    "def main():\n"
+                    "    return 42\n\n"
+                    "if __name__ == '__main__':\n"
+                    "    main()\n"
+                )
+
+            rows = detect_entry_points(repo_dir, repo_prefix="demo_repo")
+            kinds = [row["kind"] for row in rows]
+            titles = [row["title"] for row in rows]
+
+            self.assertIn("api_route", kinds)
+            self.assertIn("cli_command", kinds)
+            self.assertIn("script_start", kinds)
+            self.assertIn("GET /items", titles)
+            self.assertIn("CLI command: run", titles)
+            self.assertIn("Run this file directly", titles)
+            self.assertIn("Script start: main()", titles)
+        finally:
+            shutil.rmtree(repo_dir, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    unittest.main()

{codemap_python-0.1.5 → codemap_python-0.1.6}/ui/app.py

@@ -77,8 +77,9 @@ templates = Jinja2Templates(directory=templates_dir)
 # This avoids issues when Jinja2 tries to cache templates containing the Request context
 templates.env.cache = NoCache()
 app.mount("/static", StaticFiles(directory=os.path.join(os.path.dirname(__file__), "static")), name="static")
-SEARCH_INDEX_CACHE: Dict[str, List[Dict[str, Any]]] = {}
-GRAPH_INDEX_CACHE: Dict[str, Dict[str, Any]] = {}
+SEARCH_INDEX_CACHE: Dict[str, List[Dict[str, Any]]] = {}
+GRAPH_INDEX_CACHE: Dict[str, Dict[str, Any]] = {}
+REPO_DATA_CACHE: Dict[str, Dict[str, Any]] = {}
 
 
 def _load_json(path: str, default: Any) -> Any:
@@ -582,10 +583,20 @@ def _rel_file(ctx: Dict[str, str], file_path: str) -> str:
     return file_path.replace("\\", "/")
 
 
-def _load_repo_data(ctx: Dict[str, str]) -> Dict[str, Any]:
-    explain = _load_json(ctx["explain_path"], {})
-    resolved_calls = _load_json(ctx["resolved_calls_path"], [])
-    return {"explain": explain, "resolved_calls": resolved_calls}
+def _load_repo_data(ctx: Dict[str, str]) -> Dict[str, Any]:
+    cache_key = ctx["repo_hash"]
+    explain_mtime = os.path.getmtime(ctx["explain_path"]) if os.path.exists(ctx["explain_path"]) else -1
+    resolved_mtime = os.path.getmtime(ctx["resolved_calls_path"]) if os.path.exists(ctx["resolved_calls_path"]) else -1
+    signature = f"{explain_mtime}:{resolved_mtime}"
+    cached = REPO_DATA_CACHE.get(cache_key)
+    if cached and cached.get("signature") == signature:
+        return cached["data"]
+
+    explain = _load_json(ctx["explain_path"], {})
+    resolved_calls = _load_json(ctx["resolved_calls_path"], [])
+    data = {"explain": explain, "resolved_calls": resolved_calls}
+    REPO_DATA_CACHE[cache_key] = {"signature": signature, "data": data}
+    return data
 
 
 def _repo_registry_data() -> List[Dict[str, Any]]:
@@ -628,41 +639,20 @@ def _repo_registry_data() -> List[Dict[str, Any]]:
     return items
 
 
-def _build_symbol_connections(
-    ctx: Dict[str, str],
-    fqn: str,
-    explain: Dict[str, Any],
-    resolved_calls: List[Dict[str, Any]],
-) -> Dict[str, Any]:
-    called_by: List[Dict[str, Any]] = []
-    used_in: List[Dict[str, Any]] = []
-    calls_counter: Counter[str] = Counter()
-
-    for call in resolved_calls:
-        caller_fqn = call.get("caller_fqn")
-        callee_fqn = call.get("callee_fqn")
-        file_path = call.get("file", "")
-        line = int(call.get("line", -1))
-
-        if callee_fqn == fqn:
-            item = {
-                "fqn": caller_fqn,
-                "file": _rel_file(ctx, file_path),
-                "line": line,
-            }
-            called_by.append(item)
-            used_in.append(item)
-
-        if caller_fqn == fqn and callee_fqn:
-            calls_counter[callee_fqn] += 1
-
-    called_by.sort(key=lambda x: (x.get("file", ""), int(x.get("line", -1)), x.get("fqn", "")))
-    used_in.sort(key=lambda x: (x.get("file", ""), int(x.get("line", -1)), x.get("fqn", "")))
-
-    calls: List[Dict[str, Any]] = []
-    for callee_fqn, count in sorted(calls_counter.items(), key=lambda x: (x[0].lower(), x[1])):
-        parts = callee_fqn.split(".")
-        if len(parts) >= 2 and parts[-2][:1].isupper():
+def _build_symbol_connections(
+    ctx: Dict[str, str],
+    fqn: str,
+    explain: Dict[str, Any],
+    graph_index: Dict[str, Any],
+) -> Dict[str, Any]:
+    called_by = list(graph_index.get("called_by_map", {}).get(fqn, []))
+    used_in = list(called_by)
+    calls_counter: Counter[str] = graph_index.get("outgoing_counts_map", {}).get(fqn, Counter())
+
+    calls: List[Dict[str, Any]] = []
+    for callee_fqn, count in sorted(calls_counter.items(), key=lambda x: (x[0].lower(), x[1])):
+        parts = callee_fqn.split(".")
+        if len(parts) >= 2 and parts[-2][:1].isupper():
             name = f"{parts[-2]}.{parts[-1]}"
         else:
             name = parts[-1]
@@ -833,7 +823,7 @@ def _analysis_version_from_cache(cache_dir: str) -> str:
     return ""
 
 
-def _build_graph_index(ctx: Dict[str, str]) -> Dict[str, Any]:
+def _build_graph_index(ctx: Dict[str, str]) -> Dict[str, Any]:
     cache_key = ctx["repo_hash"]
     resolved_mtime = os.path.getmtime(ctx["resolved_calls_path"]) if os.path.exists(ctx["resolved_calls_path"]) else -1
     explain_mtime = os.path.getmtime(ctx["explain_path"]) if os.path.exists(ctx["explain_path"]) else -1
@@ -843,35 +833,51 @@ def _build_graph_index(ctx: Dict[str, str]) -> Dict[str, Any]:
     if cached and cached.get("signature") == signature:
         return cached["index"]
 
-    explain = _load_json(ctx["explain_path"], {})
-    resolved_calls = _load_json(ctx["resolved_calls_path"], [])
-
-    callees_map: Dict[str, List[str]] = {}
-    callers_map: Dict[str, List[str]] = {}
-    edge_counts: Dict[tuple, int] = {}
-
-    for call in resolved_calls:
-        caller = call.get("caller_fqn")
-        if not caller:
-            continue
+    repo_data = _load_repo_data(ctx)
+    explain = repo_data["explain"]
+    resolved_calls = repo_data["resolved_calls"]
+
+    callees_map: Dict[str, List[str]] = {}
+    callers_map: Dict[str, List[str]] = {}
+    edge_counts: Dict[tuple, int] = {}
+    called_by_map: Dict[str, List[Dict[str, Any]]] = {}
+    outgoing_counts_map: Dict[str, Counter[str]] = {}
+
+    for call in resolved_calls:
+        caller = call.get("caller_fqn")
+        if not caller:
+            continue
         callee = call.get("callee_fqn")
         if not callee:
             raw_name = str(call.get("callee") or "<unknown>").strip()
             callee = f"external::{raw_name}"
-
-        callees_map.setdefault(caller, []).append(callee)
-        callers_map.setdefault(callee, []).append(caller)
-        edge_key = (caller, callee)
-        edge_counts[edge_key] = edge_counts.get(edge_key, 0) + 1
-
-    index = {
-        "explain": explain,
-        "callees_map": callees_map,
-        "callers_map": callers_map,
-        "edge_counts": edge_counts,
-    }
-    GRAPH_INDEX_CACHE[cache_key] = {"signature": signature, "index": index}
-    return index
+
+        callees_map.setdefault(caller, []).append(callee)
+        callers_map.setdefault(callee, []).append(caller)
+        edge_key = (caller, callee)
+        edge_counts[edge_key] = edge_counts.get(edge_key, 0) + 1
+        outgoing_counts_map.setdefault(caller, Counter())[callee] += 1
+        called_by_map.setdefault(callee, []).append(
+            {
+                "fqn": caller,
+                "file": _rel_file(ctx, call.get("file", "")),
+                "line": int(call.get("line", -1)),
+            }
+        )
+
+    for rows in called_by_map.values():
+        rows.sort(key=lambda x: (x.get("file", ""), int(x.get("line", -1)), x.get("fqn", "")))
+
+    index = {
+        "explain": explain,
+        "callees_map": callees_map,
+        "callers_map": callers_map,
+        "edge_counts": edge_counts,
+        "called_by_map": called_by_map,
+        "outgoing_counts_map": outgoing_counts_map,
+    }
+    GRAPH_INDEX_CACHE[cache_key] = {"signature": signature, "index": index}
+    return index
 
 
 def _normalize_ui_state(state: Dict[str, Any]) -> Dict[str, Any]:
@@ -1949,21 +1955,21 @@ def api_file(path: str = Query(...), repo: Optional[str] = Query(default=None)):
 
 
 @app.get("/api/symbol")
-def api_symbol(fqn: str = Query(...), repo: Optional[str] = Query(default=None)):
+def api_symbol(fqn: str = Query(...), repo: Optional[str] = Query(default=None)):
     ctx = _repo_ctx(repo) if repo else _active_repo_ctx()
     if not ctx:
         return _no_active_repo_response()
     if not _has_analysis_cache(ctx):
         return _missing_cache_response()
 
-    explain = _load_json(ctx["explain_path"], {})
-    obj = explain.get(fqn)
-    if not obj:
-        return JSONResponse(status_code=404, content={"ok": False, "error": "NOT_FOUND", "fqn": fqn})
-    resolved_calls = _load_json(ctx["resolved_calls_path"], [])
-    result = dict(obj)
-    result["connections"] = _build_symbol_connections(ctx, fqn, explain, resolved_calls)
-    return {"ok": True, "result": result}
+    graph_index = _build_graph_index(ctx)
+    explain = graph_index["explain"]
+    obj = explain.get(fqn)
+    if not obj:
+        return JSONResponse(status_code=404, content={"ok": False, "error": "NOT_FOUND", "fqn": fqn})
+    result = dict(obj)
+    result["connections"] = _build_symbol_connections(ctx, fqn, explain, graph_index)
+    return {"ok": True, "result": result}
 
 
 @app.get("/api/usages")