cmap-core 0.1.0__py3-none-any.whl

cmap_core/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

cmap_core/__main__.py

@@ -0,0 +1,3 @@
+from .main import app
+
+app()

cmap_core/cmap_analyzer.py

@@ -0,0 +1,68 @@
+import ast
+from pathlib import Path
+from .cmap_models import Call, CodeMap, Import, Symbol
+
+class Analyzer(ast.NodeVisitor):
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        self.result = CodeMap()
+        self.scope: list[str] = []
+
+    @property
+    def current(self) -> str:
+        return ".".join(self.scope) or "<module>"
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        self._visit_function(node)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        self._visit_function(node)
+
+    def _visit_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        parent = self.current if self.scope else None
+        symbol_id = f"{self.path}:{'.'.join((*self.scope, node.name))}"
+        self.result.symbols.append(Symbol(symbol_id, node.name, "function", str(self.path), node.lineno, parent))
+        self.scope.append(node.name)
+        self.generic_visit(node)
+        self.scope.pop()
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        parent = self.current if self.scope else None
+        symbol_id = f"{self.path}:{'.'.join((*self.scope, node.name))}"
+        self.result.symbols.append(Symbol(symbol_id, node.name, "class", str(self.path), node.lineno, parent))
+        self.scope.append(node.name)
+        self.generic_visit(node)
+        self.scope.pop()
+
+    def visit_Call(self, node: ast.Call) -> None:
+        if isinstance(node.func, ast.Name):
+            callee = node.func.id
+        elif isinstance(node.func, ast.Attribute):
+            callee = ast.unparse(node.func)
+        else:
+            callee = ast.unparse(node.func)
+        self.result.calls.append(Call(self.current, callee, str(self.path), node.lineno))
+        self.generic_visit(node)
+
+    def visit_Import(self, node: ast.Import) -> None:
+        for alias in node.names:
+            self.result.imports.append(Import(alias.name, str(self.path), node.lineno))
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
+        module = "." * node.level + (node.module or "")
+        self.result.imports.append(Import(module, str(self.path), node.lineno))
+
+def analyze(path: Path) -> CodeMap:
+    from .cmap_ast import parse
+    analyzer = Analyzer(path)
+    analyzer.visit(parse(path))
+    return analyzer.result
+
+def analyze_paths(paths: list[Path]) -> CodeMap:
+    result = CodeMap()
+    for path in paths:
+        current = analyze(path)
+        result.symbols.extend(current.symbols)
+        result.calls.extend(current.calls)
+        result.imports.extend(current.imports)
+    return result

cmap_core/cmap_ast.py

@@ -0,0 +1,5 @@
+import ast
+from pathlib import Path
+
+def parse(path: Path) -> ast.Module:
+    return ast.parse(path.read_text(encoding="utf-8"), filename=str(path))

cmap_core/cmap_graph.py

@@ -0,0 +1,67 @@
+from collections import defaultdict
+from pathlib import Path
+from .cmap_models import CodeMap
+
+def callers(graph: CodeMap, target: str) -> list[str]:
+    return sorted({call.caller for call in graph.calls if call.callee == target})
+
+def callees(graph: CodeMap, target: str) -> list[str]:
+    return sorted({call.callee for call in graph.calls if call.caller == target})
+
+def dependencies(graph: CodeMap) -> dict[str, set[str]]:
+    result: dict[str, set[str]] = defaultdict(set)
+    for item in graph.imports:
+        result[item.file].add(item.module)
+    return dict(result)
+
+def _module_name(path: str, root: Path) -> str:
+    relative = Path(path).relative_to(root)
+    parts = list(relative.with_suffix("").parts)
+    if parts[-1] == "__init__":
+        parts.pop()
+    return ".".join(parts)
+
+def circular_dependencies(graph: CodeMap, root: Path) -> list[list[str]]:
+    files = {Path(symbol.file) for symbol in graph.symbols}
+    modules = {_module_name(str(path), root): path for path in files}
+    edges: dict[Path, set[Path]] = defaultdict(set)
+    for item in graph.imports:
+        source = Path(item.file)
+        for module, target in modules.items():
+            if item.module == module or item.module.startswith(f"{module}."):
+                edges[source].add(target)
+    visited: set[Path] = set()
+    stack: list[Path] = []
+    found: list[list[str]] = []
+
+    def visit(node: Path) -> None:
+        if node in stack:
+            cycle = stack[stack.index(node):] + [node]
+            names = [str(item) for item in cycle]
+            if names not in found:
+                found.append(names)
+            return
+        if node in visited:
+            return
+        visited.add(node)
+        stack.append(node)
+        for target in edges.get(node, ()):
+            visit(target)
+        stack.pop()
+
+    for node in files:
+        visit(node)
+    return found
+
+def trace(graph: CodeMap, target: str) -> list[tuple[str, str]]:
+    result: list[tuple[str, str]] = []
+    queue = [target]
+    seen = {target}
+    while queue:
+        current = queue.pop(0)
+        for callee in callees(graph, current):
+            result.append((current, callee))
+            if callee not in seen:
+                seen.add(callee)
+                queue.append(callee)
+    return result

cmap_core/cmap_models.py

@@ -0,0 +1,29 @@
+from dataclasses import dataclass, field
+
+@dataclass(frozen=True, slots=True)
+class Symbol:
+    id: str
+    name: str
+    kind: str
+    file: str
+    line: int
+    parent: str | None = None
+
+@dataclass(frozen=True, slots=True)
+class Call:
+    caller: str
+    callee: str
+    file: str
+    line: int
+
+@dataclass(frozen=True, slots=True)
+class Import:
+    module: str
+    file: str
+    line: int
+
+@dataclass(slots=True)
+class CodeMap:
+    symbols: list[Symbol] = field(default_factory=list)
+    calls: list[Call] = field(default_factory=list)
+    imports: list[Import] = field(default_factory=list)

cmap_core/cmap_render.py

@@ -0,0 +1,14 @@
+import json
+from dataclasses import asdict
+from .cmap_models import CodeMap
+
+def text(graph: CodeMap) -> str:
+    lines = [f"{symbol.kind} {symbol.name}  {symbol.file}:{symbol.line}" for symbol in graph.symbols]
+    if graph.calls:
+        lines += ["", "Calls", *[f"  {call.caller} -> {call.callee}" for call in graph.calls]]
+    if graph.imports:
+        lines += ["", "Imports", *[f"  {item.file} -> {item.module}" for item in graph.imports]]
+    return "\n".join(lines)
+
+def json_output(graph: CodeMap) -> str:
+    return json.dumps({"symbols": [asdict(item) for item in graph.symbols], "calls": [asdict(item) for item in graph.calls], "imports": [asdict(item) for item in graph.imports]}, indent=2)

cmap_core/cmap_scan.py

@@ -0,0 +1,6 @@
+from pathlib import Path
+
+def python_files(root: Path) -> list[Path]:
+    if root.is_file():
+        return [root] if root.suffix == ".py" else []
+    return sorted(path for path in root.rglob("*.py") if ".venv" not in path.parts and "__pycache__" not in path.parts)

cmap_core/main.py

@@ -0,0 +1,66 @@
+from pathlib import Path
+from typing import Annotated
+import json
+import typer
+from rich.console import Console
+from . import __version__
+from .cmap_analyzer import analyze_paths
+from .cmap_graph import callers, callees, circular_dependencies, dependencies, trace
+from .cmap_render import json_output, text
+from .cmap_scan import python_files
+
+app = typer.Typer(help="CMap — Code Map for Python.", no_args_is_help=True)
+console = Console()
+
+@app.command()
+def version() -> None:
+    """Show the CMap version."""
+    typer.echo(__version__)
+
+@app.command()
+def scan(path: Annotated[Path, typer.Argument(exists=True, readable=True)], json_mode: Annotated[bool, typer.Option("--json")] = False) -> None:
+    """Scan Python files and show their structure."""
+    graph = analyze_paths(python_files(path))
+    typer.echo(json_output(graph) if json_mode else text(graph))
+
+@app.command("trace")
+def trace_code(path: Annotated[Path, typer.Argument(exists=True, readable=True)], target: Annotated[str, typer.Argument()], json_mode: Annotated[bool, typer.Option("--json")] = False) -> None:
+    """Show the reachable calls from a function."""
+    graph = analyze_paths(python_files(path))
+    result = trace(graph, target)
+    typer.echo(json.dumps(result) if json_mode else "\n".join(f"{a} -> {b}" for a, b in result))
+
+@app.command("callers")
+def callers_code(path: Annotated[Path, typer.Argument(exists=True, readable=True)], target: Annotated[str, typer.Argument()]) -> None:
+    """Show callers of a function."""
+    graph = analyze_paths(python_files(path))
+    typer.echo("\n".join(callers(graph, target)))
+
+@app.command("callees")
+def callees_code(path: Annotated[Path, typer.Argument(exists=True, readable=True)], target: Annotated[str, typer.Argument()]) -> None:
+    """Show functions called by a function."""
+    graph = analyze_paths(python_files(path))
+    typer.echo("\n".join(callees(graph, target)))
+
+@app.command()
+def deps(path: Annotated[Path, typer.Argument(exists=True, readable=True)]) -> None:
+    """Show Python import dependencies."""
+    graph = analyze_paths(python_files(path))
+    for source, modules in dependencies(graph).items():
+        typer.echo(source)
+        for module in sorted(modules):
+            typer.echo(f"  -> {module}")
+
+@app.command()
+def circular(path: Annotated[Path, typer.Argument(exists=True, readable=True)]) -> None:
+    """Find circular local import dependencies."""
+    graph = analyze_paths(python_files(path))
+    cycles = circular_dependencies(graph)
+    if not cycles:
+        typer.echo("No circular dependencies found.")
+        return
+    for cycle in cycles:
+        typer.echo(" -> ".join(cycle))
+
+if __name__ == "__main__":
+    app()

cmap_core-0.1.0.dist-info/METADATA

@@ -0,0 +1,7 @@
+Metadata-Version: 2.5
+Name: cmap-core
+Version: 0.1.0
+Summary: Code Map: inspect Python code structure and relationships from the terminal.
+Requires-Python: >=3.12
+Requires-Dist: rich<15,>=13.9
+Requires-Dist: typer<1,>=0.16

cmap_core-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+cmap_core/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+cmap_core/__main__.py,sha256=6Hs2PV7EYc5Tid4g4OtcLXhqVHiNYTGzSBdoOnW2HXA,29
+cmap_core/cmap_analyzer.py,sha256=EcguGOqGG1hANNF1rmKHFApzWREWLm8Mz_YaZ4h-tEs,2599
+cmap_core/cmap_ast.py,sha256=SmHP-oHUQZXyBhUlTUKCAx8vYKsGbJgZWxi5hXLjMxo,149
+cmap_core/cmap_graph.py,sha256=16Lh9xP2guCkiSnTNgKMUD6SNIVPqEalBEAc6qll0p8,2292
+cmap_core/cmap_models.py,sha256=9X4zBqkPPZ0rBFNtI5wwA6gIfXyD9awRDsSqDigI2P8,597
+cmap_core/cmap_render.py,sha256=B3zgZB_RJkHOjRpjjn5QuIhlgZi8p55AuVEmoxlJb8E,704
+cmap_core/cmap_scan.py,sha256=fLLH8vUYKDQrBamdke1WhfyuoOhNASpqVc7SFIsYTOY,267
+cmap_core/main.py,sha256=rrLE4pnaZnh7jjpBpDt7Y8yoiQNYp0NMVDWmQvDRrZI,2697
+cmap_core-0.1.0.dist-info/METADATA,sha256=hvlZf9sjZZ_kecPsgZacdL8gLHdVX840VXG1AeZ9cWw,223
+cmap_core-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+cmap_core-0.1.0.dist-info/entry_points.txt,sha256=rlT_geTsrm10pMU0JPJCqyNAB520HwXGo2F_XWc7o5s,49
+cmap_core-0.1.0.dist-info/RECORD,,

cmap_core-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cmap_core-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cmap-core = cmap_core.main:app