@monoes/monomindcli 2.0.3 → 2.1.0

package/dist/src/mcp-tools/monograph-tools.js

@@ -19,23 +19,36 @@ function _isValidDb(p) {
         return false;
     }
 }
-function getDbPath() {
-    const cwd = getProjectCwd();
+/**
+ * Resolve the monograph DB path for a given repo root (defaults to project cwd).
+ * Falls back to searching up to the git root when the DB isn't directly under
+ * `<cwd>/.monomind` — e.g. when called from a subdirectory of the repo. Only
+ * the no-arg (project cwd) form is cached; explicit `repoPath` overrides are
+ * cheap one-off lookups (staleness checks with a user-supplied path) so caching
+ * them isn't worth the invalidation complexity.
+ */
+function getDbPath(repoPathOverride) {
+    const cwd = repoPathOverride ?? getProjectCwd();
+    const useCache = repoPathOverride === undefined;
     // Invalidate cache when project root changes (e.g. MONOMIND_CWD set after initialize)
-    if (_cachedDbPath && _cachedCwd === cwd)
+    if (useCache && _cachedDbPath && _cachedCwd === cwd)
         return _cachedDbPath;
-    _cachedCwd = cwd;
-    _cachedDbPath = undefined;
+    if (useCache) {
+        _cachedCwd = cwd;
+        _cachedDbPath = undefined;
+    }
     const direct = join(cwd, '.monomind', 'monograph.db');
     if (_isValidDb(direct)) {
-        _cachedDbPath = direct;
+        if (useCache)
+            _cachedDbPath = direct;
         return direct;
     }
     try {
         const root = execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf8' }).trim();
         const candidate = join(root, '.monomind', 'monograph.db');
         if (_isValidDb(candidate)) {
-            _cachedDbPath = candidate;
+            if (useCache)
+                _cachedDbPath = candidate;
             return candidate;
         }
     }
@@ -46,13 +59,6 @@ function getDbPath() {
 function text(t) {
     return { content: [{ type: 'text', text: t }] };
 }
-function ensureDbExists() {
-    const p = getDbPath();
-    if (!_isValidDb(p)) {
-        throw new Error(`Monograph index not built yet. Run monograph_build first (path: ${p}).`);
-    }
-    return p;
-}
 // ── Active watcher registry ──────────────────────────────────────────────────
 const _activeWatchers = new Map();
 function applyPprRerank(db, seedNodes, damping, maxResults) {
@@ -577,9 +583,13 @@ function taskRelevance(task, nodeText) {
     return taskTerms.filter(t => txt.includes(t)).length / taskTerms.length;
 }
 // ── monograph_visualize ───────────────────────────────────────────────────────
+// Columns needed to render/export the graph — deliberately excludes `embedding`,
+// which can be several KB per node (384D vectors) and would otherwise bloat
+// tool-result payloads and written files by many MB.
+const NODE_RENDER_COLUMNS = 'id, label, name, norm_label, file_path, start_line, end_line, community_id, is_exported, language, properties';
 const monographVisualizeTool = {
     name: 'monograph_visualize',
-    description: 'Render the knowledge graph as HTML (default), SVG, or JSON.',
+    description: 'Render the knowledge graph as HTML (default), SVG, or JSON. Writes output to a file under .monomind/visualize/ and returns the file path (output can be multi-MB at the max node count, too large to return inline).',
     inputSchema: {
         type: 'object',
         properties: {
@@ -589,6 +599,7 @@ const monographVisualizeTool = {
     },
     handler: async (input) => {
         const { openDb, closeDb, toJson, toHtml, toSvg } = await import('@monoes/monograph');
+        const { writeFileSync, mkdirSync } = await import('fs');
         const db = openDb(getDbPath());
         try {
             // Cap maxNodes: passed to SQL LIMIT clause for both nodes (n) and edges
@@ -598,7 +609,7 @@ const monographVisualizeTool = {
             const limit = Number.isFinite(rawMaxNodes) && rawMaxNodes > 0
                 ? Math.min(Math.floor(rawMaxNodes), MAX_EXPORT_NODES)
                 : 500;
-            const nodes = db.prepare('SELECT * FROM nodes LIMIT ?').all(limit);
+            const nodes = db.prepare(`SELECT ${NODE_RENDER_COLUMNS} FROM nodes LIMIT ?`).all(limit);
             // Only include edges where both endpoints are in the visible node set
             const edges = db.prepare(`
         SELECT e.* FROM edges e
@@ -607,11 +618,15 @@ const monographVisualizeTool = {
         LIMIT ?
       `).all(limit, limit, limit * 3);
             const fmt = input.format ?? 'html';
-            if (fmt === 'json')
-                return text(toJson(nodes, edges));
-            if (fmt === 'svg')
-                return text(toSvg(nodes, edges));
-            return text(toHtml(nodes, edges));
+            const rendered = fmt === 'json' ? toJson(nodes, edges)
+                : fmt === 'svg' ? toSvg(nodes, edges)
+                    : toHtml(nodes, edges);
+            const ext = fmt === 'json' ? 'json' : fmt === 'svg' ? 'svg' : 'html';
+            const outDir = resolve(join(getProjectCwd(), '.monomind', 'visualize'));
+            mkdirSync(outDir, { recursive: true });
+            const outPath = join(outDir, `graph-${Date.now()}.${ext}`);
+            writeFileSync(outPath, rendered);
+            return text(`Visualization written to ${outPath} (${nodes.length} nodes, ${edges.length} edges)${ext === 'html' ? '\nNote: HTML uses the vis-network CDN script and requires network access to render.' : ''}`);
         }
         finally {
             closeDb(db);
@@ -700,7 +715,8 @@ const monographReportTool = {
                     return `${i + 1}. **${n.name}** (${n.label}) — degree ${n.degree}${loc ? `  \`${loc}\`` : ''}`;
                 }),
             ].join('\n');
-            const outPath = resolve(input.path ?? join(getProjectCwd(), '.monomind', 'GRAPH_REPORT.md'));
+            const rawOutPath = input.path ?? join(getProjectCwd(), '.monomind', 'GRAPH_REPORT.md');
+            const outPath = resolve(getProjectCwd(), rawOutPath);
             const allowedRoot = resolve(getProjectCwd());
             if (outPath !== allowedRoot && !outPath.startsWith(allowedRoot + sep)) {
                 return text(`Error: path must be within the project directory (${allowedRoot})`);
@@ -725,7 +741,10 @@ let _buildInProgress = false;
 async function computeCommitsBehind(repoPath) {
     const { openDb, closeDb } = await import('@monoes/monograph');
     const { execSync } = await import('child_process');
-    const db = openDb(join(repoPath, '.monomind', 'monograph.db'));
+    const dbPath = getDbPath(repoPath);
+    if (!_isValidDb(dbPath))
+        return null;
+    const db = openDb(dbPath, { fileMustExist: true });
     try {
         const meta = db.prepare("SELECT value FROM index_meta WHERE key = 'last_commit_hash'").get() ?? db.prepare("SELECT value FROM index_meta WHERE key = 'lastCommit'").get();
         const lastCommit = meta?.value ?? null;
@@ -929,11 +948,13 @@ const monographExportTool = {
         const { writeFileSync, mkdirSync } = await import('fs');
         const db = openDb(getDbPath());
         try {
-            const nodes = db.prepare('SELECT * FROM nodes').all();
+            // Exclude `embedding` — a several-KB-per-node vector column that would
+            // otherwise bloat exported files by many MB for no rendering benefit.
+            const nodes = db.prepare(`SELECT ${NODE_RENDER_COLUMNS} FROM nodes`).all();
             const edges = db.prepare('SELECT * FROM edges').all();
             const fmt = input.format;
             const requestedOut = input.outputPath ?? join(getProjectCwd(), '.monomind', 'export');
-            const outDir = resolve(requestedOut);
+            const outDir = resolve(getProjectCwd(), requestedOut);
             const allowedRoot = resolve(getProjectCwd());
             if (outDir !== allowedRoot && !outDir.startsWith(allowedRoot + sep)) {
                 return text(`Error: outputPath must be within the project directory (${allowedRoot})`);
@@ -1072,8 +1093,10 @@ const monographImpactTool = {
             const impactPath = typeof rawImpactPath === 'string' && rawImpactPath.length > MAX_IMPACT_PATH_LEN
                 ? rawImpactPath.slice(0, MAX_IMPACT_PATH_LEN) : rawImpactPath;
             const rawDepth = input.depth;
-            const depth = typeof rawDepth === 'number' && Number.isFinite(rawDepth) && rawDepth > 0
-                ? Math.min(Math.floor(rawDepth), 6) : rawDepth;
+            const depth = rawDepth === undefined
+                ? undefined
+                : (typeof rawDepth === 'number' && Number.isFinite(rawDepth) && rawDepth > 0
+                    ? Math.min(Math.floor(rawDepth), 6) : 3);
             const result = getMonographImpact(db, {
                 name: impactName,
                 filePath: impactPath,
@@ -1737,10 +1760,10 @@ const monographInstallSkillsTool = {
             return text(`Invalid platform "${platform}". Must be one of: ${validPlatforms.join(', ')}`);
         }
         // Load community data from graph
-        const dbPath = join(repoPath, '.monomind', 'monograph.db');
+        const dbPath = getDbPath(repoPath);
         let db;
         try {
-            db = openDb(dbPath);
+            db = openDb(dbPath, { fileMustExist: true });
         }
         catch {
             return text('Graph not built yet. Run monograph_build first.');
@@ -1846,21 +1869,19 @@ const monographListReposTool = {
 // ── monograph_group_contracts ─────────────────────────────────────────────────
 const monographGroupContractsTool = {
     name: 'monograph_group_contracts',
-    description: 'List public API contracts (exported symbols, interfaces, and types) for all groups defined in .monograph/groups.json.',
+    description: 'List public API contracts (exported symbols, interfaces, and types) for all groups defined in group.yaml.',
     inputSchema: {
         type: 'object',
         properties: {
-            repoPath: { type: 'string', description: 'Absolute path to the repository (defaults to cwd).' },
+            configPath: { type: 'string', description: 'Path to group.yaml (defaults to group.yaml in project cwd)' },
         },
     },
     handler: async (input) => {
         const { getGroupContracts } = await import('./monograph-compat.js');
-        const { join } = await import('path');
-        const repoPath = input.repoPath ?? getProjectCwd();
-        const configPath = join(repoPath, '.monograph', 'groups.json');
+        const configPath = input.configPath ?? join(getProjectCwd(), 'group.yaml');
         const contracts = await getGroupContracts(configPath);
         if (contracts.length === 0)
-            return text('No contracts found. Ensure groups are defined in .monograph/groups.json.');
+            return text(`No contracts found. Ensure groups are defined in ${configPath}.`);
         const lines = contracts.map(c => `[${c.groupName}] ${c.symbol} — ${c.filePath}:${c.line}`);
         return text(lines.join('\n'));
     },
@@ -1872,14 +1893,12 @@ const monographGroupStatusTool = {
     inputSchema: {
         type: 'object',
         properties: {
-            repoPath: { type: 'string', description: 'Absolute path to the repository (defaults to cwd).' },
+            configPath: { type: 'string', description: 'Path to group.yaml (defaults to group.yaml in project cwd)' },
         },
     },
     handler: async (input) => {
         const { getGroupStatus } = await import('./monograph-compat.js');
-        const { join } = await import('path');
-        const repoPath = input.repoPath ?? getProjectCwd();
-        const configPath = join(repoPath, '.monograph', 'groups.json');
+        const configPath = input.configPath ?? join(getProjectCwd(), 'group.yaml');
         const status = await getGroupStatus(configPath);
         const lines = [`Groups: ${status.totalGroups} (${status.indexedGroups} indexed, ${status.stalledGroups} stalled)`];
         for (const g of status.groups) {
@@ -1954,10 +1973,10 @@ const monographDeadCodeTool = {
         const repoPath = input.path ?? getProjectCwd();
         const cats = input.categories ?? ['dead-functions', 'orphan-files', 'stale-dist'];
         const result = {};
-        const dbPath = join(repoPath, '.monomind', 'monograph.db');
+        const dbPath = getDbPath(repoPath);
         let db = null;
         try {
-            db = openDb(dbPath);
+            db = openDb(dbPath, { fileMustExist: true });
         }
         catch {
             return text(JSON.stringify({ error: 'No monograph index found. Run monograph_build first.' }));
@@ -1997,9 +2016,12 @@ const monographDeadCodeTool = {
           FROM nodes n
           WHERE n.label = 'File'
             AND (SELECT COUNT(*) FROM edges e WHERE e.target_id = n.id AND e.relation = 'IMPORTS') = 0
-            AND n.file_path NOT LIKE '%test%'
+            AND n.file_path NOT LIKE '%/test/%'
+            AND n.file_path NOT LIKE '%/tests/%'
+            AND n.file_path NOT LIKE '%.test.%'
             AND n.file_path NOT LIKE '%__tests__%'
-            AND n.file_path NOT LIKE '%spec%'
+            AND n.file_path NOT LIKE '%/spec/%'
+            AND n.file_path NOT LIKE '%.spec.%'
             AND n.file_path NOT LIKE '%/index.%'
             AND n.file_path NOT LIKE 'bin/%'
             AND n.file_path NOT LIKE 'scripts/%'