codetrap 0.1.1 → 0.1.3

package/src/db/queries.ts

@@ -12,32 +12,37 @@ import {
 } 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 {
+  encodeTrapInsertFields,
+  mergeTrapUpdateForSearchText,
+  normalizeEvidenceForExport,
+  normalizeTrapForExport,
+} from "../lib/trap-codec";
+import { encodeEvidenceRelatedFiles, encodeTrapPathGlobs, encodeTrapTags } from "../lib/trap-json-fields";
 import { buildTrapSearchText, passageFieldsChanged, searchTextFieldsChanged } from "../lib/trap-search-document";
 
 export type TrapStatusFilter = TrapStatus | "all";
+export type TrapRecordInsert = Omit<Trap, "id">;
 
 export function insertTrap(db: Database, input: TrapInput): number {
-  const tags = encodeTrapTags(input.tags);
-  const searchText = buildTrapSearchText({ ...input, tags });
+  const fields = encodeTrapInsertFields(input);
   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
+      valid_from, valid_until, project_path, path_globs, module, owner
     )
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'), ?, ?)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'), ?, ?, ?, ?, ?)
   `);
   const result = stmt.run(
     input.title,
     input.category,
-    tags,
+    fields.tags,
     input.scope,
     input.context,
     input.mistake,
     input.fix,
-    searchText,
+    fields.search_text,
     input.before_code ?? null,
     input.after_code ?? null,
     input.severity ?? DEFAULT_SEVERITY,
@@ -45,7 +50,10 @@ export function insertTrap(db: Database, input: TrapInput): number {
     DEFAULT_TRAP_STATUS,
     null,
     null,
-    input.project_path ?? null
+    input.project_path ?? null,
+    fields.path_globs,
+    normalizeOptionalText(input.module),
+    normalizeOptionalText(input.owner)
   );
   return Number(result.lastInsertRowid);
 }
@@ -53,7 +61,7 @@ export function insertTrap(db: Database, input: TrapInput): number {
 export function searchTraps(
   db: Database,
   query: string,
-  opts: { category?: string; scope?: string; limit?: number; status?: TrapStatusFilter } = {}
+  opts: { category?: string; scope?: string; limit?: number; status?: TrapStatusFilter; module?: string; owner?: string } = {}
 ): TrapSearchResult[] {
   const prepared = prepareFTSQuery(normalizeQuery(query));
   if (!prepared) return [];
@@ -86,7 +94,7 @@ export function getTrap(db: Database, id: number): Trap | null {
 
 export function listTraps(
   db: Database,
-  opts: { category?: string; scope?: string; limit?: number; offset?: number; status?: TrapStatusFilter } = {}
+  opts: { category?: string; scope?: string; limit?: number; offset?: number; status?: TrapStatusFilter; module?: string; owner?: string } = {}
 ): Trap[] {
   const conditions: string[] = [];
   const params: SQLQueryBindings[] = [];
@@ -108,24 +116,24 @@ export function updateTrap(db: Database, id: number, input: TrapUpdate): boolean
   const current = searchTextFieldsChanged(input) || passageFieldsChanged(input) ? getTrap(db, id) : null;
 
   for (const key of TRAP_UPDATE_FIELDS) {
-    if (key === "tags") continue;
+    if (key === "tags" || key === "path_globs") continue;
     const value = input[key];
     if (value !== undefined) {
       updates.push(`${key} = ?`);
-      params.push(value ?? null);
+      params.push(key === "module" || key === "owner" ? normalizeOptionalText(value) : value ?? null);
     }
   }
   if (input.tags !== undefined) {
     updates.push("tags = ?");
     params.push(encodeTrapTags(input.tags));
   }
+  if (input.path_globs !== undefined) {
+    updates.push("path_globs = ?");
+    params.push(encodeTrapPathGlobs(input.path_globs));
+  }
 
   if (current && searchTextFieldsChanged(input)) {
-    const merged = {
-      ...current,
-      ...input,
-      tags: input.tags !== undefined ? encodeTrapTags(input.tags) : current.tags,
-    };
+    const merged = mergeTrapUpdateForSearchText(current, input);
     updates.push("search_text = ?");
     params.push(buildTrapSearchText(merged));
   }
@@ -260,11 +268,79 @@ export function getStats(db: Database): {
 export function exportTraps(db: Database): TrapExportRecord[] {
   const traps = db.query("SELECT * FROM traps").all() as Trap[];
   return traps.map((trap) => ({
-    ...trap,
+    ...normalizeTrapForExport(trap),
     evidence: listTrapEvidence(db, trap.id).map(normalizeEvidenceForExport),
   }));
 }
 
+export function exportProjectTrapsByPath(db: Database, projectPath: string): TrapExportRecord[] {
+  const traps = db
+    .query("SELECT * FROM traps WHERE scope = 'project' AND project_path = ? ORDER BY id")
+    .all(projectPath) as Trap[];
+  return traps.map((trap) => ({
+    ...normalizeTrapForExport(trap),
+    evidence: listTrapEvidence(db, trap.id).map(normalizeEvidenceForExport),
+  }));
+}
+
+export function insertTrapRecord(db: Database, record: TrapRecordInsert): number {
+  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, path_globs, module, owner,
+      hit_count, created_at, updated_at
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+  const result = stmt.run(
+    record.title,
+    record.category,
+    record.tags,
+    record.scope,
+    record.context,
+    record.mistake,
+    record.fix,
+    record.search_text,
+    record.before_code,
+    record.after_code,
+    record.severity,
+    record.state_key,
+    record.status,
+    record.supersedes_id,
+    record.valid_from,
+    record.valid_until,
+    record.project_path,
+    record.path_globs,
+    normalizeOptionalText(record.module),
+    normalizeOptionalText(record.owner),
+    record.hit_count,
+    record.created_at,
+    record.updated_at
+  );
+  return Number(result.lastInsertRowid);
+}
+
+export function updateTrapSupersedesId(db: Database, id: number, supersedesId: number): boolean {
+  const result = db.prepare("UPDATE traps SET supersedes_id = ? WHERE id = ?").run(supersedesId, id);
+  return result.changes > 0;
+}
+
+export function deleteTrapsByIds(db: Database, ids: number[]): number {
+  if (ids.length === 0) return 0;
+  let deleted = 0;
+  const stmt = db.prepare("DELETE FROM traps WHERE id = ?");
+  const tx = db.transaction(() => {
+    for (const id of ids) {
+      if (!getTrap(db, id)) continue;
+      stmt.run(id);
+      deleted++;
+    }
+  });
+  tx();
+  return deleted;
+}
+
 export function countTraps(db: Database, opts: { scope?: string; category?: string; status?: TrapStatusFilter } = {}): number {
   const conditions: string[] = [];
   const params: SQLQueryBindings[] = [];
@@ -274,10 +350,17 @@ export function countTraps(db: Database, opts: { scope?: string; category?: stri
   return row.c;
 }
 
+export function countProjectTrapsByPath(db: Database, projectPath: string): number {
+  const row = db
+    .query("SELECT COUNT(*) as c FROM traps WHERE scope = 'project' AND project_path = ?")
+    .get(projectPath) as { c: number };
+  return row.c;
+}
+
 function addTrapFilters(
   conditions: string[],
   params: SQLQueryBindings[],
-  opts: { category?: string; scope?: string; status?: TrapStatusFilter },
+  opts: { category?: string; scope?: string; status?: TrapStatusFilter; module?: string; owner?: string },
   alias?: string
 ): void {
   const prefix = alias ? `${alias}.` : "";
@@ -293,4 +376,20 @@ function addTrapFilters(
     conditions.push(`${prefix}status = ?`);
     params.push(opts.status ?? DEFAULT_TRAP_STATUS);
   }
+  const module = normalizeOptionalText(opts.module);
+  if (module) {
+    conditions.push(`(${prefix}module IS NULL OR ${prefix}module = '' OR ${prefix}module = ?)`);
+    params.push(module);
+  }
+  const owner = normalizeOptionalText(opts.owner);
+  if (owner) {
+    conditions.push(`(${prefix}owner IS NULL OR ${prefix}owner = '' OR ${prefix}owner = ?)`);
+    params.push(owner);
+  }
+}
+
+function normalizeOptionalText(value: unknown): string | null {
+  if (typeof value !== "string") return value == null ? null : String(value);
+  const trimmed = value.trim();
+  return trimmed === "" ? null : trimmed;
 }

package/src/db/repository.ts

@@ -19,11 +19,15 @@ import { runEmbeddingJob } from "../lib/embedding-job";
 import { passageFieldsChanged } from "../lib/trap-search-document";
 import * as queries from "./queries";
 import type { TrapStatus } from "../lib/constants";
+import { TrapSearchPolicy } from "../lib/search-policy";
 
 export type TrapStats = ReturnType<typeof queries.getStats>;
+export type EmbeddingStateCounts = ReturnType<typeof embeddingQueries.getEmbeddingStateCounts>;
+export type TrapRecordInsert = queries.TrapRecordInsert;
 
 export class TrapRepository {
   private readonly searchService: SearchService;
+  private readonly searchPolicy = new TrapSearchPolicy();
 
   constructor(
     private readonly db: Database,
@@ -54,8 +58,13 @@ export class TrapRepository {
     };
   }
 
-  list(opts: { category?: string; scope?: string; limit?: number; offset?: number; status?: TrapStatus | "all" } = {}): Trap[] {
-    return queries.listTraps(this.db, opts);
+  list(opts: { category?: string; scope?: string; limit?: number; offset?: number; status?: TrapStatus | "all"; path?: string; module?: string; owner?: string } = {}): Trap[] {
+    const limit = opts.limit ?? 50;
+    const queryLimit = opts.path ? Math.max(limit * 5, 250) : limit;
+    return queries
+      .listTraps(this.db, { ...opts, limit: queryLimit })
+      .filter((trap) => this.searchPolicy.matchesTrap(trap, opts))
+      .slice(0, limit);
   }
 
   update(id: number, input: TrapUpdate): boolean {
@@ -95,10 +104,38 @@ export class TrapRepository {
     return queries.getStats(this.db);
   }
 
+  embeddingStats(config: EmbeddingConfig | null): EmbeddingStateCounts {
+    return embeddingQueries.getEmbeddingStateCounts(this.db, config);
+  }
+
   exportAll(): TrapExportRecord[] {
     return queries.exportTraps(this.db);
   }
 
+  exportProjectTrapsByPath(projectPath: string): TrapExportRecord[] {
+    return queries.exportProjectTrapsByPath(this.db, projectPath);
+  }
+
+  insertTrapRecord(record: TrapRecordInsert): number {
+    return queries.insertTrapRecord(this.db, record);
+  }
+
+  updateTrapSupersedesId(id: number, supersedesId: number): boolean {
+    return queries.updateTrapSupersedesId(this.db, id, supersedesId);
+  }
+
+  deleteTrapsByIds(ids: number[]): number {
+    return queries.deleteTrapsByIds(this.db, ids);
+  }
+
+  countProjectTrapsByPath(projectPath: string): number {
+    return queries.countProjectTrapsByPath(this.db, projectPath);
+  }
+
+  transaction<T>(callback: () => T): T {
+    return this.db.transaction(callback)();
+  }
+
   getEmbedding(trapId: number): StoredEmbedding | null {
     return embeddingQueries.getEmbedding(this.db, trapId);
   }

package/src/db/schema.ts

@@ -140,6 +140,41 @@ function applyMigrations(db: Database, from: number): void {
 
     db.prepare("UPDATE schema_version SET version = ?").run(4);
   }
+
+  if (from < 5) {
+    if (!columnExists(db, "traps", "path_globs")) {
+      db.exec("ALTER TABLE traps ADD COLUMN path_globs TEXT NOT NULL DEFAULT '[]'");
+    }
+    if (!columnExists(db, "traps", "module")) {
+      db.exec("ALTER TABLE traps ADD COLUMN module TEXT");
+    }
+    if (!columnExists(db, "traps", "owner")) {
+      db.exec("ALTER TABLE traps ADD COLUMN owner TEXT");
+    }
+
+    const rows = db
+      .query("SELECT id, title, context, mistake, fix, tags, before_code, after_code, path_globs, module, owner FROM traps")
+      .all() as {
+      id: number;
+      title: string;
+      context: string;
+      mistake: string;
+      fix: string;
+      tags: string;
+      before_code: string | null;
+      after_code: string | null;
+      path_globs: string;
+      module: string | null;
+      owner: string | null;
+    }[];
+
+    const update = db.prepare("UPDATE traps SET search_text = ? WHERE id = ?");
+    for (const row of rows) {
+      update.run(buildTrapSearchText(row), row.id);
+    }
+
+    db.prepare("UPDATE schema_version SET version = ?").run(5);
+  }
 }
 
 function columnExists(db: Database, table: string, column: string): boolean {

package/src/domain/trap.ts

@@ -30,6 +30,9 @@ export interface Trap {
   valid_from: string;
   valid_until: string | null;
   project_path: string | null;
+  path_globs: string;
+  module: string | null;
+  owner: string | null;
   hit_count: number;
   created_at: string;
   updated_at: string;
@@ -47,6 +50,9 @@ export interface TrapInput {
   after_code?: string;
   severity?: string;
   project_path?: string | null;
+  path_globs?: string[];
+  module?: string | null;
+  owner?: string | null;
 }
 
 export interface TrapSearchResult {
@@ -55,6 +61,13 @@ export interface TrapSearchResult {
   sources?: ("fts" | "semantic")[];
   score?: number;
   diagnostics?: { code: string; message: string }[];
+  ranking_signals?: RankingSignal[];
+}
+
+export interface RankingSignal {
+  code: string;
+  weight: number;
+  detail?: string;
 }
 
 export interface TrapActionCard {
@@ -67,6 +80,7 @@ export interface TrapActionCard {
   severity: string;
   score: number | null;
   sources: ("fts" | "semantic")[];
+  ranking_signals?: RankingSignal[];
   next_action: {
     details_tool: "get_trap";
     details_args: {
@@ -101,7 +115,8 @@ export interface TrapExportEvidence extends Omit<TrapEvidence, "related_files">
   related_files: string[];
 }
 
-export interface TrapExportRecord extends Trap {
+export interface TrapExportRecord extends Omit<Trap, "path_globs"> {
+  path_globs: string[];
   evidence: TrapExportEvidence[];
 }
 
@@ -110,11 +125,12 @@ export type TrapImportEvidence = Partial<Omit<TrapEvidence, "related_files">> &
   related_files?: string[] | string | null;
 };
 
-export type TrapImportRecord = Omit<TrapInput, "tags" | "before_code" | "after_code" | "project_path"> & {
+export type TrapImportRecord = Omit<TrapInput, "tags" | "before_code" | "after_code" | "project_path" | "path_globs"> & {
   tags?: string[] | string | null;
   before_code?: string | null;
   after_code?: string | null;
   project_path?: string | null;
+  path_globs?: string[] | string | null;
   evidence?: TrapImportEvidence[];
 };
 
@@ -168,6 +184,9 @@ export const TRAP_UPDATE_FIELDS = [
   "before_code",
   "after_code",
   "severity",
+  "path_globs",
+  "module",
+  "owner",
 ] as const;
 
 export const TRAP_INPUT_SCHEMA_PROPERTIES = {
@@ -185,6 +204,13 @@ export const TRAP_INPUT_SCHEMA_PROPERTIES = {
   before_code: { type: "string", description: "Example of wrong code (optional)" },
   after_code: { type: "string", description: "Example of correct code (optional)" },
   severity: { type: "string", enum: [...SEVERITIES] as string[], description: "How severe is this pitfall?" },
+  path_globs: {
+    type: "array",
+    items: { type: "string" },
+    description: "Optional file globs where this trap applies, for example src/db/**",
+  },
+  module: { type: "string", description: "Optional module or subsystem where this trap applies" },
+  owner: { type: "string", description: "Optional team or owner for this trap" },
 } satisfies Record<keyof Omit<TrapInput, "project_path">, JsonSchemaProperty>;
 
 export function trapInputSchema() {
@@ -270,6 +296,9 @@ export function buildTrapInput(args: Record<string, any>): TrapInput {
     before_code: args.before_code,
     after_code: args.after_code,
     severity: args.severity ?? DEFAULT_SEVERITY,
+    path_globs: Array.isArray(args.path_globs) ? args.path_globs.map(String) : args.path_globs,
+    module: args.module,
+    owner: args.owner,
   };
 }
 

package/src/index.ts

@@ -46,6 +46,9 @@ function showHelp(): void {
   console.log("  export                Export traps as JSON");
   console.log("  import <file.json>    Import traps from JSON");
   console.log("  stats                 Show statistics");
+  console.log("  doctor                Diagnose scope, database, and embedding health");
+  console.log("  repair-scope          Move mis-scoped project traps into the current project");
+  console.log("  migrate-project       Move project traps between initialized projects");
   console.log("  serve                 Start MCP server (for Claude Code)");
   console.log("");
   console.log("Flags:");
@@ -53,6 +56,15 @@ function showHelp(): void {
   console.log("  --category <name>       Filter by category");
   console.log("  --mode fts|semantic|hybrid  Search mode");
   console.log("  --status active|superseded|archived|all  Lifecycle filter");
+  console.log("  --path <file>           Filter/boost traps scoped to a file path");
+  console.log("  --module <name>         Filter/boost traps scoped to a module");
+  console.log("  --owner <name>          Filter/boost traps scoped to an owner/team");
+  console.log("  --no-rerank             Disable query-aware search reranking");
+  console.log("  --ranking-signals       Include search ranking diagnostics in JSON cards");
   console.log("  --batch-size <n>        Embedding generation batch size");
-  console.log("  --json '{}'             JSON input for add/edit");
+  console.log("  --json                  JSON output for search/show/list/stats/doctor; JSON input for add/edit");
+  console.log("  --output-json           JSON output for add/edit when --json is used as input");
+  console.log("  --from-project-path <path>  Source project path for scope repair/migration");
+  console.log("  --to-project-path <path>    Destination project path for scope repair/migration");
+  console.log("  --dry-run|--apply       Preview or apply scope repair/migration");
 }

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,76 @@
+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;
+  };
+  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,
+    },
+    embeddings,
+    hybrid_search: {
+      semantic_available: semanticAvailable,
+      fallback_reason: hybridFallbackReason(semanticAvailable, embeddings),
+    },
+    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)"}`,
+    `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}`;
+}