@aprimediet/codewalker 1.1.0 → 1.3.0

package/src/notes.ts

@@ -0,0 +1,145 @@
+/**
+ * Note orchestration for codewalker v1.3.
+ *
+ * Provides:
+ * - `addNote()`: render card → atomic write → upsertNote
+ * - `rebuildNotesDbFromCards()`: disposable-index rebuild from card files
+ *
+ * Mirrors the style of src/libs/indexer.ts (atomic write, tmp + rename, mode 0o600).
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { openDb, upsertNote } from "./db.ts";
+import { renderNoteCard, parseNoteCard } from "./notes-cards.ts";
+import type { Note, NoteKind } from "./types.ts";
+
+/**
+ * Write a note: render card → atomic write → upsert DB row.
+ *
+ * The note's note_kind determines which directory to use.
+ * When `notesDir` is provided, it is used directly (backward compat).
+ * When both `glossaryDir` and `decisionsDir` are available, pass them via an options bag.
+ */
+export function addNote(
+  dbPath: string,
+  note: Note,
+  notesDir?: string,
+): void {
+  const dir = notesDir;
+  if (!dir) throw new Error("notesDir is required");
+
+  // Ensure directory exists
+  fs.mkdirSync(dir, { recursive: true });
+
+  // Generate slug from title
+  const slug = slugifyNoteTitle(note.title);
+  const cardPath = path.join(dir, `${slug}.md`);
+
+  // Render card
+  const card = renderNoteCard(note);
+
+  // Atomic write
+  const tmpPath = cardPath + ".tmp";
+  fs.writeFileSync(tmpPath, card, { encoding: "utf-8", mode: 0o600 });
+  fs.renameSync(tmpPath, cardPath);
+
+  // Upsert DB row with the actual card_path
+  const db = openDb(dbPath);
+  try {
+    upsertNote(db, {
+      ...note,
+      card_path: cardPath,
+    });
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Rebuild the notes DB tables from glossary + decisions cards alone.
+ * Demonstrates the disposable-index property: cards are the source of truth.
+ */
+export function rebuildNotesDbFromCards(
+  dbPath: string,
+  glossaryDir: string,
+  decisionsDir: string,
+): void {
+  const db = openDb(dbPath);
+
+  try {
+    db.exec("BEGIN TRANSACTION");
+
+    // Clear existing notes
+    db.prepare("DELETE FROM notes").run();
+
+    // Process glossary cards
+    if (fs.existsSync(glossaryDir)) {
+      processCardsInDir(db, glossaryDir, "glossary");
+    }
+
+    // Process decisions cards
+    if (fs.existsSync(decisionsDir)) {
+      processCardsInDir(db, decisionsDir, "decision");
+    }
+
+    db.exec("COMMIT");
+  } catch (e) {
+    db.exec("ROLLBACK");
+    throw e;
+  } finally {
+    db.close();
+  }
+}
+
+// ── Internal helpers ───────────────────────────────────────────
+
+function processCardsInDir(
+  db: ReturnType<typeof openDb>,
+  dir: string,
+  expectedKind: NoteKind,
+): void {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+
+    const cardPath = path.join(dir, entry.name);
+    const cardText = fs.readFileSync(cardPath, "utf-8");
+    const parsed = parseNoteCard(cardText);
+    if (!parsed) continue;
+    if (parsed.note_kind !== expectedKind) continue;
+
+    // Extract body from card
+    const body = extractNoteBody(cardText);
+
+    upsertNote(db, {
+      note_kind: parsed.note_kind,
+      title: parsed.title,
+      body,
+      tags: parsed.tags,
+      related: parsed.related,
+      card_path: cardPath,
+    });
+  }
+}
+
+/** Extract the body (after frontmatter) from a note card, stripping the # title header. */
+function extractNoteBody(cardText: string): string {
+  const trimmed = cardText.trim();
+  if (!trimmed.startsWith("---")) return "";
+
+  const endOfFm = trimmed.indexOf("\n---", 3);
+  if (endOfFm === -1) return "";
+
+  return trimmed.slice(endOfFm + 4).trim();
+}
+
+function slugifyNoteTitle(title: string): string {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60) || "untitled";
+}
+
+// Re-export for convenience
+export { slugifyNoteTitle };

package/src/project.test.ts

@@ -80,6 +80,14 @@ describe('project.ts', () => {
       expect(p.metaFile).toBe(path.join(p.codewalkerDir, 'meta.json'));
       expect(p.entriesDir).toBe(path.join(p.codewalkerDir, 'entries'));
       expect(p.symbolsDir).toBe(path.join(p.codewalkerDir, 'entries', 'symbols'));
+      expect(p.libsDir).toBe(path.join(p.codewalkerDir, 'entries', 'libs'));
+    });
+
+    it('exposes glossaryDir and decisionsDir paths', async () => {
+      const mod = await import('./project.ts');
+      const p = mod.resolveProject(tmpDir);
+      expect(p.glossaryDir).toBe(path.join(p.codewalkerDir, 'entries', 'glossary'));
+      expect(p.decisionsDir).toBe(path.join(p.codewalkerDir, 'entries', 'decisions'));
     });
   });
 
@@ -89,10 +97,13 @@ describe('project.ts', () => {
       const p = await mod.ensureProject(tmpDir);
       // marker file exists
       expect(fs.existsSync(p.markerPath)).toBe(true);
-      // codewalker dir is created
+      // codewalker dir + subdirs are created
       expect(fs.existsSync(p.codewalkerDir)).toBe(true);
       expect(fs.existsSync(p.entriesDir)).toBe(true);
       expect(fs.existsSync(p.symbolsDir)).toBe(true);
+      expect(fs.existsSync(p.libsDir)).toBe(true);
+      expect(fs.existsSync(p.glossaryDir)).toBe(true);
+      expect(fs.existsSync(p.decisionsDir)).toBe(true);
       // meta.json written
       expect(fs.existsSync(p.metaFile)).toBe(true);
       // meta.json has correct shape

package/src/project.ts

@@ -30,6 +30,9 @@ export interface ProjectPaths {
   metaFile: string;
   entriesDir: string;
   symbolsDir: string;
+  libsDir: string;
+  glossaryDir: string;
+  decisionsDir: string;
 }
 
 function piHome(): string {
@@ -123,6 +126,9 @@ function pathsForId(id: string, root: string, configDir: string, markerPath: str
     metaFile: path.join(globalDir, "codewalker", "meta.json"),
     entriesDir: path.join(globalDir, "codewalker", "entries"),
     symbolsDir: path.join(globalDir, "codewalker", "entries", "symbols"),
+    libsDir: path.join(globalDir, "codewalker", "entries", "libs"),
+    glossaryDir: path.join(globalDir, "codewalker", "entries", "glossary"),
+    decisionsDir: path.join(globalDir, "codewalker", "entries", "decisions"),
   };
 }
 
@@ -164,7 +170,7 @@ export async function ensureProject(cwd: string): Promise<ProjectPaths> {
   const p = resolveProject(cwd);
   const nowISO = new Date().toISOString();
 
-  for (const dir of [p.codewalkerDir, p.entriesDir, p.symbolsDir]) {
+  for (const dir of [p.codewalkerDir, p.entriesDir, p.symbolsDir, p.libsDir, p.glossaryDir, p.decisionsDir]) {
     fs.mkdirSync(dir, { recursive: true });
   }
 

package/src/query.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import { openDb, upsertSymbol, setMeta, getMeta, searchSymbols } from './db.ts';
+import { openDb, upsertSymbol, setMeta, getMeta, upsertLibSymbol, upsertNote, searchLibSymbols } from './db.ts';
 import { runQuery } from './query.ts';
 
 describe('query.ts', () => {
@@ -95,4 +95,151 @@ describe('query.ts', () => {
     // In a non-git dir, staleness should be null
     expect(result.staleness).toBeNull();
   });
+
+  // ── source filter ───────────────────────────────────────────
+  it('source="code" returns only code symbols (default)', () => {
+    const db = openDb(dbPath);
+    upsertSymbol(db, {
+      name: 'myFunc', kind: 'function', file_path: 'src/a.ts',
+      line_start: 1, line_end: 1, signature: '', doc: '', summary: '', card_path: '',
+    });
+    upsertLibSymbol(db, {
+      lib: 'hono', version: '4.6.3', name: 'honoFunc',
+      kind: 'function', signature: '', doc: '', summary: '', card_path: '',
+    });
+    db.close();
+
+    const result = runQuery(dbPath, { query: '', source: 'code' });
+    expect(result.rows).toHaveLength(1);
+    expect(result.rows[0]!.name).toBe('myFunc');
+    expect(result.rows[0]!.source).toBeUndefined();
+  });
+
+  it('source="libs" returns only lib symbols', () => {
+    const db = openDb(dbPath);
+    upsertSymbol(db, {
+      name: 'myFunc', kind: 'function', file_path: 'src/a.ts',
+      line_start: 1, line_end: 1, signature: '', doc: '', summary: '', card_path: '',
+    });
+    upsertLibSymbol(db, {
+      lib: 'hono', version: '4.6.3', name: 'honoFunc',
+      kind: 'function', signature: '', doc: '', summary: '', card_path: '',
+    });
+    db.close();
+
+    const result = runQuery(dbPath, { query: '', source: 'libs' });
+    expect(result.rows).toHaveLength(1);
+    expect(result.rows[0]!.name).toBe('honoFunc');
+    expect(result.rows[0]!.source).toBe('lib');
+    expect(result.rows[0]!.lib).toBe('hono');
+    expect(result.rows[0]!.version).toBe('4.6.3');
+  });
+
+  it('source="all" returns merged code and lib symbols', () => {
+    const db = openDb(dbPath);
+    upsertSymbol(db, {
+      name: 'myFunc', kind: 'function', file_path: 'src/a.ts',
+      line_start: 1, line_end: 1, signature: '', doc: '', summary: '', card_path: '',
+    });
+    upsertLibSymbol(db, {
+      lib: 'hono', version: '4.6.3', name: 'honoFunc',
+      kind: 'function', signature: '', doc: '', summary: '', card_path: '',
+    });
+    db.close();
+
+    const result = runQuery(dbPath, { query: '', source: 'all' });
+    expect(result.rows).toHaveLength(2);
+  });
+
+  it('source=all respects limit across merged set', () => {
+    const db = openDb(dbPath);
+    upsertSymbol(db, {
+      name: 'aCode', kind: 'function', file_path: 'src/a.ts',
+      line_start: 1, line_end: 1, signature: '', doc: '', summary: '', card_path: '',
+    });
+    upsertLibSymbol(db, {
+      lib: 'pkg', version: '1.0.0', name: 'bLib',
+      kind: 'function', signature: '', doc: '', summary: '', card_path: '',
+    });
+    db.close();
+
+    const result = runQuery(dbPath, { query: '', source: 'all', limit: 1 });
+    expect(result.rows).toHaveLength(1);
+  });
+
+  // ── notes source ───────────────────────────────────────────
+  it('source="notes" returns only notes', () => {
+    const db = openDb(dbPath);
+    upsertSymbol(db, {
+      name: 'myFunc', kind: 'function', file_path: 'src/a.ts',
+      line_start: 1, line_end: 1, signature: '', doc: '', summary: '', card_path: '',
+    });
+    upsertNote(db, {
+      note_kind: 'glossary', title: 'Glossary Term', body: 'A term', tags: '', related: '', card_path: '',
+    });
+    db.close();
+
+    const result = runQuery(dbPath, { query: '', source: 'notes' });
+    expect(result.rows).toHaveLength(1);
+    expect(result.rows[0]!.name).toBe('Glossary Term');
+    expect(result.rows[0]!.source).toBe('note');
+  });
+
+  it('source="all" includes notes interleaved with code and libs', () => {
+    const db = openDb(dbPath);
+    upsertSymbol(db, {
+      name: 'myFunc', kind: 'function', file_path: 'src/a.ts',
+      line_start: 1, line_end: 1, signature: '', doc: 'refresh token', summary: '', card_path: '',
+    });
+    upsertLibSymbol(db, {
+      lib: 'hono', version: '4.6.3', name: 'honoFunc',
+      kind: 'function', signature: '', doc: 'refresh token', summary: '', card_path: '',
+    });
+    upsertNote(db, {
+      note_kind: 'glossary', title: 'Refresh Token', body: 'A token used to refresh auth without re-login.', tags: 'auth', related: 'myFunc', card_path: '',
+    });
+    db.close();
+
+    const result = runQuery(dbPath, { query: 'refresh', source: 'all' });
+    expect(result.rows.length).toBeGreaterThanOrEqual(2);
+    // Should have note + lib + code (code rows have source undefined)
+    const sources = result.rows.map(r => r.source);
+    expect(sources).toContain('note');
+    expect(sources).toContain('lib');
+    expect(sources).toContain(undefined); // code rows have no source
+  });
+
+  it('source kind filter works for notes source', () => {
+    const db = openDb(dbPath);
+    upsertNote(db, {
+      note_kind: 'glossary', title: 'Term', body: 'A glossary term', tags: '', related: '', card_path: '',
+    });
+    upsertNote(db, {
+      note_kind: 'decision', title: 'Decision', body: 'A decision note', tags: '', related: '', card_path: '',
+    });
+    db.close();
+
+    const result = runQuery(dbPath, { query: '', source: 'notes', kind: 'glossary' });
+    expect(result.rows).toHaveLength(1);
+    expect(result.rows[0]!.name).toBe('Term');
+  });
+
+  it('source=all with note in query works (note matches alongside code)', () => {
+    const db = openDb(dbPath);
+    upsertSymbol(db, {
+      name: 'myFunc', kind: 'function', file_path: 'src/payments.ts',
+      line_start: 1, line_end: 10, signature: '', doc: 'processes charges', summary: '', card_path: '',
+    });
+    upsertNote(db, {
+      note_kind: 'glossary', title: 'charge', body: 'A payment processing concept.',
+      tags: 'payments', related: 'myFunc', card_path: '',
+    });
+    db.close();
+
+    const result = runQuery(dbPath, { query: 'charge', source: 'all' });
+    expect(result.rows.length).toBeGreaterThanOrEqual(1);
+    const sources = result.rows.map(r => r.source);
+    expect(sources).toContain('note');
+  });
+
 });

package/src/query.ts

@@ -2,14 +2,16 @@
  * Query orchestration: wraps DB search with staleness detection.
  */
 
-import type { QueryResult, QueryResultRow, StalenessInfo } from "./types.ts";
-import { openDb, searchSymbols, getMeta } from "./db.ts";
+import type { QueryResult, QueryResultRow, StalenessInfo, NoteKind } from "./types.ts";
+import { openDb, searchSymbols, searchLibSymbols, searchNotes, getMeta } from "./db.ts";
 import { getHeadSha, changedFilesSince } from "./git.ts";
 
 export interface QueryParams {
   query: string;
   kind?: string;
   limit?: number;
+  /** Source scope: "code" (default, only code symbols), "libs" (only lib symbols), "notes" (only notes), or "all" (all three). */
+  source?: "code" | "libs" | "notes" | "all";
 }
 
 /**
@@ -27,12 +29,30 @@ export function runQuery(
   const db = openDb(dbPath);
 
   try {
-    const rows = searchSymbols(
-      db,
-      params.query,
-      params.kind,
-      params.limit ?? 10,
-    );
+    const source = params.source ?? "code";
+    const limit = params.limit ?? 10;
+
+    let rows: QueryResultRow[];
+
+    if (source === "libs") {
+      rows = searchLibSymbols(db, params.query, params.kind, limit) as unknown as QueryResultRow[];
+    } else if (source === "notes") {
+      const noteRows = searchNotes(db, params.query, params.kind as NoteKind | undefined, limit);
+      rows = noteRows as unknown as QueryResultRow[];
+    } else if (source === "all") {
+      // Run code + lib + note searches, merge, sort by score, apply limit
+      const codeRows = searchSymbols(db, params.query, params.kind, limit);
+      const libRows = searchLibSymbols(db, params.query, params.kind, limit) as unknown as QueryResultRow[];
+      const noteRows = searchNotes(db, params.query, params.kind as NoteKind | undefined, limit * 2) as unknown as QueryResultRow[];
+
+      // Merge and sort by score ascending (lower bm25 = better match)
+      const merged: QueryResultRow[] = [...codeRows, ...libRows, ...noteRows];
+      merged.sort((a, b) => a.score - b.score);
+      rows = merged.slice(0, limit);
+    } else {
+      // "code" — default, existing behavior
+      rows = searchSymbols(db, params.query, params.kind, limit);
+    }
 
     const staleness = detectStaleness(db, repoDir);
 

package/src/types.ts

@@ -4,6 +4,18 @@
  * These types are shared across all layers (extraction, cards, DB, query).
  */
 
+/** Library symbol kind — extends SymbolKind with reexport + namespace. */
+export type LibSymbolKind =
+  | "function"
+  | "const"
+  | "class"
+  | "interface"
+  | "type"
+  | "enum"
+  | "namespace"
+  | "reexport"
+  | "module";
+
 /** The kind of a code symbol. */
 export type SymbolKind =
   | "function"
@@ -17,6 +29,18 @@ export type SymbolKind =
   | "namespace"
   | "module";
 
+/** A single symbol extracted from a library's .d.ts file. */
+export interface LibSymbol {
+  lib: string;
+  version: string;
+  name: string;
+  kind: LibSymbolKind;
+  signature: string;
+  doc: string;
+  summary: string;
+  card_path: string;
+}
+
 /** A single symbol extracted from source code. */
 export interface Symbol {
   name: string;
@@ -40,6 +64,19 @@ export interface CardHead {
   summary: string;
 }
 
+/** Note kind discriminator for bridge cards. */
+export type NoteKind = "glossary" | "decision";
+
+/** A glossary/decision note (bridge card) for conceptual knowledge. */
+export interface Note {
+  note_kind: NoteKind;
+  title: string;
+  body: string;
+  tags: string;
+  related: string;
+  card_path: string;
+}
+
 /** A single row returned from a query. */
 export interface QueryResultRow {
   name: string;
@@ -51,6 +88,13 @@ export interface QueryResultRow {
   summary: string;
   score: number;
   id: number;
+  /** Origin fields — code rows omit these; lib / note rows set them. */
+  source?: "code" | "lib" | "note";
+  lib?: string;
+  version?: string;
+  /** Note-specific fields — only for source === "note" rows. */
+  note_kind?: NoteKind;
+  tags?: string;
 }
 
 /** The full result of a query, including staleness info. */