@monoes/monograph 1.1.0 → 1.2.0

package/__tests__/search/http-embedder.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { HttpEmbedder } from '../../src/search/http-embedder.js';
+import { resolveDevice } from '../../src/search/device-config.js';
+
+// Mock global fetch
+const mockFetch = vi.fn();
+vi.stubGlobal('fetch', mockFetch);
+
+function makeOkResponse(embedding: number[]) {
+  return {
+    ok: true,
+    status: 200,
+    statusText: 'OK',
+    json: async () => ({ embedding }),
+  };
+}
+
+beforeEach(() => mockFetch.mockReset());
+
+describe('HttpEmbedder', () => {
+  it('embedOne sends POST and returns vector', async () => {
+    mockFetch.mockResolvedValueOnce(makeOkResponse([0.1, 0.2, 0.3]));
+    const embedder = new HttpEmbedder({ endpoint: 'http://localhost:1234/embed' });
+    const vec = await embedder.embedOne('hello');
+    expect(vec).toEqual([0.1, 0.2, 0.3]);
+    expect(mockFetch).toHaveBeenCalledWith(
+      'http://localhost:1234/embed',
+      expect.objectContaining({ method: 'POST' }),
+    );
+  });
+
+  it('throws on non-2xx response', async () => {
+    mockFetch.mockResolvedValueOnce({ ok: false, status: 503, statusText: 'Service Unavailable', json: async () => ({}) });
+    const embedder = new HttpEmbedder({ endpoint: 'http://localhost:1234/embed' });
+    await expect(embedder.embedOne('hello')).rejects.toThrow('503');
+  });
+
+  it('throws when embedding field is missing', async () => {
+    mockFetch.mockResolvedValueOnce({ ok: true, status: 200, statusText: 'OK', json: async () => ({}) });
+    const embedder = new HttpEmbedder({ endpoint: 'http://localhost:1234/embed' });
+    await expect(embedder.embedOne('hello')).rejects.toThrow('no embedding');
+  });
+
+  it('adds Authorization header when apiKey is set', async () => {
+    mockFetch.mockResolvedValueOnce(makeOkResponse([1, 2]));
+    const embedder = new HttpEmbedder({ endpoint: 'http://localhost:1234/embed', apiKey: 'sk-test' });
+    await embedder.embedOne('hi');
+    const [, opts] = mockFetch.mock.calls[0] as [string, RequestInit];
+    expect((opts.headers as Record<string, string>)['Authorization']).toBe('Bearer sk-test');
+  });
+
+  it('embedBatch returns one vector per input text', async () => {
+    mockFetch
+      .mockResolvedValueOnce(makeOkResponse([1, 0]))
+      .mockResolvedValueOnce(makeOkResponse([0, 1]));
+    const embedder = new HttpEmbedder({ endpoint: 'http://localhost:1234/embed', batchSize: 1 });
+    const vecs = await embedder.embedBatch(['a', 'b']);
+    expect(vecs).toHaveLength(2);
+    expect(vecs[0]).toEqual([1, 0]);
+    expect(vecs[1]).toEqual([0, 1]);
+  });
+});
+
+describe('resolveDevice', () => {
+  it('returns cpu by default on non-darwin with no CUDA', () => {
+    vi.stubEnv('CUDA_VISIBLE_DEVICES', '');
+    // Can't reliably mock process.platform in vitest without patching,
+    // so just verify it returns one of the valid values
+    const d = resolveDevice();
+    expect(['cpu', 'cuda', 'mps']).toContain(d);
+  });
+
+  it('returns the explicit device when set', () => {
+    expect(resolveDevice({ device: 'cuda' })).toBe('cuda');
+    expect(resolveDevice({ device: 'cpu' })).toBe('cpu');
+    expect(resolveDevice({ device: 'mps' })).toBe('mps');
+  });
+});

package/__tests__/search/hybrid-query.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { unlinkSync, existsSync } from 'fs';
+import { openDb, closeDb } from '../../src/storage/db.js';
+import { insertNode } from '../../src/storage/node-store.js';
+import { upsertEmbedding } from '../../src/storage/embedding-store.js';
+import { hybridQuery } from '../../src/search/hybrid-query.js';
+import type { MonographNode } from '../../src/types.js';
+
+const dbPath = join(tmpdir(), `monograph-hybrid-${Date.now()}.db`);
+let db: ReturnType<typeof openDb>;
+
+// Deterministic 384-dim vectors (not meaningful but unique per node)
+function makeVec(seed: number): Float32Array {
+  const v = new Float32Array(384);
+  // Fill with a pattern so cosine similarity with seed=0 favours index 0
+  v[seed % 384] = 1.0; // sparse one-hot–ish (not normalised but fine for mocking)
+  // L2-normalise
+  const norm = Math.sqrt(v.reduce((s, x) => s + x * x, 0));
+  for (let i = 0; i < v.length; i++) v[i] /= norm;
+  return v;
+}
+
+// Fake embedder that always returns the same "query" vector (seed 0)
+const fakeEmbedder = async (_text: string | string[]) => ({
+  data: makeVec(0),
+});
+
+const nodes: MonographNode[] = [
+  { id: 'n1', label: 'Function', name: 'authenticate', normLabel: 'authenticate', filePath: 'src/auth.ts', startLine: 1, isExported: true },
+  { id: 'n2', label: 'Function', name: 'authorise', normLabel: 'authorise', filePath: 'src/auth.ts', startLine: 10, isExported: true },
+  { id: 'n3', label: 'Class', name: 'UserService', normLabel: 'userservice', filePath: 'src/user.ts', startLine: 1, isExported: true },
+];
+
+beforeAll(() => {
+  db = openDb(dbPath);
+  for (const node of nodes) insertNode(db, node);
+  // Store embeddings (n1 gets seed=0, others get different seeds)
+  upsertEmbedding(db, 'n1', makeVec(0));
+  upsertEmbedding(db, 'n2', makeVec(1));
+  upsertEmbedding(db, 'n3', makeVec(2));
+});
+
+afterAll(() => {
+  closeDb(db);
+  for (const p of [dbPath, dbPath + '-wal', dbPath + '-shm']) {
+    if (existsSync(p)) unlinkSync(p);
+  }
+});
+
+describe('hybridQuery', () => {
+  it('falls back to BM25 when embedder is not provided and env not set', async () => {
+    const results = await hybridQuery(db, 'authenticate');
+    // Without embedder, we still get BM25 results
+    expect(results.length).toBeGreaterThan(0);
+    expect(results.some((r) => r.id === 'n1')).toBe(true);
+  });
+
+  it('uses hybrid ranking when an explicit embedder is passed', async () => {
+    const results = await hybridQuery(db, 'authenticate', { embedder: fakeEmbedder as never });
+    expect(results.length).toBeGreaterThan(0);
+    // n1 has the same vector as the fake query (seed 0) so it should score well
+    expect(results.some((r) => r.id === 'n1')).toBe(true);
+  });
+
+  it('returns at most `limit` results', async () => {
+    const results = await hybridQuery(db, 'auth', { limit: 1, embedder: fakeEmbedder as never });
+    expect(results.length).toBeLessThanOrEqual(1);
+  });
+
+  it('returns HybridResult objects with required fields', async () => {
+    const results = await hybridQuery(db, 'authenticate', { embedder: fakeEmbedder as never });
+    for (const r of results) {
+      expect(r).toHaveProperty('id');
+      expect(r).toHaveProperty('score');
+    }
+  });
+
+  it('returns empty array for a query with no matches', async () => {
+    const results = await hybridQuery(db, 'zzznonexistentzzzxxx');
+    expect(results).toEqual([]);
+  });
+
+  it('respects label filter', async () => {
+    const results = await hybridQuery(db, 'auth', { label: 'Class' });
+    for (const r of results) {
+      expect(r.label).toBe('Class');
+    }
+  });
+
+  it('scores are numeric', async () => {
+    const results = await hybridQuery(db, 'authenticate', { embedder: fakeEmbedder as never });
+    for (const r of results) {
+      expect(typeof r.score).toBe('number');
+      expect(isNaN(r.score)).toBe(false);
+    }
+  });
+});

package/__tests__/search/rrf.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from 'vitest';
+import { mergeRanks, type RankedResult } from '../../src/search/rrf.js';
+
+describe('mergeRanks (RRF)', () => {
+  it('returns empty array when both lists are empty', () => {
+    expect(mergeRanks([], [])).toEqual([]);
+  });
+
+  it('returns list1 items when list2 is empty', () => {
+    const list1: RankedResult[] = [
+      { id: 'a', score: 1.0 },
+      { id: 'b', score: 0.5 },
+    ];
+    const merged = mergeRanks(list1, []);
+    expect(merged.map((r) => r.id)).toEqual(['a', 'b']);
+  });
+
+  it('returns list2 items when list1 is empty', () => {
+    const list2: RankedResult[] = [
+      { id: 'x', score: 0.9 },
+      { id: 'y', score: 0.3 },
+    ];
+    const merged = mergeRanks([], list2);
+    expect(merged.map((r) => r.id)).toEqual(['x', 'y']);
+  });
+
+  it('computes correct RRF score for an item in both lists (K=60)', () => {
+    // item A: rank 1 in list1, rank 2 in list2
+    // expected rrf = 1/(60+1) + 1/(60+2) = 1/61 + 1/62
+    const list1: RankedResult[] = [{ id: 'A', score: 1 }];
+    const list2: RankedResult[] = [
+      { id: 'B', score: 1 }, // rank 1
+      { id: 'A', score: 0.8 }, // rank 2
+    ];
+    const merged = mergeRanks(list1, list2);
+    const itemA = merged.find((r) => r.id === 'A')!;
+    const expected = 1 / 61 + 1 / 62;
+    expect(itemA.score).toBeCloseTo(expected, 10);
+  });
+
+  it('ranks an item appearing in both lists above items in only one list', () => {
+    // A appears in both; B only in list1; C only in list2
+    const list1: RankedResult[] = [
+      { id: 'A', score: 0.5 },
+      { id: 'B', score: 0.4 },
+    ];
+    const list2: RankedResult[] = [
+      { id: 'A', score: 0.6 },
+      { id: 'C', score: 0.3 },
+    ];
+    const merged = mergeRanks(list1, list2);
+    const ids = merged.map((r) => r.id);
+    expect(ids[0]).toBe('A');
+  });
+
+  it('sorts results by RRF score descending', () => {
+    const list1: RankedResult[] = [
+      { id: 'a', score: 1 },
+      { id: 'b', score: 0.9 },
+      { id: 'c', score: 0.8 },
+    ];
+    const list2: RankedResult[] = [
+      { id: 'c', score: 1 },
+      { id: 'b', score: 0.95 },
+      { id: 'a', score: 0.7 },
+    ];
+    const merged = mergeRanks(list1, list2);
+    const scores = merged.map((r) => r.score);
+    for (let i = 1; i < scores.length; i++) {
+      expect(scores[i]).toBeLessThanOrEqual(scores[i - 1]);
+    }
+  });
+
+  it('preserves extra properties from list1 items', () => {
+    const list1: RankedResult[] = [{ id: 'x', score: 1, name: 'myNode', filePath: 'src/x.ts' }];
+    const merged = mergeRanks(list1, []);
+    expect(merged[0]).toMatchObject({ id: 'x', name: 'myNode', filePath: 'src/x.ts' });
+  });
+
+  it('uses custom K value correctly', () => {
+    const list1: RankedResult[] = [{ id: 'a', score: 1 }]; // rank 1
+    const list2: RankedResult[] = [{ id: 'a', score: 1 }]; // rank 1
+    const K = 10;
+    const merged = mergeRanks(list1, list2, K);
+    const expected = 2 / (K + 1); // 2 * 1/(10+1)
+    expect(merged[0].score).toBeCloseTo(expected, 10);
+  });
+
+  it('handles large lists without duplicates', () => {
+    const list1 = Array.from({ length: 100 }, (_, i) => ({ id: `item-${i}`, score: 100 - i }));
+    const list2 = Array.from({ length: 100 }, (_, i) => ({ id: `other-${i}`, score: 100 - i }));
+    const merged = mergeRanks(list1, list2);
+    expect(merged).toHaveLength(200);
+  });
+});

package/__tests__/security/safe-fetch.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect } from 'vitest';
+import { isPrivateUrl, validateUrl } from '../../src/security/safe-fetch.js';
+
+describe('isPrivateUrl', () => {
+  it('blocks localhost', () => {
+    expect(isPrivateUrl('http://localhost/data')).toBe(true);
+    expect(isPrivateUrl('http://127.0.0.1:8080/api')).toBe(true);
+    expect(isPrivateUrl('http://[::1]/api')).toBe(true);
+  });
+
+  it('blocks RFC-1918 private ranges', () => {
+    expect(isPrivateUrl('http://192.168.1.1/data')).toBe(true);
+    expect(isPrivateUrl('http://10.0.0.1/data')).toBe(true);
+    expect(isPrivateUrl('http://172.16.0.1/data')).toBe(true);
+  });
+
+  it('blocks cloud metadata endpoints', () => {
+    expect(isPrivateUrl('http://169.254.169.254/latest/meta-data')).toBe(true);
+    expect(isPrivateUrl('http://metadata.google.internal/')).toBe(true);
+  });
+
+  it('allows public URLs', () => {
+    expect(isPrivateUrl('https://api.github.com/repos')).toBe(false);
+    expect(isPrivateUrl('https://raw.githubusercontent.com/file.ts')).toBe(false);
+  });
+});
+
+describe('validateUrl', () => {
+  it('rejects non-http schemes', () => {
+    expect(() => validateUrl('file:///etc/passwd')).toThrow('Unsupported scheme');
+    expect(() => validateUrl('ftp://example.com')).toThrow('Unsupported scheme');
+  });
+
+  it('rejects private URLs', () => {
+    expect(() => validateUrl('http://192.168.1.1/admin')).toThrow('private');
+  });
+
+  it('accepts valid https URLs', () => {
+    expect(() => validateUrl('https://example.com/api')).not.toThrow();
+  });
+});

package/__tests__/security/sensitive-files.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'vitest';
+import { isSensitiveFile } from '../../src/security/sensitive-files.js';
+
+describe('isSensitiveFile', () => {
+  it('blocks .env files', () => {
+    expect(isSensitiveFile('.env')).toBe(true);
+    expect(isSensitiveFile('.env.local')).toBe(true);
+    expect(isSensitiveFile('/repo/.env.production')).toBe(true);
+  });
+
+  it('blocks private key files', () => {
+    expect(isSensitiveFile('id_rsa')).toBe(true);
+    expect(isSensitiveFile('id_ed25519')).toBe(true);
+    expect(isSensitiveFile('server.key')).toBe(true);
+    expect(isSensitiveFile('cert.pem')).toBe(true);
+  });
+
+  it('blocks credential and secret patterns', () => {
+    expect(isSensitiveFile('aws_credentials')).toBe(true);
+    expect(isSensitiveFile('credentials.json')).toBe(true);
+    expect(isSensitiveFile('secret.yaml')).toBe(true);
+    expect(isSensitiveFile('secrets.toml')).toBe(true);
+    expect(isSensitiveFile('.netrc')).toBe(true);
+  });
+
+  it('allows normal source files', () => {
+    expect(isSensitiveFile('src/auth.ts')).toBe(false);
+    expect(isSensitiveFile('config/database.ts')).toBe(false);
+    expect(isSensitiveFile('README.md')).toBe(false);
+    expect(isSensitiveFile('token-manager.ts')).toBe(false);
+  });
+});

package/__tests__/skills/platform-skills.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { installSkillsForPlatform } from '../../src/skills/platform-skills.js';
+
+let tempDir: string;
+beforeEach(() => { tempDir = mkdtempSync(join(tmpdir(), 'monograph-skills-')); });
+afterEach(() => { rmSync(tempDir, { recursive: true, force: true }); });
+
+const COMMUNITIES = [
+  { name: 'auth', symbols: ['AuthService', 'loginUser', 'logoutUser'] },
+  { name: 'api', symbols: ['ApiRouter', 'handleRequest'] },
+];
+
+describe('installSkillsForPlatform', () => {
+  it('writes .md files for claude platform', async () => {
+    const result = await installSkillsForPlatform(tempDir, COMMUNITIES, { platform: 'claude' });
+    expect(result.platform).toBe('claude');
+    expect(result.filesWritten).toHaveLength(2);
+    const content = readFileSync(result.filesWritten[0], 'utf8');
+    expect(content).toContain('# auth Skills');
+    expect(content).toContain('AuthService');
+  });
+
+  it('uses .claude/skills/ output dir for claude', async () => {
+    const result = await installSkillsForPlatform(tempDir, COMMUNITIES, { platform: 'claude' });
+    expect(result.outputDir).toBe(join(tempDir, '.claude', 'skills'));
+    expect(existsSync(result.outputDir)).toBe(true);
+  });
+
+  it('writes .md files for cursor platform in .cursor/rules/', async () => {
+    const result = await installSkillsForPlatform(tempDir, COMMUNITIES, { platform: 'cursor' });
+    expect(result.outputDir).toBe(join(tempDir, '.cursor', 'rules'));
+    expect(result.filesWritten[0]).toMatch(/\.md$/);
+  });
+
+  it('writes .json snippets for vscode platform', async () => {
+    const result = await installSkillsForPlatform(tempDir, COMMUNITIES, { platform: 'vscode' });
+    expect(result.filesWritten[0]).toMatch(/\.json$/);
+    const parsed = JSON.parse(readFileSync(result.filesWritten[0], 'utf8')) as Record<string, { prefix: string }>;
+    const first = Object.values(parsed)[0];
+    expect(first.prefix).toBe('auth');
+  });
+
+  it('writes .md files for zed platform in .zed/', async () => {
+    const result = await installSkillsForPlatform(tempDir, COMMUNITIES, { platform: 'zed' });
+    expect(result.outputDir).toBe(join(tempDir, '.zed'));
+    expect(result.filesWritten[0]).toMatch(/\.md$/);
+  });
+
+  it('respects custom outputDir override', async () => {
+    const custom = join(tempDir, 'custom-out');
+    const result = await installSkillsForPlatform(tempDir, COMMUNITIES, { platform: 'claude', outputDir: custom });
+    expect(result.outputDir).toBe(custom);
+    expect(existsSync(custom)).toBe(true);
+  });
+
+  it('returns empty filesWritten for empty communities', async () => {
+    const result = await installSkillsForPlatform(tempDir, [], { platform: 'claude' });
+    expect(result.filesWritten).toHaveLength(0);
+  });
+});

package/__tests__/staleness/git-staleness.test.ts

@@ -0,0 +1,107 @@
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { unlinkSync, existsSync } from 'fs';
+import { vi, describe, it, expect, beforeAll, afterAll, afterEach } from 'vitest';
+import { openDb, closeDb } from '../../src/storage/db.js';
+import { checkStaleness } from '../../src/staleness/git-staleness.js';
+
+// vi.mock must be at top level for Vitest hoisting
+vi.mock('child_process', () => ({
+  execSync: vi.fn(),
+}));
+
+import { execSync } from 'child_process';
+
+const dbPath = join(tmpdir(), `monograph-staleness-${Date.now()}.db`);
+let db: ReturnType<typeof openDb>;
+
+beforeAll(() => {
+  db = openDb(dbPath);
+});
+
+afterAll(() => {
+  closeDb(db);
+  for (const p of [dbPath, dbPath + '-wal', dbPath + '-shm']) {
+    if (existsSync(p)) unlinkSync(p);
+  }
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+  // Clear stored commit hash between tests
+  db.prepare("DELETE FROM index_meta WHERE key = 'last_commit_hash'").run();
+});
+
+describe('checkStaleness', () => {
+  it('returns isStale: false when indexed commit matches current HEAD', () => {
+    // Store a full commit hash
+    db.prepare("INSERT OR REPLACE INTO index_meta VALUES ('last_commit_hash', ?)").run('abc1234def5678');
+    // git rev-parse --short HEAD returns short version matching slice(0,7)
+    vi.mocked(execSync).mockReturnValue('abc1234' as any);
+
+    const report = checkStaleness(db, '/fake/repo');
+
+    expect(report.isStale).toBe(false);
+    expect(report.indexedCommit).toBe('abc1234');
+    expect(report.currentCommit).toBe('abc1234');
+    expect(report.changedSince).toHaveLength(0);
+    expect(report.staleSince).toBeNull();
+  });
+
+  it('returns isStale: true with changedSince when commits differ', () => {
+    db.prepare("INSERT OR REPLACE INTO index_meta VALUES ('last_commit_hash', ?)").run('aaa0000111222333');
+    // First call: git rev-parse --short HEAD
+    // Second call: git diff --name-only ...
+    // Third call: git log ...
+    vi.mocked(execSync)
+      .mockReturnValueOnce('bbb9999' as any)
+      .mockReturnValueOnce('src/foo.ts\nsrc/bar.ts\n' as any)
+      .mockReturnValueOnce('2024-01-15 10:00:00 +0000' as any);
+
+    const report = checkStaleness(db, '/fake/repo');
+
+    expect(report.isStale).toBe(true);
+    expect(report.indexedCommit).toBe('aaa0000');
+    expect(report.currentCommit).toBe('bbb9999');
+    expect(report.changedSince).toContain('src/foo.ts');
+    expect(report.changedSince).toContain('src/bar.ts');
+    expect(report.staleSince).toBe('2024-01-15 10:00:00 +0000');
+  });
+
+  it('returns isStale: false with null commits when not a git repo', () => {
+    db.prepare("INSERT OR REPLACE INTO index_meta VALUES ('last_commit_hash', ?)").run('abc1234def');
+    vi.mocked(execSync).mockImplementation(() => {
+      throw new Error('not a git repository');
+    });
+
+    const report = checkStaleness(db, '/not/a/git/repo');
+
+    expect(report.isStale).toBe(false);
+    expect(report.currentCommit).toBeNull();
+    expect(report.changedSince).toHaveLength(0);
+  });
+
+  it('returns isStale: false when no commit hash has been stored', () => {
+    // No stored commit hash
+    vi.mocked(execSync).mockReturnValue('abc1234' as any);
+
+    const report = checkStaleness(db, '/fake/repo');
+
+    expect(report.isStale).toBe(false);
+    expect(report.indexedCommit).toBeNull();
+    expect(report.currentCommit).toBe('abc1234');
+  });
+
+  it('returns empty changedSince when git diff fails', () => {
+    db.prepare("INSERT OR REPLACE INTO index_meta VALUES ('last_commit_hash', ?)").run('aaa0000111222');
+    vi.mocked(execSync)
+      .mockReturnValueOnce('bbb9999' as any)
+      .mockImplementationOnce(() => { throw new Error('git diff failed'); })
+      .mockReturnValueOnce('' as any);
+
+    const report = checkStaleness(db, '/fake/repo');
+
+    expect(report.isStale).toBe(true);
+    expect(report.changedSince).toHaveLength(0);
+  });
+});

package/__tests__/storage/evidence-roundtrip.test.ts

@@ -0,0 +1,89 @@
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { unlinkSync, existsSync } from 'fs';
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { openDb, closeDb } from '../../src/storage/db.js';
+import { insertNode } from '../../src/storage/node-store.js';
+import { insertEdge, getEdgesForSource } from '../../src/storage/edge-store.js';
+import type { MonographNode, MonographEdge } from '../../src/types.js';
+
+const dbPath = join(tmpdir(), `monograph-evidence-rt-${Date.now()}.db`);
+let db: ReturnType<typeof openDb>;
+
+beforeAll(() => {
+  db = openDb(dbPath);
+
+  const nodeA: MonographNode = {
+    id: 'node_a',
+    label: 'Function',
+    name: 'funcA',
+    normLabel: 'funca',
+    filePath: 'src/a.ts',
+    isExported: true,
+  };
+  const nodeB: MonographNode = {
+    id: 'node_b',
+    label: 'Function',
+    name: 'funcB',
+    normLabel: 'funcb',
+    filePath: 'src/b.ts',
+    isExported: false,
+  };
+  insertNode(db, nodeA);
+  insertNode(db, nodeB);
+});
+
+afterAll(() => {
+  closeDb(db);
+  if (existsSync(dbPath)) unlinkSync(dbPath);
+  if (existsSync(dbPath + '-wal')) unlinkSync(dbPath + '-wal');
+  if (existsSync(dbPath + '-shm')) unlinkSync(dbPath + '-shm');
+});
+
+describe('evidence round-trip', () => {
+  it('persists and retrieves an edge with evidence array', () => {
+    const edge: MonographEdge = {
+      id: 'edge_ab',
+      sourceId: 'node_a',
+      targetId: 'node_b',
+      relation: 'CALLS',
+      confidence: 'EXTRACTED',
+      confidenceScore: 1.0,
+      evidence: [
+        { kind: 'import', weight: 0.9, note: 'direct import' },
+        { kind: 'heuristic', weight: 0.5 },
+      ],
+    };
+
+    insertEdge(db, edge);
+
+    const fetched = getEdgesForSource(db, 'node_a');
+    expect(fetched).toHaveLength(1);
+    const retrieved = fetched[0];
+    expect(retrieved.evidence).toBeDefined();
+    expect(retrieved.evidence).toHaveLength(2);
+    expect(retrieved.evidence![0].kind).toBe('import');
+    expect(retrieved.evidence![0].weight).toBe(0.9);
+    expect(retrieved.evidence![0].note).toBe('direct import');
+    expect(retrieved.evidence![1].kind).toBe('heuristic');
+    expect(retrieved.evidence![1].note).toBeUndefined();
+  });
+
+  it('returns undefined evidence when not set', () => {
+    const edge: MonographEdge = {
+      id: 'edge_ab_no_ev',
+      sourceId: 'node_a',
+      targetId: 'node_b',
+      relation: 'IMPORTS',
+      confidence: 'INFERRED',
+      confidenceScore: 0.5,
+    };
+
+    insertEdge(db, edge);
+
+    const fetched = getEdgesForSource(db, 'node_a');
+    const noEvEdge = fetched.find(e => e.id === 'edge_ab_no_ev');
+    expect(noEvEdge).toBeDefined();
+    expect(noEvEdge!.evidence).toBeUndefined();
+  });
+});

package/__tests__/validation/extraction-validator.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import { validateExtraction } from '../../src/validation/extraction-validator.js';
+import type { MonographNode, MonographEdge } from '../../src/types.js';
+
+const validNode: MonographNode = {
+  id: 'n1', label: 'Function', name: 'myFn', normLabel: 'myfn',
+  filePath: 'src/a.ts', startLine: 1, endLine: 5, isExported: true,
+};
+const validEdge: MonographEdge = {
+  id: 'e1', sourceId: 'n1', targetId: 'n1',
+  relation: 'CALLS', confidence: 'EXTRACTED', confidenceScore: 1.0,
+};
+
+describe('validateExtraction', () => {
+  it('passes on valid nodes and edges', () => {
+    const r = validateExtraction([validNode], [validEdge]);
+    expect(r.valid).toBe(true);
+    expect(r.errors).toHaveLength(0);
+  });
+
+  it('rejects node with missing id', () => {
+    const bad = { ...validNode, id: '' };
+    const r = validateExtraction([bad], []);
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.includes('id'))).toBe(true);
+  });
+
+  it('rejects node with invalid label', () => {
+    const bad = { ...validNode, label: 'Goblin' as any };
+    const r = validateExtraction([bad], []);
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.includes('label'))).toBe(true);
+  });
+
+  it('rejects edge referencing unknown node', () => {
+    const badEdge = { ...validEdge, targetId: 'unknown_node' };
+    const r = validateExtraction([validNode], [badEdge]);
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.includes('targetId'))).toBe(true);
+  });
+
+  it('rejects edge with invalid confidence', () => {
+    const badEdge = { ...validEdge, confidence: 'MADE_UP' as any };
+    const r = validateExtraction([validNode], [badEdge]);
+    expect(r.valid).toBe(false);
+    expect(r.errors.some(e => e.includes('confidence'))).toBe(true);
+  });
+});