purecontext-mcp 1.1.0 → 1.1.2

package/docs/08-framework-adapters.md

@@ -0,0 +1,324 @@
+# Framework Adapters
+
+
+Framework adapters layer domain-specific symbol extraction on top of language handlers. They are auto-detected from project config files.
+
+## How adapters work
+
+Each adapter implements the `FrameworkAdapter` interface:
+
+- `detect(projectRoot)` — returns `true` if this framework is present (checks `package.json`, `go.mod`, etc.)
+- `fileFilter(filePath)` — returns `true` for files this adapter should process
+- `preProcess(source, filePath)` — splits multi-language files into parseable blocks (e.g., Vue SFCs)
+- `extractFrameworkSymbols(tree, source, filePath)` — extracts framework-specific symbols from the AST
+- `enrichMetadata(symbol)` — adds `frameworkMeta` to existing symbols
+
+Multiple adapters can be active simultaneously. Adapters compose — a Vue + Nuxt project activates both.
+
+## Configuring adapters
+
+```json
+{
+  "adapters": "auto"       // auto-detect from project files (default)
+  "adapters": "none"       // disable all adapters
+  "adapters": ["vue", "nuxt"]  // explicit list
+}
+```
+
+---
+
+## JavaScript / TypeScript frameworks
+
+### Vue 3
+
+**Detected by:** `vue` in `package.json`, or any `.vue` file present.
+
+Extracts from `.vue` Single File Components:
+- `component` — the component itself (from filename or `defineComponent`)
+- `composable` — exported `use*` functions
+
+`frameworkMeta` includes: `vue_component: true`, `vue_composable: true`.
+
+### Nuxt
+
+**Detected by:** `nuxt.config.ts` (or `.js`, `.mts`, `.mjs`) in project root.
+
+Extracts:
+- `route` from `pages/**/*.vue` (derives route path: `pages/blog/[slug].vue` → `/blog/:slug`)
+- `route` from `server/api/**/*.ts` (HTTP method from filename suffix)
+- `middleware` from `plugins/**` and `middleware/**`
+- Enriches composables in `composables/**` with `nuxt_auto_import: true`
+
+### React
+
+**Detected by:** `react` in `package.json` dependencies.
+
+Enriches TypeScript handler symbols:
+- PascalCase functions returning JSX → `component`
+- `use*` functions → `hook`
+
+### Next.js
+
+**Detected by:** `next.config.*` or `next` in `package.json`.
+
+Extracts:
+- **Pages Router** (`pages/**`): `route` symbols with path derivation
+  - `pages/blog/[slug].tsx` → `/blog/:slug`
+  - Detects `getServerSideProps` (SSR), `getStaticProps` (SSG)
+- **App Router** (`app/**/page.tsx`): `route` symbols
+  - `app/(marketing)/about/page.tsx` → `/about` (route groups stripped)
+  - Detects `'use client'` directive
+- **API routes**: `pages/api/**` and `app/**/route.ts` with HTTP method exports
+- **Middleware** (`middleware.ts`): `middleware` symbol with matcher config
+
+### Angular
+
+**Detected by:** `@angular/core` in `package.json`.
+
+Extracts from decorated classes:
+- `@Component` → `component` (with `selector`)
+- `@Injectable` → `class` (service)
+- `@NgModule` → `class` (module)
+- `@Directive` → `component` (with `selector`)
+- `@Pipe` → `component` (with pipe name)
+- `RouterModule.forRoot/forChild` → `route` symbols
+
+### NestJS
+
+**Detected by:** `@nestjs/core` in `package.json`.
+
+Extracts from decorated controllers:
+- `@Controller('prefix')` + `@Get(':id')` → `route` with combined path (`GET /prefix/:id`)
+- `@Injectable` → `class` with `nestjs_provider: true`
+- `@Module` → `class` with `nestjs_module: true`
+- `@Guard` / `CanActivate` → `middleware`
+
+### Express
+
+**Detected by:** `express` in `package.json`.
+
+Extracts string-literal route registrations:
+- `app.get('/path', ...)` → `route`
+- `router.post('/path', ...)` → `route`
+- `app.use('/path', ...)` → `middleware`
+
+Dynamic paths (variables, template literals) are skipped.
+
+### Fastify
+
+**Detected by:** `fastify` in `package.json`.
+
+Same pattern as Express: `fastify.get(path, ...)` → `route`.
+
+---
+
+## Python frameworks
+
+### Flask
+
+**Detected by:** `Flask` in `requirements.txt` or `pyproject.toml`.
+
+Extracts:
+- `@app.route('/path')` → `route`
+- `@app.get('/path')`, `@app.post(...)` → `route`
+- Blueprint routes: `@bp.route(...)` → `route`
+- Class-based views (inheriting `MethodView`) → `view`
+
+Flask path parameters (`<int:user_id>`) are preserved as-is.
+
+### FastAPI
+
+**Detected by:** `fastapi` in `requirements.txt` or `pyproject.toml`.
+
+Extracts:
+- `@app.get('/items/{id}')` → `route`
+- `@router.post(...)` (APIRouter) → `route`
+
+FastAPI path parameters (`{param}`) are preserved.
+
+### Django
+
+**Detected by:** `manage.py` at project root, or `django` in requirements.
+
+Extracts:
+- `models.Model` subclasses → `model`
+- Class-based views (`APIView`, `ViewSet`, etc.) → `view`
+- Function-based views (with `@login_required`, `@api_view`) → `view`
+- `path(...)` / `re_path(...)` in `urls.py` → `route`
+- `@receiver(post_save)` → `signal`
+
+---
+
+## Go frameworks
+
+### Gin
+
+**Detected by:** `github.com/gin-gonic/gin` in `go.mod`.
+
+Extracts: `r.GET("/path", handler)`, `r.POST(...)`, etc. → `route`. Groups: `r.Group("/api")` prefix applied to child routes.
+
+### Echo
+
+**Detected by:** `github.com/labstack/echo` in `go.mod`.
+
+Same pattern as Gin: `e.GET("/path", handler)` → `route`.
+
+### Fiber
+
+**Detected by:** `github.com/gofiber/fiber` in `go.mod`.
+
+Title-case methods: `app.Get("/path", handler)` → `route`.
+
+---
+
+## PHP frameworks
+
+### Laravel
+
+**Detected by:** `laravel/framework` in `composer.json`.
+
+Extracts:
+- `Route::get('/path', ...)` → `route`
+- `Route::resource('users', Controller::class)` → multiple CRUD routes
+- `Route::group(['prefix' => '/api'], ...)` → prefix applied to children
+- `User extends Model` → `model`
+- Controller public methods → `view`
+- Middleware classes → `middleware`
+
+### Symfony
+
+**Detected by:** `symfony/framework-bundle` in `composer.json`.
+
+Extracts:
+- `#[Route('/path', methods: ['GET'])]` → `route` (PHP 8 attributes)
+- `@Route('/path')` in docblock → `route` (annotation style)
+
+---
+
+## Ruby frameworks
+
+### Rails
+
+**Detected by:** `gem 'rails'` in `Gemfile`.
+
+Extracts:
+- `ApplicationRecord` subclasses → `model` (with `has_many` associations)
+- Controller public methods → `view` (action)
+- `get '/path'`, `resources :users` in `routes.rb` → `route`
+
+### Sinatra
+
+**Detected by:** `gem 'sinatra'` in `Gemfile` or `require 'sinatra'` in source.
+
+Extracts: `get '/path' do ... end` → `route`.
+
+---
+
+## Kotlin frameworks
+
+### Ktor
+
+**Detected by:** `io.ktor` in `build.gradle` / `pom.xml`.
+
+Extracts from routing DSL:
+- `get("/path") { ... }` → `route`
+- `route("/api") { get("/users") }` → combined path `/api/users`
+- `authenticate { ... }` → `frameworkMeta.authenticated: true`
+
+### Spring (Kotlin)
+
+**Detected by:** `org.springframework.boot` in `build.gradle` / `pom.xml`.
+
+Extracts: `@RestController` + `@GetMapping("/path")` → `route`; `@Service`, `@Component`, `@Repository` → class with metadata.
+
+---
+
+## Rust frameworks
+
+### Axum
+
+**Detected by:** `axum` in `Cargo.toml`.
+
+Extracts: `.route("/path", get(handler))` chains → `route`. Layers: `.layer(...)` → `middleware`.
+
+### Actix-web
+
+**Detected by:** `actix-web` in `Cargo.toml`.
+
+Extracts: `#[get("/path")]` attribute macro → `route`; `.wrap(...)` → `middleware`.
+
+### Rocket
+
+**Detected by:** `rocket` in `Cargo.toml`.
+
+Extracts: `#[get("/path")]` → `route`; `#[catch(404)]` → error catcher; `Fairing` implementations → `middleware`.
+
+---
+
+## Java frameworks
+
+### Spring Boot
+
+**Detected by:** `spring-boot-starter` in `pom.xml` / `build.gradle`.
+
+Extracts: `@GetMapping`, `@PostMapping` (combined with `@RequestMapping` prefix) → `route`; `@Service`, `@Component`, `@Repository` → beans; `@Bean` methods; `@Scheduled` methods → scheduled tasks.
+
+### Micronaut
+
+**Detected by:** `io.micronaut` in build files.
+
+Extracts: `@Get("/path")`, `@Post(...)` → `route`; `@Client` interfaces.
+
+### Quarkus
+
+**Detected by:** `io.quarkus` in build files.
+
+Extracts: JAX-RS `@GET` / `@Path` → `route`; `@ApplicationScoped` → bean.
+
+---
+
+## ORM adapters
+
+### Hibernate (Java)
+
+**Detected by:** `hibernate-core` or `jakarta.persistence` in dependencies.
+
+Extracts from `@Entity` classes: table name, columns with types and nullability, relationships (`@OneToMany`, etc.), named queries.
+
+### SQLAlchemy (Python)
+
+**Detected by:** `sqlalchemy` in requirements.
+
+Extracts from `Base` / `DeclarativeBase` subclasses: `__tablename__`, `Column(Type)` fields, `relationship()` associations, `@hybrid_property` methods. Supports both SQLAlchemy 1.x and 2.0 (`mapped_column`) styles.
+
+### Django ORM
+
+**Detected by:** Django project with `manage.py`.
+
+Extracts `models.Model` subclasses with field types: `CharField`, `IntegerField`, `ForeignKey`, `ManyToManyField`, etc.
+
+### Prisma
+
+**Detected by:** `prisma` in `package.json` or `schema.prisma` present.
+
+Extracts model definitions and relations from `schema.prisma`.
+
+### TypeORM
+
+**Detected by:** `typeorm` in `package.json`.
+
+Extracts `@Entity` classes and `@Column` / `@Relation` fields.
+
+---
+
+## Mobile frameworks
+
+### Flutter
+
+**Detected by:** `sdk: flutter` in `pubspec.yaml`.
+
+Extracts from `.dart` files:
+- `StatelessWidget` subclasses → `widget`
+- `StatefulWidget` subclasses → `widget` (with linked State class)
+- `ChangeNotifier` subclasses → `class` with `flutter_notifier: true`
+

package/docs/09-dependency-graph.md

@@ -0,0 +1,182 @@
+# Dependency Graph Tools
+
+
+The dependency graph tracks import relationships between files. Four tools let agents query it at different granularities — from a single hop to a full transitive walk.
+
+---
+
+## Concepts
+
+During indexing, each `import` / `require` / `use` statement is resolved to a dependency edge:
+
+```
+dep_edge: sourceFile → resolvedTargetFile (via import specifier)
+```
+
+Edges are stored in the `dep_edges` SQLite table. External packages (e.g., `from 'react'`) produce edges with `resolvedPath: null` and are excluded from graph traversal.
+
+Two directions of traversal:
+- **Forward walk** — "what does X depend on?" (imports, transitively)
+- **Reverse walk** — "what depends on X?" (importers, transitively)
+
+---
+
+## `get_context_bundle`
+
+**Purpose:** Forward-walk from a symbol — returns everything an agent needs to understand it (the symbol itself plus its transitive imports).
+
+**When to use:** Before modifying a function — understand its full context without reading whole files.
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `repoId` | `string` | required | Target repository |
+| `symbolId` | `string` | required | Starting symbol |
+| `maxDepth` | `number` | `3` | Traversal depth |
+| `maxTokens` | `number` | — | Stop collecting when estimate exceeds this |
+
+**Example:**
+
+```
+"Give me everything needed to understand the processOrder function."
+
+→ get_context_bundle({ symbolId: "processOrder-id", maxDepth: 2 })
+→ Returns: processOrder + validateCart + calculateTax + formatPrice
+  _tokenEstimate: 820
+```
+
+**Response:**
+
+```json
+{
+  "symbols": [
+    { "id": "...", "name": "processOrder", "signature": "...", "source": "..." },
+    { "id": "...", "name": "validateCart", "signature": "...", "source": "..." }
+  ],
+  "files": ["src/orders/processor.ts", "src/cart/validator.ts"],
+  "_tokenEstimate": 820
+}
+```
+
+---
+
+## `get_blast_radius`
+
+**Purpose:** Reverse-walk — all files that (transitively) import a given symbol. Tells you what would break if you change or delete it.
+
+**When to use:** Before modifying or deleting a symbol.
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `repoId` | `string` | required | Target repository |
+| `symbolId` | `string` | required | Symbol to analyze |
+| `maxDepth` | `number` | `5` | Traversal depth |
+
+**Example:**
+
+```
+"What breaks if I change UserService.authenticate?"
+
+→ get_blast_radius({ symbolId: "UserService.authenticate-id" })
+→ Returns: 14 files at depth 1–3
+  (AuthController, LoginPage, SessionMiddleware, tests/...)
+```
+
+**Response:**
+
+```json
+{
+  "importers": [
+    "src/controllers/auth.ts",
+    "src/middleware/session.ts",
+    "src/pages/Login.tsx",
+    "test/auth.test.ts"
+  ],
+  "count": 14,
+  "_tokenEstimate": 120
+}
+```
+
+---
+
+## `find_importers`
+
+**Purpose:** Direct (one-hop) importers of a file — faster and narrower than `get_blast_radius`.
+
+**When to use:** Quick check — "who imports this module directly?"
+
+**Parameters:** `{ repoId, filePath }` — `filePath` is relative to repo root.
+
+**Response:**
+
+```json
+{
+  "importers": [
+    {
+      "filePath": "src/controllers/auth.ts",
+      "importedNames": ["UserService", "AuthToken"]
+    }
+  ],
+  "_tokenEstimate": 80
+}
+```
+
+---
+
+## `find_dead_code`
+
+**Purpose:** Exported symbols in files that nothing else imports — potential dead code.
+
+**When to use:** Cleanup sprints, pre-refactor audits.
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `repoId` | `string` | required | Target repository |
+| `limit` | `number` | `50` | Max results |
+
+**Response:**
+
+```json
+{
+  "symbols": [
+    {
+      "id": "...",
+      "name": "legacyFormatDate",
+      "kind": "function",
+      "filePath": "src/utils/date-old.ts",
+      "signature": "function legacyFormatDate(d: Date): string"
+    }
+  ],
+  "_tokenEstimate": 240
+}
+```
+
+**False positive sources:**
+- **Dynamic imports** — `import('./module')` are not tracked by the static graph
+- **Side-effect imports** — `import './setup'` (no names imported) create edges but no `importedNames`
+- **External consumers** — if this repo is itself an npm package, external consumers won't appear in the index
+- **Test files** — test imports are included in the graph; symbols only used by tests are not dead
+
+---
+
+## Combining graph tools
+
+A typical refactoring workflow:
+
+```
+1. get_blast_radius(symbolId)
+   → See the full impact scope before touching anything
+
+2. get_context_bundle(symbolId, maxDepth: 2)
+   → Understand the symbol and its immediate dependencies
+
+3. Make the change
+
+4. find_dead_code(repoId)
+   → Verify no orphaned exports were left behind
+```

package/docs/10-semantic-search.md

@@ -0,0 +1,153 @@
+# Semantic Search
+
+
+Semantic search finds symbols by **meaning** rather than exact name. It uses an HNSW (Hierarchical Navigable Small World) vector index built from symbol summaries and signatures.
+
+---
+
+## How it works
+
+1. During indexing, each symbol's summary + signature is sent to an embedding model (e.g., OpenAI `text-embedding-3-small`)
+2. The resulting vector is stored in an HNSW index persisted at `~/.purecontext/indexes/{repoId}/hnsw.idx`
+3. At search time, the query is embedded using the same model
+4. HNSW performs an approximate nearest-neighbor search by cosine similarity
+5. Results are ranked by similarity score and returned
+
+---
+
+## When the HNSW index is built
+
+The HNSW index is only built when **all three** conditions are met:
+
+1. `semantic.enabled: true` in config
+2. An embedding provider is configured (`semantic.provider`)
+3. The repo has more symbols than `semantic.threshold` (default: 50,000)
+
+**For small or medium repos**, set `threshold` low to enable HNSW early:
+
+```json
+{
+  "semantic": {
+    "enabled": true,
+    "provider": "openai",
+    "threshold": 100
+  }
+}
+```
+
+Below the threshold, all search falls back to FTS5 keyword search — which is fast and accurate for name-based queries.
+
+---
+
+## Enabling semantic search
+
+### Using OpenAI embeddings
+
+```json
+{
+  "semantic": {
+    "enabled": true,
+    "provider": "openai",
+    "threshold": 50000
+  },
+  "ai": {
+    "openaiApiKey": "${OPENAI_API_KEY}"
+  }
+}
+```
+
+### Using local Ollama embeddings
+
+```json
+{
+  "semantic": {
+    "enabled": true,
+    "provider": "local",
+    "localEmbeddingEndpoint": "http://localhost:11434",
+    "threshold": 1000
+  }
+}
+```
+
+Set the model by passing it in the endpoint config or using Ollama's default embedding model.
+
+---
+
+## Using `search_semantic`
+
+```json
+{
+  "repo": "my-project",
+  "query": "function that validates user credentials",
+  "mode": "hybrid",
+  "semantic_weight": 0.6,
+  "keyword_weight": 0.4,
+  "max_results": 10
+}
+```
+
+**Response:**
+
+```json
+{
+  "results": [
+    {
+      "id": "8f3a...",
+      "name": "authenticateUser",
+      "kind": "function",
+      "filePath": "src/auth/validator.ts",
+      "signature": "function authenticateUser(creds: Credentials): Promise<User>",
+      "summary": "Validates credentials against the database and returns a session token.",
+      "scores": {
+        "keyword": 0.72,
+        "semantic": 0.89,
+        "combined": 0.82
+      }
+    }
+  ]
+}
+```
+
+---
+
+## Keyword vs semantic — when to use which
+
+| Situation | Best tool |
+|-----------|-----------|
+| You know the name or a fragment of it | `search_symbols` (keyword) |
+| You know what it does, not what it's called | `search_semantic` |
+| You want maximum recall | `search_semantic` with `mode: "hybrid"` |
+| Semantic index not available (small repo) | `search_symbols` always works |
+
+The `search_symbols` tool also supports `mode: "hybrid"` — it will use HNSW automatically if the index exists.
+
+---
+
+## How hybrid search works
+
+Hybrid mode runs both searches and merges results using **Reciprocal Rank Fusion (RRF)**:
+
+```
+score = keyword_weight × (1 / (60 + keyword_rank))
+      + semantic_weight × (1 / (60 + semantic_rank))
+```
+
+This combines the precision of exact-name matching with the recall of semantic matching. Adjust weights to bias toward one or the other.
+
+---
+
+## Performance
+
+- HNSW search: < 10ms for k=10 in a 100k vector index
+- Embedding generation: batched at index time, ~50ms per symbol (API latency)
+- Indexes are persisted — no rebuild on each startup
+
+## Rebuilding the vector index
+
+The HNSW index is rebuilt automatically on full re-index. To force a rebuild without re-parsing all files:
+
+```
+Use invalidate_cache with force: true, then index_folder again.
+```
+
+Or call `index_folder` with `force: true` — this re-embeds all symbols even if their source hasn't changed.