Metadata-Version: 2.4
Name: codemap-zero
Version: 0.1.1
Summary: Zero-LLM project scanner for AI agents. Produces a compact project map so AI uses 50-100x fewer tokens to understand your codebase.
Author: Jerry4539
License-Expression: MIT
Project-URL: Homepage, https://github.com/Jerry4539/codemap-zero
Project-URL: Repository, https://github.com/Jerry4539/codemap-zero
Project-URL: Issues, https://github.com/Jerry4539/codemap-zero/issues
Project-URL: Documentation, https://github.com/Jerry4539/codemap-zero#readme
Keywords: codemap-zero,codemap,ai,knowledge-graph,static-analysis,tree-sitter,ast,code-analysis,dependency-graph
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tree-sitter>=0.23.0
Requires-Dist: tree-sitter-python
Requires-Dist: tree-sitter-javascript
Requires-Dist: tree-sitter-typescript
Requires-Dist: tree-sitter-go
Requires-Dist: tree-sitter-rust
Requires-Dist: tree-sitter-java
Requires-Dist: tree-sitter-c
Requires-Dist: tree-sitter-cpp
Requires-Dist: tree-sitter-ruby
Requires-Dist: tree-sitter-c-sharp
Requires-Dist: tree-sitter-kotlin
Requires-Dist: tree-sitter-scala
Requires-Dist: tree-sitter-php
Requires-Dist: tree-sitter-swift
Requires-Dist: tree-sitter-lua
Requires-Dist: tree-sitter-zig
Requires-Dist: tree-sitter-powershell
Requires-Dist: tree-sitter-elixir
Requires-Dist: tree-sitter-julia
Requires-Dist: networkx>=3.0
Requires-Dist: click>=8.0
Provides-Extra: leiden
Requires-Dist: graspologic; python_version < "3.13" and extra == "leiden"
Provides-Extra: web
Requires-Dist: flask>=3.0; extra == "web"
Provides-Extra: ai
Requires-Dist: httpx>=0.27; extra == "ai"
Provides-Extra: watch
Requires-Dist: watchdog>=3.0; extra == "watch"
Provides-Extra: svg
Requires-Dist: matplotlib>=3.7; extra == "svg"
Provides-Extra: all
Requires-Dist: codemap-zero[ai,leiden,svg,watch,web]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: flask>=3.0; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Dynamic: license-file

# codemap-zero

**Zero-LLM project scanner for AI agents.** Scan any codebase and get a compact project map so AI uses 50-100x fewer tokens to understand your code.

[![PyPI](https://img.shields.io/pypi/v/codemap-zero)](https://pypi.org/project/codemap-zero/)
[![Python](https://img.shields.io/pypi/pyversions/codemap-zero)](https://pypi.org/project/codemap-zero/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![GitHub](https://img.shields.io/github/stars/Jerry4539/codemap-zero?style=social)](https://github.com/Jerry4539/codemap-zero)

## What it does

```
Your Project (50,000+ lines)  →  codemap-zero  →  PROJECT_MAP.md (~3K tokens)
                                                →  codemap.json (full graph)
                                                →  codemap.html (interactive viz)
```

- **AST-level extraction** — parses 20+ languages via tree-sitter
- **Dependency graph** — imports, calls, class hierarchies as a directed graph
- **Community detection** — auto-discovers logical modules (Louvain/Leiden)
- **Architecture analysis** — god nodes, circular deps, dead code, layers
- **Zero LLM tokens** — everything is deterministic static analysis

## Install

```bash
pip install codemap-zero
```

With extras:

```bash
pip install codemap-zero[web]   # web dashboard (Flask)
pip install codemap-zero[ai]    # AI assistant (vedaslab.in API)
pip install codemap-zero[all]   # everything
```

## Quick Start

### Scan a project

```bash
codemap scan .
```

Generates `PROJECT_MAP.md`, `codemap.json`, and `codemap.html` in the current directory.

### Interactive menu

```bash
codemap menu .
```

Choose actions by number — scan, launch dashboard, AI assistant, stats.

### Web dashboard

```bash
codemap serve .
```

Opens a professional web dashboard at `http://localhost:8787` with interactive graph visualization, module explorer, and complexity analysis.

### AI assistant

```bash
export VEDASLAB_API_KEY=your-key
codemap ai .
```

Chat with AI about your project using multiple providers (Vedaslab.in, OpenAI, Google Gemini, Anthropic Claude). The AI gets full project context from the scan.

## CLI Reference

```
codemap scan [TARGET] [OPTIONS]    Scan project and generate maps
  -o, --output DIR                 Output directory (default: .)
  --no-html                        Skip HTML generation
  --no-json                        Skip JSON export

codemap serve [TARGET] [OPTIONS]   Launch web dashboard
  -p, --port PORT                  Port (default: 8787)
  --host HOST                      Host (default: 127.0.0.1)

codemap ai [TARGET] [OPTIONS]      Interactive AI assistant
  --api-key KEY                    API key (supports vedaslab, openai, gemini, claude)
  --model MODEL                    Model name (e.g. gpt-4o, gemini-2.5-pro)

codemap menu [TARGET]              Interactive menu mode
```

## Supported Languages

Python, JavaScript, TypeScript, TSX, Go, Rust, Java, C, C++, C#, Ruby, Kotlin, Scala, PHP, Swift, Lua, Zig, PowerShell, Elixir, Julia — plus Markdown, JSON, YAML, TOML configs.

## How It Works

1. **Detect** — finds project type, frameworks, entry points, file structure
2. **Extract** — parses every source file into AST nodes (files, classes, functions, imports)
3. **Build** — constructs a directed graph with import/call/containment edges
4. **Cluster** — detects communities using Louvain algorithm, auto-labels them
5. **Analyze** — finds god nodes, entry points, circular deps, dead code, architecture patterns
6. **Report** — generates a token-optimized Markdown summary
7. **Export** — outputs JSON graph data and interactive HTML visualization

## Development

```bash
git clone https://github.com/Jerry4539/codemap-zero.git
cd codemap-zero
pip install -e ".[dev]"
codemap scan .
```

## Contributing

Contributions are welcome! Please open an issue or pull request on [GitHub](https://github.com/Jerry4539/codemap-zero).

> **Note:** The PyPI package name is `codemap-zero` (`pip install codemap-zero`), but the CLI command is `codemap`.

## License

MIT — see [LICENSE](LICENSE) for details.

---

Developed by **Jerry4539**
