codemap-ai 0.2.0 → 3.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sahan Nishshanka, JUST ADD AI GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 OR COPYRIGHT HOLDERS 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.

package/README.md

@@ -1,156 +1,544 @@
-# CodeMap
+# CodeMap AI
 
-AI-powered codebase knowledge graph generator with Claude Code integration.
+**Call graph analyzer for understanding code impact and execution flows - built for Claude Code**
 
-**One command to understand your entire codebase.**
+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.
 
-## Quick Start
+## 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
+- 💾 **Incremental Updates** - Only re-indexes changed files (git-aware)
+- 🤖 **Claude Code Integration** - MCP server for AI-powered code queries
+
+## Installation
 
 ```bash
-# Initialize everything in one command
+# Use directly with npx (recommended)
 npx codemap-ai init
 
-# That's it! Now use skills in Claude Code:
-# /architecture - Project overview
-# /patterns     - Code conventions
-# /impact       - Change analysis
+# Or install globally
+npm install -g codemap-ai
 ```
 
-## What It Does
+## Quick Start (3 Commands)
+
+```bash
+# 1. First time: Initialize (indexes + configures Claude Code)
+npx codemap-ai init
 
-1. **Scans** your codebase using Tree-sitter (Python, TypeScript, JavaScript)
-2. **Builds** a knowledge graph of all functions, classes, imports, and calls
-3. **Generates** Claude Code skills that understand your project
-4. **Connects** to Claude Code via MCP for intelligent queries
+# 2. Before PR: Check impact of your changes
+npx codemap-ai impact
 
-## Installation
+# 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 init` - First-Time Setup
+
+Initialize CodeMap in your project (one command does everything):
 
 ```bash
-# Option 1: Use directly with npx (recommended)
+cd /path/to/project
 npx codemap-ai init
+```
 
-# Option 2: Install globally
-npm install -g codemap-ai
-codemap init
+**What it does:**
+1. Indexes your entire codebase
+2. Automatically configures MCP server in Claude Code
+3. Ready to ask questions!
+
+**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?'
 ```
 
-## Commands
+**Options:**
+- `--skip-mcp` - Skip MCP server configuration
+- `--include <patterns>` - File patterns to include
+- `--exclude <patterns>` - File patterns to exclude
 
-### `codemap init` (Recommended)
+---
 
-**One command that does everything:**
+### `codemap impact` - Check What Changed
+
+Analyze the impact of your uncommitted changes (smart git integration):
 
 ```bash
-npx codemap-ai init /path/to/project --name "My Project"
+# 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:**
+```
+✔ Detected 2 modified files
+
+Modified Files:
+  • chat.py
+  • authentication.py
+
+Changed Functions:
+  • handle_chat (chat.py:47)
+  • authenticate_user (authentication.py:120)
+
+Impact Analysis:
+  handle_chat:
+    12 direct callers
+  authenticate_user:
+    25 direct callers ⚠️
+
+Affected HTTP Endpoints:
+  • POST /api/chat
+  • POST /api/agents
+
+Risk Assessment:
+  HIGH - 37 functions affected
+```
+
+**Options:**
+- `-v, --verbose` - Show detailed caller information
+
+**Use cases:**
+- Before creating a PR
+- After refactoring
+- When debugging regressions
+
+---
+
+### `codemap reindex` - Force Full Rebuild
+
+Force re-index everything from scratch:
+
+```bash
+npx codemap-ai reindex
+```
+
+**When to use:**
+- After pulling major changes
+- After changing many files
+- When you want to rebuild the entire graph
+
+---
+
+## Claude Code Integration (MCP Tools)
+
+Once you run `codemap init`, Claude gains these capabilities via MCP:
+
+### 1. `codemap_impact` - Analyze Change Impact
+
+**Ask Claude:**
+> "If I change authenticate_user, what breaks?"
+
+**Claude uses:** `codemap_impact` tool
+
+**Returns:**
+- Direct callers (functions that call it)
+- Total impact (affected functions/files)
+- Risk level (LOW/MEDIUM/HIGH)
+- Recommendations
+
+**Example response:**
+```
+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.
+```
+
+---
+
+### 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:**
+```
+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
+```
+
+---
+
+### 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:**
+```
+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
+...
 ```
 
-This will:
-1. Scan your codebase and build the knowledge graph
-2. Generate Claude Code skills
-3. Add the MCP server to Claude Code
+---
 
-Options:
-- `--name <name>` - Project name for skill descriptions
-- `--skip-mcp` - Skip adding MCP server (just scan + skills)
+## Supported Languages
+
+| Language   | Parsing | Imports | Calls | Classes | Methods | Inheritance |
+|------------|---------|---------|-------|---------|---------|-------------|
+| Python     | ✅      | ✅      | ✅    | ✅      | ✅      | ✅          |
+| TypeScript | ✅      | ✅      | ✅    | ✅      | ✅      | ✅          |
+| JavaScript | ✅      | ✅      | ✅    | ✅      | ✅      | ✅          |
+
+## Framework Detection
+
+**FastAPI** (Python):
+- HTTP route decorators: `@router.post("/chat")`
+- Dependency injection: `Depends(get_user)`
+- Request handlers and middleware
+
+**Coming Soon:**
+- Django views and models
+- Express.js routes
+- React component hierarchy
+
+## How It Works
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  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            │
+└──────────────────────────────────────────────────────────────┘
+```
 
-### `codemap serve`
+## Real-World Workflows
 
-Start the web visualization:
+### Workflow 1: Before Refactoring
 
 ```bash
-npx codemap-ai serve
+# 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
 ```
 
-Opens an interactive graph at `http://localhost:3333`
+---
+
+### Workflow 2: Understanding Legacy Code
 
-### `codemap stats`
+```bash
+# Scenario: New to codebase, need to understand payment flow
+
+# Step 1: Initialize
+npx codemap-ai init
 
-Show codebase statistics:
+# 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
+```
+
+---
+
+### Workflow 3: Pre-PR Safety Check
 
 ```bash
-npx codemap-ai stats
+# 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
 ```
 
-### `codemap affected <target>`
+---
+
+## Advanced Features
+
+### Smart Git Integration
 
-Analyze what files would be affected by changes:
+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 only re-indexes changed files:
 
 ```bash
-npx codemap-ai affected src/auth/login.ts
-npx codemap-ai affected UserService
+# First run: Index all 290 files (5 seconds)
+codemap init
+
+# Edit 2 files...
+
+# Second run: Only index 2 files (< 1 second)
+codemap impact
 ```
 
-## Generated Skills
+Uses SHA-256 file hashing for change detection.
 
-After initialization, these skills are available in Claude Code:
+---
 
-| Skill | Description |
-|-------|-------------|
-| `/architecture` | Project overview, stats, directory structure |
-| `/patterns` | Key classes, common functions, conventions |
-| `/impact <file>` | What's affected by changes to a file |
-| `/navigate <query>` | Find code by name |
-| `/dependencies <file>` | Import/export relationships |
+### Variable Type Tracking
 
-## How It Works
+Resolves method calls through type inference:
 
+```python
+user = UserService()  # Type tracked
+user.authenticate()   # ✅ Resolved to UserService.authenticate
 ```
-┌──────────────┐      ┌─────────────┐      ┌──────────────┐
-│  Your Code   │ ───► │ Tree-sitter │ ───► │ Knowledge    │
-│  .ts/.py/.js │      │   Parser    │      │ Graph (SQLite)│
-└──────────────┘      └─────────────┘      └──────────────┘
-                                                  │
-                      ┌───────────────────────────┼───────────────────────────┐
-                      │                           │                           │
-                      ▼                           ▼                           ▼
-               ┌─────────────┐             ┌─────────────┐             ┌─────────────┐
-               │ Skills      │             │ MCP Server  │             │ Web UI      │
-               │ /impact     │             │ codemap_*   │             │ Graph Viz   │
-               │ /patterns   │             │ tools       │             │             │
-               └─────────────┘             └─────────────┘             └─────────────┘
+
+---
+
+### Super() Resolution
+
+Follows inheritance chains:
+
+```python
+class Child(Parent):
+    def method(self):
+        super().method()  # ✅ Resolved to Parent.method
 ```
 
-## Supported Languages
+---
+
+### Database Operation Tracking
+
+Tracks MongoDB operations:
+
+```python
+db.users.find_one({"id": user_id})
+# ✅ Tracked as: find_one on users collection
+```
+
+---
+
+## Performance
 
-| Language | Parsing | Imports | Calls | Classes |
-|----------|---------|---------|-------|---------|
-| TypeScript | ✅ | ✅ | ✅ | ✅ |
-| JavaScript | ✅ | ✅ | ✅ | ✅ |
-| Python | ✅ | ✅ | ✅ | ✅ |
-| Go | 🚧 | 🚧 | 🚧 | 🚧 |
-| Rust | 🚧 | 🚧 | 🚧 | 🚧 |
+- **Indexing Speed**: ~290 files in 2-3 seconds
+- **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
 
-## Advanced Usage
+## Configuration
 
-### Individual Commands
+CodeMap stores data in `.codemap/graph.db` (SQLite) in your project root.
 
-If you prefer step-by-step:
+**Default patterns:**
+- Include: `**/*.py`, `**/*.ts`, `**/*.tsx`, `**/*.js`, `**/*.jsx`
+- Exclude: `**/node_modules/**`, `**/__pycache__/**`, `**/venv/**`
+- Max file size: 200KB
 
+**Custom patterns:**
 ```bash
-# Step 1: Scan
-npx codemap-ai scan /path/to/project
+codemap init \
+  --include "src/**/*.py" "lib/**/*.py" \
+  --exclude "**/tests/**" "**/migrations/**"
+```
 
-# Step 2: Generate skills
-npx codemap-ai generate-skills /path/to/project --name "My Project"
+## Troubleshooting
 
-# Step 3: Add MCP server (optional, for database queries)
-claude mcp add codemap -- npx codemap-ai mcp-server --path /path/to/project
+### "Not initialized" error
+```bash
+# Run init first
+npx codemap-ai init
 ```
 
-### MCP Tools
+### No changes detected
+```bash
+# Make sure you have uncommitted changes
+git status
 
-When the MCP server is connected, Claude Code gains these tools:
+# Or force re-index
+npx codemap-ai reindex
+```
 
-- `codemap_search` - Search functions, classes, files
-- `codemap_callers` - Find who calls a function
-- `codemap_dependencies` - Get import relationships
-- `codemap_impact` - Analyze change impact
-- `codemap_stats` - Get codebase statistics
+### MCP not working in Claude Code
+```bash
+# Check if MCP is configured
+cat ~/.claude/config.json
 
-## Author
+# 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_callers` to verify specific functions
+
+## Contributing
 
-Sahan Nishshanka (Hub.KI GmbH)
+We welcome contributions focused on:
+- Parser improvements for better resolution
+- New language support (Go, Rust, Java)
+- Framework-specific pattern detection
+- Performance optimizations
 
 ## License
 
-MIT
+MIT License - see [LICENSE](LICENSE) file
+
+## Author
+
+Sahan Nishshanka, JUST ADD AI GmbH
+
+## Links
+
+- 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.** 🚀