@aprimediet/codewalker 1.3.0 → 1.4.0

package/src/db.ts

@@ -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 = 3;
+    PRAGMA user_version = 4;
 
     CREATE TABLE IF NOT EXISTS files (
       path        TEXT PRIMARY KEY,
@@ -155,6 +155,45 @@ export function bootstrapDb(db: DatabaseType): void {
       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;
   `);
 }
 
@@ -171,6 +210,7 @@ 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. */
@@ -378,6 +418,156 @@ export function searchNotes(
   }));
 }
 
+// ── 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 ──────────────────────────────────────────
 
 /**

package/src/format.test.ts

@@ -166,6 +166,103 @@ describe('formatCompact with note rows', () => {
   });
 });
 
+describe('formatCompact with analysis rows', () => {
+  it('renders a coverage finding row with [coverage] prefix and severity', () => {
+    const rows: QueryResultRow[] = [{
+      id: 1, name: 'Low coverage: src/auth/token.ts', kind: 'coverage',
+      file_path: 'src/auth/token.ts', line_start: 0, line_end: 0,
+      signature: '', summary: 'Token path is under-tested.',
+      score: 0.5, source: 'analysis', finding_kind: 'coverage',
+      severity: 'warn', metric: '38% (24/63 lines)',
+    }];
+    const result = formatCompact(rows, null);
+    expect(result).toContain('Low coverage: src/auth/token.ts');
+    expect(result).toContain('[coverage]');
+    expect(result).toContain('warn');
+    expect(result).toContain('38%');
+    expect(result).toContain('token.ts');
+  });
+
+  it('renders a debt finding row with [debt] prefix', () => {
+    const rows: QueryResultRow[] = [{
+      id: 1, name: 'TODO: fix this', kind: 'debt',
+      file_path: 'src/a.ts', line_start: 5, line_end: 5,
+      signature: '', summary: 'Need to handle edge case',
+      score: 0.5, source: 'analysis', finding_kind: 'debt',
+      severity: 'info', metric: 'TODO',
+    }];
+    const result = formatCompact(rows, null);
+    expect(result).toContain('[debt]');
+    expect(result).toContain('TODO: fix this');
+    expect(result).toContain('info');
+  });
+
+  it('renders a practice finding row with [practice] prefix', () => {
+    const rows: QueryResultRow[] = [{
+      id: 1, name: 'Missing error handling', kind: 'practice',
+      file_path: 'src/api/route.ts', line_start: 15, line_end: 15,
+      signature: '', summary: 'No error handling in this function.',
+      score: 0.5, source: 'analysis', finding_kind: 'practice',
+      severity: 'high', metric: '',
+    }];
+    const result = formatCompact(rows, null);
+    expect(result).toContain('[practice]');
+    expect(result).toContain('high');
+  });
+
+  it('renders mixed code + analysis rows', () => {
+    const codeRow: QueryResultRow = {
+      id: 1, name: 'myFunc', kind: 'function',
+      file_path: 'src/util/helper.ts', line_start: 10, line_end: 20,
+      signature: '', summary: 'Does something', score: 0.5,
+    };
+    const analysisRow: QueryResultRow = {
+      id: 2, name: 'Low coverage', kind: 'coverage',
+      file_path: 'src/util/helper.ts', line_start: 0, line_end: 0,
+      signature: '', summary: 'Low coverage.',
+      score: 0.3, source: 'analysis', finding_kind: 'coverage',
+      severity: 'warn', metric: '30%',
+    };
+    const result = formatCompact([codeRow, analysisRow], null);
+    expect(result).toContain('helper.ts:10-20');
+    expect(result).toContain('[coverage]');
+    expect(result.split('\n')).toHaveLength(2);
+  });
+
+  it('renders mixed code + lib + note + analysis rows', () => {
+    const codeRow: QueryResultRow = {
+      id: 1, name: 'myFunc', kind: 'function',
+      file_path: 'src/util/helper.ts', line_start: 10, line_end: 20,
+      signature: '', summary: 'Does something', score: 0.5,
+    };
+    const libRow: QueryResultRow = {
+      id: 100, name: 'createMiddleware', kind: 'function',
+      file_path: 'hono/dist/helper.d.ts', line_start: 0, line_end: 0,
+      signature: '', summary: 'Define a typed middleware handler.',
+      score: 0.3, source: 'lib', lib: 'hono', version: '4.6.3',
+    };
+    const noteRow: QueryResultRow = {
+      id: 1, name: 'Retry Key', kind: 'glossary',
+      file_path: '', line_start: 0, line_end: 0,
+      signature: '', summary: 'Key for idempotent retries.',
+      score: 0.5, source: 'note', note_kind: 'glossary', tags: '',
+    };
+    const analysisRow: QueryResultRow = {
+      id: 2, name: 'Low coverage', kind: 'coverage',
+      file_path: 'src/util/helper.ts', line_start: 0, line_end: 0,
+      signature: '', summary: 'Low coverage.',
+      score: 0.3, source: 'analysis', finding_kind: 'coverage',
+      severity: 'warn', metric: '30%',
+    };
+
+    const result = formatCompact([codeRow, libRow, noteRow, analysisRow], null);
+    expect(result).toContain('[coverage]');
+    expect(result).toContain('[hono@4.6.3]');
+    expect(result).toContain('[glossary]');
+    expect(result.split('\n')).toHaveLength(4);
+  });
+});
+
 describe('formatCardBody', () => {
   it('returns the card body text', () => {
     const body = '# myFunc\n\nDoes something.\n';

package/src/format.ts

@@ -32,6 +32,14 @@ export function formatCompact(
       const summary = truncate(row.summary || "", SUMMARY_MAX);
       return `${row.name} · ${row.note_kind} · ${prefix} · ${summary}`;
     }
+    if (row.source === "analysis") {
+      const kindTag = `[${row.finding_kind || "finding"}]`;
+      const sev = row.severity ? ` · ${row.severity}` : "";
+      const metric = row.metric ? ` · ${row.metric}` : "";
+      const loc = row.file_path ? ` · ${basename(row.file_path)}` : "";
+      const summary = truncate(row.summary || row.name || "", SUMMARY_MAX);
+      return `${row.name}${loc}${sev}${metric} · ${kindTag} · ${summary}`;
+    }
     if (row.source === "lib" && row.lib && row.version) {
       const origin = `[${row.lib}@${row.version}]`;
       const summary = truncate(row.summary || "", SUMMARY_MAX);

package/src/index.contract.test.ts

@@ -78,6 +78,15 @@ describe('index.ts contract', () => {
     expect(noteParams.properties).toHaveProperty('title');
     expect(noteParams.properties).toHaveProperty('body');
 
+    // Check v1.4 tools
+    const findingTool = stub.tools.find(t => t.name === 'codewalker_finding');
+    expect(findingTool).toBeDefined();
+    expect(findingTool!.description).toContain('finding');
+    const findingParams = (findingTool!.parameters as any);
+    expect(findingParams.properties).toHaveProperty('kind');
+    expect(findingParams.properties).toHaveProperty('title');
+    expect(findingParams.properties).toHaveProperty('body');
+
     // Check tool has a source parameter
     const toolParams = (queryTool!.parameters as any);
     expect(toolParams.properties).toHaveProperty('source');
@@ -173,4 +182,26 @@ describe('index.ts contract', () => {
     expect(cmd.description).toContain('glossary');
     expect(cmd.description).toContain('decisions');
   });
+
+  it('command description includes v1.4 subcommands (analyze, review, findings, conventions)', async () => {
+    const mod = await import('./index.ts');
+    const stub = createPiStub();
+    mod.default(stub.api as any);
+
+    const cmd = stub.commands.find(c => c.name === 'codewalker')!;
+    expect(cmd.description).toContain('analyze');
+    expect(cmd.description).toContain('review');
+    expect(cmd.description).toContain('findings');
+    expect(cmd.description).toContain('conventions');
+  });
+
+  it('codewalker_note tool accepts type="convention"', async () => {
+    const mod = await import('./index.ts');
+    const stub = createPiStub();
+    mod.default(stub.api as any);
+
+    const noteTool = stub.tools.find(t => t.name === 'codewalker_note')!;
+    const noteParams = (noteTool!.parameters as any);
+    expect(noteParams.properties.type.description).toContain('convention');
+  });
 });