@monoes/monograph 1.0.0 → 1.2.0

package/src/__tests__/ingest/query-memory.test.ts

@@ -0,0 +1,123 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { saveQueryResult } from '../../ingest/query-memory.js';
+import { mkdtempSync, readFileSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+function makeTempDir() {
+  return mkdtempSync(join(tmpdir(), 'monograph-qmem-test-'));
+}
+
+describe('saveQueryResult', () => {
+  const dirs: string[] = [];
+  afterEach(() => {
+    for (const d of dirs) {
+      try { rmSync(d, { recursive: true }); } catch { /* ignore */ }
+    }
+    dirs.length = 0;
+  });
+
+  it('creates the memory directory if it does not exist', () => {
+    const memDir = join(makeTempDir(), 'sub', 'memory');
+    dirs.push(memDir.split('/').slice(0, -2).join('/'));
+    saveQueryResult({ question: 'What is X?', answer: 'X is Y.', memoryDir: memDir });
+    const { existsSync } = require('fs');
+    expect(existsSync(memDir)).toBe(true);
+  });
+
+  it('writes a Markdown file with YAML front-matter', () => {
+    const memDir = makeTempDir();
+    dirs.push(memDir);
+    const result = saveQueryResult({ question: 'What is X?', answer: 'X is Y.', memoryDir: memDir });
+    const content = readFileSync(result.filePath, 'utf-8');
+    expect(content).toContain('---');
+    expect(content).toContain('type: "query"');
+    expect(content).toContain('question: "What is X?"');
+    expect(content).toContain('contributor: "monograph"');
+    expect(content).toContain('# Q: What is X?');
+    expect(content).toContain('X is Y.');
+  });
+
+  it('includes a date field in the front-matter', () => {
+    const memDir = makeTempDir();
+    dirs.push(memDir);
+    const result = saveQueryResult({ question: 'Test?', answer: 'Yes.', memoryDir: memDir });
+    const content = readFileSync(result.filePath, 'utf-8');
+    expect(content).toMatch(/date: "\d{4}-\d{2}-\d{2}/);
+  });
+
+  it('includes source_nodes in front-matter when provided', () => {
+    const memDir = makeTempDir();
+    dirs.push(memDir);
+    const result = saveQueryResult({
+      question: 'Who calls auth?',
+      answer: 'login calls auth.',
+      memoryDir: memDir,
+      sourceNodes: ['login', 'auth'],
+    });
+    const content = readFileSync(result.filePath, 'utf-8');
+    expect(content).toContain('source_nodes:');
+    expect(content).toContain('"login"');
+    expect(content).toContain('"auth"');
+  });
+
+  it('includes Source Nodes section in body when sourceNodes provided', () => {
+    const memDir = makeTempDir();
+    dirs.push(memDir);
+    const result = saveQueryResult({
+      question: 'Q',
+      answer: 'A',
+      memoryDir: memDir,
+      sourceNodes: ['nodeA'],
+    });
+    const content = readFileSync(result.filePath, 'utf-8');
+    expect(content).toContain('## Source Nodes');
+    expect(content).toContain('- nodeA');
+  });
+
+  it('limits source_nodes to 10 entries in front-matter', () => {
+    const memDir = makeTempDir();
+    dirs.push(memDir);
+    const manyNodes = Array.from({ length: 15 }, (_, i) => `node${i}`);
+    const result = saveQueryResult({
+      question: 'Q',
+      answer: 'A',
+      memoryDir: memDir,
+      sourceNodes: manyNodes,
+    });
+    const content = readFileSync(result.filePath, 'utf-8');
+    // front-matter line has at most 10 quoted node names
+    const fmLine = content.split('\n').find(l => l.startsWith('source_nodes:'))!;
+    const matches = fmLine.match(/"node\d+"/g) ?? [];
+    expect(matches.length).toBeLessThanOrEqual(10);
+  });
+
+  it('uses custom queryType in front-matter', () => {
+    const memDir = makeTempDir();
+    dirs.push(memDir);
+    const result = saveQueryResult({ question: 'Q', answer: 'A', memoryDir: memDir, queryType: 'impact' });
+    const content = readFileSync(result.filePath, 'utf-8');
+    expect(content).toContain('type: "impact"');
+  });
+
+  it('returns the written file path and writtenAt timestamp', () => {
+    const memDir = makeTempDir();
+    dirs.push(memDir);
+    const before = new Date().toISOString();
+    const result = saveQueryResult({ question: 'Q', answer: 'A', memoryDir: memDir });
+    const after = new Date().toISOString();
+    expect(result.filePath).toContain(memDir);
+    expect(result.filePath.endsWith('.md')).toBe(true);
+    expect(result.writtenAt >= before).toBe(true);
+    expect(result.writtenAt <= after).toBe(true);
+  });
+
+  it('escapes double quotes in the question', () => {
+    const memDir = makeTempDir();
+    dirs.push(memDir);
+    const result = saveQueryResult({ question: 'Say "hello"?', answer: 'Hi.', memoryDir: memDir });
+    const content = readFileSync(result.filePath, 'utf-8');
+    // YAML value should escape the inner quotes
+    expect(content).toContain('\\"hello\\"');
+  });
+});

package/src/__tests__/ingest/transcribe.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest';
+import { isUrl, buildWhisperPrompt, VIDEO_EXTENSIONS } from '../../ingest/transcribe.js';
+
+describe('isUrl', () => {
+  it('returns true for http:// URLs', () => {
+    expect(isUrl('http://example.com/video.mp4')).toBe(true);
+  });
+
+  it('returns true for https:// URLs', () => {
+    expect(isUrl('https://www.youtube.com/watch?v=abc')).toBe(true);
+  });
+
+  it('returns true for www. prefixed strings', () => {
+    expect(isUrl('www.youtube.com/watch?v=abc')).toBe(true);
+  });
+
+  it('returns false for local file paths', () => {
+    expect(isUrl('/path/to/video.mp4')).toBe(false);
+    expect(isUrl('./relative/video.mp4')).toBe(false);
+    expect(isUrl('video.mp4')).toBe(false);
+  });
+});
+
+describe('buildWhisperPrompt', () => {
+  it('returns fallback prompt for empty labels', () => {
+    const prompt = buildWhisperPrompt([]);
+    expect(prompt).toContain('punctuation');
+  });
+
+  it('includes top 5 labels in the prompt', () => {
+    const labels = ['React', 'TypeScript', 'GraphQL', 'Node.js', 'Webpack', 'Babel'];
+    const prompt = buildWhisperPrompt(labels);
+    expect(prompt).toContain('React');
+    expect(prompt).toContain('TypeScript');
+    expect(prompt).toContain('GraphQL');
+    // 6th label should not appear
+    expect(prompt).not.toContain('Babel');
+  });
+
+  it('produces a domain hint in the expected format', () => {
+    const prompt = buildWhisperPrompt(['Auth', 'JWT']);
+    expect(prompt).toMatch(/Technical discussion about Auth, JWT/);
+  });
+});
+
+describe('VIDEO_EXTENSIONS', () => {
+  it('includes common video extensions', () => {
+    expect(VIDEO_EXTENSIONS.has('.mp4')).toBe(true);
+    expect(VIDEO_EXTENSIONS.has('.mov')).toBe(true);
+    expect(VIDEO_EXTENSIONS.has('.webm')).toBe(true);
+  });
+
+  it('includes common audio extensions', () => {
+    expect(VIDEO_EXTENSIONS.has('.mp3')).toBe(true);
+    expect(VIDEO_EXTENSIONS.has('.wav')).toBe(true);
+    expect(VIDEO_EXTENSIONS.has('.m4a')).toBe(true);
+  });
+});

package/src/__tests__/ingest/url-ingest.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect, vi } from 'vitest';
+import { ingestUrl, classifyUrlType } from '../../ingest/url-ingest.js';
+
+describe('classifyUrlType', () => {
+  it('detects arxiv', () => {
+    expect(classifyUrlType('https://arxiv.org/abs/2401.00001')).toBe('paper');
+  });
+  it('detects github', () => {
+    expect(classifyUrlType('https://github.com/user/repo')).toBe('github');
+  });
+  it('detects youtube', () => {
+    expect(classifyUrlType('https://www.youtube.com/watch?v=abc')).toBe('video');
+  });
+  it('defaults to webpage', () => {
+    expect(classifyUrlType('https://example.com/article')).toBe('webpage');
+  });
+});
+
+describe('ingestUrl', () => {
+  it('returns IngestResult with id, type, and url', async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      text: async () => '<html><title>Test Page</title><body>Hello world content here</body></html>',
+      headers: { get: (_h: string) => 'text/html' },
+    });
+    const result = await ingestUrl('https://example.com/page', { fetch: mockFetch as any });
+    expect(result.url).toBe('https://example.com/page');
+    expect(result.type).toBe('webpage');
+    expect(typeof result.id).toBe('string');
+    expect(result.title).toBeTruthy();
+  });
+
+  it('blocks private URLs', async () => {
+    await expect(ingestUrl('http://localhost/admin', {})).rejects.toThrow();
+  });
+
+  it('blocks oversized responses', async () => {
+    const bigBody = 'x'.repeat(11 * 1024 * 1024);
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      text: async () => bigBody,
+      headers: { get: (h: string) => h === 'content-length' ? String(bigBody.length) : 'text/html' },
+    });
+    await expect(
+      ingestUrl('https://example.com/big', { fetch: mockFetch as any, maxBytes: 10 * 1024 * 1024 })
+    ).rejects.toThrow(/too large/i);
+  });
+});

package/src/__tests__/mcp-resources/repo-context-resource.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest';
+import Database from 'better-sqlite3';
+import { repoContextResource } from '../../mcp-resources/repo-context-resource.js';
+
+function makeDb(): Database.Database {
+  const db = new Database(':memory:');
+  db.exec(`
+    CREATE TABLE nodes (id TEXT PRIMARY KEY, name TEXT, label TEXT, file_path TEXT, start_line INTEGER, end_line INTEGER, community_id INTEGER);
+    CREATE TABLE edges (id TEXT PRIMARY KEY, source_id TEXT, target_id TEXT, relation TEXT, confidence TEXT, confidence_score REAL);
+    CREATE TABLE index_meta (key TEXT PRIMARY KEY, value TEXT);
+    INSERT INTO nodes VALUES ('n1', 'UserService', 'Class', '/app/user.ts', 1, 50, 1);
+    INSERT INTO index_meta VALUES ('indexed_at', '2026-05-01T00:00:00.000Z');
+  `);
+  return db;
+}
+
+describe('repoContextResource', () => {
+  it('has uri and handler', () => {
+    expect(repoContextResource.uri).toBeDefined();
+    expect(typeof repoContextResource.handler).toBe('function');
+  });
+
+  it('handler returns node count, edge count, indexedAt', () => {
+    const db = makeDb();
+    const result = repoContextResource.handler(db) as any;
+    expect(result.nodeCount).toBe(1);
+    expect(result.edgeCount).toBe(0);
+    expect(result.indexedAt).toBe('2026-05-01T00:00:00.000Z');
+  });
+
+  it('result includes available tools list', () => {
+    const db = makeDb();
+    const result = repoContextResource.handler(db) as any;
+    expect(Array.isArray(result.availableTools)).toBe(true);
+    expect(result.availableTools.length).toBeGreaterThan(0);
+  });
+});

package/src/__tests__/mcp-resources/repos-resource.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest';
+import Database from 'better-sqlite3';
+import { reposResource } from '../../mcp-resources/repos-resource.js';
+import { namedClusterResource } from '../../mcp-resources/named-cluster-resource.js';
+import { namedProcessResource } from '../../mcp-resources/named-process-resource.js';
+
+function makeDb(): Database.Database {
+  const db = new Database(':memory:');
+  db.exec(`
+    CREATE TABLE nodes (id TEXT PRIMARY KEY, name TEXT, label TEXT, file_path TEXT, start_line INTEGER, end_line INTEGER, community_id INTEGER);
+    CREATE TABLE communities (id INTEGER PRIMARY KEY, label TEXT);
+    INSERT INTO communities VALUES (1, 'auth-cluster');
+    INSERT INTO nodes VALUES ('n1', 'UserService', 'Class', '/app/user.ts', 1, 50, 1);
+    INSERT INTO nodes VALUES ('n2', 'main', 'Function', '/app/main.ts', 1, 20, null);
+  `);
+  return db;
+}
+
+describe('reposResource', () => {
+  it('has uri and handler defined', () => {
+    expect(reposResource.uri).toBeDefined();
+    expect(typeof reposResource.handler).toBe('function');
+  });
+
+  it('handler returns an array', () => {
+    const db = makeDb();
+    const result = reposResource.handler(db);
+    expect(Array.isArray(result)).toBe(true);
+  });
+});
+
+describe('namedClusterResource', () => {
+  it('has uri and handler defined', () => {
+    expect(namedClusterResource.uri).toBeDefined();
+    expect(typeof namedClusterResource.handler).toBe('function');
+  });
+
+  it('handler returns cluster data for known label', () => {
+    const db = makeDb();
+    const result = namedClusterResource.handler(db, { name: 'auth-cluster' }) as any;
+    expect(result).not.toBeNull();
+    expect(result.label).toBe('auth-cluster');
+    expect(Array.isArray(result.members)).toBe(true);
+  });
+
+  it('returns null for unknown cluster', () => {
+    const db = makeDb();
+    const result = namedClusterResource.handler(db, { name: 'nonexistent' });
+    expect(result).toBeNull();
+  });
+});
+
+describe('namedProcessResource', () => {
+  it('has uri and handler defined', () => {
+    expect(namedProcessResource.uri).toBeDefined();
+    expect(typeof namedProcessResource.handler).toBe('function');
+  });
+
+  it('handler returns node for known name', () => {
+    const db = makeDb();
+    const result = namedProcessResource.handler(db, { name: 'UserService' }) as any;
+    expect(result).not.toBeNull();
+    expect(result.name).toBe('UserService');
+  });
+
+  it('returns null for unknown name', () => {
+    const db = makeDb();
+    const result = namedProcessResource.handler(db, { name: 'nonexistent' });
+    expect(result).toBeNull();
+  });
+});

package/src/__tests__/mcp-resources/wiki-resource.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest';
+import Database from 'better-sqlite3';
+import { wikiResource, wikiPageResource } from '../../mcp-resources/wiki-resource.js';
+
+function makeDb(): Database.Database {
+  const db = new Database(':memory:');
+  db.exec(`
+    CREATE TABLE wiki_pages (
+      community_id TEXT PRIMARY KEY,
+      content TEXT NOT NULL,
+      generated_at TEXT NOT NULL
+    );
+    INSERT INTO wiki_pages VALUES ('1', '# Auth cluster\nHandles user authentication.', '2026-05-01T00:00:00Z');
+    INSERT INTO wiki_pages VALUES ('2', '# Data cluster\nManages database access.', '2026-05-01T00:00:00Z');
+  `);
+  return db;
+}
+
+describe('wikiResource (list)', () => {
+  it('has correct URI and name', () => {
+    expect(wikiResource.uri).toBe('monograph://wiki');
+    expect(wikiResource.name).toBe('wiki');
+  });
+
+  it('handler returns all wiki pages', () => {
+    const db = makeDb();
+    const result = wikiResource.handler(db) as any[];
+    expect(Array.isArray(result)).toBe(true);
+    expect(result.length).toBe(2);
+    expect(result[0].communityId).toBeDefined();
+    expect(result[0].content).toBeDefined();
+  });
+});
+
+describe('wikiPageResource (single)', () => {
+  it('has URI with {communityId} template', () => {
+    expect(wikiPageResource.uri).toContain('{communityId}');
+  });
+
+  it('returns a single wiki page by communityId', () => {
+    const db = makeDb();
+    const result = wikiPageResource.handler(db, { communityId: '1' }) as any;
+    expect(result).not.toBeNull();
+    expect(result.content).toContain('Auth cluster');
+  });
+
+  it('returns null for unknown communityId', () => {
+    const db = makeDb();
+    const result = wikiPageResource.handler(db, { communityId: '999' });
+    expect(result).toBeNull();
+  });
+});

package/src/__tests__/mcp-tools/embed.test.ts

@@ -0,0 +1,13 @@
+import { describe, it, expect } from 'vitest';
+
+describe('embed tool exports', () => {
+  it('runEmbed is exported from mcp-tools index', async () => {
+    const mod = await import('../../mcp-tools/index.js');
+    expect(typeof (mod as any).runEmbed).toBe('function');
+  });
+
+  it('runEmbed is directly importable from embed.js', async () => {
+    const { runEmbed } = await import('../../mcp-tools/embed.js');
+    expect(typeof runEmbed).toBe('function');
+  });
+});

package/src/__tests__/mcp-tools/explain.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import Database from 'better-sqlite3';
+import { explainNode } from '../../mcp-tools/explain.js';
+
+function makeDb(): Database.Database {
+  const db = new Database(':memory:');
+  db.exec(`
+    CREATE TABLE nodes (id TEXT PRIMARY KEY, name TEXT, label TEXT, file_path TEXT, start_line INTEGER, end_line INTEGER, community_id INTEGER, norm_label TEXT, is_exported INTEGER, language TEXT, properties TEXT);
+    CREATE TABLE edges (id TEXT PRIMARY KEY, source_id TEXT, target_id TEXT, relation TEXT, confidence TEXT, confidence_score REAL);
+    INSERT INTO nodes VALUES ('n1', 'UserService', 'Class', '/app/user.ts', 1, 50, 1, 'userservice', 1, 'typescript', null);
+    INSERT INTO nodes VALUES ('n2', 'getUser', 'Function', '/app/user.ts', 5, 15, 1, 'getuser', 1, 'typescript', null);
+    INSERT INTO nodes VALUES ('n3', 'Database', 'Class', '/app/db.ts', 1, 100, 2, 'database', 1, 'typescript', null);
+    INSERT INTO edges VALUES ('e1', 'n1', 'n2', 'HAS_METHOD', 'EXTRACTED', 1.0);
+    INSERT INTO edges VALUES ('e2', 'n2', 'n3', 'CALLS', 'EXTRACTED', 1.0);
+  `);
+  return db;
+}
+
+describe('explainNode', () => {
+  it('returns an explanation string for a known node', () => {
+    const db = makeDb();
+    const result = explainNode(db, 'UserService');
+    expect(result.explanation).toBeDefined();
+    expect(result.explanation).toContain('UserService');
+    expect(result.explanation).toContain('Class');
+  });
+
+  it('explanation mentions outbound connections', () => {
+    const db = makeDb();
+    const result = explainNode(db, 'UserService');
+    expect(result.explanation).toContain('getUser');
+  });
+
+  it('returns null explanation for unknown node', () => {
+    const db = makeDb();
+    const result = explainNode(db, 'NonExistent');
+    expect(result.node).toBeNull();
+    expect(result.explanation).toBeNull();
+  });
+
+  it('includes connection count in summary', () => {
+    const db = makeDb();
+    const result = explainNode(db, 'getUser');
+    expect(result.connectionCount).toBeGreaterThanOrEqual(0);
+  });
+});

package/src/__tests__/mcp-tools/graph-query.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest';
+import Database from 'better-sqlite3';
+import { queryGraph as queryGraphMcp } from '../../mcp-tools/graph-query.js';
+
+function makeDb(): Database.Database {
+  const db = new Database(':memory:');
+  db.exec(`
+    CREATE TABLE nodes (id TEXT PRIMARY KEY, name TEXT, label TEXT, file_path TEXT, start_line INTEGER, end_line INTEGER, community_id INTEGER, norm_label TEXT, is_exported INTEGER, language TEXT, properties TEXT);
+    CREATE TABLE edges (id TEXT PRIMARY KEY, source_id TEXT, target_id TEXT, relation TEXT, confidence TEXT, confidence_score REAL);
+    INSERT INTO nodes VALUES ('n1', 'AuthService', 'Class', '/app/auth.ts', 1, 50, 1, 'authservice', 1, 'typescript', null);
+    INSERT INTO nodes VALUES ('n2', 'login', 'Function', '/app/auth.ts', 5, 20, 1, 'login', 1, 'typescript', null);
+    INSERT INTO nodes VALUES ('n3', 'Database', 'Class', '/app/db.ts', 1, 100, 2, 'database', 1, 'typescript', null);
+    INSERT INTO edges VALUES ('e1', 'n1', 'n2', 'HAS_METHOD', 'EXTRACTED', 1.0);
+    INSERT INTO edges VALUES ('e2', 'n2', 'n3', 'CALLS', 'EXTRACTED', 1.0);
+  `);
+  return db;
+}
+
+describe('queryGraphMcp', () => {
+  it('returns nodes matching query string', () => {
+    const db = makeDb();
+    const result = queryGraphMcp(db, { query: 'auth', mode: 'bfs' });
+    expect(result.nodes.length).toBeGreaterThan(0);
+    expect(result.nodes.some(n => n.name === 'AuthService')).toBe(true);
+  });
+
+  it('respects tokenBudget — stops when estimate exceeded', () => {
+    const db = makeDb();
+    const result = queryGraphMcp(db, { query: 'auth', mode: 'bfs', tokenBudget: 10 });
+    // Very small budget — should return minimal results
+    expect(result.truncated).toBe(true);
+  });
+
+  it('works with dfs mode', () => {
+    const db = makeDb();
+    const result = queryGraphMcp(db, { query: 'auth', mode: 'dfs' });
+    expect(result.nodes.length).toBeGreaterThan(0);
+  });
+
+  it('result has mode in metadata', () => {
+    const db = makeDb();
+    const result = queryGraphMcp(db, { query: 'login', mode: 'bfs' });
+    expect(result.mode).toBe('bfs');
+  });
+});

package/src/__tests__/mcp-tools/group-sync.test.ts

@@ -0,0 +1,8 @@
+import { describe, it, expect } from 'vitest';
+
+describe('group-sync tool exports', () => {
+  it('runGroupSync is exported from mcp-tools index', async () => {
+    const mod = await import('../../mcp-tools/index.js');
+    expect(typeof (mod as any).runGroupSync).toBe('function');
+  });
+});

package/src/__tests__/mcp-tools/impact-filtering.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import Database from 'better-sqlite3';
+import { monographImpact } from '../../mcp-tools/impact.js';
+
+function makeDb(): Database.Database {
+  const db = new Database(':memory:');
+  db.exec(`
+    CREATE TABLE nodes (id TEXT PRIMARY KEY, label TEXT NOT NULL, name TEXT NOT NULL,
+      norm_label TEXT, file_path TEXT, start_line INTEGER, end_line INTEGER,
+      community_id INTEGER, is_exported INTEGER DEFAULT 0, language TEXT, properties TEXT);
+    CREATE TABLE edges (id TEXT PRIMARY KEY, source_id TEXT NOT NULL, target_id TEXT NOT NULL,
+      relation TEXT NOT NULL, confidence TEXT DEFAULT 'EXTRACTED', confidence_score REAL DEFAULT 1.0,
+      properties TEXT);
+  `);
+  db.prepare(`INSERT INTO nodes VALUES ('n1','Function','doA',null,'/a.ts',1,5,null,1,null,null)`).run();
+  db.prepare(`INSERT INTO nodes VALUES ('n2','Function','doB',null,'/b.ts',1,3,null,1,null,null)`).run();
+  db.prepare(`INSERT INTO nodes VALUES ('n3','Function','doC',null,'/c.ts',1,3,null,1,null,null)`).run();
+  db.prepare(`INSERT INTO edges VALUES ('e1','n2','n1','CALLS','EXTRACTED',0.9,null)`).run();
+  db.prepare(`INSERT INTO edges VALUES ('e2','n3','n1','CALLS','AMBIGUOUS',0.2,null)`).run();
+  return db;
+}
+
+describe('monographImpact filtering', () => {
+  it('minConfidenceScore filters low-confidence callers', async () => {
+    const db = makeDb();
+    const result = await monographImpact(db, 'n1', { minConfidenceScore: 0.5 });
+    const callerIds = result.directCallers.map(n => n.id);
+    expect(callerIds).toContain('n2');
+    expect(callerIds).not.toContain('n3');
+  });
+
+  it('without filter returns all callers', async () => {
+    const db = makeDb();
+    const result = await monographImpact(db, 'n1', {});
+    const callerIds = result.directCallers.map(n => n.id);
+    expect(callerIds).toContain('n2');
+    expect(callerIds).toContain('n3');
+  });
+
+  it('relationTypes restricts edge traversal', async () => {
+    const db = makeDb();
+    db.prepare(`INSERT INTO edges VALUES ('e3','n3','n1','IMPORTS','EXTRACTED',0.9,null)`).run();
+    const result = await monographImpact(db, 'n1', { relationTypes: ['IMPORTS'] });
+    const callerIds = result.directCallers.map(n => n.id);
+    expect(callerIds).toContain('n3');
+    expect(callerIds).not.toContain('n2');
+  });
+});

package/src/__tests__/mcp-tools/impact.risk.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import { computeRiskLevel, type RiskLevel } from '../../mcp-tools/impact.js';
+
+describe('computeRiskLevel', () => {
+  it('returns CRITICAL for score > 0.75', () => {
+    expect(computeRiskLevel(0.9)).toBe('CRITICAL');
+    expect(computeRiskLevel(1.0)).toBe('CRITICAL');
+  });
+
+  it('returns HIGH for score 0.5-0.75', () => {
+    expect(computeRiskLevel(0.6)).toBe('HIGH');
+    expect(computeRiskLevel(0.75)).toBe('HIGH');
+  });
+
+  it('returns MEDIUM for score 0.25-0.5', () => {
+    expect(computeRiskLevel(0.3)).toBe('MEDIUM');
+    expect(computeRiskLevel(0.5)).toBe('MEDIUM');
+  });
+
+  it('returns LOW for score < 0.25', () => {
+    expect(computeRiskLevel(0)).toBe('LOW');
+    expect(computeRiskLevel(0.24)).toBe('LOW');
+  });
+});

package/src/__tests__/mcp-tools/list-repos.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import { listReposTool } from '../../mcp-tools/list-repos.js';
+
+describe('listReposTool', () => {
+  it('has correct name', () => {
+    expect(listReposTool.name).toBe('monograph_list_repos');
+  });
+
+  it('has description', () => {
+    expect(typeof listReposTool.description).toBe('string');
+    expect(listReposTool.description.length).toBeGreaterThan(5);
+  });
+
+  it('has inputSchema', () => {
+    expect(listReposTool.inputSchema).toBeDefined();
+    expect(listReposTool.inputSchema.type).toBe('object');
+  });
+
+  it('handler returns repos array', async () => {
+    const result = await listReposTool.handler({});
+    expect(result).toHaveProperty('repos');
+    expect(Array.isArray(result.repos)).toBe(true);
+  });
+});

package/src/__tests__/mcp-tools/neighbors.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import Database from 'better-sqlite3';
+import { getMonographNeighbors } from '../../mcp-tools/neighbors.js';
+
+function makeDb(): Database.Database {
+  const db = new Database(':memory:');
+  db.exec(`
+    CREATE TABLE nodes (id TEXT PRIMARY KEY, name TEXT, label TEXT, file_path TEXT, start_line INTEGER, end_line INTEGER, community_id INTEGER, norm_label TEXT, is_exported INTEGER, language TEXT, properties TEXT);
+    CREATE TABLE edges (id TEXT PRIMARY KEY, source_id TEXT, target_id TEXT, relation TEXT, confidence TEXT, confidence_score REAL);
+    INSERT INTO nodes VALUES ('n1', 'UserService', 'Class', '/app/user.ts', 1, 50, 1, 'userservice', 1, 'typescript', null);
+    INSERT INTO nodes VALUES ('n2', 'getUser', 'Function', '/app/user.ts', 5, 15, 1, 'getuser', 1, 'typescript', null);
+    INSERT INTO nodes VALUES ('n3', 'Database', 'Class', '/app/db.ts', 1, 100, 2, 'database', 1, 'typescript', null);
+    INSERT INTO edges VALUES ('e1', 'n1', 'n2', 'HAS_METHOD', 'EXTRACTED', 1.0);
+    INSERT INTO edges VALUES ('e2', 'n1', 'n3', 'CALLS', 'INFERRED', 0.7);
+  `);
+  return db;
+}
+
+describe('getMonographNeighbors', () => {
+  it('returns outbound neighbors with edge details', () => {
+    const db = makeDb();
+    const result = getMonographNeighbors(db, { name: 'UserService' });
+    expect(result.node).not.toBeNull();
+    expect(result.neighbors.length).toBe(2);
+    const rels = result.neighbors.map(n => n.relation);
+    expect(rels).toContain('HAS_METHOD');
+    expect(rels).toContain('CALLS');
+  });
+
+  it('can filter by relation type', () => {
+    const db = makeDb();
+    const result = getMonographNeighbors(db, { name: 'UserService', relationFilter: 'CALLS' });
+    expect(result.neighbors.every(n => n.relation === 'CALLS')).toBe(true);
+  });
+
+  it('returns null node for unknown symbol', () => {
+    const db = makeDb();
+    const result = getMonographNeighbors(db, { name: 'NonExistent' });
+    expect(result.node).toBeNull();
+    expect(result.neighbors).toEqual([]);
+  });
+
+  it('includes inbound neighbors', () => {
+    const db = makeDb();
+    const result = getMonographNeighbors(db, { name: 'getUser', includeInbound: true });
+    expect(result.neighbors.some(n => n.direction === 'inbound')).toBe(true);
+  });
+});