codetrap 0.1.2 → 0.1.3

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;
+};
+
+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;
+  const total = (embeddings.project?.total ?? 0) + embeddings.global.total;
+  if (total > 0 && fresh === 0) return "semantic_no_candidates";
+  return null;
+}

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 {
@@ -25,6 +25,7 @@ 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,116 @@
+import type { RankingSignal, TrapActionCard, TrapDetails } 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 = Omit<TrapActionCard, "next_action"> & {
+  next_action: {
+    command: string;
+  };
+  ranking_signals?: RankingSignal[];
+};
+
+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.ranking_signals ? { ranking_signals: card.ranking_signals } : {}),
+    next_action: {
+      command: `codetrap show ${card.trap_id} --scope ${card.scope} --json`,
+    },
+  }));
+}
+
+export function toMcpSearchJson(cards: TrapActionCard[]): TrapActionCard[] {
+  return cards;
+}
+
+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,
+      embeddings: embeddings?.global ?? null,
+    },
+  };
+}
+
+export function toDoctorJson(input: DoctorReport): DoctorReport {
+  return input;
+}
+
+export { toTrapEvidenceJson, toTrapJson, type JsonTrap, type JsonTrapEvidence };

package/src/lib/scope-context.ts

@@ -0,0 +1,116 @@
+import { join, resolve } from "node:path";
+import { openGlobal, openProject } from "../db/connection";
+import { TrapRepository } from "../db/repository";
+import { CODETRAP_DIR, TRAPS_DB_FILE } from "./constants";
+import type { Scope } from "./constants";
+import type { EmbeddingProvider } from "./embedder";
+import { findProjectRoot, getGlobalDB } from "./scope";
+
+export type ScopeContext = {
+  cwd: string;
+  project_root: string | null;
+  project_db: string | null;
+  global_db: string;
+};
+
+export function createScopeContext(cwd = process.cwd()): ScopeContext {
+  const resolvedCwd = resolve(cwd);
+  const projectRoot = findProjectRoot(resolvedCwd);
+  return {
+    cwd: resolvedCwd,
+    project_root: projectRoot,
+    project_db: projectRoot ? join(projectRoot, CODETRAP_DIR, TRAPS_DB_FILE) : null,
+    global_db: getGlobalDB(),
+  };
+}
+
+export type ScopedRepository = {
+  scope: Scope;
+  repository: TrapRepository;
+};
+
+export class ScopedRepositoryContext {
+  private readonly context: ScopeContext;
+  private globalRepository?: TrapRepository;
+  private projectRepository?: TrapRepository;
+
+  constructor(cwd = process.cwd(), private readonly embedder?: EmbeddingProvider) {
+    this.context = createScopeContext(cwd);
+  }
+
+  hasProject(): boolean {
+    return this.context.project_root !== null;
+  }
+
+  projectRoot(): string | null {
+    return this.context.project_root;
+  }
+
+  repositoriesForRead(scope?: string): ScopedRepository[] {
+    const resolvedScope = optionalScope(scope);
+    if (resolvedScope) {
+      const entry = this.repositoryEntry(resolvedScope);
+      return entry ? [entry] : [];
+    }
+
+    const repositories: ScopedRepository[] = [];
+    const project = this.repositoryEntry("project");
+    if (project) repositories.push(project);
+    repositories.push({ scope: "global", repository: this.globalRepo() });
+    return repositories;
+  }
+
+  repositoriesForWrite(scope?: string): ScopedRepository[] {
+    return this.repositoriesForRead(scope);
+  }
+
+  repositoryFor(scope: Scope): TrapRepository {
+    const entry = this.repositoryEntry(scope);
+    if (!entry) {
+      throw new Error("Not in a project. Run 'codetrap init' first, or use --scope global.");
+    }
+    return entry.repository;
+  }
+
+  repositoryEntry(scope: Scope): ScopedRepository | null {
+    if (scope === "project") {
+      return this.context.project_root ? { scope, repository: this.projectRepo() } : null;
+    }
+    return { scope, repository: this.globalRepo() };
+  }
+
+  private projectRepo(): TrapRepository {
+    const projectRoot = this.context.project_root;
+    if (!projectRoot) {
+      throw new Error("Not in a project. Run 'codetrap init' first, or use --scope global.");
+    }
+    if (!this.projectRepository) {
+      this.projectRepository = new TrapRepository(openProject(projectRoot), this.embedder);
+    }
+    return this.projectRepository;
+  }
+
+  private globalRepo(): TrapRepository {
+    if (!this.globalRepository) {
+      this.globalRepository = new TrapRepository(openGlobal(), this.embedder);
+    }
+    return this.globalRepository;
+  }
+}
+
+export function normalizeScope(scope: string): Scope {
+  if (scope === "project" || scope === "global") return scope;
+  throw new Error(`Invalid scope: ${scope}`);
+}
+
+export function optionalScope(scope?: string): Scope | null {
+  if (!scope) return null;
+  return normalizeScope(scope);
+}
+
+export function storeForScopeContext<T extends { forCwd(cwd: string): T }>(store: T, cwd?: unknown): T {
+  if (typeof cwd === "string" && cwd.trim() !== "") {
+    return store.forCwd(cwd);
+  }
+  return store;
+}

package/src/lib/scope-migration.ts

@@ -0,0 +1,360 @@
+import { Database } from "bun:sqlite";
+import { existsSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { openDatabase } from "../db/connection";
+import { TrapRepository } from "../db/repository";
+import type { TrapExportRecord } from "../domain/trap";
+import { CODETRAP_DIR, TRAPS_DB_FILE } from "./constants";
+import { findProjectRoot } from "./scope";
+import {
+  deleteTransferredSourceTraps,
+  importProjectTrapTransfer,
+  type TrapTransferMapping,
+} from "./trap-transfer";
+
+export type ScopeMigrationCommand = "repair-scope" | "migrate-project";
+export type ScopeMigrationMode = "dry-run" | "apply";
+
+export type ScopeMigrationCandidate = {
+  id: number;
+  title: string;
+  category: string;
+  severity: string;
+  status: string;
+  project_path: string | null;
+};
+
+export type ScopeMigrationCounts = {
+  source_before: number;
+  source_after: number;
+  destination_before: number;
+  destination_after: number;
+  candidates: number;
+  moved: number;
+};
+
+export type ScopeMigrationBackups = {
+  source_db: string | null;
+  destination_db: string | null;
+};
+
+export type ScopeMigrationResult = {
+  command: ScopeMigrationCommand;
+  mode: ScopeMigrationMode;
+  from_project_path: string;
+  to_project_path: string;
+  source_db: string;
+  destination_db: string;
+  source_db_exists: boolean;
+  destination_db_exists: boolean;
+  candidates: ScopeMigrationCandidate[];
+  moved: TrapTransferMapping[];
+  backups: ScopeMigrationBackups;
+  counts: ScopeMigrationCounts;
+  next_action: { command: string } | null;
+};
+
+export type ScopeMigrationOptions = {
+  command: ScopeMigrationCommand;
+  cwd?: string;
+  fromProjectPath?: string;
+  toProjectPath?: string;
+  apply?: boolean;
+};
+
+type ResolvedScopeMigration = {
+  command: ScopeMigrationCommand;
+  mode: ScopeMigrationMode;
+  apply: boolean;
+  fromProjectPath: string;
+  toProjectPath: string;
+  sourceDb: string;
+  destinationDb: string;
+};
+
+type ScopeMigrationPlan = ResolvedScopeMigration & {
+  sourceDbExists: boolean;
+  destinationDbExists: boolean;
+  records: TrapExportRecord[];
+  sourceBefore: number;
+  destinationBefore: number;
+};
+
+type ScopeMigrationApplyResult = {
+  moved: TrapTransferMapping[];
+  backups: ScopeMigrationBackups;
+  sourceAfter: number;
+  destinationAfter: number;
+};
+
+export function runScopeMigration(options: ScopeMigrationOptions): ScopeMigrationResult {
+  const plan = buildScopeMigrationPlan(options);
+
+  if (!plan.apply || plan.records.length === 0) {
+    return buildScopeMigrationResult(plan, {
+      moved: [],
+      backups: { source_db: null, destination_db: null },
+      sourceAfter: plan.sourceBefore,
+      destinationAfter: plan.destinationBefore,
+    });
+  }
+
+  return buildScopeMigrationResult(plan, applyScopeMigrationPlan(plan));
+}
+
+export function formatScopeMigrationText(result: ScopeMigrationResult): string {
+  const lines = [
+    `${result.command} ${result.mode}`,
+    `from_project_path: ${result.from_project_path}`,
+    `to_project_path: ${result.to_project_path}`,
+    `source_db: ${result.source_db}${result.source_db_exists ? "" : " (missing)"}`,
+    `destination_db: ${result.destination_db}${result.destination_db_exists ? "" : " (missing)"}`,
+    `candidates: ${result.counts.candidates}`,
+  ];
+
+  if (result.candidates.length > 0) {
+    lines.push("candidate traps:");
+    lines.push(...result.candidates.map((trap) =>
+      `  #${trap.id} [${trap.severity}] [${trap.category}] [${trap.status}] ${trap.title}`
+    ));
+  }
+
+  if (result.mode === "apply") {
+    lines.push(`moved: ${result.counts.moved}`);
+    if (result.backups.source_db || result.backups.destination_db) {
+      lines.push("backups:");
+      if (result.backups.source_db) lines.push(`  source_db: ${result.backups.source_db}`);
+      if (result.backups.destination_db) lines.push(`  destination_db: ${result.backups.destination_db}`);
+    }
+    if (result.moved.length > 0) {
+      lines.push("id mapping:");
+      lines.push(...result.moved.map((item) =>
+        `  #${item.source_id} -> #${item.destination_id} ${item.title}`
+      ));
+    }
+  }
+
+  lines.push(
+    `source_count: ${result.counts.source_before} -> ${result.counts.source_after}`,
+    `destination_count: ${result.counts.destination_before} -> ${result.counts.destination_after}`
+  );
+
+  if (result.next_action) {
+    lines.push(`Next: ${result.next_action.command}`);
+  }
+  if (result.candidates.length === 0) {
+    lines.push("No matching project traps found.");
+  }
+  return lines.join("\n");
+}
+
+function buildScopeMigrationPlan(options: ScopeMigrationOptions): ScopeMigrationPlan {
+  const resolved = resolveScopeMigrationOptions(options);
+  validateMigrationPaths(resolved);
+  const sourceDbExists = existsSync(resolved.sourceDb);
+  const destinationDbExists = existsSync(resolved.destinationDb);
+  const records = sourceDbExists
+    ? withReadOnlyRepository(resolved.sourceDb, (repository) =>
+        repository.exportProjectTrapsByPath(resolved.fromProjectPath)
+      )
+    : [];
+  const destinationBefore = destinationDbExists
+    ? withReadOnlyRepository(resolved.destinationDb, (repository) =>
+        repository.countProjectTrapsByPath(resolved.toProjectPath)
+      )
+    : 0;
+
+  return {
+    ...resolved,
+    sourceDbExists,
+    destinationDbExists,
+    records,
+    sourceBefore: records.length,
+    destinationBefore,
+  };
+}
+
+function applyScopeMigrationPlan(plan: ScopeMigrationPlan): ScopeMigrationApplyResult {
+  const backups = {
+    source_db: backupDatabase(plan.sourceDb, "source"),
+    destination_db: plan.destinationDbExists ? backupDatabase(plan.destinationDb, "destination") : null,
+  };
+
+  const applyResult = applyScopeMigration(
+    plan.sourceDb,
+    plan.destinationDb,
+    plan.fromProjectPath,
+    plan.toProjectPath
+  );
+
+  return {
+    moved: applyResult.moved,
+    backups,
+    sourceAfter: applyResult.sourceAfter,
+    destinationAfter: applyResult.destinationAfter,
+  };
+}
+
+function resolveScopeMigrationOptions(options: ScopeMigrationOptions): ResolvedScopeMigration {
+  const cwd = resolve(options.cwd ?? process.cwd());
+  const projectRoot = findProjectRoot(cwd);
+  const fromProjectPath = resolve(options.fromProjectPath ?? homedir());
+  const rawToProjectPath = options.toProjectPath ?? projectRoot;
+
+  if (!rawToProjectPath) {
+    throw new Error("Destination project not found. Run 'codetrap init' first, or pass --to-project-path.");
+  }
+  const toProjectPath = resolve(rawToProjectPath);
+
+  return {
+    command: options.command,
+    mode: options.apply ? "apply" : "dry-run",
+    apply: options.apply === true,
+    fromProjectPath,
+    toProjectPath,
+    sourceDb: projectDbPath(fromProjectPath),
+    destinationDb: projectDbPath(toProjectPath),
+  };
+}
+
+function validateMigrationPaths(input: {
+  command: ScopeMigrationCommand;
+  fromProjectPath: string;
+  toProjectPath: string;
+  sourceDb: string;
+  destinationDb: string;
+}): void {
+  if (input.command === "migrate-project" && input.fromProjectPath === input.toProjectPath) {
+    throw new Error("--from-project-path and --to-project-path must be different.");
+  }
+  if (canonicalPath(input.sourceDb) === canonicalPath(input.destinationDb)) {
+    throw new Error("Source and destination database paths are the same.");
+  }
+  if (!existsSync(join(input.toProjectPath, CODETRAP_DIR))) {
+    throw new Error(`Destination project is not initialized: ${input.toProjectPath}. Run 'codetrap init' first.`);
+  }
+}
+
+function applyScopeMigration(
+  sourceDbPath: string,
+  destinationDbPath: string,
+  fromProjectPath: string,
+  toProjectPath: string
+): { moved: TrapTransferMapping[]; sourceAfter: number; destinationAfter: number } {
+  const sourceDb = openDatabase(sourceDbPath);
+  const destinationDb = openDatabase(destinationDbPath);
+  try {
+    const sourceRepository = new TrapRepository(sourceDb);
+    const destinationRepository = new TrapRepository(destinationDb);
+    const records = sourceRepository.exportProjectTrapsByPath(fromProjectPath);
+    const moved = importProjectTrapTransfer(destinationRepository, records, toProjectPath);
+    const deleted = deleteTransferredSourceTraps(sourceRepository, records);
+    if (deleted !== records.length) {
+      throw new Error(`Expected to delete ${records.length} source traps, deleted ${deleted}.`);
+    }
+
+    return {
+      moved,
+      sourceAfter: sourceRepository.countProjectTrapsByPath(fromProjectPath),
+      destinationAfter: destinationRepository.countProjectTrapsByPath(toProjectPath),
+    };
+  } finally {
+    sourceDb.close();
+    destinationDb.close();
+  }
+}
+
+function buildScopeMigrationResult(
+  plan: ScopeMigrationPlan,
+  applied: ScopeMigrationApplyResult
+): ScopeMigrationResult {
+  const candidates = plan.records.map(toCandidate);
+  return {
+    command: plan.command,
+    mode: plan.mode,
+    from_project_path: plan.fromProjectPath,
+    to_project_path: plan.toProjectPath,
+    source_db: plan.sourceDb,
+    destination_db: plan.destinationDb,
+    source_db_exists: plan.sourceDbExists,
+    destination_db_exists: plan.destinationDbExists,
+    candidates,
+    moved: applied.moved,
+    backups: applied.backups,
+    counts: {
+      source_before: plan.sourceBefore,
+      source_after: applied.sourceAfter,
+      destination_before: plan.destinationBefore,
+      destination_after: applied.destinationAfter,
+      candidates: candidates.length,
+      moved: applied.moved.length,
+    },
+    next_action: plan.mode === "dry-run" && candidates.length > 0
+      ? { command: buildApplyCommand(plan.command, plan.fromProjectPath, plan.toProjectPath) }
+      : null,
+  };
+}
+
+function toCandidate(record: TrapExportRecord): ScopeMigrationCandidate {
+  return {
+    id: record.id,
+    title: record.title,
+    category: record.category,
+    severity: record.severity,
+    status: record.status,
+    project_path: record.project_path,
+  };
+}
+
+function withReadOnlyRepository<T>(dbPath: string, callback: (repository: TrapRepository) => T): T {
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    return callback(new TrapRepository(db));
+  } finally {
+    db.close();
+  }
+}
+
+function backupDatabase(dbPath: string, label: string): string {
+  const backupDir = join(dirname(dbPath), "backups");
+  mkdirSync(backupDir, { recursive: true });
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const backupPath = join(backupDir, `${basename(dbPath)}.${label}.${timestamp}.backup`);
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    writeFileSync(backupPath, db.serialize());
+  } finally {
+    db.close();
+  }
+  return backupPath;
+}
+
+function buildApplyCommand(
+  command: ScopeMigrationCommand,
+  fromProjectPath: string,
+  toProjectPath: string
+): string {
+  return [
+    "codetrap",
+    command,
+    "--from-project-path",
+    shellQuote(fromProjectPath),
+    "--to-project-path",
+    shellQuote(toProjectPath),
+    "--apply",
+    "--json",
+  ].join(" ");
+}
+
+function projectDbPath(projectPath: string): string {
+  return join(projectPath, CODETRAP_DIR, TRAPS_DB_FILE);
+}
+
+function canonicalPath(path: string): string {
+  return existsSync(path) ? realpathSync(path) : path;
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}

package/src/lib/search-normalizer.ts

@@ -18,6 +18,9 @@ export type SearchTextFields = {
   tags?: string | string[];
   before_code?: string | null;
   after_code?: string | null;
+  path_globs?: string | string[] | null;
+  module?: string | null;
+  owner?: string | null;
 };
 
 export const SEARCH_TEXT_FIELD_NAMES = [
@@ -28,6 +31,9 @@ export const SEARCH_TEXT_FIELD_NAMES = [
   "tags",
   "before_code",
   "after_code",
+  "path_globs",
+  "module",
+  "owner",
 ] as const;
 
 export function bigramCJK(input: string): string[] {