@aprimediet/codewalker 1.2.0 → 1.4.0

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 = 4;
 
     CREATE TABLE IF NOT EXISTS files (
       path        TEXT PRIMARY KEY,
@@ -120,9 +120,99 @@ 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;
+
+    -- v1.4: Analysis table for coverage/debt/practice findings
+    CREATE TABLE IF NOT EXISTS analysis (
+      id            INTEGER PRIMARY KEY AUTOINCREMENT,
+      finding_kind  TEXT NOT NULL,
+      title         TEXT NOT NULL,
+      severity      TEXT,
+      file_path     TEXT,
+      line_start    INTEGER,
+      line_end      INTEGER,
+      metric        TEXT,
+      body          TEXT,
+      related       TEXT,
+      card_path     TEXT,
+      created_at    TEXT
+    );
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS analysis_fts USING fts5(
+      title, body, metric,
+      content='analysis', content_rowid='id',
+      tokenize='unicode61 remove_diacritics 2'
+    );
+
+    CREATE TRIGGER IF NOT EXISTS analysis_ai AFTER INSERT ON analysis BEGIN
+      INSERT INTO analysis_fts(rowid, title, body, metric)
+      VALUES (new.id, new.title, new.body, new.metric);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS analysis_ad AFTER DELETE ON analysis BEGIN
+      INSERT INTO analysis_fts(analysis_fts, rowid, title, body, metric)
+      VALUES ('delete', old.id, old.title, old.body, old.metric);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS analysis_au AFTER UPDATE ON analysis BEGIN
+      INSERT INTO analysis_fts(analysis_fts, rowid, title, body, metric)
+      VALUES ('delete', old.id, old.title, old.body, old.metric);
+      INSERT INTO analysis_fts(rowid, title, body, metric)
+      VALUES (new.id, new.title, new.body, new.metric);
+    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')");
+  db.exec("INSERT INTO analysis_fts(analysis_fts) VALUES('rebuild')");
+}
+
 /** Upsert a file record. */
 export function upsertFile(
   db: DatabaseType,
@@ -223,6 +313,312 @@ 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,
+  }));
+}
+
+// ── Analysis CRUD ────────────────────────────────────────────
+
+/**
+ * Allowed finding kinds.
+ */
+const VALID_FINDING_KINDS = new Set(["coverage", "debt", "practice"]);
+
+/**
+ * Upsert a finding keyed on (finding_kind, file_path, title).
+ * Returns the row id.
+ */
+export function upsertFinding(
+  db: DatabaseType,
+  finding: {
+    finding_kind: string;
+    title: string;
+    severity?: string;
+    file_path?: string;
+    line_start?: number;
+    line_end?: number;
+    metric?: string;
+    body?: string;
+    related?: string;
+    card_path?: string;
+  },
+): number {
+  if (!VALID_FINDING_KINDS.has(finding.finding_kind)) {
+    throw new Error(`Invalid finding_kind "${finding.finding_kind}". Must be coverage, debt, or practice.`);
+  }
+
+  const existing = db.prepare(
+    "SELECT id FROM analysis WHERE finding_kind = ? AND file_path = ? AND title = ?",
+  ).get(finding.finding_kind, finding.file_path ?? "", finding.title) as { id: number } | undefined;
+
+  if (existing) {
+    db.prepare(
+      `UPDATE analysis SET severity=?, line_start=?, line_end=?, metric=?, body=?, related=?, card_path=?, created_at=COALESCE(created_at, datetime('now'))
+       WHERE id = ?`,
+    ).run(
+      finding.severity ?? null, finding.line_start ?? null, finding.line_end ?? null,
+      finding.metric ?? null, finding.body ?? null, finding.related ?? null,
+      finding.card_path ?? null, existing.id,
+    );
+    return existing.id;
+  }
+
+  const result = db.prepare(
+    `INSERT INTO analysis (finding_kind, title, severity, file_path, line_start, line_end, metric, body, related, card_path, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))`,
+  ).run(
+    finding.finding_kind, finding.title, finding.severity ?? null, finding.file_path ?? "",
+    finding.line_start ?? null, finding.line_end ?? null, finding.metric ?? null,
+    finding.body ?? null, finding.related ?? null, finding.card_path ?? null,
+  );
+  return Number(result.lastInsertRowid);
+}
+
+/**
+ * Delete all findings for a given file of a given kind.
+ * The analysis_ad trigger removes the FTS rows.
+ */
+export function deleteFindingsForFile(
+  db: DatabaseType,
+  findingKind: string,
+  filePath: string,
+): void {
+  db.prepare("DELETE FROM analysis WHERE finding_kind = ? AND file_path = ?").run(findingKind, filePath);
+}
+
+/**
+ * Search findings via FTS5 MATCH, ranked by bm25.
+ * Empty query returns all findings ordered by severity, title.
+ * Each result is shaped as a QueryResultRow with source:'analysis'.
+ */
+export function searchFindings(
+  db: DatabaseType,
+  query: string,
+  kindFilter?: string,
+  limit = 10,
+): Array<{
+  id: number;
+  name: string;
+  kind: string;
+  summary: string;
+  score: number;
+  source: "analysis";
+  finding_kind: string;
+  severity: string | null;
+  metric: string | null;
+  file_path: string;
+  line_start: number;
+  line_end: number;
+}> {
+  if (!query.trim()) {
+    let sql = `
+      SELECT a.id, a.title as name, a.finding_kind as kind, a.body as summary,
+             a.severity, a.metric, a.file_path, a.line_start, a.line_end, 0.0 as score
+      FROM analysis a
+    `;
+    const params: unknown[] = [];
+    if (kindFilter) {
+      sql += " WHERE a.finding_kind = ?";
+      params.push(kindFilter);
+    }
+    sql += " ORDER BY CASE a.severity WHEN 'high' THEN 1 WHEN 'warn' THEN 2 WHEN 'info' THEN 3 ELSE 4 END, a.title LIMIT ?";
+    params.push(limit);
+    const rows = db.prepare(sql).all(...params) as any[];
+    return rows.map((r) => ({
+      ...r,
+      source: "analysis" as const,
+      finding_kind: r.kind as string,
+      file_path: r.file_path ?? "",
+      line_start: r.line_start ?? 0,
+      line_end: r.line_end ?? 0,
+      severity: r.severity ?? null,
+      metric: r.metric ?? null,
+    }));
+  }
+
+  let sql = `
+    SELECT a.id, a.title as name, a.finding_kind as kind, a.body as summary,
+           a.severity, a.metric, a.file_path, a.line_start, a.line_end,
+           bm25(analysis_fts, 10.0, 5.0, 3.0) as score
+    FROM analysis_fts
+    JOIN analysis a ON a.id = analysis_fts.rowid
+    WHERE analysis_fts MATCH ?
+  `;
+  const params: unknown[] = [query];
+
+  if (kindFilter) {
+    sql += " AND a.finding_kind = ?";
+    params.push(kindFilter);
+  }
+
+  sql += " ORDER BY CASE a.severity WHEN 'high' THEN 1 WHEN 'warn' THEN 2 WHEN 'info' THEN 3 ELSE 4 END, score LIMIT ?";
+  params.push(limit);
+
+  const rows = db.prepare(sql).all(...params) as any[];
+  return rows.map((r) => ({
+    ...r,
+    source: "analysis" as const,
+    finding_kind: r.kind as string,
+    file_path: r.file_path ?? "",
+    line_start: r.line_start ?? 0,
+    line_end: r.line_end ?? 0,
+    severity: r.severity ?? null,
+    metric: r.metric ?? null,
+  }));
+}
+
+// ── 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');
+  });
+});

package/src/enrich.ts

@@ -0,0 +1,107 @@
+/**
+ * Enrichment core for codewalker v1.3.
+ *
+ * Pure/lightweight helpers for the enrichment workflow:
+ * - `validateEnrichPath()` — ensures path is provided
+ * - `checkEnrichCap()` — enforces the enrichment cap guardrail
+ * - `formatEnrichWorklist()` — formats worklist items for agent display
+ *
+ * The heavy lifting (selecting unenriched symbols) lives in db.ts.
+ * The write-back path (updating card + DB) is in cards.ts + db.ts.
+ */
+
+/** Default maximum symbols per enrich command. */
+export const DEFAULT_ENRICH_CAP = 40;
+
+/** A single unenriched symbol from the selection query. */
+export interface UnenrichedSymbol {
+  name: string;
+  kind: string;
+  file_path: string;
+  line_start: number;
+  line_end: number;
+  card_path: string;
+}
+
+/** Result of validateEnrichPath. */
+export interface PathValidation {
+  valid: boolean;
+  error?: string;
+}
+
+/** Result of checkEnrichCap. */
+export interface CapCheck {
+  ok: boolean;
+  count: number;
+  /** Number of symbols over the cap (only when !ok). */
+  skipped: number;
+  error?: string;
+}
+
+/**
+ * Validate that an enrichment path was provided.
+ */
+export function validateEnrichPath(path: string | undefined | null): PathValidation {
+  const trimmed = (path ?? "").trim();
+  if (!trimmed) {
+    return {
+      valid: false,
+      error: 'specify a path, e.g. src/auth. Bare /codewalker enrich with no path is not allowed.',
+    };
+  }
+  return { valid: true };
+}
+
+/**
+ * Check whether a count of unenriched symbols exceeds the cap.
+ * If ok is false, the caller should refuse and tell the user to narrow the path.
+ *
+ * @param count - Number of unenriched symbols found.
+ * @param cap - Maximum allowed (default: DEFAULT_ENRICH_CAP = 40).
+ */
+export function checkEnrichCap(count: number, cap: number = DEFAULT_ENRICH_CAP): CapCheck {
+  if (count > cap) {
+    const skipped = count - cap;
+    return {
+      ok: false,
+      count,
+      skipped,
+      error: `Refusing to enrich ${count} symbols (cap ${cap}). ` +
+        `Narrow your path or raise the cap with --max=${count}.`,
+    };
+  }
+  return { ok: true, count, skipped: 0 };
+}
+
+/**
+ * Format an enrichment worklist for the agent to process.
+ * Each line shows one unenriched symbol. Includes a header with instructions.
+ */
+export function formatEnrichWorklist(
+  symbols: UnenrichedSymbol[],
+  pathPrefix: string,
+): string {
+  if (symbols.length === 0) {
+    return `No unenriched symbols found under "${pathPrefix}". All symbols in this path already have summaries.`;
+  }
+
+  const lines: string[] = [
+    `Found ${symbols.length} unenriched symbol(s) under "${pathPrefix}":`,
+    "",
+  ];
+
+  for (const sym of symbols) {
+    const loc = `${sym.file_path}:${sym.line_start}-${sym.line_end}`;
+    lines.push(`  ${sym.name} · ${sym.kind} · ${loc} · card: ${sym.card_path}`);
+  }
+
+  lines.push(
+    "",
+    "Instructions:",
+    `  For each symbol above, read the source span and call \`codewalker_enrich\``,
+    "  with a ≤120 character plain-English summary of what the symbol does.",
+    `  Example: \`codewalker_enrich { card: "${symbols[0]?.card_path ?? '<card_path>'}", summary: "..." }\``,
+  );
+
+  return lines.join("\n");
+}