@aprimediet/codewalker 1.2.0 → 1.3.0

package/src/db.test.ts

@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import Database from 'better-sqlite3';
-import { openDb, bootstrapDb, upsertSymbol, searchSymbols, getMeta, setMeta, deleteFileSymbols, upsertLibrary, upsertLibSymbol, deleteLibrary, searchLibSymbols } from './db.ts';
+import { openDb, bootstrapDb, upsertSymbol, searchSymbols, getMeta, setMeta, deleteFileSymbols, upsertLibrary, upsertLibSymbol, deleteLibrary, searchLibSymbols, upsertNote, searchNotes, deleteNote, updateSymbolSummary, selectUnenrichedSymbols } from './db.ts';
 
 describe('db.ts', () => {
   let tmpDir: string;
@@ -47,11 +47,11 @@ describe('db.ts', () => {
       // No error = idempotent
     });
 
-    it('sets user_version to 1', () => {
+    it('sets user_version to 3 (v1.3 schema)', () => {
       const db = new Database(dbPath);
       bootstrapDb(db);
       const version = db.pragma('user_version', { simple: true }) as number;
-      expect(version).toBe(2);
+      expect(version).toBe(3);
       db.close();
     });
 
@@ -67,8 +67,8 @@ describe('db.ts', () => {
       db.close();
     });
 
-    it('does not destroy existing symbols tables (additive upgrade)', () => {
-      // Bootstrap v1 DB first, then re-bootstrap (simulate upgrade)
+    it('does not destroy existing tables (additive upgrade, v2 → notes in v3)', () => {
+      // Bootstrap then re-bootstrap (simulate upgrade)
       const db = new Database(dbPath);
       bootstrapDb(db);
       upsertSymbol(db, {
@@ -76,16 +76,19 @@ describe('db.ts', () => {
         line_start: 1, line_end: 1, signature: '', doc: '', summary: '', card_path: '',
       });
 
-      // Call bootstrapDb again (simulates upgrade to v2 adds lib tables)
+      // Call bootstrapDb again (simulates upgrade to v3 adds notes tables)
       bootstrapDb(db);
 
       // Symbol still there
       const symbols = searchSymbols(db, 'keep', undefined, 10);
       expect(symbols).toHaveLength(1);
 
-      // Lib tables exist
+      // Notes tables exist
       const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all() as { name: string }[];
-      expect(tables.map(t => t.name)).toContain('lib_symbols');
+      expect(tables.map(t => t.name)).toContain('notes');
+
+      const ftsTables = db.prepare("SELECT name FROM sqlite_master WHERE name='notes_fts'").all() as { name: string }[];
+      expect(ftsTables.length).toBe(1);
       db.close();
     });
   });
@@ -319,6 +322,259 @@ describe('db.ts', () => {
     });
   });
 
+  describe('notes CRUD + FTS via triggers', () => {
+    it('creates notes + notes_fts on bootstrap', () => {
+      const db = openDb(dbPath);
+      const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all() as { name: string }[];
+      expect(tables.map(t => t.name)).toContain('notes');
+
+      const ftsTables = db.prepare("SELECT name FROM sqlite_master WHERE name='notes_fts'").all() as { name: string }[];
+      expect(ftsTables.length).toBe(1);
+
+      // Triggers exist
+      const triggers = db.prepare("SELECT name FROM sqlite_master WHERE type='trigger'").all() as { name: string }[];
+      const triggerNames = triggers.map(t => t.name);
+      expect(triggerNames).toContain('notes_ai');
+      expect(triggerNames).toContain('notes_ad');
+      expect(triggerNames).toContain('notes_au');
+      db.close();
+    });
+
+    it('upsertNote inserts a note and FTS MATCH finds it', () => {
+      const db = openDb(dbPath);
+
+      const id = upsertNote(db, {
+        note_kind: 'glossary',
+        title: 'Idempotency Key',
+        body: 'A client-supplied key that makes a retried POST safe to replay.',
+        tags: 'api,payments',
+        related: 'createCharge',
+        card_path: '/entries/glossary/idempotency-key.md',
+      });
+
+      expect(typeof id).toBe('number');
+      expect(id).toBeGreaterThan(0);
+
+      // FTS search
+      const results = searchNotes(db, 'idempotency');
+      expect(results).toHaveLength(1);
+      expect(results[0]!.name).toBe('Idempotency Key');
+      expect(results[0]!.note_kind).toBe('glossary');
+      expect(results[0]!.source).toBe('note');
+
+      db.close();
+    });
+
+    it('upsertNote upserts on (note_kind, title) — updating a note refreshes FTS via notes_au', () => {
+      const db = openDb(dbPath);
+
+      upsertNote(db, {
+        note_kind: 'glossary',
+        title: 'Retry Key',
+        body: 'Old description',
+        tags: '',
+        related: '',
+        card_path: '/entries/glossary/retry-key.md',
+      });
+
+      // Update the body
+      upsertNote(db, {
+        note_kind: 'glossary',
+        title: 'Retry Key',
+        body: 'New improved description with uniqueTermXYZ',
+        tags: 'updated',
+        related: '',
+        card_path: '/entries/glossary/retry-key.md',
+      });
+
+      // Should find by new text (proves notes_au fired the reindex)
+      const results = searchNotes(db, 'uniqueTermXYZ');
+      expect(results).toHaveLength(1);
+      expect(results[0]!.summary).toContain('uniqueTermXYZ');
+
+      // Should NOT have duplicates (upsert behavior)
+      const all = searchNotes(db, '');
+      expect(all).toHaveLength(1);
+
+      db.close();
+    });
+
+    it('deleteNote removes a note from both base table and FTS', () => {
+      const db = openDb(dbPath);
+
+      upsertNote(db, {
+        note_kind: 'glossary',
+        title: 'Temp Term',
+        body: 'Will be deleted',
+        tags: '',
+        related: '',
+        card_path: '',
+      });
+
+      deleteNote(db, 'glossary', 'Temp Term');
+
+      const results = searchNotes(db, 'Temp');
+      expect(results).toHaveLength(0);
+
+      // Verify base table is also empty
+      const row = db.prepare("SELECT * FROM notes WHERE title = ?").get('Temp Term');
+      expect(row).toBeUndefined();
+
+      db.close();
+    });
+
+    it('searchNotes empty query returns all notes ordered by title', () => {
+      const db = openDb(dbPath);
+
+      upsertNote(db, {
+        note_kind: 'glossary', title: 'Zebra', body: '', tags: '', related: '', card_path: '',
+      });
+      upsertNote(db, {
+        note_kind: 'decision', title: 'Alpha decision', body: '', tags: '', related: '', card_path: '',
+      });
+
+      const results = searchNotes(db, '');
+      expect(results).toHaveLength(2);
+      expect(results[0]!.name).toBe('Alpha decision');
+      expect(results[1]!.name).toBe('Zebra');
+
+      db.close();
+    });
+
+    it('searchNotes with kindFilter narrows by note_kind', () => {
+      const db = openDb(dbPath);
+
+      upsertNote(db, {
+        note_kind: 'glossary', title: 'Term', body: '', tags: '', related: '', card_path: '',
+      });
+      upsertNote(db, {
+        note_kind: 'decision', title: 'Decide', body: '', tags: '', related: '', card_path: '',
+      });
+
+      const glossaryResults = searchNotes(db, '', 'glossary');
+      expect(glossaryResults).toHaveLength(1);
+      expect(glossaryResults[0]!.name).toBe('Term');
+
+      const decisionResults = searchNotes(db, '', 'decision');
+      expect(decisionResults).toHaveLength(1);
+      expect(decisionResults[0]!.name).toBe('Decide');
+
+      db.close();
+    });
+  });
+
+  describe('updateSymbolSummary', () => {
+    it('sets symbols.summary for a matching card_path and symbols_au reindexes FTS', () => {
+      const db = openDb(dbPath);
+
+      upsertSymbol(db, {
+        name: 'myFunc', kind: 'function', file_path: 'src/a.ts',
+        line_start: 1, line_end: 10, signature: '', doc: 'Old doc', summary: '',
+        card_path: '/cards/myFunc.md',
+      });
+
+      const result = updateSymbolSummary(db, '/cards/myFunc.md', 'A function that does X');
+      expect(result).toBe(true);
+
+      // Query FTS for the summary word — proves symbols_au trigger reindexed
+      const syms = searchSymbols(db, 'does X', undefined, 10);
+      expect(syms).toHaveLength(1);
+      expect(syms[0]!.name).toBe('myFunc');
+      expect(syms[0]!.summary).toBe('A function that does X');
+
+      db.close();
+    });
+
+    it('returns false when no symbol matches card_path', () => {
+      const db = openDb(dbPath);
+      const result = updateSymbolSummary(db, '/nonexistent.md', 'summary');
+      expect(result).toBe(false);
+      db.close();
+    });
+  });
+
+  describe('selectUnenrichedSymbols', () => {
+    it('selects symbols with empty summary under a path prefix', () => {
+      const db = openDb(dbPath);
+
+      upsertSymbol(db, {
+        name: 'enriched', kind: 'function', file_path: 'src/auth/token.ts',
+        line_start: 1, line_end: 5, signature: '', doc: '', summary: 'Already done',
+        card_path: '/cards/enriched.md',
+      });
+      upsertSymbol(db, {
+        name: 'unenriched', kind: 'function', file_path: 'src/auth/token.ts',
+        line_start: 10, line_end: 20, signature: '', doc: '', summary: '',
+        card_path: '/cards/unenriched.md',
+      });
+      upsertSymbol(db, {
+        name: 'other', kind: 'function', file_path: 'src/other/util.ts',
+        line_start: 1, line_end: 1, signature: '', doc: '', summary: '',
+        card_path: '/cards/other.md',
+      });
+
+      const results = selectUnenrichedSymbols(db, 'src/auth/', 10);
+      expect(results).toHaveLength(1);
+      expect(results[0]!.name).toBe('unenriched');
+      expect(results[0]!.card_path).toBe('/cards/unenriched.md');
+
+      db.close();
+    });
+
+    it('returns empty for a prefix with no unenriched symbols', () => {
+      const db = openDb(dbPath);
+
+      upsertSymbol(db, {
+        name: 'done', kind: 'function', file_path: 'src/done.ts',
+        line_start: 1, line_end: 1, signature: '', doc: '', summary: 'Has summary',
+        card_path: '',
+      });
+
+      const results = selectUnenrichedSymbols(db, 'src/done.ts', 10);
+      expect(results).toHaveLength(0);
+
+      db.close();
+    });
+
+    it('respects limit parameter', () => {
+      const db = openDb(dbPath);
+
+      for (let i = 0; i < 5; i++) {
+        upsertSymbol(db, {
+          name: `sym${i}`, kind: 'function', file_path: 'src/a.ts',
+          line_start: i, line_end: i, signature: '', doc: '', summary: '',
+          card_path: '',
+        });
+      }
+
+      const results = selectUnenrichedSymbols(db, 'src/', 3);
+      expect(results).toHaveLength(3);
+
+      db.close();
+    });
+
+    it('returns card_path, name, kind, file_path, line_start, line_end for each result', () => {
+      const db = openDb(dbPath);
+
+      upsertSymbol(db, {
+        name: 'myFunc', kind: 'function', file_path: 'src/test.ts',
+        line_start: 10, line_end: 20, signature: '', doc: '', summary: '',
+        card_path: '/cards/test.md',
+      });
+
+      const results = selectUnenrichedSymbols(db, 'src/', 10);
+      expect(results).toHaveLength(1);
+      expect(results[0]!.name).toBe('myFunc');
+      expect(results[0]!.kind).toBe('function');
+      expect(results[0]!.file_path).toBe('src/test.ts');
+      expect(results[0]!.line_start).toBe(10);
+      expect(results[0]!.line_end).toBe(20);
+      expect(results[0]!.card_path).toBe('/cards/test.md');
+
+      db.close();
+    });
+  });
+
   describe('meta', () => {
     it('setMeta and getMeta round-trip values', () => {
       const db = openDb(dbPath);

package/src/db.ts

@@ -12,7 +12,7 @@
  */
 
 import Database, { type Database as DatabaseType } from "better-sqlite3";
-import type { LibSymbol } from "./types.ts";
+import type { LibSymbol, NoteKind } from "./types.ts";
 
 export { Database };
 export type { DatabaseType };
@@ -28,7 +28,7 @@ export function openDb(dbPath: string): DatabaseType {
 /** Bootstrap DDL — idempotent (all CREATE use IF NOT EXISTS). */
 export function bootstrapDb(db: DatabaseType): void {
   db.exec(`
-    PRAGMA user_version = 2;
+    PRAGMA user_version = 3;
 
     CREATE TABLE IF NOT EXISTS files (
       path        TEXT PRIMARY KEY,
@@ -120,9 +120,59 @@ export function bootstrapDb(db: DatabaseType): void {
       INSERT INTO lib_symbols_fts(rowid, name, signature, doc, summary)
       VALUES (new.id, new.name, new.signature, new.doc, new.summary);
     END;
+
+    -- v1.3: Notes table for glossary/decision bridge cards
+    CREATE TABLE IF NOT EXISTS notes (
+      id          INTEGER PRIMARY KEY AUTOINCREMENT,
+      note_kind   TEXT NOT NULL,
+      title       TEXT NOT NULL,
+      body        TEXT,
+      tags        TEXT,
+      related     TEXT,
+      card_path   TEXT,
+      created_at  TEXT
+    );
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(
+      title, body, tags,
+      content='notes', content_rowid='id',
+      tokenize='unicode61 remove_diacritics 2'
+    );
+
+    CREATE TRIGGER IF NOT EXISTS notes_ai AFTER INSERT ON notes BEGIN
+      INSERT INTO notes_fts(rowid, title, body, tags)
+      VALUES (new.id, new.title, new.body, new.tags);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS notes_ad AFTER DELETE ON notes BEGIN
+      INSERT INTO notes_fts(notes_fts, rowid, title, body, tags)
+      VALUES ('delete', old.id, old.title, old.body, old.tags);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS notes_au AFTER UPDATE ON notes BEGIN
+      INSERT INTO notes_fts(notes_fts, rowid, title, body, tags)
+      VALUES ('delete', old.id, old.title, old.body, old.tags);
+      INSERT INTO notes_fts(rowid, title, body, tags)
+      VALUES (new.id, new.title, new.body, new.tags);
+    END;
   `);
 }
 
+/**
+ * Re-derive the external-content FTS indexes from their content tables (the FTS5 'rebuild'
+ * command). This heals a stale/legacy index: a DB written by an older (pre-trigger, manual-sync)
+ * build can have a `*_fts` shadow that is silently out of sync with its base table. The
+ * `*_ad`/`*_au` triggers issue FTS5 'delete' commands using `old.*` values; if those don't match
+ * the stale index, the delete decrements counts that aren't there and corrupts the index
+ * ("database disk image is malformed"). Running 'rebuild' first makes subsequent trigger-driven
+ * deletes safe. Cheap and idempotent — it only re-tokenizes existing rows (no filesystem work).
+ */
+export function rebuildFtsIndexes(db: DatabaseType): void {
+  db.exec("INSERT INTO symbols_fts(symbols_fts) VALUES('rebuild')");
+  db.exec("INSERT INTO lib_symbols_fts(lib_symbols_fts) VALUES('rebuild')");
+  db.exec("INSERT INTO notes_fts(notes_fts) VALUES('rebuild')");
+}
+
 /** Upsert a file record. */
 export function upsertFile(
   db: DatabaseType,
@@ -223,6 +273,162 @@ export function searchSymbols(
   return db.prepare(sql).all(...params) as typeof results;
 }
 
+// ── Notes CRUD ─────────────────────────────────────────────────
+
+/**
+ * Upsert a note keyed on (note_kind, title).
+ * Returns the row id.
+ */
+export function upsertNote(
+  db: DatabaseType,
+  note: { note_kind: string; title: string; body: string; tags: string; related: string; card_path: string },
+): number {
+  const existing = db.prepare(
+    "SELECT id FROM notes WHERE note_kind = ? AND title = ?",
+  ).get(note.note_kind, note.title) as { id: number } | undefined;
+
+  if (existing) {
+    db.prepare(
+      `UPDATE notes SET body=?, tags=?, related=?, card_path=?, created_at=COALESCE(created_at, datetime('now'))
+       WHERE id = ?`,
+    ).run(note.body, note.tags, note.related, note.card_path, existing.id);
+    return existing.id;
+  }
+
+  const result = db.prepare(
+    `INSERT INTO notes (note_kind, title, body, tags, related, card_path, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, datetime('now'))`,
+  ).run(note.note_kind, note.title, note.body, note.tags, note.related, note.card_path);
+  return Number(result.lastInsertRowid);
+}
+
+/** Delete a note by (note_kind, title). */
+export function deleteNote(db: DatabaseType, noteKind: string, title: string): void {
+  db.prepare("DELETE FROM notes WHERE note_kind = ? AND title = ?").run(noteKind, title);
+}
+
+/**
+ * Search notes via FTS5 MATCH, ranked by bm25.
+ * Empty query returns all notes ordered by title.
+ * Each result is shaped as a QueryResultRow with source:'note'.
+ */
+export function searchNotes(
+  db: DatabaseType,
+  query: string,
+  kindFilter?: NoteKind,
+  limit = 10,
+): Array<{
+  id: number;
+  name: string;
+  kind: string;
+  summary: string;
+  score: number;
+  source: "note";
+  note_kind: NoteKind;
+  tags: string;
+  file_path: string;
+  line_start: number;
+  line_end: number;
+}> {
+  if (!query.trim()) {
+    let sql = "SELECT n.id, n.title as name, n.note_kind as kind, n.body as summary, n.tags, 0.0 as score FROM notes n";
+    const params: unknown[] = [];
+    if (kindFilter) {
+      sql += " WHERE n.note_kind = ?";
+      params.push(kindFilter);
+    }
+    sql += " ORDER BY n.title LIMIT ?";
+    params.push(limit);
+    const rows = db.prepare(sql).all(...params) as any[];
+    return rows.map((r) => ({
+      ...r,
+      source: "note" as const,
+      note_kind: r.kind as NoteKind,
+      file_path: "",
+      line_start: 0,
+      line_end: 0,
+    }));
+  }
+
+  let sql = `
+    SELECT n.id, n.title as name, n.note_kind as kind, n.body as summary, n.tags,
+           bm25(notes_fts, 10.0, 5.0, 3.0) as score
+    FROM notes_fts
+    JOIN notes n ON n.id = notes_fts.rowid
+    WHERE notes_fts MATCH ?
+  `;
+  const params: unknown[] = [query];
+
+  if (kindFilter) {
+    sql += " AND n.note_kind = ?";
+    params.push(kindFilter);
+  }
+
+  sql += " ORDER BY score LIMIT ?";
+  params.push(limit);
+
+  const rows = db.prepare(sql).all(...params) as any[];
+  return rows.map((r) => ({
+    ...r,
+    source: "note" as const,
+    note_kind: r.kind as NoteKind,
+    file_path: "",
+    line_start: 0,
+    line_end: 0,
+  }));
+}
+
+// ── Enrichment helpers ──────────────────────────────────────────
+
+/**
+ * Update symbols.summary for a given card_path.
+ * Returns true if a row was updated, false if no symbol matched.
+ * The existing symbols_au trigger reindexes FTS automatically.
+ */
+export function updateSymbolSummary(
+  db: DatabaseType,
+  cardPath: string,
+  summary: string,
+): boolean {
+  const result = db.prepare(
+    "UPDATE symbols SET summary = ? WHERE card_path = ?",
+  ).run(summary, cardPath);
+  return result.changes > 0;
+}
+
+/**
+ * Select unenriched symbols (summary IS NULL or empty) under a path prefix.
+ * Results ordered by file_path then line_start.
+ */
+export function selectUnenrichedSymbols(
+  db: DatabaseType,
+  pathPrefix: string,
+  limit: number,
+): Array<{
+  name: string;
+  kind: string;
+  file_path: string;
+  line_start: number;
+  line_end: number;
+  card_path: string;
+}> {
+  return db.prepare(
+    `SELECT name, kind, file_path, line_start, line_end, card_path
+     FROM symbols
+     WHERE (summary IS NULL OR summary = '')
+       AND file_path LIKE ?
+     ORDER BY file_path, line_start
+     LIMIT ?`,
+  ).all(pathPrefix + "%", limit) as Array<{
+    name: string;
+    kind: string;
+    file_path: string;
+    line_start: number;
+    line_end: number;
+    card_path: string;
+  }>;
+}
+
 /** Upsert a library record. */
 export function upsertLibrary(
   db: DatabaseType,

package/src/enrich.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from 'vitest';
+import { formatEnrichWorklist, validateEnrichPath, checkEnrichCap } from './enrich.ts';
+import type { UnenrichedSymbol } from './enrich.ts';
+
+function makeSym(overrides: Partial<UnenrichedSymbol> = {}): UnenrichedSymbol {
+  return {
+    name: 'myFunc',
+    kind: 'function',
+    file_path: 'src/auth/token.ts',
+    line_start: 10,
+    line_end: 30,
+    card_path: '/entries/symbols/auth-token/myFunc.md',
+    ...overrides,
+  };
+}
+
+describe('validateEnrichPath', () => {
+  it('accepts a non-empty path', () => {
+    const result = validateEnrichPath('src/auth');
+    expect(result.valid).toBe(true);
+    expect(result.error).toBeUndefined();
+  });
+
+  it('rejects empty string', () => {
+    const result = validateEnrichPath('');
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain('specify a path');
+  });
+
+  it('rejects whitespace-only', () => {
+    const result = validateEnrichPath('   ');
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain('specify a path');
+  });
+
+  it('rejects undefined/null', () => {
+    const result = validateEnrichPath(undefined as any);
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain('specify a path');
+  });
+});
+
+describe('checkEnrichCap', () => {
+  it('returns ok when count within cap', () => {
+    const result = checkEnrichCap(5, 40);
+    expect(result.ok).toBe(true);
+    expect(result.count).toBe(5);
+    expect(result.skipped).toBe(0);
+    expect(result.error).toBeUndefined();
+  });
+
+  it('rejects when count exceeds cap', () => {
+    const result = checkEnrichCap(100, 40);
+    expect(result.ok).toBe(false);
+    expect(result.count).toBe(100);
+    expect(result.skipped).toBe(60);
+    expect(result.error).toContain('100 symbols');
+    expect(result.error).toContain('--max=100');
+  });
+
+  it('uses default cap when not specified', () => {
+    const result = checkEnrichCap(50);
+    expect(result.ok).toBe(false);
+    expect(result.error).toContain('--max=50');
+  });
+
+  it('accepts edge case at exactly cap', () => {
+    const result = checkEnrichCap(40, 40);
+    expect(result.ok).toBe(true);
+    expect(result.count).toBe(40);
+  });
+});
+
+describe('formatEnrichWorklist', () => {
+  it('formats symbols into compact lines', () => {
+    const syms = [
+      makeSym({ name: 'refreshToken', file_path: 'src/auth/token.ts', line_start: 42, line_end: 71 }),
+      makeSym({ name: 'validateJwt', file_path: 'src/auth/jwt.ts', line_start: 10, line_end: 30 }),
+    ];
+
+    const result = formatEnrichWorklist(syms, 'src/auth');
+    expect(result).toContain('refreshToken');
+    expect(result).toContain('validateJwt');
+    expect(result).toContain('src/auth');
+    expect(result).toContain('42-71');
+    expect(result).toContain('10-30');
+    expect(result).toMatch(/function/g);
+  });
+
+  it('includes instructions for the agent', () => {
+    const syms = [makeSym()];
+    const result = formatEnrichWorklist(syms, 'src/');
+    expect(result).toContain('codewalker_enrich');
+    expect(result).toContain('summary');
+    expect(result).toContain('120');
+  });
+
+  it('says "No unenriched symbols" for empty array', () => {
+    const result = formatEnrichWorklist([], 'src/');
+    expect(result).toContain('No unenriched symbols');
+  });
+});