@optave/codegraph 2.2.2-dev.c252ef9 → 2.3.0

package/README.md

@@ -373,7 +373,7 @@ Codegraph also extracts symbols from common callback patterns: Commander `.comma
 
 ## 📊 Performance
 
-Self-measured on every release via CI ([full history](generated/BENCHMARKS.md)):
+Self-measured on every release via CI ([build benchmarks](generated/BUILD-BENCHMARKS.md) | [embedding benchmarks](generated/EMBEDDING-BENCHMARKS.md)):
 
 | Metric | Latest |
 |---|---|
@@ -384,6 +384,20 @@ Self-measured on every release via CI ([full history](generated/BENCHMARKS.md)):
 
 Metrics are normalized per file for cross-version comparability. Times above are for a full initial build — incremental rebuilds only re-parse changed files.
 
+### Lightweight Footprint
+
+<a href="https://www.npmjs.com/package/@optave/codegraph"><img src="https://img.shields.io/npm/unpacked-size/@optave/codegraph?style=flat-square&label=unpacked%20size" alt="npm unpacked size" /></a>
+
+Only **3 runtime dependencies** — everything else is optional or a devDependency:
+
+| Dependency | What it does | | |
+|---|---|---|---|
+| [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) | Fast, synchronous SQLite driver | ![GitHub stars](https://img.shields.io/github/stars/WiseLibs/better-sqlite3?style=flat-square&label=%E2%AD%90) | ![npm downloads](https://img.shields.io/npm/dw/better-sqlite3?style=flat-square&label=%F0%9F%93%A5%2Fwk) |
+| [commander](https://github.com/tj/commander.js) | CLI argument parsing | ![GitHub stars](https://img.shields.io/github/stars/tj/commander.js?style=flat-square&label=%E2%AD%90) | ![npm downloads](https://img.shields.io/npm/dw/commander?style=flat-square&label=%F0%9F%93%A5%2Fwk) |
+| [web-tree-sitter](https://github.com/tree-sitter/tree-sitter) | WASM tree-sitter bindings | ![GitHub stars](https://img.shields.io/github/stars/tree-sitter/tree-sitter?style=flat-square&label=%E2%AD%90) | ![npm downloads](https://img.shields.io/npm/dw/web-tree-sitter?style=flat-square&label=%F0%9F%93%A5%2Fwk) |
+
+Optional: `@huggingface/transformers` (semantic search), `@modelcontextprotocol/sdk` (MCP server) — lazy-loaded only when needed.
+
 ## 🤖 AI Agent Integration
 
 ### MCP Server
@@ -583,15 +597,16 @@ const { results: fused } = await multiSearchData(
 
 ## 🗺️ Roadmap
 
-See **[ROADMAP.md](ROADMAP.md)** for the full development roadmap. Current plan:
+See **[ROADMAP.md](ROADMAP.md)** for the full development roadmap and **[STABILITY.md](STABILITY.md)** for the stability policy and versioning guarantees. Current plan:
 
 1. ~~**Rust Core**~~ — **Complete** (v1.3.0) — native tree-sitter parsing via napi-rs, parallel multi-core parsing, incremental re-parsing, import resolution & cycle detection in Rust
 2. ~~**Foundation Hardening**~~ — **Complete** (v1.4.0) — parser registry, 12-tool MCP server with multi-repo support, test coverage 62%→75%, `apiKeyCommand` secret resolution, global repo registry
-3. **Intelligent Embeddings** — LLM-generated descriptions, hybrid search
-4. **Natural Language Queries** — `codegraph ask` command, conversational sessions
-5. **Expanded Language Support** — 8 new languages (12 → 20)
-6. **GitHub Integration & CI** — reusable GitHub Action, PR review, SARIF output
-7. **Visualization & Advanced** — web UI, dead code detection, monorepo support, agentic search
+3. **Architectural Refactoring** — parser plugin system, repository pattern, pipeline builder, engine strategy, domain errors, curated API
+4. **Intelligent Embeddings** — LLM-generated descriptions, hybrid search
+5. **Natural Language Queries** — `codegraph ask` command, conversational sessions
+6. **Expanded Language Support** — 8 new languages (12 → 20)
+7. **GitHub Integration & CI** — reusable GitHub Action, PR review, SARIF output
+8. **Visualization & Advanced** — web UI, dead code detection, monorepo support, agentic search
 
 ## 🤝 Contributing
 

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@optave/codegraph",
-  "version": "2.2.2-dev.c252ef9",
+  "version": "2.3.0",
   "description": "Local code graph CLI — parse codebases with tree-sitter, build dependency graphs, query them",
   "type": "module",
   "main": "src/index.js",
   "exports": {
     ".": {
       "import": "./src/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "bin": {
     "codegraph": "./src/cli.js"
@@ -61,10 +62,10 @@
   "optionalDependencies": {
     "@huggingface/transformers": "^3.8.1",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@optave/codegraph-darwin-arm64": "2.2.2-dev.c252ef9",
-    "@optave/codegraph-darwin-x64": "2.2.2-dev.c252ef9",
-    "@optave/codegraph-linux-x64-gnu": "2.2.2-dev.c252ef9",
-    "@optave/codegraph-win32-x64-msvc": "2.2.2-dev.c252ef9"
+    "@optave/codegraph-darwin-arm64": "2.3.0",
+    "@optave/codegraph-darwin-x64": "2.3.0",
+    "@optave/codegraph-linux-x64-gnu": "2.3.0",
+    "@optave/codegraph-win32-x64-msvc": "2.3.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.4",

package/src/builder.js

@@ -1,12 +1,11 @@
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { loadConfig } from './config.js';
 import { EXTENSIONS, IGNORE_DIRS, normalizePath } from './constants.js';
 import { initSchema, openDb } from './db.js';
 import { readJournal, writeJournalHeader } from './journal.js';
-import { debug, warn } from './logger.js';
+import { debug, info, warn } from './logger.js';
 import { getActiveEngine, parseFilesAuto } from './parser.js';
 import { computeConfidence, resolveImportPath, resolveImportsBatch } from './resolve.js';
 
@@ -345,7 +344,7 @@ export async function buildGraph(rootDir, opts = {}) {
   // Engine selection: 'native', 'wasm', or 'auto' (default)
   const engineOpts = { engine: opts.engine || 'auto' };
   const { name: engineName, version: engineVersion } = getActiveEngine(engineOpts);
-  console.log(`Using ${engineName} engine${engineVersion ? ` (v${engineVersion})` : ''}`);
+  info(`Using ${engineName} engine${engineVersion ? ` (v${engineVersion})` : ''}`);
 
   const aliases = loadPathAliases(rootDir);
   // Merge config aliases
@@ -358,7 +357,7 @@ export async function buildGraph(rootDir, opts = {}) {
   }
 
   if (aliases.baseUrl || Object.keys(aliases.paths).length > 0) {
-    console.log(
+    info(
       `Loaded path aliases: baseUrl=${aliases.baseUrl || 'none'}, ${Object.keys(aliases.paths).length} path mappings`,
     );
   }
@@ -366,7 +365,7 @@ export async function buildGraph(rootDir, opts = {}) {
   const collected = collectFiles(rootDir, [], config, new Set());
   const files = collected.files;
   const discoveredDirs = collected.directories;
-  console.log(`Found ${files.length} files to parse`);
+  info(`Found ${files.length} files to parse`);
 
   // Check for incremental build
   const { changed, removed, isFullBuild } = incremental
@@ -397,19 +396,36 @@ export async function buildGraph(rootDir, opts = {}) {
         /* ignore heal errors */
       }
     }
-    console.log('No changes detected. Graph is up to date.');
+    info('No changes detected. Graph is up to date.');
     db.close();
     writeJournalHeader(rootDir, Date.now());
     return;
   }
 
+  // Check if embeddings table exists (created by `embed`, not by initSchema)
+  let hasEmbeddings = false;
+  try {
+    db.prepare('SELECT 1 FROM embeddings LIMIT 1').get();
+    hasEmbeddings = true;
+  } catch {
+    /* table doesn't exist */
+  }
+
   if (isFullBuild) {
+    const deletions =
+      'PRAGMA foreign_keys = OFF; DELETE FROM node_metrics; DELETE FROM edges; DELETE FROM nodes; PRAGMA foreign_keys = ON;';
     db.exec(
-      'PRAGMA foreign_keys = OFF; DELETE FROM node_metrics; DELETE FROM edges; DELETE FROM nodes; PRAGMA foreign_keys = ON;',
+      hasEmbeddings
+        ? `${deletions.replace('PRAGMA foreign_keys = ON;', '')} DELETE FROM embeddings; PRAGMA foreign_keys = ON;`
+        : deletions,
     );
   } else {
-    console.log(`Incremental: ${parseChanges.length} changed, ${removed.length} removed`);
-    // Remove metrics/edges/nodes for changed and removed files
+    info(`Incremental: ${parseChanges.length} changed, ${removed.length} removed`);
+    // Remove embeddings/metrics/edges/nodes for changed and removed files
+    // Embeddings must be deleted BEFORE nodes (we need node IDs to find them)
+    const deleteEmbeddingsForFile = hasEmbeddings
+      ? db.prepare('DELETE FROM embeddings WHERE node_id IN (SELECT id FROM nodes WHERE file = ?)')
+      : null;
     const deleteNodesForFile = db.prepare('DELETE FROM nodes WHERE file = ?');
     const deleteEdgesForFile = db.prepare(`
       DELETE FROM edges WHERE source_id IN (SELECT id FROM nodes WHERE file = @f)
@@ -419,12 +435,14 @@ export async function buildGraph(rootDir, opts = {}) {
       'DELETE FROM node_metrics WHERE node_id IN (SELECT id FROM nodes WHERE file = ?)',
     );
     for (const relPath of removed) {
+      deleteEmbeddingsForFile?.run(relPath);
       deleteEdgesForFile.run({ f: relPath });
       deleteMetricsForFile.run(relPath);
       deleteNodesForFile.run(relPath);
     }
     for (const item of parseChanges) {
       const relPath = item.relPath || normalizePath(path.relative(rootDir, item.file));
+      deleteEmbeddingsForFile?.run(relPath);
       deleteEdgesForFile.run({ f: relPath });
       deleteMetricsForFile.run(relPath);
       deleteNodesForFile.run(relPath);
@@ -528,7 +546,7 @@ export async function buildGraph(rootDir, opts = {}) {
 
   const parsed = allSymbols.size;
   const skipped = filesToParse.length - parsed;
-  console.log(`Parsed ${parsed} files (${skipped} skipped)`);
+  info(`Parsed ${parsed} files (${skipped} skipped)`);
 
   // Clean up removed file hashes
   if (upsertHash && removed.length > 0) {
@@ -822,15 +840,33 @@ export async function buildGraph(rootDir, opts = {}) {
   }
 
   const nodeCount = db.prepare('SELECT COUNT(*) as c FROM nodes').get().c;
-  console.log(`Graph built: ${nodeCount} nodes, ${edgeCount} edges`);
-  console.log(`Stored in ${dbPath}`);
+  info(`Graph built: ${nodeCount} nodes, ${edgeCount} edges`);
+  info(`Stored in ${dbPath}`);
+
+  // Warn about orphaned embeddings that no longer match any node
+  if (hasEmbeddings) {
+    try {
+      const orphaned = db
+        .prepare('SELECT COUNT(*) as c FROM embeddings WHERE node_id NOT IN (SELECT id FROM nodes)')
+        .get().c;
+      if (orphaned > 0) {
+        warn(
+          `${orphaned} embeddings are orphaned (nodes changed). Run "codegraph embed" to refresh.`,
+        );
+      }
+    } catch {
+      /* ignore — embeddings table may have been dropped */
+    }
+  }
+
   db.close();
 
   // Write journal header after successful build
   writeJournalHeader(rootDir, Date.now());
 
   if (!opts.skipRegistry) {
-    const tmpDir = path.resolve(os.tmpdir());
+    const { tmpdir } = await import('node:os');
+    const tmpDir = path.resolve(tmpdir());
     const resolvedRoot = path.resolve(rootDir);
     if (resolvedRoot.startsWith(tmpDir)) {
       debug(`Skipping auto-registration for temp directory: ${resolvedRoot}`);

package/src/cli.js

@@ -2,12 +2,12 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import Database from 'better-sqlite3';
 import { Command } from 'commander';
 import { buildGraph } from './builder.js';
+import { loadConfig } from './config.js';
 import { findCycles, formatCycles } from './cycles.js';
-import { findDbPath } from './db.js';
-import { buildEmbeddings, MODELS, search } from './embedder.js';
+import { openReadonlyOrFail } from './db.js';
+import { buildEmbeddings, EMBEDDING_STRATEGIES, MODELS, search } from './embedder.js';
 import { exportDOT, exportJSON, exportMermaid } from './export.js';
 import { setVerbose } from './logger.js';
 import {
@@ -36,6 +36,8 @@ import { watchProject } from './watcher.js';
 const __cliDir = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/i, '$1'));
 const pkg = JSON.parse(fs.readFileSync(path.join(__cliDir, '..', 'package.json'), 'utf-8'));
 
+const config = loadConfig(process.cwd());
+
 const program = new Command();
 program
   .name('codegraph')
@@ -48,6 +50,18 @@ program
     if (opts.verbose) setVerbose(true);
   });
 
+/**
+ * Resolve the effective noTests value: CLI flag > config > false.
+ * Commander sets opts.tests to false when --no-tests is passed.
+ * When --include-tests is passed, always return false (include tests).
+ * Otherwise, fall back to config.query.excludeTests.
+ */
+function resolveNoTests(opts) {
+  if (opts.includeTests) return false;
+  if (opts.tests === false) return true;
+  return config.query?.excludeTests || false;
+}
+
 program
   .command('build [dir]')
   .description('Parse repo and build graph in .codegraph/graph.db')
@@ -63,9 +77,10 @@ program
   .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('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
   .action((name, opts) => {
-    queryName(name, opts.db, { noTests: !opts.tests, json: opts.json });
+    queryName(name, opts.db, { noTests: resolveNoTests(opts), json: opts.json });
   });
 
 program
@@ -73,9 +88,10 @@ program
   .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('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
   .action((file, opts) => {
-    impactAnalysis(file, opts.db, { noTests: !opts.tests, json: opts.json });
+    impactAnalysis(file, opts.db, { noTests: resolveNoTests(opts), json: opts.json });
   });
 
 program
@@ -84,9 +100,13 @@ program
   .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('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
   .action((opts) => {
-    moduleMap(opts.db, parseInt(opts.limit, 10), { noTests: !opts.tests, json: opts.json });
+    moduleMap(opts.db, parseInt(opts.limit, 10), {
+      noTests: resolveNoTests(opts),
+      json: opts.json,
+    });
   });
 
 program
@@ -94,9 +114,10 @@ program
   .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('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
   .action((opts) => {
-    stats(opts.db, { noTests: !opts.tests, json: opts.json });
+    stats(opts.db, { noTests: resolveNoTests(opts), json: opts.json });
   });
 
 program
@@ -104,9 +125,10 @@ program
   .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('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
   .action((file, opts) => {
-    fileDeps(file, opts.db, { noTests: !opts.tests, json: opts.json });
+    fileDeps(file, opts.db, { noTests: resolveNoTests(opts), json: opts.json });
   });
 
 program
@@ -117,6 +139,7 @@ program
   .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('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
   .action((name, opts) => {
     if (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
@@ -127,7 +150,7 @@ program
       depth: parseInt(opts.depth, 10),
       file: opts.file,
       kind: opts.kind,
-      noTests: !opts.tests,
+      noTests: resolveNoTests(opts),
       json: opts.json,
     });
   });
@@ -140,6 +163,7 @@ program
   .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('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
   .action((name, opts) => {
     if (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
@@ -150,7 +174,7 @@ program
       depth: parseInt(opts.depth, 10),
       file: opts.file,
       kind: opts.kind,
-      noTests: !opts.tests,
+      noTests: resolveNoTests(opts),
       json: opts.json,
     });
   });
@@ -163,8 +187,9 @@ program
   .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('--with-test-source', 'Include test source code')
   .option('-T, --no-tests', 'Exclude test/spec files from results')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
   .action((name, opts) => {
     if (opts.kind && !ALL_SYMBOL_KINDS.includes(opts.kind)) {
@@ -176,8 +201,8 @@ program
       file: opts.file,
       kind: opts.kind,
       noSource: !opts.source,
-      noTests: !opts.tests,
-      includeTests: opts.includeTests,
+      noTests: resolveNoTests(opts),
+      includeTests: opts.withTestSource,
       json: opts.json,
     });
   });
@@ -186,10 +211,16 @@ program
   .command('explain <target>')
   .description('Structural summary of a file or function (no LLM needed)')
   .option('-d, --db <path>', 'Path to graph.db')
+  .option('--depth <n>', 'Recursively explain dependencies up to N levels deep', '0')
   .option('-T, --no-tests', 'Exclude test/spec files from results')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
   .action((target, opts) => {
-    explain(target, opts.db, { noTests: !opts.tests, json: opts.json });
+    explain(target, opts.db, {
+      depth: parseInt(opts.depth, 10),
+      noTests: resolveNoTests(opts),
+      json: opts.json,
+    });
   });
 
 program
@@ -198,6 +229,7 @@ program
   .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 from results')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
   .action((name, opts) => {
     if (!name && !opts.file) {
@@ -205,7 +237,7 @@ program
       process.exit(1);
     }
     const target = opts.file || name;
-    where(target, opts.db, { file: !!opts.file, noTests: !opts.tests, json: opts.json });
+    where(target, opts.db, { file: !!opts.file, noTests: resolveNoTests(opts), json: opts.json });
   });
 
 program
@@ -215,6 +247,7 @@ program
   .option('--staged', 'Analyze staged changes instead of unstaged')
   .option('--depth <n>', 'Max transitive caller depth', '3')
   .option('-T, --no-tests', 'Exclude test/spec files from results')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
   .option('-f, --format <format>', 'Output format: text, mermaid, json', 'text')
   .action((ref, opts) => {
@@ -222,7 +255,7 @@ program
       ref,
       staged: opts.staged,
       depth: parseInt(opts.depth, 10),
-      noTests: !opts.tests,
+      noTests: resolveNoTests(opts),
       json: opts.json,
       format: opts.format,
     });
@@ -237,10 +270,16 @@ program
   .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('--include-tests', 'Include test/spec files (overrides excludeTests config)')
+  .option('--min-confidence <score>', 'Minimum edge confidence threshold (default: 0.5)', '0.5')
   .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, noTests: !opts.tests };
+    const db = openReadonlyOrFail(opts.db);
+    const exportOpts = {
+      fileLevel: !opts.functions,
+      noTests: resolveNoTests(opts),
+      minConfidence: parseFloat(opts.minConfidence),
+    };
 
     let output;
     switch (opts.format) {
@@ -271,10 +310,11 @@ program
   .option('-d, --db <path>', 'Path to graph.db')
   .option('--functions', 'Function-level cycle detection')
   .option('-T, --no-tests', 'Exclude test/spec files')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
   .action((opts) => {
-    const db = new Database(findDbPath(opts.db), { readonly: true });
-    const cycles = findCycles(db, { fileLevel: !opts.functions, noTests: !opts.tests });
+    const db = openReadonlyOrFail(opts.db);
+    const cycles = findCycles(db, { fileLevel: !opts.functions, noTests: resolveNoTests(opts) });
     db.close();
 
     if (opts.json) {
@@ -376,10 +416,13 @@ program
   .action(() => {
     console.log('\nAvailable embedding models:\n');
     for (const [key, config] of Object.entries(MODELS)) {
-      const def = key === 'nomic-v1.5' ? ' (default)' : '';
-      console.log(`  ${key.padEnd(12)} ${String(config.dim).padStart(4)}d  ${config.desc}${def}`);
+      const def = key === 'minilm' ? ' (default)' : '';
+      const ctx = config.contextWindow ? `${config.contextWindow} ctx` : '';
+      console.log(
+        `  ${key.padEnd(12)} ${String(config.dim).padStart(4)}d  ${ctx.padEnd(9)} ${config.desc}${def}`,
+      );
     }
-    console.log('\nUsage: codegraph embed --model <name>');
+    console.log('\nUsage: codegraph embed --model <name> --strategy <structured|source>');
     console.log('       codegraph search "query" --model <name>\n');
   });
 
@@ -390,12 +433,23 @@ program
   )
   .option(
     '-m, --model <name>',
-    'Embedding model: minilm, jina-small, jina-base, jina-code, nomic, nomic-v1.5 (default), bge-large. Run `codegraph models` for details',
-    'nomic-v1.5',
+    'Embedding model: minilm (default), jina-small, jina-base, jina-code, nomic, nomic-v1.5, bge-large. Run `codegraph models` for details',
+    'minilm',
+  )
+  .option(
+    '-s, --strategy <name>',
+    `Embedding strategy: ${EMBEDDING_STRATEGIES.join(', ')}. "structured" uses graph context (callers/callees), "source" embeds raw code`,
+    'structured',
   )
   .action(async (dir, opts) => {
+    if (!EMBEDDING_STRATEGIES.includes(opts.strategy)) {
+      console.error(
+        `Unknown strategy: ${opts.strategy}. Available: ${EMBEDDING_STRATEGIES.join(', ')}`,
+      );
+      process.exit(1);
+    }
     const root = path.resolve(dir || '.');
-    await buildEmbeddings(root, opts.model);
+    await buildEmbeddings(root, opts.model, undefined, { strategy: opts.strategy });
   });
 
 program
@@ -405,6 +459,7 @@ program
   .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 from results')
+  .option('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .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')
@@ -412,7 +467,7 @@ program
   .action(async (query, opts) => {
     await search(query, opts.db, {
       limit: parseInt(opts.limit, 10),
-      noTests: !opts.tests,
+      noTests: resolveNoTests(opts),
       minScore: parseFloat(opts.minScore),
       model: opts.model,
       kind: opts.kind,
@@ -430,6 +485,7 @@ program
   .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('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
   .action(async (dir, opts) => {
     const { structureData, formatStructure } = await import('./structure.js');
@@ -437,7 +493,7 @@ program
       directory: dir,
       depth: opts.depth ? parseInt(opts.depth, 10) : undefined,
       sort: opts.sort,
-      noTests: !opts.tests,
+      noTests: resolveNoTests(opts),
     });
     if (opts.json) {
       console.log(JSON.stringify(data, null, 2));
@@ -456,6 +512,7 @@ program
   .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('--include-tests', 'Include test/spec files (overrides excludeTests config)')
   .option('-j, --json', 'Output as JSON')
   .action(async (opts) => {
     const { hotspotsData, formatHotspots } = await import('./structure.js');
@@ -463,7 +520,7 @@ program
       metric: opts.metric,
       level: opts.level,
       limit: parseInt(opts.limit, 10),
-      noTests: !opts.tests,
+      noTests: resolveNoTests(opts),
     });
     if (opts.json) {
       console.log(JSON.stringify(data, null, 2));

package/src/config.js

@@ -18,6 +18,7 @@ export const DEFAULTS = {
   query: {
     defaultDepth: 3,
     defaultLimit: 20,
+    excludeTests: false,
   },
   embeddings: { model: 'nomic-v1.5', llmProvider: null },
   llm: { provider: null, model: null, baseUrl: null, apiKey: null, apiKeyCommand: null },

package/src/embedder.js

@@ -4,6 +4,18 @@ import Database from 'better-sqlite3';
 import { findDbPath, openReadonlyOrFail } from './db.js';
 import { warn } from './logger.js';
 
+/**
+ * Split an identifier into readable words.
+ * camelCase/PascalCase → "camel Case", snake_case → "snake case", kebab-case → "kebab case"
+ */
+function splitIdentifier(name) {
+  return name
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .replace(/[_-]+/g, ' ')
+    .trim();
+}
+
 // Lazy-load transformers (heavy, optional module)
 let pipeline = null;
 let _cos_sim = null;
@@ -14,48 +26,57 @@ export const MODELS = {
   minilm: {
     name: 'Xenova/all-MiniLM-L6-v2',
     dim: 384,
+    contextWindow: 256,
     desc: 'Smallest, fastest (~23MB). General text.',
     quantized: true,
   },
   'jina-small': {
     name: 'Xenova/jina-embeddings-v2-small-en',
     dim: 512,
+    contextWindow: 8192,
     desc: 'Small, good quality (~33MB). General text.',
     quantized: false,
   },
   'jina-base': {
     name: 'Xenova/jina-embeddings-v2-base-en',
     dim: 768,
+    contextWindow: 8192,
     desc: 'Good quality (~137MB). General text, 8192 token context.',
     quantized: false,
   },
   'jina-code': {
     name: 'Xenova/jina-embeddings-v2-base-code',
     dim: 768,
+    contextWindow: 8192,
     desc: 'Code-aware (~137MB). Trained on code+text, best for code search.',
     quantized: false,
   },
   nomic: {
     name: 'Xenova/nomic-embed-text-v1',
     dim: 768,
+    contextWindow: 8192,
     desc: 'Good local quality (~137MB). 8192 context.',
     quantized: false,
   },
   'nomic-v1.5': {
     name: 'nomic-ai/nomic-embed-text-v1.5',
     dim: 768,
+    contextWindow: 8192,
     desc: 'Improved nomic (~137MB). Matryoshka dimensions, 8192 context.',
     quantized: false,
   },
   'bge-large': {
     name: 'Xenova/bge-large-en-v1.5',
     dim: 1024,
+    contextWindow: 512,
     desc: 'Best general retrieval (~335MB). Top MTEB scores.',
     quantized: false,
   },
 };
 
-export const DEFAULT_MODEL = 'nomic-v1.5';
+export const EMBEDDING_STRATEGIES = ['structured', 'source'];
+
+export const DEFAULT_MODEL = 'minilm';
 const BATCH_SIZE_MAP = {
   minilm: 32,
   'jina-small': 16,
@@ -77,6 +98,108 @@ function getModelConfig(modelKey) {
   return config;
 }
 
+/**
+ * Rough token estimate (~4 chars per token for code/English).
+ * Conservative — avoids adding a tokenizer dependency.
+ */
+export function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+
+/**
+ * Extract leading comment text (JSDoc, //, #, etc.) above a function line.
+ * Returns the cleaned comment text or null if none found.
+ */
+function extractLeadingComment(lines, fnLineIndex) {
+  const raw = [];
+  for (let i = fnLineIndex - 1; i >= Math.max(0, fnLineIndex - 15); i--) {
+    const trimmed = lines[i].trim();
+    if (/^(\/\/|\/\*|\*\/|\*|#|\/\/\/)/.test(trimmed)) {
+      raw.unshift(trimmed);
+    } else if (trimmed === '') {
+      if (raw.length > 0) break;
+    } else {
+      break;
+    }
+  }
+  if (raw.length === 0) return null;
+  return raw
+    .map((line) =>
+      line
+        .replace(/^\/\*\*?\s?|\*\/$/g, '') // opening /** or /* and closing */
+        .replace(/^\*\s?/, '') // middle * lines
+        .replace(/^\/\/\/?\s?/, '') // // or ///
+        .replace(/^#\s?/, '') // # (Python/Ruby)
+        .trim(),
+    )
+    .filter((l) => l.length > 0)
+    .join(' ');
+}
+
+/**
+ * Build graph-enriched text for a symbol using dependency context.
+ * Produces compact, semantic text (~100 tokens) instead of full source code.
+ */
+function buildStructuredText(node, file, lines, calleesStmt, callersStmt) {
+  const readable = splitIdentifier(node.name);
+  const parts = [`${node.kind} ${node.name} (${readable}) in ${file}`];
+  const startLine = Math.max(0, node.line - 1);
+
+  // Extract parameters from signature (best-effort, single-line)
+  const sigLine = lines[startLine] || '';
+  const paramMatch = sigLine.match(/\(([^)]*)\)/);
+  if (paramMatch?.[1]?.trim()) {
+    parts.push(`Parameters: ${paramMatch[1].trim()}`);
+  }
+
+  // Graph context: callees (capped at 10)
+  const callees = calleesStmt.all(node.id);
+  if (callees.length > 0) {
+    parts.push(
+      `Calls: ${callees
+        .slice(0, 10)
+        .map((c) => c.name)
+        .join(', ')}`,
+    );
+  }
+
+  // Graph context: callers (capped at 10)
+  const callers = callersStmt.all(node.id);
+  if (callers.length > 0) {
+    parts.push(
+      `Called by: ${callers
+        .slice(0, 10)
+        .map((c) => c.name)
+        .join(', ')}`,
+    );
+  }
+
+  // Leading comment (high semantic value) or first few lines of code
+  const comment = extractLeadingComment(lines, startLine);
+  if (comment) {
+    parts.push(comment);
+  } else {
+    const endLine = Math.min(lines.length, startLine + 4);
+    const snippet = lines.slice(startLine, endLine).join('\n').trim();
+    if (snippet) parts.push(snippet);
+  }
+
+  return parts.join('\n');
+}
+
+/**
+ * Build raw source-code text for a symbol (original strategy).
+ */
+function buildSourceText(node, file, lines) {
+  const startLine = Math.max(0, node.line - 1);
+  const endLine = node.end_line
+    ? Math.min(lines.length, node.end_line)
+    : Math.min(lines.length, startLine + 15);
+  const context = lines.slice(startLine, endLine).join('\n');
+  const readable = splitIdentifier(node.name);
+  return `${node.kind} ${node.name} (${readable}) in ${file}\n${context}`;
+}
+
 /**
  * Lazy-load @huggingface/transformers.
  * This is an optional dependency — gives a clear error if not installed.
@@ -103,8 +226,27 @@ async function loadModel(modelKey) {
   _cos_sim = transformers.cos_sim;
 
   console.log(`Loading embedding model: ${config.name} (${config.dim}d)...`);
-  const opts = config.quantized ? { quantized: true } : {};
-  extractor = await pipeline('feature-extraction', config.name, opts);
+  const pipelineOpts = config.quantized ? { quantized: true } : {};
+  try {
+    extractor = await pipeline('feature-extraction', config.name, pipelineOpts);
+  } catch (err) {
+    const msg = err.message || String(err);
+    if (msg.includes('Unauthorized') || msg.includes('401') || msg.includes('gated')) {
+      console.error(
+        `\nModel "${config.name}" requires authentication.\n` +
+          `This model is gated on HuggingFace and needs an access token.\n\n` +
+          `Options:\n` +
+          `  1. Set HF_TOKEN env var: export HF_TOKEN=hf_...\n` +
+          `  2. Use a public model instead: codegraph embed --model minilm\n`,
+      );
+    } else {
+      console.error(
+        `\nFailed to load model "${config.name}": ${msg}\n` +
+          `Try a different model: codegraph embed --model minilm\n`,
+      );
+    }
+    process.exit(1);
+  }
   activeModel = config.name;
   console.log('Model loaded.');
   return { extractor, config };
@@ -172,12 +314,24 @@ function initEmbeddingsSchema(db) {
 
 /**
  * Build embeddings for all functions/methods/classes in the graph.
+ * @param {string} rootDir - Project root directory
+ * @param {string} modelKey - Model identifier from MODELS registry
+ * @param {string} [customDbPath] - Override path to graph.db
+ * @param {object} [options] - Embedding options
+ * @param {string} [options.strategy='structured'] - 'structured' (graph-enriched) or 'source' (raw code)
  */
-export async function buildEmbeddings(rootDir, modelKey, customDbPath) {
-  // path already imported at top
-  // fs already imported at top
+export async function buildEmbeddings(rootDir, modelKey, customDbPath, options = {}) {
+  const strategy = options.strategy || 'structured';
   const dbPath = customDbPath || findDbPath(null);
 
+  if (!fs.existsSync(dbPath)) {
+    console.error(
+      `No codegraph database found at ${dbPath}.\n` +
+        `Run "codegraph build" first to analyze your codebase.`,
+    );
+    process.exit(1);
+  }
+
   const db = new Database(dbPath);
   initEmbeddingsSchema(db);
 
@@ -190,7 +344,24 @@ export async function buildEmbeddings(rootDir, modelKey, customDbPath) {
     )
     .all();
 
-  console.log(`Building embeddings for ${nodes.length} symbols...`);
+  console.log(`Building embeddings for ${nodes.length} symbols (strategy: ${strategy})...`);
+
+  // Prepare graph-context queries for structured strategy
+  let calleesStmt, callersStmt;
+  if (strategy === 'structured') {
+    calleesStmt = db.prepare(`
+      SELECT DISTINCT n.name FROM edges e
+      JOIN nodes n ON e.target_id = n.id
+      WHERE e.source_id = ? AND e.kind = 'calls'
+      ORDER BY n.name
+    `);
+    callersStmt = db.prepare(`
+      SELECT DISTINCT n.name FROM edges e
+      JOIN nodes n ON e.source_id = n.id
+      WHERE e.target_id = ? AND e.kind = 'calls'
+      ORDER BY n.name
+    `);
+  }
 
   const byFile = new Map();
   for (const node of nodes) {
@@ -201,6 +372,9 @@ export async function buildEmbeddings(rootDir, modelKey, customDbPath) {
   const texts = [];
   const nodeIds = [];
   const previews = [];
+  const config = getModelConfig(modelKey);
+  const contextWindow = config.contextWindow;
+  let overflowCount = 0;
 
   for (const [file, fileNodes] of byFile) {
     const fullPath = path.join(rootDir, file);
@@ -213,19 +387,31 @@ export async function buildEmbeddings(rootDir, modelKey, customDbPath) {
     }
 
     for (const node of fileNodes) {
-      const startLine = Math.max(0, node.line - 1);
-      const endLine = node.end_line
-        ? Math.min(lines.length, node.end_line)
-        : Math.min(lines.length, startLine + 15);
-      const context = lines.slice(startLine, endLine).join('\n');
+      let text =
+        strategy === 'structured'
+          ? buildStructuredText(node, file, lines, calleesStmt, callersStmt)
+          : buildSourceText(node, file, lines);
+
+      // Detect and handle context window overflow
+      const tokens = estimateTokens(text);
+      if (tokens > contextWindow) {
+        overflowCount++;
+        const maxChars = contextWindow * 4;
+        text = text.slice(0, maxChars);
+      }
 
-      const text = `${node.kind} ${node.name} in ${file}\n${context}`;
       texts.push(text);
       nodeIds.push(node.id);
       previews.push(`${node.name} (${node.kind}) -- ${file}:${node.line}`);
     }
   }
 
+  if (overflowCount > 0) {
+    warn(
+      `${overflowCount} symbol(s) exceeded model context window (${contextWindow} tokens) and were truncated`,
+    );
+  }
+
   console.log(`Embedding ${texts.length} symbols...`);
   const { vectors, dim } = await embed(texts, modelKey);
 
@@ -237,16 +423,19 @@ export async function buildEmbeddings(rootDir, modelKey, customDbPath) {
     for (let i = 0; i < vectors.length; i++) {
       insert.run(nodeIds[i], Buffer.from(vectors[i].buffer), previews[i]);
     }
-    const config = getModelConfig(modelKey);
     insertMeta.run('model', config.name);
     insertMeta.run('dim', String(dim));
     insertMeta.run('count', String(vectors.length));
+    insertMeta.run('strategy', strategy);
     insertMeta.run('built_at', new Date().toISOString());
+    if (overflowCount > 0) {
+      insertMeta.run('truncated_count', String(overflowCount));
+    }
   });
   insertAll();
 
   console.log(
-    `\nStored ${vectors.length} embeddings (${dim}d, ${getModelConfig(modelKey).name}) in graph.db`,
+    `\nStored ${vectors.length} embeddings (${dim}d, ${config.name}, strategy: ${strategy}) in graph.db`,
   );
   db.close();
 }

package/src/export.js

@@ -1,12 +1,15 @@
 import path from 'node:path';
 import { isTestFile } from './queries.js';
 
+const DEFAULT_MIN_CONFIDENCE = 0.5;
+
 /**
  * Export the dependency graph in DOT (Graphviz) format.
  */
 export function exportDOT(db, opts = {}) {
   const fileLevel = opts.fileLevel !== false;
   const noTests = opts.noTests || false;
+  const minConf = opts.minConfidence ?? DEFAULT_MIN_CONFIDENCE;
   const lines = [
     'digraph codegraph {',
     '  rankdir=LR;',
@@ -23,8 +26,9 @@ export function exportDOT(db, opts = {}) {
       JOIN nodes n1 ON e.source_id = n1.id
       JOIN nodes n2 ON e.target_id = n2.id
       WHERE n1.file != n2.file AND e.kind IN ('imports', 'imports-type', 'calls')
+        AND e.confidence >= ?
     `)
-      .all();
+      .all(minConf);
     if (noTests) edges = edges.filter((e) => !isTestFile(e.source) && !isTestFile(e.target));
 
     // Try to use directory nodes from DB (built by structure analysis)
@@ -102,8 +106,9 @@ export function exportDOT(db, opts = {}) {
       JOIN nodes n2 ON e.target_id = n2.id
       WHERE n1.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module') AND n2.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module')
       AND e.kind = 'calls'
+      AND e.confidence >= ?
     `)
-      .all();
+      .all(minConf);
     if (noTests)
       edges = edges.filter((e) => !isTestFile(e.source_file) && !isTestFile(e.target_file));
 
@@ -126,6 +131,7 @@ export function exportDOT(db, opts = {}) {
 export function exportMermaid(db, opts = {}) {
   const fileLevel = opts.fileLevel !== false;
   const noTests = opts.noTests || false;
+  const minConf = opts.minConfidence ?? DEFAULT_MIN_CONFIDENCE;
   const lines = ['graph LR'];
 
   if (fileLevel) {
@@ -136,8 +142,9 @@ export function exportMermaid(db, opts = {}) {
       JOIN nodes n1 ON e.source_id = n1.id
       JOIN nodes n2 ON e.target_id = n2.id
       WHERE n1.file != n2.file AND e.kind IN ('imports', 'imports-type', 'calls')
+        AND e.confidence >= ?
     `)
-      .all();
+      .all(minConf);
     if (noTests) edges = edges.filter((e) => !isTestFile(e.source) && !isTestFile(e.target));
 
     for (const { source, target } of edges) {
@@ -155,8 +162,9 @@ export function exportMermaid(db, opts = {}) {
       JOIN nodes n2 ON e.target_id = n2.id
       WHERE n1.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module') AND n2.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module')
       AND e.kind = 'calls'
+      AND e.confidence >= ?
     `)
-      .all();
+      .all(minConf);
     if (noTests)
       edges = edges.filter((e) => !isTestFile(e.source_file) && !isTestFile(e.target_file));
 
@@ -175,6 +183,7 @@ export function exportMermaid(db, opts = {}) {
  */
 export function exportJSON(db, opts = {}) {
   const noTests = opts.noTests || false;
+  const minConf = opts.minConfidence ?? DEFAULT_MIN_CONFIDENCE;
 
   let nodes = db
     .prepare(`
@@ -185,13 +194,13 @@ export function exportJSON(db, opts = {}) {
 
   let edges = db
     .prepare(`
-    SELECT DISTINCT n1.file AS source, n2.file AS target, e.kind
+    SELECT DISTINCT n1.file AS source, n2.file AS target, e.kind, e.confidence
     FROM edges e
     JOIN nodes n1 ON e.source_id = n1.id
     JOIN nodes n2 ON e.target_id = n2.id
-    WHERE n1.file != n2.file
+    WHERE n1.file != n2.file AND e.confidence >= ?
   `)
-    .all();
+    .all(minConf);
   if (noTests) edges = edges.filter((e) => !isTestFile(e.source) && !isTestFile(e.target));
 
   return { nodes, edges };

package/src/index.js

@@ -21,7 +21,9 @@ export {
   buildEmbeddings,
   cosineSim,
   DEFAULT_MODEL,
+  EMBEDDING_STRATEGIES,
   embed,
+  estimateTokens,
   MODELS,
   multiSearchData,
   search,

package/src/queries.js

@@ -334,6 +334,7 @@ export function moduleMapData(customDbPath, limit = 20, opts = {}) {
     dir: path.dirname(n.file) || '.',
     inEdges: n.in_edges,
     outEdges: n.out_edges,
+    coupling: n.in_edges + n.out_edges,
   }));
 
   const totalNodes = db.prepare('SELECT COUNT(*) as c FROM nodes').get().c;
@@ -1263,10 +1264,10 @@ export function moduleMap(customDbPath, limit = 20, opts = {}) {
   for (const [dir, files] of [...dirs].sort()) {
     console.log(`  [${dir}/]`);
     for (const f of files) {
-      const total = f.inEdges + f.outEdges;
-      const bar = '#'.repeat(Math.min(total, 40));
+      const coupling = f.inEdges + f.outEdges;
+      const bar = '#'.repeat(Math.min(coupling, 40));
       console.log(
-        `    ${path.basename(f.file).padEnd(35)} <-${String(f.inEdges).padStart(3)} ->${String(f.outEdges).padStart(3)}  ${bar}`,
+        `    ${path.basename(f.file).padEnd(35)} <-${String(f.inEdges).padStart(3)} ->${String(f.outEdges).padStart(3)}  =${String(coupling).padStart(3)}  ${bar}`,
       );
     }
   }
@@ -1920,6 +1921,7 @@ function explainFunctionImpl(db, target, noTests, getFileLines) {
 export function explainData(target, customDbPath, opts = {}) {
   const db = openReadonlyOrFail(customDbPath);
   const noTests = opts.noTests || false;
+  const depth = opts.depth || 0;
   const kind = isFileLikeTarget(target) ? 'file' : 'function';
 
   const dbPath = findDbPath(customDbPath);
@@ -1949,6 +1951,37 @@ export function explainData(target, customDbPath, opts = {}) {
       ? explainFileImpl(db, target, getFileLines)
       : explainFunctionImpl(db, target, noTests, getFileLines);
 
+  // Recursive dependency explanation for function targets
+  if (kind === 'function' && depth > 0 && results.length > 0) {
+    const visited = new Set(results.map((r) => `${r.name}:${r.file}:${r.line}`));
+
+    function explainCallees(parentResults, currentDepth) {
+      if (currentDepth <= 0) return;
+      for (const r of parentResults) {
+        const newCallees = [];
+        for (const callee of r.callees) {
+          const key = `${callee.name}:${callee.file}:${callee.line}`;
+          if (visited.has(key)) continue;
+          visited.add(key);
+          const calleeResults = explainFunctionImpl(db, callee.name, noTests, getFileLines);
+          const exact = calleeResults.find(
+            (cr) => cr.file === callee.file && cr.line === callee.line,
+          );
+          if (exact) {
+            exact._depth = (r._depth || 0) + 1;
+            newCallees.push(exact);
+          }
+        }
+        if (newCallees.length > 0) {
+          r.depDetails = newCallees;
+          explainCallees(newCallees, currentDepth - 1);
+        }
+      }
+    }
+
+    explainCallees(results, depth);
+  }
+
   db.close();
   return { target, kind, results };
 }
@@ -2008,46 +2041,63 @@ export function explain(target, customDbPath, opts = {}) {
       console.log();
     }
   } else {
-    for (const r of data.results) {
+    function printFunctionExplain(r, indent = '') {
       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}`);
+      const depthLevel = r._depth || 0;
+      const heading = depthLevel === 0 ? '#' : '##'.padEnd(depthLevel + 2, '#');
+      console.log(`\n${indent}${heading} ${r.name} (${r.kind})  ${r.file}:${lineRange}`);
       if (lineInfo || r.summary) {
-        console.log(`  ${lineInfo}${summaryPart}`);
+        console.log(`${indent}  ${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.signature.params != null)
+          console.log(`${indent}  Parameters: (${r.signature.params})`);
+        if (r.signature.returnType) console.log(`${indent}  Returns: ${r.signature.returnType}`);
       }
 
       if (r.callees.length > 0) {
-        console.log(`\n## Calls (${r.callees.length})`);
+        console.log(`\n${indent}  Calls (${r.callees.length}):`);
         for (const c of r.callees) {
-          console.log(`  ${kindIcon(c.kind)} ${c.name}  ${c.file}:${c.line}`);
+          console.log(`${indent}    ${kindIcon(c.kind)} ${c.name}  ${c.file}:${c.line}`);
         }
       }
 
       if (r.callers.length > 0) {
-        console.log(`\n## Called by (${r.callers.length})`);
+        console.log(`\n${indent}  Called by (${r.callers.length}):`);
         for (const c of r.callers) {
-          console.log(`  ${kindIcon(c.kind)} ${c.name}  ${c.file}:${c.line}`);
+          console.log(`${indent}    ${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})`);
+        console.log(`\n${indent}  Tests (${r.relatedTests.length} ${label}):`);
         for (const t of r.relatedTests) {
-          console.log(`  ${t.file}`);
+          console.log(`${indent}    ${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(
+          `${indent}  (no call edges found -- may be invoked dynamically or via re-exports)`,
+        );
+      }
+
+      // Render recursive dependency details
+      if (r.depDetails && r.depDetails.length > 0) {
+        console.log(`\n${indent}  --- Dependencies (depth ${depthLevel + 1}) ---`);
+        for (const dep of r.depDetails) {
+          printFunctionExplain(dep, `${indent}  `);
+        }
       }
       console.log();
     }
+
+    for (const r of data.results) {
+      printFunctionExplain(r);
+    }
   }
 }
 

package/src/structure.js

@@ -231,7 +231,8 @@ export function buildStructure(db, fileSymbols, _rootDir, lineCountMap, director
  */
 export function structureData(customDbPath, opts = {}) {
   const db = openReadonlyOrFail(customDbPath);
-  const filterDir = opts.directory || null;
+  const rawDir = opts.directory || null;
+  const filterDir = rawDir && normalizePath(rawDir) !== '.' ? rawDir : null;
   const maxDepth = opts.depth || null;
   const sortBy = opts.sort || 'files';
   const noTests = opts.noTests || false;