codezoom 0.1.0__tar.gz

codezoom-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+*.pyc
+/dist/
+/uv.lock
+__pycache__/

codezoom-0.1.0/Makefile

@@ -0,0 +1,18 @@
+help:
+	@echo "Available targets:\n\
+		clean - remove build files and directories\n\
+		lint  - run code formatters and linters\n\
+		dist  - generate release archives\n\
+	"
+
+clean:
+	bin/clean.sh
+
+check:
+	@bin/check.sh
+
+lint: check
+	bin/lint.sh
+
+dist: check clean
+	bin/dist.sh

codezoom-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: codezoom
+Version: 0.1.0
+Summary: Multi-level code structure explorer — interactive drill-down HTML visualizations
+Author: Curtis Rueden
+License-Expression: Unlicense
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# codezoom
+
+Multi-level code structure explorer — interactive drill-down HTML visualizations.
+
+codezoom generates a standalone HTML file that lets you explore a project's
+structure at multiple levels of detail:
+
+1. **External dependencies** — direct and transitive packages from `pyproject.toml` + `uv.lock`
+2. **Package hierarchy** — sub-packages and modules (via [pydeps](https://github.com/thebjorn/pydeps) or file-tree fallback)
+3. **Module internals** — functions and classes extracted from the AST
+4. **Class internals** — methods and their call relationships
+
+Click any node to drill down. Use breadcrumb navigation to go back up.
+
+## Examples
+
+<table>
+  <tr>
+    <td align="center"><a href="screenshots/dependencies.png"><img src="screenshots/jgo-dependencies.png" width="400"></a><br><em>External dependencies</em></td>
+    <td align="center"><a href="screenshots/modules-1.png"><img src="screenshots/jgo-submodules.png" width="400"></a><br><em>Project submodules</em></td>
+  </tr>
+  <tr>
+    <td align="center"><a href="screenshots/modules-1a.png"><img src="screenshots/jgo-env.png" width="400"></a><br><em>A submodule's children</em></td>
+    <td align="center"><a href="screenshots/modules-2.png"><img src="screenshots/jgo-cli.png" width="400"></a><br><em>Another submodule's children</em></td>
+  </tr>
+  <tr>
+    <td align="center"><a href="screenshots/modules-3.png"><img src="screenshots/jgo-cli-rich-formatters.png" width="400"></a><br><em>Single-file view</em></td>
+    <td></td>
+  </tr>
+</table>
+
+## Installation
+
+<details><summary><strong>Installing codezoom with uv</strong></summary>
+
+```shell
+uv tool install codezoom
+```
+
+</details>
+<details><summary><strong>Installing codezoom with pip</strong></summary>
+
+```shell
+pip install codezoom
+```
+
+</details>
+<details><summary><strong>Installing codezoom from source</strong></summary>
+
+```shell
+git clone https://github.com/apposed/codezoom
+uv tool install --with-editable codezoom codezoom
+```
+
+When installed in this fashion, changes to the codezoom source code will be immediately reflected when running `codezoom` from the command line.
+
+</details>
+<details><summary><strong>Using codezoom as a dependency</strong></summary>
+
+```shell
+uv add codezoom
+```
+or
+```shell
+pixi add --pypi codezoom
+```
+Not sure which to use? [Read this](https://jacobtomlinson.dev/posts/2025/python-package-managers-uv-vs-pixi/#so-what-do-i-use).
+
+</details>
+
+## Usage
+
+```bash
+codezoom /path/to/project                     # auto-detect, output to <project>_deps.html
+codezoom /path/to/project -o output.html      # custom output path
+codezoom /path/to/project --name "My Project" # custom display name
+codezoom /path/to/project --open              # open in browser after generating
+```
+
+Also works as a module:
+
+```bash
+python -m codezoom /path/to/project
+```
+
+## Requirements
+
+- Python 3.11+
+- No mandatory runtime dependencies beyond the standard library
+- Optional: [pydeps](https://github.com/thebjorn/pydeps) for richer module-level
+  import analysis (falls back to file-tree scanning without it)
+
+## Per-project configuration
+
+Projects can include a `.codezoom.toml` or a `[tool.codezoom]` section in
+`pyproject.toml`:
+
+```toml
+[tool.codezoom]
+exclude = ["tests", "docs", "__pycache__"]
+```
+
+The `exclude` list is passed to pydeps via `-xx` to omit modules from the
+hierarchy.
+
+## Language support
+
+| Language | Status |
+|----------|--------|
+| Python   | Supported |
+| Java     | Stub extractors present — not yet implemented |
+
+## License
+
+[UNLICENSE](UNLICENSE) - All copyright disclaimed.

codezoom-0.1.0/README.md

@@ -0,0 +1,115 @@
+# codezoom
+
+Multi-level code structure explorer — interactive drill-down HTML visualizations.
+
+codezoom generates a standalone HTML file that lets you explore a project's
+structure at multiple levels of detail:
+
+1. **External dependencies** — direct and transitive packages from `pyproject.toml` + `uv.lock`
+2. **Package hierarchy** — sub-packages and modules (via [pydeps](https://github.com/thebjorn/pydeps) or file-tree fallback)
+3. **Module internals** — functions and classes extracted from the AST
+4. **Class internals** — methods and their call relationships
+
+Click any node to drill down. Use breadcrumb navigation to go back up.
+
+## Examples
+
+<table>
+  <tr>
+    <td align="center"><a href="screenshots/dependencies.png"><img src="screenshots/jgo-dependencies.png" width="400"></a><br><em>External dependencies</em></td>
+    <td align="center"><a href="screenshots/modules-1.png"><img src="screenshots/jgo-submodules.png" width="400"></a><br><em>Project submodules</em></td>
+  </tr>
+  <tr>
+    <td align="center"><a href="screenshots/modules-1a.png"><img src="screenshots/jgo-env.png" width="400"></a><br><em>A submodule's children</em></td>
+    <td align="center"><a href="screenshots/modules-2.png"><img src="screenshots/jgo-cli.png" width="400"></a><br><em>Another submodule's children</em></td>
+  </tr>
+  <tr>
+    <td align="center"><a href="screenshots/modules-3.png"><img src="screenshots/jgo-cli-rich-formatters.png" width="400"></a><br><em>Single-file view</em></td>
+    <td></td>
+  </tr>
+</table>
+
+## Installation
+
+<details><summary><strong>Installing codezoom with uv</strong></summary>
+
+```shell
+uv tool install codezoom
+```
+
+</details>
+<details><summary><strong>Installing codezoom with pip</strong></summary>
+
+```shell
+pip install codezoom
+```
+
+</details>
+<details><summary><strong>Installing codezoom from source</strong></summary>
+
+```shell
+git clone https://github.com/apposed/codezoom
+uv tool install --with-editable codezoom codezoom
+```
+
+When installed in this fashion, changes to the codezoom source code will be immediately reflected when running `codezoom` from the command line.
+
+</details>
+<details><summary><strong>Using codezoom as a dependency</strong></summary>
+
+```shell
+uv add codezoom
+```
+or
+```shell
+pixi add --pypi codezoom
+```
+Not sure which to use? [Read this](https://jacobtomlinson.dev/posts/2025/python-package-managers-uv-vs-pixi/#so-what-do-i-use).
+
+</details>
+
+## Usage
+
+```bash
+codezoom /path/to/project                     # auto-detect, output to <project>_deps.html
+codezoom /path/to/project -o output.html      # custom output path
+codezoom /path/to/project --name "My Project" # custom display name
+codezoom /path/to/project --open              # open in browser after generating
+```
+
+Also works as a module:
+
+```bash
+python -m codezoom /path/to/project
+```
+
+## Requirements
+
+- Python 3.11+
+- No mandatory runtime dependencies beyond the standard library
+- Optional: [pydeps](https://github.com/thebjorn/pydeps) for richer module-level
+  import analysis (falls back to file-tree scanning without it)
+
+## Per-project configuration
+
+Projects can include a `.codezoom.toml` or a `[tool.codezoom]` section in
+`pyproject.toml`:
+
+```toml
+[tool.codezoom]
+exclude = ["tests", "docs", "__pycache__"]
+```
+
+The `exclude` list is passed to pydeps via `-xx` to omit modules from the
+hierarchy.
+
+## Language support
+
+| Language | Status |
+|----------|--------|
+| Python   | Supported |
+| Java     | Stub extractors present — not yet implemented |
+
+## License
+
+[UNLICENSE](UNLICENSE) - All copyright disclaimed.

codezoom-0.1.0/UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org/>

codezoom-0.1.0/bin/check.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+
+if ! command -v uv >/dev/null 2>&1; then
+  echo "Please install uv (https://docs.astral.sh/uv/getting-started/installation/)."
+  exit 1
+fi

codezoom-0.1.0/bin/clean.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+
+dir=$(dirname "$0")
+cd "$dir/.."
+
+find . -name __pycache__ -type d | while read d
+  do rm -rfv "$d"
+done
+rm -rfv .mypy_cache .pytest_cache build dist src/*.egg-info

codezoom-0.1.0/bin/dist.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+
+dir=$(dirname "$0")
+cd "$dir/.."
+
+uv run python -m build

codezoom-0.1.0/bin/lint.sh

@@ -0,0 +1,24 @@
+#!/bin/sh
+
+dir=$(dirname "$0")
+cd "$dir/.."
+
+exitCode=0
+
+# Check for errors and capture non-zero exit codes.
+uv run validate-pyproject pyproject.toml
+code=$?; test $code -eq 0 || exitCode=$code
+uv run ruff check >/dev/null 2>&1
+code=$?; test $code -eq 0 || exitCode=$code
+uv run ruff format --check >/dev/null 2>&1
+code=$?; test $code -eq 0 || exitCode=$code
+
+# Do actual code reformatting.
+uv run ruff check --select I --fix
+code=$?; test $code -eq 0 || exitCode=$code
+uv run ruff check --fix
+code=$?; test $code -eq 0 || exitCode=$code
+uv run ruff format
+code=$?; test $code -eq 0 || exitCode=$code
+
+exit $exitCode

codezoom-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codezoom"
+version = "0.1.0"
+description = "Multi-level code structure explorer — interactive drill-down HTML visualizations"
+readme = "README.md"
+license = "Unlicense"
+requires-python = ">=3.11"
+authors = [
+    { name = "Curtis Rueden" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Documentation",
+]
+
+[dependency-groups]
+dev = [
+    "build",
+    "ruff",
+    "validate-pyproject[all]",
+]
+
+[project.scripts]
+codezoom = "codezoom.cli:main"

codezoom-0.1.0/src/codezoom/__init__.py

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

codezoom-0.1.0/src/codezoom/__main__.py

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

codezoom-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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