CLAUDE.md

CLAUDE.md

@@ -0,0 +1,134 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+CodeGraph is a local-first code intelligence system that builds a semantic knowledge graph from any codebase. It provides structural understanding of code relationships using tree-sitter for AST parsing and SQLite for storage.
+
+**Key characteristics:**
+- Headless library (no UI) - purely an API
+- Node.js runtime (works standalone, in Electron, or any Node environment)
+- Per-project data stored in `.codegraph/` directory
+- Deterministic extraction from AST, not AI-generated summaries
+
+## Build and Development Commands
+
+```bash
+# Build
+npm run build          # Compile TypeScript and copy assets
+
+# Test
+npm test               # Run all tests once
+npm run test:watch     # Run tests in watch mode
+
+# Clean
+npm run clean          # Remove dist/ directory
+```
+
+## Running a Single Test
+
+```bash
+npx vitest run __tests__/extraction.test.ts           # Run specific test file
+npx vitest run __tests__/extraction.test.ts -t "TypeScript"  # Run tests matching pattern
+```
+
+## Architecture
+
+### Core Module Structure
+
+```
+src/
+├── index.ts              # Main CodeGraph class - public API entry point
+├── types.ts              # All TypeScript interfaces and types
+├── db/                   # SQLite database layer
+│   ├── index.ts          # DatabaseConnection class
+│   ├── queries.ts        # QueryBuilder with prepared statements
+│   └── schema.sql        # Table definitions with FTS5 search
+├── extraction/           # Tree-sitter AST parsing
+│   ├── index.ts          # ExtractionOrchestrator
+│   ├── tree-sitter.ts    # Universal parser wrapper
+│   └── grammars.ts       # Language detection and grammar loading
+├── resolution/           # Reference resolver
+│   ├── index.ts          # ReferenceResolver orchestrator
+│   ├── import-resolver.ts
+│   ├── name-matcher.ts
+│   └── frameworks/       # Framework-specific patterns (React, Express, Laravel, etc.)
+├── graph/                # Graph traversal and queries
+│   ├── index.ts          # GraphQueryManager
+│   ├── traversal.ts      # GraphTraverser (BFS/DFS, impact radius)
+│   └── queries.ts        # High-level graph queries
+├── vectors/              # Semantic search with embeddings
+│   ├── index.ts          # VectorManager
+│   ├── embedder.ts       # ONNX runtime + model loading
+│   └── search.ts         # Similarity search
+├── context/              # Context building for AI assistants
+│   ├── index.ts          # ContextBuilder
+│   └── formatter.ts      # Markdown/JSON output formatting
+├── sync/                 # Incremental update system
+│   ├── index.ts
+│   └── git-hooks.ts      # Post-commit hook management
+├── mcp/                  # Model Context Protocol server
+│   ├── index.ts          # MCPServer class
+│   ├── tools.ts          # MCP tool definitions
+│   └── transport.ts      # Stdio transport
+└── bin/codegraph.ts      # CLI entry point
+```
+
+### Key Classes
+
+- **CodeGraph** (`src/index.ts`): Main entry point. Lifecycle methods (`init`, `open`, `close`), indexing (`indexAll`, `sync`), graph queries (`traverse`, `getCallGraph`, `getImpactRadius`), semantic search (`semanticSearch`, `findSimilar`), context building (`buildContext`)
+
+- **ExtractionOrchestrator** (`src/extraction/index.ts`): Coordinates file scanning, parsing, and storing. Uses tree-sitter native bindings for each supported language
+
+- **GraphTraverser** (`src/graph/traversal.ts`): BFS/DFS traversal, call graph construction, impact radius calculation, path finding
+
+- **VectorManager** (`src/vectors/manager.ts`): Manages embeddings using `@xenova/transformers` for ONNX inference. Stores vectors in SQLite BLOB format
+
+- **ReferenceResolver** (`src/resolution/index.ts`): Resolves unresolved references after full indexing using framework patterns, import resolution, and name matching
+
+### Database Schema
+
+SQLite database with:
+- `nodes`: Code symbols (functions, classes, methods, etc.)
+- `edges`: Relationships (calls, imports, extends, contains, etc.)
+- `files`: Tracked source files with content hashes
+- `unresolved_refs`: References pending resolution
+- `vectors`: Embeddings stored as BLOBs
+- `nodes_fts`: FTS5 virtual table for full-text search
+
+### Supported Languages
+
+TypeScript, JavaScript, TSX, JSX, Python, Go, Rust, Java, C, C++, C#, PHP, Ruby, Swift, Kotlin
+
+### Node and Edge Types
+
+**NodeKind**: `file`, `module`, `class`, `struct`, `interface`, `trait`, `protocol`, `function`, `method`, `property`, `field`, `variable`, `constant`, `enum`, `enum_member`, `type_alias`, `namespace`, `parameter`, `import`, `export`, `route`, `component`
+
+**EdgeKind**: `contains`, `calls`, `imports`, `exports`, `extends`, `implements`, `references`, `type_of`, `returns`, `instantiates`, `overrides`, `decorates`
+
+## CLI Usage
+
+```bash
+codegraph init [path]       # Initialize in project
+codegraph index [path]      # Full index
+codegraph sync [path]       # Incremental update
+codegraph status [path]     # Show statistics
+codegraph query <search>    # Search symbols
+codegraph context <task>    # Build context for AI
+codegraph hooks install     # Install git auto-sync
+codegraph serve --mcp       # Start MCP server
+```
+
+## Test Structure
+
+Tests are in `__tests__/` directory with files mirroring the module structure:
+- `foundation.test.ts` - Database, config, directory management
+- `extraction.test.ts` - Tree-sitter parsing for all languages
+- `resolution.test.ts` - Reference resolution
+- `graph.test.ts` - Traversal and graph queries
+- `vectors.test.ts` - Embedding and semantic search
+- `context.test.ts` - Context building
+- `sync.test.ts` - Incremental updates and git hooks
+
+Tests use temporary directories created with `fs.mkdtempSync` and cleaned up after each test.