@monoes/monograph 1.5.2 → 1.5.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monoes/monograph",
-  "version": "1.5.2",
+  "version": "1.5.4",
   "type": "module",
   "description": "Native TypeScript code intelligence engine for monomind",
   "main": "dist/src/index.js",
@@ -20,7 +20,8 @@
   },
   "scripts": {
     "build": "tsc",
-    "test": "vitest run"
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "better-sqlite3": "^12.0.0",
@@ -56,4 +57,4 @@
     "typescript": "^7.0.2",
     "vitest": "^4.1.4"
   }
-}
+}

package/src/cli/eval-server.ts

@@ -9,6 +9,7 @@
  *   createEvalServer('/path/to/repo', 4848)
  */
 
+import { createRequire } from 'node:module';
 import type { Server } from 'http';
 import type { Application } from 'express';
 import { openDb, closeDb } from '../storage/db.js';
@@ -49,7 +50,13 @@ export function createEvalServer(repoPath: string, _port?: number): EvalServerHa
   function getApp(): Application {
     if (_app) return _app;
 
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    // createRequire, not a bare require(): this package is ESM
+    // ("type": "module"), where `require` is undefined at runtime — the
+    // eslint-disable that used to sit here silenced the lint but the call
+    // still threw "require is not defined" the moment getApp() ran.
+    // getApp() is synchronous, so `await import()` is not an option; this is
+    // the correct ESM escape hatch for a deliberately deferred load.
+    const require = createRequire(import.meta.url);
     const express = require('express') as typeof import('express');
     const app = express();
     app.use(express.json());

package/src/cli/skill-gen.ts

@@ -60,29 +60,29 @@ export async function generateSkillFiles(
   const db = openDb(dbPath);
 
   try {
-  const communities = queryCommunities(db);
+    const communities = queryCommunities(db);
 
-  if (communities.length === 0) {
-    return { filesWritten: [], communityCount: 0 };
-  }
+    if (communities.length === 0) {
+      return { filesWritten: [], communityCount: 0 };
+    }
 
-  await fs.mkdir(skillsDir, { recursive: true });
+    await fs.mkdir(skillsDir, { recursive: true });
 
-  const filesWritten: string[] = [];
+    const filesWritten: string[] = [];
 
-  for (const community of communities) {
-    const members = queryMembers(db, community.community_id);
-    const crossConnections = queryCrossConnections(db, community.community_id);
+    for (const community of communities) {
+      const members = queryMembers(db, community.community_id);
+      const crossConnections = queryCrossConnections(db, community.community_id);
 
-    const content = renderSkillMarkdown(community, members, crossConnections, repoPath);
+      const content = renderSkillMarkdown(community, members, crossConnections, repoPath);
 
-    const kebab = toKebabName(community.label || `community-${community.community_id}`);
-    const filePath = path.join(skillsDir, `${kebab}.md`);
-    await fs.writeFile(filePath, content, 'utf-8');
-    filesWritten.push(filePath);
-  }
+      const kebab = toKebabName(community.label || `community-${community.community_id}`);
+      const filePath = path.join(skillsDir, `${kebab}.md`);
+      await fs.writeFile(filePath, content, 'utf-8');
+      filesWritten.push(filePath);
+    }
 
-  return { filesWritten, communityCount: communities.length };
+    return { filesWritten, communityCount: communities.length };
   } finally {
     closeDb(db);
   }

package/src/graph/regex-search.ts

@@ -48,20 +48,6 @@ export function regexSearchNodes(
   const results: RegexNodeMatch[] = [];
 
   for (const r of rows) {
-    const node: MonographNode = {
-      id: r.id,
-      label: r.label as MonographNode['label'],
-      name: r.name,
-      normLabel: r.norm_label,
-      filePath: r.file_path ?? undefined,
-      startLine: r.start_line ?? undefined,
-      endLine: r.end_line ?? undefined,
-      communityId: r.community_id ?? undefined,
-      isExported: r.is_exported === 1,
-      language: r.language ?? undefined,
-      properties: r.properties ? (JSON.parse(r.properties) as Record<string, unknown>) : undefined,
-    };
-
     for (const field of fields) {
       const value =
         field === 'name' ? r.name :
@@ -70,6 +56,19 @@ export function regexSearchNodes(
         r.label;
 
       if (value && re.test(value)) {
+        const node: MonographNode = {
+          id: r.id,
+          label: r.label as MonographNode['label'],
+          name: r.name,
+          normLabel: r.norm_label,
+          filePath: r.file_path ?? undefined,
+          startLine: r.start_line ?? undefined,
+          endLine: r.end_line ?? undefined,
+          communityId: r.community_id ?? undefined,
+          isExported: r.is_exported === 1,
+          language: r.language ?? undefined,
+          properties: r.properties ? (JSON.parse(r.properties) as Record<string, unknown>) : undefined,
+        };
         results.push({ node, field });
         break;
       }

package/src/graph/statistics.ts

@@ -27,14 +27,6 @@ function getGraph(db: MonographDb): Graph {
   return graph;
 }
 
-/**
- * Evict the cached graph for a given DB instance (call after writes).
- */
-export function invalidateGraphCache(db: MonographDb): void {
-  const key = (db as unknown as { name: string }).name ?? '__default__';
-  _graphCache.delete(key);
-}
-
 /**
  * Graph density: ratio of actual edges to maximum possible directed edges.
  * For a directed graph with n nodes: max = n * (n - 1).

package/src/pipeline/orchestrator.ts

@@ -132,6 +132,17 @@ async function buildAsyncLocked(
 
   const db = openDb(dbPath);
 
+  // The whole build is one SQL transaction: a phase throwing (e.g. issue
+  // #40's FK violation) used to leave whatever earlier phases had already
+  // autocommitted sitting in the DB, silently corrupting the index into a
+  // stale partial state that a later build wouldn't repair (cache hits skip
+  // re-scanning the files that would restore the missing rows). BEGIN/COMMIT/
+  // ROLLBACK are issued directly via db.exec() rather than better-sqlite3's
+  // `.transaction()` helper, which requires a synchronous callback — the
+  // phases below are async. This is still safe: every phase writes through
+  // this same single connection, so SQLite serializes them regardless of how
+  // the JS event loop interleaves the awaits between phases.
+  db.exec('BEGIN');
   try {
     const graph = new Graph({ multi: true, type: 'directed' });
     const ctx: PipelineContext = {
@@ -229,6 +240,13 @@ async function buildAsyncLocked(
       }
     }
     db.prepare("INSERT OR REPLACE INTO index_meta VALUES ('indexed_at', ?)").run(new Date().toISOString());
+    db.exec('COMMIT');
+  } catch (err) {
+    // Best-effort: if the connection is already broken (e.g. the failure was
+    // itself a corrupt-database error), rolling back can throw too — the
+    // original error is what matters and must not be masked by this one.
+    try { db.exec('ROLLBACK'); } catch { /* ignore */ }
+    throw err;
   } finally {
     closeDb(db);
   }

package/src/pipeline/phases/call-site-extractors.ts

@@ -7,6 +7,14 @@ export interface CallSite {
   form: 'method' | 'direct' | 'dynamic';
   receiverName?: string;
   methodName?: string;
+  /**
+   * Byte offset of the match in the source, used by scope resolution to find
+   * the function enclosing this call. Without it every CALLS edge is
+   * attributed to the containing File, which makes a function look "used" by
+   * its own file just for being declared there — see the dead-code masking
+   * described in graph/dead-code.ts.
+   */
+  offset?: number;
 }
 
 // ── Language keyword sets ────────────────────────────────────────────────────
@@ -71,13 +79,13 @@ function extractSimpleCallSites(
   const methodPattern = /(\w+)\.(\w+)\s*\(/g;
   let m: RegExpExecArray | null;
   while ((m = methodPattern.exec(source)) !== null) {
-    sites.push({ callerFileNodeId: fileNodeId, callerFilePath: filePath, calleeRaw: `${m[1]}.${m[2]}`, form: 'method', receiverName: m[1], methodName: m[2] });
+    sites.push({ offset: m.index, callerFileNodeId: fileNodeId, callerFilePath: filePath, calleeRaw: `${m[1]}.${m[2]}`, form: 'method', receiverName: m[1], methodName: m[2] });
   }
   const directPattern = new RegExp(`(?<![.[\\w])(${directCharClass})\\s*\\(`, 'g');
   while ((m = directPattern.exec(source)) !== null) {
     const name = m[1]!;
     if (keywords.has(name)) continue;
-    sites.push({ callerFileNodeId: fileNodeId, callerFilePath: filePath, calleeRaw: name, form: 'direct' });
+    sites.push({ offset: m.index, callerFileNodeId: fileNodeId, callerFilePath: filePath, calleeRaw: name, form: 'direct' });
   }
   return sites;
 }
@@ -112,44 +120,44 @@ export function extractCallSites(
     const methodPattern = /(\w+)\.(\w+)\s*(?:<[^>]*>\s*)?\(/g;
     let m: RegExpExecArray | null;
     while ((m = methodPattern.exec(source)) !== null) {
-      sites.push({ callerFileNodeId: fileNodeId, callerFilePath: filePath, calleeRaw: `${m[1]}.${m[2]}`, form: 'method', receiverName: m[1], methodName: m[2] });
+      sites.push({ offset: m.index, callerFileNodeId: fileNodeId, callerFilePath: filePath, calleeRaw: `${m[1]}.${m[2]}`, form: 'method', receiverName: m[1], methodName: m[2] });
     }
 
     const chainedPattern = /[)\]]\s*\.(\w+)\s*(?:<[^>]*>\s*)?\(/g;
     while ((m = chainedPattern.exec(source)) !== null) {
       const name = m[1];
       if (JS_KEYWORDS.has(name)) continue;
-      sites.push({ callerFileNodeId: fileNodeId, callerFilePath: filePath, calleeRaw: `?.${name}`, form: 'method', methodName: name });
+      sites.push({ offset: m.index, callerFileNodeId: fileNodeId, callerFilePath: filePath, calleeRaw: `?.${name}`, form: 'method', methodName: name });
     }
 
     const directPattern = /(?<![.[\w])([A-Za-z_$][\w$]*)\s*(?:<[^>]*>\s*)?\(/g;
     while ((m = directPattern.exec(source)) !== null) {
       const name = m[1];
       if (JS_KEYWORDS.has(name)) continue;
-      sites.push({ callerFileNodeId: fileNodeId, callerFilePath: filePath, calleeRaw: name, form: 'direct', methodName: name });
+      sites.push({ offset: m.index, callerFileNodeId: fileNodeId, callerFilePath: filePath, calleeRaw: name, form: 'direct', methodName: name });
     }
 
     const newPattern = /\bnew\s+([A-Z][\w$]*)\s*(?:<[^>]*>\s*)?\(/g;
     while ((m = newPattern.exec(source)) !== null) {
-      sites.push({ callerFileNodeId: fileNodeId, callerFilePath: filePath, calleeRaw: `new ${m[1]}`, form: 'direct', methodName: m[1] });
+      sites.push({ offset: m.index, callerFileNodeId: fileNodeId, callerFilePath: filePath, calleeRaw: `new ${m[1]}`, form: 'direct', methodName: m[1] });
     }
 
     const dynamicPattern = /\w+\s*\[[\w'"` ]+\]\s*\(/g;
     while ((m = dynamicPattern.exec(source)) !== null) {
-      sites.push({ callerFileNodeId: fileNodeId, callerFilePath: filePath, calleeRaw: m[0], form: 'dynamic' });
+      sites.push({ offset: m.index, callerFileNodeId: fileNodeId, callerFilePath: filePath, calleeRaw: m[0], form: 'dynamic' });
     }
   } else if (PY_EXTS.has(ext)) {
     const methodPattern = /(\w+)\.(\w+)\s*\(/g;
     let m: RegExpExecArray | null;
     while ((m = methodPattern.exec(source)) !== null) {
-      sites.push({ callerFileNodeId: fileNodeId, callerFilePath: filePath, calleeRaw: `${m[1]}.${m[2]}`, form: 'method', receiverName: m[1], methodName: m[2] });
+      sites.push({ offset: m.index, callerFileNodeId: fileNodeId, callerFilePath: filePath, calleeRaw: `${m[1]}.${m[2]}`, form: 'method', receiverName: m[1], methodName: m[2] });
     }
 
     const directPattern = /(?<![.[\w])([A-Za-z_][\w]*)\s*\(/g;
     while ((m = directPattern.exec(source)) !== null) {
       const name = m[1];
       if (PY_KEYWORDS.has(name)) continue;
-      sites.push({ callerFileNodeId: fileNodeId, callerFilePath: filePath, calleeRaw: name, form: 'direct', methodName: name });
+      sites.push({ offset: m.index, callerFileNodeId: fileNodeId, callerFilePath: filePath, calleeRaw: name, form: 'direct', methodName: name });
     }
   }
 

package/src/pipeline/phases/module-resolution.ts

@@ -1,6 +1,6 @@
 // ── Module resolution for import specifiers ──────────────────────────────────
 
-import { readFileSync, existsSync } from 'fs';
+import { readFileSync, existsSync, readdirSync } from 'fs';
 import { join, extname, dirname, resolve as resolvePath } from 'path';
 import type { MonographNode } from '../../types.js';
 import { TS_JS_EXTS, CJS_MJS_EXTS } from './call-site-extractors.js';
@@ -40,7 +40,7 @@ export function buildWorkspacePackageMap(repoPath: string): Map<string, string>
     const scanDirs = (base: string, depth: number) => {
       if (depth > 2) return;
       let entries: string[];
-      try { entries = require('fs').readdirSync(base); } catch { return; }
+      try { entries = readdirSync(base); } catch { return; }
       for (const e of entries) {
         const full = join(base, e);
         const pkgJson = join(full, 'package.json');

package/src/pipeline/phases/scope-resolution.ts

@@ -56,6 +56,86 @@ function buildFunctionIndex(ctx: PipelineContext): {
   return { byFilePath, nameCounts };
 }
 
+/** A callable node with a known line range, used to attribute a call to its caller. */
+interface EnclosingSymbol {
+  id: string;
+  startLine: number;
+  endLine: number;
+}
+
+/**
+ * Line ranges of every callable, grouped by file, innermost-first.
+ *
+ * Call edges are attributed to the enclosing function rather than the file.
+ * Attributing them to the file makes a function appear "used" by its own file
+ * purely because it is declared there, which silently disabled dead-export
+ * detection: `detectDeadCodeNodes` rejects any candidate with an inbound CALLS
+ * edge, and that self-edge always existed.
+ */
+function buildEnclosingIndex(ctx: PipelineContext): Map<string, EnclosingSymbol[]> {
+  const byFile = new Map<string, EnclosingSymbol[]>();
+  if (!ctx.db) return byFile;
+
+  const rows = ctx.db
+    .prepare(
+      `SELECT id, file_path, start_line, end_line FROM nodes
+        WHERE label IN ('Function', 'Method', 'Constructor')
+          AND file_path IS NOT NULL AND start_line IS NOT NULL AND end_line IS NOT NULL`
+    )
+    .all() as { id: string; file_path: string; start_line: number; end_line: number }[];
+
+  for (const row of rows) {
+    let list = byFile.get(row.file_path);
+    if (!list) { list = []; byFile.set(row.file_path, list); }
+    list.push({ id: row.id, startLine: row.start_line, endLine: row.end_line });
+  }
+
+  // Narrowest range first, so the first containing match is the innermost
+  // scope — a call inside a closure belongs to the closure, not the function
+  // that happens to wrap it.
+  for (const list of byFile.values()) {
+    list.sort((a, b) => (a.endLine - a.startLine) - (b.endLine - b.startLine));
+  }
+
+  return byFile;
+}
+
+/** Line-start offsets, for turning a match offset into a 1-based line number. */
+function buildLineOffsets(source: string): number[] {
+  const offsets = [0];
+  for (let i = 0; i < source.length; i++) {
+    if (source.charCodeAt(i) === 10) offsets.push(i + 1);
+  }
+  return offsets;
+}
+
+function lineAtOffset(lineOffsets: number[], offset: number): number {
+  let lo = 0, hi = lineOffsets.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (lineOffsets[mid]! <= offset) lo = mid; else hi = mid - 1;
+  }
+  return lo + 1;
+}
+
+/**
+ * The innermost callable containing `offset`, or null when the call sits at
+ * module top level — which is genuinely file-scoped, so the file node stays
+ * the correct source for those.
+ */
+function findEnclosingSymbolId(
+  enclosing: EnclosingSymbol[] | undefined,
+  lineOffsets: number[],
+  offset: number | undefined,
+): string | null {
+  if (!enclosing || enclosing.length === 0 || offset === undefined) return null;
+  const line = lineAtOffset(lineOffsets, offset);
+  for (const sym of enclosing) {
+    if (line >= sym.startLine && line <= sym.endLine) return sym.id;
+  }
+  return null;
+}
+
 // ── Target resolution ────────────────────────────────────────────────────────
 
 function pickBestId(ids: string[], site: CallSite): string | null {
@@ -226,6 +306,7 @@ export const scopeResolutionPhase: PipelinePhase<ScopeResolutionOutput> = {
 
     const allImportMaps = buildAllImportMapsFromSource(ctx.repoPath, fileNodesByPath, fileContents);
     const { byFilePath: fnIndex, nameCounts } = buildFunctionIndex(ctx);
+    const enclosingIndex = buildEnclosingIndex(ctx);
 
     const edgeStmts = ctx.db ? prepareEdgeStmts(ctx.db) : null;
     const resolveAllCalls = ctx.db?.transaction(() => {
@@ -243,6 +324,8 @@ export const scopeResolutionPhase: PipelinePhase<ScopeResolutionOutput> = {
         }
 
         const callSites = extractCallSites(source, filePath, fileNode.id, ext);
+        const lineOffsets = buildLineOffsets(source);
+        const enclosing = enclosingIndex.get(filePath);
         const importMap = getImportMap(allImportMaps, fileNode.id);
         const ctorMap = (TS_JS_EXTS.has(ext) || CJS_MJS_EXTS.has(ext)) ? extractConstructorAssignments(source) : undefined;
         const importedFiles = [...new Set(importMap.values())];
@@ -260,7 +343,12 @@ export const scopeResolutionPhase: PipelinePhase<ScopeResolutionOutput> = {
             ambiguous++;
           }
 
-          const result = edgeStmts ? emitEdge(edgeStmts, site.callerFileNodeId, resolved.targetId) : 'skipped';
+          // Attribute the call to the function it sits in; fall back to the
+          // file node for genuine module-top-level calls.
+          const sourceId =
+            findEnclosingSymbolId(enclosing, lineOffsets, site.offset) ?? site.callerFileNodeId;
+
+          const result = edgeStmts ? emitEdge(edgeStmts, sourceId, resolved.targetId) : 'skipped';
           if (result === 'inserted' || result === 'upgraded') {
             resolvedEdges++;
           }

package/src/registry/repo-registry.ts

@@ -4,7 +4,7 @@
  * Persists at ~/.monograph/registry.json and tracks all repos indexed by monograph.
  */
 
-import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'fs';
+import { mkdirSync, readFileSync, writeFileSync, existsSync, renameSync } from 'fs';
 import { join, basename, dirname } from 'path';
 import { homedir } from 'os';
 
@@ -67,7 +67,6 @@ export function saveRegistry(registry: RepoRegistry): void {
   const tmpPath = registryPath + '.tmp';
   writeFileSync(tmpPath, JSON.stringify(registry, null, 2), 'utf8');
   // Rename is atomic on POSIX systems
-  const { renameSync } = require('fs') as typeof import('fs');
   renameSync(tmpPath, registryPath);
 }
 

package/vitest.config.ts

@@ -6,8 +6,15 @@ export default defineConfig({
     include: ['__tests__/**/*.test.ts', 'src/__tests__/**/*.test.ts'],
     exclude: ['node_modules', 'dist', '**/._*'],
     globals: true,
+    // Off by default to keep the edit/test loop fast; run
+    // `npm run test:coverage` (or pass --coverage) to measure.
     coverage: {
       enabled: false,
+      provider: 'v8',
+      reporter: ['text-summary', 'json-summary', 'html'],
+      reportsDirectory: './coverage',
+      include: ['src/**/*.ts'],
+      exclude: ['src/**/*.test.ts', 'src/__tests__/**', 'src/**/*.d.ts'],
     },
   },
 });