@optave/codegraph 2.1.1-dev.00f091c → 2.1.1-dev.0e15f12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optave/codegraph",
-  "version": "2.1.1-dev.00f091c",
+  "version": "2.1.1-dev.0e15f12",
   "description": "Local code graph CLI — parse codebases with tree-sitter, build dependency graphs, query them",
   "type": "module",
   "main": "src/index.js",
@@ -61,10 +61,10 @@
   "optionalDependencies": {
     "@huggingface/transformers": "^3.8.1",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@optave/codegraph-darwin-arm64": "2.1.1-dev.00f091c",
-    "@optave/codegraph-darwin-x64": "2.1.1-dev.00f091c",
-    "@optave/codegraph-linux-x64-gnu": "2.1.1-dev.00f091c",
-    "@optave/codegraph-win32-x64-msvc": "2.1.1-dev.00f091c"
+    "@optave/codegraph-darwin-arm64": "2.1.1-dev.0e15f12",
+    "@optave/codegraph-darwin-x64": "2.1.1-dev.0e15f12",
+    "@optave/codegraph-linux-x64-gnu": "2.1.1-dev.0e15f12",
+    "@optave/codegraph-win32-x64-msvc": "2.1.1-dev.0e15f12"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.4",

package/src/cli.js

@@ -11,8 +11,10 @@ import { buildEmbeddings, MODELS, search } from './embedder.js';
 import { exportDOT, exportJSON, exportMermaid } from './export.js';
 import { setVerbose } from './logger.js';
 import {
+  ALL_SYMBOL_KINDS,
   context,
   diffImpact,
+  explain,
   fileDeps,
   fnDeps,
   fnImpact,
@@ -20,6 +22,7 @@ import {
   moduleMap,
   queryName,
   stats,
+  where,
 } from './queries.js';
 import {
   listRepos,
@@ -106,11 +109,19 @@ program
   .description('Function-level dependencies: callers, callees, and transitive call chain')
   .option('-d, --db <path>', 'Path to graph.db')
   .option('--depth <n>', 'Transitive caller depth', '3')
+  .option('-f, --file <path>', 'Scope search to functions in this file (partial match)')
+  .option('-k, --kind <kind>', 'Filter to a specific symbol kind')
   .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('-j, --json', 'Output as JSON')
   .action((name, opts) => {
+    if (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
+      console.error(`Invalid kind "${opts.kind}". Valid: ${ALL_SYMBOL_KINDS.join(', ')}`);
+      process.exit(1);
+    }
     fnDeps(name, opts.db, {
       depth: parseInt(opts.depth, 10),
+      file: opts.file,
+      kind: opts.kind,
       noTests: !opts.tests,
       json: opts.json,
     });
@@ -121,11 +132,19 @@ program
   .description('Function-level impact: what functions break if this one changes')
   .option('-d, --db <path>', 'Path to graph.db')
   .option('--depth <n>', 'Max transitive depth', '5')
+  .option('-f, --file <path>', 'Scope search to functions in this file (partial match)')
+  .option('-k, --kind <kind>', 'Filter to a specific symbol kind')
   .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('-j, --json', 'Output as JSON')
   .action((name, opts) => {
+    if (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
+      console.error(`Invalid kind "${opts.kind}". Valid: ${ALL_SYMBOL_KINDS.join(', ')}`);
+      process.exit(1);
+    }
     fnImpact(name, opts.db, {
       depth: parseInt(opts.depth, 10),
+      file: opts.file,
+      kind: opts.kind,
       noTests: !opts.tests,
       json: opts.json,
     });
@@ -136,13 +155,21 @@ program
   .description('Full context for a function: source, deps, callers, tests, signature')
   .option('-d, --db <path>', 'Path to graph.db')
   .option('--depth <n>', 'Include callee source up to N levels deep', '0')
+  .option('-f, --file <path>', 'Scope search to functions in this file (partial match)')
+  .option('-k, --kind <kind>', 'Filter to a specific symbol kind')
   .option('--no-source', 'Metadata only (skip source extraction)')
   .option('--include-tests', 'Include test source code')
   .option('-T, --no-tests', 'Exclude test files from callers')
   .option('-j, --json', 'Output as JSON')
   .action((name, opts) => {
+    if (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
+      console.error(`Invalid kind "${opts.kind}". Valid: ${ALL_SYMBOL_KINDS.join(', ')}`);
+      process.exit(1);
+    }
     context(name, opts.db, {
       depth: parseInt(opts.depth, 10),
+      file: opts.file,
+      kind: opts.kind,
       noSource: !opts.source,
       noTests: !opts.tests,
       includeTests: opts.includeTests,
@@ -150,6 +177,32 @@ program
     });
   });
 
+program
+  .command('explain <target>')
+  .description('Structural summary of a file or function (no LLM needed)')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('-T, --no-tests', 'Exclude test/spec files')
+  .option('-j, --json', 'Output as JSON')
+  .action((target, opts) => {
+    explain(target, opts.db, { noTests: !opts.tests, json: opts.json });
+  });
+
+program
+  .command('where [name]')
+  .description('Find where a symbol is defined and used (minimal, fast lookup)')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('-f, --file <path>', 'File overview: list symbols, imports, exports')
+  .option('-T, --no-tests', 'Exclude test/spec files')
+  .option('-j, --json', 'Output as JSON')
+  .action((name, opts) => {
+    if (!name && !opts.file) {
+      console.error('Provide a symbol name or use --file <path>');
+      process.exit(1);
+    }
+    const target = opts.file || name;
+    where(target, opts.db, { file: !!opts.file, noTests: !opts.tests, json: opts.json });
+  });
+
 program
   .command('diff-impact [ref]')
   .description('Show impact of git changes (unstaged, staged, or vs a ref)')

package/src/extractors/javascript.js

@@ -140,6 +140,8 @@ export function extractSymbols(tree, _filePath) {
             calls.push(callInfo);
           }
         }
+        const cbDef = extractCallbackDefinition(node);
+        if (cbDef) definitions.push(cbDef);
         break;
       }
 
@@ -372,6 +374,126 @@ function extractCallInfo(fn, callNode) {
   return null;
 }
 
+function findAnonymousCallback(argsNode) {
+  for (let i = 0; i < argsNode.childCount; i++) {
+    const child = argsNode.child(i);
+    if (child && (child.type === 'arrow_function' || child.type === 'function_expression')) {
+      return child;
+    }
+  }
+  return null;
+}
+
+function findFirstStringArg(argsNode) {
+  for (let i = 0; i < argsNode.childCount; i++) {
+    const child = argsNode.child(i);
+    if (child && child.type === 'string') {
+      return child.text.replace(/['"]/g, '');
+    }
+  }
+  return null;
+}
+
+function walkCallChain(startNode, methodName) {
+  let current = startNode;
+  while (current) {
+    if (current.type === 'call_expression') {
+      const fn = current.childForFieldName('function');
+      if (fn && fn.type === 'member_expression') {
+        const prop = fn.childForFieldName('property');
+        if (prop && prop.text === methodName) {
+          return current;
+        }
+      }
+    }
+    if (current.type === 'member_expression') {
+      const obj = current.childForFieldName('object');
+      current = obj;
+    } else if (current.type === 'call_expression') {
+      const fn = current.childForFieldName('function');
+      current = fn;
+    } else {
+      break;
+    }
+  }
+  return null;
+}
+
+const EXPRESS_METHODS = new Set([
+  'get',
+  'post',
+  'put',
+  'delete',
+  'patch',
+  'options',
+  'head',
+  'all',
+  'use',
+]);
+const EVENT_METHODS = new Set(['on', 'once', 'addEventListener', 'addListener']);
+
+function extractCallbackDefinition(callNode) {
+  const fn = callNode.childForFieldName('function');
+  if (!fn || fn.type !== 'member_expression') return null;
+
+  const prop = fn.childForFieldName('property');
+  if (!prop) return null;
+  const method = prop.text;
+
+  const args = callNode.childForFieldName('arguments') || findChild(callNode, 'arguments');
+  if (!args) return null;
+
+  // Commander: .action(callback) with .command('name') in chain
+  if (method === 'action') {
+    const cb = findAnonymousCallback(args);
+    if (!cb) return null;
+    const commandCall = walkCallChain(fn.childForFieldName('object'), 'command');
+    if (!commandCall) return null;
+    const cmdArgs =
+      commandCall.childForFieldName('arguments') || findChild(commandCall, 'arguments');
+    if (!cmdArgs) return null;
+    const cmdName = findFirstStringArg(cmdArgs);
+    if (!cmdName) return null;
+    const firstWord = cmdName.split(/\s/)[0];
+    return {
+      name: `command:${firstWord}`,
+      kind: 'function',
+      line: cb.startPosition.row + 1,
+      endLine: nodeEndLine(cb),
+    };
+  }
+
+  // Express: app.get('/path', callback)
+  if (EXPRESS_METHODS.has(method)) {
+    const strArg = findFirstStringArg(args);
+    if (!strArg || !strArg.startsWith('/')) return null;
+    const cb = findAnonymousCallback(args);
+    if (!cb) return null;
+    return {
+      name: `route:${method.toUpperCase()} ${strArg}`,
+      kind: 'function',
+      line: cb.startPosition.row + 1,
+      endLine: nodeEndLine(cb),
+    };
+  }
+
+  // Events: emitter.on('event', callback)
+  if (EVENT_METHODS.has(method)) {
+    const eventName = findFirstStringArg(args);
+    if (!eventName) return null;
+    const cb = findAnonymousCallback(args);
+    if (!cb) return null;
+    return {
+      name: `event:${eventName}`,
+      kind: 'function',
+      line: cb.startPosition.row + 1,
+      endLine: nodeEndLine(cb),
+    };
+  }
+
+  return null;
+}
+
 function extractSuperclass(heritage) {
   for (let i = 0; i < heritage.childCount; i++) {
     const child = heritage.child(i);

package/src/index.js

@@ -38,8 +38,12 @@ export { isNativeAvailable } from './native.js';
 export { getActiveEngine, parseFileAuto, parseFilesAuto } from './parser.js';
 // Query functions (data-returning)
 export {
+  ALL_SYMBOL_KINDS,
   contextData,
   diffImpactData,
+  explainData,
+  FALSE_POSITIVE_CALLER_THRESHOLD,
+  FALSE_POSITIVE_NAMES,
   fileDepsData,
   fnDepsData,
   fnImpactData,
@@ -47,6 +51,7 @@ export {
   moduleMapData,
   queryNameData,
   statsData,
+  whereData,
 } from './queries.js';
 // Registry (multi-repo)
 export {

package/src/mcp.js

@@ -8,6 +8,7 @@
 import { createRequire } from 'node:module';
 import { findCycles } from './cycles.js';
 import { findDbPath } from './db.js';
+import { ALL_SYMBOL_KINDS } from './queries.js';
 
 const REPO_PROP = {
   repo: {
@@ -81,6 +82,15 @@ const BASE_TOOLS = [
       properties: {
         name: { type: 'string', description: 'Function/method/class name (partial match)' },
         depth: { type: 'number', description: 'Transitive caller depth', default: 3 },
+        file: {
+          type: 'string',
+          description: 'Scope search to functions in this file (partial match)',
+        },
+        kind: {
+          type: 'string',
+          enum: ALL_SYMBOL_KINDS,
+          description: 'Filter to a specific symbol kind',
+        },
         no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
       },
       required: ['name'],
@@ -95,6 +105,15 @@ const BASE_TOOLS = [
       properties: {
         name: { type: 'string', description: 'Function/method/class name (partial match)' },
         depth: { type: 'number', description: 'Max traversal depth', default: 5 },
+        file: {
+          type: 'string',
+          description: 'Scope search to functions in this file (partial match)',
+        },
+        kind: {
+          type: 'string',
+          enum: ALL_SYMBOL_KINDS,
+          description: 'Filter to a specific symbol kind',
+        },
         no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
       },
       required: ['name'],
@@ -113,6 +132,15 @@ const BASE_TOOLS = [
           description: 'Include callee source up to N levels deep (0=no source, 1=direct)',
           default: 0,
         },
+        file: {
+          type: 'string',
+          description: 'Scope search to functions in this file (partial match)',
+        },
+        kind: {
+          type: 'string',
+          enum: ALL_SYMBOL_KINDS,
+          description: 'Filter to a specific symbol kind',
+        },
         no_source: {
           type: 'boolean',
           description: 'Skip source extraction (metadata only)',
@@ -128,6 +156,37 @@ const BASE_TOOLS = [
       required: ['name'],
     },
   },
+  {
+    name: 'explain',
+    description:
+      'Structural summary of a file or function: public/internal API, data flow, dependencies. No LLM needed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target: { type: 'string', description: 'File path or function name' },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+      },
+      required: ['target'],
+    },
+  },
+  {
+    name: 'where',
+    description:
+      'Find where a symbol is defined and used, or list symbols/imports/exports for a file. Minimal, fast lookup.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target: { type: 'string', description: 'Symbol name or file path' },
+        file_mode: {
+          type: 'boolean',
+          description: 'Treat target as file path (list symbols/imports/exports)',
+          default: false,
+        },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
+      },
+      required: ['target'],
+    },
+  },
   {
     name: 'diff_impact',
     description: 'Analyze git diff to find which functions changed and their transitive callers',
@@ -299,6 +358,8 @@ export async function startMCPServer(customDbPath, options = {}) {
     fnDepsData,
     fnImpactData,
     contextData,
+    explainData,
+    whereData,
     diffImpactData,
     listFunctionsData,
   } = await import('./queries.js');
@@ -368,23 +429,38 @@ export async function startMCPServer(customDbPath, options = {}) {
         case 'fn_deps':
           result = fnDepsData(args.name, dbPath, {
             depth: args.depth,
+            file: args.file,
+            kind: args.kind,
             noTests: args.no_tests,
           });
           break;
         case 'fn_impact':
           result = fnImpactData(args.name, dbPath, {
             depth: args.depth,
+            file: args.file,
+            kind: args.kind,
             noTests: args.no_tests,
           });
           break;
         case 'context':
           result = contextData(args.name, dbPath, {
             depth: args.depth,
+            file: args.file,
+            kind: args.kind,
             noSource: args.no_source,
             noTests: args.no_tests,
             includeTests: args.include_tests,
           });
           break;
+        case 'explain':
+          result = explainData(args.target, dbPath, { noTests: args.no_tests });
+          break;
+        case 'where':
+          result = whereData(args.target, dbPath, {
+            file: args.file_mode,
+            noTests: args.no_tests,
+          });
+          break;
         case 'diff_impact':
           result = diffImpactData(dbPath, {
             staged: args.staged,

package/src/queries.js

@@ -3,13 +3,70 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { findCycles } from './cycles.js';
 import { findDbPath, openReadonlyOrFail } from './db.js';
+import { debug } from './logger.js';
 import { LANGUAGE_REGISTRY } from './parser.js';
 
+/**
+ * Resolve a file path relative to repoRoot, rejecting traversal outside the repo.
+ * Returns null if the resolved path escapes repoRoot.
+ */
+function safePath(repoRoot, file) {
+  const resolved = path.resolve(repoRoot, file);
+  if (!resolved.startsWith(repoRoot + path.sep) && resolved !== repoRoot) return null;
+  return resolved;
+}
+
 const TEST_PATTERN = /\.(test|spec)\.|__test__|__tests__|\.stories\./;
 function isTestFile(filePath) {
   return TEST_PATTERN.test(filePath);
 }
 
+export const FALSE_POSITIVE_NAMES = new Set([
+  'run',
+  'get',
+  'set',
+  'init',
+  'start',
+  'handle',
+  'main',
+  'new',
+  'create',
+  'update',
+  'delete',
+  'process',
+  'execute',
+  'call',
+  'apply',
+  'setup',
+  'render',
+  'build',
+  'load',
+  'save',
+  'find',
+  'make',
+  'open',
+  'close',
+  'reset',
+  'send',
+  'read',
+  'write',
+]);
+export const FALSE_POSITIVE_CALLER_THRESHOLD = 20;
+
+const FUNCTION_KINDS = ['function', 'method', 'class'];
+export const ALL_SYMBOL_KINDS = [
+  'function',
+  'method',
+  'class',
+  'interface',
+  'type',
+  'struct',
+  'enum',
+  'trait',
+  'record',
+  'module',
+];
+
 /**
  * Get all ancestor class names for a given class using extends edges.
  */
@@ -60,6 +117,58 @@ function resolveMethodViaHierarchy(db, methodName) {
   return results;
 }
 
+/**
+ * Find nodes matching a name query, ranked by relevance.
+ * Scoring: exact=100, prefix=60, word-boundary=40, substring=10, plus fan-in tiebreaker.
+ */
+function findMatchingNodes(db, name, opts = {}) {
+  const kinds = opts.kind ? [opts.kind] : FUNCTION_KINDS;
+  const placeholders = kinds.map(() => '?').join(', ');
+  const params = [`%${name}%`, ...kinds];
+
+  let fileCondition = '';
+  if (opts.file) {
+    fileCondition = ' AND n.file LIKE ?';
+    params.push(`%${opts.file}%`);
+  }
+
+  const rows = db
+    .prepare(`
+      SELECT n.*, COALESCE(fi.cnt, 0) AS fan_in
+      FROM nodes n
+      LEFT JOIN (
+        SELECT target_id, COUNT(*) AS cnt FROM edges WHERE kind = 'calls' GROUP BY target_id
+      ) fi ON fi.target_id = n.id
+      WHERE n.name LIKE ? AND n.kind IN (${placeholders})${fileCondition}
+    `)
+    .all(...params);
+
+  const nodes = opts.noTests ? rows.filter((n) => !isTestFile(n.file)) : rows;
+
+  const lowerQuery = name.toLowerCase();
+  for (const node of nodes) {
+    const lowerName = node.name.toLowerCase();
+    const bareName = lowerName.includes('.') ? lowerName.split('.').pop() : lowerName;
+
+    let matchScore;
+    if (lowerName === lowerQuery || bareName === lowerQuery) {
+      matchScore = 100;
+    } else if (lowerName.startsWith(lowerQuery) || bareName.startsWith(lowerQuery)) {
+      matchScore = 60;
+    } else if (lowerName.includes(`.${lowerQuery}`) || lowerName.includes(`${lowerQuery}.`)) {
+      matchScore = 40;
+    } else {
+      matchScore = 10;
+    }
+
+    const fanInBonus = Math.min(Math.log2(node.fan_in + 1) * 5, 25);
+    node._relevance = matchScore + fanInBonus;
+  }
+
+  nodes.sort((a, b) => b._relevance - a._relevance);
+  return nodes;
+}
+
 function kindIcon(kind) {
   switch (kind) {
     case 'function':
@@ -132,8 +241,9 @@ export function queryNameData(name, customDbPath) {
   return { query: name, results };
 }
 
-export function impactAnalysisData(file, customDbPath) {
+export function impactAnalysisData(file, customDbPath, opts = {}) {
   const db = openReadonlyOrFail(customDbPath);
+  const noTests = opts.noTests || false;
   const fileNodes = db
     .prepare(`SELECT * FROM nodes WHERE file LIKE ? AND kind = 'file'`)
     .all(`%${file}%`);
@@ -162,7 +272,7 @@ export function impactAnalysisData(file, customDbPath) {
     `)
       .all(current);
     for (const dep of dependents) {
-      if (!visited.has(dep.id)) {
+      if (!visited.has(dep.id) && (!noTests || !isTestFile(dep.file))) {
         visited.add(dep.id);
         queue.push(dep.id);
         levels.set(dep.id, level + 1);
@@ -187,8 +297,17 @@ export function impactAnalysisData(file, customDbPath) {
   };
 }
 
-export function moduleMapData(customDbPath, limit = 20) {
+export function moduleMapData(customDbPath, limit = 20, opts = {}) {
   const db = openReadonlyOrFail(customDbPath);
+  const noTests = opts.noTests || false;
+
+  const testFilter = noTests
+    ? `AND n.file NOT LIKE '%.test.%'
+      AND n.file NOT LIKE '%.spec.%'
+      AND n.file NOT LIKE '%__test__%'
+      AND n.file NOT LIKE '%__tests__%'
+      AND n.file NOT LIKE '%.stories.%'`
+    : '';
 
   const nodes = db
     .prepare(`
@@ -197,9 +316,7 @@ export function moduleMapData(customDbPath, limit = 20) {
       (SELECT COUNT(*) FROM edges WHERE target_id = n.id AND kind != 'contains') as in_edges
     FROM nodes n
     WHERE n.kind = 'file'
-      AND n.file NOT LIKE '%.test.%'
-      AND n.file NOT LIKE '%.spec.%'
-      AND n.file NOT LIKE '%__test__%'
+      ${testFilter}
     ORDER BY (SELECT COUNT(*) FROM edges WHERE target_id = n.id AND kind != 'contains') DESC
     LIMIT ?
   `)
@@ -220,8 +337,9 @@ export function moduleMapData(customDbPath, limit = 20) {
   return { limit, topNodes, stats: { totalFiles, totalNodes, totalEdges } };
 }
 
-export function fileDepsData(file, customDbPath) {
+export function fileDepsData(file, customDbPath, opts = {}) {
   const db = openReadonlyOrFail(customDbPath);
+  const noTests = opts.noTests || false;
   const fileNodes = db
     .prepare(`SELECT * FROM nodes WHERE file LIKE ? AND kind = 'file'`)
     .all(`%${file}%`);
@@ -231,19 +349,21 @@ export function fileDepsData(file, customDbPath) {
   }
 
   const results = fileNodes.map((fn) => {
-    const importsTo = db
+    let importsTo = db
       .prepare(`
       SELECT n.file, e.kind as edge_kind FROM edges e JOIN nodes n ON e.target_id = n.id
       WHERE e.source_id = ? AND e.kind IN ('imports', 'imports-type')
     `)
       .all(fn.id);
+    if (noTests) importsTo = importsTo.filter((i) => !isTestFile(i.file));
 
-    const importedBy = db
+    let importedBy = db
       .prepare(`
       SELECT n.file, e.kind as edge_kind FROM edges e JOIN nodes n ON e.source_id = n.id
       WHERE e.target_id = ? AND e.kind IN ('imports', 'imports-type')
     `)
       .all(fn.id);
+    if (noTests) importedBy = importedBy.filter((i) => !isTestFile(i.file));
 
     const defs = db
       .prepare(`SELECT * FROM nodes WHERE file = ? AND kind != 'file' ORDER BY line`)
@@ -266,12 +386,7 @@ export function fnDepsData(name, customDbPath, opts = {}) {
   const depth = opts.depth || 3;
   const noTests = opts.noTests || false;
 
-  let nodes = db
-    .prepare(
-      `SELECT * FROM nodes WHERE name LIKE ? AND kind IN ('function', 'method', 'class') ORDER BY file, line`,
-    )
-    .all(`%${name}%`);
-  if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
+  const nodes = findMatchingNodes(db, name, { noTests, file: opts.file, kind: opts.kind });
   if (nodes.length === 0) {
     db.close();
     return { name, results: [] };
@@ -391,10 +506,7 @@ export function fnImpactData(name, customDbPath, opts = {}) {
   const maxDepth = opts.depth || 5;
   const noTests = opts.noTests || false;
 
-  let nodes = db
-    .prepare(`SELECT * FROM nodes WHERE name LIKE ? AND kind IN ('function', 'method', 'class')`)
-    .all(`%${name}%`);
-  if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
+  const nodes = findMatchingNodes(db, name, { noTests, file: opts.file, kind: opts.kind });
   if (nodes.length === 0) {
     db.close();
     return { name, results: [] };
@@ -695,6 +807,67 @@ export function statsData(customDbPath) {
     /* embeddings table may not exist */
   }
 
+  // Graph quality metrics
+  const totalCallable = db
+    .prepare("SELECT COUNT(*) as c FROM nodes WHERE kind IN ('function', 'method')")
+    .get().c;
+  const callableWithCallers = db
+    .prepare(`
+      SELECT COUNT(DISTINCT e.target_id) as c FROM edges e
+      JOIN nodes n ON e.target_id = n.id
+      WHERE e.kind = 'calls' AND n.kind IN ('function', 'method')
+    `)
+    .get().c;
+  const callerCoverage = totalCallable > 0 ? callableWithCallers / totalCallable : 0;
+
+  const totalCallEdges = db.prepare("SELECT COUNT(*) as c FROM edges WHERE kind = 'calls'").get().c;
+  const highConfCallEdges = db
+    .prepare("SELECT COUNT(*) as c FROM edges WHERE kind = 'calls' AND confidence >= 0.7")
+    .get().c;
+  const callConfidence = totalCallEdges > 0 ? highConfCallEdges / totalCallEdges : 0;
+
+  // False-positive warnings: generic names with > threshold callers
+  const fpRows = db
+    .prepare(`
+      SELECT n.name, n.file, n.line, COUNT(e.source_id) as caller_count
+      FROM nodes n
+      LEFT JOIN edges e ON n.id = e.target_id AND e.kind = 'calls'
+      WHERE n.kind IN ('function', 'method')
+      GROUP BY n.id
+      HAVING caller_count > ?
+      ORDER BY caller_count DESC
+    `)
+    .all(FALSE_POSITIVE_CALLER_THRESHOLD);
+  const falsePositiveWarnings = fpRows
+    .filter((r) =>
+      FALSE_POSITIVE_NAMES.has(r.name.includes('.') ? r.name.split('.').pop() : r.name),
+    )
+    .map((r) => ({ name: r.name, file: r.file, line: r.line, callerCount: r.caller_count }));
+
+  // Edges from suspicious nodes
+  let fpEdgeCount = 0;
+  for (const fp of falsePositiveWarnings) fpEdgeCount += fp.callerCount;
+  const falsePositiveRatio = totalCallEdges > 0 ? fpEdgeCount / totalCallEdges : 0;
+
+  const score = Math.round(
+    callerCoverage * 40 + callConfidence * 40 + (1 - falsePositiveRatio) * 20,
+  );
+
+  const quality = {
+    score,
+    callerCoverage: {
+      ratio: callerCoverage,
+      covered: callableWithCallers,
+      total: totalCallable,
+    },
+    callConfidence: {
+      ratio: callConfidence,
+      highConf: highConfCallEdges,
+      total: totalCallEdges,
+    },
+    falsePositiveWarnings,
+  };
+
   db.close();
   return {
     nodes: { total: totalNodes, byKind: nodesByKind },
@@ -703,6 +876,7 @@ export function statsData(customDbPath) {
     cycles: { fileLevel: fileCycles.length, functionLevel: fnCycles.length },
     hotspots,
     embeddings,
+    quality,
   };
 }
 
@@ -779,6 +953,26 @@ export function stats(customDbPath, opts = {}) {
     console.log('\nEmbeddings: not built');
   }
 
+  // Quality
+  if (data.quality) {
+    const q = data.quality;
+    const cc = q.callerCoverage;
+    const cf = q.callConfidence;
+    console.log(`\nGraph Quality: ${q.score}/100`);
+    console.log(
+      `  Caller coverage:  ${(cc.ratio * 100).toFixed(1)}% (${cc.covered}/${cc.total} functions have >=1 caller)`,
+    );
+    console.log(
+      `  Call confidence:  ${(cf.ratio * 100).toFixed(1)}% (${cf.highConf}/${cf.total} call edges are high-confidence)`,
+    );
+    if (q.falsePositiveWarnings.length > 0) {
+      console.log('  False-positive warnings:');
+      for (const fp of q.falsePositiveWarnings) {
+        console.log(`    ! ${fp.name} (${fp.callerCount} callers) -- ${fp.file}:${fp.line}`);
+      }
+    }
+  }
+
   console.log();
 }
 
@@ -815,7 +1009,7 @@ export function queryName(name, customDbPath, opts = {}) {
 }
 
 export function impactAnalysis(file, customDbPath, opts = {}) {
-  const data = impactAnalysisData(file, customDbPath);
+  const data = impactAnalysisData(file, customDbPath, { noTests: opts.noTests });
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2));
     return;
@@ -846,7 +1040,7 @@ export function impactAnalysis(file, customDbPath, opts = {}) {
 }
 
 export function moduleMap(customDbPath, limit = 20, opts = {}) {
-  const data = moduleMapData(customDbPath, limit);
+  const data = moduleMapData(customDbPath, limit, { noTests: opts.noTests });
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2));
     return;
@@ -874,7 +1068,7 @@ export function moduleMap(customDbPath, limit = 20, opts = {}) {
 }
 
 export function fileDeps(file, customDbPath, opts = {}) {
-  const data = fileDepsData(file, customDbPath);
+  const data = fileDepsData(file, customDbPath, { noTests: opts.noTests });
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2));
     return;
@@ -949,13 +1143,15 @@ export function fnDeps(name, customDbPath, opts = {}) {
 
 function readSourceRange(repoRoot, file, startLine, endLine) {
   try {
-    const absPath = path.resolve(repoRoot, file);
+    const absPath = safePath(repoRoot, file);
+    if (!absPath) return null;
     const content = fs.readFileSync(absPath, 'utf-8');
     const lines = content.split('\n');
     const start = Math.max(0, (startLine || 1) - 1);
     const end = Math.min(lines.length, endLine || startLine + 50);
     return lines.slice(start, end).join('\n');
-  } catch {
+  } catch (e) {
+    debug(`readSourceRange failed for ${file}: ${e.message}`);
     return null;
   }
 }
@@ -1065,12 +1261,7 @@ export function contextData(name, customDbPath, opts = {}) {
   const dbPath = findDbPath(customDbPath);
   const repoRoot = path.resolve(path.dirname(dbPath), '..');
 
-  let nodes = db
-    .prepare(
-      `SELECT * FROM nodes WHERE name LIKE ? AND kind IN ('function', 'method', 'class') ORDER BY file, line`,
-    )
-    .all(`%${name}%`);
-  if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
+  let nodes = findMatchingNodes(db, name, { noTests, file: opts.file, kind: opts.kind });
   if (nodes.length === 0) {
     db.close();
     return { name, results: [] };
@@ -1084,11 +1275,16 @@ export function contextData(name, customDbPath, opts = {}) {
   function getFileLines(file) {
     if (fileCache.has(file)) return fileCache.get(file);
     try {
-      const absPath = path.resolve(repoRoot, file);
+      const absPath = safePath(repoRoot, file);
+      if (!absPath) {
+        fileCache.set(file, null);
+        return null;
+      }
       const lines = fs.readFileSync(absPath, 'utf-8').split('\n');
       fileCache.set(file, lines);
       return lines;
-    } catch {
+    } catch (e) {
+      debug(`getFileLines failed for ${file}: ${e.message}`);
       fileCache.set(file, null);
       return null;
     }
@@ -1341,6 +1537,461 @@ export function context(name, customDbPath, opts = {}) {
   }
 }
 
+// ─── explainData ────────────────────────────────────────────────────────
+
+function isFileLikeTarget(target) {
+  if (target.includes('/') || target.includes('\\')) return true;
+  const ext = path.extname(target).toLowerCase();
+  if (!ext) return false;
+  for (const entry of LANGUAGE_REGISTRY) {
+    if (entry.extensions.includes(ext)) return true;
+  }
+  return false;
+}
+
+function explainFileImpl(db, target, getFileLines) {
+  const fileNodes = db
+    .prepare(`SELECT * FROM nodes WHERE file LIKE ? AND kind = 'file'`)
+    .all(`%${target}%`);
+  if (fileNodes.length === 0) return [];
+
+  return fileNodes.map((fn) => {
+    const symbols = db
+      .prepare(`SELECT * FROM nodes WHERE file = ? AND kind != 'file' ORDER BY line`)
+      .all(fn.file);
+
+    // IDs of symbols that have incoming calls from other files (public)
+    const publicIds = new Set(
+      db
+        .prepare(
+          `SELECT DISTINCT e.target_id FROM edges e
+           JOIN nodes caller ON e.source_id = caller.id
+           JOIN nodes target ON e.target_id = target.id
+           WHERE target.file = ? AND caller.file != ? AND e.kind = 'calls'`,
+        )
+        .all(fn.file, fn.file)
+        .map((r) => r.target_id),
+    );
+
+    const fileLines = getFileLines(fn.file);
+    const mapSymbol = (s) => ({
+      name: s.name,
+      kind: s.kind,
+      line: s.line,
+      summary: fileLines ? extractSummary(fileLines, s.line) : null,
+      signature: fileLines ? extractSignature(fileLines, s.line) : null,
+    });
+
+    const publicApi = symbols.filter((s) => publicIds.has(s.id)).map(mapSymbol);
+    const internal = symbols.filter((s) => !publicIds.has(s.id)).map(mapSymbol);
+
+    // Imports / importedBy
+    const imports = db
+      .prepare(
+        `SELECT n.file FROM edges e JOIN nodes n ON e.target_id = n.id
+         WHERE e.source_id = ? AND e.kind IN ('imports', 'imports-type')`,
+      )
+      .all(fn.id)
+      .map((r) => ({ file: r.file }));
+
+    const importedBy = db
+      .prepare(
+        `SELECT n.file FROM edges e JOIN nodes n ON e.source_id = n.id
+         WHERE e.target_id = ? AND e.kind IN ('imports', 'imports-type')`,
+      )
+      .all(fn.id)
+      .map((r) => ({ file: r.file }));
+
+    // Intra-file data flow
+    const intraEdges = db
+      .prepare(
+        `SELECT caller.name as caller_name, callee.name as callee_name
+         FROM edges e
+         JOIN nodes caller ON e.source_id = caller.id
+         JOIN nodes callee ON e.target_id = callee.id
+         WHERE caller.file = ? AND callee.file = ? AND e.kind = 'calls'
+         ORDER BY caller.line`,
+      )
+      .all(fn.file, fn.file);
+
+    const dataFlowMap = new Map();
+    for (const edge of intraEdges) {
+      if (!dataFlowMap.has(edge.caller_name)) dataFlowMap.set(edge.caller_name, []);
+      dataFlowMap.get(edge.caller_name).push(edge.callee_name);
+    }
+    const dataFlow = [...dataFlowMap.entries()].map(([caller, callees]) => ({
+      caller,
+      callees,
+    }));
+
+    // Line count: prefer node_metrics (actual), fall back to MAX(end_line)
+    const metric = db
+      .prepare(`SELECT nm.line_count FROM node_metrics nm WHERE nm.node_id = ?`)
+      .get(fn.id);
+    let lineCount = metric?.line_count || null;
+    if (!lineCount) {
+      const maxLine = db
+        .prepare(`SELECT MAX(end_line) as max_end FROM nodes WHERE file = ?`)
+        .get(fn.file);
+      lineCount = maxLine?.max_end || null;
+    }
+
+    return {
+      file: fn.file,
+      lineCount,
+      symbolCount: symbols.length,
+      publicApi,
+      internal,
+      imports,
+      importedBy,
+      dataFlow,
+    };
+  });
+}
+
+function explainFunctionImpl(db, target, noTests, getFileLines) {
+  let nodes = db
+    .prepare(
+      `SELECT * FROM nodes WHERE name LIKE ? AND kind IN ('function','method','class','interface','type','struct','enum','trait','record','module') ORDER BY file, line`,
+    )
+    .all(`%${target}%`);
+  if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
+  if (nodes.length === 0) return [];
+
+  return nodes.slice(0, 10).map((node) => {
+    const fileLines = getFileLines(node.file);
+    const lineCount = node.end_line ? node.end_line - node.line + 1 : null;
+    const summary = fileLines ? extractSummary(fileLines, node.line) : null;
+    const signature = fileLines ? extractSignature(fileLines, node.line) : null;
+
+    const callees = db
+      .prepare(
+        `SELECT n.name, n.kind, n.file, n.line
+         FROM edges e JOIN nodes n ON e.target_id = n.id
+         WHERE e.source_id = ? AND e.kind = 'calls'`,
+      )
+      .all(node.id)
+      .map((c) => ({ name: c.name, kind: c.kind, file: c.file, line: c.line }));
+
+    let callers = db
+      .prepare(
+        `SELECT n.name, n.kind, n.file, n.line
+         FROM edges e JOIN nodes n ON e.source_id = n.id
+         WHERE e.target_id = ? AND e.kind = 'calls'`,
+      )
+      .all(node.id)
+      .map((c) => ({ name: c.name, kind: c.kind, file: c.file, line: c.line }));
+    if (noTests) callers = callers.filter((c) => !isTestFile(c.file));
+
+    const testCallerRows = db
+      .prepare(
+        `SELECT DISTINCT n.file FROM edges e JOIN nodes n ON e.source_id = n.id
+         WHERE e.target_id = ? AND e.kind = 'calls'`,
+      )
+      .all(node.id);
+    const relatedTests = testCallerRows
+      .filter((r) => isTestFile(r.file))
+      .map((r) => ({ file: r.file }));
+
+    return {
+      name: node.name,
+      kind: node.kind,
+      file: node.file,
+      line: node.line,
+      endLine: node.end_line || null,
+      lineCount,
+      summary,
+      signature,
+      callees,
+      callers,
+      relatedTests,
+    };
+  });
+}
+
+export function explainData(target, customDbPath, opts = {}) {
+  const db = openReadonlyOrFail(customDbPath);
+  const noTests = opts.noTests || false;
+  const kind = isFileLikeTarget(target) ? 'file' : 'function';
+
+  const dbPath = findDbPath(customDbPath);
+  const repoRoot = path.resolve(path.dirname(dbPath), '..');
+
+  const fileCache = new Map();
+  function getFileLines(file) {
+    if (fileCache.has(file)) return fileCache.get(file);
+    try {
+      const absPath = safePath(repoRoot, file);
+      if (!absPath) {
+        fileCache.set(file, null);
+        return null;
+      }
+      const lines = fs.readFileSync(absPath, 'utf-8').split('\n');
+      fileCache.set(file, lines);
+      return lines;
+    } catch (e) {
+      debug(`getFileLines failed for ${file}: ${e.message}`);
+      fileCache.set(file, null);
+      return null;
+    }
+  }
+
+  const results =
+    kind === 'file'
+      ? explainFileImpl(db, target, getFileLines)
+      : explainFunctionImpl(db, target, noTests, getFileLines);
+
+  db.close();
+  return { target, kind, results };
+}
+
+export function explain(target, customDbPath, opts = {}) {
+  const data = explainData(target, customDbPath, opts);
+  if (opts.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+  if (data.results.length === 0) {
+    console.log(`No ${data.kind === 'file' ? 'file' : 'function/symbol'} matching "${target}"`);
+    return;
+  }
+
+  if (data.kind === 'file') {
+    for (const r of data.results) {
+      const publicCount = r.publicApi.length;
+      const internalCount = r.internal.length;
+      const lineInfo = r.lineCount ? `${r.lineCount} lines, ` : '';
+      console.log(`\n# ${r.file}`);
+      console.log(
+        `  ${lineInfo}${r.symbolCount} symbols (${publicCount} exported, ${internalCount} internal)`,
+      );
+
+      if (r.imports.length > 0) {
+        console.log(`  Imports: ${r.imports.map((i) => i.file).join(', ')}`);
+      }
+      if (r.importedBy.length > 0) {
+        console.log(`  Imported by: ${r.importedBy.map((i) => i.file).join(', ')}`);
+      }
+
+      if (r.publicApi.length > 0) {
+        console.log(`\n## Exported`);
+        for (const s of r.publicApi) {
+          const sig = s.signature?.params != null ? `(${s.signature.params})` : '';
+          const summary = s.summary ? `  -- ${s.summary}` : '';
+          console.log(`  ${kindIcon(s.kind)} ${s.name}${sig} :${s.line}${summary}`);
+        }
+      }
+
+      if (r.internal.length > 0) {
+        console.log(`\n## Internal`);
+        for (const s of r.internal) {
+          const sig = s.signature?.params != null ? `(${s.signature.params})` : '';
+          const summary = s.summary ? `  -- ${s.summary}` : '';
+          console.log(`  ${kindIcon(s.kind)} ${s.name}${sig} :${s.line}${summary}`);
+        }
+      }
+
+      if (r.dataFlow.length > 0) {
+        console.log(`\n## Data Flow`);
+        for (const df of r.dataFlow) {
+          console.log(`  ${df.caller} -> ${df.callees.join(', ')}`);
+        }
+      }
+      console.log();
+    }
+  } else {
+    for (const r of data.results) {
+      const lineRange = r.endLine ? `${r.line}-${r.endLine}` : `${r.line}`;
+      const lineInfo = r.lineCount ? `${r.lineCount} lines` : '';
+      const summaryPart = r.summary ? ` | ${r.summary}` : '';
+      console.log(`\n# ${r.name} (${r.kind})  ${r.file}:${lineRange}`);
+      if (lineInfo || r.summary) {
+        console.log(`  ${lineInfo}${summaryPart}`);
+      }
+      if (r.signature) {
+        if (r.signature.params != null) console.log(`  Parameters: (${r.signature.params})`);
+        if (r.signature.returnType) console.log(`  Returns: ${r.signature.returnType}`);
+      }
+
+      if (r.callees.length > 0) {
+        console.log(`\n## Calls (${r.callees.length})`);
+        for (const c of r.callees) {
+          console.log(`  ${kindIcon(c.kind)} ${c.name}  ${c.file}:${c.line}`);
+        }
+      }
+
+      if (r.callers.length > 0) {
+        console.log(`\n## Called by (${r.callers.length})`);
+        for (const c of r.callers) {
+          console.log(`  ${kindIcon(c.kind)} ${c.name}  ${c.file}:${c.line}`);
+        }
+      }
+
+      if (r.relatedTests.length > 0) {
+        const label = r.relatedTests.length === 1 ? 'file' : 'files';
+        console.log(`\n## Tests (${r.relatedTests.length} ${label})`);
+        for (const t of r.relatedTests) {
+          console.log(`  ${t.file}`);
+        }
+      }
+
+      if (r.callees.length === 0 && r.callers.length === 0) {
+        console.log(`  (no call edges found -- may be invoked dynamically or via re-exports)`);
+      }
+      console.log();
+    }
+  }
+}
+
+// ─── whereData ──────────────────────────────────────────────────────────
+
+function whereSymbolImpl(db, target, noTests) {
+  const placeholders = ALL_SYMBOL_KINDS.map(() => '?').join(', ');
+  let nodes = db
+    .prepare(
+      `SELECT * FROM nodes WHERE name LIKE ? AND kind IN (${placeholders}) ORDER BY file, line`,
+    )
+    .all(`%${target}%`, ...ALL_SYMBOL_KINDS);
+  if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
+
+  return nodes.map((node) => {
+    const crossFileCallers = db
+      .prepare(
+        `SELECT COUNT(*) as cnt FROM edges e JOIN nodes n ON e.source_id = n.id
+         WHERE e.target_id = ? AND e.kind = 'calls' AND n.file != ?`,
+      )
+      .get(node.id, node.file);
+    const exported = crossFileCallers.cnt > 0;
+
+    let uses = db
+      .prepare(
+        `SELECT n.name, n.file, n.line FROM edges e JOIN nodes n ON e.source_id = n.id
+         WHERE e.target_id = ? AND e.kind = 'calls'`,
+      )
+      .all(node.id);
+    if (noTests) uses = uses.filter((u) => !isTestFile(u.file));
+
+    return {
+      name: node.name,
+      kind: node.kind,
+      file: node.file,
+      line: node.line,
+      exported,
+      uses: uses.map((u) => ({ name: u.name, file: u.file, line: u.line })),
+    };
+  });
+}
+
+function whereFileImpl(db, target) {
+  const fileNodes = db
+    .prepare(`SELECT * FROM nodes WHERE file LIKE ? AND kind = 'file'`)
+    .all(`%${target}%`);
+  if (fileNodes.length === 0) return [];
+
+  return fileNodes.map((fn) => {
+    const symbols = db
+      .prepare(`SELECT * FROM nodes WHERE file = ? AND kind != 'file' ORDER BY line`)
+      .all(fn.file);
+
+    const imports = db
+      .prepare(
+        `SELECT n.file FROM edges e JOIN nodes n ON e.target_id = n.id
+         WHERE e.source_id = ? AND e.kind IN ('imports', 'imports-type')`,
+      )
+      .all(fn.id)
+      .map((r) => r.file);
+
+    const importedBy = db
+      .prepare(
+        `SELECT n.file FROM edges e JOIN nodes n ON e.source_id = n.id
+         WHERE e.target_id = ? AND e.kind IN ('imports', 'imports-type')`,
+      )
+      .all(fn.id)
+      .map((r) => r.file);
+
+    const exportedIds = new Set(
+      db
+        .prepare(
+          `SELECT DISTINCT e.target_id FROM edges e
+           JOIN nodes caller ON e.source_id = caller.id
+           JOIN nodes target ON e.target_id = target.id
+           WHERE target.file = ? AND caller.file != ? AND e.kind = 'calls'`,
+        )
+        .all(fn.file, fn.file)
+        .map((r) => r.target_id),
+    );
+
+    const exported = symbols.filter((s) => exportedIds.has(s.id)).map((s) => s.name);
+
+    return {
+      file: fn.file,
+      symbols: symbols.map((s) => ({ name: s.name, kind: s.kind, line: s.line })),
+      imports,
+      importedBy,
+      exported,
+    };
+  });
+}
+
+export function whereData(target, customDbPath, opts = {}) {
+  const db = openReadonlyOrFail(customDbPath);
+  const noTests = opts.noTests || false;
+  const fileMode = opts.file || false;
+
+  const results = fileMode ? whereFileImpl(db, target) : whereSymbolImpl(db, target, noTests);
+
+  db.close();
+  return { target, mode: fileMode ? 'file' : 'symbol', results };
+}
+
+export function where(target, customDbPath, opts = {}) {
+  const data = whereData(target, customDbPath, opts);
+  if (opts.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  if (data.results.length === 0) {
+    console.log(
+      data.mode === 'file'
+        ? `No file matching "${target}" in graph`
+        : `No symbol matching "${target}" in graph`,
+    );
+    return;
+  }
+
+  if (data.mode === 'symbol') {
+    for (const r of data.results) {
+      const tag = r.exported ? '  (exported)' : '';
+      console.log(`\n${kindIcon(r.kind)} ${r.name}  ${r.file}:${r.line}${tag}`);
+      if (r.uses.length > 0) {
+        const useStrs = r.uses.map((u) => `${u.file}:${u.line}`);
+        console.log(`  Used in: ${useStrs.join(', ')}`);
+      } else {
+        console.log('  No uses found');
+      }
+    }
+  } else {
+    for (const r of data.results) {
+      console.log(`\n# ${r.file}`);
+      if (r.symbols.length > 0) {
+        const symStrs = r.symbols.map((s) => `${s.name}:${s.line}`);
+        console.log(`  Symbols: ${symStrs.join(', ')}`);
+      }
+      if (r.imports.length > 0) {
+        console.log(`  Imports: ${r.imports.join(', ')}`);
+      }
+      if (r.importedBy.length > 0) {
+        console.log(`  Imported by: ${r.importedBy.join(', ')}`);
+      }
+      if (r.exported.length > 0) {
+        console.log(`  Exported: ${r.exported.join(', ')}`);
+      }
+    }
+  }
+  console.log();
+}
+
 export function fnImpact(name, customDbPath, opts = {}) {
   const data = fnImpactData(name, customDbPath, opts);
   if (opts.json) {

package/src/structure.js

@@ -315,30 +315,40 @@ export function hotspotsData(customDbPath, opts = {}) {
   const metric = opts.metric || 'fan-in';
   const level = opts.level || 'file';
   const limit = opts.limit || 10;
+  const noTests = opts.noTests || false;
 
   const kind = level === 'directory' ? 'directory' : 'file';
 
+  const testFilter =
+    noTests && kind === 'file'
+      ? `AND n.name NOT LIKE '%.test.%'
+         AND n.name NOT LIKE '%.spec.%'
+         AND n.name NOT LIKE '%__test__%'
+         AND n.name NOT LIKE '%__tests__%'
+         AND n.name NOT LIKE '%.stories.%'`
+      : '';
+
   const HOTSPOT_QUERIES = {
     'fan-in': db.prepare(`
       SELECT n.name, n.kind, nm.line_count, nm.symbol_count, nm.import_count, nm.export_count,
              nm.fan_in, nm.fan_out, nm.cohesion, nm.file_count
       FROM nodes n JOIN node_metrics nm ON n.id = nm.node_id
-      WHERE n.kind = ? ORDER BY nm.fan_in DESC NULLS LAST LIMIT ?`),
+      WHERE n.kind = ? ${testFilter} ORDER BY nm.fan_in DESC NULLS LAST LIMIT ?`),
     'fan-out': db.prepare(`
       SELECT n.name, n.kind, nm.line_count, nm.symbol_count, nm.import_count, nm.export_count,
              nm.fan_in, nm.fan_out, nm.cohesion, nm.file_count
       FROM nodes n JOIN node_metrics nm ON n.id = nm.node_id
-      WHERE n.kind = ? ORDER BY nm.fan_out DESC NULLS LAST LIMIT ?`),
+      WHERE n.kind = ? ${testFilter} ORDER BY nm.fan_out DESC NULLS LAST LIMIT ?`),
     density: db.prepare(`
       SELECT n.name, n.kind, nm.line_count, nm.symbol_count, nm.import_count, nm.export_count,
              nm.fan_in, nm.fan_out, nm.cohesion, nm.file_count
       FROM nodes n JOIN node_metrics nm ON n.id = nm.node_id
-      WHERE n.kind = ? ORDER BY nm.symbol_count DESC NULLS LAST LIMIT ?`),
+      WHERE n.kind = ? ${testFilter} ORDER BY nm.symbol_count DESC NULLS LAST LIMIT ?`),
     coupling: db.prepare(`
       SELECT n.name, n.kind, nm.line_count, nm.symbol_count, nm.import_count, nm.export_count,
              nm.fan_in, nm.fan_out, nm.cohesion, nm.file_count
       FROM nodes n JOIN node_metrics nm ON n.id = nm.node_id
-      WHERE n.kind = ? ORDER BY (COALESCE(nm.fan_in, 0) + COALESCE(nm.fan_out, 0)) DESC NULLS LAST LIMIT ?`),
+      WHERE n.kind = ? ${testFilter} ORDER BY (COALESCE(nm.fan_in, 0) + COALESCE(nm.fan_out, 0)) DESC NULLS LAST LIMIT ?`),
   };
 
   const stmt = HOTSPOT_QUERIES[metric] || HOTSPOT_QUERIES['fan-in'];