codemap-ai 0.1.2 → 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,181 +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**
 
-**CodeMap** scans your codebase, builds a knowledge graph of all functions, classes, imports, and their relationships, then generates Claude Code skills that help the AI understand your project.
+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
 
-- **Multi-language support**: Python, TypeScript, JavaScript (more coming)
-- **Knowledge graph**: SQLite-based graph of code relationships
-- **Auto-generated skills**: Creates Claude Code skills from your codebase
-- **Impact analysis**: See what files are affected by changes
-- **Web visualization**: Interactive D3 force-directed graph
-- **MCP server**: Direct integration with Claude Code
+- 🔍 **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
-# Scan your project
-npx codemap-ai scan /path/to/project
+# Index your codebase
+npx codemap-ai index /path/to/project
 
-# Generate Claude Code skills
-npx codemap-ai generate-skills /path/to/project
+# Start MCP server for Claude Code
+npx codemap-ai mcp-server
 
-# Start visualization server
-npx codemap-ai serve /path/to/project
+# Add to Claude Code (one-time setup)
+claude mcp add codemap -- npx codemap-ai mcp-server --path /path/to/project
 ```
 
 ## Commands
 
-### `codemap scan [path]`
+### `codemap index [path]`
 
-Scan a codebase and build the knowledge graph.
+Build a call graph of your codebase:
 
 ```bash
-codemap scan .
-codemap scan /path/to/project --clean
-codemap scan . --include "src/**/*.ts" --exclude "**/*.test.ts"
+# Index current directory
+codemap index
+
+# 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/**"
 ```
 
-Options:
-- `-o, --output <dir>` - Output directory (default: `.codemap`)
-- `--include <patterns...>` - Glob patterns to include
-- `--exclude <patterns...>` - Glob patterns to exclude
-- `--clean` - Clear existing data before scanning
+**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)
 
-### `codemap generate-skills [path]`
+**Output:**
+```
+CodeMap Call Graph Indexer
+
+Indexed:    290 files
+Resolved:   3,987 function calls
+Unresolved: 12,253 calls (external/dynamic)
+
+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`
 
-Generate Claude Code skills from the knowledge graph.
+Start the MCP server for Claude Code integration:
 
 ```bash
-codemap generate-skills .
-codemap generate-skills . --name "My Project"
+codemap mcp-server --path /path/to/project
 ```
 
-This creates skills in `.claude/skills/codemap/`:
-- `/architecture` - Project structure overview
-- `/patterns` - Common code patterns
-- `/dependencies` - Dependency explorer
-- `/impact` - Change impact analysis
-- `/navigate` - Code navigation helper
+**Options:**
+- `--path <path>` - Path to indexed project (default: current directory)
 
-### `codemap affected <target>`
+## MCP Tools for Claude Code
 
-Show files that would be affected by changes.
+Once connected via MCP, Claude gains these capabilities:
 
-```bash
-codemap affected src/auth/login.ts
-codemap affected UserService
-codemap affected handleSubmit --depth 3
+### `codemap_callers`
+Find all functions that call a specific function:
+
+```
+Claude: "What calls the authenticate_user function?"
+→ Returns: 12 callers with file:line references
 ```
 
-### `codemap stats`
+### `codemap_impact`
+Analyze the blast radius of changing code:
+
+```
+Claude: "If I change authenticate_user, what breaks?"
+→ Returns: 15 affected files, call chain, risk level
+```
 
-Show statistics about the analyzed codebase.
+### `codemap_trace_flow`
+Trace execution paths between functions:
 
-```bash
-codemap stats
 ```
+Claude: "Show me the flow from chat endpoint to database"
+→ Returns: handle_chat → authenticate → get_handler → save_chat → db.insert
+```
+
+### `codemap_dependencies`
+Get import/export relationships:
 
-### `codemap serve [path]`
+```
+Claude: "What does auth.py import?"
+→ Returns: All imports and what they're used for
+```
 
-Start the web visualization server.
+### `codemap_search`
+Search for functions, classes, files:
 
-```bash
-codemap serve .
-codemap serve . --port 8080
+```
+Claude: "Find all database operations"
+→ Returns: 476 operations (find_one: 137, update_one: 122, ...)
 ```
 
-Opens an interactive graph at `http://localhost:3333`.
+## Supported Languages
 
-### `codemap mcp-server`
+| Language   | Parsing | Imports | Calls | Classes | Methods |
+|------------|---------|---------|-------|---------|---------|
+| Python     | ✅      | ✅      | ✅    | ✅      | ✅      |
+| TypeScript | ✅      | ✅      | ✅    | ✅      | ✅      |
+| JavaScript | ✅      | ✅      | ✅    | ✅      | ✅      |
 
-Start the MCP server for Claude Code integration.
+## Framework Detection
 
-```bash
-# Add to Claude Code
-claude mcp add codemap -- npx codemap-ai mcp-server --path /path/to/project
+CodeMap understands framework-specific patterns:
+
+**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
 
-# Or run directly
-codemap mcp-server --path .
 ```
+┌──────────────┐
+│  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
 
-## MCP Tools
+### Before Refactoring
+```bash
+codemap index
+# Ask Claude: "Show me everything that calls UserService.authenticate"
+# → Make informed decisions about API changes
+```
 
-When connected to Claude Code, these tools become available:
+### Understanding Legacy Code
+```bash
+codemap index
+# Ask Claude: "How does the payment flow work from API to database?"
+# → Get complete execution traces
+```
 
-- `codemap_search` - Search for functions, classes, files
-- `codemap_callers` - Find all callers of a function
-- `codemap_dependencies` - Get import/dependency info
-- `codemap_impact` - Analyze change impact
-- `codemap_stats` - Get codebase statistics
-- `codemap_file_contents` - List contents of a file
+### Security Audits
+```bash
+codemap index
+# Ask Claude: "Find all functions that access user credentials"
+# → Trace data flow through the system
+```
 
-## Generated Skills
+### Dependency Analysis
+```bash
+codemap index
+# Ask Claude: "What would break if I remove this utility function?"
+# → Impact analysis before deletion
+```
 
-After running `generate-skills`, Claude Code can use these commands:
+## Advanced Features
 
-### `/architecture`
-Shows project structure, statistics, and key directories.
+### Incremental Indexing
 
-### `/patterns`
-Explains common patterns, key classes, and coding conventions.
+CodeMap uses file hashing to only re-index changed files:
 
-### `/dependencies [module]`
-Explores what a module imports and what imports it.
+```bash
+# First run: indexes all 290 files
+codemap index
 
-### `/impact [file or function]`
-Analyzes what would be affected by changes.
+# Second run: only indexes changed files
+codemap index
+→ Indexed: 3 files, Skipped: 287 files (unchanged)
+```
 
-### `/navigate [query]`
-Finds and navigates to specific code.
+### Variable Type Tracking
 
-## Programmatic Usage
+Resolves method calls through type inference:
 
-```typescript
-import { scan, generateSkills, scanAndGenerate } from 'codemap-ai';
+```python
+user = UserService()  # Type tracked
+user.authenticate()   # ✅ Resolved to UserService.authenticate
+```
 
-// Scan only
-const { analysis, dbPath } = await scan('/path/to/project');
+### Super() Resolution
 
-// Generate skills from existing scan
-const skills = generateSkills('/path/to/project', 'My Project');
+Follows inheritance chains:
 
-// Scan and generate in one step
-const result = await scanAndGenerate('/path/to/project', 'My Project');
+```python
+class Child(Parent):
+    def method(self):
+        super().method()  # ✅ Resolved to Parent.method
 ```
 
-## How It Works
+### Database Operation Detection
 
-1. **Parsing**: Uses Tree-sitter to parse source files into ASTs
-2. **Graph Building**: Extracts nodes (files, functions, classes) and edges (imports, calls, extends)
-3. **Storage**: Stores everything in a SQLite database for fast queries
-4. **Skill Generation**: Analyzes the graph to create helpful Claude Code skills
-5. **MCP Server**: Exposes graph queries as MCP tools
+Tracks MongoDB operations:
 
-## Supported Languages
+```python
+db.users.find_one({"id": user_id})
+# ✅ Tracked as database operation: find_one on users collection
+```
 
-| Language | Parsing | Imports | Calls | Classes |
-|----------|---------|---------|-------|---------|
-| TypeScript | ✅ | ✅ | ✅ | ✅ |
-| JavaScript | ✅ | ✅ | ✅ | ✅ |
-| Python | ✅ | ✅ | ✅ | ✅ |
-| Go | 🚧 | 🚧 | 🚧 | 🚧 |
-| Rust | 🚧 | 🚧 | 🚧 | 🚧 |
+## 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
 
-Create a `codemap.config.json` in your project root:
+CodeMap stores data in `.codemap/graph.db` (SQLite) in your project root.
 
-```json
-{
-  "include": ["src/**/*.ts", "lib/**/*.py"],
-  "exclude": ["**/*.test.ts", "**/node_modules/**"],
-  "languages": ["typescript", "python"]
-}
-```
+**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