@optave/codegraph 2.1.1-dev.0e15f12 → 2.2.0

package/README.md

@@ -93,7 +93,7 @@ Most code graph tools make you choose: **fast local analysis with no AI, or powe
 | **⚡** | **Always-fresh graph** | Three-tier change detection: journal (O(changed)) → mtime+size (O(n) stats) → hash (O(changed) reads). Sub-second rebuilds even on large codebases. Competitors re-index everything from scratch; Merkle-tree approaches still require O(n) filesystem scanning |
 | **🔓** | **Zero-cost core, LLM-enhanced when you want** | Full graph analysis with no API keys, no accounts, no cost. Optionally bring your own LLM provider for richer embeddings and AI-powered search — your code only goes to the provider you already chose |
 | **🔬** | **Function-level, not just files** | Traces `handleAuth()` → `validateToken()` → `decryptJWT()` and shows 14 callers across 9 files break if `decryptJWT` changes |
-| **🤖** | **Built for AI agents** | 13-tool [MCP server](https://modelcontextprotocol.io/) — AI assistants query your graph directly. Single-repo by default, your code doesn't leak to other projects |
+| **🤖** | **Built for AI agents** | 17-tool [MCP server](https://modelcontextprotocol.io/) — AI assistants query your graph directly. Single-repo by default, your code doesn't leak to other projects |
 | **🌐** | **Multi-language, one CLI** | JS/TS + Python + Go + Rust + Java + C# + PHP + Ruby + HCL in a single graph — no juggling Madge, pyan, and cflow |
 | **💥** | **Git diff impact** | `codegraph diff-impact` shows changed functions, their callers, and full blast radius — ships with a GitHub Actions workflow |
 | **🧠** | **Semantic search** | Local embeddings by default, LLM-powered embeddings when opted in — multi-query with RRF ranking via `"auth; token; JWT"` |
@@ -132,7 +132,7 @@ Here is a cold, analytical breakdown to help you decide which tool fits your wor
 | Aspect | Optave Codegraph | Narsil-MCP |
 | :--- | :--- | :--- |
 | **Philosophy** | Lean, deterministic, AI-optimized | Comprehensive, feature-dense |
-| **AI Tool Count** | 13 focused tools | 90 distinct tools |
+| **AI Tool Count** | 17 focused tools | 90 distinct tools |
 | **Language Support** | 11 languages | 32 languages |
 | **Primary Interface** | CLI-first with MCP integration | MCP-first (CLI is secondary) |
 | **Supply Chain Risk** | Low (minimal dependency tree) | Higher (requires massive dependency graph for embedded ML/scanners) |
@@ -141,7 +141,7 @@ Here is a cold, analytical breakdown to help you decide which tool fits your wor
 #### Choose Codegraph if:
 
 * **You need the fastest possible incremental rebuilds.** Codegraph’s three-tier change detection (journal → mtime+size → hash) achieves true O(changed) when the watcher is running — only touched files are processed. Narsil’s Merkle trees still require O(n) filesystem scanning to recompute hashes on every rebuild, even when nothing changed. On a 3,000-file project, this is the difference between near-instant and noticeable.
-* **You want to optimize AI agent reasoning.** Large Language Models degrade in performance and hallucinate when overwhelmed with choices. Codegraph’s tight 13-tool surface area ensures agents quickly understand their capabilities without wasting context window tokens.
+* **You want to optimize AI agent reasoning.** Large Language Models degrade in performance and hallucinate when overwhelmed with choices. Codegraph’s tight 17-tool surface area ensures agents quickly understand their capabilities without wasting context window tokens.
 * **You are concerned about supply chain attacks.** To support 90 tools, SBOMs, and neural embeddings, a tool must pull in a massive dependency tree. Codegraph keeps its dependencies minimal, dramatically reducing the risk of malicious code sneaking onto your machine.
 * **You want deterministic blast-radius checks.** Features like `diff-impact` are built specifically to tell you exactly how a changed function cascades through your codebase before you merge a PR.
 * **You value a strong standalone CLI.** You want to query your code graph locally without necessarily spinning up an AI agent.
@@ -190,7 +190,7 @@ codegraph deps src/index.ts  # file-level import/export map
 | 📤 | **Export** | DOT (Graphviz), Mermaid, and JSON graph export |
 | 🧠 | **Semantic search** | Embeddings-powered natural language search with multi-query RRF ranking |
 | 👀 | **Watch mode** | Incrementally update the graph as files change |
-| 🤖 | **MCP server** | 13-tool MCP server for AI assistants; single-repo by default, opt-in multi-repo |
+| 🤖 | **MCP server** | 17-tool MCP server for AI assistants; single-repo by default, opt-in multi-repo |
 | 🔒 | **Your code, your choice** | Zero-cost core with no API keys. Optionally enhance with your LLM provider — your code only goes where you send it |
 
 ## 📦 Commands
@@ -391,7 +391,7 @@ Metrics are normalized per file for cross-version comparability. Times above are
 
 ### MCP Server
 
-Codegraph includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) server with 13 tools, so AI assistants can query your dependency graph directly:
+Codegraph includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) server with 17 tools, so AI assistants can query your dependency graph directly:
 
 ```bash
 codegraph mcp                  # Single-repo mode (default) — only local project
@@ -405,20 +405,35 @@ codegraph mcp --repos a,b      # Multi-repo with allowlist
 
 ### CLAUDE.md / Agent Instructions
 
-Add this to your project's `CLAUDE.md` to help AI agents use codegraph:
+Add this to your project's `CLAUDE.md` to help AI agents use codegraph (full template in the [AI Agent Guide](docs/ai-agent-guide.md#claudemd-template)):
 
 ```markdown
 ## Code Navigation
 
 This project uses codegraph. The database is at `.codegraph/graph.db`.
 
-- **Before modifying a function**: `codegraph fn <name> --no-tests`
-- **Before modifying a file**: `codegraph deps <file>`
-- **To assess PR impact**: `codegraph diff-impact --no-tests`
-- **To find entry points**: `codegraph map`
-- **To trace breakage**: `codegraph fn-impact <name> --no-tests`
-
-Rebuild after major structural changes: `codegraph build`
+### Before modifying code, always:
+1. `codegraph where <name>` — find where the symbol lives
+2. `codegraph explain <file-or-function>` — understand the structure
+3. `codegraph context <name> -T` — get full context (source, deps, callers)
+4. `codegraph fn-impact <name> -T` — check blast radius before editing
+
+### After modifying code:
+5. `codegraph diff-impact --staged -T` — verify impact before committing
+
+### Other useful commands
+- `codegraph build .` — rebuild the graph (incremental by default)
+- `codegraph map` — module overview
+- `codegraph fn <name> -T` — function call chain
+- `codegraph deps <file>` — file-level dependencies
+- `codegraph search "<query>"` — semantic search (requires `codegraph embed`)
+- `codegraph cycles` — check for circular dependencies
+
+### Flags
+- `-T` / `--no-tests` — exclude test files (use by default)
+- `-j` / `--json` — JSON output for programmatic use
+- `-f, --file <path>` — scope to a specific file
+- `-k, --kind <kind>` — filter by symbol kind
 
 ### Semantic search
 
@@ -456,6 +471,8 @@ See **[docs/recommended-practices.md](docs/recommended-practices.md)** for integ
 - **Developer workflow** — watch mode, explore-before-you-edit, semantic search
 - **Secure credentials** — `apiKeyCommand` with 1Password, Bitwarden, Vault, macOS Keychain, `pass`
 
+For AI-specific integration, see the **[AI Agent Guide](docs/ai-agent-guide.md)** — a comprehensive reference covering the 6-step agent workflow, complete command-to-MCP mapping, Claude Code hooks, and token-saving patterns.
+
 ## 🔁 CI / GitHub Actions
 
 Codegraph ships with a ready-to-use GitHub Actions workflow that comments impact analysis on every pull request.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optave/codegraph",
-  "version": "2.1.1-dev.0e15f12",
+  "version": "2.2.0",
   "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.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"
+    "@optave/codegraph-darwin-arm64": "2.2.0",
+    "@optave/codegraph-darwin-x64": "2.2.0",
+    "@optave/codegraph-linux-x64-gnu": "2.2.0",
+    "@optave/codegraph-win32-x64-msvc": "2.2.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.4",

package/src/cli.js

@@ -62,18 +62,20 @@ program
   .command('query <name>')
   .description('Find a function/class, show callers and callees')
   .option('-d, --db <path>', 'Path to graph.db')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('-j, --json', 'Output as JSON')
   .action((name, opts) => {
-    queryName(name, opts.db, { json: opts.json });
+    queryName(name, opts.db, { noTests: !opts.tests, json: opts.json });
   });
 
 program
   .command('impact <file>')
   .description('Show what depends on this file (transitive)')
   .option('-d, --db <path>', 'Path to graph.db')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('-j, --json', 'Output as JSON')
   .action((file, opts) => {
-    impactAnalysis(file, opts.db, { json: opts.json });
+    impactAnalysis(file, opts.db, { noTests: !opts.tests, json: opts.json });
   });
 
 program
@@ -81,27 +83,30 @@ program
   .description('High-level module overview with most-connected nodes')
   .option('-d, --db <path>', 'Path to graph.db')
   .option('-n, --limit <number>', 'Number of top nodes', '20')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('-j, --json', 'Output as JSON')
   .action((opts) => {
-    moduleMap(opts.db, parseInt(opts.limit, 10), { json: opts.json });
+    moduleMap(opts.db, parseInt(opts.limit, 10), { noTests: !opts.tests, json: opts.json });
   });
 
 program
   .command('stats')
   .description('Show graph health overview: nodes, edges, languages, cycles, hotspots, embeddings')
   .option('-d, --db <path>', 'Path to graph.db')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('-j, --json', 'Output as JSON')
   .action((opts) => {
-    stats(opts.db, { json: opts.json });
+    stats(opts.db, { noTests: !opts.tests, json: opts.json });
   });
 
 program
   .command('deps <file>')
   .description('Show what this file imports and what imports it')
   .option('-d, --db <path>', 'Path to graph.db')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('-j, --json', 'Output as JSON')
   .action((file, opts) => {
-    fileDeps(file, opts.db, { json: opts.json });
+    fileDeps(file, opts.db, { noTests: !opts.tests, json: opts.json });
   });
 
 program
@@ -159,7 +164,7 @@ program
   .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('-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)) {
@@ -181,7 +186,7 @@ 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('-T, --no-tests', 'Exclude test/spec files from results')
   .option('-j, --json', 'Output as JSON')
   .action((target, opts) => {
     explain(target, opts.db, { noTests: !opts.tests, json: opts.json });
@@ -192,7 +197,7 @@ program
   .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('-T, --no-tests', 'Exclude test/spec files from results')
   .option('-j, --json', 'Output as JSON')
   .action((name, opts) => {
     if (!name && !opts.file) {
@@ -229,10 +234,11 @@ program
   .option('-d, --db <path>', 'Path to graph.db')
   .option('-f, --format <format>', 'Output format: dot, mermaid, json', 'dot')
   .option('--functions', 'Function-level graph instead of file-level')
+  .option('-T, --no-tests', 'Exclude test/spec files')
   .option('-o, --output <file>', 'Write to file instead of stdout')
   .action((opts) => {
     const db = new Database(findDbPath(opts.db), { readonly: true });
-    const exportOpts = { fileLevel: !opts.functions };
+    const exportOpts = { fileLevel: !opts.functions, noTests: !opts.tests };
 
     let output;
     switch (opts.format) {
@@ -240,7 +246,7 @@ program
         output = exportMermaid(db, exportOpts);
         break;
       case 'json':
-        output = JSON.stringify(exportJSON(db), null, 2);
+        output = JSON.stringify(exportJSON(db, exportOpts), null, 2);
         break;
       default:
         output = exportDOT(db, exportOpts);
@@ -262,10 +268,11 @@ program
   .description('Detect circular dependencies in the codebase')
   .option('-d, --db <path>', 'Path to graph.db')
   .option('--functions', 'Function-level cycle detection')
+  .option('-T, --no-tests', 'Exclude test/spec files')
   .option('-j, --json', 'Output as JSON')
   .action((opts) => {
     const db = new Database(findDbPath(opts.db), { readonly: true });
-    const cycles = findCycles(db, { fileLevel: !opts.functions });
+    const cycles = findCycles(db, { fileLevel: !opts.functions, noTests: !opts.tests });
     db.close();
 
     if (opts.json) {
@@ -395,7 +402,7 @@ program
   .option('-d, --db <path>', 'Path to graph.db')
   .option('-m, --model <name>', 'Override embedding model (auto-detects from DB)')
   .option('-n, --limit <number>', 'Max results', '15')
-  .option('-T, --no-tests', 'Exclude test/spec files')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('--min-score <score>', 'Minimum similarity threshold', '0.2')
   .option('-k, --kind <kind>', 'Filter by kind: function, method, class')
   .option('--file <pattern>', 'Filter by file path pattern')
@@ -420,6 +427,7 @@ program
   .option('-d, --db <path>', 'Path to graph.db')
   .option('--depth <n>', 'Max directory depth')
   .option('--sort <metric>', 'Sort by: cohesion | fan-in | fan-out | density | files', 'files')
+  .option('-T, --no-tests', 'Exclude test/spec files')
   .option('-j, --json', 'Output as JSON')
   .action(async (dir, opts) => {
     const { structureData, formatStructure } = await import('./structure.js');
@@ -427,6 +435,7 @@ program
       directory: dir,
       depth: opts.depth ? parseInt(opts.depth, 10) : undefined,
       sort: opts.sort,
+      noTests: !opts.tests,
     });
     if (opts.json) {
       console.log(JSON.stringify(data, null, 2));
@@ -444,6 +453,7 @@ program
   .option('-n, --limit <number>', 'Number of results', '10')
   .option('--metric <metric>', 'fan-in | fan-out | density | coupling', 'fan-in')
   .option('--level <level>', 'file | directory', 'file')
+  .option('-T, --no-tests', 'Exclude test/spec files from results')
   .option('-j, --json', 'Output as JSON')
   .action(async (opts) => {
     const { hotspotsData, formatHotspots } = await import('./structure.js');
@@ -451,6 +461,7 @@ program
       metric: opts.metric,
       level: opts.level,
       limit: parseInt(opts.limit, 10),
+      noTests: !opts.tests,
     });
     if (opts.json) {
       console.log(JSON.stringify(data, null, 2));

package/src/cycles.js

@@ -1,14 +1,16 @@
 import { loadNative } from './native.js';
+import { isTestFile } from './queries.js';
 
 /**
  * Detect circular dependencies in the codebase using Tarjan's SCC algorithm.
  * Dispatches to native Rust implementation when available, falls back to JS.
  * @param {object} db - Open SQLite database
- * @param {object} opts - { fileLevel: true }
+ * @param {object} opts - { fileLevel: true, noTests: false }
  * @returns {string[][]} Array of cycles, each cycle is an array of file paths
  */
 export function findCycles(db, opts = {}) {
   const fileLevel = opts.fileLevel !== false;
+  const noTests = opts.noTests || false;
 
   // Build adjacency list from SQLite (stays in JS — only the algorithm can move to Rust)
   let edges;
@@ -22,6 +24,9 @@ export function findCycles(db, opts = {}) {
       WHERE n1.file != n2.file AND e.kind IN ('imports', 'imports-type')
     `)
       .all();
+    if (noTests) {
+      edges = edges.filter((e) => !isTestFile(e.source) && !isTestFile(e.target));
+    }
   } else {
     edges = db
       .prepare(`
@@ -37,6 +42,13 @@ export function findCycles(db, opts = {}) {
         AND n1.id != n2.id
     `)
       .all();
+    if (noTests) {
+      edges = edges.filter((e) => {
+        const sourceFile = e.source.split('|').pop();
+        const targetFile = e.target.split('|').pop();
+        return !isTestFile(sourceFile) && !isTestFile(targetFile);
+      });
+    }
   }
 
   // Try native Rust implementation

package/src/export.js

@@ -1,10 +1,12 @@
 import path from 'node:path';
+import { isTestFile } from './queries.js';
 
 /**
  * Export the dependency graph in DOT (Graphviz) format.
  */
 export function exportDOT(db, opts = {}) {
   const fileLevel = opts.fileLevel !== false;
+  const noTests = opts.noTests || false;
   const lines = [
     'digraph codegraph {',
     '  rankdir=LR;',
@@ -14,7 +16,7 @@ export function exportDOT(db, opts = {}) {
   ];
 
   if (fileLevel) {
-    const edges = db
+    let edges = db
       .prepare(`
       SELECT DISTINCT n1.file AS source, n2.file AS target
       FROM edges e
@@ -23,6 +25,7 @@ export function exportDOT(db, opts = {}) {
       WHERE n1.file != n2.file AND e.kind IN ('imports', 'imports-type', 'calls')
     `)
       .all();
+    if (noTests) edges = edges.filter((e) => !isTestFile(e.source) && !isTestFile(e.target));
 
     // Try to use directory nodes from DB (built by structure analysis)
     const hasDirectoryNodes =
@@ -89,7 +92,7 @@ export function exportDOT(db, opts = {}) {
       lines.push(`  "${source}" -> "${target}";`);
     }
   } else {
-    const edges = db
+    let edges = db
       .prepare(`
       SELECT n1.name AS source_name, n1.kind AS source_kind, n1.file AS source_file,
              n2.name AS target_name, n2.kind AS target_kind, n2.file AS target_file,
@@ -101,6 +104,8 @@ export function exportDOT(db, opts = {}) {
       AND e.kind = 'calls'
     `)
       .all();
+    if (noTests)
+      edges = edges.filter((e) => !isTestFile(e.source_file) && !isTestFile(e.target_file));
 
     for (const e of edges) {
       const sId = `${e.source_file}:${e.source_name}`.replace(/[^a-zA-Z0-9_]/g, '_');
@@ -120,10 +125,11 @@ export function exportDOT(db, opts = {}) {
  */
 export function exportMermaid(db, opts = {}) {
   const fileLevel = opts.fileLevel !== false;
+  const noTests = opts.noTests || false;
   const lines = ['graph LR'];
 
   if (fileLevel) {
-    const edges = db
+    let edges = db
       .prepare(`
       SELECT DISTINCT n1.file AS source, n2.file AS target
       FROM edges e
@@ -132,6 +138,7 @@ export function exportMermaid(db, opts = {}) {
       WHERE n1.file != n2.file AND e.kind IN ('imports', 'imports-type', 'calls')
     `)
       .all();
+    if (noTests) edges = edges.filter((e) => !isTestFile(e.source) && !isTestFile(e.target));
 
     for (const { source, target } of edges) {
       const s = source.replace(/[^a-zA-Z0-9]/g, '_');
@@ -139,7 +146,7 @@ export function exportMermaid(db, opts = {}) {
       lines.push(`  ${s}["${source}"] --> ${t}["${target}"]`);
     }
   } else {
-    const edges = db
+    let edges = db
       .prepare(`
       SELECT n1.name AS source_name, n1.file AS source_file,
              n2.name AS target_name, n2.file AS target_file
@@ -150,6 +157,8 @@ export function exportMermaid(db, opts = {}) {
       AND e.kind = 'calls'
     `)
       .all();
+    if (noTests)
+      edges = edges.filter((e) => !isTestFile(e.source_file) && !isTestFile(e.target_file));
 
     for (const e of edges) {
       const sId = `${e.source_file}_${e.source_name}`.replace(/[^a-zA-Z0-9]/g, '_');
@@ -164,14 +173,17 @@ export function exportMermaid(db, opts = {}) {
 /**
  * Export as JSON adjacency list.
  */
-export function exportJSON(db) {
-  const nodes = db
+export function exportJSON(db, opts = {}) {
+  const noTests = opts.noTests || false;
+
+  let nodes = db
     .prepare(`
     SELECT id, name, kind, file, line FROM nodes WHERE kind = 'file'
   `)
     .all();
+  if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
 
-  const edges = db
+  let edges = db
     .prepare(`
     SELECT DISTINCT n1.file AS source, n2.file AS target, e.kind
     FROM edges e
@@ -180,6 +192,7 @@ export function exportJSON(db) {
     WHERE n1.file != n2.file
   `)
     .all();
+  if (noTests) edges = edges.filter((e) => !isTestFile(e.source) && !isTestFile(e.target));
 
   return { nodes, edges };
 }

package/src/mcp.js

@@ -30,6 +30,7 @@ const BASE_TOOLS = [
           description: 'Traversal depth for transitive callers',
           default: 2,
         },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
       },
       required: ['name'],
     },
@@ -41,6 +42,7 @@ const BASE_TOOLS = [
       type: 'object',
       properties: {
         file: { type: 'string', description: 'File path (partial match supported)' },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
       },
       required: ['file'],
     },
@@ -52,6 +54,7 @@ const BASE_TOOLS = [
       type: 'object',
       properties: {
         file: { type: 'string', description: 'File path to analyze' },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
       },
       required: ['file'],
     },
@@ -71,6 +74,7 @@ const BASE_TOOLS = [
       type: 'object',
       properties: {
         limit: { type: 'number', description: 'Number of top files to show', default: 20 },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
       },
     },
   },
@@ -282,6 +286,7 @@ const BASE_TOOLS = [
           description: 'Rank files or directories',
         },
         limit: { type: 'number', description: 'Number of results to return', default: 10 },
+        no_tests: { type: 'boolean', description: 'Exclude test files', default: false },
       },
     },
   },
@@ -408,13 +413,13 @@ export async function startMCPServer(customDbPath, options = {}) {
       let result;
       switch (name) {
         case 'query_function':
-          result = queryNameData(args.name, dbPath);
+          result = queryNameData(args.name, dbPath, { noTests: args.no_tests });
           break;
         case 'file_deps':
-          result = fileDepsData(args.file, dbPath);
+          result = fileDepsData(args.file, dbPath, { noTests: args.no_tests });
           break;
         case 'impact_analysis':
-          result = impactAnalysisData(args.file, dbPath);
+          result = impactAnalysisData(args.file, dbPath, { noTests: args.no_tests });
           break;
         case 'find_cycles': {
           const db = new Database(findDbPath(dbPath), { readonly: true });
@@ -424,7 +429,7 @@ export async function startMCPServer(customDbPath, options = {}) {
           break;
         }
         case 'module_map':
-          result = moduleMapData(dbPath, args.limit || 20);
+          result = moduleMapData(dbPath, args.limit || 20, { noTests: args.no_tests });
           break;
         case 'fn_deps':
           result = fnDepsData(args.name, dbPath, {
@@ -536,6 +541,7 @@ export async function startMCPServer(customDbPath, options = {}) {
             metric: args.metric,
             level: args.level,
             limit: args.limit,
+            noTests: args.no_tests,
           });
           break;
         }

package/src/queries.js

@@ -17,7 +17,7 @@ function safePath(repoRoot, file) {
 }
 
 const TEST_PATTERN = /\.(test|spec)\.|__test__|__tests__|\.stories\./;
-function isTestFile(filePath) {
+export function isTestFile(filePath) {
   return TEST_PATTERN.test(filePath);
 }
 
@@ -190,16 +190,18 @@ function kindIcon(kind) {
 
 // ─── Data-returning functions ───────────────────────────────────────────
 
-export function queryNameData(name, customDbPath) {
+export function queryNameData(name, customDbPath, opts = {}) {
   const db = openReadonlyOrFail(customDbPath);
-  const nodes = db.prepare(`SELECT * FROM nodes WHERE name LIKE ?`).all(`%${name}%`);
+  const noTests = opts.noTests || false;
+  let nodes = db.prepare(`SELECT * FROM nodes WHERE name LIKE ?`).all(`%${name}%`);
+  if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
   if (nodes.length === 0) {
     db.close();
     return { query: name, results: [] };
   }
 
   const results = nodes.map((node) => {
-    const callees = db
+    let callees = db
       .prepare(`
       SELECT n.name, n.kind, n.file, n.line, e.kind as edge_kind
       FROM edges e JOIN nodes n ON e.target_id = n.id
@@ -207,7 +209,7 @@ export function queryNameData(name, customDbPath) {
     `)
       .all(node.id);
 
-    const callers = db
+    let callers = db
       .prepare(`
       SELECT n.name, n.kind, n.file, n.line, e.kind as edge_kind
       FROM edges e JOIN nodes n ON e.source_id = n.id
@@ -215,6 +217,11 @@ export function queryNameData(name, customDbPath) {
     `)
       .all(node.id);
 
+    if (noTests) {
+      callees = callees.filter((c) => !isTestFile(c.file));
+      callers = callers.filter((c) => !isTestFile(c.file));
+    }
+
     return {
       name: node.name,
       kind: node.kind,
@@ -728,11 +735,40 @@ export function listFunctionsData(customDbPath, opts = {}) {
   return { count: rows.length, functions: rows };
 }
 
-export function statsData(customDbPath) {
+export function statsData(customDbPath, opts = {}) {
   const db = openReadonlyOrFail(customDbPath);
+  const noTests = opts.noTests || false;
+
+  // Build set of test file IDs for filtering nodes and edges
+  let testFileIds = null;
+  if (noTests) {
+    const allFileNodes = db.prepare("SELECT id, file FROM nodes WHERE kind = 'file'").all();
+    testFileIds = new Set();
+    const testFiles = new Set();
+    for (const n of allFileNodes) {
+      if (isTestFile(n.file)) {
+        testFileIds.add(n.id);
+        testFiles.add(n.file);
+      }
+    }
+    // Also collect non-file node IDs that belong to test files
+    const allNodes = db.prepare('SELECT id, file FROM nodes').all();
+    for (const n of allNodes) {
+      if (testFiles.has(n.file)) testFileIds.add(n.id);
+    }
+  }
 
   // Node breakdown by kind
-  const nodeRows = db.prepare('SELECT kind, COUNT(*) as c FROM nodes GROUP BY kind').all();
+  let nodeRows;
+  if (noTests) {
+    const allNodes = db.prepare('SELECT id, kind, file FROM nodes').all();
+    const filtered = allNodes.filter((n) => !testFileIds.has(n.id));
+    const counts = {};
+    for (const n of filtered) counts[n.kind] = (counts[n.kind] || 0) + 1;
+    nodeRows = Object.entries(counts).map(([kind, c]) => ({ kind, c }));
+  } else {
+    nodeRows = db.prepare('SELECT kind, COUNT(*) as c FROM nodes GROUP BY kind').all();
+  }
   const nodesByKind = {};
   let totalNodes = 0;
   for (const r of nodeRows) {
@@ -741,7 +777,18 @@ export function statsData(customDbPath) {
   }
 
   // Edge breakdown by kind
-  const edgeRows = db.prepare('SELECT kind, COUNT(*) as c FROM edges GROUP BY kind').all();
+  let edgeRows;
+  if (noTests) {
+    const allEdges = db.prepare('SELECT source_id, target_id, kind FROM edges').all();
+    const filtered = allEdges.filter(
+      (e) => !testFileIds.has(e.source_id) && !testFileIds.has(e.target_id),
+    );
+    const counts = {};
+    for (const e of filtered) counts[e.kind] = (counts[e.kind] || 0) + 1;
+    edgeRows = Object.entries(counts).map(([kind, c]) => ({ kind, c }));
+  } else {
+    edgeRows = db.prepare('SELECT kind, COUNT(*) as c FROM edges GROUP BY kind').all();
+  }
   const edgesByKind = {};
   let totalEdges = 0;
   for (const r of edgeRows) {
@@ -756,7 +803,8 @@ export function statsData(customDbPath) {
       extToLang.set(ext, entry.id);
     }
   }
-  const fileNodes = db.prepare("SELECT file FROM nodes WHERE kind = 'file'").all();
+  let fileNodes = db.prepare("SELECT file FROM nodes WHERE kind = 'file'").all();
+  if (noTests) fileNodes = fileNodes.filter((n) => !isTestFile(n.file));
   const byLanguage = {};
   for (const row of fileNodes) {
     const ext = path.extname(row.file).toLowerCase();
@@ -766,23 +814,30 @@ export function statsData(customDbPath) {
   const langCount = Object.keys(byLanguage).length;
 
   // Cycles
-  const fileCycles = findCycles(db, { fileLevel: true });
-  const fnCycles = findCycles(db, { fileLevel: false });
+  const fileCycles = findCycles(db, { fileLevel: true, noTests });
+  const fnCycles = findCycles(db, { fileLevel: false, noTests });
 
   // Top 5 coupling hotspots (fan-in + fan-out, file nodes)
+  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 hotspotRows = db
     .prepare(`
     SELECT n.file,
       (SELECT COUNT(*) FROM edges WHERE target_id = n.id) as fan_in,
       (SELECT COUNT(*) FROM edges WHERE source_id = n.id) as fan_out
     FROM nodes n
-    WHERE n.kind = 'file'
+    WHERE n.kind = 'file' ${testFilter}
     ORDER BY (SELECT COUNT(*) FROM edges WHERE target_id = n.id)
            + (SELECT COUNT(*) FROM edges WHERE source_id = n.id) DESC
-    LIMIT 5
   `)
     .all();
-  const hotspots = hotspotRows.map((r) => ({
+  const filteredHotspots = noTests ? hotspotRows.filter((r) => !isTestFile(r.file)) : hotspotRows;
+  const hotspots = filteredHotspots.slice(0, 5).map((r) => ({
     file: r.file,
     fanIn: r.fan_in,
     fanOut: r.fan_out,
@@ -808,14 +863,17 @@ export function statsData(customDbPath) {
   }
 
   // Graph quality metrics
+  const qualityTestFilter = testFilter.replace(/n\.file/g, 'file');
   const totalCallable = db
-    .prepare("SELECT COUNT(*) as c FROM nodes WHERE kind IN ('function', 'method')")
+    .prepare(
+      `SELECT COUNT(*) as c FROM nodes WHERE kind IN ('function', 'method') ${qualityTestFilter}`,
+    )
     .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')
+      WHERE e.kind = 'calls' AND n.kind IN ('function', 'method') ${testFilter}
     `)
     .get().c;
   const callerCoverage = totalCallable > 0 ? callableWithCallers / totalCallable : 0;
@@ -881,7 +939,7 @@ export function statsData(customDbPath) {
 }
 
 export function stats(customDbPath, opts = {}) {
-  const data = statsData(customDbPath);
+  const data = statsData(customDbPath, { noTests: opts.noTests });
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2));
     return;
@@ -979,7 +1037,7 @@ export function stats(customDbPath, opts = {}) {
 // ─── Human-readable output (original formatting) ───────────────────────
 
 export function queryName(name, customDbPath, opts = {}) {
-  const data = queryNameData(name, customDbPath);
+  const data = queryNameData(name, customDbPath, { noTests: opts.noTests });
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2));
     return;

package/src/structure.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { normalizePath } from './constants.js';
 import { openReadonlyOrFail } from './db.js';
 import { debug } from './logger.js';
+import { isTestFile } from './queries.js';
 
 // ─── Build-time: insert directory nodes, contains edges, and metrics ────
 
@@ -233,6 +234,7 @@ export function structureData(customDbPath, opts = {}) {
   const filterDir = opts.directory || null;
   const maxDepth = opts.depth || null;
   const sortBy = opts.sort || 'files';
+  const noTests = opts.noTests || false;
 
   // Get all directory nodes with their metrics
   let dirs = db
@@ -263,7 +265,7 @@ export function structureData(customDbPath, opts = {}) {
 
   // Get file metrics for each directory
   const result = dirs.map((d) => {
-    const files = db
+    let files = db
       .prepare(`
         SELECT n.name, nm.line_count, nm.symbol_count, nm.import_count, nm.export_count, nm.fan_in, nm.fan_out
         FROM edges e
@@ -272,6 +274,7 @@ export function structureData(customDbPath, opts = {}) {
         WHERE e.source_id = ? AND e.kind = 'contains' AND n.kind = 'file'
       `)
       .all(d.id);
+    if (noTests) files = files.filter((f) => !isTestFile(f.name));
 
     const subdirs = db
       .prepare(`
@@ -282,14 +285,15 @@ export function structureData(customDbPath, opts = {}) {
       `)
       .all(d.id);
 
+    const fileCount = noTests ? files.length : d.file_count || 0;
     return {
       directory: d.name,
-      fileCount: d.file_count || 0,
+      fileCount,
       symbolCount: d.symbol_count || 0,
       fanIn: d.fan_in || 0,
       fanOut: d.fan_out || 0,
       cohesion: d.cohesion,
-      density: d.file_count > 0 ? (d.symbol_count || 0) / d.file_count : 0,
+      density: fileCount > 0 ? (d.symbol_count || 0) / fileCount : 0,
       files: files.map((f) => ({
         file: f.name,
         lineCount: f.line_count || 0,