graph-indexer 1.1.0 → 2.0.0

package/parse/routes.mjs

@@ -0,0 +1,327 @@
+/**
+ * @file parse/routes.mjs
+ * @description HTTP route extraction from AST (Express/NestJS/FastAPI/Flask/Spring Boot).
+ * @author MaquinaTech <https://github.com/MaquinaTech>
+ * @copyright (c) 2026 MaquinaTech. All rights reserved.
+ * @license MIT
+ */
+
+// ─── HTTP route extraction ────────────────────────────────────────────────────
+// The call graph records that a function was called, but cannot connect an HTTP
+// verb+path (`GET /api/users`) to the handler that serves it. extractRoutes mines
+// that mapping at index time from the four common shapes:
+//   • decorator-on-method     — NestJS           (@Get/@Post on a class method)
+//   • decorator-on-function   — FastAPI/Flask    (@app.get / @app.route)
+//   • annotation-on-method    — Spring Boot      (@GetMapping / @RequestMapping)
+//   • functional registration — Express/Koa      (router.get('/x', handler))
+// Each route resolves its handler to a chunk id (by name, case-sensitive) so an
+// agent can jump straight from an endpoint to get_chunk / get_call_graph on the
+// handler. No framework names are hardcoded beyond the verb sets — detection is by
+// AST node type, mirroring extractDecorators / extractCallSites.
+
+const HTTP_VERBS = new Set(['get', 'post', 'put', 'delete', 'patch', 'all', 'head', 'options']);
+const ROUTE_JS_LIKE = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'];
+
+/** Unquote a string-literal node across grammars (JS string_fragment, Python
+ *  string_content, Java string_fragment, …). Returns null for non-string nodes. */
+function _routeLiteral(node) {
+    if (!node) return null;
+    const STR = new Set(['string', 'template_string', 'string_literal',
+        'interpreted_string_literal', 'raw_string_literal']);
+    if (!STR.has(node.type)) return null;
+    const frag = node.namedChildren?.find(c => /fragment|content/.test(c.type));
+    if (frag) return frag.text;
+    return node.text.replace(/^[`'"]+|[`'"]+$/g, '');
+}
+
+/** Join a controller/class path prefix to a method path. Empty prefix → path as-is
+ *  (spec: "if no Controller prefix, leave it as-is"). Collapses duplicate slashes. */
+function _joinRoutePath(prefix, sub) {
+    prefix = (prefix || '').trim();
+    sub = (sub || '').trim();
+    if (!prefix) return sub;
+    if (!sub) return prefix;
+    return (prefix.replace(/\/+$/, '') + '/' + sub.replace(/^\/+/, '')).replace(/\/{2,}/g, '/');
+}
+
+/** Decorators that lead a node as siblings (mirrors extractDecorators' sibling walk).
+ *  NestJS method decorators sit as previous siblings inside the class_body. */
+function _leadingDecorators(node) {
+    const out = [];
+    let prev = node.previousSibling;
+    while (prev) {
+        if (prev.type === 'decorator') out.push(prev);
+        else if (prev.isNamed && prev.type !== 'comment') break;
+        prev = prev.previousSibling;
+    }
+    return out;
+}
+
+/** Parse a TS/JS decorator node into { name, path } — name is the callee (`Get`,
+ *  `Controller`), path is its first string argument (or null for bare `@Get()`). */
+function _parseTsDecorator(decoNode) {
+    const call = decoNode.namedChildren?.find(c => c.type === 'call_expression');
+    if (!call) {
+        const id = decoNode.namedChildren?.find(c => c.type === 'identifier');
+        return { name: id?.text || decoNode.text.replace(/^@/, '').split(/[\s(]/)[0], path: null };
+    }
+    const fn = call.childForFieldName?.('function');
+    let name = '';
+    if (fn?.type === 'identifier') name = fn.text;
+    else if (fn?.type === 'member_expression') name = fn.childForFieldName?.('property')?.text || '';
+    const args = call.childForFieldName?.('arguments');
+    const firstStr = args?.namedChildren?.find(c => _routeLiteral(c) != null);
+    return { name, path: _routeLiteral(firstStr) };
+}
+
+/** NestJS: @Get/@Post/… on class methods, with the enclosing
+ *  @Controller(prefix) prepended. */
+function _extractNestRoutes(rootNode, emit) {
+    const stack = [rootNode];
+    while (stack.length) {
+        const n = stack.pop();
+        if (n.type === 'class_declaration' || n.type === 'abstract_class_declaration') {
+            // For `export class` the @Controller decorator is a leading sibling inside
+            // export_statement; for bare/abstract class it is a direct child before class_body.
+            const classDecos = [..._leadingDecorators(n)];
+            for (let i = 0; i < n.namedChildCount; i++) {
+                const c = n.namedChild(i);
+                if (c.type === 'class_body') break;
+                if (c.type === 'decorator') classDecos.push(c);
+            }
+            let prefix = '';
+            for (const d of classDecos) {
+                const { name, path } = _parseTsDecorator(d);
+                if (name === 'Controller' && path != null) { prefix = path; break; }
+            }
+            const body = n.childForFieldName?.('body')
+                || n.namedChildren?.find(c => c.type === 'class_body');
+            if (body) {
+                for (let i = 0; i < body.namedChildCount; i++) {
+                    const member = body.namedChild(i);
+                    if (member.type !== 'method_definition') continue;
+                    const handler = member.childForFieldName?.('name')?.text
+                        || member.namedChildren?.find(c => c.type === 'property_identifier')?.text;
+                    for (const d of _leadingDecorators(member)) {
+                        const { name, path } = _parseTsDecorator(d);
+                        if (!name || !HTTP_VERBS.has(name.toLowerCase())) continue;
+                        emit(name, _joinRoutePath(prefix, path), handler, member.startPosition.row + 1, 'nestjs');
+                    }
+                }
+            }
+        }
+        for (let i = 0; i < n.namedChildCount; i++) stack.push(n.namedChild(i));
+    }
+}
+
+/** Derive a handler name from an Express argument node: a bare identifier, a member
+ *  expression (`ctrl.getThing` → 'getThing', `this.handler` → 'handler'), or a
+ *  `.bind()` call (`handler.bind(this)` → 'handler'). Arrow/inline fn → 'anonymous'. */
+function _jsHandlerName(node) {
+    if (!node) return 'anonymous';
+    if (node.type === 'identifier') return node.text;
+    if (node.type === 'member_expression') {
+        return node.childForFieldName?.('property')?.text || 'anonymous';
+    }
+    if (node.type === 'call_expression') {
+        const callee = node.childForFieldName?.('function');
+        if (callee?.type === 'member_expression') {
+            const obj = callee.childForFieldName?.('object');
+            if (obj?.type === 'identifier') return obj.text;                                   // handler.bind(this) → handler
+            if (obj?.type === 'member_expression') return obj.childForFieldName?.('property')?.text || 'anonymous';
+            return callee.childForFieldName?.('property')?.text || 'anonymous';
+        }
+        if (callee?.type === 'identifier') return callee.text;                                 // makeHandler() → makeHandler
+    }
+    return 'anonymous'; // arrow_function / function / function_expression / unknown
+}
+
+/** Express / Koa: `<router|app>.<verb>(<path>, …, <handler>)` call sites. The route
+ *  path must be rooted ('/…') or a wildcard ('*') — this matches Express/Koa
+ *  convention and rejects look-alike calls (`cache.get('key', cb)`, `map.get(k)`). */
+function _extractExpressRoutes(rootNode, emit) {
+    const stack = [rootNode];
+    while (stack.length) {
+        const n = stack.pop();
+        if (n.type === 'call_expression') {
+            const fn = n.childForFieldName?.('function');
+            if (fn?.type === 'member_expression') {
+                const verb = fn.childForFieldName?.('property')?.text || '';
+                const args = n.childForFieldName?.('arguments');
+                if (verb && HTTP_VERBS.has(verb.toLowerCase()) && args) {
+                    const named = args.namedChildren || [];
+                    const routePath = _routeLiteral(named[0]);
+                    if (routePath != null && /^[/*]/.test(routePath) && named.length >= 2) {
+                        // The handler is the LAST argument — preceding args may be middleware.
+                        const handler = _jsHandlerName(named[named.length - 1]);
+                        emit(verb, routePath, handler, n.startPosition.row + 1, 'express');
+                    }
+                }
+            }
+        }
+        for (let i = 0; i < n.namedChildCount; i++) stack.push(n.namedChild(i));
+    }
+}
+
+/** FastAPI / Flask: @app.get / @router.post / @app.route(path, methods=[…]). */
+function _extractPyRoutes(rootNode, emit) {
+    const stack = [rootNode];
+    while (stack.length) {
+        const n = stack.pop();
+        if (n.type === 'decorated_definition') {
+            const def = n.namedChildren?.find(c => c.type === 'function_definition');
+            const handler = def?.childForFieldName?.('name')?.text
+                || def?.namedChildren?.find(c => c.type === 'identifier')?.text;
+            const line = (def || n).startPosition.row + 1;
+            for (const d of n.namedChildren || []) {
+                if (d.type !== 'decorator') continue;
+                const call = d.namedChildren?.find(c => c.type === 'call');
+                const fn = call?.childForFieldName?.('function');
+                if (fn?.type !== 'attribute') continue;
+                const verb = fn.childForFieldName?.('attribute')?.text || '';
+                const args = call.childForFieldName?.('arguments');
+                // FastAPI uses a positional path string; Flask uses `path=`/`rule=` keyword argument.
+                let routePath = _routeLiteral(args?.namedChildren?.find(c => c.type === 'string'));
+                if (routePath == null) {
+                    const kw = args?.namedChildren?.find(c => c.type === 'keyword_argument'
+                        && ['path', 'rule'].includes(c.childForFieldName?.('name')?.text));
+                    routePath = _routeLiteral(kw?.childForFieldName?.('value'));
+                }
+                // Require a rooted path string to reject look-alike decorators such as
+                // `@cache.get("key")` or `@retry.post(n=3)` that share verb names.
+                const isRoute = routePath != null && routePath.startsWith('/');
+                if (HTTP_VERBS.has(verb.toLowerCase())) {
+                    if (isRoute) emit(verb, routePath, handler, line, 'fastapi');
+                } else if (verb === 'route' && isRoute) {
+                    // Flask `@app.route` can declare multiple HTTP methods; default GET when `methods` is omitted.
+                    const kw = args?.namedChildren?.find(c => c.type === 'keyword_argument'
+                        && c.childForFieldName?.('name')?.text === 'methods');
+                    const list = kw?.childForFieldName?.('value');
+                    const methods = list
+                        ? (list.namedChildren || []).map(_routeLiteral).filter(Boolean)
+                        : [];
+                    for (const m of (methods.length ? methods : ['GET'])) {
+                        emit(m, routePath, handler, line, 'flask');
+                    }
+                }
+            }
+        }
+        for (let i = 0; i < n.namedChildCount; i++) stack.push(n.namedChild(i));
+    }
+}
+
+/** Spring Boot: @GetMapping/@PostMapping/… and @RequestMapping(value=…, method=…)
+ *  on methods, with class-level @RequestMapping as a prefix. */
+function _springAnnotation(annNode) {
+    // annotation > identifier <name> + annotation_argument_list
+    const name = annNode.namedChildren?.find(c => c.type === 'identifier')?.text || '';
+    const argList = annNode.namedChildren?.find(c => c.type === 'annotation_argument_list');
+    const verbOf = (t) => (t || '').split('.').pop(); // RequestMethod.POST → POST
+    let path = null, methods = [];
+    if (argList) {
+        const positional = argList.namedChildren?.find(c => _routeLiteral(c) != null);
+        if (positional) path = _routeLiteral(positional);
+        for (const pair of argList.namedChildren || []) {
+            if (pair.type !== 'element_value_pair') continue;
+            const key = pair.namedChildren?.[0]?.text;
+            const valNode = pair.namedChildren?.[1];
+            if (key === 'value' || key === 'path') path = _routeLiteral(valNode) ?? path;
+            else if (key === 'method') {
+                // `method` may be a single value or an array literal — handle both shapes.
+                methods = (valNode?.type === 'element_value_array_initializer'
+                    ? (valNode.namedChildren || []).map(c => verbOf(c.text))
+                    : [verbOf(valNode?.text)]).filter(Boolean);
+            }
+        }
+    }
+    return { name, path, methods };
+}
+
+const SPRING_VERB = {
+    GetMapping: 'GET', PostMapping: 'POST', PutMapping: 'PUT',
+    DeleteMapping: 'DELETE', PatchMapping: 'PATCH',
+};
+
+function _extractSpringRoutes(rootNode, emit) {
+    const stack = [rootNode];
+    while (stack.length) {
+        const n = stack.pop();
+        if (n.type === 'class_declaration') {
+            const mods = n.namedChildren?.find(c => c.type === 'modifiers');
+            let prefix = '';
+            for (const a of (mods?.namedChildren || [])) {
+                if (a.type !== 'annotation') continue;
+                const { name, path } = _springAnnotation(a);
+                if (name === 'RequestMapping' && path != null) { prefix = path; break; }
+            }
+            const body = n.namedChildren?.find(c => c.type === 'class_body');
+            for (const member of (body?.namedChildren || [])) {
+                if (member.type !== 'method_declaration') continue;
+                const handler = member.childForFieldName?.('name')?.text;
+                const mMods = member.namedChildren?.find(c => c.type === 'modifiers');
+                for (const a of (mMods?.namedChildren || [])) {
+                    if (a.type !== 'annotation' && a.type !== 'marker_annotation') continue;
+                    const { name, path, methods } = _springAnnotation(a);
+                    let verbs;
+                    if (SPRING_VERB[name]) verbs = [SPRING_VERB[name]];
+                    else if (name === 'RequestMapping') verbs = methods.length ? methods : ['ALL'];
+                    else continue;
+                    // @RequestMapping(method = {GET, POST}) → one route per verb.
+                    for (const verb of verbs) {
+                        emit(verb, _joinRoutePath(prefix, path), handler, member.startPosition.row + 1, 'spring');
+                    }
+                }
+            }
+        }
+        for (let i = 0; i < n.namedChildCount; i++) stack.push(n.namedChild(i));
+    }
+}
+
+/**
+ * Map HTTP routes to their handlers for one parsed file.
+ *
+ * @param {object}  rootNode  parsed AST root
+ * @param {string}  relPath   repo-relative file path (stored on each route)
+ * @param {object[]} chunks   the file's already-extracted chunks (handler→id lookup)
+ * @param {string}  ext       dotted file extension
+ * @returns {Array<{method,path,handler_name,handler_chunk_id,file_path,line,framework}>}
+ */
+export function extractRoutes(rootNode, relPath, chunks, ext) {
+    const routes = [];
+    if (!rootNode) return routes;
+
+    // Case-sensitive; first definition wins to match the chunk extraction order.
+    const idByName = new Map();
+    for (const c of (chunks || [])) {
+        if (c && c.name && !idByName.has(c.name)) idByName.set(c.name, c.id);
+    }
+
+    const emit = (method, routePath, handlerName, line, framework) => {
+        if (!method) return;
+        // NestJS controller-prefixed paths omit the leading slash ('users/:id'); normalise
+        // so a '/'-prefix query matches uniformly across all frameworks.
+        let p = routePath == null ? '' : String(routePath);
+        if (p && !p.startsWith('/')) p = '/' + p;
+        routes.push({
+            method: String(method).toUpperCase(),
+            path: p,
+            handler_name: handlerName || 'anonymous',
+            handler_chunk_id: (handlerName && idByName.has(handlerName)) ? idByName.get(handlerName) : null,
+            file_path: relPath,
+            line,
+            framework,
+        });
+    };
+
+    try {
+        if (ROUTE_JS_LIKE.includes(ext)) {
+            _extractNestRoutes(rootNode, emit);
+            _extractExpressRoutes(rootNode, emit);
+        } else if (ext === '.py') {
+            _extractPyRoutes(rootNode, emit);
+        } else if (ext === '.java') {
+            _extractSpringRoutes(rootNode, emit);
+        }
+    } catch { /* best-effort — never fail indexing */ }
+    return routes;
+}

package/prompts/CORE.md

@@ -0,0 +1,86 @@
+<system_prompt layer="1" name="graph-indexer-core" version="1.0">
+
+    <context>This codebase is pre-indexed. The graph-indexer MCP server answers code questions from an AST-precise index in tens of tokens, and most result cards carry cross-file topology (imports, importers, calls) native tools cannot see. Treat the codebase as a QUERYABLE DATABASE, never as documents to wander through.</context>
+
+    <prime_directive>
+        <do>Every code DISCOVERY — locating, understanding, summarizing, tracing callers/deps — STARTS with a graph-indexer tool.</do>
+        <dont>Never start discovery with a native tool (read-file, list-dir, grep, find, built-in codebase search). Native tools are allowed ONLY under fallback_protocol.</dont>
+        <note>Editing is unaffected — modify code with your normal tools. Only discovery belongs to the index.</note>
+    </prime_directive>
+
+    <hard_limits priority="absolute">
+        These are physical constraints, not advice; no lower layer or task framing relaxes them. Every wasted call bloats context with stale output and delays the answer — efficiency is a precondition for accuracy.
+
+        <limit id="1" name="4-call-budget">MAX 4 graph-indexer calls per user question — ONE budget across all phases (locate, read, map-usage, verify). No resets, no self-granted extensions. After the 4th result, ANSWER from what you hold, naming in one line what's unverified and offering to dig further if asked. Planning a 5th call? That call IS your answer. Budget resets only on a new user question. 80% verified in 4 calls beats 100% in 14 — latency and context bloat destroy answer quality faster than one missing detail.</limit>
+
+        <limit id="2" name="batch-dont-iterate">≥2 known names = exactly ONE call: search_code("NameA NameB NameC", top_k: 2×N). Each name gets an exact-name boost so all definitions surface together, and because bodies are indexed the chunks that USE them surface right below — often answering "where used" in the same call. NEVER one resolve_symbol/search per name (the single most common failure). resolve_symbol is for a SINGLE known name only.</limit>
+
+        <limit id="3" name="consume-before-call">After each result, before any new call, extract: (a) what it already answers, (b) what its topology lines — Deps:, Used by:, Calls:, paths, line ranges, signatures, extends — give you, (c) which chunk IDs you now hold. A new call is justified only for ONE specific named fact no result in hand contains. The "Expand: get_chunk(...)" footer is an offer, not an instruction. Nothing specific missing → answer now.</limit>
+
+        <limit id="4" name="rule-of-one">At most ONE example hop per question: one consumer to show usage, or one parent/helper to clarify an interface. List other consumers directly from topology text. Never trace recursively — post-budget uncertainty is resolved by saying so, never by more calls.</limit>
+    </hard_limits>
+
+    <call_protocol>
+        <step n="0">Classify against the playbooks and plan ≤4 calls BEFORE the first call.</step>
+        <step n="1">Make the cheapest call filling the largest gap. Escalate detail stepwise: signatures → summary → smart → full.</step>
+        <step n="2">Consume (limit 3). Gap list empty → answer.</step>
+        <step n="3">Repeat until answerable or the 4th call is spent — then answer.</step>
+        <answer_contract>A component answer covers definition (what it is, signature, behaviour), usage (who uses it — from the Used by: topology, NOT extra calls), and its direct dependencies (the Deps:/Calls line, free on the card). Deps:/Used by: are DEPTH-1: a grandchild dependency (a dep of a dep) is NOT on X's card — name the boundary ("PillCluster is itself built from pill primitives") and stop, UNLESS the question explicitly asks for the FULL ecosystem / what X's parts are in turn made of, in which case follow the full-ecosystem playbook (ONE hop into the principal dependency). Name uncertainties instead of chasing them.</answer_contract>
+    </call_protocol>
+
+    <playbooks>
+        <playbook name="one-known-symbol" calls="1-2">resolve_symbol("Name") → answer. get_chunk(id) only when the body is the question. Miss → ONE search_code(query: "what it does", exact_tokens: "Name"), then accept the outcome.</playbook>
+        <playbook name="several-known-symbols" calls="1-2">ONE search_code(query: "A B C D", detail: "smart", top_k: 2×N): top cards = definitions with query-relevant body lines + topology; lower cards = consumers whose bodies mention the names. Spend a 2nd call only to escalate ONE result to full body. The serial resolve_symbol(A)→(B)→(C)→(D) loop burns the budget with nothing read — limit 2 forbids it.</playbook>
+        <playbook name="concept-or-behaviour" calls="2-3">search_code(behavioural query, detail: "signatures", top_k: 5) → get_chunk_summary(best id) or one re-search with detail: "smart" → answer. LOW-CONFIDENCE HANDOFF: a "⚠️ Low confidence — Candidate files" line (json: low_confidence + candidate_files[]) means the right FILE is in that short list but wasn't ranked #1 — get_file_skeleton ONE candidate (or re-search with a symbol name / exact_tokens), never read whole files blindly. It never appears on confident symbol lookups, so its presence is itself the signal to switch tactics.</playbook>
+        <playbook name="where-used-or-impact" calls="1-2">Blast radius, by node type (check the card): FUNCTION/METHOD → get_call_graph("name"); CLASS/TYPE/INTERFACE/ENUM → find_references("Name"); thin result → ONE search_code(exact_tokens: "Name", detail: "signatures", top_k: 8). Never read files to hunt usage. "No callers/refs" ≠ unused (may be framework-invoked). A STALE index footer (json: index.stale) means a "safe to modify" verdict may be wrong — trust it only after `npm run mcp:index`.</playbook>
+        <playbook name="one-file" calls="1">get_file_skeleton(path): every definition + line ranges, nested methods included. Cost ∝ file (small ~80 tok, god-class 1.5–2.5k). Already resolved the symbol? get_chunk_summary(id, expand_calls) is cheaper. Never skeleton a big file to find call sites — that is get_call_graph.</playbook>
+        <playbook name="orientation" calls="1">get_repo_map(path_filter: "subsystem") once. Never twice with overlapping filters.</playbook>
+        <playbook name="trace-a-flow" calls="1-2">"How does X flow through the system / how do these connect" → get_subgraph("seed", depth: 2) ONCE: connected callees + high-confidence callers + type users in a budget, instead of stitching search_code + get_call_graph + find_references yourself. Widen max_nodes/token_budget only on ⚠️ truncated.</playbook>
+        <playbook name="full-ecosystem" calls="2-3">"What is X built from / its full ecosystem / what its parts are in turn made of" is a DEPTH-2 question — the single most common miss is stopping at depth-1. (1) resolve_symbol("X") (or get_chunk) and read the Deps:/Calls/Type refs line = X's DIRECT (depth-1) collaborators. (2) REQUIRED second move: resolve_symbol the PRINCIPAL depth-1 dependency (the one the question centres on) and read ITS Deps:/Calls to name the grandchild (depth-2) deps — the dep-of-a-dep is NOT on X's card, so a one-card answer misses it. List the other depth-1 deps directly from X's topology (rule-of-one: hop into only the principal child). get_subgraph is the WRONG tool for import/type/JSX composition — it walks the CALL graph, never imports/JSX children — so for "what is X built from" resolve the dependency's card, do NOT get_subgraph. (Exception: where composition IS calls — e.g. a Ruby/Python service that *calls* its collaborators — get_subgraph(depth:2) reaches depth-2 directly.)</playbook>
+        <playbook name="modify-a-signature" calls="2-4">get_call_graph("target") FIRST → optionally ONE caller chunk as the edit template → edit. For a refactor where completeness is the point, spend the budget CLOSING the full caller set (high-confidence callers + the name-only bucket + the git "changes with" line), not on body reads — an incomplete caller set is the costly miss here, not a missing body. Exact pre-edit file state = fallback condition 4, not an index call.</playbook>
+    </playbooks>
+
+    <tools>
+        <tool sig="search_code(query, exact_tokens?, detail?, top_k?, token_budget?, rerank?)" cost="100-750">Hybrid lexical+semantic. Cards: name, file:lines, ID, signature, decorators, extends, docstring, topology. detail: signatures ~20 tok/card · smart (default) adds query-relevant body lines · full adds complete bodies. top_k ≤20. token_budget raises body allowance (e.g. 3000 for several full small classes in one call). exact_tokens pins ONE name to rank-1 (several names → put them all in the query). rerank: true = local-LLM reorder of NL queries (~1-2 s) when results are plausible-but-not-quite.</tool>
+        <tool sig="resolve_symbol(symbol)" cost="50">O(1) exact-name lookup, case-insensitive. ALL definitions of that one name, each with signature + topology.</tool>
+        <tool sig="get_chunk(chunk_id, view?)" cost="300">Full body + topology by ID. view: signature = one line.</tool>
+        <tool sig="get_chunk_summary(chunk_id, expand_calls?)" cost="50-150">Signature, doc, calls — no body. expand_calls inlines ≤6 callee signatures. Where a whole class is ONE chunk (Java/C#/PHP, often Python/Kotlin), callees may not resolve → get_file_skeleton or get_chunk answers more.</tool>
+        <tool sig="get_file_skeleton(file_path)" cost="80-2.5k ∝ size">Every definition in one file + line ranges, nested methods included. Parses the LIVE file — precise even for whole-class chunks. Don't reach for it when get_chunk_summary/get_call_graph answers the question.</tool>
+        <tool sig="get_call_graph(target_function, target_class?)" cost="15-100">Repo-wide callers of a FUNCTION/METHOD, high-confidence vs name-only. A class/type/interface returns "no callers" (construction and type-use aren't call edges) → use find_references. target_class scopes an ambiguous name. "No callers" ≠ unused. With git history indexed, appends "🔄 Historically changes with" — fold those files into a refactor's blast radius.</tool>
+        <tool sig="find_references(symbol, target_class?)" cost="15-120">Broader than get_call_graph: callers + subclasses/implementers (extends) + type-annotation users, each high-confidence vs name-only. THE move for a CLASS/TYPE/INTERFACE; for a plain function get_call_graph is the cheaper subset. Per-language coverage of the heritage/type channels is in your language layer.</tool>
+        <tool sig="get_subgraph(symbol, depth?, max_nodes?, token_budget?)" cost="100-600">ONE bounded connected subgraph around a seed: callees + high-confidence callers + type/inheritance users, depth 1–3 (default 2). THE "trace a flow across files" move; replaces chaining. Edges are CALLS + refs/inheritance, NOT imports — a module merely imported (or a JSX child, which is not a call) is NOT reached; for "what is X built from" read the Deps: line, not this. ⚠️ truncated = raise the budget. Not for one body (get_chunk) or a flat caller list (get_call_graph).</tool>
+        <tool sig="find_routes(method?, path?)" cost="15-80">HTTP routes → handler chunk_id for Express/Koa, NestJS, FastAPI/Flask, Spring (controller prefix already joined onto the method path). Feed the chunk_id straight into get_chunk/get_call_graph. method case-insensitive; path "/"=prefix else substring. NOT populated for attribute-routed C#/ASP.NET, PHP (Laravel/Symfony), Rails, or Django URLconf — search the path string there.</tool>
+        <tool sig="get_repo_map(path_filter?, max_files?, sort_by?)" cost="300-1500">Symbol map grouped by file, most-imported first.</tool>
+        <tool sig="list_index_stats()" cost="100">Index health: chunk count, search mode, daemon, freshness.</tool>
+        <tool sig="resource graph://dependencies/{file_path}" cost="100">Bidirectional import topology of one file.</tool>
+        <note>Topology reliability is LANGUAGE-DEPENDENT — your language layer states whether Deps:/Used by: are RELIABLE or WEAK. Where weak, map usage by name search; never read an empty Used by: as "unused". A re_export node = symbol re-exported from an external dependency; its implementation is outside this repo — don't hunt for it.</note>
+    </tools>
+
+    <query_rules>
+        <rule>LEAD WITH KEYWORDS — exact-name and domain-keyword matching is the strongest ranking signal, measurably stronger than the semantic channel. Build queries from concrete identifiers, API names, and domain nouns + the operation ("JWT token validation expiry middleware"). Know or suspect the symbol? include it or pin it with exact_tokens.</rule>
+        <rule>Describe behaviour with concrete nouns + the operation, never a lone abstraction ("parse and validate request body schema", not "validation"). One-word queries are useless.</rule>
+        <rule>Include path hints when known ("middleware auth route").</rule>
+        <rule>NL behavioural phrasing is a SECONDARY rescue, not co-equal: if a keyword search misses, try ONE behavioural rephrase — one, not a loop. Still missing → fallback_protocol.</rule>
+        <rule>In lexical-only mode (see list_index_stats) the semantic channel is off — keyword queries are mandatory.</rule>
+    </query_rules>
+
+    <anti_patterns>
+        <avoid>One resolve_symbol/search per name when several are known (limit 2); the serial-lookup loop is the #1 failure.</avoid>
+        <avoid>"4 calls used but I can continue because…" — there is no because (limit 1).</avoid>
+        <avoid>Re-confirming a fact a result already proved; re-searching anything you hold a chunk ID for; re-searching inside one already-located file (that's get_file_skeleton, once).</avoid>
+        <avoid>Expanding every "Expand: get_chunk(...)" footer — it is an offer. detail: "full" as a default.</avoid>
+        <avoid>Reading a file as the FIRST discovery move; search_code("validateToken") for a single known name (that's resolve_symbol).</avoid>
+        <avoid>Editing an exported signature without get_call_graph first.</avoid>
+        <avoid>Re-indexing after edits, or telling the user to: the live daemon syncs in the background; your next call sees your edits.</avoid>
+    </anti_patterns>
+
+    <fallback_protocol>
+        Native file/search tools are FORBIDDEN for discovery except:
+        <condition id="1">Both query styles AND resolve_symbol genuinely fail to return the target.</condition>
+        <condition id="2">list_index_stats() shows 0 chunks / missing / stale-and-unsynced — tell the user to run `npm run mcp:index`, then fall back for now.</condition>
+        <condition id="3">Non-code files: configs, lockfiles, markdown, templates, data, generated artifacts.</condition>
+        <condition id="4">You need exact current file state for an edit — AFTER the index located the file + line range.</condition>
+        <scope>When falling back, read the ONE file the index pointed to. Never directory-walk or repo-grep what the index already answered.</scope>
+    </fallback_protocol>
+
+</system_prompt>

package/prompts/DOMAIN_TEMPLATE.md

@@ -0,0 +1,46 @@
+<domain_prompt layer="3" name="project-domain" requires="graph-indexer-core">
+
+    <!--
+        LAYER 3 — YOUR PROJECT'S RULES. Replace every [BRACKETED] placeholder with
+        facts about YOUR codebase and delete sections that don't apply. Keep it under
+        ~40 lines: this exists to make the agent's FIRST query hit rank-1, not to
+        restate your architecture docs. May ADD precision to Layers 1–2 but may NEVER
+        relax the 4-call budget, the prime directive, or the fallback protocol.
+        Tip: delete these comments once filled — they cost tokens every session.
+    -->
+
+    <project_identity>
+        <name>[PROJECT_NAME]</name>
+        <summary>[One sentence: what this system does and for whom.]</summary>
+    </project_identity>
+
+    <entry_points>
+        <!-- Where execution starts — saves the agent its first orientation call. -->
+        <entry path="[src/main.ts]" role="[application bootstrap]"/>
+        <entry path="[src/api/routes/]" role="[HTTP surface]"/>
+    </entry_points>
+
+    <domain_vocabulary>
+        <!-- Map business words to code words so search queries hit rank-1. -->
+        <term business="[invoice]" code="[BillingDocument]"/>
+        <term business="[customer]" code="[Account, AccountHolder]"/>
+    </domain_vocabulary>
+
+    <critical_paths>
+        <!-- Symbols where get_call_graph is MANDATORY before any change. -->
+        <symbol name="[processPayment]" reason="[money-moving path; callers in 3 services]"/>
+    </critical_paths>
+
+    <no_go_zones>
+        <!-- Code the agent should never explore or edit. -->
+        <zone path="[src/generated/]" reason="[generated — regenerate, never edit]"/>
+        <zone path="[legacy/]" reason="[frozen for deprecation]"/>
+    </no_go_zones>
+
+    <house_rules>
+        <!-- Project-specific conventions the agent must respect. -->
+        <rule>[Example: all new endpoints require a schema in src/schemas/.]</rule>
+        <rule>[Example: feature flags are checked via FlagService, never process.env.]</rule>
+    </house_rules>
+
+</domain_prompt>

package/prompts/INTEGRATION.md

@@ -0,0 +1,123 @@
+# Integrating the graph-indexer prompt suite
+
+The suite is a **3-layer architecture**. Each layer is a standalone XML block; you combine them by **concatenation, in layer order**. Never merge layers into one hand-edited blob ("god prompt") — that is what causes context dilution and framework hallucinations.
+
+```
+prompts/
+├── CORE.md                          Layer 1 — universal rules (always required)
+├── languages/                       Layer 2 — pick the ones matching your code
+│   ├── JAVASCRIPT_TYPESCRIPT.md
+│   ├── PYTHON.md
+│   ├── GO.md
+│   ├── RUST.md
+│   ├── JAVA.md
+│   ├── KOTLIN.md
+│   ├── CSHARP.md
+│   ├── RUBY.md
+│   ├── PHP.md
+│   ├── CSS_SCSS.md
+│   ├── BASH.md
+│   ├── C.md
+│   └── SWIFT.md
+├── frameworks/                      Layer 2 — pick the ones matching your stack
+│   ├── REACT.md
+│   ├── NODE_EXPRESS_NESTJS.md
+│   ├── FASTAPI_DJANGO.md
+│   ├── SPRING_BOOT.md
+│   ├── RAILS.md
+│   ├── LARAVEL_SYMFONY.md
+│   ├── ASPNET_CORE.md
+│   └── ANDROID.md
+└── DOMAIN_TEMPLATE.md               Layer 3 — copy, then fill with YOUR project's rules
+```
+
+## The assembly rule
+
+```
+Layer 1 (CORE)  →  Layer 2 (language)  →  Layer 2 (framework)  →  Layer 3 (domain)
+```
+
+1. **Order matters.** Core first, then language, then framework, then domain. Frameworks assume their base language layer is already loaded (`requires=` attribute in each file).
+2. **Precedence on conflict:** a more specific layer *refines* a more general one (e.g. REACT's render-site protocol refines the core call-graph rule). But Layer 1's `<hard_limits>`, `<prime_directive>`, and `<fallback_protocol>` are **inviolable** — no lower layer may relax them.
+3. **Only include layers you need.** A Go microservice needs `CORE + GO` — nothing else. Every unused layer dilutes the agent's attention.
+
+## Automatic setup (recommended)
+
+```bash
+npx graph-indexer init
+```
+
+`init` asks for your languages and frameworks, then lets you **multi-select which agents/IDEs to wire** (Claude Code/Desktop, Cursor, VS Code/Copilot, Windsurf, Cline/Roo, JetBrains Junie, Codex/AGENTS.md, Gemini CLI). The choice is pre-checked from what's detected (or your last run) and remembered in `.graph-indexer/config.json`, so only the agents you pick get files — the two `GRAPH_INDEXER_*.md` source files are always written. For each selected agent it generates:
+
+| File | Agent | Ownership |
+| :--- | :--- | :--- |
+| `GRAPH_INDEXER_PROMPT.md` | source of truth (Layers 1 + 2, assembled for your selection) | Generated — re-run `init` to regenerate; do not edit |
+| `GRAPH_INDEXER_DOMAIN.md` | source of truth (Layer 3 template) | **Yours** — fill it in; `init` never overwrites it |
+| `CLAUDE.md` | Claude Code (`@`-import lines) | Appended once, idempotent |
+| `.cursor/rules/graph-indexer.mdc` | Cursor (always-on rule) | Generated — regenerated on re-run |
+| `.windsurf/rules/graph-indexer.md` | Windsurf (always-on rule) | Generated — regenerated on re-run |
+| `.clinerules/graph-indexer.md` | Cline / Roo Code (rule) | Generated — regenerated on re-run |
+| `.github/copilot-instructions.md` | GitHub Copilot (managed block) | Shared — your text outside the markers is preserved |
+| `.junie/guidelines.md` | JetBrains Junie (managed block) | Shared — your text outside the markers is preserved |
+| `AGENTS.md` | AGENTS.md standard: Codex, Zed, Jules, … (managed block) | Shared — your text outside the markers is preserved |
+| `GEMINI.md` | Gemini CLI (`@`-import) | Shared — references the canonical files (no duplication); your text outside the markers is preserved |
+
+**Why some files reference and others embed.** `CLAUDE.md` and `GEMINI.md` use `@`-import (Claude Code imports, Gemini CLI's Memory Import Processor), so they just point at the canonical `GRAPH_INDEXER_*.md` — zero duplication. The Cursor/Windsurf/Cline rule files hold the assembled prompt verbatim, and the Copilot/Junie/AGENTS.md managed blocks embed it inline, because those tools read the file **literally** — they have no reliable import mechanism, so an `@`-reference would appear as plain text and the rules would silently not apply. (AGENTS.md embeds because its main reader, OpenAI Codex, does not yet honour `@` imports.) Embedded blocks are wrapped in `<!-- >>> graph-indexer >>> -->` … `<!-- <<< graph-indexer <<< -->` markers, so your own instructions around them survive re-runs.
+
+## Manual setup
+
+`init` already wires Claude Code, Cursor, Windsurf, Cline/Roo, Copilot, Junie, the AGENTS.md ecosystem, and Gemini (see the table above). Reach for the steps below only for a legacy format (`.cursorrules`, `.clauderc`), a raw-system-prompt config, or an agent not in that list.
+
+### Claude Code (`CLAUDE.md` or `.clauderc`)
+
+Claude Code loads `CLAUDE.md` from the project root and supports `@path` imports — reference the assembled files instead of pasting them:
+
+```markdown
+# CLAUDE.md
+@GRAPH_INDEXER_PROMPT.md
+@GRAPH_INDEXER_DOMAIN.md
+```
+
+If your tooling uses a `.clauderc` (or any agent config that takes a raw system prompt), paste the concatenated layers directly, in layer order.
+
+### Cursor (`.cursorrules` or `.cursor/rules/`)
+
+For the legacy single-file format, concatenate the layers into `.cursorrules`:
+
+```bash
+cat node_modules/graph-indexer/prompts/CORE.md \
+    node_modules/graph-indexer/prompts/languages/JAVASCRIPT_TYPESCRIPT.md \
+    node_modules/graph-indexer/prompts/frameworks/REACT.md \
+    GRAPH_INDEXER_DOMAIN.md > .cursorrules
+```
+
+For the modern format, put the same concatenation in `.cursor/rules/graph-indexer.mdc` with this frontmatter:
+
+```yaml
+---
+description: graph-indexer usage rules
+alwaysApply: true
+---
+```
+
+### Any other agent
+
+Concatenate the layers (in order) into whatever field your agent calls "system prompt", "rules", or "custom instructions". The XML structure is self-describing — no other formatting is required.
+
+## Worked examples
+
+| Stack | Assembly |
+| :--- | :--- |
+| React SPA | `CORE + languages/JAVASCRIPT_TYPESCRIPT + languages/CSS_SCSS + frameworks/REACT + domain` |
+| NestJS API + React front-end (monorepo) | `CORE + languages/JAVASCRIPT_TYPESCRIPT + frameworks/NODE_EXPRESS_NESTJS + frameworks/REACT + domain` |
+| Django service | `CORE + languages/PYTHON + frameworks/FASTAPI_DJANGO + domain` |
+| Spring Boot backend (Java or Kotlin) | `CORE + languages/JAVA` (or `KOTLIN`) `+ frameworks/SPRING_BOOT + domain` |
+| Rails app | `CORE + languages/RUBY + frameworks/RAILS + domain` |
+| Laravel / Symfony app | `CORE + languages/PHP + frameworks/LARAVEL_SYMFONY + domain` |
+| ASP.NET Core API | `CORE + languages/CSHARP + frameworks/ASPNET_CORE + domain` |
+| Android app | `CORE + languages/KOTLIN + frameworks/ANDROID + domain` |
+| Go / Rust service | `CORE + languages/GO` (or `RUST`) `+ domain` |
+
+## Layer 3 — make it yours
+
+Copy `DOMAIN_TEMPLATE.md` (or let `init` create `GRAPH_INDEXER_DOMAIN.md`), then fill in entry points, domain vocabulary, critical paths, and no-go zones. Keep it under ~40 lines: Layer 3 exists to make the agent's *first* query hit rank-1, not to restate your architecture docs.

package/prompts/frameworks/ANDROID.md

@@ -0,0 +1,17 @@
+<environment_prompt layer="2" type="framework" name="android" requires="graph-indexer-core, kotlin" version="1.0">
+
+    <scope>Android (Jetpack, Compose or XML views, coroutines). Loads after the kotlin layer.</scope>
+
+    <critical_fact>Activities, Fragments, Services, ViewModels, BroadcastReceivers are instantiated and driven by the OS: lifecycle methods (onCreate, onResume, onCleared...) have NO inbound edges — empty call graphs mean FRAMEWORK-INVOKED, never dead. Who launches a screen lives in navigation graphs, manifest entries, and intent construction — ONE exact_tokens search on the screen/class name finds the launchers.</critical_fact>
+
+    <rules>
+        <rule name="compose-vs-xml">Composables are ordinary Kotlin functions: get_call_graph("OrderScreen") DOES find composition sites — the graph works for Compose UI, unlike JSX. What it can't see is RECOMPOSITION: state-driven re-execution is runtime — answer "when does this re-render" from the composable's chunk (its state reads), never the graph. XML layouts, nav graphs, manifest are non-code resources (fallback condition 3); the code↔layout link is the resource NAME — search R.layout.x-style identifiers or the binding class name.</rule>
+        <rule name="generated-artifacts">R, BuildConfig, ViewBinding/DataBinding classes, generated DAO impls have NO chunks — the annotated interface or XML they were generated FROM is the answer; never hunt for generated bodies.</rule>
+        <rule name="di-annotations">Hilt/Dagger injection is annotation-driven (@Inject, @Provides, @Module, @HiltViewModel): the container builds the graph, so injection sites carry no caller edges. ONE exact_tokens search on the injected TYPE finds its module/provider and its consumers together.</rule>
+        <rule name="coroutines-and-state">viewModelScope.launch and Flow pipelines decouple call sites from execution (kotlin layer). UI state connects ViewModel → UI by the STATE property name — ONE search of that name finds emitter and collectors together. Click listeners and observers are lambdas with no symbols — find them behaviourally inside the owning screen's chunk.</rule>
+        <rule name="query-style">Screen names, state property names, resource identifiers, DI types are the highest-precision tokens. Intent actions and navigation route strings trace inter-screen flow better than any graph.</rule>
+    </rules>
+
+    <playbook question="explain screen X" calls="2-4">resolve_symbol("XViewModel" or "XScreen") → get_chunk(the one whose logic is in question — ViewModel for behaviour, composable for UI) → ONE exact_tokens search for the launcher or the state property → answer.</playbook>
+
+</environment_prompt>