codezoom 0.1.0.dev0__py3-none-any.whl

codezoom/__init__.py

@@ -0,0 +1 @@
+"""codezoom — Multi-level code structure explorer."""

codezoom/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m codezoom`."""
+
+from codezoom.cli import main
+
+main()

codezoom/cli.py

@@ -0,0 +1,47 @@
+"""Command-line interface for codezoom."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from codezoom.pipeline import run
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="codezoom",
+        description="Multi-level code structure explorer — interactive drill-down HTML visualizations.",
+    )
+    parser.add_argument(
+        "project_dir",
+        type=Path,
+        help="Path to the project to visualize",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        default=None,
+        help="Output HTML file path (default: <project>_deps.html)",
+    )
+    parser.add_argument(
+        "--name",
+        default=None,
+        help="Project display name (default: auto-detect from pyproject.toml)",
+    )
+    parser.add_argument(
+        "--open",
+        action="store_true",
+        dest="open_browser",
+        help="Open the generated HTML in a browser",
+    )
+
+    args = parser.parse_args(argv)
+
+    run(
+        args.project_dir,
+        output=args.output,
+        name=args.name,
+        open_browser=args.open_browser,
+    )

codezoom/detect.py

@@ -0,0 +1,58 @@
+"""Auto-detect project type and return appropriate extractors."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from codezoom.extractors.base import Extractor
+from codezoom.extractors.python.ast_symbols import AstSymbolsExtractor
+from codezoom.extractors.python.module_hierarchy import ModuleHierarchyExtractor
+from codezoom.extractors.python.package_deps import PackageDepsExtractor
+
+
+def detect_extractors(project_dir: Path, project_name: str) -> list[Extractor]:
+    """Return an ordered list of extractors applicable to *project_dir*."""
+    extractors: list[Extractor] = []
+
+    if (project_dir / "pyproject.toml").exists():
+        # Read optional codezoom config
+        exclude = _read_config_exclude(project_dir, project_name)
+        extractors.append(PackageDepsExtractor())
+        extractors.append(ModuleHierarchyExtractor(exclude=exclude))
+        extractors.append(AstSymbolsExtractor())
+
+    if (project_dir / "pom.xml").exists() or (project_dir / "build.gradle").exists():
+        print(
+            "Note: Java project detected — Java support coming soon.",
+            file=sys.stderr,
+        )
+
+    return extractors
+
+
+def _read_config_exclude(project_dir: Path, project_name: str) -> list[str] | None:
+    """Read pydeps exclude list from .codezoom.toml or pyproject.toml."""
+    import tomllib
+
+    # Try .codezoom.toml first
+    codezoom_toml = project_dir / ".codezoom.toml"
+    if codezoom_toml.exists():
+        try:
+            with open(codezoom_toml, "rb") as f:
+                data = tomllib.load(f)
+            return data.get("codezoom", {}).get("exclude", None)
+        except Exception:
+            pass
+
+    # Fall back to [tool.codezoom] in pyproject.toml
+    pyproject = project_dir / "pyproject.toml"
+    if pyproject.exists():
+        try:
+            with open(pyproject, "rb") as f:
+                data = tomllib.load(f)
+            return data.get("tool", {}).get("codezoom", {}).get("exclude", None)
+        except Exception:
+            pass
+
+    return None

codezoom/extractors/base.py

@@ -0,0 +1,20 @@
+"""Extractor protocol — all extractors conform to this interface."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol
+
+from codezoom.model import ProjectGraph
+
+
+class Extractor(Protocol):
+    """Protocol for project structure extractors."""
+
+    def can_handle(self, project_dir: Path) -> bool:
+        """Return True if this extractor applies to the given project."""
+        ...
+
+    def extract(self, project_dir: Path, graph: ProjectGraph) -> None:
+        """Populate *graph* with data extracted from *project_dir*."""
+        ...

codezoom/extractors/java/__init__.py

@@ -0,0 +1,43 @@
+"""Java extractors — stubs for future implementation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from codezoom.model import ProjectGraph
+
+
+class JavaMavenDeps:
+    """Extract dependencies from pom.xml / build.gradle. (Not yet implemented.)"""
+
+    def can_handle(self, project_dir: Path) -> bool:
+        return (project_dir / "pom.xml").exists() or (
+            project_dir / "build.gradle"
+        ).exists()
+
+    def extract(self, project_dir: Path, graph: ProjectGraph) -> None:
+        pass  # TODO: parse pom.xml / build.gradle
+
+
+class JavaPackageHierarchy:
+    """Extract Java package/class hierarchy. (Not yet implemented.)"""
+
+    def can_handle(self, project_dir: Path) -> bool:
+        return (project_dir / "pom.xml").exists() or (
+            project_dir / "build.gradle"
+        ).exists()
+
+    def extract(self, project_dir: Path, graph: ProjectGraph) -> None:
+        pass  # TODO: walk src/main/java tree
+
+
+class JavaAstSymbols:
+    """Extract methods/fields from Java classes. (Not yet implemented.)"""
+
+    def can_handle(self, project_dir: Path) -> bool:
+        return (project_dir / "pom.xml").exists() or (
+            project_dir / "build.gradle"
+        ).exists()
+
+    def extract(self, project_dir: Path, graph: ProjectGraph) -> None:
+        pass  # TODO: parse Java AST

codezoom/extractors/python/ast_symbols.py

@@ -0,0 +1,120 @@
+"""Extract functions, classes, and methods from Python source via AST."""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from codezoom.model import NodeData, ProjectGraph, SymbolData
+
+
+class AstSymbolsExtractor:
+    """Populate hierarchy leaf nodes with symbol (function/class/method) data."""
+
+    def can_handle(self, project_dir: Path) -> bool:
+        return (project_dir / "pyproject.toml").exists()
+
+    def extract(self, project_dir: Path, graph: ProjectGraph) -> None:
+        src_dir = _find_source_dir(project_dir, graph.root_node_id)
+        if src_dir is None:
+            return
+
+        for py_file in src_dir.rglob("*.py"):
+            if py_file.name == "__init__.py":
+                continue
+
+            relative = py_file.relative_to(src_dir.parent)
+            module_name = (
+                str(relative).replace("/", ".").replace("\\", ".").removesuffix(".py")
+            )
+
+            symbols = _extract_symbols(py_file)
+            if symbols:
+                node = graph.hierarchy.get(module_name)
+                if node is None:
+                    node = NodeData()
+                    graph.hierarchy[module_name] = node
+                node.symbols = symbols
+
+
+def _find_source_dir(project_dir: Path, root_node_id: str) -> Path | None:
+    candidate = project_dir / "src" / root_node_id
+    if candidate.is_dir():
+        return candidate
+    candidate = project_dir / root_node_id
+    if candidate.is_dir():
+        return candidate
+    return None
+
+
+class _CallExtractor(ast.NodeVisitor):
+    """Collect names called within a function/method body."""
+
+    def __init__(self) -> None:
+        self.called_names: set[str] = set()
+
+    def visit_Call(self, node: ast.Call) -> None:
+        if isinstance(node.func, ast.Name):
+            self.called_names.add(node.func.id)
+        elif isinstance(node.func, ast.Attribute):
+            if isinstance(node.func.value, ast.Name):
+                self.called_names.add(node.func.attr)
+        self.generic_visit(node)
+
+
+def _extract_symbols(file_path: Path) -> dict[str, SymbolData] | None:
+    """Return symbol data for top-level functions and classes in *file_path*."""
+    try:
+        tree = ast.parse(file_path.read_text())
+    except Exception:
+        return None
+
+    results: dict[str, SymbolData] = {}
+
+    for node in tree.body:
+        if isinstance(node, ast.FunctionDef):
+            ext = _CallExtractor()
+            ext.visit(node)
+            results[node.name] = SymbolData(
+                name=node.name,
+                kind="function",
+                line=node.lineno,
+                calls=sorted(ext.called_names),
+            )
+
+        elif isinstance(node, ast.ClassDef):
+            bases: list[str] = []
+            for base in node.bases:
+                if isinstance(base, ast.Name):
+                    bases.append(base.id)
+                elif isinstance(base, ast.Attribute):
+                    bases.append(base.attr)
+
+            methods: dict[str, SymbolData] = {}
+            for item in node.body:
+                if isinstance(item, ast.FunctionDef):
+                    ext = _CallExtractor()
+                    ext.visit(item)
+                    methods[item.name] = SymbolData(
+                        name=item.name,
+                        kind="method",
+                        line=item.lineno,
+                        calls=sorted(ext.called_names),
+                    )
+
+            # Class-level calls (decorators, class-var assignments, etc.)
+            ext = _CallExtractor()
+            for item in node.body:
+                if not isinstance(item, ast.FunctionDef):
+                    ext.visit(item)
+
+            results[node.name] = SymbolData(
+                name=node.name,
+                kind="class",
+                line=node.lineno,
+                calls=sorted(ext.called_names),
+                inherits=bases,
+                children=methods,
+            )
+
+    return results or None

codezoom/extractors/python/module_hierarchy.py

@@ -0,0 +1,171 @@
+"""Extract module hierarchy via pydeps or simple file-walk fallback."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+from codezoom.model import NodeData, ProjectGraph
+
+
+class ModuleHierarchyExtractor:
+    """Populate hierarchy with package/module tree and inter-module imports."""
+
+    def __init__(
+        self,
+        *,
+        exclude: list[str] | None = None,
+    ):
+        self._exclude = exclude
+
+    def can_handle(self, project_dir: Path) -> bool:
+        return (project_dir / "pyproject.toml").exists()
+
+    def extract(self, project_dir: Path, graph: ProjectGraph) -> None:
+        src_dir = _find_source_dir(project_dir, graph.root_node_id)
+        if src_dir is None:
+            return
+
+        deps = _run_pydeps(project_dir, src_dir, graph.root_node_id, self._exclude)
+        if deps is None:
+            # Fallback: build hierarchy from file tree only (no import edges)
+            deps = _build_deps_from_files(src_dir, graph.root_node_id)
+
+        _build_hierarchical_data(deps, graph)
+
+
+def _find_source_dir(project_dir: Path, root_node_id: str) -> Path | None:
+    """Locate the Python package directory inside the project."""
+    # Try src-layout first
+    candidate = project_dir / "src" / root_node_id
+    if candidate.is_dir():
+        return candidate
+    # Try flat layout
+    candidate = project_dir / root_node_id
+    if candidate.is_dir():
+        return candidate
+    return None
+
+
+def _run_pydeps(
+    project_dir: Path,
+    src_dir: Path,
+    root_node_id: str,
+    exclude: list[str] | None,
+) -> dict | None:
+    """Run pydeps and return the JSON dict, or None on failure."""
+    pydeps_path = shutil.which("pydeps")
+    if not pydeps_path:
+        print(
+            "Warning: pydeps not found (install with `pip install pydeps`). "
+            "Falling back to file-based hierarchy.",
+            file=sys.stderr,
+        )
+        return None
+
+    cmd: list[str] = [
+        pydeps_path,
+        str(src_dir),
+        "--show-deps",
+        "--no-show",
+        "--no-output",
+    ]
+    if exclude:
+        cmd.extend(["-xx"] + exclude)
+
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        cwd=str(project_dir),
+    )
+    if result.returncode != 0:
+        print(f"Warning: pydeps failed: {result.stderr}", file=sys.stderr)
+        return None
+
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError as e:
+        print(f"Warning: pydeps JSON parse error: {e}", file=sys.stderr)
+        return None
+
+
+def _build_deps_from_files(src_dir: Path, root_node_id: str) -> dict:
+    """Build a minimal dep dict from the file tree (no import edges)."""
+    deps: dict[str, dict] = {}
+    for py_file in src_dir.rglob("*.py"):
+        if py_file.name == "__init__.py":
+            continue
+        relative = py_file.relative_to(src_dir.parent)
+        module_name = (
+            str(relative).replace("/", ".").replace("\\", ".").removesuffix(".py")
+        )
+        deps[module_name] = {"imports": []}
+    return deps
+
+
+def _build_hierarchical_data(deps: dict, graph: ProjectGraph) -> None:
+    """Build the hierarchy inside *graph* from pydeps output."""
+    root_id = graph.root_node_id
+
+    hierarchy: dict[str, dict[str, set]] = defaultdict(
+        lambda: {"children": set(), "imports_from": set(), "imports_to": set()}
+    )
+    hierarchy[root_id] = {"children": set(), "imports_from": set(), "imports_to": set()}
+
+    for module_name, info in deps.items():
+        if module_name == "__main__":
+            continue
+
+        parts = module_name.split(".")
+
+        # Build parent→child edges
+        current = root_id
+        for i, _part in enumerate(parts[1:], 1):
+            child_name = ".".join(parts[: i + 1])
+            hierarchy[current]["children"].add(child_name)
+            hierarchy[child_name]  # ensure exists
+            current = child_name
+
+        # Track module-level imports
+        for imported in info.get("imports", []):
+            if imported != "__main__":
+                hierarchy[module_name]["imports_to"].add(imported)
+                hierarchy[imported]["imports_from"].add(module_name)
+
+    # Aggregate imports for package nodes
+    def aggregate_imports(node_id: str) -> tuple[set[str], set[str]]:
+        node = hierarchy[node_id]
+        if not node["children"]:
+            node["imports_to"] = {
+                imp for imp in node["imports_to"] if not imp.startswith(node_id)
+            }
+            return node["imports_to"], node["imports_from"]
+
+        all_to = set(node["imports_to"])
+        all_from = set(node["imports_from"])
+        for child_id in node["children"]:
+            child_to, child_from = aggregate_imports(child_id)
+            all_to.update(child_to)
+            all_from.update(child_from)
+
+        all_to = {imp for imp in all_to if not imp.startswith(node_id)}
+        hierarchy[node_id]["imports_to"] = all_to
+        hierarchy[node_id]["imports_from"] = all_from
+        return all_to, all_from
+
+    aggregate_imports(root_id)
+
+    # Write into graph.hierarchy (preserving any existing symbols data)
+    for node_id, raw in hierarchy.items():
+        existing = graph.hierarchy.get(node_id)
+        graph.hierarchy[node_id] = NodeData(
+            children=sorted(raw["children"]),
+            imports_to=sorted(raw["imports_to"]),
+            imports_from=sorted(raw["imports_from"]),
+            symbols=existing.symbols if existing else None,
+        )

codezoom/extractors/python/package_deps.py

@@ -0,0 +1,100 @@
+"""Extract external package dependencies from pyproject.toml + uv.lock."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from codezoom.model import ExternalDep, ProjectGraph
+
+
+class PackageDepsExtractor:
+    """Populate external_deps and external_deps_graph from project metadata."""
+
+    def can_handle(self, project_dir: Path) -> bool:
+        return (project_dir / "pyproject.toml").exists()
+
+    def extract(self, project_dir: Path, graph: ProjectGraph) -> None:
+        direct_deps, dep_graph = _extract_python_dependencies(project_dir)
+
+        # Collect all deps (direct + transitive)
+        all_deps: set[str] = set(direct_deps)
+        visited: set[str] = set()
+
+        def collect_transitive(pkg_name: str) -> None:
+            if pkg_name in visited:
+                return
+            visited.add(pkg_name)
+            if pkg_name in dep_graph:
+                for dep in dep_graph[pkg_name]:
+                    all_deps.add(dep)
+                    collect_transitive(dep)
+
+        for dep in direct_deps:
+            collect_transitive(dep)
+
+        direct_set = set(direct_deps)
+        graph.external_deps = [
+            ExternalDep(name=d, is_direct=(d in direct_set)) for d in sorted(all_deps)
+        ]
+        graph.external_deps_graph = dep_graph
+
+
+def _extract_python_dependencies(
+    project_root: Path,
+) -> tuple[list[str], dict[str, list[str]]]:
+    """Return (direct_deps, dependency_graph) from pyproject.toml + uv.lock."""
+    import tomllib
+
+    pyproject_path = project_root / "pyproject.toml"
+    if not pyproject_path.exists():
+        return [], {}
+
+    # --- direct deps from pyproject.toml ---
+    direct_deps: list[str] = []
+    try:
+        with open(pyproject_path, "rb") as f:
+            data = tomllib.load(f)
+
+        for dep in data.get("project", {}).get("dependencies", []):
+            pkg_name = (
+                dep.split("[")[0]
+                .split(">")[0]
+                .split("<")[0]
+                .split("=")[0]
+                .split(";")[0]
+                .strip()
+            )
+            if pkg_name:
+                direct_deps.append(pkg_name.lower())
+    except Exception as e:
+        print(f"Warning: Could not parse pyproject.toml: {e}", file=sys.stderr)
+
+    # --- transitive deps from uv.lock ---
+    dep_graph: dict[str, list[str]] = {}
+    uv_lock_path = project_root / "uv.lock"
+    if uv_lock_path.exists():
+        try:
+            with open(uv_lock_path, "rb") as f:
+                lock_data = tomllib.load(f)
+
+            packages = lock_data.get("package", [])
+            if isinstance(packages, list):
+                for pkg_info in packages:
+                    pkg_name = pkg_info.get("name", "").lower()
+                    if not pkg_name:
+                        continue
+                    pkg_deps: list[str] = []
+                    dependencies = pkg_info.get("dependencies", [])
+                    if isinstance(dependencies, list):
+                        for dep in dependencies:
+                            if isinstance(dep, dict):
+                                dep_name = dep.get("name", "").lower()
+                                if dep_name and dep_name not in pkg_deps:
+                                    pkg_deps.append(dep_name)
+                    if pkg_deps:
+                        dep_graph[pkg_name] = pkg_deps
+        except Exception as e:
+            print(f"Warning: Could not parse uv.lock: {e}", file=sys.stderr)
+
+    return sorted(set(direct_deps)), dep_graph

codezoom/model.py

@@ -0,0 +1,46 @@
+"""Language-agnostic data model for project structure graphs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class SymbolData:
+    """A function, class, or method within a module."""
+
+    name: str
+    kind: str  # "function", "class", "method"
+    line: int | None = None
+    calls: list[str] = field(default_factory=list)
+    inherits: list[str] = field(default_factory=list)
+    children: dict[str, SymbolData] = field(default_factory=dict)
+
+
+@dataclass
+class NodeData:
+    """A node in the project hierarchy (package, module, etc.)."""
+
+    children: list[str] = field(default_factory=list)
+    imports_to: list[str] = field(default_factory=list)
+    imports_from: list[str] = field(default_factory=list)
+    symbols: dict[str, SymbolData] | None = None
+
+
+@dataclass
+class ExternalDep:
+    """An external package dependency."""
+
+    name: str
+    is_direct: bool
+
+
+@dataclass
+class ProjectGraph:
+    """Complete project structure produced by extractors."""
+
+    project_name: str
+    root_node_id: str
+    hierarchy: dict[str, NodeData] = field(default_factory=dict)
+    external_deps: list[ExternalDep] = field(default_factory=list)
+    external_deps_graph: dict[str, list[str]] = field(default_factory=dict)