@booklib/core 2.0.0

package/tests/corrections.test.js

@@ -0,0 +1,245 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, readFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  levelFromMentions, cosine, loadCorrections, listCorrections,
+  removeCorrection, rebuildLearnedSection, MARKER_START, MARKER_END,
+  addCorrection,
+} from '../lib/engine/corrections.js';
+
+function tmpHome() {
+  const dir = mkdtempSync(join(tmpdir(), 'booklib-test-'));
+  mkdirSync(join(dir, '.booklib'), { recursive: true });
+  mkdirSync(join(dir, '.claude'), { recursive: true });
+  return dir;
+}
+
+function seedCorrections(home, entries) {
+  const p = join(home, '.booklib', 'corrections.jsonl');
+  writeFileSync(p, entries.map(e => JSON.stringify(e)).join('\n') + '\n');
+}
+
+test('levelFromMentions: 1→1, 3→2, 5→3, 10→4', () => {
+  assert.equal(levelFromMentions(1), 1);
+  assert.equal(levelFromMentions(2), 1);
+  assert.equal(levelFromMentions(3), 2);
+  assert.equal(levelFromMentions(4), 2);
+  assert.equal(levelFromMentions(5), 3);
+  assert.equal(levelFromMentions(9), 3);
+  assert.equal(levelFromMentions(10), 4);
+  assert.equal(levelFromMentions(99), 4);
+});
+
+test('cosine: identical vectors → 1.0', () => {
+  const v = [0.5, 0.5, 0.5, 0.5];
+  assert.ok(Math.abs(cosine(v, v) - 1.0) < 1e-9);
+});
+
+test('cosine: orthogonal vectors → 0.0', () => {
+  const a = [1, 0];
+  const b = [0, 1];
+  assert.ok(Math.abs(cosine(a, b)) < 1e-9);
+});
+
+test('loadCorrections: returns [] when file missing', () => {
+  const home = tmpHome();
+  assert.deepEqual(loadCorrections(home), []);
+});
+
+test('loadCorrections: skips corrupt lines, preserves valid ones', () => {
+  const home = tmpHome();
+  const valid = { id: 'abc', text: 'use const', mentions: 1, level: 1,
+                  sessions: [], firstSeen: '', lastSeen: '' };
+  // One corrupt line mixed with one valid line
+  writeFileSync(
+    join(home, '.booklib', 'corrections.jsonl'),
+    'not json\n' + JSON.stringify(valid) + '\n'
+  );
+  const result = loadCorrections(home);
+  assert.equal(result.length, 1);
+  assert.equal(result[0].id, 'abc');
+});
+
+test('loadCorrections: parses valid JSONL', () => {
+  const home = tmpHome();
+  const entry = { id: 'abc123', text: 'use const', mentions: 2, level: 1,
+                   sessions: [], firstSeen: '2026-01-01', lastSeen: '2026-01-01' };
+  seedCorrections(home, [entry]);
+  const result = loadCorrections(home);
+  assert.equal(result.length, 1);
+  assert.equal(result[0].id, 'abc123');
+});
+
+test('listCorrections: sorted by mentions descending', () => {
+  const home = tmpHome();
+  const a = { id: 'a', text: 'A', mentions: 1, level: 1, sessions: [], firstSeen: '', lastSeen: '' };
+  const b = { id: 'b', text: 'B', mentions: 9, level: 3, sessions: [], firstSeen: '', lastSeen: '' };
+  const c = { id: 'c', text: 'C', mentions: 4, level: 2, sessions: [], firstSeen: '', lastSeen: '' };
+  seedCorrections(home, [a, b, c]);
+  const sorted = listCorrections(home);
+  assert.equal(sorted[0].id, 'b');
+  assert.equal(sorted[1].id, 'c');
+  assert.equal(sorted[2].id, 'a');
+});
+
+test('removeCorrection: returns removed entry', () => {
+  const home = tmpHome();
+  const entry = { id: 'xyz', text: 'no var', mentions: 2, level: 1,
+                   sessions: [], firstSeen: '', lastSeen: '' };
+  seedCorrections(home, [entry]);
+  const removed = removeCorrection('xyz', home);
+  assert.equal(removed.id, 'xyz');
+  assert.equal(loadCorrections(home).length, 0);
+});
+
+test('removeCorrection: returns null for unknown id', () => {
+  const home = tmpHome();
+  seedCorrections(home, []);
+  assert.equal(removeCorrection('nope', home), null);
+});
+
+test('rebuildLearnedSection: writes section with level-3+ corrections', () => {
+  const home = tmpHome();
+  const entries = [
+    { id: 'a', text: 'always use const', mentions: 5, level: 3, sessions: [], firstSeen: '', lastSeen: '' },
+    { id: 'b', text: 'no magic numbers', mentions: 1, level: 1, sessions: [], firstSeen: '', lastSeen: '' },
+  ];
+  seedCorrections(home, entries);
+  rebuildLearnedSection(home);
+  const content = readFileSync(join(home, '.claude', 'CLAUDE.md'), 'utf8');
+  assert.ok(content.includes(MARKER_START));
+  assert.ok(content.includes('always use const'));
+  assert.ok(!content.includes('no magic numbers'));
+  assert.ok(content.includes(MARKER_END));
+});
+
+test('rebuildLearnedSection: replaces existing section idempotently', () => {
+  const home = tmpHome();
+  const entries = [
+    { id: 'a', text: 'use const', mentions: 5, level: 3, sessions: [], firstSeen: '', lastSeen: '' },
+  ];
+  seedCorrections(home, entries);
+  rebuildLearnedSection(home);
+  rebuildLearnedSection(home);
+  const content = readFileSync(join(home, '.claude', 'CLAUDE.md'), 'utf8');
+  const count = (content.match(/booklib-learned-start/g) || []).length;
+  assert.equal(count, 1);
+});
+
+test('rebuildLearnedSection: removes section when no level-3+ corrections', () => {
+  const home = tmpHome();
+  seedCorrections(home, [
+    { id: 'a', text: 'use const', mentions: 5, level: 3, sessions: [], firstSeen: '', lastSeen: '' },
+  ]);
+  rebuildLearnedSection(home);
+  seedCorrections(home, [
+    { id: 'a', text: 'use const', mentions: 1, level: 1, sessions: [], firstSeen: '', lastSeen: '' },
+  ]);
+  rebuildLearnedSection(home);
+  const content = readFileSync(join(home, '.claude', 'CLAUDE.md'), 'utf8');
+  assert.ok(!content.includes(MARKER_START));
+});
+
+test('rebuildLearnedSection: preserves existing CLAUDE.md content', () => {
+  const home = tmpHome();
+  const existing = '# My existing rules\n\nSome content here.\n';
+  writeFileSync(join(home, '.claude', 'CLAUDE.md'), existing);
+  seedCorrections(home, [
+    { id: 'a', text: 'use const', mentions: 5, level: 3, sessions: [], firstSeen: '', lastSeen: '' },
+  ]);
+  rebuildLearnedSection(home);
+  const content = readFileSync(join(home, '.claude', 'CLAUDE.md'), 'utf8');
+  assert.ok(content.includes('# My existing rules'));
+  assert.ok(content.includes(MARKER_START));
+});
+
+// ── addCorrection tests (use injected embedFn to avoid loading real model) ────
+
+function makeEmbedFn(map) {
+  return async (text) => {
+    if (map[text]) return map[text];
+    const v = new Array(8).fill(0);
+    v[text.length % 8] = 1;
+    return v;
+  };
+}
+
+test('addCorrection: new correction stored at level 1', async () => {
+  const home = tmpHome();
+  const embedFn = makeEmbedFn({});
+  const result = await addCorrection('use const not var', home, embedFn);
+  assert.equal(result.mentions, 1);
+  assert.equal(result.level, 1);
+  assert.equal(result.wasExisting, false);
+  assert.equal(loadCorrections(home).length, 1);
+});
+
+test('addCorrection: identical text increments existing', async () => {
+  const home = tmpHome();
+  const vec = [1, 0, 0, 0, 0, 0, 0, 0];
+  const embedFn = makeEmbedFn({ 'use const': vec, 'use const not var': vec });
+  await addCorrection('use const', home, embedFn);
+  const result = await addCorrection('use const not var', home, embedFn);
+  assert.equal(result.wasExisting, true);
+  assert.equal(result.mentions, 2);
+  assert.equal(loadCorrections(home).length, 1);
+});
+
+test('addCorrection: different text creates new entry', async () => {
+  const home = tmpHome();
+  const embedFn = makeEmbedFn({
+    'use const': [1, 0, 0, 0, 0, 0, 0, 0],
+    'no magic numbers': [0, 1, 0, 0, 0, 0, 0, 0],
+  });
+  await addCorrection('use const', home, embedFn);
+  await addCorrection('no magic numbers', home, embedFn);
+  assert.equal(loadCorrections(home).length, 2);
+});
+
+test('addCorrection: reaching level 3 triggers CLAUDE.md rebuild', async () => {
+  const home = tmpHome();
+  const vec = [1, 0, 0, 0, 0, 0, 0, 0];
+  const embedFn = makeEmbedFn({ 'use const': vec });
+  seedCorrections(home, [{
+    id: 'test1', text: 'use const', mentions: 4, level: 2,
+    sessions: [], firstSeen: '', lastSeen: '',
+  }]);
+  await addCorrection('use const', home, embedFn);
+  const content = readFileSync(join(home, '.claude', 'CLAUDE.md'), 'utf8');
+  assert.ok(content.includes(MARKER_START));
+  assert.ok(content.includes('use const'));
+});
+
+test('addCorrection: does not expose embedding field in return value', async () => {
+  const home = tmpHome();
+  const embedFn = makeEmbedFn({ 'test rule': [1, 0, 0, 0, 0, 0, 0, 0] });
+  const result = await addCorrection('test rule', home, embedFn);
+  assert.ok(!('embedding' in result));
+});
+
+test('addCorrection: backfilled embedding is persisted to disk', async (t) => {
+  const tmpHome = mkdtempSync(join(tmpdir(), 'bl-test-'));
+  const bookLibDir = join(tmpHome, '.booklib');
+  mkdirSync(bookLibDir, { recursive: true });
+
+  // Seed entry with NO embedding field
+  const entry = {
+    id: 'aabbcc01', text: 'use const', mentions: 1, level: 1,
+    sessions: ['s1'], firstSeen: '2024-01-01T00:00:00.000Z', lastSeen: '2024-01-01T00:00:00.000Z',
+  };
+  writeFileSync(join(bookLibDir, 'corrections.jsonl'), JSON.stringify(entry) + '\n');
+
+  const embedMap = { 'use const': [1, 0, 0], 'use const again': [1, 0, 0] };
+  const embedFn = makeEmbedFn(embedMap);
+
+  // Call add with text that deduplicates (same vector)
+  await addCorrection('use const again', tmpHome, embedFn);
+
+  // Reload from disk and verify embedding was persisted
+  const loaded = loadCorrections(tmpHome);
+  assert.equal(loaded.length, 1);
+  assert.ok(loaded[0].embedding, 'embedding should be persisted to disk after backfill');
+  assert.deepEqual(loaded[0].embedding, [1, 0, 0]);
+});

package/tests/doctor/hook-installer.test.js

@@ -0,0 +1,72 @@
+// tests/doctor/hook-installer.test.js
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { installTrackingHook } from '../../lib/doctor/hook-installer.js';
+
+function tmp() { return mkdtempSync(join(tmpdir(), 'booklib-hook-')); }
+
+test('installTrackingHook writes track-usage.mjs', () => {
+  const home = tmp();
+  installTrackingHook(home);
+  const scriptPath = join(home, '.booklib', 'track-usage.mjs');
+  assert.ok(existsSync(scriptPath));
+  const content = readFileSync(scriptPath, 'utf8');
+  assert.ok(content.includes('usage.json'));
+  assert.ok(content.includes('skill'));
+  rmSync(home, { recursive: true });
+});
+
+test('installTrackingHook creates settings.json with Skill hook', () => {
+  const home = tmp();
+  mkdirSync(join(home, '.claude'), { recursive: true });
+  installTrackingHook(home);
+  const settings = JSON.parse(readFileSync(join(home, '.claude', 'settings.json'), 'utf8'));
+  assert.ok(Array.isArray(settings.hooks?.PreToolUse));
+  const entry = settings.hooks.PreToolUse.find(e => e.matcher === 'Skill');
+  assert.ok(entry);
+  assert.ok(entry.hooks[0].command.includes('track-usage.mjs'));
+  rmSync(home, { recursive: true });
+});
+
+test('installTrackingHook preserves existing hooks', () => {
+  const home = tmp();
+  mkdirSync(join(home, '.claude'), { recursive: true });
+  const settingsPath = join(home, '.claude', 'settings.json');
+  writeFileSync(settingsPath, JSON.stringify({
+    hooks: {
+      PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: 'echo bash' }] }]
+    }
+  }, null, 2));
+  installTrackingHook(home);
+  const updated = JSON.parse(readFileSync(settingsPath, 'utf8'));
+  assert.ok(updated.hooks.PreToolUse.find(e => e.matcher === 'Bash'));
+  assert.ok(updated.hooks.PreToolUse.find(e => e.matcher === 'Skill'));
+  rmSync(home, { recursive: true });
+});
+
+test('installTrackingHook reports alreadyInstalled on second call', () => {
+  const home = tmp();
+  installTrackingHook(home);
+  const result = installTrackingHook(home);
+  assert.equal(result.alreadyInstalled, true);
+  rmSync(home, { recursive: true });
+});
+
+test('installTrackingHook returns scriptPath and settingsPath', () => {
+  const home = tmp();
+  const result = installTrackingHook(home);
+  assert.ok(result.scriptPath.endsWith('track-usage.mjs'));
+  assert.ok(result.settingsPath.endsWith('settings.json'));
+  rmSync(home, { recursive: true });
+});
+
+test('installTrackingHook throws on corrupted settings.json', () => {
+  const home = tmp();
+  mkdirSync(join(home, '.claude'), { recursive: true });
+  writeFileSync(join(home, '.claude', 'settings.json'), 'not valid json');
+  assert.throws(() => installTrackingHook(home), SyntaxError);
+  rmSync(home, { recursive: true });
+});

package/tests/doctor/usage-tracker.test.js

@@ -0,0 +1,140 @@
+// tests/doctor/usage-tracker.test.js
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { appendUsage, readUsage, summarize } from '../../lib/doctor/usage-tracker.js';
+
+function tmp() { return mkdtempSync(join(tmpdir(), 'booklib-doctor-')); }
+
+test('readUsage returns [] when file does not exist', () => {
+  const dir = tmp();
+  const result = readUsage(join(dir, 'usage.json'));
+  assert.deepEqual(result, []);
+  rmSync(dir, { recursive: true });
+});
+
+test('appendUsage creates file and adds entry', () => {
+  const dir = tmp();
+  const file = join(dir, 'usage.json');
+  appendUsage('effective-python', file);
+  const entries = readUsage(file);
+  assert.equal(entries.length, 1);
+  assert.equal(entries[0].skill, 'effective-python');
+  assert.ok(typeof entries[0].timestamp === 'string');
+  rmSync(dir, { recursive: true });
+});
+
+test('appendUsage accumulates multiple entries', () => {
+  const dir = tmp();
+  const file = join(dir, 'usage.json');
+  appendUsage('effective-python', file);
+  appendUsage('effective-python', file);
+  appendUsage('clean-code-reviewer', file);
+  const entries = readUsage(file);
+  assert.equal(entries.length, 3);
+  rmSync(dir, { recursive: true });
+});
+
+test('summarize returns entry for every installed skill', () => {
+  const entries = [
+    { skill: 'effective-python', timestamp: new Date().toISOString() },
+  ];
+  const result = summarize(entries, ['effective-python', 'design-patterns']);
+  assert.equal(result.length, 2);
+  const names = result.map(r => r.name);
+  assert.ok(names.includes('effective-python'));
+  assert.ok(names.includes('design-patterns'));
+});
+
+test('summarize counts uses correctly', () => {
+  const now = new Date().toISOString();
+  const entries = [
+    { skill: 'effective-python', timestamp: now },
+    { skill: 'effective-python', timestamp: now },
+    { skill: 'clean-code-reviewer', timestamp: now },
+  ];
+  const result = summarize(entries, ['effective-python', 'clean-code-reviewer']);
+  const py = result.find(r => r.name === 'effective-python');
+  const cc = result.find(r => r.name === 'clean-code-reviewer');
+  assert.equal(py.uses, 2);
+  assert.equal(cc.uses, 1);
+});
+
+test('summarize sets lastUsed to most recent timestamp', () => {
+  const old    = new Date('2026-01-01T00:00:00Z').toISOString();
+  const recent = new Date('2026-03-28T00:00:00Z').toISOString();
+  const entries = [
+    { skill: 'effective-python', timestamp: old },
+    { skill: 'effective-python', timestamp: recent },
+  ];
+  const result = summarize(entries, ['effective-python']);
+  const py = result.find(r => r.name === 'effective-python');
+  assert.equal(py.lastUsed.toISOString(), recent);
+});
+
+test('summarize sets lastUsed null for never-used skill', () => {
+  const result = summarize([], ['design-patterns']);
+  assert.equal(result[0].lastUsed, null);
+  assert.equal(result[0].uses, 0);
+});
+
+test('summarize flags 0-use skill installed >30 days ago as remove', () => {
+  const installDate = new Date(Date.now() - 47 * 24 * 60 * 60 * 1000);
+  const result = summarize([], ['design-patterns'], { 'design-patterns': installDate });
+  assert.equal(result[0].suggestion, 'remove');
+});
+
+test('summarize flags <2 uses in 60 days as low-activity', () => {
+  const oldDate = new Date(Date.now() - 62 * 24 * 60 * 60 * 1000).toISOString();
+  const entries = [{ skill: 'effective-java', timestamp: oldDate }];
+  const result = summarize(entries, ['effective-java']);
+  assert.equal(result[0].suggestion, 'low-activity');
+});
+
+test('summarize healthy skill has suggestion null', () => {
+  const entries = Array.from({ length: 5 }, () => ({
+    skill: 'effective-python',
+    timestamp: new Date().toISOString(),
+  }));
+  const result = summarize(entries, ['effective-python']);
+  assert.equal(result[0].suggestion, null);
+});
+
+test('appendUsage creates nested directories if absent', () => {
+  const dir = tmp();
+  const file = join(dir, 'deep', 'nested', 'usage.json');
+  appendUsage('effective-python', file);
+  const entries = readUsage(file);
+  assert.equal(entries.length, 1);
+  rmSync(dir, { recursive: true });
+});
+
+test('summarize sorts healthy skills before suggestions', () => {
+  const now = new Date().toISOString();
+  const oldDate = new Date(Date.now() - 62 * 24 * 60 * 60 * 1000).toISOString();
+  // design-patterns installed 20 days ago (established, no recent use → low-activity)
+  const installDates = { 'design-patterns': new Date(Date.now() - 20 * 24 * 60 * 60 * 1000) };
+  const entries = [
+    { skill: 'effective-python', timestamp: now },
+    { skill: 'effective-python', timestamp: now },
+    { skill: 'effective-python', timestamp: now },
+    { skill: 'effective-java', timestamp: oldDate },
+  ];
+  const result = summarize(entries, ['effective-python', 'effective-java', 'design-patterns'], installDates);
+  // healthy first
+  assert.equal(result[0].suggestion, null);
+  assert.equal(result[0].name, 'effective-python');
+  // suggestions after
+  assert.ok(result.slice(1).every(r => r.suggestion !== null));
+});
+
+test('readUsage returns [] for corrupt file', () => {
+  const dir = tmp();
+  const file = join(dir, 'usage.json');
+  writeFileSync(file, 'not valid json{{{');
+  const result = readUsage(file);
+  assert.deepEqual(result, []);
+  rmSync(dir, { recursive: true });
+});

package/tests/engine/benchmark-eval.test.js

@@ -0,0 +1,31 @@
+// tests/engine/benchmark-eval.test.js
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { computeMRR, computeRecall, computeNDCG } from '../../benchmark/run-eval.js';
+
+describe('eval metrics', () => {
+  it('MRR@5: rank 1 hit returns 1.0', () => {
+    assert.strictEqual(computeMRR([['a', 'b', 'c']], [['a']], 5), 1.0);
+  });
+
+  it('MRR@5: rank 2 hit returns 0.5', () => {
+    assert.strictEqual(computeMRR([['x', 'a', 'b']], [['a']], 5), 0.5);
+  });
+
+  it('MRR@5: no hit returns 0', () => {
+    assert.strictEqual(computeMRR([['x', 'y', 'z']], [['a']], 5), 0);
+  });
+
+  it('Recall@5: all relevant in top 5 returns 1.0', () => {
+    assert.strictEqual(computeRecall([['a', 'b', 'c']], [['a', 'b']], 5), 1.0);
+  });
+
+  it('Recall@5: no relevant returns 0', () => {
+    assert.strictEqual(computeRecall([['x', 'y', 'z']], [['a']], 5), 0);
+  });
+
+  it('NDCG@5: perfect ranking returns 1.0', () => {
+    const score = computeNDCG([['a', 'b']], [['a', 'b']], 5);
+    assert.ok(Math.abs(score - 1.0) < 0.01);
+  });
+});

package/tests/engine/bm25-index.test.js

@@ -0,0 +1,85 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+import { BM25Index } from '../../lib/engine/bm25-index.js';
+
+const CHUNKS = [
+  { text: 'null safety kotlin avoid null pointer exception', metadata: { name: 'effective-kotlin' } },
+  { text: 'typescript strict mode null undefined checks', metadata: { name: 'effective-typescript' } },
+  { text: 'java generics wildcards bounded type parameters', metadata: { name: 'effective-java' } },
+  { text: 'kotlin data class immutable copy pattern', metadata: { name: 'effective-kotlin' } },
+  { text: 'clean code naming variables functions clear intent', metadata: { name: 'clean-code-reviewer' } },
+];
+
+describe('BM25Index', () => {
+  it('returns higher score for documents containing query terms', () => {
+    const idx = new BM25Index();
+    idx.build(CHUNKS);
+    const results = idx.search('kotlin null safety', 3);
+    assert.ok(results.length > 0);
+    assert.strictEqual(results[0].metadata.name, 'effective-kotlin');
+    assert.ok(results[0].score > 0);
+  });
+
+  it('returns results sorted by score descending', () => {
+    const idx = new BM25Index();
+    idx.build(CHUNKS);
+    const results = idx.search('kotlin', 5);
+    for (let i = 1; i < results.length; i++) {
+      assert.ok(results[i - 1].score >= results[i].score);
+    }
+  });
+
+  it('returns empty array for query with no matching terms', () => {
+    const idx = new BM25Index();
+    idx.build(CHUNKS);
+    const results = idx.search('xyzzy completely unknown term', 5);
+    assert.strictEqual(results.length, 0);
+  });
+
+  it('save and load round-trip preserves search results', () => {
+    const tmpFile = path.join(os.tmpdir(), `bm25-test-${Date.now()}.json`);
+    try {
+      const idx = new BM25Index();
+      idx.build(CHUNKS);
+      idx.save(tmpFile);
+      const loaded = BM25Index.load(tmpFile);
+      const original = idx.search('kotlin null', 3);
+      const restored = loaded.search('kotlin null', 3);
+      assert.deepEqual(original.map(r => r.metadata.name), restored.map(r => r.metadata.name));
+    } finally {
+      fs.unlinkSync(tmpFile);
+    }
+  });
+
+  it('add() appends a document and it becomes searchable', () => {
+    const idx = new BM25Index();
+    idx.build(CHUNKS);
+    idx.add({ text: 'python dataclass immutable frozen field', metadata: { name: 'effective-python' } });
+    const results = idx.search('python dataclass', 3);
+    assert.ok(results.some(r => r.metadata.name === 'effective-python'));
+  });
+
+  it('search on empty index returns empty array', () => {
+    const idx = new BM25Index();
+    const results = idx.search('kotlin', 5);
+    assert.deepEqual(results, []);
+  });
+
+  it('search with all short tokens returns empty array', () => {
+    const idx = new BM25Index();
+    idx.build(CHUNKS);
+    const results = idx.search('a b', 5);
+    assert.strictEqual(results.length, 0);
+  });
+
+  it('add() works on a fresh index without prior build()', () => {
+    const idx = new BM25Index();
+    idx.add({ text: 'kotlin extension function', metadata: { name: 'effective-kotlin' } });
+    const results = idx.search('kotlin extension', 3);
+    assert.ok(results.length > 0);
+    assert.strictEqual(results[0].metadata.name, 'effective-kotlin');
+  });
+});

package/tests/engine/capture-command.test.js

@@ -0,0 +1,35 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { parseCaptureLinkArgs } from '../../lib/engine/graph.js';
+
+test('parseCaptureLinkArgs returns empty array for empty string', () => {
+  assert.deepStrictEqual(parseCaptureLinkArgs(''), []);
+});
+
+test('parseCaptureLinkArgs parses single link', () => {
+  const result = parseCaptureLinkArgs('effective-kotlin:applies-to');
+  assert.deepStrictEqual(result, [{ to: 'effective-kotlin', type: 'applies-to' }]);
+});
+
+test('parseCaptureLinkArgs parses multiple links', () => {
+  const result = parseCaptureLinkArgs('effective-kotlin:applies-to,design-patterns:see-also');
+  assert.deepStrictEqual(result, [
+    { to: 'effective-kotlin', type: 'applies-to' },
+    { to: 'design-patterns', type: 'see-also' },
+  ]);
+});
+
+test('parseCaptureLinkArgs trims whitespace', () => {
+  const result = parseCaptureLinkArgs(' effective-kotlin : applies-to ');
+  assert.deepStrictEqual(result, [{ to: 'effective-kotlin', type: 'applies-to' }]);
+});
+
+test('parseCaptureLinkArgs skips malformed pairs without colon', () => {
+  const result = parseCaptureLinkArgs('effective-kotlin,design-patterns:see-also');
+  assert.deepStrictEqual(result, [{ to: 'design-patterns', type: 'see-also' }]);
+});
+
+test('parseCaptureLinkArgs handles skill names with hyphens', () => {
+  const result = parseCaptureLinkArgs('clean-code-reviewer:see-also');
+  assert.deepStrictEqual(result, [{ to: 'clean-code-reviewer', type: 'see-also' }]);
+});

package/tests/engine/capture.test.js

@@ -0,0 +1,17 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { buildDictatePrompt, buildSummarizePrompt } from '../../lib/engine/capture.js';
+
+test('buildDictatePrompt contains raw text and required fields', () => {
+  const prompt = buildDictatePrompt('rough ideas about auth');
+  assert.ok(prompt.includes('rough ideas about auth'));
+  assert.ok(prompt.includes('title'));
+  assert.ok(prompt.includes('tags'));
+});
+
+test('buildSummarizePrompt contains conversation and required sections', () => {
+  const prompt = buildSummarizePrompt('User: question\nAssistant: answer', 'My title');
+  assert.ok(prompt.includes('User: question'));
+  assert.ok(prompt.includes('Key Decisions'));
+  assert.ok(prompt.includes('My title'));
+});