From dc91d8adb8dab8c3d4e60b166b251ac6d675ef9a Mon Sep 17 00:00:00 2001 From: Colby McHenry Date: Sun, 18 Jan 2026 16:49:39 -0600 Subject: [PATCH] CLAUDE.md --- CLAUDE.md | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..2d799d0 --- /dev/null +++ b/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 symbols +codegraph context # 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.