codetrap 0.1.3 → 0.1.5

package/src/lib/scope-path.ts

@@ -0,0 +1,99 @@
+import { existsSync, realpathSync } from "node:fs";
+import { posix, win32 } from "node:path";
+
+export type ScopePathFlavor = "posix" | "win32";
+
+export type ScopePathFs = {
+  exists(path: string): boolean;
+  realpath(path: string): string;
+};
+
+export type ScopePathResolverOptions = {
+  fs?: ScopePathFs;
+  platform?: NodeJS.Platform;
+};
+
+const nodeFs: ScopePathFs = {
+  exists: existsSync,
+  realpath: realpathSync,
+};
+
+export class ScopePathResolver {
+  private readonly fs: ScopePathFs;
+  private readonly platform: NodeJS.Platform;
+
+  constructor(options: ScopePathResolverOptions = {}) {
+    this.fs = options.fs ?? nodeFs;
+    this.platform = options.platform ?? process.platform;
+  }
+
+  resolve(path: string, relatedPath = path): string {
+    return this.resolveWithFlavor(path, this.flavorFor(path, relatedPath));
+  }
+
+  canonical(path: string, relatedPath = path): string {
+    const flavor = this.flavorFor(path, relatedPath);
+    const resolved = this.resolveWithFlavor(path, flavor);
+    const real = this.fs.exists(resolved) ? this.fs.realpath(resolved) : resolved;
+    const normalized = pathApi(flavor).normalize(real);
+    return flavor === "win32" ? normalized.toLowerCase() : normalized;
+  }
+
+  same(left: string, right: string): boolean {
+    const flavor = this.flavorFor(left, right);
+    return this.canonicalWithFlavor(left, flavor) === this.canonicalWithFlavor(right, flavor);
+  }
+
+  join(base: string, ...segments: string[]): string {
+    return pathApi(this.flavorFor(base)).join(base, ...segments);
+  }
+
+  exists(path: string): boolean {
+    return this.fs.exists(path);
+  }
+
+  dirname(path: string): string {
+    return pathApi(this.flavorFor(path)).dirname(path);
+  }
+
+  flavorFor(...paths: string[]): ScopePathFlavor {
+    if (this.platform === "win32") return "win32";
+    return paths.some((path) => isWindowsAbsolutePath(path) || isMsysAbsolutePath(path)) ? "win32" : "posix";
+  }
+
+  private canonicalWithFlavor(path: string, flavor: ScopePathFlavor): string {
+    const resolved = this.resolveWithFlavor(path, flavor);
+    const real = this.fs.exists(resolved) ? this.fs.realpath(resolved) : resolved;
+    const normalized = pathApi(flavor).normalize(real);
+    return flavor === "win32" ? normalized.toLowerCase() : normalized;
+  }
+
+  private resolveWithFlavor(path: string, flavor: ScopePathFlavor): string {
+    return pathApi(flavor).resolve(flavor === "win32" ? msysToWindowsPath(path) : path);
+  }
+}
+
+export const defaultScopePathResolver = new ScopePathResolver();
+
+export function resolveScopePath(path: string, relatedPath = path): string {
+  return defaultScopePathResolver.resolve(path, relatedPath);
+}
+
+function pathApi(flavor: ScopePathFlavor): typeof posix {
+  return flavor === "win32" ? win32 : posix;
+}
+
+function msysToWindowsPath(path: string): string {
+  const match = path.match(/^\/([a-zA-Z])(?:\/(.*))?$/);
+  if (!match) return path;
+  const [, drive, rest = ""] = match;
+  return `${drive.toUpperCase()}:\\${rest.replaceAll("/", "\\")}`;
+}
+
+function isWindowsAbsolutePath(path: string): boolean {
+  return /^[a-zA-Z]:[\\/]/.test(path) || /^\\\\/.test(path);
+}
+
+function isMsysAbsolutePath(path: string): boolean {
+  return /^\/[a-zA-Z](?:\/|$)/.test(path);
+}

package/src/lib/scope.ts

@@ -1,32 +1,37 @@
 import { existsSync, mkdirSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
 import { homedir } from "node:os";
 import { CODETRAP_DIR, TRAPS_DB_FILE } from "./constants";
+import { defaultScopePathResolver, resolveScopePath, ScopePathResolver } from "./scope-path";
+
+export { resolveScopePath, ScopePathResolver } from "./scope-path";
 
 export function getGlobalDir(): string {
-  const dir = join(homedir(), CODETRAP_DIR);
+  const dir = defaultScopePathResolver.join(homedir(), CODETRAP_DIR);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   return dir;
 }
 
 export function getGlobalDB(): string {
-  return join(getGlobalDir(), TRAPS_DB_FILE);
+  return defaultScopePathResolver.join(getGlobalDir(), TRAPS_DB_FILE);
 }
 
-export function findProjectRoot(cwd: string, homeDir = homedir()): string | null {
-  let dir = resolve(cwd);
-  const home = resolve(homeDir);
+export function findProjectRoot(
+  cwd: string,
+  homeDir = homedir(),
+  resolver: ScopePathResolver = defaultScopePathResolver
+): string | null {
+  let dir = resolver.resolve(cwd, homeDir);
   while (true) {
-    if (dir === home) return null;
-    if (existsSync(join(dir, CODETRAP_DIR))) return dir;
-    const parent = dirname(dir);
+    if (resolver.same(dir, homeDir)) return null;
+    if (resolver.exists(resolver.join(dir, CODETRAP_DIR))) return dir;
+    const parent = resolver.dirname(dir);
     if (parent === dir) return null;
     dir = parent;
   }
 }
 
 export function getProjectDB(root: string): string {
-  const dir = join(root, CODETRAP_DIR);
+  const dir = defaultScopePathResolver.join(root, CODETRAP_DIR);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  return join(dir, TRAPS_DB_FILE);
+  return defaultScopePathResolver.join(dir, TRAPS_DB_FILE);
 }

package/src/lib/search-policy.ts

@@ -1,4 +1,5 @@
 import type { RankingSignal, Trap, TrapSearchResult } from "../domain/trap";
+import type { TrapStatus } from "./constants";
 import { EmbeddingProviderUnavailableError } from "./embedder";
 import { parseTrapPathGlobs, parseTrapTags } from "./trap-json-fields";
 import {
@@ -8,11 +9,39 @@ import {
 } from "./trap-scope-match";
 
 export interface SearchPolicyOptions extends ApplicabilityFilter {
+  category?: string;
+  scope?: string;
+  status?: TrapStatus | "all";
   limit?: number;
   rerank?: boolean;
   includeRankingSignals?: boolean;
 }
 
+export type SearchStorageFilter = {
+  category?: string;
+  scope?: string;
+  status?: TrapStatus | "all";
+  module?: string;
+  owner?: string;
+  limit?: number;
+};
+
+export type SemanticStorageFilter = {
+  category?: string;
+  scope?: string;
+  status?: TrapStatus | "all";
+};
+
+export type SearchRetrievalSource = "fts" | "semantic";
+
+export interface SearchRetrievalPlan {
+  resultLimit: number;
+  candidateLimit: number;
+  ftsStorageFilter: SearchStorageFilter & { limit: number };
+  semanticStorageFilter: SemanticStorageFilter;
+  applicabilityFilter: ApplicabilityFilter;
+}
+
 export interface RankingConfig {
   rrfK: number;
   semanticMinScore: number;
@@ -48,6 +77,33 @@ export const DEFAULT_RANKING_CONFIG: RankingConfig = {
 export class TrapSearchPolicy {
   constructor(private readonly ranking: RankingConfig = DEFAULT_RANKING_CONFIG) {}
 
+  plan(opts: SearchPolicyOptions, defaultLimit: number): SearchRetrievalPlan {
+    const resultLimit = opts.limit ?? defaultLimit;
+    const candidateLimit = this.candidateLimit(opts, resultLimit);
+    return {
+      resultLimit,
+      candidateLimit,
+      ftsStorageFilter: {
+        category: opts.category,
+        scope: opts.scope,
+        status: opts.status,
+        module: opts.module,
+        owner: opts.owner,
+        limit: candidateLimit,
+      },
+      semanticStorageFilter: {
+        category: opts.category,
+        scope: opts.scope,
+        status: opts.status,
+      },
+      applicabilityFilter: {
+        path: opts.path,
+        module: opts.module,
+        owner: opts.owner,
+      },
+    };
+  }
+
   candidateLimit(opts: SearchPolicyOptions, resultLimit: number): number {
     return shouldOverfetch(opts) ? Math.max(resultLimit * 5, 50) : resultLimit;
   }
@@ -68,6 +124,30 @@ export class TrapSearchPolicy {
     return traps.filter((trap) => this.matchesTrap(trap, filter));
   }
 
+  prepareRetrievedResults(
+    results: TrapSearchResult[],
+    source: SearchRetrievalSource,
+    plan: SearchRetrievalPlan
+  ): TrapSearchResult[] {
+    const applicable = this.filterResults(results, plan.applicabilityFilter);
+    if (source === "semantic") {
+      return applicable
+        .filter((result) => (result.score ?? 0) >= this.semanticMinScore())
+        .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
+        .slice(0, plan.candidateLimit);
+    }
+    return applicable.slice(0, plan.candidateLimit);
+  }
+
+  finalizeResults(
+    results: TrapSearchResult[],
+    query: string,
+    opts: SearchPolicyOptions,
+    plan: SearchRetrievalPlan
+  ): TrapSearchResult[] {
+    return this.rankResults(results, query, opts, plan.resultLimit);
+  }
+
   rankResults(
     results: TrapSearchResult[],
     query: string,
@@ -95,12 +175,21 @@ export class TrapSearchPolicy {
         score: applyLengthNormalization(result.score, result.trap, this.ranking),
         rank: applyLengthNormalization(result.score, result.trap, this.ranking),
       }))
-      .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
-      .slice(0, limit);
+      .sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
 
     return this.rankResults(fused, query, opts, limit);
   }
 
+  fuseAndFinalize(
+    ftsResults: TrapSearchResult[],
+    semanticResults: TrapSearchResult[],
+    query: string,
+    opts: SearchPolicyOptions,
+    plan: SearchRetrievalPlan
+  ): TrapSearchResult[] {
+    return this.fuse(ftsResults, semanticResults, query, opts, plan.resultLimit);
+  }
+
   withDiagnostics(
     results: TrapSearchResult[],
     diagnostic: { code: string; message: string }

package/src/lib/search-result-card.ts

@@ -15,14 +15,8 @@ export function toTrapActionCard(result: TrapSearchResult, scope: Scope): TrapAc
     severity: trap.severity,
     score: result.score ?? null,
     sources: result.sources ?? [],
+    ...(result.diagnostics ? { diagnostics: result.diagnostics } : {}),
     ...(result.ranking_signals ? { ranking_signals: result.ranking_signals } : {}),
-    next_action: {
-      details_tool: "get_trap",
-      details_args: {
-        id: trap.id,
-        scope,
-      },
-    },
   };
 }
 

package/src/lib/search-service.ts

@@ -1,5 +1,4 @@
 import type { Database } from "bun:sqlite";
-import * as embeddingQueries from "../db/embedding-queries";
 import * as queries from "../db/queries";
 import type { TrapSearchResult } from "../domain/trap";
 import type { SearchMode, TrapStatus } from "./constants";
@@ -13,7 +12,9 @@ import {
   DEFAULT_RANKING_CONFIG,
   TrapSearchPolicy,
   type RankingConfig,
+  type SearchRetrievalPlan,
 } from "./search-policy";
+import { DatabaseEmbeddingIndex } from "./embedding-index";
 
 export interface SearchOptions {
   category?: string;
@@ -32,6 +33,7 @@ const DEFAULT_LIMIT = 20;
 
 export class SearchService {
   private readonly policy: TrapSearchPolicy;
+  private readonly embeddingIndex: DatabaseEmbeddingIndex;
 
   constructor(
     private readonly db: Database,
@@ -39,6 +41,7 @@ export class SearchService {
     ranking: RankingConfig = DEFAULT_RANKING_CONFIG
   ) {
     this.policy = new TrapSearchPolicy(ranking);
+    this.embeddingIndex = new DatabaseEmbeddingIndex(db);
   }
 
   async search(query: string, opts: SearchOptions = {}): Promise<TrapSearchResult[]> {
@@ -58,20 +61,51 @@ export class SearchService {
   }
 
   ftsSearch(query: string, opts: SearchOptions = {}): TrapSearchResult[] {
-    const limit = opts.limit ?? DEFAULT_LIMIT;
-    const searchLimit = this.policy.candidateLimit(opts, limit);
+    const plan = this.policy.plan(opts, DEFAULT_LIMIT);
+    return this.policy.finalizeResults(this.retrieveFtsCandidates(query, plan), query, opts, plan);
+  }
+
+  async semanticSearch(query: string, opts: SearchOptions = {}): Promise<TrapSearchResult[]> {
+    const plan = this.policy.plan(opts, DEFAULT_LIMIT);
+    return this.policy.finalizeResults(await this.retrieveSemanticCandidates(query, plan), query, opts, plan);
+  }
+
+  async hybridSearch(query: string, opts: SearchOptions = {}): Promise<TrapSearchResult[]> {
+    const plan = this.policy.plan(opts, DEFAULT_LIMIT);
+    const ftsCandidates = this.retrieveFtsCandidates(query, plan);
+
+    try {
+      const semanticCandidates = await this.retrieveSemanticCandidates(query, plan);
+      if (semanticCandidates.length === 0) {
+        return this.policy.withDiagnostics(this.policy.finalizeResults(ftsCandidates, query, opts, plan), {
+          code: "semantic_no_candidates",
+          message: "Hybrid search used FTS results because no fresh semantic candidates passed the score threshold.",
+        });
+      }
+      return this.policy.fuseAndFinalize(ftsCandidates, semanticCandidates, query, opts, plan);
+    } catch (error) {
+      return this.policy.withDiagnostics(
+        this.policy.finalizeResults(ftsCandidates, query, opts, plan),
+        this.policy.semanticDiagnostic(error)
+      );
+    }
+  }
+
+  private retrieveFtsCandidates(query: string, plan: SearchRetrievalPlan): TrapSearchResult[] {
     const candidates = queries
-      .searchTraps(this.db, query, { ...opts, limit: searchLimit })
-      .filter((result) => this.policy.matchesTrap(result.trap, opts))
+      .searchTraps(this.db, query, plan.ftsStorageFilter)
       .map((result) => ({
         ...result,
         sources: ["fts"] as ("fts")[],
         score: ftsScore(result.rank),
       }));
-    return this.policy.rankResults(candidates, query, opts, limit);
+    return this.policy.prepareRetrievedResults(candidates, "fts", plan);
   }
 
-  async semanticSearch(query: string, opts: SearchOptions = {}): Promise<TrapSearchResult[]> {
+  private async retrieveSemanticCandidates(
+    query: string,
+    plan: SearchRetrievalPlan
+  ): Promise<TrapSearchResult[]> {
     if (!this.embedder) {
       throw new EmbeddingProviderUnavailableError();
     }
@@ -80,11 +114,7 @@ export class SearchService {
     if (!queryEmbedding) return [];
 
     const config = embeddingConfig(this.embedder);
-    const candidates = embeddingQueries.getAllFreshEmbeddings(this.db, config, {
-      category: opts.category,
-      scope: opts.scope,
-      status: opts.status,
-    });
+    const candidates = this.embeddingIndex.freshEmbeddings(config, plan.semanticStorageFilter);
 
     const results = candidates
       .map(({ trap, embedding }) => {
@@ -96,29 +126,8 @@ export class SearchService {
           score,
         };
       })
-      .filter((result) => this.policy.matchesTrap(result.trap, opts))
-      .filter((result) => (result.score ?? 0) >= this.policy.semanticMinScore())
-      .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
       .map((result) => result as TrapSearchResult);
-    return this.policy.rankResults(results, query, opts, opts.limit ?? DEFAULT_LIMIT);
-  }
-
-  async hybridSearch(query: string, opts: SearchOptions = {}): Promise<TrapSearchResult[]> {
-    const limit = opts.limit ?? DEFAULT_LIMIT;
-    const ftsResults = this.ftsSearch(query, { ...opts, limit });
-
-    try {
-      const semanticResults = await this.semanticSearch(query, { ...opts, limit });
-      if (semanticResults.length === 0) {
-        return this.policy.withDiagnostics(ftsResults, {
-          code: "semantic_no_candidates",
-          message: "Hybrid search used FTS results because no fresh semantic candidates passed the score threshold.",
-        });
-      }
-      return this.policy.fuse(ftsResults, semanticResults, query, opts, limit);
-    } catch (error) {
-      return this.policy.withDiagnostics(ftsResults, this.policy.semanticDiagnostic(error));
-    }
+    return this.policy.prepareRetrievedResults(results, "semantic", plan);
   }
 }
 

package/src/lib/store.ts

@@ -167,19 +167,51 @@ export class TrapStore {
     return this.scopes.repositoryFor(resolvedScope).top(resolvedScope, limit);
   }
 
-  stats(): { project: TrapStats | null; global: TrapStats } {
-    const project = this.scopes.repositoryEntry("project")?.repository.stats() ?? null;
-    return { project, global: this.scopes.repositoryFor("global").stats() };
+  stats(opts: { scope?: string } = {}): { project: TrapStats | null; global: TrapStats | null } {
+    const scope = opts.scope ? normalizeScope(opts.scope) : null;
+    const project = scope === "global"
+      ? null
+      : this.scopes.repositoryEntry("project")?.repository.stats({ scope: "project" }) ?? null;
+    const global = scope === "project"
+      ? null
+      : this.scopes.repositoryFor("global").stats({ scope: "global" });
+    return { project, global };
   }
 
-  embeddingStats(): TrapEmbeddingStats {
+  embeddingStats(opts: { scope?: string } = {}): TrapEmbeddingStats {
+    const scope = opts.scope ? normalizeScope(opts.scope) : null;
     const config = this.embeddingConfig();
-    const project = this.scopes.repositoryEntry("project")
-      ? summarizeEmbeddingState(this.scopes.repositoryFor("project").embeddingStats(config), config)
+    const project = scope === "global"
+      ? null
+      : this.scopes.repositoryEntry("project")
+      ? summarizeEmbeddingState(this.scopes.repositoryFor("project").embeddingStats(config, { scope: "project" }), config)
       : null;
+    const global = scope === "project"
+      ? null
+      : summarizeEmbeddingState(this.scopes.repositoryFor("global").embeddingStats(config, { scope: "global" }), config);
     return {
       project,
-      global: summarizeEmbeddingState(this.scopes.repositoryFor("global").embeddingStats(config), config),
+      global,
+    };
+  }
+
+  diagnostics(): {
+    mis_scoped_traps: {
+      global_db_project_traps: Pick<Trap, "id" | "title" | "scope" | "project_path" | "status">[];
+    };
+  } {
+    return {
+      mis_scoped_traps: {
+        global_db_project_traps: this.scopes.repositoryFor("global")
+          .listMisScoped("global")
+          .map((trap) => ({
+            id: trap.id,
+            title: trap.title,
+            scope: trap.scope,
+            project_path: trap.project_path,
+            status: trap.status,
+          })),
+      },
     };
   }
 

package/src/lib/trap-lifecycle.ts

@@ -0,0 +1,37 @@
+import type { Trap } from "../domain/trap";
+
+export type TrapLifecycleAdapter = {
+  get(id: number): Trap | null;
+  transaction<T>(callback: () => T): T;
+  markArchived(id: number): boolean;
+  markSuperseded(id: number, stateKey: string): boolean;
+  markSuperseding(id: number, supersedesId: number, stateKey: string): boolean;
+};
+
+export function archiveTrapLifecycle(adapter: TrapLifecycleAdapter, id: number): boolean {
+  return adapter.markArchived(id);
+}
+
+export function supersedeTrapLifecycle(
+  adapter: TrapLifecycleAdapter,
+  id: number,
+  supersededById: number,
+  stateKey?: string
+): boolean {
+  if (id === supersededById) return false;
+
+  const oldTrap = adapter.get(id);
+  const newTrap = adapter.get(supersededById);
+  if (!oldTrap || !newTrap) return false;
+
+  const key = lifecycleStateKey(oldTrap, newTrap, stateKey);
+  return adapter.transaction(() => {
+    adapter.markSuperseded(id, key);
+    adapter.markSuperseding(supersededById, id, key);
+    return true;
+  });
+}
+
+export function lifecycleStateKey(oldTrap: Trap, newTrap: Trap, requested?: string): string {
+  return requested ?? oldTrap.state_key ?? newTrap.state_key ?? `trap:${oldTrap.id}`;
+}

package/src/lib/trap-operations.ts

@@ -18,7 +18,7 @@ export type TrapListGroup = { traps: Trap[]; scope: string };
 export type TrapSearchGroup = { results: TrapSearchResult[]; scope: string };
 export type { AddTrapEvidenceResult, TrapMutationResult };
 
-export type TrapStatsResult = { project: TrapStats | null; global: TrapStats };
+export type TrapStatsResult = { project: TrapStats | null; global: TrapStats | null };
 export type EmbeddingStatsResult = ReturnType<TrapStore["embeddingStats"]>;
 
 export interface SearchTrapsArgs {
@@ -130,12 +130,12 @@ export class TrapOperations {
     return this.store.supersede(id, supersededById, scope, stateKey);
   }
 
-  getStats(): TrapStatsResult {
-    return this.store.stats();
+  getStats(scope?: string): TrapStatsResult {
+    return this.store.stats({ scope });
   }
 
-  getEmbeddingStats(): EmbeddingStatsResult {
-    return this.store.embeddingStats();
+  getEmbeddingStats(scope?: string): EmbeddingStatsResult {
+    return this.store.embeddingStats({ scope });
   }
 
   exportTraps(scope?: string): ReturnType<TrapStore["exportAll"]> {

package/src/mcp/server.ts

@@ -21,6 +21,11 @@ import {
   toTrapDetailsJson,
 } from "../lib/output-json";
 import { storeForScopeContext } from "../lib/scope-context";
+import {
+  listRequestFromArgs,
+  searchRequestFromArgs,
+  statsRequestFromArgs,
+} from "../lib/command-requests";
 
 type ToolArgs = Record<string, any>;
 
@@ -30,19 +35,8 @@ export async function handleToolCall(store: TrapStore, name: string, args: ToolA
   try {
     switch (name) {
       case "search_traps": {
-        const cards = await operations.searchTrapCards({
-          query: args.query,
-          scope: args.scope,
-          category: args.category,
-          mode: args.mode,
-          limit: args.limit ?? 20,
-          status: args.status,
-          path: args.path,
-          module: args.module,
-          owner: args.owner,
-          rerank: args.rerank,
-          includeRankingSignals: args.ranking_signals,
-        });
+        const defaults = { mode: "hybrid" as const, limit: args.limit ?? 20, rerank: true };
+        const cards = await operations.searchTrapCards(searchRequestFromArgs(args.query, args, defaults));
         return toMcpTextJson(toMcpSearchJson(cards));
       }
 
@@ -60,15 +54,7 @@ export async function handleToolCall(store: TrapStore, name: string, args: ToolA
       }
 
       case "list_traps": {
-        const groups = operations.listTraps({
-          scope: args.scope,
-          category: args.category,
-          status: args.status,
-          limit: args.limit ?? 50,
-          path: args.path,
-          module: args.module,
-          owner: args.owner,
-        });
+        const groups = operations.listTraps(listRequestFromArgs(args));
         return toMcpTextJson(toListJson(groups));
       }
 
@@ -98,8 +84,9 @@ export async function handleToolCall(store: TrapStore, name: string, args: ToolA
       }
 
       case "get_stats": {
-        const stats = operations.getStats();
-        return toMcpTextJson(toStatsJson(stats, operations.getEmbeddingStats()));
+        const request = statsRequestFromArgs(args);
+        const stats = operations.getStats(request.scope);
+        return toMcpTextJson(toStatsJson(stats, operations.getEmbeddingStats(request.scope)));
       }
 
       default: