fix: throw on explicit --engine native when addon is unavailable

Previously --engine native silently fell back to WASM with a warning,
which was easy to miss. Now it throws a clear error with install
instructions, matching user intent. Auto mode remains unchanged.

Author: github-actions[bot]

docs/improvement-plan.md

@@ -109,12 +109,10 @@ Currently you need to run `map`, `cycles`, and read build output separately to a
 - Top 5 coupling hotspots
 - Embedding status (model, count, staleness)
 
-#### 8. Improve map command ranking
+#### ~~8. Improve map command ranking~~ FIXED
 **Found by:** `codegraph map --limit 20` (WASM build)
 
-When Rust files are parsed, the map is dominated by Rust extractor files (all with `inEdges: 1, outEdges: 0`). The ranking should prioritize files with meaningful import relationships over files with only `contains` edges.
-
-**Action:** Weight import/reexport edges higher than `contains` edges in the `map` ranking algorithm. Consider filtering out files below a minimum edge threshold.
+Fixed: `moduleMapData` SQL now excludes `contains` edges from `inEdges`/`outEdges` counts and ranking (`AND kind != 'contains'`). Files with only structural `contains` edges (e.g. Rust extractor files) no longer dominate the map. `stats.totalEdges` remains the raw total for graph size indication.
 
 #### 9. builder.js fan-out reduction
 **Found by:** `codegraph map` (fan-out 7, highest in codebase)

src/queries.js

@@ -1,7 +1,9 @@
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import { findCycles } from './cycles.js';
 import { findDbPath, openReadonlyOrFail } from './db.js';
+import { LANGUAGE_REGISTRY } from './parser.js';
 
 const TEST_PATTERN = /\.(test|spec)\.|__test__|__tests__|\.stories\./;
 function isTestFile(filePath) {
@@ -191,14 +193,14 @@ export function moduleMapData(customDbPath, limit = 20) {
   const nodes = db
     .prepare(`
     SELECT n.*,
-      (SELECT COUNT(*) FROM edges WHERE source_id = n.id) as out_edges,
-      (SELECT COUNT(*) FROM edges WHERE target_id = n.id) as in_edges
+      (SELECT COUNT(*) FROM edges WHERE source_id = n.id AND kind != 'contains') as out_edges,
+      (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__%'
-    ORDER BY (SELECT COUNT(*) FROM edges WHERE target_id = n.id) DESC
+    ORDER BY (SELECT COUNT(*) FROM edges WHERE target_id = n.id AND kind != 'contains') DESC
     LIMIT ?
   `)
     .all(limit);
@@ -614,6 +616,172 @@ export function listFunctionsData(customDbPath, opts = {}) {
   return { count: rows.length, functions: rows };
 }
 
+export function statsData(customDbPath) {
+  const db = openReadonlyOrFail(customDbPath);
+
+  // Node breakdown by kind
+  const nodeRows = db.prepare('SELECT kind, COUNT(*) as c FROM nodes GROUP BY kind').all();
+  const nodesByKind = {};
+  let totalNodes = 0;
+  for (const r of nodeRows) {
+    nodesByKind[r.kind] = r.c;
+    totalNodes += r.c;
+  }
+
+  // Edge breakdown by kind
+  const edgeRows = db.prepare('SELECT kind, COUNT(*) as c FROM edges GROUP BY kind').all();
+  const edgesByKind = {};
+  let totalEdges = 0;
+  for (const r of edgeRows) {
+    edgesByKind[r.kind] = r.c;
+    totalEdges += r.c;
+  }
+
+  // File/language distribution — map extensions via LANGUAGE_REGISTRY
+  const extToLang = new Map();
+  for (const entry of LANGUAGE_REGISTRY) {
+    for (const ext of entry.extensions) {
+      extToLang.set(ext, entry.id);
+    }
+  }
+  const fileNodes = db.prepare("SELECT file FROM nodes WHERE kind = 'file'").all();
+  const byLanguage = {};
+  for (const row of fileNodes) {
+    const ext = path.extname(row.file).toLowerCase();
+    const lang = extToLang.get(ext) || 'other';
+    byLanguage[lang] = (byLanguage[lang] || 0) + 1;
+  }
+  const langCount = Object.keys(byLanguage).length;
+
+  // Cycles
+  const fileCycles = findCycles(db, { fileLevel: true });
+  const fnCycles = findCycles(db, { fileLevel: false });
+
+  // Top 5 coupling hotspots (fan-in + fan-out, file nodes)
+  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'
+    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) => ({
+    file: r.file,
+    fanIn: r.fan_in,
+    fanOut: r.fan_out,
+  }));
+
+  // Embeddings metadata
+  let embeddings = null;
+  try {
+    const count = db.prepare('SELECT COUNT(*) as c FROM embeddings').get();
+    if (count && count.c > 0) {
+      const meta = {};
+      const metaRows = db.prepare('SELECT key, value FROM embedding_meta').all();
+      for (const r of metaRows) meta[r.key] = r.value;
+      embeddings = {
+        count: count.c,
+        model: meta.model || null,
+        dim: meta.dim ? parseInt(meta.dim, 10) : null,
+        builtAt: meta.built_at || null,
+      };
+    }
+  } catch {
+    /* embeddings table may not exist */
+  }
+
+  db.close();
+  return {
+    nodes: { total: totalNodes, byKind: nodesByKind },
+    edges: { total: totalEdges, byKind: edgesByKind },
+    files: { total: fileNodes.length, languages: langCount, byLanguage },
+    cycles: { fileLevel: fileCycles.length, functionLevel: fnCycles.length },
+    hotspots,
+    embeddings,
+  };
+}
+
+export function stats(customDbPath, opts = {}) {
+  const data = statsData(customDbPath);
+  if (opts.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  // Human-readable output
+  console.log('\n# Codegraph Stats\n');
+
+  // Nodes
+  console.log(`Nodes:     ${data.nodes.total} total`);
+  const kindEntries = Object.entries(data.nodes.byKind).sort((a, b) => b[1] - a[1]);
+  const kindParts = kindEntries.map(([k, v]) => `${k} ${v}`);
+  // Print in rows of 3
+  for (let i = 0; i < kindParts.length; i += 3) {
+    const row = kindParts
+      .slice(i, i + 3)
+      .map((p) => p.padEnd(18))
+      .join('');
+    console.log(`  ${row}`);
+  }
+
+  // Edges
+  console.log(`\nEdges:     ${data.edges.total} total`);
+  const edgeEntries = Object.entries(data.edges.byKind).sort((a, b) => b[1] - a[1]);
+  const edgeParts = edgeEntries.map(([k, v]) => `${k} ${v}`);
+  for (let i = 0; i < edgeParts.length; i += 3) {
+    const row = edgeParts
+      .slice(i, i + 3)
+      .map((p) => p.padEnd(18))
+      .join('');
+    console.log(`  ${row}`);
+  }
+
+  // Files
+  console.log(`\nFiles:     ${data.files.total} (${data.files.languages} languages)`);
+  const langEntries = Object.entries(data.files.byLanguage).sort((a, b) => b[1] - a[1]);
+  const langParts = langEntries.map(([k, v]) => `${k} ${v}`);
+  for (let i = 0; i < langParts.length; i += 3) {
+    const row = langParts
+      .slice(i, i + 3)
+      .map((p) => p.padEnd(18))
+      .join('');
+    console.log(`  ${row}`);
+  }
+
+  // Cycles
+  console.log(
+    `\nCycles:    ${data.cycles.fileLevel} file-level, ${data.cycles.functionLevel} function-level`,
+  );
+
+  // Hotspots
+  if (data.hotspots.length > 0) {
+    console.log(`\nTop ${data.hotspots.length} coupling hotspots:`);
+    for (let i = 0; i < data.hotspots.length; i++) {
+      const h = data.hotspots[i];
+      console.log(
+        `  ${String(i + 1).padStart(2)}. ${h.file.padEnd(35)} fan-in: ${String(h.fanIn).padStart(3)}  fan-out: ${String(h.fanOut).padStart(3)}`,
+      );
+    }
+  }
+
+  // Embeddings
+  if (data.embeddings) {
+    const e = data.embeddings;
+    console.log(
+      `\nEmbeddings: ${e.count} vectors (${e.model || 'unknown'}, ${e.dim || '?'}d) built ${e.builtAt || 'unknown'}`,
+    );
+  } else {
+    console.log('\nEmbeddings: not built');
+  }
+
+  console.log();
+}
+
 // ─── Human-readable output (original formatting) ───────────────────────
 
 export function queryName(name, customDbPath, opts = {}) {

tests/integration/queries.test.js

@@ -160,6 +160,50 @@ describe('moduleMapData', () => {
     const data = moduleMapData(dbPath, 2);
     expect(data.topNodes).toHaveLength(2);
   });
+
+  test('excludes contains edges from ranking and counts', () => {
+    // Build a separate DB with contains + imports edges
+    const tmpDir2 = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-contains-'));
+    fs.mkdirSync(path.join(tmpDir2, '.codegraph'));
+    const dbPath2 = path.join(tmpDir2, '.codegraph', 'graph.db');
+
+    const db2 = new Database(dbPath2);
+    db2.pragma('journal_mode = WAL');
+    initSchema(db2);
+
+    // Two file nodes
+    const fA = insertNode(db2, 'a.js', 'file', 'a.js', 0);
+    const fB = insertNode(db2, 'b.js', 'file', 'b.js', 0);
+    const fC = insertNode(db2, 'c.js', 'file', 'c.js', 0);
+
+    // a.js gets only a contains edge (structural)
+    insertEdge(db2, fC, fA, 'contains');
+    // b.js gets an imports edge (real dependency)
+    insertEdge(db2, fC, fB, 'imports');
+
+    db2.close();
+
+    try {
+      const data = moduleMapData(dbPath2);
+      const nodeA = data.topNodes.find((n) => n.file === 'a.js');
+      const nodeB = data.topNodes.find((n) => n.file === 'b.js');
+
+      // b.js (imports edge) should have inEdges=1, a.js (contains edge) should have inEdges=0
+      expect(nodeB.inEdges).toBe(1);
+      expect(nodeA.inEdges).toBe(0);
+
+      // b.js should rank above a.js
+      const indexA = data.topNodes.indexOf(nodeA);
+      const indexB = data.topNodes.indexOf(nodeB);
+      expect(indexB).toBeLessThan(indexA);
+
+      // c.js outEdges should only count the imports edge, not contains
+      const nodeC = data.topNodes.find((n) => n.file === 'c.js');
+      expect(nodeC.outEdges).toBe(1);
+    } finally {
+      fs.rmSync(tmpDir2, { recursive: true, force: true });
+    }
+  });
 });
 
 // ─── fileDepsData ──────────────────────────────────────────────────────