codemap-ai 3.0.0 → 3.1.1

package/README.md

@@ -2,151 +2,261 @@
 
 **Call graph analyzer for understanding code impact and execution flows - built for Claude Code**
 
-Stop guessing what breaks when you change code. CodeMap builds a complete call graph of your codebase so Claude can answer "what depends on this?" with surgical precision.
+Stop guessing what breaks when you change code. CodeMap builds a complete call graph so Claude can answer "what depends on this?" with surgical precision.
 
 ## Features
 
 - 🔍 **Call Graph Analysis** - Trace every function call across your entire codebase
 - 🎯 **Impact Analysis** - Know exactly what breaks before you change code
 - 🔗 **Cross-File Resolution** - Follows imports and tracks dependencies
-- 🚀 **FastAPI Support** - Detects HTTP endpoints and dependency injection patterns
-- 💾 **Incremental Updates** - Only re-indexes changed files
+- 🚀 **FastAPI Support** - Detects HTTP endpoints and dependency injection
+- 💾 **Incremental Updates** - Only re-indexes changed files (git-aware)
 - 🤖 **Claude Code Integration** - MCP server for AI-powered code queries
 
 ## Installation
 
 ```bash
 # Use directly with npx (recommended)
-npx codemap-ai index /path/to/project
+npx codemap-ai init
 
 # Or install globally
 npm install -g codemap-ai
 ```
 
-## Quick Start
+## Quick Start (3 Commands)
 
 ```bash
-# Index your codebase
-npx codemap-ai index /path/to/project
+# 1. First time: Initialize (indexes + configures Claude Code)
+npx codemap-ai init
 
-# Start MCP server for Claude Code
-npx codemap-ai mcp-server
+# 2. Before PR: Check impact of your changes
+npx codemap-ai impact
 
-# Add to Claude Code (one-time setup)
-claude mcp add codemap -- npx codemap-ai mcp-server --path /path/to/project
+# 3. After major refactor: Force re-index
+npx codemap-ai reindex
 ```
 
+That's it! Now ask Claude questions like:
+- "What would break if I change authenticate_user?"
+- "Show me the flow from chat endpoint to database"
+- "What functions call get_user_permissions?"
+
 ## Commands
 
-### `codemap index [path]`
+### `codemap init` - First-Time Setup
 
-Build a call graph of your codebase:
+Initialize CodeMap in your project (one command does everything):
 
 ```bash
-# Index current directory
-codemap index
-
-# Index specific directory
-codemap index /path/to/project
+cd /path/to/project
+npx codemap-ai init
+```
 
-# Force re-index everything
-codemap index --force
+**What it does:**
+1. Indexes your entire codebase
+2. Automatically configures MCP server in Claude Code
+3. Ready to ask questions!
 
-# Custom file patterns
-codemap index --include "src/**/*.py" --exclude "**/tests/**"
+**Output:**
+```
+✓ Indexed 290 files (3,987 calls resolved)
+✓ MCP server configured in Claude Code
+✓ Ready! Ask Claude: 'What would break if I change authenticate_user?'
 ```
 
 **Options:**
-- `--force` - Force re-index all files (default: incremental)
-- `--include <patterns>` - File patterns to include (can be repeated)
-- `--exclude <patterns>` - File patterns to exclude (can be repeated)
+- `--skip-mcp` - Skip MCP server configuration
+- `--include <patterns>` - File patterns to include
+- `--exclude <patterns>` - File patterns to exclude
+
+---
+
+### `codemap impact` - Check What Changed
+
+Analyze the impact of your uncommitted changes (smart git integration):
+
+```bash
+# After editing files
+npx codemap-ai impact
+```
+
+**What it does:**
+1. Detects modified files (uses `git diff` if available)
+2. Finds which functions changed
+3. Re-indexes only changed files (fast!)
+4. Shows callers, affected endpoints, risk level
 
 **Output:**
 ```
-CodeMap Call Graph Indexer
+✔ Detected 2 modified files
+
+Modified Files:
+  • chat.py
+  • authentication.py
 
-Indexed:    290 files
-Resolved:   3,987 function calls
-Unresolved: 12,253 calls (external/dynamic)
+Changed Functions:
+  • handle_chat (chat.py:47)
+  • authenticate_user (authentication.py:120)
 
-Framework Detection:
-HTTP Endpoints: 283 routes detected
-Dependencies:   30/30 resolved (FastAPI Depends)
+Impact Analysis:
+  handle_chat:
+    12 direct callers
+  authenticate_user:
+    25 direct callers ⚠️
 
-Call resolution rate: 25%
-Database saved to: .codemap/graph.db
+Affected HTTP Endpoints:
+  • POST /api/chat
+  • POST /api/agents
+
+Risk Assessment:
+  HIGH - 37 functions affected
 ```
 
-### `codemap mcp-server`
+**Options:**
+- `-v, --verbose` - Show detailed caller information
+
+**Use cases:**
+- Before creating a PR
+- After refactoring
+- When debugging regressions
+
+---
 
-Start the MCP server for Claude Code integration:
+### `codemap reindex` - Force Full Rebuild
+
+Force re-index everything from scratch:
 
 ```bash
-codemap mcp-server --path /path/to/project
+npx codemap-ai reindex
 ```
 
-**Options:**
-- `--path <path>` - Path to indexed project (default: current directory)
+**When to use:**
+- After pulling major changes
+- After changing many files
+- When you want to rebuild the entire graph
 
-## MCP Tools for Claude Code
+---
 
-Once connected via MCP, Claude gains these capabilities:
+## Claude Code Integration (MCP Tools)
 
-### `codemap_callers`
-Find all functions that call a specific function:
+Once you run `codemap init`, Claude gains these capabilities via MCP:
 
-```
-Claude: "What calls the authenticate_user function?"
-→ Returns: 12 callers with file:line references
-```
+### 1. `codemap_impact` - Analyze Change Impact
 
-### `codemap_impact`
-Analyze the blast radius of changing code:
+**Ask Claude:**
+> "If I change authenticate_user, what breaks?"
 
-```
-Claude: "If I change authenticate_user, what breaks?"
-→ Returns: 15 affected files, call chain, risk level
-```
+**Claude uses:** `codemap_impact` tool
 
-### `codemap_trace_flow`
-Trace execution paths between functions:
+**Returns:**
+- Direct callers (functions that call it)
+- Total impact (affected functions/files)
+- Risk level (LOW/MEDIUM/HIGH)
+- Recommendations
 
+**Example response:**
 ```
-Claude: "Show me the flow from chat endpoint to database"
-→ Returns: handle_chat → authenticate → get_handler → save_chat → db.insert
+Impact Analysis: authenticate_user
+
+Location: authentication.py:120
+Risk Level: HIGH
+
+Direct Callers (25):
+- handle_chat in chat.py:47
+- handle_agent in agents.py:85
+- get_settings in settings.py:120
+...
+
+Total Impact:
+- Affected functions: 45
+- Affected files: 15
+
+⚠️ Recommendation: High-risk change. Review all callers before modifying.
 ```
 
-### `codemap_dependencies`
-Get import/export relationships:
+---
+
+### 2. `codemap_trace_flow` - Trace Execution Paths
+
+**Ask Claude:**
+> "Show me the flow from chat endpoint to database"
+
+**Claude uses:** `codemap_trace_flow` tool
 
+**Returns:**
+- Complete call path from source to target
+- File locations for each step
+- Total steps in the flow
+
+**Example response:**
 ```
-Claude: "What does auth.py import?"
-→ Returns: All imports and what they're used for
+Execution Flow: handle_chat → save_message
+
+1. handle_chat
+   File: chat.py:47
+   ↓ calls
+
+2. authenticate_user
+   File: authentication.py:120
+   ↓ calls
+
+3. ChatHandler.save_message
+   File: handlers/chat.py:200
+   ↓ calls
+
+4. db.chats.insert_one
+   File: external
+
+Total steps: 4
 ```
 
-### `codemap_search`
-Search for functions, classes, files:
+---
+
+### 3. `codemap_callers` - Find Who Calls a Function
+
+**Ask Claude:**
+> "What functions call get_user_permissions?"
+
+**Claude uses:** `codemap_callers` tool
 
+**Returns:**
+- All functions that call the target
+- File locations with line numbers
+- Function types (function, method, etc.)
+
+**Example response:**
 ```
-Claude: "Find all database operations"
-→ Returns: 476 operations (find_one: 137, update_one: 122, ...)
+Callers of get_user_permissions
+
+Total callers: 12
+
+Who Calls This Function:
+- handle_chat (function)
+  File: chat.py:47
+
+- handle_agent (function)
+  File: agents.py:85
+
+- verify_access (function)
+  File: auth.py:150
+...
 ```
 
+---
+
 ## Supported Languages
 
-| Language   | Parsing | Imports | Calls | Classes | Methods |
-|------------|---------|---------|-------|---------|---------|
-| Python     | ✅      | ✅      | ✅    | ✅      | ✅      |
-| TypeScript | ✅      | ✅      | ✅    | ✅      | ✅      |
-| JavaScript | ✅      | ✅      | ✅    | ✅      | ✅      |
+| Language   | Parsing | Imports | Calls | Classes | Methods | Inheritance |
+|------------|---------|---------|-------|---------|---------|-------------|
+| Python     | ✅      | ✅      | ✅    | ✅      | ✅      | ✅          |
+| TypeScript | ✅      | ✅      | ✅    | ✅      | ✅      | ✅          |
+| JavaScript | ✅      | ✅      | ✅    | ✅      | ✅      | ✅          |
 
 ## Framework Detection
 
-CodeMap understands framework-specific patterns:
-
-**FastAPI:**
-- HTTP route decorators (`@router.post("/chat")`)
-- Dependency injection (`Depends()`)
+**FastAPI** (Python):
+- HTTP route decorators: `@router.post("/chat")`
+- Dependency injection: `Depends(get_user)`
 - Request handlers and middleware
 
 **Coming Soon:**
@@ -157,83 +267,142 @@ CodeMap understands framework-specific patterns:
 ## How It Works
 
 ```
-┌──────────────┐
-│  Your Code   │
-│ .py/.ts/.js  │
-└──────┬───────┘
-       │
-       ▼
-┌──────────────┐
-│ Tree-sitter  │  Parse AST for every file
-│   Parser     │  Extract: functions, classes, calls, imports
-└──────┬───────┘
-       │
-       ▼
-┌──────────────┐
-│  Resolution  │  Resolve all calls to definitions
-│   Engine     │  Track: variable types, inheritance, imports
-└──────┬───────┘
-       │
-       ▼
-┌──────────────┐
-│   SQLite     │  Store: nodes (functions/classes)
-│  Database    │         edges (calls/imports)
-└──────┬───────┘
-       │
-       ├─────────────┬─────────────┐
-       ▼             ▼             ▼
-┌───────────┐  ┌───────────┐  ┌───────────┐
-│ MCP Tools │  │   Stats   │  │  Impact   │
-│  Impact   │  │ Reporting │  │ Analysis  │
-│  Callers  │  │           │  │           │
-└───────────┘  └───────────┘  └───────────┘
-```
-
-## Use Cases
-
-### Before Refactoring
-```bash
-codemap index
-# Ask Claude: "Show me everything that calls UserService.authenticate"
-# → Make informed decisions about API changes
+┌──────────────────────────────────────────────────────────────┐
+│  Step 1: codemap init                                        │
+│  • Parse all files with Tree-sitter                          │
+│  • Extract: functions, classes, calls, imports              │
+│  • Resolve: variable types, inheritance, cross-file refs    │
+│  • Store: SQLite database (.codemap/graph.db)               │
+│  • Configure: MCP server in Claude Code                     │
+└──────────────────────────────────────────────────────────────┘
+           │
+           ▼
+┌──────────────────────────────────────────────────────────────┐
+│  Step 2: codemap impact (before PR)                          │
+│  • Detect: git diff finds changed files                      │
+│  • Parse: extract changed function names                     │
+│  • Re-index: only modified files (fast!)                     │
+│  • Calculate: who calls changed functions                    │
+│  • Report: risk level + affected files                       │
+└──────────────────────────────────────────────────────────────┘
+           │
+           ▼
+┌──────────────────────────────────────────────────────────────┐
+│  Step 3: Ask Claude (via MCP)                                │
+│  • Claude calls: codemap_impact / codemap_trace_flow         │
+│  • Returns: markdown with analysis                           │
+│  • You decide: safe to merge or need more testing            │
+└──────────────────────────────────────────────────────────────┘
 ```
 
-### Understanding Legacy Code
+## Real-World Workflows
+
+### Workflow 1: Before Refactoring
+
 ```bash
-codemap index
-# Ask Claude: "How does the payment flow work from API to database?"
-# → Get complete execution traces
+# Scenario: Need to change authenticate_user() signature
+
+# Step 1: Check current state
+npx codemap-ai init
+
+# Step 2: Ask Claude
+# "Show me all functions that call authenticate_user"
+# Claude uses codemap_callers → Shows 25 callers
+
+# Step 3: Make changes
+vim authentication.py
+
+# Step 4: Check impact
+npx codemap-ai impact
+# → HIGH risk: 25 functions affected
+
+# Step 5: Ask Claude for help
+# "Review the impact of my authentication changes"
+# Claude analyzes and suggests testing strategy
 ```
 
-### Security Audits
+---
+
+### Workflow 2: Understanding Legacy Code
+
 ```bash
-codemap index
-# Ask Claude: "Find all functions that access user credentials"
-# → Trace data flow through the system
+# Scenario: New to codebase, need to understand payment flow
+
+# Step 1: Initialize
+npx codemap-ai init
+
+# Step 2: Ask Claude
+# "How does payment processing work from API to database?"
+# Claude uses codemap_trace_flow → Shows complete path
+
+# Step 3: Deep dive
+# "What calls process_payment?"
+# Claude uses codemap_callers → Shows all entry points
 ```
 
-### Dependency Analysis
+---
+
+### Workflow 3: Pre-PR Safety Check
+
 ```bash
-codemap index
-# Ask Claude: "What would break if I remove this utility function?"
-# → Impact analysis before deletion
+# Scenario: Made changes to 10 files, need PR review
+
+# Step 1: Already initialized (ran init on day 1)
+
+# Step 2: Check impact
+npx codemap-ai impact
+# → Detects 10 modified files
+# → Shows 3 changed functions
+# → 15 callers affected
+# → MEDIUM risk
+
+# Step 3: Ask Claude
+# "Analyze the impact of my changes and suggest test cases"
+# Claude reviews impact report + generates test plan
+
+# Step 4: Create PR with confidence
 ```
 
+---
+
 ## Advanced Features
 
+### Smart Git Integration
+
+CodeMap uses `git diff` to detect exactly what changed:
+
+```python
+# Before: def authenticate_user(token: str)
+# After:  def authenticate_user(token: str, role: str)  # Added parameter
+
+# codemap impact detects:
+# - Signature changed at line 120
+# - 25 callers need updating
+# - Risk: HIGH
+```
+
+**Fallback:** If not a git repo, uses file hash comparison.
+
+---
+
 ### Incremental Indexing
 
-CodeMap uses file hashing to only re-index changed files:
+CodeMap only re-indexes changed files:
 
 ```bash
-# First run: indexes all 290 files
-codemap index
+# First run: Index all 290 files (5 seconds)
+codemap init
+
+# Edit 2 files...
 
-# Second run: only indexes changed files
-codemap index
-→ Indexed: 3 files, Skipped: 287 files (unchanged)
+# Second run: Only index 2 files (< 1 second)
+codemap impact
 ```
 
+Uses SHA-256 file hashing for change detection.
+
+---
+
 ### Variable Type Tracking
 
 Resolves method calls through type inference:
@@ -243,6 +412,8 @@ user = UserService()  # Type tracked
 user.authenticate()   # ✅ Resolved to UserService.authenticate
 ```
 
+---
+
 ### Super() Resolution
 
 Follows inheritance chains:
@@ -253,20 +424,24 @@ class Child(Parent):
         super().method()  # ✅ Resolved to Parent.method
 ```
 
-### Database Operation Detection
+---
+
+### Database Operation Tracking
 
 Tracks MongoDB operations:
 
 ```python
 db.users.find_one({"id": user_id})
-# ✅ Tracked as database operation: find_one on users collection
+# ✅ Tracked as: find_one on users collection
 ```
 
+---
+
 ## Performance
 
 - **Indexing Speed**: ~290 files in 2-3 seconds
-- **Resolution Rate**: 25% internal calls (75% are external libraries/builtins)
-- **Incremental Updates**: Only re-indexes changed files
+- **Impact Analysis**: < 1 second (only re-indexes changed files)
+- **Resolution Rate**: 25% (75% are external libraries - expected)
 - **Memory Usage**: ~50MB for 290 Python files
 - **Database Size**: ~2MB for 290 files, 16K nodes, 12K edges
 
@@ -274,31 +449,54 @@ db.users.find_one({"id": user_id})
 
 CodeMap stores data in `.codemap/graph.db` (SQLite) in your project root.
 
-**File patterns:**
-- Default include: `**/*.py`, `**/*.ts`, `**/*.tsx`, `**/*.js`, `**/*.jsx`
-- Default exclude: `**/node_modules/**`, `**/__pycache__/**`, `**/venv/**`
-- Max file size: 200KB (larger files skipped)
+**Default patterns:**
+- Include: `**/*.py`, `**/*.ts`, `**/*.tsx`, `**/*.js`, `**/*.jsx`
+- Exclude: `**/node_modules/**`, `**/__pycache__/**`, `**/venv/**`
+- Max file size: 200KB
+
+**Custom patterns:**
+```bash
+codemap init \
+  --include "src/**/*.py" "lib/**/*.py" \
+  --exclude "**/tests/**" "**/migrations/**"
+```
 
 ## Troubleshooting
 
-### No functions detected
-- Check file patterns with `--include` and `--exclude`
-- Ensure files are under 200KB
-- Verify supported language (.py, .ts, .js)
+### "Not initialized" error
+```bash
+# Run init first
+npx codemap-ai init
+```
+
+### No changes detected
+```bash
+# Make sure you have uncommitted changes
+git status
+
+# Or force re-index
+npx codemap-ai reindex
+```
+
+### MCP not working in Claude Code
+```bash
+# Check if MCP is configured
+cat ~/.claude/config.json
+
+# Re-run init to reconfigure
+npx codemap-ai init
+
+# Restart Claude Code
+```
 
 ### Low resolution rate
 - Normal for projects with many external libraries
 - Internal calls should resolve at ~90%+
-- Use `codemap_search` to find unresolved patterns
-
-### MCP server not connecting
-- Ensure Claude Code is running
-- Check `~/.claude/config.json` for MCP configuration
-- Restart Claude Code after adding MCP server
+- Use `codemap_callers` to verify specific functions
 
 ## Contributing
 
-CodeMap is focused on call graph accuracy and performance. We welcome:
+We welcome contributions focused on:
 - Parser improvements for better resolution
 - New language support (Go, Rust, Java)
 - Framework-specific pattern detection
@@ -317,3 +515,30 @@ Sahan Nishshanka, JUST ADD AI GmbH
 - Repository: https://github.com/justaddai/codemap-ai
 - Issues: https://github.com/justaddai/codemap-ai/issues
 - NPM: https://www.npmjs.com/package/codemap-ai
+
+---
+
+## Why CodeMap?
+
+**Traditional approach:**
+```
+Developer: "I need to change this function..."
+Developer: *searches codebase manually*
+Developer: *finds 10 references*
+Developer: *misses 15 hidden callers*
+Developer: *deploys*
+💥 Production breaks
+```
+
+**With CodeMap:**
+```
+Developer: "I need to change this function..."
+Developer: npx codemap-ai impact
+Developer: "Shows 25 callers - HIGH risk"
+Claude: "Here's a test plan for all affected areas"
+Developer: *tests thoroughly*
+Developer: *deploys with confidence*
+✅ Production stable
+```
+
+**Stop breaking prod. Use CodeMap.** 🚀