codetrap 0.1.2 → 0.1.4

package/src/lib/command-requests.ts

@@ -0,0 +1,133 @@
+import { SEARCH_MODES, type SearchMode } from "./constants";
+import type { SearchDefaults } from "./config";
+import type { SearchTrapsArgs, ListTrapsArgs } from "./trap-operations";
+
+type RawArgs = Record<string, unknown>;
+
+export type EmbedRequest = {
+  scope?: string;
+  category?: string;
+  limit?: number;
+  force?: boolean;
+  batchSize?: number;
+};
+
+export type StatsRequest = {
+  scope?: string;
+};
+
+export function searchRequestFromArgs(query: string, args: RawArgs, defaults: SearchDefaults): SearchTrapsArgs {
+  return {
+    query,
+    category: stringOption(args, "category"),
+    scope: stringOption(args, "scope") ?? defaults.scope,
+    limit: intOption(args, "limit", defaults.limit),
+    mode: searchModeOption(args, "mode") ?? defaults.mode,
+    status: stringOption(args, "status"),
+    path: stringOption(args, "path"),
+    module: stringOption(args, "module"),
+    owner: stringOption(args, "owner"),
+    rerank: flagPresent(args, "no-rerank") ? false : booleanOption(args, "rerank") ?? defaults.rerank,
+    includeRankingSignals: booleanOption(args, "ranking_signals", "ranking-signals") ?? false,
+  };
+}
+
+export function listRequestFromArgs(args: RawArgs): ListTrapsArgs {
+  return {
+    category: stringOption(args, "category"),
+    scope: stringOption(args, "scope"),
+    status: stringOption(args, "status"),
+    path: stringOption(args, "path"),
+    module: stringOption(args, "module"),
+    owner: stringOption(args, "owner"),
+    limit: intOption(args, "limit", 50),
+  };
+}
+
+export function statsRequestFromArgs(args: RawArgs): StatsRequest {
+  return {
+    scope: stringOption(args, "scope"),
+  };
+}
+
+export function embedRequestFromArgs(args: RawArgs): EmbedRequest {
+  return {
+    scope: stringOption(args, "scope"),
+    category: stringOption(args, "category"),
+    limit: optionalIntOption(args, "limit"),
+    force: booleanOption(args, "force") === true,
+    batchSize: optionalIntOption(args, "batch_size", "batch-size"),
+  };
+}
+
+export function evidenceRequestFromArgs(args: RawArgs): RawArgs {
+  return {
+    source_type: stringOption(args, "source_type", "source-type"),
+    source_ref: stringOption(args, "source_ref", "source-ref"),
+    observed_at: stringOption(args, "observed_at", "observed-at"),
+    related_files: csvOrArrayOption(args, "related_files", "related-files"),
+    note: stringOption(args, "note"),
+  };
+}
+
+function stringOption(args: RawArgs, ...keys: string[]): string | undefined {
+  for (const key of keys) {
+    const value = args[key];
+    if (typeof value === "string" && value.trim() !== "") return value;
+  }
+  return undefined;
+}
+
+function intOption(args: RawArgs, key: string, fallback: number): number {
+  return optionalIntOption(args, key) ?? fallback;
+}
+
+function optionalIntOption(args: RawArgs, ...keys: string[]): number | undefined {
+  for (const key of keys) {
+    const value = args[key];
+    if (value === undefined) continue;
+    const parsed = typeof value === "number" ? value : Number.parseInt(String(value), 10);
+    if (Number.isInteger(parsed) && parsed > 0) return parsed;
+    throw new Error(`Invalid number: ${String(value)}`);
+  }
+  return undefined;
+}
+
+function searchModeOption(args: RawArgs, key: string): SearchMode | undefined {
+  const value = stringOption(args, key);
+  if (!value) return undefined;
+  if ((SEARCH_MODES as readonly string[]).includes(value)) return value as SearchMode;
+  throw new Error(`Invalid search mode: ${value}. Expected one of: ${SEARCH_MODES.join(", ")}`);
+}
+
+function booleanOption(args: RawArgs, ...keys: string[]): boolean | undefined {
+  for (const key of keys) {
+    const value = args[key];
+    if (value === undefined) continue;
+    if (typeof value === "boolean") return value;
+    if (typeof value === "string") {
+      if (["true", "1", "yes", "on"].includes(value.toLowerCase())) return true;
+      if (["false", "0", "no", "off"].includes(value.toLowerCase())) return false;
+    }
+    throw new Error(`Invalid boolean: ${String(value)}`);
+  }
+  return undefined;
+}
+
+function flagPresent(args: RawArgs, key: string): boolean {
+  return args[key] !== undefined;
+}
+
+function csvOrArrayOption(args: RawArgs, ...keys: string[]): string[] | undefined {
+  for (const key of keys) {
+    const value = args[key];
+    if (Array.isArray(value)) return value.map(String);
+    if (typeof value === "string" && value.trim() !== "") {
+      return value
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+    }
+  }
+  return undefined;
+}

package/src/lib/config.ts

@@ -0,0 +1,102 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CODETRAP_DIR, SCOPES, SEARCH_MODES, type Scope, type SearchMode } from "./constants";
+
+export type CodetrapConfig = {
+  search?: {
+    mode?: SearchMode;
+    limit?: number;
+    scope?: Scope;
+    rerank?: boolean;
+  };
+};
+
+export type SearchDefaults = {
+  mode: SearchMode;
+  limit: number;
+  scope?: Scope;
+  rerank: boolean;
+};
+
+const BUILT_IN_SEARCH_DEFAULTS: SearchDefaults = {
+  mode: "hybrid",
+  limit: 20,
+  rerank: true,
+};
+
+export function loadCodetrapConfig(home = homedir()): CodetrapConfig {
+  const path = join(home, CODETRAP_DIR, "config.json");
+  if (!existsSync(path)) return {};
+
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    return normalizeConfig(parsed);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid codetrap config at ${path}: ${message}`);
+  }
+}
+
+export function searchDefaultsFromConfig(config = loadCodetrapConfig(), env = process.env): SearchDefaults {
+  return {
+    mode: config.search?.mode ?? parseSearchModeEnv(env.CODETRAP_SEARCH_MODE) ?? BUILT_IN_SEARCH_DEFAULTS.mode,
+    limit: config.search?.limit ?? parsePositiveIntEnv(env.CODETRAP_SEARCH_LIMIT) ?? BUILT_IN_SEARCH_DEFAULTS.limit,
+    scope: config.search?.scope ?? parseScopeEnv(env.CODETRAP_SEARCH_SCOPE),
+    rerank: config.search?.rerank ?? parseBooleanEnv(env.CODETRAP_RERANK) ?? BUILT_IN_SEARCH_DEFAULTS.rerank,
+  };
+}
+
+function normalizeConfig(value: unknown): CodetrapConfig {
+  if (!isRecord(value)) return {};
+  const search = isRecord(value.search) ? normalizeSearchConfig(value.search) : undefined;
+  return search ? { search } : {};
+}
+
+function normalizeSearchConfig(value: Record<string, unknown>): CodetrapConfig["search"] {
+  const out: NonNullable<CodetrapConfig["search"]> = {};
+  if (typeof value.mode === "string") out.mode = parseSearchMode(value.mode);
+  if (typeof value.limit === "number") out.limit = parsePositiveInt(value.limit, "search.limit");
+  if (typeof value.scope === "string") out.scope = parseScope(value.scope);
+  if (typeof value.rerank === "boolean") out.rerank = value.rerank;
+  return out;
+}
+
+function parseSearchModeEnv(value?: string): SearchMode | undefined {
+  return value ? parseSearchMode(value) : undefined;
+}
+
+function parseScopeEnv(value?: string): Scope | undefined {
+  return value ? parseScope(value) : undefined;
+}
+
+function parsePositiveIntEnv(value?: string): number | undefined {
+  if (!value) return undefined;
+  return parsePositiveInt(Number.parseInt(value, 10), "CODETRAP_SEARCH_LIMIT");
+}
+
+function parseBooleanEnv(value?: string): boolean | undefined {
+  if (!value) return undefined;
+  if (["1", "true", "yes", "on"].includes(value.toLowerCase())) return true;
+  if (["0", "false", "no", "off"].includes(value.toLowerCase())) return false;
+  throw new Error(`Invalid CODETRAP_RERANK: ${value}. Expected true or false.`);
+}
+
+function parseSearchMode(value: string): SearchMode {
+  if ((SEARCH_MODES as readonly string[]).includes(value)) return value as SearchMode;
+  throw new Error(`Invalid search mode: ${value}. Expected one of: ${SEARCH_MODES.join(", ")}`);
+}
+
+function parseScope(value: string): Scope {
+  if ((SCOPES as readonly string[]).includes(value)) return value as Scope;
+  throw new Error(`Invalid scope: ${value}. Expected one of: ${SCOPES.join(", ")}`);
+}
+
+function parsePositiveInt(value: number, label: string): number {
+  if (Number.isInteger(value) && value > 0) return value;
+  throw new Error(`Invalid ${label}: expected a positive integer.`);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/lib/constants.ts

@@ -49,7 +49,7 @@ export const DEFAULT_TRAP_STATUS: TrapStatus = "active";
 
 // Increment this when schema changes in a breaking way.
 // Migrations are stored in src/db/migrations.ts
-export const SCHEMA_VERSION = 4;
+export const SCHEMA_VERSION = 5;
 
 // Directory and file names
 export const CODETRAP_DIR = ".codetrap";

package/src/lib/doctor.ts

@@ -0,0 +1,86 @@
+import type { TrapStore } from "./store";
+import type { TrapOperations } from "./trap-operations";
+import type { EmbeddingStatsResult, HybridFallbackReason } from "./embedding-health";
+import { createScopeContext } from "./scope-context";
+import { hybridFallbackReason } from "./embedding-health";
+
+export type DoctorReport = {
+  cwd: string;
+  project_root: string | null;
+  project_db: string | null;
+  global_db: string;
+  traps: {
+    project: number | null;
+    global: number;
+  };
+  embeddings: EmbeddingStatsResult;
+  hybrid_search: {
+    semantic_available: boolean;
+    fallback_reason: HybridFallbackReason | null;
+  };
+  diagnostics: {
+    mis_scoped_traps: {
+      global_db_project_traps: ReturnType<TrapStore["diagnostics"]>["mis_scoped_traps"]["global_db_project_traps"];
+    };
+  };
+  mcp_hint: string;
+};
+
+export function buildDoctorReport(
+  store: TrapStore,
+  operations: TrapOperations,
+  cwd = process.cwd()
+): DoctorReport {
+  const scope = createScopeContext(cwd);
+  const stats = operations.getStats();
+  const embeddings = operations.getEmbeddingStats();
+  const semanticAvailable = store.hasEmbeddingProvider();
+
+  return {
+    ...scope,
+    traps: {
+      project: stats.project?.total ?? null,
+      global: stats.global?.total ?? 0,
+    },
+    embeddings,
+    hybrid_search: {
+      semantic_available: semanticAvailable,
+      fallback_reason: hybridFallbackReason(semanticAvailable, embeddings),
+    },
+    diagnostics: {
+      mis_scoped_traps: store.diagnostics().mis_scoped_traps,
+    },
+    mcp_hint: "Pass cwd in MCP tool calls, or restart codetrap serve after changing projects.",
+  };
+}
+
+export function formatDoctorText(report: DoctorReport): string {
+  return [
+    `cwd: ${report.cwd}`,
+    `project_root: ${report.project_root ?? "(none)"}`,
+    `project_db: ${report.project_db ?? "(none)"}`,
+    `global_db: ${report.global_db}`,
+    `project_traps: ${report.traps.project ?? "(none)"}`,
+    `global_traps: ${report.traps.global}`,
+    "Embeddings:",
+    formatEmbeddingStats("project", report.embeddings.project),
+    formatEmbeddingStats("global", report.embeddings.global),
+    "Hybrid search:",
+    `  semantic_available: ${report.hybrid_search.semantic_available ? "yes" : "no"}`,
+    `  fallback_reason: ${report.hybrid_search.fallback_reason ?? "(none)"}`,
+    "Diagnostics:",
+    `  global_db_project_traps: ${report.diagnostics.mis_scoped_traps.global_db_project_traps.length}`,
+    `mcp_hint: ${report.mcp_hint}`,
+  ].join("\n");
+}
+
+function formatEmbeddingStats(
+  label: string,
+  stats: EmbeddingStatsResult["global"] | null
+): string {
+  if (!stats) return `  ${label}: unavailable`;
+  const provider = stats.provider_available
+    ? `${stats.provider}/${stats.model}`
+    : "unavailable";
+  return `  ${label}: fresh=${stats.fresh}, stale=${stats.stale}, missing=${stats.missing}, total=${stats.total}, provider=${provider}`;
+}

package/src/lib/embedding-health.ts

@@ -0,0 +1,49 @@
+import type { EmbeddingConfig } from "./embedder";
+
+export type EmbeddingStateCounts = {
+  total: number;
+  fresh: number;
+  stale: number;
+  missing: number;
+};
+
+export type EmbeddingStateSummary = EmbeddingStateCounts & {
+  provider_available: boolean;
+  provider: string | null;
+  model: string | null;
+  dimensions: number | null;
+  passage_version: number | null;
+};
+
+export type EmbeddingStatsResult = {
+  project: EmbeddingStateSummary | null;
+  global: EmbeddingStateSummary | null;
+};
+
+export type HybridFallbackReason = "semantic_unavailable" | "semantic_no_candidates";
+
+export function summarizeEmbeddingState(
+  counts: EmbeddingStateCounts,
+  config: EmbeddingConfig | null
+): EmbeddingStateSummary {
+  return {
+    ...counts,
+    provider_available: config !== null,
+    provider: config?.provider ?? null,
+    model: config?.model ?? null,
+    dimensions: config?.dimensions ?? null,
+    passage_version: config?.passageVersion ?? null,
+  };
+}
+
+export function hybridFallbackReason(
+  providerAvailable: boolean,
+  embeddings: EmbeddingStatsResult
+): HybridFallbackReason | null {
+  if (!providerAvailable) return "semantic_unavailable";
+
+  const fresh = (embeddings.project?.fresh ?? 0) + (embeddings.global?.fresh ?? 0);
+  const total = (embeddings.project?.total ?? 0) + (embeddings.global?.total ?? 0);
+  if (total > 0 && fresh === 0) return "semantic_no_candidates";
+  return null;
+}

package/src/lib/embedding-index.ts

@@ -0,0 +1,53 @@
+import type { Database } from "bun:sqlite";
+import * as embeddingQueries from "../db/embedding-queries";
+import type { Trap } from "../domain/trap";
+import type { TrapStatus } from "./constants";
+import type {
+  EmbeddingConfig,
+  FreshEmbedding,
+  StoredEmbedding,
+} from "./embedder";
+import type { EmbeddingStateCounts } from "./embedding-health";
+
+export type EmbeddingIndexFilter = {
+  scope?: string;
+  category?: string;
+  status?: TrapStatus | "all";
+};
+
+export type EmbeddingRefreshFilter = EmbeddingIndexFilter & {
+  force?: boolean;
+  limit?: number;
+};
+
+export class DatabaseEmbeddingIndex {
+  constructor(private readonly db: Database) {}
+
+  get(trapId: number): StoredEmbedding | null {
+    return embeddingQueries.getEmbedding(this.db, trapId);
+  }
+
+  save(record: StoredEmbedding): void {
+    embeddingQueries.upsertEmbedding(this.db, record);
+  }
+
+  delete(trapId: number): void {
+    embeddingQueries.deleteEmbedding(this.db, trapId);
+  }
+
+  freshEmbeddings(config: EmbeddingConfig, filter: EmbeddingIndexFilter = {}): FreshEmbedding[] {
+    return embeddingQueries.getAllFreshEmbeddings(this.db, config, filter);
+  }
+
+  trapsNeedingEmbeddings(config: EmbeddingConfig, filter: EmbeddingRefreshFilter = {}): Trap[] {
+    return embeddingQueries.getTrapsNeedingEmbeddings(this.db, config, filter);
+  }
+
+  countEmbeddable(filter: EmbeddingIndexFilter = {}): number {
+    return embeddingQueries.countEmbeddableTraps(this.db, filter);
+  }
+
+  stateCounts(config: EmbeddingConfig | null, filter: EmbeddingIndexFilter = {}): EmbeddingStateCounts {
+    return embeddingQueries.getEmbeddingStateCounts(this.db, config, filter);
+  }
+}

package/src/lib/format.ts

@@ -1,6 +1,6 @@
 import { CATEGORY_LABELS, SEVERITY_ICONS, type Category, type Severity } from "./constants";
 import type { Trap, TrapActionCard, TrapDetails, TrapEvidence } from "../domain/trap";
-import { parseEvidenceRelatedFiles, parseTrapTags } from "./trap-json-fields";
+import { parseEvidenceRelatedFiles, parseTrapPathGlobs, parseTrapTags } from "./trap-json-fields";
 export type { Trap } from "../domain/trap";
 
 export function formatTrapShort(t: Trap, scopeLabel: string): string {
@@ -18,13 +18,14 @@ Why relevant: ${card.why_relevant}
 Avoid: ${card.avoid}
 Do instead: ${card.do_instead}
 Score: ${formatScore(card.score)} (${sourceLabel})
-Next: get_trap id=${card.next_action.details_args.id} scope=${card.next_action.details_args.scope}`;
+Next: codetrap show ${card.trap_id} --scope ${card.scope} --json`;
 }
 
 export function formatTrapDetail(t: Trap, scopeLabel: string): string {
   const sev = SEVERITY_ICONS[t.severity as Severity] ?? t.severity;
   const cat = CATEGORY_LABELS[t.category as Category] ?? t.category;
   const tags = parseTrapTags(t.tags);
+  const pathGlobs = parseTrapPathGlobs(t.path_globs);
   let out = `\
 ══════════════════════════════════════════
 #${t.id}  ${t.title}
@@ -33,6 +34,9 @@ Scope:     ${scopeLabel} (${t.scope})
 Severity:  ${sev}
 Category:  ${cat}
 Tags:      ${tags.join(", ") || "-"}
+Paths:     ${pathGlobs.join(", ") || "-"}
+Module:    ${t.module ?? "-"}
+Owner:     ${t.owner ?? "-"}
 Hit count: ${t.hit_count}
 Created:   ${t.created_at}
 Updated:   ${t.updated_at}

package/src/lib/output-json.ts

@@ -0,0 +1,141 @@
+import type { RankingSignal, TrapActionCard, TrapDetails, TrapSearchDiagnostic } from "../domain/trap";
+import type { Scope } from "./constants";
+import type { DoctorReport } from "./doctor";
+import type { EmbeddingStatsResult } from "./embedding-health";
+import type { TrapListGroup, TrapStatsResult } from "./trap-operations";
+import {
+  toTrapEvidenceJson,
+  toTrapJson,
+  type JsonTrap,
+  type JsonTrapEvidence,
+} from "./trap-codec";
+
+export type JsonTrapDetails = {
+  scope: Scope;
+  trap: JsonTrap;
+  evidence: JsonTrapEvidence[];
+};
+
+export type CliTrapActionCard = TrapActionCard & {
+  next_action: {
+    command: string;
+  };
+  ranking_signals?: RankingSignal[];
+  diagnostics?: TrapSearchDiagnostic[];
+};
+
+export type McpTrapActionCard = TrapActionCard & {
+  next_action: {
+    details_tool: "get_trap";
+    details_args: {
+      id: number;
+      scope: Scope;
+    };
+  };
+  ranking_signals?: RankingSignal[];
+  diagnostics?: TrapSearchDiagnostic[];
+};
+
+export type McpTextResult = {
+  content: { type: "text"; text: string }[];
+  isError?: boolean;
+};
+
+export type McpResourceResult = {
+  contents: { uri: string; mimeType: string; text: string }[];
+};
+
+export function toCliSearchJson(cards: TrapActionCard[]): CliTrapActionCard[] {
+  return cards.map((card) => ({
+    trap_id: card.trap_id,
+    scope: card.scope,
+    title: card.title,
+    why_relevant: card.why_relevant,
+    avoid: card.avoid,
+    do_instead: card.do_instead,
+    severity: card.severity,
+    score: card.score,
+    sources: card.sources,
+    ...(card.diagnostics ? { diagnostics: card.diagnostics } : {}),
+    ...(card.ranking_signals ? { ranking_signals: card.ranking_signals } : {}),
+    next_action: {
+      command: `codetrap show ${card.trap_id} --scope ${card.scope} --json`,
+    },
+  }));
+}
+
+export function toMcpSearchJson(cards: TrapActionCard[]): McpTrapActionCard[] {
+  return cards.map((card) => ({
+    ...card,
+    next_action: {
+      details_tool: "get_trap",
+      details_args: {
+        id: card.trap_id,
+        scope: card.scope,
+      },
+    },
+  }));
+}
+
+export function toMcpTextJson(value: unknown, isError = false): McpTextResult {
+  return {
+    content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+    ...(isError ? { isError: true } : {}),
+  };
+}
+
+export function toMcpTextError(message: string): McpTextResult {
+  return toMcpTextJson({ error: message }, true);
+}
+
+export function toMcpResourceJson(uri: string, value: unknown): McpResourceResult {
+  return {
+    contents: [{ uri, mimeType: "application/json", text: JSON.stringify(value, null, 2) }],
+  };
+}
+
+export function toMcpResourceText(uri: string, text: string): McpResourceResult {
+  return {
+    contents: [{ uri, mimeType: "text/plain", text }],
+  };
+}
+
+export function toTrapDetailsJson(details: TrapDetails): JsonTrapDetails {
+  return {
+    scope: details.scope,
+    trap: toTrapJson(details.trap),
+    evidence: details.evidence.map(toTrapEvidenceJson),
+  };
+}
+
+export function toListJson(groups: TrapListGroup[]): JsonTrap[] {
+  return groups.flatMap((group) =>
+    group.traps.map((trap) => ({
+      ...toTrapJson(trap),
+      scope: group.scope,
+    }))
+  );
+}
+
+export function toStatsJson(stats: TrapStatsResult, embeddings?: EmbeddingStatsResult) {
+  return {
+    project: stats.project
+      ? {
+          ...stats.project,
+          embeddings: embeddings?.project ?? null,
+        }
+      : null,
+    global: stats.global
+      ? {
+          ...stats.global,
+          embeddings: embeddings?.global ?? null,
+        }
+      : null,
+  };
+}
+
+export function toDoctorJson(input: DoctorReport): DoctorReport {
+  return input;
+}
+
+export { toTrapEvidenceJson, toTrapJson, type JsonTrap, type JsonTrapEvidence };