purecontext-mcp 1.1.1 → 1.1.2

package/docs/dev/PHASE1_TASKS.md

@@ -1,443 +0,0 @@
-# Phase 1 — Task Breakdown
-
-**Goal**: Working MCP server that indexes JS/TS projects with symbol-level retrieval and dependency graph.
-
-**Approach**: Tasks are sequenced so each one builds on the previous. Complete them in order. Each task should be independently testable before moving to the next.
-
----
-
-## Task 1: Project Scaffolding
-
-Set up the TypeScript project with all tooling configured.
-
-**Deliverables:**
-- `package.json` with ES modules, scripts (build, dev, test, lint), and dependencies
-- `tsconfig.json` with strict mode, ES2022 target, NodeNext module resolution
-- `vitest.config.ts`
-- `.eslintrc.cjs` with TypeScript rules
-- `.gitignore`
-- Empty directory structure matching CLAUDE.md specification
-- `src/index.ts` entry point that prints version and exits
-
-**Dependencies to install:**
-- `typescript`, `@types/node`
-- `web-tree-sitter`
-- `better-sqlite3`, `@types/better-sqlite3`
-- `@modelcontextprotocol/sdk`
-- `chokidar`
-- `vitest` (dev)
-- `eslint`, `@typescript-eslint/parser`, `@typescript-eslint/eslint-plugin` (dev)
-
-**Verify:** `npm run build` succeeds, `npm run test` runs (no tests yet), `node dist/index.js` prints version.
-
----
-
-## Task 2: Core Types and Error System
-
-Define the foundational types and error classes that everything else depends on.
-
-**Deliverables:**
-- `src/core/types.ts` — `SymbolRecord`, `SymbolKind`, `ImportRecord`, `LanguageHandler`, `FrameworkAdapter`, `ProcessedBlock`, `RepoMetadata`, `IndexOptions`
-- `src/core/errors.ts` — `PureContextError` base class, `IndexError`, `ParseError`, `ConfigError`, `StorageError`
-- `src/core/logger.ts` — Simple leveled logger (debug/info/warn/error) that writes to stderr (stdout is reserved for MCP stdio transport)
-
-**Verify:** Types compile cleanly. Logger outputs formatted messages to stderr.
-
-**Tests:** Logger formatting test.
-
----
-
-## Task 3: SQLite Schema and Storage Layer
-
-Create the database schema and CRUD operations.
-
-**Deliverables:**
-- `src/core/db/schema.ts` — Table creation SQL, schema version, migration support
-  - `repos` table: id, root_path, symbol_count, file_count, languages (JSON), indexed_at, schema_version
-  - `symbols` table: id, repo_id, name, kind, file_path, start_byte, end_byte, signature, summary, framework_meta (JSON), indexed_at
-  - `files` table: repo_id, path, content_hash, raw_content (BLOB), indexed_at
-  - `dep_edges` table: repo_id, source_file, source_symbol_id (nullable), target_file, target_symbol_id (nullable), edge_type, specifier
-  - Indexes on: symbols(repo_id, name), symbols(repo_id, file_path), symbols(repo_id, kind), dep_edges(repo_id, source_file), dep_edges(repo_id, target_file)
-- `src/core/db/symbol-store.ts` — insertSymbols (batch), searchSymbols (FTS or LIKE), getSymbolById, getSymbolsByFile, getSymbolsByRepo, deleteByFile
-- `src/core/db/file-store.ts` — upsertFile, getFileContent, getFileHash, deleteFile
-- `src/core/db/dep-store.ts` — insertEdges (batch), getForwardDeps, getReverseDeps, getImportersOf, findDeadExports
-
-**Key decisions:**
-- Use `better-sqlite3` synchronous API (faster than async for local DB)
-- Database file at `~/.purecontext/indexes/{repoId}.db`
-- Repo ID = `SHA-256(absolutePath).slice(0, 16)`
-- Batch inserts use transactions for performance
-
-**Verify:** Can create DB, insert symbols, query by name, query deps.
-
-**Tests:** Unit tests for each store with an in-memory SQLite database.
-
----
-
-## Task 4: File Discovery and Hash Cache
-
-Build the file scanner that finds and prioritizes source files.
-
-**Deliverables:**
-- `src/core/file-discovery.ts`
-  - `discoverFiles(rootPath, options)` — recursively scan directory
-  - Respect `.gitignore` patterns (use a simple `.gitignore` parser or `ignore` npm package)
-  - Built-in exclusions: `node_modules/`, `.git/`, `dist/`, `build/`, `.claude/`, `.env*`, `*.lock`
-  - Priority ordering: `src/` > `lib/` > `app/` > `pages/` > `components/` > `server/` > everything else > `test/` > `__tests__/`
-  - File count limit (default 1000, configurable)
-  - Filter by supported extensions (from registered language handlers)
-  - Return: `DiscoveredFile[]` with path, size, priority
-- `src/core/hash-cache.ts`
-  - In-memory `Map<string, string>` (filePath → SHA-256 hash)
-  - `computeHash(content: Buffer): string`
-  - `hasChanged(filePath, newHash): boolean`
-  - `sync(db)` — persist to files table
-  - `loadFromDb(db, repoId)` — hydrate cache from SQLite on startup
-
-**Verify:** Scan a real project directory, get sorted file list, compute hashes.
-
-**Tests:** Test against `test/fixtures/basic-ts-project/` (create a small fixture with 5-10 files).
-
----
-
-## Task 5: Tree-sitter Integration
-
-Set up web-tree-sitter with WASM grammar loading.
-
-**Deliverables:**
-- Download and bundle WASM grammars into `grammars/`:
-  - `tree-sitter-typescript.wasm`
-  - `tree-sitter-tsx.wasm`
-  - `tree-sitter-javascript.wasm`
-- `src/core/parse-dispatcher.ts`
-  - `initParser()` — initialize web-tree-sitter, load WASM grammars
-  - `parseFile(source: Buffer, handler: LanguageHandler): Tree` — parse source with handler's grammar
-  - Grammar caching: load each grammar once, reuse across files
-- `src/handlers/handler-registry.ts`
-  - `registerHandler(handler: LanguageHandler)` — register by extensions
-  - `getHandler(filePath: string): LanguageHandler | null` — resolve by extension
-  - `getAllHandlers(): LanguageHandler[]`
-  - Auto-scan `src/handlers/` for handler files at startup
-
-**Key technical notes:**
-- `web-tree-sitter` requires calling `Parser.init()` before use (async, loads WASM runtime)
-- Grammar loading: `parser.setLanguage(await Parser.Language.load('path/to/grammar.wasm'))`
-- The Tree object holds the CST; traverse via `tree.rootNode`
-
-**Verify:** Parse a TypeScript file, walk the tree, print node types.
-
-**Tests:** Parse a known fixture file, verify root node type is `program`.
-
----
-
-## Task 6: TypeScript/JavaScript Language Handler
-
-The first (and for Phase 1, only) language handler.
-
-**Deliverables:**
-- `src/handlers/typescript.ts` — implements `LanguageHandler`
-  - `extensions()`: `['.ts', '.tsx', '.mts', '.cts']`
-  - `grammarPath()`: path to typescript/tsx WASM
-  - `extractSymbols()`: Walk AST, extract symbols from these node types:
-    - `function_declaration` → kind: 'function'
-    - `class_declaration` → kind: 'class'
-    - `method_definition` (inside class) → kind: 'method'
-    - `lexical_declaration` with `export` → kind: 'const' (for exported const/let)
-    - `type_alias_declaration` → kind: 'type'
-    - `interface_declaration` → kind: 'interface'
-    - `enum_declaration` → kind: 'enum'
-    - `arrow_function` assigned to exported const → kind: 'function'
-    - For each: capture name, byte offsets (startIndex/endIndex), build signature from the declaration line
-  - `extractImports()`: Find `import_statement` nodes, parse:
-    - Default imports, named imports, namespace imports
-    - `import type` detection
-    - Source specifier (the string after `from`)
-  - `extractDocstring()`: Look for comment node immediately preceding symbol node (JSDoc `/** */` pattern), extract first sentence
-
-- `src/handlers/javascript.ts` — implements `LanguageHandler`
-  - Mostly identical to TypeScript but with JS grammar
-  - `extensions()`: `['.js', '.jsx', '.mjs', '.cjs']`
-  - No type-specific nodes (type_alias, interface)
-
-**Key extraction logic:**
-```
-For each child of root:
-  If node.type is 'export_statement':
-    Check its child — could be function_declaration, class_declaration, lexical_declaration
-    Extract the actual declaration from inside the export wrapper
-  If node.type is 'function_declaration', 'class_declaration', etc.:
-    Extract directly (non-exported symbol, still useful for internal navigation)
-```
-
-**Signature building:**
-- For functions: `function name(params): returnType`
-- For classes: `class Name extends Base implements Interface`
-- For const: `const name: Type = ...` (truncate value)
-- For types/interfaces: `type Name = ...` or `interface Name { ... }` (truncate body)
-- Keep signatures under 120 chars
-
-**Verify:** Index `test/fixtures/basic-ts-project/`, confirm all exported functions, classes, types are extracted with correct byte offsets.
-
-**Tests:** Comprehensive tests with fixture files covering: simple functions, arrow functions, classes with methods, type aliases, interfaces, enums, default exports, named exports, re-exports, import statements.
-
----
-
-## Task 7: Import Path Resolution
-
-Resolve import specifiers to actual file paths within the project.
-
-**Deliverables:**
-- `src/graph/path-resolver.ts`
-  - `createResolver(projectRoot: string): PathResolver`
-  - Load `tsconfig.json` → extract `compilerOptions.paths` and `baseUrl`
-  - Resolve strategies (tried in order):
-    1. Relative paths (`./foo`, `../bar`) → resolve against importing file's directory
-    2. tsconfig paths (`@/utils/foo`) → map through paths config
-    3. Index files → try appending `/index.ts`, `/index.js`
-    4. Extension resolution → try `.ts`, `.tsx`, `.js`, `.jsx` if no extension
-    5. External packages → if specifier doesn't start with `.` or `@/` and isn't in paths, mark as external (resolvedPath = null)
-  - Return `resolvedPath` relative to project root, or `null` for external
-
-**Key edge cases:**
-- `@/` alias (common in Vue/Nuxt — maps to `src/`)
-- `~/` alias (Nuxt convention)
-- Barrel files (`index.ts` re-exports)
-- Path aliases with wildcards (`"@components/*": ["src/components/*"]`)
-
-**Verify:** Resolve imports from fixture project files correctly, including alias paths.
-
-**Tests:** Test each resolution strategy independently. Test with a tsconfig that has path aliases.
-
----
-
-## Task 8: Dependency Graph Builder
-
-Build the import dependency graph from extracted ImportRecords.
-
-**Deliverables:**
-- `src/graph/graph-builder.ts`
-  - `buildGraph(imports: ImportRecord[], resolver: PathResolver, repoId: string): DepEdge[]`
-  - For each import: resolve path, create edge(s) from source file to target file
-  - If specific named imports: create symbol-level edges (source file → target symbol)
-  - Store edges in `dep_edges` table via dep-store
-- `src/graph/graph-traversal.ts`
-  - `getBlastRadius(symbolId, depth, db): SymbolRecord[]` — reverse-walk deps to find all affected symbols
-  - `getContextBundle(symbolId, depth, db): SymbolRecord[]` — forward-walk deps to find all dependencies
-  - `findImporters(filePath, db): { file, symbols }[]` — who imports this file
-  - `findDeadCode(repoId, db): SymbolRecord[]` — exported symbols with zero importers
-  - All traversals return results with token count estimates
-
-**Verify:** Build graph for fixture project, query blast radius and context bundle, verify results match expected dependency chains.
-
-**Tests:** Fixture project with known dependency chain (A imports B, B imports C). Verify forward/reverse walks.
-
----
-
-## Task 9: Index Manager (Orchestrator)
-
-The central coordinator that ties the pipeline together.
-
-**Deliverables:**
-- `src/core/index-manager.ts`
-  - `indexFolder(rootPath, options): IndexResult`
-    1. Compute repo ID from rootPath
-    2. Create/open SQLite database
-    3. Run file discovery
-    4. Load hash cache from DB
-    5. Filter to changed files only
-    6. For each changed file:
-       a. Get language handler
-       b. Parse with tree-sitter
-       c. Extract symbols
-       d. Extract imports
-       e. Extract docstrings → set as summaries
-       f. Generate symbol IDs
-    7. Batch insert symbols to DB
-    8. Resolve import paths
-    9. Build dependency graph, batch insert edges
-    10. Update hash cache
-    11. Update repo metadata
-    12. Return IndexResult (counts, timing, errors)
-  - `reindexFiles(repoId, changedPaths): IndexResult` — fast path for watcher events
-  - `deleteIndex(repoId)` — remove DB file
-
-**Verify:** Index `test/fixtures/basic-ts-project/` end-to-end. Query symbols and deps from resulting DB.
-
-**Tests:** Full integration test: index a fixture, verify symbol count, verify dep edges, re-index after file change, verify incremental behavior.
-
----
-
-## Task 10: Summary Generator
-
-Three-stage fallback for symbol summaries (no AI in Phase 1).
-
-**Deliverables:**
-- `src/summarizer/summarizer.ts`
-  - `generateSummary(symbol, docstring): string`
-  - Stage 1: If docstring exists, extract first sentence (up to first period or 100 chars)
-  - Stage 2: (Placeholder for Phase 2 — framework-derived summaries)
-  - Stage 3: (Placeholder for Phase 2 — AI batch summarization)
-  - Stage 4: Use signature as summary (truncated to 100 chars)
-- `src/summarizer/docstring-extractor.ts`
-  - Parse JSDoc/TSDoc format
-  - Extract `@description` or first paragraph
-  - Strip tags, markdown, and formatting
-
-**Verify:** Symbols with JSDoc get docstring summaries. Symbols without get signature summaries.
-
-**Tests:** Various JSDoc formats (single-line, multi-line, with tags, without).
-
----
-
-## Task 11: MCP Server and Tool Handlers
-
-Wire everything up as an MCP server.
-
-**Deliverables:**
-- `src/server/mcp-server.ts`
-  - Initialize MCP server with `@modelcontextprotocol/sdk`
-  - Register all tools with names, descriptions, JSON schemas
-  - stdio transport
-  - Graceful shutdown handling
-- `src/server/tools/` — one file per tool:
-  - `index-folder.ts` — calls IndexManager.indexFolder, returns counts and timing
-  - `resolve-repo.ts` — computes repo ID, checks if DB exists, returns metadata or hint
-  - `list-repos.ts` — scan `~/.purecontext/indexes/` for DB files, return metadata
-  - `search-symbols.ts` — search by name/kind/file pattern, return signatures + summaries (no source)
-  - `get-symbol-source.ts` — retrieve raw source via byte offsets from file cache
-  - `get-file-outline.ts` — all symbols in a file with signatures and summaries
-  - `get-repo-outline.ts` — files with their top-level symbols
-  - `get-file-tree.ts` — directory structure with file counts
-  - `get-context-bundle.ts` — symbol + forward deps, include token count
-  - `get-blast-radius.ts` — symbol + reverse deps
-  - `find-importers.ts` — files importing a given module
-  - `find-dead-code.ts` — exported symbols with zero importers
-
-**Key design:**
-- Each tool handler is a pure function: `(input, services) => output`
-- Services object holds: IndexManager, SymbolStore, DepStore, PathResolver
-- Tool responses include a `_tokenEstimate` field so agents can gauge response size
-
-**Verify:** Start server, connect with Claude Code, index a project, run search and retrieval tools.
-
-**Tests:** Unit tests for each tool handler with mocked services. Integration test: start server, send MCP messages via stdio, verify responses.
-
----
-
-## Task 12: File Watcher
-
-Live re-indexing on file changes.
-
-**Deliverables:**
-- `src/core/watcher/file-watcher.ts`
-  - `startWatching(rootPath, repoId, indexManager, options)`
-  - Use chokidar to watch the indexed directory
-  - Debounce events (default 2000ms, configurable)
-  - Batch changed paths during debounce window
-  - On debounce fire: call `indexManager.reindexFiles(repoId, changedPaths)` — fast path
-  - Handle: add, change, unlink events
-  - Ignore: node_modules, .git, dist, build (same as file discovery exclusions)
-  - `stopWatching()` — cleanup
-
-**Verify:** Start watching, modify a file, verify re-index happens within debounce window.
-
-**Tests:** Use temp directory, create/modify/delete files, verify watcher events and re-indexing.
-
----
-
-## Task 13: Configuration System
-
-User-configurable settings with sensible defaults.
-
-**Deliverables:**
-- `src/config/config-schema.ts` — JSON schema for `config.json`
-  - `indexDir`: where to store indexes (default: `~/.purecontext/indexes/`)
-  - `fileLimit`: max files to index (default: 1000)
-  - `watchDebounceMs`: watcher debounce (default: 2000)
-  - `excludePatterns`: additional glob patterns to exclude
-  - `adapters`: `'auto'` | `string[]` | `'none'` (default: `'auto'`)
-  - `ai.provider`: `'anthropic'` | `'openai'` | `'none'` (default: `'none'`)
-  - `ai.allowRemoteAI`: boolean (default: false)
-  - `layers`: layer violation config (optional)
-- `src/config/config-loader.ts` — load from `~/.purecontext/config.json`, merge with defaults
-- `src/config/cli.ts`
-  - `config --init` — generate default config.json with comments
-  - `config --check` — validate config, check prerequisites (tree-sitter grammars present, SQLite working)
-  - `config` — show effective configuration
-
-**Verify:** `npx purecontext-mcp config --init` creates config, `--check` validates it.
-
-**Tests:** Config loading with various override combinations.
-
----
-
-## Task 14: Entry Point and CLI
-
-Tie everything together into a runnable command.
-
-**Deliverables:**
-- `src/index.ts`
-  - Parse CLI args: `purecontext-mcp` (start server), `purecontext-mcp config [--init|--check]`
-  - Initialize parser, load handlers, start MCP server
-  - Handle SIGINT/SIGTERM for graceful shutdown
-- `package.json` `"bin"` field pointing to compiled entry point
-- `README.md` with:
-  - Quick start (install, configure, connect to Claude Code)
-  - Tool reference (brief description of each tool)
-  - Configuration reference
-  - Architecture overview (link to PRD)
-
-**Verify:** Full end-to-end: `npx purecontext-mcp` → Claude Code connects → index a real project → search symbols → retrieve source → check blast radius.
-
----
-
-## Task 15: Integration Testing and Polish
-
-Final validation before Phase 1 is complete.
-
-**Deliverables:**
-- Create `test/fixtures/basic-ts-project/` — a small but representative TypeScript project:
-  - 3-4 modules with imports between them
-  - Functions, classes, interfaces, types, enums
-  - JSDoc comments on some symbols
-  - A tsconfig.json with path aliases
-  - At least one circular dependency to test graph handling
-- End-to-end integration test:
-  1. Index the fixture project
-  2. Verify symbol count matches expected
-  3. Search for a symbol by name → verify found
-  4. Get symbol source → verify byte offsets produce correct code
-  5. Get context bundle → verify dependencies included
-  6. Get blast radius → verify reverse deps
-  7. Find dead code → verify unreferenced exports detected
-  8. Modify a fixture file → trigger re-index → verify incremental update
-- Performance benchmark:
-  - Index a medium project (500+ files) if available
-  - Measure: index time, search time, retrieval time
-  - Compare token counts: symbol retrieval vs. full file
-
-**Verify:** All tests pass. Performance targets from PRD Section 8.2 are met.
-
----
-
-## Order of Execution
-
-```
-Task  1: Project scaffolding           ██░░░░░░░░ Foundation
-Task  2: Core types and errors         ██░░░░░░░░ Foundation
-Task  3: SQLite schema + stores        ███░░░░░░░ Storage
-Task  4: File discovery + hashing      ███░░░░░░░ Storage
-Task  5: Tree-sitter integration       ████░░░░░░ Parsing
-Task  6: TS/JS language handler        █████░░░░░ Parsing
-Task  7: Import path resolution        █████░░░░░ Graph
-Task  8: Dependency graph builder      ██████░░░░ Graph
-Task  9: Index manager orchestrator    ███████░░░ Integration
-Task 10: Summary generator            ███████░░░ Integration
-Task 11: MCP server + tool handlers   ████████░░ Server
-Task 12: File watcher                  █████████░ Server
-Task 13: Configuration system          █████████░ Server
-Task 14: Entry point + CLI            ██████████ Polish
-Task 15: Integration testing          ██████████ Polish
-```
-
-**After Phase 1 is complete**, move to Phase 2 (Vue + Nuxt adapters) as defined in the PRD.