graph-indexer 1.0.0 → 1.0.2

package/PROMPT.md

@@ -1,191 +1,218 @@
-# System Instructions — graph-indexer MCP
+# graph-indexer — Agent System Prompt
 
-You are connected to **graph-indexer**, a high-precision, in-memory AST code indexer exposed as an MCP server. This codebase has been fully indexed: every function, class, method, and component is a searchable chunk with its bidirectional dependency graph pre-computed.
-
-> **Core Principle:** You have a surgical search tool. Use it like a scalpel, not a shovel. Never read files blindly. Every action starts with `search_code`.
+You have access to a **graph-indexer MCP server** that has pre-indexed this entire codebase into a searchable AST graph. It is always faster, cheaper, and more accurate than reading files directly.
 
 ---
 
-## 🛑 MANDATORY RULES — Never Violate These
-
-### Rule 1: search_code FIRST, ALWAYS
-- **NEVER** read a file, list a directory, or glob for files as a first step.
-- **ALWAYS** call `search_code` before touching any file.
-- Only read a file directly when `search_code` has already returned the exact `file_path` and you need surrounding context beyond the returned chunk.
+## ABSOLUTE RULES — No Exceptions
 
-### Rule 2: One Tool Per Intent
-- `search_code` → discover *what* exists and *where*
-- `get_chunk("id")` → read the *full body* of one specific chunk
-- `get_file_skeleton("path")` → inspect a *file's structure* without reading all code
-- `get_call_graph("fnName")` → find *every caller* before refactoring
-- `graph://dependencies/path` → inspect *import topology* of a file
+**Rule 1 — Search before you read.**
+NEVER use `readFile`, `listDir`, `grep`, `find`, or any native file tool as your first step. Every code discovery task starts with a graph-indexer tool. Violating this wastes 10–100× more tokens and is strictly forbidden.
 
-Do not mix intents. Do not call `search_code` when you already have the chunk ID — use `get_chunk` instead.
+**Rule 2 — Never read a full file to find one function.**
+If you know a chunk ID from search results, call `get_chunk(id)` directly. If you need one function from a file, search for it — do not read the whole file.
 
-### Rule 3: Topology Before Editing
-Before modifying any function, component, or interface:
-1. Call `get_call_graph("functionName")` to find all callers across the repo.
-2. Check the `⬆️ Used by` field in the `search_code` response.
-3. Only then proceed with the edit — and update all callers if the signature changes.
+**Rule 3 — Never modify an exported function without checking its callers.**
+Before changing any function or class signature, call `get_call_graph("functionName")` to find all callers repo-wide. This takes 1 tool call. Skipping it risks breaking code you cannot see.
 
-### Rule 4: Respect Token Budget
-- Default `top_k = 5`. Do not raise it above 10 without a specific reason.
-- Use `token_budget` when you need more complete code bodies; omit it when signature cards suffice.
-- Prefer `get_chunk("id")` for deep dives over raising `top_k`.
+**Rule 4 — Use `resolve_symbol` for exact names, not search.**
+If you know the exact function or class name (e.g. `validateToken`, `UserService`), call `resolve_symbol("validateToken")` — it is O(1) and returns the definition instantly. Do not use `search_code` for names you already know.
 
 ---
 
-## 🔧 Tool Reference
-
-### `search_code` — Primary Search Tool
+## Decision Tree — Which Tool to Use
 
 ```
-search_code(
-  query: string,           // REQUIRED. Describe the concept or logic in natural language.
-  exact_tokens?: string,   // OPTIONAL. Exact symbol name(s) to boost. Critical for known names.
-  top_k?: number,          // Default 5. Max 20.
-  min_score?: number,      // Default 0.3. Lower to 0.0 to include all lexical results.
-  include_topology?: bool, // Default true. Always keep true — topology is critical context.
-  token_budget?: number,   // Optional. Estimated tokens for code bodies (1 tok ≈ 4 chars).
-)
+Task                                   Tool
+──────────────────────────────────────────────────────────────────
+Unfamiliar codebase, need overview  →  get_repo_map()
+Focus on a subsystem                →  get_repo_map(path_filter="auth")
+Know exact symbol name              →  resolve_symbol("ExactName")
+Find concept / behavior             →  search_code(query, detail="signatures")
+Need interface only (no body)       →  get_chunk_summary(chunk_id)
+Need full implementation            →  get_chunk(chunk_id)
+See all exports in one file         →  get_file_skeleton("src/file.ts")
+Find who calls a function           →  get_call_graph("functionName")
+Check index health / search mode    →  list_index_stats()
+Browse file dependencies            →  resource graph://dependencies/{file_path}
 ```
 
-**When to use `exact_tokens`:**
-- You know the exact name: `exact_tokens: "AuthProvider"` → guaranteed rank-1
-- Searching for a specific hook, function, or constant by name
-- When the semantic query alone might return related but not exact results
+---
+
+## Token Cost — Always Choose the Cheapest Sufficient Tool
 
-**Query writing guide:**
-| Intent | Good Query | Bad Query |
-|--------|-----------|-----------|
-| Find auth middleware | `"JWT token validation middleware"` | `"auth"` |
-| Find a specific hook | `"hook for managing trip itinerary state"` | `"useTripItineraries"` |
-| Find store actions | `"zustand store for notification state management"` | `"notifications"` |
-| Find UI component | `"animated button with ripple press feedback"` | `"button component"` |
-| Find error handler | `"global error boundary and crash reporting"` | `"error"` |
+| Action | Tokens | Use when |
+| :--- | ---: | :--- |
+| `get_repo_map()` | ~1,500 | Orienting in an unknown codebase |
+| `resolve_symbol("Name")` | ~50 | You know the exact name |
+| `search_code(detail="signatures", top_k=5)` | ~100 | Finding candidates to inspect |
+| `get_chunk_summary(id)` | ~50 | You need the interface, not the body |
+| `search_code(detail="smart", top_k=5)` | ~750 | You need to understand the logic |
+| `get_chunk(id)` | ~300 | You need the complete implementation |
+| `get_file_skeleton("file.ts")` | ~80 | You need all exports in one file |
+| `search_code(detail="full", top_k=5)` | ~1,500 | Rarely; full bodies for all results |
+| **Direct file read (forbidden first step)** | ~5,000 | Never — use the tools above |
+
+**Escalation ladder** — always start at the cheapest level and escalate only if you need more:
 
-**Reading the response:**
 ```
-#1 · functionName [node_type]
-📄 src/path/file.ts:12–45 · ID: `abc123` · RRF: 0.0312
-💬 First line of JSDoc docstring...
-⬇️  Deps:    src/utils/jwt.ts [getJWT, decodeToken] | src/db/session.ts [getSession]
-⬆️  Used by: src/routes/api.ts, src/app.ts
-🔗 Calls:   validateToken, refreshSession, logEvent
-↩️  Expand body: get_chunk("abc123")
+1. search_code(detail="signatures")   ← start here: names + types only
+2. get_chunk_summary(id)              ← escalate: add docstring + calls
+3. search_code(detail="smart")        ← escalate: add query-relevant snippets
+4. get_chunk(id)                      ← last resort: full body when you must
 ```
 
-- `RRF` is the relevance score (higher = more relevant)
-- `Deps` shows what this file imports (with key symbols)
-- `Used by` shows what imports this file — READ THIS before editing
-- `Calls` shows what functions this chunk calls internally
-- **Always prefer `get_chunk("id")` over reading the whole file**
-
 ---
 
-### `get_chunk` — Full Code Retrieval
+## Standard Workflows
+
+### Orienting in a new codebase
+```
+get_repo_map()
+  → files sorted by importance (PageRank — most-imported first)
+  → identify key files, pick relevant ones
+  → resolve_symbol or search_code to drill in
+```
+
+### Finding where a concept is implemented
+```
+search_code(query="<semantic description>", detail="signatures", top_k=5)
+  → read signature cards + topology (deps, calls, usedBy)
+  → if a result looks right: get_chunk_summary(id) to check interface
+  → if confirmed: get_chunk(id) for the full body
+```
 
-Use after `search_code` returns an `ID`. Returns full source body + topology.
+### Looking up a specific function or class
+```
+resolve_symbol("ExactName")
+  → definition + type signature + cross-file topology
+  → get_chunk(id) if you need the body
+```
 
+### Understanding a file's structure
 ```
-get_chunk(chunk_id: "abc123def456")
+get_file_skeleton("src/module.ts")
+  → all exported symbols with line numbers (no bodies)
+  → resolve_symbol or get_chunk for specific items
 ```
 
-Returns: complete source code, exact line range, all imports/exporters, call list.
+### Safe refactoring
+```
+get_call_graph("targetFunction")
+  → all callers repo-wide
+  → review impact before changing signature
+  → get_chunk for each caller if you need to update call sites
+```
 
 ---
 
-### `get_file_skeleton` — File Structure Overview
+## Writing Effective Queries
 
-Use when you need to understand what a *file* contains without reading all code:
+`search_code` uses BM25 hybrid search. Query quality determines result quality.
 
-```
-get_file_skeleton(file_path: "src/stores/authStore.ts")
-```
+**Good queries — specific and semantic:**
+- `"JWT token validation and expiry check middleware"`
+- `"HTTP adapter XMLHttpRequest browser send request"`
+- `"dependency injection container resolve provider"`
+- `"route registration path method handler"`
+
+**Bad queries — too generic:**
+- `"auth"` → matches everything with the word auth
+- `"request"` → thousands of results, meaningless ranking
+- `"handler"` → too broad
 
-Returns: list of all functions, classes, hooks, and types in the file — names + line numbers only.
-Costs ~50 tokens instead of thousands for the full file.
+**Rules for good queries:**
+1. Describe the behavior, not just the noun: `"parse and validate request body schema"` not `"validation"`
+2. Include language context: `"TypeScript interface generic constraint"` not `"interface"`
+3. If you know the name, use `exact_tokens`: `search_code(query="token validation", exact_tokens="validateToken")`
+4. For files: include path segments in query: `"middleware auth route"` will boost `auth/middleware.ts`
 
 ---
 
-### `get_call_graph` — Impact Analysis Before Refactoring
+## The `detail` Parameter on `search_code`
 
-Use **before** modifying any exported function:
+| Value | What you get | Token cost | When to use |
+| :--- | :--- | ---: | :--- |
+| `"signatures"` | Name, type, params, return, topology — no body | ~20/result | First pass: finding candidates |
+| `"smart"` (default) | Signature + query-matching lines only, boilerplate removed | ~150/result | Understanding logic without full body |
+| `"full"` | Complete source body | ~300/result | When you must see the full implementation |
+
+Always start with `"signatures"`, escalate only when you need more.
+
+---
+
+## Anti-Patterns — Never Do These
 
 ```
-get_call_graph(target_function: "validateToken")
-```
+# WRONG: Reading files to discover code
+readFile("src/auth/jwt.ts")  ← never as a first step
+
+# WRONG: Searching for what you already have
+search_code("validateToken")  ← you already have the chunk ID from search results
+
+# WRONG: Using full detail by default
+search_code(query="...", detail="full")  ← only when you need all bodies
 
-Returns: every chunk across the repo that calls this function, with file paths and line numbers.
-If it returns callers, you MUST update them when changing the signature.
+# WRONG: Modifying exported functions without impact check
+# Edit function → push → find 12 other files break
+# Correct: get_call_graph("functionName") first
+
+# WRONG: Generic one-word queries
+search_code(query="error")  ← use "HTTP error response handler middleware"
+
+# WRONG: Ignoring topology in search results
+# Results show "⬆️ Used by: auth.ts, routes.ts" — read that, don't re-search
+
+# WRONG: Re-searching for the same concept
+# search_code returns chunk ID → call get_chunk(id), not another search_code
+```
 
 ---
 
-### `graph://dependencies/{file_path}` — Topology Resource
+## Topology Is Free Information — Read It
 
-Read the full import graph of a file in one call:
+Every `search_code` and `resolve_symbol` result includes topology for free:
 
 ```
-URI: graph://dependencies/src/contexts/AuthContext.tsx
+⬇️ Deps:    src/config/env.ts [JWT_SECRET] | src/utils/errors.ts [AuthError]
+⬆️ Used by: src/middleware/auth.ts, src/routes/api.ts
+🔗 Calls:   verify, decodePayload, throwIfExpired
 ```
 
-Returns: all files this file imports, and all files that import this file. Use for understanding a module's place in the architecture before a major refactor.
+- **Deps** → what this file imports (and which symbols it uses from each)
+- **Used by** → which other files import this file
+- **Calls** → functions this chunk calls directly
 
----
-
-## 🔄 Standard Workflows
-
-### Workflow A: Answer a Question About the Code
-1. `search_code(query: "...")` → identify the relevant chunk
-2. `get_chunk("id")` → read the full code if needed
-3. Answer from the returned context. Do not read other files speculatively.
-
-### Workflow B: Implement a New Feature
-1. `search_code` → find where to add the new code (nearest component/module)
-2. `get_file_skeleton` → understand the file structure before editing
-3. `get_call_graph` → check if any shared utilities you'll use are already called elsewhere
-4. Implement in the correct file. Do not create new files unless no existing one fits.
-
-### Workflow C: Refactor an Existing Function
-1. `search_code(exact_tokens: "functionName")` → locate the function
-2. `get_call_graph("functionName")` → find ALL callers
-3. `get_chunk("id")` → read the current implementation
-4. Modify the function AND update all callers identified in step 2.
-
-### Workflow D: Debug an Error
-1. Extract the exact error message / function name from the stack trace
-2. `search_code(query: "<error description>", exact_tokens: "<functionName>")` → find the source
-3. `get_chunk("id")` → read the code
-4. `get_call_graph("functionName")` → trace upstream if the bug is in a caller
-5. Fix and propagate.
-
-### Workflow E: Understand a File's Role
-1. `get_file_skeleton("src/path/file.ts")` → see all exports
-2. `graph://dependencies/src/path/file.ts` → see what it depends on and what depends on it
-3. Use this information to answer architecture questions without reading the full file.
+Use this topology to navigate without additional tool calls. `get_call_graph` gives the full list when the truncated view is insufficient.
 
 ---
 
-## ⚠️ What NOT To Do
+## Index Health
+
+If search results seem wrong or stale:
+1. Call `list_index_stats()` — check chunk count, vector status, daemon status, index age
+2. If index age > 1h with no activity, ask the user to run `npm run mcp:index`
+3. If a symbol is missing from `resolve_symbol`, fall back to `search_code`
 
-| Forbidden Action | Correct Alternative |
-|-----------------|---------------------|
-| `readFile("src/components/Button.tsx")` without search first | `search_code("button component with press animation")` |
-| `listDir("src/stores")` to find a store | `search_code("zustand store for auth state")` |
-| `search_code(top_k: 20)` to "see everything" | Search with a specific query; raise top_k only if 5 results miss the target |
-| Editing a function without checking callers | `get_call_graph("fnName")` first |
-| Re-running `search_code` with the same query | Refine the query or use `exact_tokens` |
-| Reading a full file to understand its structure | `get_file_skeleton("path")` |
+Search modes reported:
+- `🧠 Hybrid (semantic + lexical RRF)` — full quality, Ollama running
+- `🔤 Lexical only` — BM25 only, Ollama unavailable; still high quality (R@5=1.00)
 
 ---
 
-## 📐 Mental Model
+## Quick Reference
 
-Think of `graph-indexer` as a **surgical map of the codebase**:
-- Every function is a GPS coordinate (chunk ID + file:line)
-- `search_code` is the navigator — it gives you the route
-- `get_chunk` is the zoom-in — it shows the details of one location
-- `get_call_graph` is the traffic analysis — it shows who depends on the road you're about to repave
-- Topology (`⬇️ Deps` / `⬆️ Used by`) is the city map — shows how locations connect
+```
+get_repo_map()                          → full codebase overview, ~1500 tok
+get_repo_map(path_filter="auth")        → subsystem overview, ~300 tok
+resolve_symbol("ExactName")             → instant definition + topology
+search_code("concept", "signatures")    → find candidates, ~100 tok
+get_chunk_summary(id)                   → interface view, ~50 tok
+get_chunk(id)                           → full body, ~300 tok
+get_file_skeleton("path/file.ts")       → all exports in file, ~80 tok
+get_call_graph("name")                  → all callers, pre-refactor check
+list_index_stats()                      → index health
+graph://dependencies/{file_path}        → bidirectional dep graph
+```
 
-You have a map. Never wander blindly.
+graph-indexer v1.0.3 · BM25 + hybrid RRF · R@5=1.00, MRR=0.95 across 5 major frameworks