@optave/codegraph 2.0.0 → 2.1.1-dev.00f091c

package/src/builder.js

@@ -1,15 +1,48 @@
 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 { getActiveEngine, parseFilesAuto } from './parser.js';
 import { computeConfidence, resolveImportPath, resolveImportsBatch } from './resolve.js';
 
 export { resolveImportPath } from './resolve.js';
 
+const BUILTIN_RECEIVERS = new Set([
+  'console',
+  'Math',
+  'JSON',
+  'Object',
+  'Array',
+  'String',
+  'Number',
+  'Boolean',
+  'Date',
+  'RegExp',
+  'Map',
+  'Set',
+  'WeakMap',
+  'WeakSet',
+  'Promise',
+  'Symbol',
+  'Error',
+  'TypeError',
+  'RangeError',
+  'Proxy',
+  'Reflect',
+  'Intl',
+  'globalThis',
+  'window',
+  'document',
+  'process',
+  'Buffer',
+  'require',
+]);
+
 export function collectFiles(dir, files = [], config = {}, directories = null) {
   const trackDirs = directories !== null;
   let entries;
@@ -80,8 +113,24 @@ function fileHash(content) {
   return createHash('md5').update(content).digest('hex');
 }
 
+/**
+ * Stat a file, returning { mtimeMs, size } or null on error.
+ */
+function fileStat(filePath) {
+  try {
+    const s = fs.statSync(filePath);
+    return { mtimeMs: s.mtimeMs, size: s.size };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Determine which files have changed since last build.
+ * Three-tier cascade:
+ *   Tier 0 — Journal: O(changed) when watcher was running
+ *   Tier 1 — mtime+size: O(n) stats, O(changed) reads
+ *   Tier 2 — Hash comparison: O(changed) reads (fallback from Tier 1)
  */
 function getChangedFiles(db, allFiles, rootDir) {
   // Check if file_hashes table exists
@@ -94,7 +143,6 @@ function getChangedFiles(db, allFiles, rootDir) {
   }
 
   if (!hasTable) {
-    // No hash table = first build, everything is new
     return {
       changed: allFiles.map((f) => ({ file: f })),
       removed: [],
@@ -104,36 +152,140 @@ function getChangedFiles(db, allFiles, rootDir) {
 
   const existing = new Map(
     db
-      .prepare('SELECT file, hash FROM file_hashes')
+      .prepare('SELECT file, hash, mtime, size FROM file_hashes')
       .all()
-      .map((r) => [r.file, r.hash]),
+      .map((r) => [r.file, r]),
   );
 
-  const changed = [];
+  // Build set of current files for removal detection
   const currentFiles = new Set();
+  for (const file of allFiles) {
+    currentFiles.add(normalizePath(path.relative(rootDir, file)));
+  }
+
+  const removed = [];
+  for (const existingFile of existing.keys()) {
+    if (!currentFiles.has(existingFile)) {
+      removed.push(existingFile);
+    }
+  }
+
+  // ── Tier 0: Journal ──────────────────────────────────────────────
+  const journal = readJournal(rootDir);
+  if (journal.valid) {
+    // Validate journal timestamp against DB — journal should be from after the last build
+    const dbMtimes = db.prepare('SELECT MAX(mtime) as latest FROM file_hashes').get();
+    const latestDbMtime = dbMtimes?.latest || 0;
+
+    // Empty journal = no watcher was running, fall to Tier 1 for safety
+    const hasJournalEntries = journal.changed.length > 0 || journal.removed.length > 0;
+
+    if (hasJournalEntries && journal.timestamp >= latestDbMtime) {
+      debug(
+        `Tier 0: journal valid, ${journal.changed.length} changed, ${journal.removed.length} removed`,
+      );
+      const changed = [];
+
+      for (const relPath of journal.changed) {
+        const absPath = path.join(rootDir, relPath);
+        const stat = fileStat(absPath);
+        if (!stat) continue;
+
+        let content;
+        try {
+          content = fs.readFileSync(absPath, 'utf-8');
+        } catch {
+          continue;
+        }
+        const hash = fileHash(content);
+        const record = existing.get(relPath);
+        if (!record || record.hash !== hash) {
+          changed.push({ file: absPath, content, hash, relPath, stat });
+        }
+      }
+
+      // Merge journal removals with filesystem removals (dedup)
+      const removedSet = new Set(removed);
+      for (const relPath of journal.removed) {
+        if (existing.has(relPath)) removedSet.add(relPath);
+      }
+
+      return { changed, removed: [...removedSet], isFullBuild: false };
+    }
+    debug(
+      `Tier 0: skipped (${hasJournalEntries ? 'timestamp stale' : 'no entries'}), falling to Tier 1`,
+    );
+  }
+
+  // ── Tier 1: mtime+size fast-path ─────────────────────────────────
+  const needsHash = []; // Files that failed mtime+size check
+  const skipped = []; // Files that passed mtime+size check
 
   for (const file of allFiles) {
     const relPath = normalizePath(path.relative(rootDir, file));
-    currentFiles.add(relPath);
+    const record = existing.get(relPath);
+
+    if (!record) {
+      // New file — needs full read+hash
+      needsHash.push({ file, relPath });
+      continue;
+    }
+
+    const stat = fileStat(file);
+    if (!stat) continue;
+
+    const storedMtime = record.mtime || 0;
+    const storedSize = record.size || 0;
+
+    // size > 0 guard: pre-v4 rows have size=0, always fall through to hash
+    if (storedSize > 0 && Math.floor(stat.mtimeMs) === storedMtime && stat.size === storedSize) {
+      skipped.push(relPath);
+      continue;
+    }
+
+    needsHash.push({ file, relPath, stat });
+  }
+
+  if (needsHash.length > 0) {
+    debug(`Tier 1: ${skipped.length} skipped by mtime+size, ${needsHash.length} need hash check`);
+  }
+
+  // ── Tier 2: Hash comparison ──────────────────────────────────────
+  const changed = [];
 
+  for (const item of needsHash) {
     let content;
     try {
-      content = fs.readFileSync(file, 'utf-8');
+      content = fs.readFileSync(item.file, 'utf-8');
     } catch {
       continue;
     }
     const hash = fileHash(content);
-
-    if (existing.get(relPath) !== hash) {
-      changed.push({ file, content, hash, relPath });
+    const stat = item.stat || fileStat(item.file);
+    const record = existing.get(item.relPath);
+
+    if (!record || record.hash !== hash) {
+      changed.push({ file: item.file, content, hash, relPath: item.relPath, stat });
+    } else if (stat) {
+      // Hash matches but mtime/size was stale — self-heal by updating stored metadata
+      changed.push({
+        file: item.file,
+        content,
+        hash,
+        relPath: item.relPath,
+        stat,
+        metadataOnly: true,
+      });
     }
   }
 
-  const removed = [];
-  for (const existingFile of existing.keys()) {
-    if (!currentFiles.has(existingFile)) {
-      removed.push(existingFile);
-    }
+  // Filter out metadata-only updates from the "changed" list for parsing,
+  // but keep them so the caller can update file_hashes
+  const parseChanged = changed.filter((c) => !c.metadataOnly);
+  if (needsHash.length > 0) {
+    debug(
+      `Tier 2: ${parseChanged.length} actually changed, ${changed.length - parseChanged.length} metadata-only`,
+    );
   }
 
   return { changed, removed, isFullBuild: false };
@@ -179,9 +331,33 @@ export async function buildGraph(rootDir, opts = {}) {
     ? getChangedFiles(db, files, rootDir)
     : { changed: files.map((f) => ({ file: f })), removed: [], isFullBuild: true };
 
-  if (!isFullBuild && changed.length === 0 && removed.length === 0) {
+  // Separate metadata-only updates (mtime/size self-heal) from real changes
+  const parseChanges = changed.filter((c) => !c.metadataOnly);
+  const metadataUpdates = changed.filter((c) => c.metadataOnly);
+
+  if (!isFullBuild && parseChanges.length === 0 && removed.length === 0) {
+    // Still update metadata for self-healing even when no real changes
+    if (metadataUpdates.length > 0) {
+      try {
+        const healHash = db.prepare(
+          'INSERT OR REPLACE INTO file_hashes (file, hash, mtime, size) VALUES (?, ?, ?, ?)',
+        );
+        const healTx = db.transaction(() => {
+          for (const item of metadataUpdates) {
+            const mtime = item.stat ? Math.floor(item.stat.mtimeMs) : 0;
+            const size = item.stat ? item.stat.size : 0;
+            healHash.run(item.relPath, item.hash, mtime, size);
+          }
+        });
+        healTx();
+        debug(`Self-healed mtime/size for ${metadataUpdates.length} files`);
+      } catch {
+        /* ignore heal errors */
+      }
+    }
     console.log('No changes detected. Graph is up to date.');
     db.close();
+    writeJournalHeader(rootDir, Date.now());
     return;
   }
 
@@ -190,7 +366,7 @@ export async function buildGraph(rootDir, opts = {}) {
       'PRAGMA foreign_keys = OFF; DELETE FROM node_metrics; DELETE FROM edges; DELETE FROM nodes; PRAGMA foreign_keys = ON;',
     );
   } else {
-    console.log(`Incremental: ${changed.length} changed, ${removed.length} removed`);
+    console.log(`Incremental: ${parseChanges.length} changed, ${removed.length} removed`);
     // Remove metrics/edges/nodes for changed and removed files
     const deleteNodesForFile = db.prepare('DELETE FROM nodes WHERE file = ?');
     const deleteEdgesForFile = db.prepare(`
@@ -205,7 +381,7 @@ export async function buildGraph(rootDir, opts = {}) {
       deleteMetricsForFile.run(relPath);
       deleteNodesForFile.run(relPath);
     }
-    for (const item of changed) {
+    for (const item of parseChanges) {
       const relPath = item.relPath || normalizePath(path.relative(rootDir, item.file));
       deleteEdgesForFile.run({ f: relPath });
       deleteMetricsForFile.run(relPath);
@@ -223,11 +399,11 @@ export async function buildGraph(rootDir, opts = {}) {
     'INSERT INTO edges (source_id, target_id, kind, confidence, dynamic) VALUES (?, ?, ?, ?, ?)',
   );
 
-  // Prepare hash upsert
+  // Prepare hash upsert (with size column from migration v4)
   let upsertHash;
   try {
     upsertHash = db.prepare(
-      'INSERT OR REPLACE INTO file_hashes (file, hash, mtime) VALUES (?, ?, ?)',
+      'INSERT OR REPLACE INTO file_hashes (file, hash, mtime, size) VALUES (?, ?, ?, ?)',
     );
   } catch {
     upsertHash = null;
@@ -245,17 +421,17 @@ export async function buildGraph(rootDir, opts = {}) {
     // We'll fill these in during the parse pass + edge pass
   }
 
-  const filesToParse = isFullBuild ? files.map((f) => ({ file: f })) : changed;
+  const filesToParse = isFullBuild ? files.map((f) => ({ file: f })) : parseChanges;
 
   // ── Unified parse via parseFilesAuto ───────────────────────────────
   const filePaths = filesToParse.map((item) => item.file);
   const allSymbols = await parseFilesAuto(filePaths, rootDir, engineOpts);
 
-  // Build a hash lookup from incremental data (changed items may carry pre-computed hashes)
-  const precomputedHashes = new Map();
+  // Build a lookup from incremental data (changed items may carry pre-computed hashes + stats)
+  const precomputedData = new Map();
   for (const item of filesToParse) {
-    if (item.hash && item.relPath) {
-      precomputedHashes.set(item.relPath, item.hash);
+    if (item.relPath) {
+      precomputedData.set(item.relPath, item);
     }
   }
 
@@ -271,11 +447,14 @@ export async function buildGraph(rootDir, opts = {}) {
         insertNode.run(exp.name, exp.kind, relPath, exp.line, null);
       }
 
-      // Update file hash for incremental builds
+      // Update file hash with real mtime+size for incremental builds
       if (upsertHash) {
-        const existingHash = precomputedHashes.get(relPath);
-        if (existingHash) {
-          upsertHash.run(relPath, existingHash, Date.now());
+        const precomputed = precomputedData.get(relPath);
+        if (precomputed?.hash) {
+          const stat = precomputed.stat || fileStat(path.join(rootDir, relPath));
+          const mtime = stat ? Math.floor(stat.mtimeMs) : 0;
+          const size = stat ? stat.size : 0;
+          upsertHash.run(relPath, precomputed.hash, mtime, size);
         } else {
           const absPath = path.join(rootDir, relPath);
           let code;
@@ -285,11 +464,23 @@ export async function buildGraph(rootDir, opts = {}) {
             code = null;
           }
           if (code !== null) {
-            upsertHash.run(relPath, fileHash(code), Date.now());
+            const stat = fileStat(absPath);
+            const mtime = stat ? Math.floor(stat.mtimeMs) : 0;
+            const size = stat ? stat.size : 0;
+            upsertHash.run(relPath, fileHash(code), mtime, size);
           }
         }
       }
     }
+
+    // Also update metadata-only entries (self-heal mtime/size without re-parse)
+    if (upsertHash) {
+      for (const item of metadataUpdates) {
+        const mtime = item.stat ? Math.floor(item.stat.mtimeMs) : 0;
+        const size = item.stat ? item.stat.size : 0;
+        upsertHash.run(item.relPath, item.hash, mtime, size);
+      }
+    }
   });
   insertAll();
 
@@ -457,7 +648,9 @@ export async function buildGraph(rootDir, opts = {}) {
       }
 
       // Call edges with confidence scoring — using pre-loaded lookup maps (N+1 fix)
+      const seenCallEdges = new Set();
       for (const call of symbols.calls) {
+        if (call.receiver && BUILTIN_RECEIVERS.has(call.receiver)) continue;
         let caller = null;
         for (const def of symbols.definitions) {
           if (def.line <= call.line) {
@@ -492,10 +685,18 @@ export async function buildGraph(rootDir, opts = {}) {
             );
             if (methodCandidates.length > 0) {
               targets = methodCandidates;
-            } else {
-              // Global fallback
-              targets = nodesByName.get(call.name) || [];
+            } else if (
+              !call.receiver ||
+              call.receiver === 'this' ||
+              call.receiver === 'self' ||
+              call.receiver === 'super'
+            ) {
+              // Scoped fallback — same-dir or parent-dir only, not global
+              targets = (nodesByName.get(call.name) || []).filter(
+                (n) => computeConfidence(relPath, n.file, null) >= 0.5,
+              );
             }
+            // else: method call on a receiver — skip global fallback entirely
           }
         }
 
@@ -508,7 +709,9 @@ export async function buildGraph(rootDir, opts = {}) {
         }
 
         for (const t of targets) {
-          if (t.id !== caller.id) {
+          const edgeKey = `${caller.id}|${t.id}`;
+          if (t.id !== caller.id && !seenCallEdges.has(edgeKey)) {
+            seenCallEdges.add(edgeKey);
             const confidence = computeConfidence(relPath, t.file, importedFrom);
             insertEdge.run(caller.id, t.id, 'calls', confidence, isDynamic);
             edgeCount++;
@@ -581,10 +784,21 @@ export async function buildGraph(rootDir, opts = {}) {
   console.log(`Stored in ${dbPath}`);
   db.close();
 
-  try {
-    const { registerRepo } = await import('./registry.js');
-    registerRepo(rootDir);
-  } catch (err) {
-    debug(`Auto-registration failed: ${err.message}`);
+  // Write journal header after successful build
+  writeJournalHeader(rootDir, Date.now());
+
+  if (!opts.skipRegistry) {
+    const tmpDir = path.resolve(os.tmpdir());
+    const resolvedRoot = path.resolve(rootDir);
+    if (resolvedRoot.startsWith(tmpDir)) {
+      debug(`Skipping auto-registration for temp directory: ${resolvedRoot}`);
+    } else {
+      try {
+        const { registerRepo } = await import('./registry.js');
+        registerRepo(rootDir);
+      } catch (err) {
+        debug(`Auto-registration failed: ${err.message}`);
+      }
+    }
   }
 }

package/src/cli.js

@@ -11,6 +11,7 @@ import { buildEmbeddings, MODELS, search } from './embedder.js';
 import { exportDOT, exportJSON, exportMermaid } from './export.js';
 import { setVerbose } from './logger.js';
 import {
+  context,
   diffImpact,
   fileDeps,
   fnDeps,
@@ -18,6 +19,7 @@ import {
   impactAnalysis,
   moduleMap,
   queryName,
+  stats,
 } from './queries.js';
 import {
   listRepos,
@@ -28,11 +30,14 @@ import {
 } from './registry.js';
 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 program = new Command();
 program
   .name('codegraph')
   .description('Local code dependency graph tool')
-  .version('1.3.0')
+  .version(pkg.version)
   .option('-v, --verbose', 'Enable verbose/debug output')
   .option('--engine <engine>', 'Parser engine: native, wasm, or auto (default: auto)', 'auto')
   .hook('preAction', (thisCommand) => {
@@ -78,6 +83,15 @@ program
     moduleMap(opts.db, parseInt(opts.limit, 10), { 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('-j, --json', 'Output as JSON')
+  .action((opts) => {
+    stats(opts.db, { json: opts.json });
+  });
+
 program
   .command('deps <file>')
   .description('Show what this file imports and what imports it')
@@ -117,6 +131,25 @@ program
     });
   });
 
+program
+  .command('context <name>')
+  .description('Full context for a function: source, deps, callers, tests, signature')
+  .option('-d, --db <path>', 'Path to graph.db')
+  .option('--depth <n>', 'Include callee source up to N levels deep', '0')
+  .option('--no-source', 'Metadata only (skip source extraction)')
+  .option('--include-tests', 'Include test source code')
+  .option('-T, --no-tests', 'Exclude test files from callers')
+  .option('-j, --json', 'Output as JSON')
+  .action((name, opts) => {
+    context(name, opts.db, {
+      depth: parseInt(opts.depth, 10),
+      noSource: !opts.source,
+      noTests: !opts.tests,
+      includeTests: opts.includeTests,
+      json: opts.json,
+    });
+  });
+
 program
   .command('diff-impact [ref]')
   .description('Show impact of git changes (unstaged, staged, or vs a ref)')
@@ -214,6 +247,7 @@ registry
   .description('List all registered repositories')
   .option('-j, --json', 'Output as JSON')
   .action((opts) => {
+    pruneRegistry();
     const repos = listRepos();
     if (opts.json) {
       console.log(JSON.stringify(repos, null, 2));
@@ -257,14 +291,16 @@ registry
 
 registry
   .command('prune')
-  .description('Remove registry entries whose directories no longer exist')
-  .action(() => {
-    const pruned = pruneRegistry();
+  .description('Remove stale registry entries (missing directories or idle beyond TTL)')
+  .option('--ttl <days>', 'Days of inactivity before pruning (default: 30)', '30')
+  .action((opts) => {
+    const pruned = pruneRegistry(undefined, parseInt(opts.ttl, 10));
     if (pruned.length === 0) {
       console.log('No stale entries found.');
     } else {
       for (const entry of pruned) {
-        console.log(`Pruned "${entry.name}" (${entry.path})`);
+        const tag = entry.reason === 'expired' ? 'expired' : 'missing';
+        console.log(`Pruned "${entry.name}" (${entry.path}) [${tag}]`);
       }
       console.log(`\nRemoved ${pruned.length} stale ${pruned.length === 1 ? 'entry' : 'entries'}.`);
     }
@@ -278,7 +314,7 @@ program
   .action(() => {
     console.log('\nAvailable embedding models:\n');
     for (const [key, config] of Object.entries(MODELS)) {
-      const def = key === 'minilm' ? ' (default)' : '';
+      const def = key === 'jina-code' ? ' (default)' : '';
       console.log(`  ${key.padEnd(12)} ${String(config.dim).padStart(4)}d  ${config.desc}${def}`);
     }
     console.log('\nUsage: codegraph embed --model <name>');
@@ -292,8 +328,8 @@ program
   )
   .option(
     '-m, --model <name>',
-    'Embedding model: minilm (default), jina-small, jina-base, jina-code, nomic, nomic-v1.5, bge-large. Run `codegraph models` for details',
-    'minilm',
+    'Embedding model: minilm, jina-small, jina-base, jina-code (default), nomic, nomic-v1.5, bge-large. Run `codegraph models` for details',
+    'jina-code',
   )
   .action(async (dir, opts) => {
     const root = path.resolve(dir || '.');

package/src/config.js

@@ -19,7 +19,7 @@ export const DEFAULTS = {
     defaultDepth: 3,
     defaultLimit: 20,
   },
-  embeddings: { model: 'minilm', llmProvider: null },
+  embeddings: { model: 'jina-code', llmProvider: null },
   llm: { provider: null, model: null, baseUrl: null, apiKey: null, apiKeyCommand: null },
   search: { defaultMinScore: 0.2, rrfK: 60, topK: 15 },
   ci: { failOnCycles: false, impactThreshold: null },

package/src/db.js

@@ -67,6 +67,10 @@ export const MIGRATIONS = [
       );
     `,
   },
+  {
+    version: 4,
+    up: `ALTER TABLE file_hashes ADD COLUMN size INTEGER DEFAULT 0;`,
+  },
 ];
 
 export function openDb(dbPath) {

package/src/embedder.js

@@ -55,7 +55,7 @@ export const MODELS = {
   },
 };
 
-export const DEFAULT_MODEL = 'minilm';
+export const DEFAULT_MODEL = 'jina-code';
 const BATCH_SIZE_MAP = {
   minilm: 32,
   'jina-small': 16,
@@ -173,10 +173,10 @@ function initEmbeddingsSchema(db) {
 /**
  * Build embeddings for all functions/methods/classes in the graph.
  */
-export async function buildEmbeddings(rootDir, modelKey) {
+export async function buildEmbeddings(rootDir, modelKey, customDbPath) {
   // path already imported at top
   // fs already imported at top
-  const dbPath = findDbPath(null);
+  const dbPath = customDbPath || findDbPath(null);
 
   const db = new Database(dbPath);
   initEmbeddingsSchema(db);