codetrap 0.1.0

package/src/db/embedding-queries.ts

@@ -0,0 +1,154 @@
+import type { Database, SQLQueryBindings } from "bun:sqlite";
+import type { Trap } from "../domain/trap";
+import { DEFAULT_TRAP_STATUS, type TrapStatus } from "../lib/constants";
+import {
+  decodeEmbedding,
+  encodeEmbedding,
+  type EmbeddingConfig,
+  type FreshEmbedding,
+  type StoredEmbedding,
+} from "../lib/embedder";
+import { embeddingIsFresh, passageHashForTrap } from "../lib/trap-search-document";
+import { countTraps, listTraps } from "./queries";
+
+type TrapEmbeddingRow = {
+  trap_id: number;
+  provider: string;
+  model: string;
+  dimensions: number;
+  passage_version: number;
+  passage_hash: string;
+  embedding: Uint8Array;
+  updated_at: string;
+};
+
+export function getEmbedding(db: Database, trapId: number): StoredEmbedding | null {
+  const row = db
+    .query("SELECT * FROM trap_embeddings WHERE trap_id = ?")
+    .get(trapId) as TrapEmbeddingRow | null;
+  return row ? rowToStoredEmbedding(row) : null;
+}
+
+export function upsertEmbedding(db: Database, record: StoredEmbedding): void {
+  db.prepare(`
+    INSERT INTO trap_embeddings (
+      trap_id, provider, model, dimensions, passage_version, passage_hash, embedding, updated_at
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now'))
+    ON CONFLICT(trap_id) DO UPDATE SET
+      provider = excluded.provider,
+      model = excluded.model,
+      dimensions = excluded.dimensions,
+      passage_version = excluded.passage_version,
+      passage_hash = excluded.passage_hash,
+      embedding = excluded.embedding,
+      updated_at = datetime('now')
+  `).run(
+    record.trap_id,
+    record.provider,
+    record.model,
+    record.dimensions,
+    record.passage_version,
+    record.passage_hash,
+    encodeEmbedding(record.embedding)
+  );
+}
+
+export function deleteEmbedding(db: Database, trapId: number): void {
+  db.prepare("DELETE FROM trap_embeddings WHERE trap_id = ?").run(trapId);
+}
+
+export function getAllFreshEmbeddings(
+  db: Database,
+  config: EmbeddingConfig,
+  opts: { category?: string; scope?: string; status?: TrapStatus | "all" } = {}
+): FreshEmbedding[] {
+  const conditions = [
+    "e.provider = ?",
+    "e.model = ?",
+    "e.dimensions = ?",
+    "e.passage_version = ?",
+  ];
+  const params: SQLQueryBindings[] = [
+    config.provider,
+    config.model,
+    config.dimensions,
+    config.passageVersion,
+  ];
+
+  if (opts.category) {
+    conditions.push("t.category = ?");
+    params.push(opts.category);
+  }
+  if (opts.scope) {
+    conditions.push("t.scope = ?");
+    params.push(opts.scope);
+  }
+  if (opts.status !== "all") {
+    conditions.push("t.status = ?");
+    params.push(opts.status ?? DEFAULT_TRAP_STATUS);
+  }
+
+  const rows = db
+    .query(
+      `
+      SELECT
+        t.*,
+        e.embedding AS embedding,
+        e.passage_hash AS embedding_passage_hash
+      FROM trap_embeddings e
+      JOIN traps t ON t.id = e.trap_id
+      WHERE ${conditions.join(" AND ")}
+    `
+    )
+    .all(...params) as (Trap & { embedding: Uint8Array; embedding_passage_hash: string })[];
+
+  return rows.flatMap((row) => {
+    if (row.embedding_passage_hash !== passageHashForTrap(row)) return [];
+    const { embedding, embedding_passage_hash: _passageHash, ...trap } = row;
+    return [{ trap: trap as Trap, embedding: decodeEmbedding(embedding) }];
+  });
+}
+
+export function getTrapsNeedingEmbeddings(
+  db: Database,
+  config: EmbeddingConfig,
+  opts: { scope?: string; category?: string; status?: TrapStatus | "all"; force?: boolean; limit?: number } = {}
+): Trap[] {
+  const traps = listTraps(db, {
+    scope: opts.scope,
+    category: opts.category,
+    status: opts.status,
+    limit: 100000,
+  });
+  const needed: Trap[] = [];
+
+  for (const trap of traps) {
+    const embedding = getEmbedding(db, trap.id);
+    if (opts.force || !embeddingIsFresh(trap, embedding, config)) {
+      needed.push(trap);
+    }
+  }
+
+  return needed.slice(0, opts.limit ?? needed.length);
+}
+
+export function countEmbeddableTraps(
+  db: Database,
+  opts: { scope?: string; category?: string; status?: TrapStatus | "all" } = {}
+): number {
+  return countTraps(db, opts);
+}
+
+function rowToStoredEmbedding(row: TrapEmbeddingRow): StoredEmbedding {
+  return {
+    trap_id: row.trap_id,
+    provider: row.provider,
+    model: row.model,
+    dimensions: row.dimensions,
+    passage_version: row.passage_version,
+    passage_hash: row.passage_hash,
+    embedding: decodeEmbedding(row.embedding),
+    updated_at: row.updated_at,
+  };
+}

package/src/db/queries.ts

@@ -0,0 +1,296 @@
+import type { Database, SQLQueryBindings } from "bun:sqlite";
+import { DEFAULT_SEVERITY, DEFAULT_TRAP_STATUS, type TrapStatus } from "../lib/constants";
+import {
+  TRAP_UPDATE_FIELDS,
+  type Trap,
+  type TrapEvidence,
+  type TrapExportRecord,
+  type TrapEvidenceInput,
+  type TrapInput,
+  type TrapSearchResult,
+  type TrapUpdate,
+} from "../domain/trap";
+import { prepareFTSQuery } from "../lib/fts-query";
+import { normalizeQuery } from "../lib/search-normalizer";
+import { normalizeEvidenceForExport } from "../lib/trap-archive";
+import { encodeEvidenceRelatedFiles, encodeTrapTags } from "../lib/trap-json-fields";
+import { buildTrapSearchText, passageFieldsChanged, searchTextFieldsChanged } from "../lib/trap-search-document";
+
+export type TrapStatusFilter = TrapStatus | "all";
+
+export function insertTrap(db: Database, input: TrapInput): number {
+  const tags = encodeTrapTags(input.tags);
+  const searchText = buildTrapSearchText({ ...input, tags });
+  const stmt = db.prepare(`
+    INSERT INTO traps (
+      title, category, tags, scope, context, mistake, fix, search_text,
+      before_code, after_code, severity, state_key, status, supersedes_id,
+      valid_from, valid_until, project_path
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'), ?, ?)
+  `);
+  const result = stmt.run(
+    input.title,
+    input.category,
+    tags,
+    input.scope,
+    input.context,
+    input.mistake,
+    input.fix,
+    searchText,
+    input.before_code ?? null,
+    input.after_code ?? null,
+    input.severity ?? DEFAULT_SEVERITY,
+    null,
+    DEFAULT_TRAP_STATUS,
+    null,
+    null,
+    input.project_path ?? null
+  );
+  return Number(result.lastInsertRowid);
+}
+
+export function searchTraps(
+  db: Database,
+  query: string,
+  opts: { category?: string; scope?: string; limit?: number; status?: TrapStatusFilter } = {}
+): TrapSearchResult[] {
+  const prepared = prepareFTSQuery(normalizeQuery(query));
+  if (!prepared) return [];
+
+  const conditions = ["traps_fts MATCH ?"];
+  const params: SQLQueryBindings[] = [prepared];
+
+  addTrapFilters(conditions, params, opts, "t");
+
+  params.push(opts.limit ?? 20);
+
+  const rows = db
+    .query(
+      `
+    SELECT t.*, rank
+    FROM traps_fts f
+    JOIN traps t ON t.id = f.rowid
+    WHERE ${conditions.join(" AND ")}
+    ORDER BY rank
+    LIMIT ?
+  `
+    )
+    .all(...params) as (Trap & { rank: number })[];
+  return rows.map((r) => ({ trap: r, rank: r.rank }));
+}
+
+export function getTrap(db: Database, id: number): Trap | null {
+  return db.query("SELECT * FROM traps WHERE id = ?").get(id) as Trap | null;
+}
+
+export function listTraps(
+  db: Database,
+  opts: { category?: string; scope?: string; limit?: number; offset?: number; status?: TrapStatusFilter } = {}
+): Trap[] {
+  const conditions: string[] = [];
+  const params: SQLQueryBindings[] = [];
+
+  addTrapFilters(conditions, params, opts);
+
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const limit = opts.limit ?? 50;
+  const offset = opts.offset ?? 0;
+
+  return db
+    .query(`SELECT * FROM traps ${where} ORDER BY updated_at DESC LIMIT ? OFFSET ?`)
+    .all(...params, limit, offset) as Trap[];
+}
+
+export function updateTrap(db: Database, id: number, input: TrapUpdate): boolean {
+  const updates: string[] = [];
+  const params: SQLQueryBindings[] = [];
+  const current = searchTextFieldsChanged(input) || passageFieldsChanged(input) ? getTrap(db, id) : null;
+
+  for (const key of TRAP_UPDATE_FIELDS) {
+    if (key === "tags") continue;
+    const value = input[key];
+    if (value !== undefined) {
+      updates.push(`${key} = ?`);
+      params.push(value ?? null);
+    }
+  }
+  if (input.tags !== undefined) {
+    updates.push("tags = ?");
+    params.push(encodeTrapTags(input.tags));
+  }
+
+  if (current && searchTextFieldsChanged(input)) {
+    const merged = {
+      ...current,
+      ...input,
+      tags: input.tags !== undefined ? encodeTrapTags(input.tags) : current.tags,
+    };
+    updates.push("search_text = ?");
+    params.push(buildTrapSearchText(merged));
+  }
+
+  if (updates.length === 0) return false;
+
+  updates.push("updated_at = datetime('now')");
+  params.push(id);
+
+  const result = db.prepare(`UPDATE traps SET ${updates.join(", ")} WHERE id = ?`).run(...params);
+  return result.changes > 0;
+}
+
+export function deleteTrap(db: Database, id: number): boolean {
+  const result = db.prepare("DELETE FROM traps WHERE id = ?").run(id);
+  return result.changes > 0;
+}
+
+export function addTrapEvidence(db: Database, trapId: number, input: TrapEvidenceInput): number {
+  const result = db
+    .prepare(
+      `
+      INSERT INTO trap_evidence (
+        trap_id, source_type, source_ref, observed_at, related_files, note
+      )
+      VALUES (?, ?, ?, COALESCE(?, datetime('now')), ?, ?)
+    `
+    )
+    .run(
+      trapId,
+      input.source_type,
+      input.source_ref ?? null,
+      input.observed_at ?? null,
+      encodeEvidenceRelatedFiles(input.related_files),
+      input.note ?? null
+    );
+  return Number(result.lastInsertRowid);
+}
+
+export function listTrapEvidence(db: Database, trapId: number): TrapEvidence[] {
+  return db
+    .query("SELECT * FROM trap_evidence WHERE trap_id = ? ORDER BY observed_at DESC, id DESC")
+    .all(trapId) as TrapEvidence[];
+}
+
+export function archiveTrap(db: Database, id: number): boolean {
+  const result = db
+    .prepare(
+      `
+      UPDATE traps
+      SET status = 'archived',
+          valid_until = COALESCE(valid_until, datetime('now')),
+          updated_at = datetime('now')
+      WHERE id = ?
+    `
+    )
+    .run(id);
+  return result.changes > 0;
+}
+
+export function supersedeTrap(
+  db: Database,
+  id: number,
+  supersededById: number,
+  stateKey?: string
+): boolean {
+  if (id === supersededById) return false;
+
+  const oldTrap = getTrap(db, id);
+  const newTrap = getTrap(db, supersededById);
+  if (!oldTrap || !newTrap) return false;
+
+  const key = stateKey ?? oldTrap.state_key ?? newTrap.state_key ?? `trap:${id}`;
+  const tx = db.transaction(() => {
+    db.prepare(
+      `
+      UPDATE traps
+      SET status = 'superseded',
+          state_key = ?,
+          valid_until = COALESCE(valid_until, datetime('now')),
+          updated_at = datetime('now')
+      WHERE id = ?
+    `
+    ).run(key, id);
+    db.prepare(
+      `
+      UPDATE traps
+      SET status = 'active',
+          state_key = ?,
+          supersedes_id = ?,
+          valid_from = COALESCE(valid_from, datetime('now')),
+          valid_until = NULL,
+          updated_at = datetime('now')
+      WHERE id = ?
+    `
+    ).run(key, id, supersededById);
+  });
+  tx();
+  return true;
+}
+
+export function incrementHitCount(db: Database, id: number): void {
+  db.prepare("UPDATE traps SET hit_count = hit_count + 1, updated_at = datetime('now') WHERE id = ?").run(id);
+}
+
+export function getTopTraps(db: Database, scope: string, limit = 20): Trap[] {
+  return db
+    .query("SELECT * FROM traps WHERE scope = ? AND status = 'active' ORDER BY hit_count DESC LIMIT ?")
+    .all(scope, limit) as Trap[];
+}
+
+export function getStats(db: Database): {
+  total: number;
+  byCategory: Record<string, number>;
+  bySeverity: Record<string, number>;
+} {
+  const total = (db.query("SELECT COUNT(*) as c FROM traps").get() as { c: number }).c;
+  const byCategory = db
+    .query("SELECT category, COUNT(*) as c FROM traps GROUP BY category")
+    .all() as { category: string; c: number }[];
+  const bySeverity = db
+    .query("SELECT severity, COUNT(*) as c FROM traps GROUP BY severity")
+    .all() as { severity: string; c: number }[];
+
+  return {
+    total,
+    byCategory: Object.fromEntries(byCategory.map((r) => [r.category, r.c])),
+    bySeverity: Object.fromEntries(bySeverity.map((r) => [r.severity, r.c])),
+  };
+}
+
+export function exportTraps(db: Database): TrapExportRecord[] {
+  const traps = db.query("SELECT * FROM traps").all() as Trap[];
+  return traps.map((trap) => ({
+    ...trap,
+    evidence: listTrapEvidence(db, trap.id).map(normalizeEvidenceForExport),
+  }));
+}
+
+export function countTraps(db: Database, opts: { scope?: string; category?: string; status?: TrapStatusFilter } = {}): number {
+  const conditions: string[] = [];
+  const params: SQLQueryBindings[] = [];
+  addTrapFilters(conditions, params, opts);
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const row = db.query(`SELECT COUNT(*) as c FROM traps ${where}`).get(...params) as { c: number };
+  return row.c;
+}
+
+function addTrapFilters(
+  conditions: string[],
+  params: SQLQueryBindings[],
+  opts: { category?: string; scope?: string; status?: TrapStatusFilter },
+  alias?: string
+): void {
+  const prefix = alias ? `${alias}.` : "";
+  if (opts.category) {
+    conditions.push(`${prefix}category = ?`);
+    params.push(opts.category);
+  }
+  if (opts.scope) {
+    conditions.push(`${prefix}scope = ?`);
+    params.push(opts.scope);
+  }
+  if (opts.status !== "all") {
+    conditions.push(`${prefix}status = ?`);
+    params.push(opts.status ?? DEFAULT_TRAP_STATUS);
+  }
+}

package/src/db/repository.ts

@@ -0,0 +1,141 @@
+import type { Database } from "bun:sqlite";
+import type {
+  Trap,
+  TrapDetails,
+  TrapEvidenceInput,
+  TrapExportRecord,
+  TrapInput,
+  TrapSearchResult,
+  TrapUpdate,
+} from "../domain/trap";
+import * as embeddingQueries from "./embedding-queries";
+import { SearchService, type SearchOptions } from "../lib/search-service";
+import {
+  type EmbeddingConfig,
+  type EmbeddingProvider,
+  type StoredEmbedding,
+} from "../lib/embedder";
+import { runEmbeddingJob } from "../lib/embedding-job";
+import { passageFieldsChanged } from "../lib/trap-search-document";
+import * as queries from "./queries";
+import type { TrapStatus } from "../lib/constants";
+
+export type TrapStats = ReturnType<typeof queries.getStats>;
+
+export class TrapRepository {
+  private readonly searchService: SearchService;
+
+  constructor(
+    private readonly db: Database,
+    private readonly embedder?: EmbeddingProvider
+  ) {
+    this.searchService = new SearchService(db, embedder);
+  }
+
+  add(input: TrapInput): number {
+    return queries.insertTrap(this.db, input);
+  }
+
+  search(query: string, opts: SearchOptions = {}): Promise<TrapSearchResult[]> {
+    return this.searchService.search(query, opts);
+  }
+
+  get(id: number): Trap | null {
+    return queries.getTrap(this.db, id);
+  }
+
+  getDetails(id: number, scope: "project" | "global"): TrapDetails | null {
+    const trap = queries.getTrap(this.db, id);
+    if (!trap) return null;
+    return {
+      trap,
+      evidence: queries.listTrapEvidence(this.db, id),
+      scope,
+    };
+  }
+
+  list(opts: { category?: string; scope?: string; limit?: number; offset?: number; status?: TrapStatus | "all" } = {}): Trap[] {
+    return queries.listTraps(this.db, opts);
+  }
+
+  update(id: number, input: TrapUpdate): boolean {
+    const success = queries.updateTrap(this.db, id, input);
+    if (success && passageFieldsChanged(input)) {
+      embeddingQueries.deleteEmbedding(this.db, id);
+    }
+    return success;
+  }
+
+  delete(id: number): boolean {
+    return queries.deleteTrap(this.db, id);
+  }
+
+  addEvidence(trapId: number, input: TrapEvidenceInput): number | null {
+    if (!queries.getTrap(this.db, trapId)) return null;
+    return queries.addTrapEvidence(this.db, trapId, input);
+  }
+
+  archive(id: number): boolean {
+    return queries.archiveTrap(this.db, id);
+  }
+
+  supersede(id: number, supersededById: number, stateKey?: string): boolean {
+    return queries.supersedeTrap(this.db, id, supersededById, stateKey);
+  }
+
+  hit(id: number): void {
+    queries.incrementHitCount(this.db, id);
+  }
+
+  top(scope: string, limit = 20): Trap[] {
+    return queries.getTopTraps(this.db, scope, limit);
+  }
+
+  stats(): TrapStats {
+    return queries.getStats(this.db);
+  }
+
+  exportAll(): TrapExportRecord[] {
+    return queries.exportTraps(this.db);
+  }
+
+  getEmbedding(trapId: number): StoredEmbedding | null {
+    return embeddingQueries.getEmbedding(this.db, trapId);
+  }
+
+  upsertEmbedding(record: StoredEmbedding): void {
+    embeddingQueries.upsertEmbedding(this.db, record);
+  }
+
+  deleteEmbedding(trapId: number): void {
+    embeddingQueries.deleteEmbedding(this.db, trapId);
+  }
+
+  getTrapsNeedingEmbeddings(
+    config: EmbeddingConfig,
+    opts: { scope?: string; category?: string; status?: TrapStatus | "all"; force?: boolean; limit?: number } = {}
+  ): Trap[] {
+    return embeddingQueries.getTrapsNeedingEmbeddings(this.db, config, opts);
+  }
+
+  async ensureEmbeddings(opts: { scope?: string; category?: string; limit?: number; force?: boolean; batchSize?: number } = {}): Promise<{
+    generated: number;
+    skipped: number;
+    batches: number;
+  }> {
+    if (!this.embedder) {
+      throw new Error("Embedding provider is unavailable. Set JINA_API_KEY to generate embeddings.");
+    }
+
+    return runEmbeddingJob(
+      {
+        countEmbeddable: (countOpts) => embeddingQueries.countEmbeddableTraps(this.db, countOpts),
+        trapsNeedingEmbeddings: (config, jobOpts) =>
+          embeddingQueries.getTrapsNeedingEmbeddings(this.db, config, jobOpts),
+        saveEmbedding: (record) => embeddingQueries.upsertEmbedding(this.db, record),
+      },
+      this.embedder,
+      opts
+    );
+  }
+}