Metadata-Version: 2.4
Name: codemap-python
Version: 0.1.3
Summary: Local Python code analysis tool - understand architecture, dependencies, and call graphs
Author-email: ADITYA <aditykushwaha69@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/ADITYA-kus/codemap_ai
Project-URL: Repository, https://github.com/ADITYA-kus/codemap_ai.git
Project-URL: Issues, https://github.com/ADITYA-kus/codemap_ai/issues
Project-URL: Documentation, https://github.com/ADITYA-kus/codemap_ai#readme
Keywords: code-analysis,python,architecture,call-graph,cli,dashboard,local,privacy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.23
Requires-Dist: jinja2>=3.1.4
Requires-Dist: requests>=2.31
Requires-Dist: starlette==0.40.0

# CodeMap

**CodeMap** is a pure local developer tool that analyzes Python codebases and provides:

- 📊 **Architecture Analysis** - Understand code structure, dependencies, and call graphs
- 🦺 **Call Graph Extraction** - Trace function/method calls across your codebase
- ⚠️ **Risk Analysis** - Identify complex code patterns and potential issues
- 📈 **Symbol Indexing** - Search and explore functions, classes, and methods
- 🌐 **Local Web Dashboard** - Visual code analysis interface
- 🔐 **Privacy First** - All analysis runs locally, no data leaves your machine

## Requirements

- **Python 3.10+**
- **pip** (Python package manager)
- **~5 minutes** to get started

## Quick Start (3 Steps)

### Step 1️⃣: Install CodeMap

```bash
# Install from PyPI (easiest)
pip install codemap-python
```

**Verify installation:**
```bash
codemap --help
```

You should see:
```
usage: codemap [-h] {analyze,dashboard,open,cache} ...
```

> **For developers:** To modify source code or contribute, clone the repository:
> ```bash
> git clone https://github.com/ADITYA-kus/codemap_ai.git
> cd codemap_ai
> pip install -e .
> ```

---

### Step 2️⃣: Analyze Your First Repository

**IMPORTANT:** The `analyze` command REQUIRES the `--path` argument pointing to a directory!

```bash
# Analyze the demo repo (takes 5-10 seconds)
codemap analyze --path demo_repo
```

**Output: JSON analysis data**
```json
{
  "ok": true,
  "cache_dir": ".codemap_cache/...",
  "analysis_version": "2.2",
  "repo_dir": "demo_repo"
}
```

**Analyze your own Python project:**
```bash
codemap analyze --path /path/to/your/python/project
```

**Analyze a GitHub repository:**
```bash
codemap analyze --github https://github.com/owner/repo
```

---

### Step 3️⃣: View in Web Dashboard

```bash
# Start the web dashboard
codemap dashboard --port 8000
```

**Open in browser:**
```
http://127.0.0.1:8000
```

You'll see:
- List of analyzed repositories
- Call graphs
- Architecture metrics
- Risk analysis
- Symbol search

---

## Common Commands

### Analyze Commands
```bash
# ⚠️ REQUIRED: Analyze needs --path argument!

# Analyze a local repository
codemap analyze --path <repo_directory>

# Analyze a GitHub repository (public)
codemap analyze --github https://github.com/owner/repo

# Analyze private GitHub repo (requires token)
codemap analyze --github https://github.com/owner/private-repo --token YOUR_GITHUB_TOKEN

# Force rebuild analysis (ignore cache)
codemap analyze --path <repo_directory> --rebuild

# Use API for detailed JSON output
codemap api analyze --path <repo_directory>
```

### Dashboard Commands
```bash
# Start web dashboard (default: localhost:8000)
codemap dashboard --port 8000

# Start dashboard with auto-reload (development)
codemap dashboard --port 8000 --reload

# Open dashboard in browser
codemap open --port 8000
```

### Cache Management
```bash
# List all analyzed repositories
codemap cache list

# Show cache details for a repository
codemap cache info <repo_hash>

# Clear a specific repository's cache
codemap cache clear <repo_hash>

# Show cache retention policy
codemap cache retention <repo_hash>

# Sweep expired caches (auto-cleanup)
codemap cache sweep
```

**Get GitHub Token (for private repos):**
1. Go to https://github.com/settings/tokens
2. Click "Generate new token" → "Generate new token (classic)"
3. Give it a name (e.g., "CodeMap")
4. Select **`repo`** scope (full control of private repos)
5. Copy the token and save it somewhere safe
6. Use in commands: `--token ghp_xxxxx`

**Or pass token via stdin (more secure):**
```bash
echo "YOUR_TOKEN" | codemap analyze --github https://github.com/owner/repo --token-stdin
```

---

## Directory Structure

This is the source code structure for developers. **If you installed via pip, these files are automatically installed in your Python environment.**

```
codemap_ai/  (source code)
├── README.md              # This file
├── cli.py                 # Command-line interface
├── security_utils.py      # Security & secret redaction
├── pyproject.toml         # Package configuration
├── analysis/              # Code analysis engine
│   ├── core/             # AST parsing, imports
│   ├── call_graph/       # Call graph building
│   ├── explain/          # Symbol metadata
│   ├── architecture/     # Dependency analysis
│   └── graph/            # Graph indexing
├── ui/                    # Web dashboard
│   ├── app.py            # FastAPI server
│   ├── templates/        # HTML templates
│   └── static/           # CSS, JavaScript
├── tests/                 # Test suite
└── demo_repo/            # Example repository
```

---

## Features Explained

### 🔍 Symbol Search
Find all functions, classes, and methods in your codebase:

```bash
codemap api search --path <repo_path> --query "MyClass"
codemap api search --path <repo_path> --query "function_name"
```

### 📊 Call Graph
Understand how functions call each other:

```bash
codemap api explain --path <repo_path> --symbol "module.ClassName.method"
```

### ⚠️ Risk Radar
Detect complex code patterns and potential issues:

```bash
codemap api risk_radar --path <repo_path>
```

### 📈 Impact Analysis
See which files/functions are affected by changes:

```bash
codemap api impact --path <repo_path> --target "module.function"
```

---









## Privacy & Security

✅ **100% Local**
- All analysis happens on your machine
- No data sent to external servers
- .env files and secrets are never exposed

✅ **Secure Cache**
- Analysis results cached locally
- Cache auto-cleared after 14 days (configurable)
- No credentials stored

✅ **Secret Redaction**
- API keys automatically masked in output
- GitHub tokens never logged
- Safe error messages

---

## Example Workflow

### Local Project Analysis
```bash
# 1. Navigate to your Python project
cd C:\Users\YourName\my_python_project

# 2. Analyze it with CodeMap
codemap analyze --path .
# ✅ Analysis complete! Results cached locally

# 3. Start the web dashboard
codemap dashboard --port 8000
# ✅ Dashboard running at http://127.0.0.1:8000

# 4. Open in browser
codemap open --port 8000

# 5. Explore in browser:
#    - View all repositories
#    - See call graphs
#    - Check architecture metrics
#    - View risk analysis

# 6. Search for a specific class
codemap api search --path . --query "MyClass"

# 7. Check call graph for a function
codemap api explain --path . --symbol "mymodule.MyClass.method"
```

### GitHub Repository Analysis
```bash
# 1. Analyze a public GitHub repo
codemap analyze --github https://github.com/owner/awesome-project
# ✅ Downloaded and analyzed

# 2. View in dashboard
codemap dashboard --port 8000
codemap open --port 8000

# 3. Clean up old repos
codemap cache list      # See all cached repos
codemap cache sweep    # Auto-cleanup old ones
```

---

## Next Steps

1. 🎯 **First analysis** - Try the demo:
   ```bash
   codemap analyze --path demo_repo
   ```

2. 📊 **View results** - Open the dashboard:
   ```bash
   codemap dashboard --port 8000
   ```

3. 📁 **Analyze your code** - Point to your project:
   ```bash
   codemap analyze --path ~/my-project
   ```

4. 🔗 **Try GitHub** - Analyze public repos:
   ```bash
   codemap analyze --github https://github.com/owner/repo
   ```

5. 🚀 **Advanced features** - Explore search, impact, risk analysis:
   ```bash
   codemap api search --path . --query "YourClass"
   ```

---

## Quick Reference

```bash
# Installation
pip install -e .

# Most common commands
codemap analyze --path <directory>              # Analyze local repo
codemap analyze --github <url>                  # Analyze GitHub repo
codemap dashboard --port 8000                   # Start dashboard
codemap open --port 8000                        # Open in browser
codemap cache list                              # List all analyses
codemap cache clear <hash>                      # Delete one analysis
```

---

## Support & Help

✅ **Run without arguments** to see all available commands:
```bash
codemap --help
codemap analyze --help
codemap dashboard --help
codemap api --help
```

✅ **Check requirements:**
```bash
python --version          # Should be 3.10+
pip --version             # Should be installed
git --version             # For GitHub repos
```

✅ **Verify repo path:**
```bash
# Make sure your repo has Python files
dir <your_repo>                 # Windows
ls <your_repo>                  # Linux/Mac
find <your_repo> -name "*.py"   # Find Python files
```

---

**Happy coding! 🚀**

---

**GitHub:** https://github.com/ADITYA-kus/codemap_ai

