codemap-ai 0.2.0 → 3.0.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,319 @@
-# 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 of your codebase 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
+- 🤖 **Claude Code Integration** - MCP server for AI-powered code queries
+
+## Installation
+
+```bash
+# Use directly with npx (recommended)
+npx codemap-ai index /path/to/project
+
+# Or install globally
+npm install -g codemap-ai
+```
 
 ## Quick Start
 
 ```bash
-# Initialize everything in one command
-npx codemap-ai init
+# Index your codebase
+npx codemap-ai index /path/to/project
+
+# Start MCP server for Claude Code
+npx codemap-ai mcp-server
 
-# That's it! Now use skills in Claude Code:
-# /architecture - Project overview
-# /patterns     - Code conventions
-# /impact       - Change analysis
+# Add to Claude Code (one-time setup)
+claude mcp add codemap -- npx codemap-ai mcp-server --path /path/to/project
 ```
 
-## What It Does
+## Commands
 
-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
+### `codemap index [path]`
 
-## Installation
+Build a call graph of your codebase:
 
 ```bash
-# Option 1: Use directly with npx (recommended)
-npx codemap-ai init
+# Index current directory
+codemap index
 
-# Option 2: Install globally
-npm install -g codemap-ai
-codemap init
+# Index specific directory
+codemap index /path/to/project
+
+# Force re-index everything
+codemap index --force
+
+# Custom file patterns
+codemap index --include "src/**/*.py" --exclude "**/tests/**"
 ```
 
-## Commands
+**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)
+
+**Output:**
+```
+CodeMap Call Graph Indexer
 
-### `codemap init` (Recommended)
+Indexed:    290 files
+Resolved:   3,987 function calls
+Unresolved: 12,253 calls (external/dynamic)
 
-**One command that does everything:**
+Framework Detection:
+HTTP Endpoints: 283 routes detected
+Dependencies:   30/30 resolved (FastAPI Depends)
+
+Call resolution rate: 25%
+Database saved to: .codemap/graph.db
+```
+
+### `codemap mcp-server`
+
+Start the MCP server for Claude Code integration:
 
 ```bash
-npx codemap-ai init /path/to/project --name "My Project"
+codemap mcp-server --path /path/to/project
 ```
 
-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:**
+- `--path <path>` - Path to indexed project (default: current directory)
 
-Options:
-- `--name <name>` - Project name for skill descriptions
-- `--skip-mcp` - Skip adding MCP server (just scan + skills)
+## MCP Tools for Claude Code
 
-### `codemap serve`
+Once connected via MCP, Claude gains these capabilities:
 
-Start the web visualization:
+### `codemap_callers`
+Find all functions that call a specific function:
 
-```bash
-npx codemap-ai serve
+```
+Claude: "What calls the authenticate_user function?"
+→ Returns: 12 callers with file:line references
 ```
 
-Opens an interactive graph at `http://localhost:3333`
+### `codemap_impact`
+Analyze the blast radius of changing code:
 
-### `codemap stats`
+```
+Claude: "If I change authenticate_user, what breaks?"
+→ Returns: 15 affected files, call chain, risk level
+```
 
-Show codebase statistics:
+### `codemap_trace_flow`
+Trace execution paths between functions:
 
-```bash
-npx codemap-ai stats
+```
+Claude: "Show me the flow from chat endpoint to database"
+→ Returns: handle_chat → authenticate → get_handler → save_chat → db.insert
 ```
 
-### `codemap affected <target>`
+### `codemap_dependencies`
+Get import/export relationships:
 
-Analyze what files would be affected by changes:
+```
+Claude: "What does auth.py import?"
+→ Returns: All imports and what they're used for
+```
+
+### `codemap_search`
+Search for functions, classes, files:
 
-```bash
-npx codemap-ai affected src/auth/login.ts
-npx codemap-ai affected UserService
 ```
+Claude: "Find all database operations"
+→ Returns: 476 operations (find_one: 137, update_one: 122, ...)
+```
+
+## Supported Languages
+
+| Language   | Parsing | Imports | Calls | Classes | Methods |
+|------------|---------|---------|-------|---------|---------|
+| Python     | ✅      | ✅      | ✅    | ✅      | ✅      |
+| TypeScript | ✅      | ✅      | ✅    | ✅      | ✅      |
+| JavaScript | ✅      | ✅      | ✅    | ✅      | ✅      |
 
-## Generated Skills
+## Framework Detection
 
-After initialization, these skills are available in Claude Code:
+CodeMap understands framework-specific patterns:
 
-| 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 |
+**FastAPI:**
+- HTTP route decorators (`@router.post("/chat")`)
+- Dependency injection (`Depends()`)
+- Request handlers and middleware
+
+**Coming Soon:**
+- Django views and models
+- Express.js routes
+- React component hierarchy
 
 ## How It Works
 
 ```
-┌──────────────┐      ┌─────────────┐      ┌──────────────┐
-│  Your Code   │ ───► │ Tree-sitter │ ───► │ Knowledge    │
-│  .ts/.py/.js │      │   Parser    │      │ Graph (SQLite)│
-└──────────────┘      └─────────────┘      └──────────────┘
-                                                  │
-                      ┌───────────────────────────┼───────────────────────────┐
-                      │                           │                           │
-                      ▼                           ▼                           ▼
-               ┌─────────────┐             ┌─────────────┐             ┌─────────────┐
-               │ Skills      │             │ MCP Server  │             │ Web UI      │
-               │ /impact     │             │ codemap_*   │             │ Graph Viz   │
-               │ /patterns   │             │ tools       │             │             │
-               └─────────────┘             └─────────────┘             └─────────────┘
+┌──────────────┐
+│  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  │  │           │  │           │
+└───────────┘  └───────────┘  └───────────┘
 ```
 
-## Supported Languages
+## Use Cases
 
-| Language | Parsing | Imports | Calls | Classes |
-|----------|---------|---------|-------|---------|
-| TypeScript | ✅ | ✅ | ✅ | ✅ |
-| JavaScript | ✅ | ✅ | ✅ | ✅ |
-| Python | ✅ | ✅ | ✅ | ✅ |
-| Go | 🚧 | 🚧 | 🚧 | 🚧 |
-| Rust | 🚧 | 🚧 | 🚧 | 🚧 |
+### Before Refactoring
+```bash
+codemap index
+# Ask Claude: "Show me everything that calls UserService.authenticate"
+# → Make informed decisions about API changes
+```
 
-## Advanced Usage
+### Understanding Legacy Code
+```bash
+codemap index
+# Ask Claude: "How does the payment flow work from API to database?"
+# → Get complete execution traces
+```
 
-### Individual Commands
+### Security Audits
+```bash
+codemap index
+# Ask Claude: "Find all functions that access user credentials"
+# → Trace data flow through the system
+```
 
-If you prefer step-by-step:
+### Dependency Analysis
+```bash
+codemap index
+# Ask Claude: "What would break if I remove this utility function?"
+# → Impact analysis before deletion
+```
+
+## Advanced Features
+
+### Incremental Indexing
+
+CodeMap uses file hashing to only re-index changed files:
 
 ```bash
-# Step 1: Scan
-npx codemap-ai scan /path/to/project
+# First run: indexes all 290 files
+codemap index
 
-# Step 2: Generate skills
-npx codemap-ai generate-skills /path/to/project --name "My Project"
+# Second run: only indexes changed files
+codemap index
+→ Indexed: 3 files, Skipped: 287 files (unchanged)
+```
 
-# Step 3: Add MCP server (optional, for database queries)
-claude mcp add codemap -- npx codemap-ai mcp-server --path /path/to/project
+### Variable Type Tracking
+
+Resolves method calls through type inference:
+
+```python
+user = UserService()  # Type tracked
+user.authenticate()   # ✅ Resolved to UserService.authenticate
 ```
 
-### MCP Tools
+### Super() Resolution
 
-When the MCP server is connected, Claude Code gains these tools:
+Follows inheritance chains:
 
-- `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
+```python
+class Child(Parent):
+    def method(self):
+        super().method()  # ✅ Resolved to Parent.method
+```
 
-## Author
+### Database Operation Detection
 
-Sahan Nishshanka (Hub.KI GmbH)
+Tracks MongoDB operations:
+
+```python
+db.users.find_one({"id": user_id})
+# ✅ Tracked as database operation: 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
+- **Memory Usage**: ~50MB for 290 Python files
+- **Database Size**: ~2MB for 290 files, 16K nodes, 12K edges
+
+## Configuration
+
+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)
+
+## Troubleshooting
+
+### No functions detected
+- Check file patterns with `--include` and `--exclude`
+- Ensure files are under 200KB
+- Verify supported language (.py, .ts, .js)
+
+### 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
+
+## Contributing
+
+CodeMap is focused on call graph accuracy and performance. We welcome:
+- 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