purecontext-mcp 1.1.1 → 1.1.2

package/docs/dev/PHASE4_TASKS.md

@@ -1,531 +0,0 @@
-# Phase 4 — Task Breakdown
-
-**Goal**: Broaden language coverage to Rust, Java, and C#; add backend framework adapters (NestJS, Express/Fastify) and the Angular frontend adapter; harden the HTTP transport with authentication; enable remote repository indexing from GitHub; and deliver semantic search — the PRD Phase 3 item that was deferred.
-
-**Scope rationale**: Phase 3 completed Python, Go, Next.js, HTTP/SSE transport, full-text search, layer violation analysis, and AI summarization expansion. The three items carried forward from the PRD that are still outstanding are: (1) semantic search, (2) authentication for remote HTTP deployments, and (3) extended language/framework coverage. Phase 4 closes all three.
-
-**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 33: Rust Language Handler
-
-Add Rust as the first systems language. Rust's rich type system (structs, enums, traits, impls) maps cleanly onto existing `SymbolKind` types, and its `pub` visibility modifier provides a clean export boundary.
-
-**Deliverables:**
-- Download and bundle `grammars/tree-sitter-rust.wasm`
-- `src/handlers/rust.ts` — implements `LanguageHandler`
-  - `extensions()`: `['.rs']`
-  - `grammarPath()`: path to `tree-sitter-rust.wasm`
-  - `extractSymbols(tree, source)`:
-    - `function_item` → kind `'function'`
-    - `struct_item` → kind `'class'`
-    - `enum_item` → kind `'enum'`
-    - `trait_item` → kind `'interface'`
-    - `impl_item` containing `function_item` children → kind `'method'`, name = `TypeName.method_name`
-    - `const_item` → kind `'const'`
-    - `type_item` (type alias) → kind `'type'`
-    - Only index items with a `pub` visibility_modifier — Rust's single visibility mechanism
-    - Exception: items inside `impl` blocks for public types may omit `pub` (emit them anyway if parent impl is public)
-  - `extractImports(tree, source)`:
-    - `use_declaration` → specifier = the path string (e.g. `std::collections::HashMap`)
-    - `extern_crate_declaration` → specifier = crate name
-    - `resolvedPath`: `null` for all (Cargo module system — no local file resolution without Cargo.toml parsing)
-    - `importedNames`: extract from `use_list` children (e.g. `use foo::{A, B}` → `['A', 'B']`)
-  - `extractDocstring(node)`:
-    - Look for `line_comment` nodes with `///` prefix immediately preceding the item
-    - Also check `doc_comment` nodes (block-style `/** */` is rare in Rust but supported)
-    - Strip `/// ` prefix, concatenate lines, return first paragraph
-
-**Signature building:**
-- Functions: `pub fn name(params) -> ReturnType`
-- Structs: `pub struct Name { field1: Type, ... }` (show first 2 fields; `{ ... }` if more)
-- Enums: `pub enum Name { Variant1, Variant2, ... }` (show first 3 variants)
-- Traits: `pub trait Name { fn method1(...); }` (show first method signature)
-- Constants: `pub const NAME: Type = value`
-- Keep signatures under 120 chars
-
-**Key technical notes:**
-- `impl` blocks tie methods to types — the `impl_item` node has a `type` child naming the type
-- Method name format: `TypeName.method_name` (consistent with Go handler)
-- Trait implementations (`impl Trait for Type`) should use `TypeName.method_name` (not `Trait.method_name`)
-- Macro-generated symbols (`derive`, procedural macros) are not visible to the AST parser — skip silently
-- Rust has no classes; `struct` → `'class'` is the closest analog (same decision as Go)
-
-**Verify:** Index `test/fixtures/rust-project/`. Verify exported structs, enums, traits, functions, and impl methods are extracted. Verify unexported items are skipped. Verify `///` docstrings are captured.
-
-**Tests:** Fixture `.rs` files covering: `pub fn`, private `fn` (skipped), `pub struct`, `pub enum`, `pub trait`, `impl` with methods, `pub const`, type alias, `use` imports, `///` docstring.
-
----
-
-## Task 34: Java Language Handler
-
-Add Java as a statically-typed OO language. Java's structure (classes, interfaces, methods) maps directly onto existing `SymbolKind` types. Only `public` and `protected` symbols are indexed — private/package-private are navigation noise.
-
-**Deliverables:**
-- Download and bundle `grammars/tree-sitter-java.wasm`
-- `src/handlers/java.ts` — implements `LanguageHandler`
-  - `extensions()`: `['.java']`
-  - `grammarPath()`: path to `tree-sitter-java.wasm`
-  - `extractSymbols(tree, source)`:
-    - `class_declaration` → kind `'class'`
-    - `interface_declaration` → kind `'interface'`
-    - `enum_declaration` → kind `'enum'`
-    - `annotation_type_declaration` → kind `'type'`
-    - `method_declaration` inside a class/interface → kind `'method'`, name = `ClassName.methodName`
-    - `constructor_declaration` → kind `'method'`, name = `ClassName.ClassName` (constructor)
-    - `field_declaration` with `static final` modifiers → kind `'const'`
-    - Visibility filter: only index nodes with `public` or `protected` modifiers
-    - Top-level class/interface only (not nested private classes)
-  - `extractImports(tree, source)`:
-    - `import_declaration` → specifier = the fully-qualified class name (strip `import ` prefix)
-    - `static` import: `import static foo.Bar.METHOD` → specifier = `foo.Bar`, importedNames = `['METHOD']`
-    - `resolvedPath`: `null` (Maven/Gradle classpath — no local resolution)
-    - `importedNames`: `[simpleClassName]` for regular imports
-  - `extractDocstring(node)`:
-    - Look for a `block_comment` node immediately preceding the declaration
-    - Must start with `/**` (Javadoc)
-    - Strip `/**`, `*/`, and leading ` * ` from each line
-    - Return first sentence (up to first `.` or 200 chars)
-
-**Signature building:**
-- Classes: `public class Name extends Base implements Interface`
-- Interfaces: `public interface Name extends Parent`
-- Methods: `public ReturnType methodName(Type param, ...)` (truncate params if > 100 chars)
-- Constructors: `public ClassName(Type param, ...)`
-- Constants: `public static final Type NAME = value`
-- Keep signatures under 120 chars
-
-**Key technical notes:**
-- Java's `@Override`, `@Deprecated`, and other annotations precede methods — extract the first annotation if present as part of the signature context
-- Generics (`<T extends Comparable<T>>`) can make signatures very long — truncate aggressively
-- Inner classes: only extract `public static` inner classes; skip instance inner classes
-- Java enums may have methods — extract them as `EnumName.methodName`
-
-**Verify:** Index `test/fixtures/java-project/`. Verify public classes, interfaces, methods, and constants are extracted. Verify private/package-private items are skipped. Verify Javadoc comments are captured.
-
-**Tests:** Fixture `.java` files covering: `public class`, `public interface`, `public enum`, public/private method (private skipped), `public static final` constant, Javadoc comment, `import` and `import static`, generic class.
-
----
-
-## Task 35: C# Language Handler
-
-Add C# as the third statically-typed OO language. C# shares Java's class/interface/method structure but adds properties, namespaces, records, and primary constructors.
-
-**Deliverables:**
-- Download and bundle `grammars/tree-sitter-c-sharp.wasm`
-- `src/handlers/csharp.ts` — implements `LanguageHandler`
-  - `extensions()`: `['.cs']`
-  - `grammarPath()`: path to `tree-sitter-c-sharp.wasm`
-  - `extractSymbols(tree, source)`:
-    - `class_declaration` → kind `'class'`
-    - `interface_declaration` → kind `'interface'`
-    - `enum_declaration` → kind `'enum'`
-    - `struct_declaration` → kind `'class'` (C# structs are value-type analogs of classes)
-    - `record_declaration` → kind `'class'`
-    - `method_declaration` inside a class/interface/struct → kind `'method'`
-    - `constructor_declaration` → kind `'method'`, name = `ClassName.ClassName`
-    - `property_declaration` → kind `'const'` (properties are named member access points)
-    - `field_declaration` with `const` or `static readonly` modifiers → kind `'const'`
-    - Visibility filter: only `public` and `protected` modifiers
-  - `extractImports(tree, source)`:
-    - `using_directive` → specifier = the namespace string (strip `using ` prefix)
-    - `using_static_directive` → specifier = the fully-qualified type
-    - `resolvedPath`: `null`
-    - `importedNames`: `[]` (C# using directives bring namespaces into scope, not individual names)
-  - `extractDocstring(node)`:
-    - Look for `single_line_doc_comment` nodes (`/// `) immediately preceding the declaration
-    - Extract the `<summary>` XML content if present, else return the raw text
-    - Strip `/// ` prefix and XML tags, return first sentence
-
-**Signature building:**
-- Classes: `public class Name : BaseClass, IInterface`
-- Interfaces: `public interface IName`
-- Methods: `public ReturnType MethodName(Type param, ...)`
-- Properties: `public Type PropertyName { get; set; }`
-- Constants: `public const Type NAME = value` or `public static readonly Type Name`
-- Keep signatures under 120 chars
-
-**Key technical notes:**
-- C# properties look like fields syntactically but are accessors — treat as `'const'` kind (same pattern as Go struct fields)
-- Async methods: `public async Task<T> MethodName(...)` — include `async` in signature
-- Extension methods: `public static ReturnType MethodName(this Type param, ...)` — include `this` hint
-- Nullable annotations (`?`): preserve in signatures (e.g. `string?`)
-- Partial classes: multiple `partial class` declarations in different files should all be indexed independently
-
-**Verify:** Index `test/fixtures/csharp-project/`. Verify public classes, interfaces, methods, and properties extracted. Verify `///` XML doc comments captured.
-
-**Tests:** Fixture `.cs` files covering: `public class`, `public interface`, `public enum`, `public record`, public/private method, `public` property, `public const`, XML docstring (`/// <summary>`), `using` directive.
-
----
-
-## Task 36: Angular Adapter
-
-Add Angular as the major frontend framework not yet covered. Angular's decorator-based architecture (`@Component`, `@Injectable`, `@NgModule`, `@Directive`, `@Pipe`) maps clearly onto existing symbol kinds.
-
-**Deliverables:**
-- `src/adapters/angular.ts` — implements `FrameworkAdapter`
-  - `name`: `'angular'`
-  - `detect(projectRoot)`:
-    - Check for `@angular/core` in `package.json` dependencies
-  - `fileFilter(filePath)`:
-    - `.component.ts`, `.service.ts`, `.module.ts`, `.directive.ts`, `.pipe.ts`, `.guard.ts`, `.resolver.ts`
-    - Also `*.ts` files that contain `@Component`, `@Injectable`, etc. (check file extension only; the AST check happens in extraction)
-  - `extractFrameworkSymbols(tree, source, filePath)`:
-    - Scan for `class_declaration` nodes with decorator children:
-      - `@Component` → kind `'component'`, extract `selector` from metadata
-      - `@Injectable` → kind `'class'` with `frameworkMeta.angular_service = true`
-      - `@NgModule` → kind `'class'` with `frameworkMeta.angular_module = true`
-      - `@Directive` → kind `'component'` with `frameworkMeta.angular_directive = true`, extract `selector`
-      - `@Pipe` → kind `'component'` with `frameworkMeta.angular_pipe = true`, extract `name` from metadata
-      - `@Guard` / class implementing `CanActivate` → kind `'middleware'`
-    - For each decorated class: set `name` = class name, `signature` = first decorator line + class declaration
-    - Extract route paths from `RouterModule.forRoot([...])` and `RouterModule.forChild([...])` call expressions → kind `'route'`
-  - `enrichMetadata(symbol)`:
-    - Add `frameworkMeta.selector` for components and directives
-    - Add `frameworkMeta.angular_injectable = true` for services
-
-**Selector extraction:**
-- Parse the decorator metadata object literal: `@Component({ selector: 'app-header', ... })`
-- Extract the `selector` property value as a string
-- For `@Pipe`, extract the `name` property
-
-**Route extraction:**
-- Find `RouterModule.forRoot` or `RouterModule.forChild` call expressions
-- Walk the routes array literal: extract `path` string properties
-- Emit one `'route'` symbol per route with `frameworkMeta.router = 'angular'`
-- Handle lazy-loaded routes: `loadChildren: () => import(...)`
-
-**Key technical notes:**
-- Angular's `standalone: true` components (Angular 14+) don't require `NgModule` — detect and handle them
-- Signals-based components (Angular 17+) look the same as class components from the AST perspective
-- Guards may use the newer functional guard pattern (`export const canActivate = () => ...`) in Angular 15+ — emit as `'middleware'` kind with `frameworkMeta.angular_guard = true`
-- Resolvers: `@Resolver` (GraphQL, not Angular routing) is NOT the same as `Resolve<T>` — check the interface, not a decorator
-
-**Verify:** Index `test/fixtures/angular-project/`. Verify components (with selectors), services, modules, and route paths are extracted.
-
-**Tests:** Component with selector, service with dependency injection, NgModule, standalone component, directive with selector, pipe with name, route path extraction from RouterModule, functional guard.
-
----
-
-## Task 37: NestJS Adapter
-
-Add NestJS as the primary Node.js backend framework adapter. NestJS's decorator-heavy architecture (`@Controller`, `@Get`, `@Post`, `@Injectable`, `@Module`) makes it ideal for structured extraction — routes, services, and modules are all explicitly declared.
-
-**Deliverables:**
-- `src/adapters/nestjs.ts` — implements `FrameworkAdapter`
-  - `name`: `'nestjs'`
-  - `detect(projectRoot)`:
-    - Check for `@nestjs/core` or `@nestjs/common` in `package.json` dependencies
-  - `fileFilter(filePath)`:
-    - `.controller.ts`, `.service.ts`, `.module.ts`, `.guard.ts`, `.middleware.ts`, `.interceptor.ts`, `.pipe.ts`, `.decorator.ts`
-  - `extractFrameworkSymbols(tree, source, filePath)`:
-    - `@Controller('path')` class → emit a `'route'` symbol per HTTP-method decorator inside:
-      - `@Get('/sub')` method → route symbol with `name = 'GET /path/sub'`, `frameworkMeta.http_method = 'GET'`
-      - `@Post(...)`, `@Put(...)`, `@Patch(...)`, `@Delete(...)` similarly
-      - Combine controller prefix + method path for the full route
-    - `@Injectable()` class → kind `'class'` with `frameworkMeta.nestjs_provider = true`
-    - `@Module(...)` class → kind `'class'` with `frameworkMeta.nestjs_module = true`
-    - `@Guard()` / `CanActivate` implementors → kind `'middleware'` with `frameworkMeta.nestjs_guard = true`
-    - `@Middleware()` / `NestMiddleware` → kind `'middleware'`
-    - `@Interceptor()` → kind `'middleware'` with `frameworkMeta.nestjs_interceptor = true`
-  - Route path merging:
-    - Controller prefix: `@Controller('users')` → `/users`
-    - Method decorator: `@Get(':id')` → `:id`
-    - Combined: `/users/:id`
-    - Support empty string prefix (root controller)
-
-**Key technical notes:**
-- NestJS uses TypeScript decorators heavily — the TypeScript handler must already parse the file before the adapter enriches it
-- `@ApiTags`, `@ApiOperation` (Swagger decorators) should be ignored — they don't affect routing
-- Versioning: `@Controller({ path: 'users', version: '1' })` — include version in route if present
-- Microservice message patterns (`@MessagePattern`, `@EventPattern`) are not HTTP routes — skip them in Phase 4
-
-**Verify:** Index `test/fixtures/nestjs-project/`. Verify GET/POST route symbols with full paths, service symbols, and module symbols.
-
-**Tests:** Controller with base path + GET/POST methods (path combining), empty-path controller, service with `@Injectable`, module, guard, parameterized route (`:id`), nested path.
-
----
-
-## Task 38: Express/Fastify Adapter
-
-Add lightweight adapters for Express and Fastify. Unlike NestJS, these frameworks define routes procedurally — route extraction requires pattern-matching call expressions rather than decorators.
-
-**Deliverables:**
-- `src/adapters/express.ts` — implements `FrameworkAdapter`
-  - `name`: `'express'`
-  - `detect(projectRoot)`: check for `express` in `package.json` dependencies
-  - `fileFilter(filePath)`: `.ts`, `.js` files (broad — filter by content in extraction)
-  - `extractFrameworkSymbols(tree, source, filePath)`:
-    - Scan for `call_expression` nodes matching:
-      - `app.get(path, ...)`, `app.post(...)`, `app.put(...)`, `app.delete(...)`, `app.patch(...)` → kind `'route'`
-      - `router.get(...)`, `router.post(...)`, etc. → kind `'route'`
-      - `app.use(path, ...)` → kind `'middleware'` if path is a string literal
-    - For each matched call: extract the path string literal as `name`, set `frameworkMeta.http_method`
-    - Skip dynamic path construction (variable paths) — only extract string literal paths
-    - Skip calls where `app`/`router` is not a recognizable Express variable name (use heuristic: variable assigned from `express()` or `express.Router()`)
-
-- `src/adapters/fastify.ts` — implements `FrameworkAdapter`
-  - `name`: `'fastify'`
-  - `detect(projectRoot)`: check for `fastify` or `@fastify/core` in `package.json` dependencies
-  - `fileFilter(filePath)`: `.ts`, `.js` files
-  - `extractFrameworkSymbols(tree, source, filePath)`:
-    - Scan for `call_expression` nodes matching:
-      - `fastify.get(path, ...)`, `fastify.post(...)`, etc. → kind `'route'`
-      - `fastify.register(plugin, { prefix: '...' })` → kind `'middleware'` with route prefix metadata
-    - Same string-literal-only constraint as Express adapter
-
-**Key technical notes:**
-- Express route definition order matters for middleware but not for symbol extraction
-- Router nesting: `app.use('/api', apiRouter)` gives `apiRouter` routes a `/api` prefix — this is hard to resolve statically without full execution; emit routes without the prefix and note it in `frameworkMeta.prefix_unknown = true`
-- Fastify plugins: `fastify.register()` with an inline function is equivalent to `router.use()` — extract the `prefix` option if present
-- Both adapters: only extract routes where the path is a string literal — dynamic paths (template literals, variables) are too noisy
-
-**Verify:** Index `test/fixtures/express-project/` and `test/fixtures/fastify-project/`. Verify GET/POST route symbols and middleware symbols are extracted from literal paths.
-
-**Tests (Express):** `app.get`/`app.post`/`app.use`, `router.get`/`router.post`, dynamic path variable (skipped), non-Express `app` variable (skipped).
-**Tests (Fastify):** `fastify.get`/`fastify.post`/`fastify.register` with prefix.
-
----
-
-## Task 39: HTTP Transport Authentication
-
-Add API key authentication to the HTTP transport. Required before the server can safely bind to non-loopback addresses for team/remote deployments.
-
-**Deliverables:**
-- Update `src/config/config-schema.ts`:
-  ```typescript
-  interface HttpConfig {
-    port: number;
-    host: string;
-    corsOrigins: string[];
-    auth: {
-      /** Enable bearer token authentication. Default: false. */
-      enabled: boolean;
-      /**
-       * Bearer token to require on all /mcp requests.
-       * Supports ${ENV_VAR} notation for secret management.
-       * If omitted when enabled=true, generates a random token on startup and logs it.
-       */
-      token: string;
-    };
-  }
-  ```
-- Update `src/server/http-server.ts`:
-  - When `auth.enabled = true`: check `Authorization: Bearer <token>` header on all `POST /mcp` requests
-  - Reject with `401 Unauthorized` + JSON body `{"error":"Unauthorized"}` if missing or wrong
-  - `/health` endpoint is always public (no auth required)
-  - `OPTIONS` preflight is always public
-  - Log a warning on startup if `host !== '127.0.0.1'` and `auth.enabled = false`
-- Update `src/config/config-loader.ts`:
-  - If `auth.enabled = true` and `auth.token` is empty: generate a random 32-byte hex token with `crypto.randomBytes(32).toString('hex')` and log it to stderr at startup: `PureContext MCP auth token: <token>`
-  - Apply `resolveEnvVar()` to `auth.token`
-- Update `src/server/mcp-server.ts`:
-  - Pass auth config to `startHttpServer`
-
-**Security notes:**
-- The generated token is logged once to stderr on first startup — users should save it and add it to config
-- No rate limiting in Phase 4 (add in Phase 5 if remote deployments are common)
-- Token comparison must use `crypto.timingSafeEqual()` to prevent timing attacks
-
-**Verify:** Start server with `auth.enabled = true` and a configured token. Verify that requests without the token return 401. Verify requests with the correct token succeed. Verify `/health` always returns 200.
-
-**Tests:** No auth header → 401, wrong token → 401, correct token → 200, health check bypasses auth, token generated when not set (logged to stderr).
-
----
-
-## Task 40: Remote Repository Indexing
-
-Add a new `index_repo` tool that clones and indexes a GitHub (or any Git) repository without requiring the user to clone it manually.
-
-**Deliverables:**
-- `src/server/tools/index-repo.ts`
-  - Tool name: `index_repo`
-  - Input schema:
-    ```json
-    {
-      "url":        { "type": "string", "description": "Git repository URL (https:// or git@)" },
-      "branch":     { "type": "string", "description": "Branch or tag to index (default: default branch)" },
-      "token":      { "type": "string", "description": "GitHub/GitLab personal access token for private repos (optional)" },
-      "fileLimit":  { "type": "number", "default": 5000 }
-    }
-    ```
-  - Implementation:
-    1. Validate the URL — reject non-http(s) and non-git@ URLs
-    2. Clone the repo to a temp directory under `~/.purecontext/clones/` using `child_process.spawn('git', ['clone', '--depth=1', '--branch', branch, url, targetDir])`
-    3. Call `indexFolder(targetDir, { fileLimit })` with the standard pipeline
-    4. Store the clone dir path in the repo metadata so the watcher and `reindexFiles` can reference it
-    5. Return the same response as `index_folder` (repoId, symbolCount, fileCount, duration)
-  - Cleanup: cloned repos are persistent (not temp) — agents can call `delete_index` to remove both the DB and the clone dir
-
-- Add `clonePath` column to `repos` table in `src/core/db/schema.ts` (nullable — null for locally-indexed repos)
-- Update `deleteIndex` in `src/core/index-manager.ts`: if `clonePath` is set, `rmSync(clonePath, { recursive: true })` after deleting the DB
-
-- `src/config/config-schema.ts`: add `clonesDir: string` (default: `~/.purecontext/clones/`)
-
-**Security notes:**
-- Never execute arbitrary git URLs without validation — only `https://`, `http://`, and `git@` schemes allowed
-- The `token` parameter is passed as a URL credential (`https://token@host/path`) — never log it
-- Clone directory is isolated under `~/.purecontext/clones/` — same security boundary as the index DB
-
-**Key technical notes:**
-- `--depth=1` shallow clone keeps disk usage low for large repos
-- Git must be available on `PATH` — check before executing and return a clear error if not found
-- Private repos: inject token into URL as `https://<token>@github.com/owner/repo.git`
-- Progress: `git clone` output goes to stderr — capture and forward to logger at debug level
-- Timeout: kill the git process after 5 minutes to prevent hanging on large repos
-
-**Verify:** Clone a small public GitHub repository, verify symbols are indexed correctly. Clone with an invalid URL, verify error response.
-
-**Tests:** Valid public URL (mock `git clone` with a temp dir), invalid URL scheme rejected, git not on PATH returns clear error, `deleteIndex` removes clone dir.
-
----
-
-## Task 41: Semantic Search
-
-Implement semantic (meaning-based) search over indexed symbols. Fills the PRD Phase 3 deliverable that was deferred. Agents can ask "find functions that validate email addresses" and get relevant symbols even when no literal string matches.
-
-**Deliverables:**
-
-**Storage:**
-- Add `embedding` column (`BLOB`, nullable) to the `symbols` table
-- Add `fts_symbols` virtual table using SQLite FTS5 on `name + signature + summary` for fast keyword fallback
-
-**Embedding generation:**
-- `src/summarizer/embeddings.ts`:
-  ```typescript
-  export interface EmbeddingProvider {
-    embed(texts: string[]): Promise<number[][]>;
-  }
-  export function createEmbeddingProvider(config: AIConfig): EmbeddingProvider | null;
-  ```
-  - Anthropic: use `voyage-code-2` model via `https://api.voyageai.com/v1/embeddings` (Voyage AI is Anthropic's recommended embedding model for code)
-  - OpenAI-compatible: use `/v1/embeddings` endpoint with the configured model (e.g. `nomic-embed-text` for Ollama)
-  - Returns `null` if no embedding provider is configured
-- Update `src/summarizer/summarizer.ts` (Stage 3.5 — after AI summarization):
-  - If embedding provider is configured: batch-generate embeddings for all symbols
-  - Store as 32-bit float array serialized to Buffer (`Float32Array → Buffer`)
-  - Max batch size: 128 texts per API call
-
-**Search:**
-- `src/server/tools/search-semantic.ts`
-  - Tool name: `search_semantic`
-  - Input schema:
-    ```json
-    {
-      "repo":       { "type": "string" },
-      "query":      { "type": "string", "description": "Natural language description of what to find" },
-      "limit":      { "type": "number", "default": 20 },
-      "minScore":   { "type": "number", "default": 0.7, "description": "Minimum cosine similarity (0–1)" }
-    }
-    ```
-  - Implementation:
-    1. Embed the query using the same provider used during indexing
-    2. Load all symbol embeddings from DB for the repo
-    3. Compute cosine similarity between query embedding and each symbol embedding
-    4. Return top-`limit` results above `minScore`, sorted by similarity descending
-    5. If no embeddings are stored (provider not configured): fall back to FTS5 keyword search
-  - Output: same structure as `search_symbols` — array of SymbolRecord with a `score` field added
-- Update `src/config/config-schema.ts`:
-  - Add `ai.embeddingModel?: string` and `ai.embeddingProvider?: 'voyage' | 'openai-compatible'`
-
-**Performance:**
-- Cosine similarity is O(n) over all symbols — acceptable up to ~50k symbols (~10ms at 100ns/symbol)
-- Beyond 50k symbols, consider chunking or approximate nearest-neighbour (HNSW) — defer to Phase 5
-- Embeddings are generated once per index and reused — no re-embedding on queries
-
-**Key technical notes:**
-- `Float32Array` embedding vectors are typically 768 or 1536 dimensions — store as raw bytes (4 bytes × dims)
-- Cosine similarity: `dot(a, b) / (|a| × |b|)` — normalize vectors at storage time to reduce query cost to a dot product
-- FTS5 fallback: when embeddings are absent, use SQLite's built-in full-text search on `name || ' ' || signature || ' ' || summary`
-- Voyage AI `voyage-code-2` is specifically trained on code and documentation — preferred over general-purpose models
-
-**Verify:** Index a project with an embedding provider configured. Query for a natural language description and verify relevant symbols are returned. Query without embeddings configured — verify FTS5 fallback works.
-
-**Tests:** Cosine similarity function (unit test), embedding provider mock, `search_semantic` returns results above minScore, FTS5 fallback when no embeddings, `minScore` filtering.
-
----
-
-## Task 42: Phase 4 Test Fixtures and Integration Tests
-
-Validate the full Phase 4 pipeline end-to-end.
-
-**Deliverables:**
-
-- `test/fixtures/rust-project/` — representative Rust project:
-  - `src/lib.rs` — public structs, traits, functions, `///` docstrings
-  - `src/auth.rs` — `pub struct AuthService`, impl block with methods
-  - `src/models.rs` — `pub struct User`, `pub enum Role`
-  - `Cargo.toml` — minimal manifest
-
-- `test/fixtures/java-project/` — representative Java project:
-  - `src/AuthService.java` — public class with methods, Javadoc
-  - `src/User.java` — public class with fields and constructors
-  - `src/IAuthenticator.java` — public interface
-  - `src/Role.java` — public enum
-
-- `test/fixtures/csharp-project/` — representative C# project:
-  - `src/AuthService.cs` — public class with methods, XML doc comments
-  - `src/User.cs` — public record/class with properties
-  - `src/IAuthenticator.cs` — public interface
-
-- `test/fixtures/angular-project/` — minimal Angular project:
-  - `package.json` with `@angular/core` dep
-  - `src/app/app.module.ts` — `@NgModule`
-  - `src/app/app.component.ts` — `@Component` with selector
-  - `src/app/auth.service.ts` — `@Injectable` service
-  - `src/app/app-routing.module.ts` — `RouterModule.forRoot` with routes
-
-- `test/fixtures/nestjs-project/` — minimal NestJS project:
-  - `package.json` with `@nestjs/core` dep
-  - `src/users/users.controller.ts` — `@Controller('users')` with `@Get`/`@Post`
-  - `src/users/users.service.ts` — `@Injectable` service
-  - `src/app.module.ts` — `@Module`
-  - `src/auth/auth.guard.ts` — `CanActivate` guard
-
-- `test/fixtures/express-project/` — minimal Express project:
-  - `package.json` with `express` dep
-  - `src/routes/users.ts` — `router.get`/`router.post` with literal paths
-  - `src/app.ts` — `app.use('/users', usersRouter)`
-
-- Integration tests `test/integration/phase4.test.ts`:
-  1. Rust: public struct, trait, function extracted; private items skipped
-  2. Rust: `///` docstring captured; impl method name includes type
-  3. Java: public class, interface, method extracted; private method skipped
-  4. Java: Javadoc `/** */` comment captured
-  5. C#: public class, property, method extracted; `/// <summary>` captured
-  6. Angular: `@Component` produces kind `'component'` with selector; `@Injectable` produces kind `'class'`
-  7. Angular: `RouterModule.forRoot` routes extracted
-  8. NestJS: `@Controller('users')` + `@Get(':id')` produces route `GET /users/:id`
-  9. NestJS: `@Injectable` service produces kind `'class'` with `nestjs_provider` metadata
-  10. Express: `router.get('/users', ...)` produces route symbol; dynamic path skipped
-  11. HTTP auth: request without token returns 401; correct token returns 200
-  12. `index_repo`: mock git clone, verify indexing runs on cloned dir
-  13. `search_semantic` FTS5 fallback: query returns results matching name/signature keywords
-  14. Full suite regression: all Phase 1–3 tests still green
-
-**Performance benchmark** `test/benchmarks/phase4.bench.ts`:
-  - Index `rust-project` → record time and symbol count
-  - Index `java-project` → record time and symbol count
-  - `search_semantic` with FTS5 on a 500-symbol repo → verify under 50ms
-
----
-
-## Order of Execution
-
-```
-Task 33: Rust language handler            ██░░░░░░░░ Languages
-Task 34: Java language handler            ███░░░░░░░ Languages
-Task 35: C# language handler              ████░░░░░░ Languages
-Task 36: Angular adapter                  █████░░░░░ Adapters
-Task 37: NestJS adapter                   ██████░░░░ Adapters
-Task 38: Express/Fastify adapter          ███████░░░ Adapters
-Task 39: HTTP auth                        ████████░░ Security
-Task 40: Remote repository indexing      █████████░ Tools
-Task 41: Semantic search                  █████████░ Tools
-Task 42: Fixtures + integration tests     ██████████ Polish
-```
-
-Tasks 33, 34, and 35 are fully independent — they can be developed in parallel. Task 36 (Angular) depends on the TypeScript handler (Phase 1) but is independent of 33–35. Tasks 37 and 38 (NestJS, Express/Fastify) are also TypeScript-only and independent of each other. Task 39 (HTTP auth) builds directly on the Phase 3 HTTP transport. Task 40 (remote indexing) depends on the core indexing pipeline being stable but is otherwise independent. Task 41 (semantic search) requires the AI summarizer infrastructure from Phase 3 and adds embedding generation as a new stage. Task 42 requires all previous tasks.
-
-**After Phase 4 is complete**, consider Phase 5: Ruby and PHP language handlers, approximate nearest-neighbour semantic search for large repos (>50k symbols), rate limiting and multi-tenant auth for hosted deployments, and a web UI for exploring the symbol graph.