Metadata-Version: 2.4
Name: codezoom
Version: 2.2.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
Requires-Dist: pyyaml>=6.0
Provides-Extra: java
Requires-Dist: jgo>=2.0.0.dev0; extra == 'java'
Provides-Extra: rust
Requires-Dist: tree-sitter-rust>=0.24; extra == 'rust'
Requires-Dist: tree-sitter>=0.24; extra == 'rust'
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. Click any node to drill down; use
breadcrumb navigation to go back up.

## What it visualizes

 Level
 Python
 Java

 1. External dependencies
 Direct and transitive packages from pyproject.toml + uv.lock
 Direct and transitive Maven dependencies from pom.xml (requires jgo)

 2. Package/module hierarchy
 Sub-packages and modules via pydeps (https://github.com/thebjorn/pydeps) (with file-tree fallback) — includes inter-module imports
 Package tree via jdeps — includes inter-package dependencies and class-level call graphs

 3. Module/class internals
 Functions and classes extracted from AST — shows visibility (public/private based on naming)
 Classes, interfaces, enums, and nested classes extracted from compiled bytecode via javap — shows visibility (public/protected/private/package)

 4. Class/method internals
 Methods and their call relationships extracted from AST
 Methods with parameter signatures and call relationships extracted from bytecode

## Examples

External dependencies (Python)
     
External dependencies (Java)

Project submodules
     
A submodule's children

Single-file view (Python)
     
Single-file view (Java)

## Installation

Installing codezoom with uv

```shell
uv tool install codezoom
```


Installing codezoom with pip

```shell
pip install codezoom
```


Installing codezoom from source

```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.

Using codezoom as a dependency

```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).

## Usage

Basic usage (auto-detects Python or Java):

```bash
codezoom /path/to/project                     # auto-detect, output to codezoom.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
```

### Python projects

```bash
# Basic usage - requires pyproject.toml
codezoom /path/to/python/project

# For best results, install pydeps first
pip install pydeps
codezoom /path/to/python/project --open
```

### Java projects

```bash
# Compile the project first
cd /path/to/java/project
mvn compile

# Generate visualization (basic - no Maven dependencies)
codezoom . --open

# For full dependency analysis, install jgo
pip install codezoom[java]
codezoom . --open
```

Also works as a module:

```bash
python -m codezoom /path/to/project
```

## Requirements

### Core
- Python 3.11+
- No mandatory runtime dependencies beyond the standard library

### For Python projects
- Optional: [pydeps](https://github.com/thebjorn/pydeps) for richer module-level
  import analysis (falls back to file-tree scanning without it)
  ```bash
  pip install pydeps
  ```

### For Java projects
- **JDK** (not just JRE) — provides `jdeps` and `javap` for package/class analysis
- **Compiled code** — run `mvn compile` before analyzing
- Optional: `jgo` for Maven dependency extraction
  ```bash
  pip install codezoom[java]
  ```

## 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

### Python
- **Detection**: Presence of `pyproject.toml`
- **Project layouts**: Both `src/` layout and flat layout
- **Dependencies**: Extracted from `pyproject.toml` and `uv.lock`
- **Hierarchy**: Module tree via `pydeps` (falls back to file tree)
- **Symbols**: Functions, classes, and methods via AST parsing
- **Call graphs**: Method calls extracted from AST
- **Visibility**: Public/private based on Python naming conventions (`_private`, `__dunder__`)
- **Configuration**: Via `.codezoom.toml` or `[tool.codezoom]` in `pyproject.toml`

### Java
- **Detection**: Presence of `pom.xml` or `build.gradle.kts` or `build.gradle`
- **Prerequisites**:
  - JDK installed (for `jdeps` and `javap`)
  - Project compiled (`mvn compile` or `./gradlew build`)
  - `pip install codezoom[java]` for dependency extraction
- **Dependencies**: Maven dependencies via `jgo` (direct + transitive with scope filtering)
- **Hierarchy**: Package tree via `jdeps` with inter-package dependencies
- **Class dependencies**: Class-to-class and class-to-package relationships via `javap`
- **Symbols**: Classes, interfaces, enums, nested classes via bytecode analysis
- **Call graphs**: Method invocations extracted from bytecode
- **Visibility**: Full Java visibility (public, protected, private, package-private)
- **Limitations**: Bridge methods are filtered out; requires compiled `.class` files

## License

[UNLICENSE](UNLICENSE) - All copyright disclaimed.
