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

package/src/queries.js

@@ -1,6 +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) {
@@ -190,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);
@@ -451,9 +454,25 @@ export function diffImpactData(customDbPath, opts = {}) {
   const dbPath = findDbPath(customDbPath);
   const repoRoot = path.resolve(path.dirname(dbPath), '..');
 
+  // Verify we're in a git repository before running git diff
+  let checkDir = repoRoot;
+  let isGitRepo = false;
+  while (checkDir) {
+    if (fs.existsSync(path.join(checkDir, '.git'))) {
+      isGitRepo = true;
+      break;
+    }
+    const parent = path.dirname(checkDir);
+    if (parent === checkDir) break;
+    checkDir = parent;
+  }
+  if (!isGitRepo) {
+    db.close();
+    return { error: `Not a git repository: ${repoRoot}` };
+  }
+
   let diffOutput;
   try {
-    // FIX: Use execFileSync with array args to prevent shell injection
     const args = opts.staged
       ? ['diff', '--cached', '--unified=0', '--no-color']
       : ['diff', opts.ref || 'HEAD', '--unified=0', '--no-color'];
@@ -461,6 +480,7 @@ export function diffImpactData(customDbPath, opts = {}) {
       cwd: repoRoot,
       encoding: 'utf-8',
       maxBuffer: 10 * 1024 * 1024,
+      stdio: ['pipe', 'pipe', 'pipe'],
     });
   } catch (e) {
     db.close();
@@ -596,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 = {}) {
@@ -759,6 +945,402 @@ export function fnDeps(name, customDbPath, opts = {}) {
   }
 }
 
+// ─── Context helpers (private) ──────────────────────────────────────────
+
+function readSourceRange(repoRoot, file, startLine, endLine) {
+  try {
+    const absPath = path.resolve(repoRoot, file);
+    const content = fs.readFileSync(absPath, 'utf-8');
+    const lines = content.split('\n');
+    const start = Math.max(0, (startLine || 1) - 1);
+    const end = Math.min(lines.length, endLine || startLine + 50);
+    return lines.slice(start, end).join('\n');
+  } catch {
+    return null;
+  }
+}
+
+function extractSummary(fileLines, line) {
+  if (!fileLines || !line || line <= 1) return null;
+  const idx = line - 2; // line above the definition (0-indexed)
+  // Scan up to 10 lines above for JSDoc or comment
+  let jsdocEnd = -1;
+  for (let i = idx; i >= Math.max(0, idx - 10); i--) {
+    const trimmed = fileLines[i].trim();
+    if (trimmed.endsWith('*/')) {
+      jsdocEnd = i;
+      break;
+    }
+    if (trimmed.startsWith('//') || trimmed.startsWith('#')) {
+      // Single-line comment immediately above
+      const text = trimmed
+        .replace(/^\/\/\s*/, '')
+        .replace(/^#\s*/, '')
+        .trim();
+      return text.length > 100 ? `${text.slice(0, 100)}...` : text;
+    }
+    if (trimmed !== '' && !trimmed.startsWith('*') && !trimmed.startsWith('/*')) break;
+  }
+  if (jsdocEnd >= 0) {
+    // Find opening /**
+    for (let i = jsdocEnd; i >= Math.max(0, jsdocEnd - 20); i--) {
+      if (fileLines[i].trim().startsWith('/**')) {
+        // Extract first non-tag, non-empty line
+        for (let j = i + 1; j <= jsdocEnd; j++) {
+          const docLine = fileLines[j]
+            .trim()
+            .replace(/^\*\s?/, '')
+            .trim();
+          if (docLine && !docLine.startsWith('@') && docLine !== '/' && docLine !== '*/') {
+            return docLine.length > 100 ? `${docLine.slice(0, 100)}...` : docLine;
+          }
+        }
+        break;
+      }
+    }
+  }
+  return null;
+}
+
+function extractSignature(fileLines, line) {
+  if (!fileLines || !line) return null;
+  const idx = line - 1;
+  // Gather up to 5 lines to handle multi-line params
+  const chunk = fileLines.slice(idx, Math.min(fileLines.length, idx + 5)).join('\n');
+
+  // JS/TS: function name(params) or (params) => or async function
+  let m = chunk.match(
+    /(?:export\s+)?(?:async\s+)?function\s*\*?\s*\w*\s*\(([^)]*)\)\s*(?::\s*([^\n{]+))?/,
+  );
+  if (m) {
+    return {
+      params: m[1].trim() || null,
+      returnType: m[2] ? m[2].trim().replace(/\s*\{$/, '') : null,
+    };
+  }
+  // Arrow: const name = (params) => or (params):ReturnType =>
+  m = chunk.match(/=\s*(?:async\s+)?\(([^)]*)\)\s*(?::\s*([^=>\n{]+))?\s*=>/);
+  if (m) {
+    return {
+      params: m[1].trim() || null,
+      returnType: m[2] ? m[2].trim() : null,
+    };
+  }
+  // Python: def name(params) -> return:
+  m = chunk.match(/def\s+\w+\s*\(([^)]*)\)\s*(?:->\s*([^:\n]+))?/);
+  if (m) {
+    return {
+      params: m[1].trim() || null,
+      returnType: m[2] ? m[2].trim() : null,
+    };
+  }
+  // Go: func (recv) name(params) (returns)
+  m = chunk.match(/func\s+(?:\([^)]*\)\s+)?\w+\s*\(([^)]*)\)\s*(?:\(([^)]+)\)|(\w[^\n{]*))?/);
+  if (m) {
+    return {
+      params: m[1].trim() || null,
+      returnType: (m[2] || m[3] || '').trim() || null,
+    };
+  }
+  // Rust: fn name(params) -> ReturnType
+  m = chunk.match(/fn\s+\w+\s*\(([^)]*)\)\s*(?:->\s*([^\n{]+))?/);
+  if (m) {
+    return {
+      params: m[1].trim() || null,
+      returnType: m[2] ? m[2].trim() : null,
+    };
+  }
+  return null;
+}
+
+// ─── contextData ────────────────────────────────────────────────────────
+
+export function contextData(name, customDbPath, opts = {}) {
+  const db = openReadonlyOrFail(customDbPath);
+  const depth = opts.depth || 0;
+  const noSource = opts.noSource || false;
+  const noTests = opts.noTests || false;
+  const includeTests = opts.includeTests || false;
+
+  const dbPath = findDbPath(customDbPath);
+  const repoRoot = path.resolve(path.dirname(dbPath), '..');
+
+  let nodes = db
+    .prepare(
+      `SELECT * FROM nodes WHERE name LIKE ? AND kind IN ('function', 'method', 'class') ORDER BY file, line`,
+    )
+    .all(`%${name}%`);
+  if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
+  if (nodes.length === 0) {
+    db.close();
+    return { name, results: [] };
+  }
+
+  // Limit to first 5 results
+  nodes = nodes.slice(0, 5);
+
+  // File-lines cache to avoid re-reading the same file
+  const fileCache = new Map();
+  function getFileLines(file) {
+    if (fileCache.has(file)) return fileCache.get(file);
+    try {
+      const absPath = path.resolve(repoRoot, file);
+      const lines = fs.readFileSync(absPath, 'utf-8').split('\n');
+      fileCache.set(file, lines);
+      return lines;
+    } catch {
+      fileCache.set(file, null);
+      return null;
+    }
+  }
+
+  const results = nodes.map((node) => {
+    const fileLines = getFileLines(node.file);
+
+    // Source
+    const source = noSource ? null : readSourceRange(repoRoot, node.file, node.line, node.end_line);
+
+    // Signature
+    const signature = fileLines ? extractSignature(fileLines, node.line) : null;
+
+    // Callees
+    const calleeRows = db
+      .prepare(
+        `SELECT n.id, n.name, n.kind, n.file, n.line, n.end_line
+       FROM edges e JOIN nodes n ON e.target_id = n.id
+       WHERE e.source_id = ? AND e.kind = 'calls'`,
+      )
+      .all(node.id);
+    const filteredCallees = noTests ? calleeRows.filter((c) => !isTestFile(c.file)) : calleeRows;
+
+    const callees = filteredCallees.map((c) => {
+      const cLines = getFileLines(c.file);
+      const summary = cLines ? extractSummary(cLines, c.line) : null;
+      let calleeSource = null;
+      if (depth >= 1) {
+        calleeSource = readSourceRange(repoRoot, c.file, c.line, c.end_line);
+      }
+      return {
+        name: c.name,
+        kind: c.kind,
+        file: c.file,
+        line: c.line,
+        endLine: c.end_line || null,
+        summary,
+        source: calleeSource,
+      };
+    });
+
+    // Deep callee expansion via BFS (depth > 1, capped at 5)
+    if (depth > 1) {
+      const visited = new Set(filteredCallees.map((c) => c.id));
+      visited.add(node.id);
+      let frontier = filteredCallees.map((c) => c.id);
+      const maxDepth = Math.min(depth, 5);
+      for (let d = 2; d <= maxDepth; d++) {
+        const nextFrontier = [];
+        for (const fid of frontier) {
+          const deeper = db
+            .prepare(
+              `SELECT n.id, n.name, n.kind, n.file, n.line, n.end_line
+             FROM edges e JOIN nodes n ON e.target_id = n.id
+             WHERE e.source_id = ? AND e.kind = 'calls'`,
+            )
+            .all(fid);
+          for (const c of deeper) {
+            if (!visited.has(c.id) && (!noTests || !isTestFile(c.file))) {
+              visited.add(c.id);
+              nextFrontier.push(c.id);
+              const cLines = getFileLines(c.file);
+              callees.push({
+                name: c.name,
+                kind: c.kind,
+                file: c.file,
+                line: c.line,
+                endLine: c.end_line || null,
+                summary: cLines ? extractSummary(cLines, c.line) : null,
+                source: readSourceRange(repoRoot, c.file, c.line, c.end_line),
+              });
+            }
+          }
+        }
+        frontier = nextFrontier;
+        if (frontier.length === 0) break;
+      }
+    }
+
+    // Callers
+    let callerRows = db
+      .prepare(
+        `SELECT n.name, n.kind, n.file, n.line
+       FROM edges e JOIN nodes n ON e.source_id = n.id
+       WHERE e.target_id = ? AND e.kind = 'calls'`,
+      )
+      .all(node.id);
+
+    // Method hierarchy resolution
+    if (node.kind === 'method' && node.name.includes('.')) {
+      const methodName = node.name.split('.').pop();
+      const relatedMethods = resolveMethodViaHierarchy(db, methodName);
+      for (const rm of relatedMethods) {
+        if (rm.id === node.id) continue;
+        const extraCallers = db
+          .prepare(
+            `SELECT n.name, n.kind, n.file, n.line
+           FROM edges e JOIN nodes n ON e.source_id = n.id
+           WHERE e.target_id = ? AND e.kind = 'calls'`,
+          )
+          .all(rm.id);
+        callerRows.push(...extraCallers.map((c) => ({ ...c, viaHierarchy: rm.name })));
+      }
+    }
+    if (noTests) callerRows = callerRows.filter((c) => !isTestFile(c.file));
+
+    const callers = callerRows.map((c) => ({
+      name: c.name,
+      kind: c.kind,
+      file: c.file,
+      line: c.line,
+      viaHierarchy: c.viaHierarchy || undefined,
+    }));
+
+    // Related tests: callers that live in test files
+    const testCallerRows = db
+      .prepare(
+        `SELECT n.name, n.kind, n.file, n.line
+       FROM edges e JOIN nodes n ON e.source_id = n.id
+       WHERE e.target_id = ? AND e.kind = 'calls'`,
+      )
+      .all(node.id);
+    const testCallers = testCallerRows.filter((c) => isTestFile(c.file));
+
+    const testsByFile = new Map();
+    for (const tc of testCallers) {
+      if (!testsByFile.has(tc.file)) testsByFile.set(tc.file, []);
+      testsByFile.get(tc.file).push(tc);
+    }
+
+    const relatedTests = [];
+    for (const [file] of testsByFile) {
+      const tLines = getFileLines(file);
+      const testNames = [];
+      if (tLines) {
+        for (const tl of tLines) {
+          const tm = tl.match(/(?:it|test|describe)\s*\(\s*['"`]([^'"`]+)['"`]/);
+          if (tm) testNames.push(tm[1]);
+        }
+      }
+      const testSource = includeTests && tLines ? tLines.join('\n') : undefined;
+      relatedTests.push({
+        file,
+        testCount: testNames.length,
+        testNames,
+        source: testSource,
+      });
+    }
+
+    return {
+      name: node.name,
+      kind: node.kind,
+      file: node.file,
+      line: node.line,
+      endLine: node.end_line || null,
+      source,
+      signature,
+      callees,
+      callers,
+      relatedTests,
+    };
+  });
+
+  db.close();
+  return { name, results };
+}
+
+export function context(name, customDbPath, opts = {}) {
+  const data = contextData(name, customDbPath, opts);
+  if (opts.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+  if (data.results.length === 0) {
+    console.log(`No function/method/class matching "${name}"`);
+    return;
+  }
+
+  for (const r of data.results) {
+    const lineRange = r.endLine ? `${r.line}-${r.endLine}` : `${r.line}`;
+    console.log(`\n# ${r.name} (${r.kind}) — ${r.file}:${lineRange}\n`);
+
+    // Signature
+    if (r.signature) {
+      console.log('## Type/Shape Info');
+      if (r.signature.params != null) console.log(`  Parameters: (${r.signature.params})`);
+      if (r.signature.returnType) console.log(`  Returns: ${r.signature.returnType}`);
+      console.log();
+    }
+
+    // Source
+    if (r.source) {
+      console.log('## Source');
+      for (const line of r.source.split('\n')) {
+        console.log(`  ${line}`);
+      }
+      console.log();
+    }
+
+    // Callees
+    if (r.callees.length > 0) {
+      console.log(`## Direct Dependencies (${r.callees.length})`);
+      for (const c of r.callees) {
+        const summary = c.summary ? ` — ${c.summary}` : '';
+        console.log(`  ${kindIcon(c.kind)} ${c.name}  ${c.file}:${c.line}${summary}`);
+        if (c.source) {
+          for (const line of c.source.split('\n').slice(0, 10)) {
+            console.log(`    | ${line}`);
+          }
+        }
+      }
+      console.log();
+    }
+
+    // Callers
+    if (r.callers.length > 0) {
+      console.log(`## Callers (${r.callers.length})`);
+      for (const c of r.callers) {
+        const via = c.viaHierarchy ? ` (via ${c.viaHierarchy})` : '';
+        console.log(`  ${kindIcon(c.kind)} ${c.name}  ${c.file}:${c.line}${via}`);
+      }
+      console.log();
+    }
+
+    // Related tests
+    if (r.relatedTests.length > 0) {
+      console.log('## Related Tests');
+      for (const t of r.relatedTests) {
+        console.log(`  ${t.file} — ${t.testCount} tests`);
+        for (const tn of t.testNames) {
+          console.log(`    - ${tn}`);
+        }
+        if (t.source) {
+          console.log('    Source:');
+          for (const line of t.source.split('\n').slice(0, 20)) {
+            console.log(`    | ${line}`);
+          }
+        }
+      }
+      console.log();
+    }
+
+    if (r.callees.length === 0 && r.callers.length === 0 && r.relatedTests.length === 0) {
+      console.log(
+        '  (no call edges or tests found — may be invoked dynamically or via re-exports)',
+      );
+      console.log();
+    }
+  }
+}
+
 export function fnImpact(name, customDbPath, opts = {}) {
   const data = fnImpactData(name, customDbPath, opts);
   if (opts.json) {

package/src/registry.js

@@ -3,7 +3,11 @@ import os from 'node:os';
 import path from 'node:path';
 import { debug, warn } from './logger.js';
 
-export const REGISTRY_PATH = path.join(os.homedir(), '.codegraph', 'registry.json');
+export const REGISTRY_PATH =
+  process.env.CODEGRAPH_REGISTRY_PATH || path.join(os.homedir(), '.codegraph', 'registry.json');
+
+/** Default TTL: entries not accessed within 30 days are pruned. */
+export const DEFAULT_TTL_DAYS = 30;
 
 /**
  * Load the registry from disk.
@@ -69,10 +73,12 @@ export function registerRepo(rootDir, name, registryPath = REGISTRY_PATH) {
     }
   }
 
+  const now = new Date().toISOString();
   registry.repos[repoName] = {
     path: absRoot,
     dbPath: path.join(absRoot, '.codegraph', 'graph.db'),
-    addedAt: new Date().toISOString(),
+    addedAt: registry.repos[repoName]?.addedAt || now,
+    lastAccessedAt: now,
   };
 
   saveRegistry(registry, registryPath);
@@ -102,6 +108,7 @@ export function listRepos(registryPath = REGISTRY_PATH) {
       path: entry.path,
       dbPath: entry.dbPath,
       addedAt: entry.addedAt,
+      lastAccessedAt: entry.lastAccessedAt || entry.addedAt,
     }))
     .sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -118,21 +125,31 @@ export function resolveRepoDbPath(name, registryPath = REGISTRY_PATH) {
     warn(`Registry: database missing for "${name}" at ${entry.dbPath}`);
     return undefined;
   }
+  // Touch lastAccessedAt on successful resolution
+  entry.lastAccessedAt = new Date().toISOString();
+  saveRegistry(registry, registryPath);
   return entry.dbPath;
 }
 
 /**
- * Remove registry entries whose repo directory no longer exists on disk.
- * Only checks the repo directory (not the DB file — a missing DB is normal pre-build state).
- * Returns an array of `{ name, path }` for each pruned entry.
+ * Remove registry entries whose repo directory no longer exists on disk,
+ * or that haven't been accessed within `ttlDays` days.
+ * Returns an array of `{ name, path, reason }` for each pruned entry.
  */
-export function pruneRegistry(registryPath = REGISTRY_PATH) {
+export function pruneRegistry(registryPath = REGISTRY_PATH, ttlDays = DEFAULT_TTL_DAYS) {
   const registry = loadRegistry(registryPath);
   const pruned = [];
+  const cutoff = Date.now() - ttlDays * 24 * 60 * 60 * 1000;
 
   for (const [name, entry] of Object.entries(registry.repos)) {
     if (!fs.existsSync(entry.path)) {
-      pruned.push({ name, path: entry.path });
+      pruned.push({ name, path: entry.path, reason: 'missing' });
+      delete registry.repos[name];
+      continue;
+    }
+    const lastAccess = Date.parse(entry.lastAccessedAt || entry.addedAt);
+    if (lastAccess < cutoff) {
+      pruned.push({ name, path: entry.path, reason: 'expired' });
       delete registry.repos[name];
     }
   }