milens 0.7.1 → 0.7.3

package/dist/server/mcp.js

@@ -6,7 +6,7 @@ import { createServer } from 'node:http';
 import { randomUUID } from 'node:crypto';
 import { resolve, relative, join, dirname } from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { readFileSync, readdirSync, statSync, mkdirSync } from 'node:fs';
+import { readFileSync, readdirSync, statSync, mkdirSync, existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import ignore from 'ignore';
 import { Database } from '../store/db.js';
@@ -22,6 +22,7 @@ import { countDependentFiles } from '../analyzer/risk.js';
 import { registerSessionTools } from './tools/session.js';
 import { registerTestingTools } from './tools/testing.js';
 import { registerSecurityTools } from './tools/security.js';
+import { registerFindingsReportTools } from './tools/findings-report.js';
 import { FileWatcher } from './watcher.js';
 import { reviewPr } from '../analyzer/review.js';
 import { globToRegex } from '../utils.js';
@@ -240,10 +241,10 @@ function isTestFilePath(filePath) {
 // ── Text grep across project files ──
 const GREP_SKIP_DIRS = new Set([
     'node_modules', '.git', 'dist', 'build', 'out',
-    '.next', '.nuxt', '.svelte-kit',
+    '.next', '.nuxt', '.svelte-kit', '.turbo', '.cache', '.parcel-cache',
     '__pycache__', '.venv', 'venv', 'env',
     'vendor', 'target',
-    '.idea', '.vscode',
+    '.idea',
     'coverage', '.nyc_output',
 ]);
 const BINARY_EXTENSIONS = new Set([
@@ -283,8 +284,6 @@ function grepFiles(rootPath, pattern, options) {
                 return;
             const abs = join(dir, entry);
             const rel = relative(rootPath, abs).replace(/\\/g, '/');
-            if (entry.startsWith('.') && entry !== '.')
-                continue;
             if (GREP_SKIP_DIRS.has(entry))
                 continue;
             if (ig.ignores(rel))
@@ -377,62 +376,62 @@ function loadGrepIgnoreRules(rootPath) {
     return ig;
 }
 // ── Server instructions (sent to client via MCP protocol on initialize) ──
-const MILENS_INSTRUCTIONS = `⚠️ CRITICAL: This project is indexed by milens (knowledge graph). Use milens MCP tools BEFORE reading files directly.
-
-WHY: The knowledge graph already knows every symbol, dependency, and reference. Reading files manually = slower, more expensive, and misses hidden connections.
-
-RULE: Before opening ANY file to understand code, call the appropriate milens tool:
-- overview({name: "X"}) — understand a symbol (context + impact + grep). Replaces 3-5 file reads.
-- impact({target: "X", mode: "strict"}) — check blast radius BEFORE editing. strict mode BLOCKS if >5 deps.
-- guard_edit_check({name: "X", session_id}) — HARD safety gate. Call BEFORE every edit. Returns BLOCKED if high risk.
-- grep({pattern: "X"}) — find ALL text references (code, templates, docs, configs, styles).
-- codebase_summary() — 500-token project overview. Use INSTEAD of reading README or exploring directories.
-- detect_changes() — verify changes before committing. Shows changed symbols + risk scores.
-- query({query: "X"}) — find symbol definitions by name. FTS5 instant search.
-
-AUDIT: session_end reports which symbols were safety-checked. Editing without checks = audit gap.
-
-TOKEN SAVINGS: Using milens first typically means far fewer tokens than manual exploration, and fewer missed dependencies — impact/context track code-level references; pair with grep for templates/configs/docs.
-
-milens — code intelligence engine. Indexes codebases into symbol graphs.
-
-## Tool selection
-- \`query\` — find symbol definitions (code identifiers only)
-- \`grep\` — text search ALL files. Use \`scope\` param: all (default), code (source only), imports, definitions
-- \`context\` — 360° view: incoming + outgoing for a symbol
-- \`impact\` — blast radius: what breaks if symbol changes
-- \`overview\` — combined context + impact + grep in one call (preferred for editing workflows)
-- \`guard_edit_check\` — HARD pre-edit gate: blocks if dependents > 5, tracks checks for session audit
-- \`edit_check\` — pre-edit safety: callers + export status + re-export chains + test coverage + ⚠ warnings (fastest for edits)
-- \`trace\` — execution flow: call chains from entrypoints to a symbol (or downstream from it)
-- \`routes\` — detect framework routes/endpoints (Express, FastAPI, NestJS, Flask, Go, PHP, Rails)
-- \`smart_context\` — intent-aware context: understand/edit/debug/test (returns only what matters for intent)
-- \`domains\` — show domain clusters: groups of files forming logical modules based on dependency graph
-- \`repos\` — list all indexed repositories with summary stats (multi-repo support)
-- \`detect_changes\` — git diff → affected symbols
-- \`explain_relationship\` — shortest path between two symbols
-- \`find_dead_code\` — unused exports
-- \`get_file_symbols\` — all symbols in a file
-- \`get_type_hierarchy\` — inheritance tree
-
-## Rules
-- Before editing a symbol: run \`guard_edit_check\` or \`edit_check\` or \`smart_context\` with intent=edit
-- \`guard_edit_check({name, session_id})\` — HARD gate: records check for audit, blocks if dependents > 5
-- \`impact({mode: "strict"})\` — strict mode returns BLOCKED when depth-1 deps > 5
-- For debugging: run \`smart_context\` with intent=debug or \`trace\` to=symbol
-- For writing tests: run \`smart_context\` with intent=test — shows deps to mock + callers to cover
-- \`impact\` only tracks code deps — always pair with \`grep\` for templates/configs
-- Use \`query\` for camelCase/PascalCase identifiers, \`grep\` for display text or multi-word strings
-- impact depth: 1=WILL BREAK, 2=LIKELY AFFECTED, 3=MAY NEED TESTING
-- ⚠ markers indicate unresolved INTERNAL references — external package imports/calls are tracked separately
-- ✓ test coverage shown on edit_check — symbols with no test coverage get a warning
-- ⏳ staleness: files not re-analyzed in 24h are flagged — consider re-running \`milens analyze\`
-
-## Resources (MCP Resources protocol)
-- \`milens://overview\` — index overview (stats, domains, coverage, staleness)
-- \`milens://symbol/{name}\` — symbol context by name
-- \`milens://file/{path}\` — all symbols in a file
-- \`milens://domain/{name}\` — domain cluster details
+const MILENS_INSTRUCTIONS = `⚠️ CRITICAL: This project is indexed by milens (knowledge graph). Use milens MCP tools BEFORE reading files directly.
+
+WHY: The knowledge graph already knows every symbol, dependency, and reference. Reading files manually = slower, more expensive, and misses hidden connections.
+
+RULE: Before opening ANY file to understand code, call the appropriate milens tool:
+- overview({name: "X"}) — understand a symbol (context + impact + grep). Replaces 3-5 file reads.
+- impact({target: "X", mode: "strict"}) — check blast radius BEFORE editing. strict mode BLOCKS if >5 deps.
+- guard_edit_check({name: "X", session_id}) — HARD safety gate. Call BEFORE every edit. Returns BLOCKED if high risk.
+- grep({pattern: "X"}) — find ALL text references (code, templates, docs, configs, styles).
+- codebase_summary() — 500-token project overview. Use INSTEAD of reading README or exploring directories.
+- detect_changes() — verify changes before committing. Shows changed symbols + risk scores.
+- query({query: "X"}) — find symbol definitions by name. FTS5 instant search.
+
+AUDIT: session_end reports which symbols were safety-checked. Editing without checks = audit gap.
+
+TOKEN SAVINGS: Using milens first typically means far fewer tokens than manual exploration, and fewer missed dependencies — impact/context track code-level references; pair with grep for templates/configs/docs.
+
+milens — code intelligence engine. Indexes codebases into symbol graphs.
+
+## Tool selection
+- \`query\` — find symbol definitions (code identifiers only)
+- \`grep\` — text search ALL files. Use \`scope\` param: all (default), code (source only), imports, definitions
+- \`context\` — 360° view: incoming + outgoing for a symbol
+- \`impact\` — blast radius: what breaks if symbol changes
+- \`overview\` — combined context + impact + grep in one call (preferred for editing workflows)
+- \`guard_edit_check\` — HARD pre-edit gate: blocks if dependents > 5, tracks checks for session audit
+- \`edit_check\` — pre-edit safety: callers + export status + re-export chains + test coverage + ⚠ warnings (fastest for edits)
+- \`trace\` — execution flow: call chains from entrypoints to a symbol (or downstream from it)
+- \`routes\` — detect framework routes/endpoints (Express, FastAPI, NestJS, Flask, Go, PHP, Rails)
+- \`smart_context\` — intent-aware context: understand/edit/debug/test (returns only what matters for intent)
+- \`domains\` — show domain clusters: groups of files forming logical modules based on dependency graph
+- \`repos\` — list all indexed repositories with summary stats (multi-repo support)
+- \`detect_changes\` — git diff → affected symbols
+- \`explain_relationship\` — shortest path between two symbols
+- \`find_dead_code\` — unused exports
+- \`get_file_symbols\` — all symbols in a file
+- \`get_type_hierarchy\` — inheritance tree
+
+## Rules
+- Before editing a symbol: run \`guard_edit_check\` or \`edit_check\` or \`smart_context\` with intent=edit
+- \`guard_edit_check({name, session_id})\` — HARD gate: records check for audit, blocks if dependents > 5
+- \`impact({mode: "strict"})\` — strict mode returns BLOCKED when depth-1 deps > 5
+- For debugging: run \`smart_context\` with intent=debug or \`trace\` to=symbol
+- For writing tests: run \`smart_context\` with intent=test — shows deps to mock + callers to cover
+- \`impact\` only tracks code deps — always pair with \`grep\` for templates/configs
+- Use \`query\` for camelCase/PascalCase identifiers, \`grep\` for display text or multi-word strings
+- impact depth: 1=WILL BREAK, 2=LIKELY AFFECTED, 3=MAY NEED TESTING
+- ⚠ markers indicate unresolved INTERNAL references — external package imports/calls are tracked separately
+- ✓ test coverage shown on edit_check — symbols with no test coverage get a warning
+- ⏳ staleness: files not re-analyzed in 24h are flagged — consider re-running \`milens analyze\`
+
+## Resources (MCP Resources protocol)
+- \`milens://overview\` — index overview (stats, domains, coverage, staleness)
+- \`milens://symbol/{name}\` — symbol context by name
+- \`milens://file/{path}\` — all symbols in a file
+- \`milens://domain/{name}\` — domain cluster details
 `;
 // ── Server setup ──
 export function createMcpServer(rootPath) {
@@ -451,6 +450,19 @@ export function createMcpServer(rootPath) {
         }
         return abs;
     }
+    function isInsideDocstring(content, lineNumber) {
+        const lines = content.split('\n');
+        let inside = false;
+        for (let i = 0; i < lineNumber; i++) {
+            if (i >= lines.length)
+                break;
+            const trimmed = lines[i].trim();
+            const tripleCount = (trimmed.match(/"""|'''/g) || []).length;
+            for (let j = 0; j < tripleCount; j++)
+                inside = !inside;
+        }
+        return inside;
+    }
     function resolveRoot(repoPath) {
         if (repoPath) {
             const root = normalizePath(repoPath);
@@ -535,7 +547,7 @@ export function createMcpServer(rootPath) {
     const profile = process.env.MILENS_PROFILE || undefined;
     if (profile && profile !== 'full') {
         const minimal = new Set(['query', 'grep', 'context', 'impact', 'status', 'codebase_summary', 'edit_check', 'detect_changes', 'get_file_symbols', 'overview']);
-        const standard = new Set([...minimal, 'domains', 'repos', 'explain_relationship', 'find_dead_code', 'get_type_hierarchy', 'trace', 'routes', 'smart_context', 'review_pr', 'review_symbol', 'test_coverage_gaps', 'test_plan', 'test_impact', 'session_start', 'recall']);
+        const standard = new Set([...minimal, 'domains', 'repos', 'explain_relationship', 'find_dead_code', 'get_type_hierarchy', 'trace', 'routes', 'smart_context', 'review_pr', 'review_symbol', 'test_coverage_gaps', 'test_plan', 'test_impact', 'session_start', 'recall', 'generate_findings_report']);
         const allowed = profile === 'minimal' ? minimal : standard;
         // Wrap the tracking-wrapped server.tool again, so profile gating sits on
         // top: disabled tools still get registered (via the no-op handler below)
@@ -712,6 +724,18 @@ export function createMcpServer(rootPath) {
         const unresolved = db.getUnresolvedStats();
         const coverage = db.getTestCoverage();
         let text = `repo: ${root}\nbuild: ${BUILD_SHA} (built: ${BUILT_AT})\nversion: ${PKG_VERSION}\nsymbols: ${stats.symbols}\nlinks: ${stats.links}\nfiles: ${stats.files}`;
+        // Warn if the running server build differs from the on-disk build
+        try {
+            const distBuildPath = join(__dirname, '..', 'build-info.js');
+            if (existsSync(distBuildPath)) {
+                const diskBuild = readFileSync(distBuildPath, 'utf-8');
+                const m = diskBuild.match(/export const BUILD_SHA = '([^']+)'/);
+                if (m && m[1] !== BUILD_SHA) {
+                    text += `\n⚠ Running server build (${BUILD_SHA}) differs from on-disk build (${m[1]}) — restart the MCP server to pick up recent changes.`;
+                }
+            }
+        }
+        catch { /* best-effort */ }
         if (unresolved.imports > 0 || unresolved.calls > 0) {
             text += `\n⚠ unresolved (internal): ${unresolved.imports} imports, ${unresolved.calls} calls — callers may be incomplete`;
         }
@@ -789,8 +813,11 @@ export function createMcpServer(rootPath) {
         // Section 2: Context (incoming + outgoing) for each symbol
         if (symbols.length > 0) {
             for (const sym of symbols) {
-                const incoming = db.getIncomingLinks(sym.id).filter(l => l.type !== 'contains');
-                const outgoing = db.getOutgoingLinks(sym.id).filter(l => l.type !== 'contains');
+                const incoming = db.getIncomingLinks(sym.id);
+                const outgoing = db.getOutgoingLinks(sym.id);
+                if (symbols.length > 1) {
+                    sections.push(`─── ${fmtSymbol(sym, detail)} ---`);
+                }
                 if (incoming.length > 0) {
                     sections.push(`[incoming] ${incoming.length} refs:`);
                     const inSyms = incoming.map(l => {
@@ -979,7 +1006,7 @@ export function createMcpServer(rootPath) {
         repo: z.string().optional(),
     }, async ({ from, to, repo }) => {
         const { db } = getDb(repo);
-        const fromSyms = db.findSymbolByName(from);
+        let fromSyms = db.findSymbolByName(from);
         const toSyms = db.findSymbolByName(to);
         if (fromSyms.length === 0) {
             return { content: [{ type: 'text', text: `Symbol "${from}" not found in index. Try \`grep\`.` }] };
@@ -987,12 +1014,24 @@ export function createMcpServer(rootPath) {
         if (toSyms.length === 0) {
             return { content: [{ type: 'text', text: `Symbol "${to}" not found in index. Try \`grep\`.` }] };
         }
-        const path = db.findPath(from, to);
+        // Vue SFC: class-kind symbols have no call edges; resolve to file's _top module
+        const fromSym = fromSyms[0];
+        if (fromSym.kind === 'class' && fromSym.filePath.endsWith('.vue')) {
+            const topId = `${fromSym.filePath}#module:_top:0`;
+            const topSym = db.findSymbolById(topId);
+            if (topSym)
+                fromSyms = [topSym];
+        }
+        // Use the id-based lookup once a symbol has been disambiguated above —
+        // findPath(name, ...) would re-resolve by name and could pick a
+        // different same-named symbol (e.g. some other file's "_top"),
+        // silently undoing the disambiguation.
+        const path = db.findPathFromId(fromSyms[0].id, to);
         if (!path) {
             return { content: [{ type: 'text', text: `No path between "${from}" and "${to}".` }] };
         }
-        const fromSym = fromSyms[0];
-        const lines = [`FROM: ${fmtSymbol(fromSym)}`, ''];
+        const displaySym = fromSyms[0];
+        const lines = [`FROM: ${fmtSymbol(displaySym)}`, ''];
         for (const { symbol, depth, via } of path) {
             lines.push(`  ${'→'.repeat(depth)} [${via}] ${fmtSymbol(symbol)}`);
         }
@@ -1012,7 +1051,8 @@ export function createMcpServer(rootPath) {
             return { content: [{ type: 'text', text: 'No unreferenced exported symbols found.' }] };
         }
         if (dead.length > 0) {
-            lines.push(`${dead.length} unreferenced exported symbols (code-level only — verify with grep before removing):\n`);
+            const cappedNote = dead.length >= limit ? ` (showing ${dead.length}, may be more — increase limit to see all)` : '';
+            lines.push(`${dead.length} unreferenced exported symbols (code-level only — verify with grep before removing)${cappedNote}:\n`);
             for (const sym of dead) {
                 lines.push(fmtSymbol(sym));
             }
@@ -1032,7 +1072,11 @@ export function createMcpServer(rootPath) {
         file: z.string().describe('File path (relative to repo root)'),
         repo: z.string().optional(),
         detail: z.enum(['L0', 'L1', 'L2']).optional().default('L1').describe('Output detail: L0=names only, L1=default, L2=full metadata'),
-    }, async ({ file, repo, detail }) => {
+        limit: z.number().optional().default(100).describe('Max symbols to return'),
+        offset: z.number().optional().default(0).describe('Offset for pagination'),
+    }, async ({ file, repo, detail, limit, offset }) => {
+        limit = limit ?? 100;
+        offset = offset ?? 0;
         const { db } = getDb(repo);
         const symbols = db.getSymbolsByFile(file);
         if (symbols.length === 0) {
@@ -1042,8 +1086,13 @@ export function createMcpServer(rootPath) {
         const sorted = detail === 'L2'
             ? [...symbols].sort((a, b) => (b.heat ?? 0) - (a.heat ?? 0))
             : symbols;
-        const lines = [`${file}: ${symbols.length} symbols\n`];
-        for (const sym of sorted) {
+        const paginated = sorted.slice(offset, offset + limit);
+        const total = sorted.length;
+        const pageInfo = total > limit || offset > 0
+            ? ` (showing ${offset + 1}-${Math.min(offset + limit, total)} of ${total}; use offset/limit to paginate)`
+            : '';
+        const lines = [`${file}: ${total} symbols${pageInfo}\n`];
+        for (const sym of paginated) {
             const incoming = db.getIncomingLinks(sym.id).filter(l => l.type !== 'contains');
             const outgoing = db.getOutgoingLinks(sym.id).filter(l => l.type !== 'contains');
             const exp = sym.exported ? ' (exported)' : '';
@@ -1096,13 +1145,17 @@ export function createMcpServer(rootPath) {
             if (ancestors.length > 0) {
                 lines.push('extends/implements:');
                 for (const { symbol: a, depth } of ancestors) {
-                    lines.push(`  ${'↑'.repeat(depth)} ${fmtSymbol(a)}`);
+                    const isExternal = a.filePath === '(external)';
+                    const label = isExternal ? ` ${fmtSymbol(a)} (external)` : ` ${fmtSymbol(a)}`;
+                    lines.push(`  ${'↑'.repeat(depth)}${label}`);
                 }
             }
             if (descendants.length > 0) {
                 lines.push('extended/implemented by:');
                 for (const { symbol: d, depth } of descendants) {
-                    lines.push(`  ${'↓'.repeat(depth)} ${fmtSymbol(d)}`);
+                    const isExternal = d.filePath === '(external)';
+                    const label = isExternal ? ` ${fmtSymbol(d)} (external)` : ` ${fmtSymbol(d)}`;
+                    lines.push(`  ${'↓'.repeat(depth)}${label}`);
                 }
             }
             if (ancestors.length === 0 && descendants.length === 0) {
@@ -1160,7 +1213,7 @@ export function createMcpServer(rootPath) {
         // 5. Unresolved warning (only for internal)
         const unresolved = db.getUnresolvedStats();
         if (unresolved.imports > 0 || unresolved.calls > 0) {
-            sections.push(`⚠ index has ${unresolved.imports} unresolved internal imports, ${unresolved.calls} unresolved internal calls — callers list may be incomplete`);
+            sections.push(`⚠ this repo's index has ${unresolved.imports} unresolved internal imports, ${unresolved.calls} unresolved internal calls repo-wide — this symbol's callers list may be incomplete`);
         }
         // 6. Test coverage for this symbol
         for (const sym of symbols) {
@@ -1264,7 +1317,7 @@ export function createMcpServer(rootPath) {
         // Unresolved warning
         const unresolved = db.getUnresolvedStats();
         if (unresolved.imports > 0 || unresolved.calls > 0) {
-            sections.push(`⚠ index has ${unresolved.imports} unresolved internal imports, ${unresolved.calls} unresolved internal calls — callers list may be incomplete`);
+            sections.push(`⚠ this repo's index has ${unresolved.imports} unresolved internal imports, ${unresolved.calls} unresolved internal calls repo-wide — this symbol's callers list may be incomplete`);
         }
         return { content: [{ type: 'text', text: sections.join('\n') }] };
     });
@@ -1329,8 +1382,8 @@ export function createMcpServer(rootPath) {
     // ── Tool: routes ──
     server.tool('routes', 'Detect framework routes/endpoints and map them to handler symbols. Scans for Express, FastAPI, NestJS, Flask, Go HTTP, PHP, Rails patterns.', {
         repo: z.string().optional(),
-        framework: z.string().optional().describe('Filter by framework (express, fastapi, nestjs, flask, go, php, rails). Default: auto-detect all.'),
-        limit: z.number().optional().default(50),
+        framework: z.string().optional().describe('Filter by framework (express, fastapi, nestjs, nestjs-gateway, flask, go, php, rails). Default: auto-detect all.'),
+        limit: z.number().optional().default(200).describe('Max routes to display. Internal search always scans up to 500 matches per framework, so a low limit only affects display truncation, not detection accuracy.'),
     }, async ({ repo, framework, limit }) => {
         const root = resolveRoot(repo);
         const { db } = getDb(repo);
@@ -1340,8 +1393,9 @@ export function createMcpServer(rootPath) {
         const routePatterns = [
             { name: 'express', pattern: /\b(?:app|router)\.(get|post|put|patch|delete|use|all)\s*\(\s*['"`]([^'"`]+)['"`]/, fileGlob: '**/*.{ts,js,mjs,cjs}' },
             { name: 'fastapi', pattern: /@(?:app|router)\.(get|post|put|patch|delete)\s*\(\s*['"]([^'"]+)['"]/, fileGlob: '**/*.py' },
-            { name: 'flask', pattern: /@(?:app|bp|blueprint)\.(route|get|post|put|delete)\s*\(\s*['"]([^'"]+)['"]/, fileGlob: '**/*.py' },
+            { name: 'flask', pattern: /@(?:app|bp|blueprint)\.route\s*\(\s*['"]([^'"]+)['"]/, fileGlob: '**/*.py' },
             { name: 'nestjs', pattern: /@(Get|Post|Put|Patch|Delete)\s*\(\s*['"]?([^'")]*?)['"]?\s*\)/, fileGlob: '**/*.ts' },
+            { name: 'nestjs-gateway', pattern: /@SubscribeMessage\s*\(\s*['"]([^'"]+)['"]\s*\)/, fileGlob: '**/*.ts' },
             { name: 'go', pattern: /\b(?:mux|router|http)\.(HandleFunc|Handle|Get|Post|Put|Delete)\s*\(\s*['"]([^'"]+)['"]/, fileGlob: '**/*.go' },
             { name: 'php', pattern: /Route::(get|post|put|patch|delete|any)\s*\(\s*['"]([^'"]+)['"]/, fileGlob: '**/*.php' },
             { name: 'rails', pattern: /\b(get|post|put|patch|delete|resources?|root)\s+['"]([^'"]+)['"]/, fileGlob: '**/*.rb' },
@@ -1350,19 +1404,29 @@ export function createMcpServer(rootPath) {
             ? routePatterns.filter(p => p.name === framework.toLowerCase())
             : routePatterns;
         if (activePatterns.length === 0) {
-            return { content: [{ type: 'text', text: `Unknown framework "${framework}". Available: express, fastapi, nestjs, flask, go, php, rails` }] };
+            return { content: [{ type: 'text', text: `Unknown framework "${framework}". Available: express, fastapi, nestjs, nestjs-gateway, flask, go, php, rails` }] };
         }
         const routes = [];
         for (const rp of activePatterns) {
             const matches = grepFiles(root, rp.pattern.source, {
-                isRegex: true, maxResults: limit, includePattern: rp.fileGlob,
+                isRegex: true, maxResults: 500, includePattern: rp.fileGlob,
             });
             for (const m of matches) {
                 const match = rp.pattern.exec(m.text);
                 if (!match)
                     continue;
-                const method = match[1].toUpperCase();
-                const path = match[2] || '/';
+                // Skip matches inside Python docstrings (triple-quoted strings)
+                if (rp.fileGlob === '**/*.py') {
+                    try {
+                        const filePath = resolve(root, m.file);
+                        const content = readFileSync(filePath, 'utf-8');
+                        if (isInsideDocstring(content, m.line))
+                            continue;
+                    }
+                    catch { /* can't read file — skip filtering */ }
+                }
+                const method = rp.name === 'nestjs-gateway' ? 'WS' : match[1].toUpperCase();
+                const path = rp.name === 'nestjs-gateway' ? match[1] : (match[2] || '/');
                 // Try to find the handler symbol on this line or nearby
                 const fileSymbols = db.getSymbolsByFile(m.file);
                 const handler = fileSymbols.find(s => s.startLine <= m.line && s.endLine >= m.line && s.kind === 'method') ?? fileSymbols.find(s => s.startLine <= m.line && s.endLine >= m.line) ?? fileSymbols.find(s => Math.abs(s.startLine - m.line) <= 3 && (s.kind === 'function' || s.kind === 'method'));
@@ -1379,6 +1443,71 @@ export function createMcpServer(rootPath) {
         if (routes.length === 0) {
             return { content: [{ type: 'text', text: 'No framework routes detected.' }] };
         }
+        // NestJS: join controller prefix with method path
+        const nestjsRoutes = routes.filter(r => r.framework === 'nestjs');
+        if (nestjsRoutes.length > 0) {
+            const nestjsByFile = new Map();
+            for (const r of nestjsRoutes) {
+                const arr = nestjsByFile.get(r.file) ?? [];
+                arr.push(r);
+                nestjsByFile.set(r.file, arr);
+            }
+            for (const [file, fileRoutes] of nestjsByFile) {
+                try {
+                    const content = readFileSync(resolve(root, file), 'utf-8');
+                    const lines = content.split('\n');
+                    // Find @Controller decorators with their class body line ranges
+                    const controllers = [];
+                    const ctrlRe = /@Controller\s*\(\s*['"]?([^'")]*?)['"]?\s*\)/;
+                    const classRe = /export\s+(?:abstract\s+)?class\s+\w+/;
+                    for (let i = 0; i < lines.length; i++) {
+                        const cm = ctrlRe.exec(lines[i]);
+                        if (!cm)
+                            continue;
+                        // Find the class declaration within next 5 lines
+                        let classLine = -1;
+                        for (let j = i; j < Math.min(i + 5, lines.length); j++) {
+                            if (classRe.test(lines[j])) {
+                                classLine = j;
+                                break;
+                            }
+                        }
+                        if (classLine === -1)
+                            continue;
+                        // Track brace depth to find end of class body
+                        let depth = 0;
+                        let started = false;
+                        let endLine = classLine;
+                        for (let k = classLine; k < lines.length; k++) {
+                            for (const ch of lines[k]) {
+                                if (ch === '{') {
+                                    depth++;
+                                    started = true;
+                                }
+                                else if (ch === '}') {
+                                    depth--;
+                                }
+                            }
+                            if (started && depth === 0) {
+                                endLine = k;
+                                break;
+                            }
+                        }
+                        controllers.push({ prefix: cm[1] || '', startLine: classLine + 1, endLine: endLine + 1 });
+                    }
+                    // Map each route to its controller prefix
+                    for (const r of fileRoutes) {
+                        const ctrl = controllers.find(c => r.line >= c.startLine && r.line <= c.endLine);
+                        if (ctrl && ctrl.prefix) {
+                            const methodPath = r.path === '/' ? '' : r.path;
+                            const joinPath = ctrl.prefix + (methodPath.startsWith('/') || methodPath === '' ? methodPath : '/' + methodPath);
+                            r.path = joinPath || '/';
+                        }
+                    }
+                }
+                catch { /* can't read file */ }
+            }
+        }
         // Group by framework
         const grouped = new Map();
         for (const r of routes) {
@@ -1386,10 +1515,13 @@ export function createMcpServer(rootPath) {
             arr.push(r);
             grouped.set(r.framework, arr);
         }
-        const lines = [`${routes.length} routes detected:\n`];
+        const displayRoutes = routes.slice(0, limit);
+        const lines = [`${routes.length} routes detected${routes.length > limit ? ` (showing first ${limit})` : ''}:\n`];
         for (const [fw, fwRoutes] of grouped) {
             lines.push(`[${fw}]`);
             for (const r of fwRoutes) {
+                if (!displayRoutes.includes(r))
+                    break;
                 const handlerInfo = r.handler ? ` → ${r.handler}` : '';
                 lines.push(`  ${r.method.padEnd(7)} ${r.path}  (${r.file}:${r.line})${handlerInfo}`);
             }
@@ -1488,10 +1620,19 @@ export function createMcpServer(rootPath) {
                 // Execution paths + data flow
                 const traces = db.traceToEntrypoints(sym.id, 6);
                 if (traces.length > 0) {
+                    const seenChains = new Set();
                     sections.push(`execution paths (${traces.length}):`);
-                    for (let i = 0; i < Math.min(traces.length, 3); i++) {
+                    let shown = 0;
+                    for (let i = 0; i < traces.length && shown < 3; i++) {
                         const chain = traces[i].path;
-                        sections.push(`  ${chain.map(s => s.symbol.name).join(' → ')}`);
+                        const firstFile = chain[0]?.symbol?.filePath?.split('/').pop() ?? '';
+                        const rendered = chain.map(s => s.symbol.name).join(' → ');
+                        const key = `${firstFile}: ${rendered}`;
+                        if (seenChains.has(key))
+                            continue;
+                        seenChains.add(key);
+                        sections.push(`  ${key}`);
+                        shown++;
                     }
                 }
                 else {
@@ -1913,6 +2054,7 @@ export function createMcpServer(rootPath) {
     // ── Register MCP Prompts ──
     registerAllPrompts(server);
     registerSecurityTools(server, { getDb, fmtSymbol, fmtImpact, rootPath, toolCallCounts, resolveRoot, guard, getToolCallCount });
+    registerFindingsReportTools(server, { getDb, fmtSymbol, fmtImpact, rootPath, toolCallCounts, resolveRoot, guard, getToolCallCount });
     // ── Tool: compare_impact ──
     server.tool('compare_impact', 'Compare impact graph before/after an edit. Takes a snapshot first, then call again to see the diff. Returns new/removed dependents and heat changes.', {
         name: z.string().describe('Symbol name to compare'),