@thoughtflow/codebase 0.2.0

package/src/tools/workspace/search-code.tool.ts

@@ -0,0 +1,344 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+import {
+  CodebaseIndex,
+  CodebaseSearchHit,
+  CodebaseSearchMode,
+  CodebaseSymbolKind,
+} from "../../libs/codebase-index.class";
+
+type SearchOutputField =
+  | "path"
+  | "line"
+  | "column"
+  | "snippet"
+  | "symbol"
+  | "kind"
+  | "source"
+  | "score";
+
+const FIELD_VALUES = [
+  "path",
+  "line",
+  "column",
+  "snippet",
+  "symbol",
+  "kind",
+  "source",
+  "score",
+] as const;
+
+const MODE_VALUES = ["hybrid", "content", "path", "symbol"] as const;
+const SYMBOL_KIND_VALUES = [
+  "class",
+  "function",
+  "method",
+  "interface",
+  "type",
+  "enum",
+  "const",
+  "variable",
+] as const;
+
+const schema = z.object({
+  query: z
+    .string()
+    .optional()
+    .describe("Search query. Required for content/symbol search."),
+  mode: z
+    .enum(MODE_VALUES)
+    .optional()
+    .describe("Search mode: hybrid (default), content, path, symbol."),
+  pathPrefix: z
+    .string()
+    .optional()
+    .describe("Restrict search to files under this relative path prefix."),
+  glob: z
+    .string()
+    .optional()
+    .describe("Include glob pattern (e.g. '**/*.ts')."),
+  include: z
+    .array(z.string())
+    .optional()
+    .describe("Additional include globs. Applied with glob."),
+  exclude: z
+    .array(z.string())
+    .optional()
+    .describe("Exclude globs (e.g. ['**/*.test.ts', 'tmp/**'])."),
+  ext: z
+    .union([z.string(), z.array(z.string())])
+    .optional()
+    .describe("Extension filter like '.ts' or ['.ts','.md']"),
+  symbolKinds: z
+    .array(z.enum(SYMBOL_KIND_VALUES))
+    .optional()
+    .describe("Filter symbols by kind in symbol/hybrid mode."),
+  regex: z
+    .boolean()
+    .optional()
+    .describe("Treat query as regex."),
+  caseSensitive: z
+    .boolean()
+    .optional()
+    .describe("Case-sensitive search (default false)."),
+  includeHidden: z
+    .boolean()
+    .optional()
+    .describe("Include dotfiles and hidden directories."),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(200)
+    .optional()
+    .describe("Max hits to return (default 20, max 200)."),
+  offset: z
+    .number()
+    .int()
+    .min(0)
+    .max(10000)
+    .optional()
+    .describe("Pagination offset."),
+  fields: z
+    .array(z.enum(FIELD_VALUES))
+    .optional()
+    .describe("Output fields. Default is minimal per mode."),
+  format: z
+    .enum(["compact", "json"])
+    .optional()
+    .describe("Output format: compact (default) or json."),
+  includeStats: z
+    .boolean()
+    .optional()
+    .describe("Include index stats in output."),
+  reindex: z
+    .boolean()
+    .optional()
+    .describe("Force rebuild of in-memory SQLite index before searching."),
+  maxFileBytes: z
+    .number()
+    .int()
+    .min(1024)
+    .max(10 * 1024 * 1024)
+    .optional()
+    .describe("Max file size indexed during reindex (default 1MB)."),
+  maxSnippetChars: z
+    .number()
+    .int()
+    .min(40)
+    .max(500)
+    .optional()
+    .describe("Max snippet length in content results."),
+});
+
+export class SearchCodeTool extends ToolBase {
+  readonly name: string = "search_code";
+  override readonly readonly = true;
+  readonly description =
+    "LLM-friendly codebase search over an in-memory SQLite index. " +
+    "Supports content/path/symbol modes, filtering, concise field selection, and compact/json outputs.";
+
+  constructor(private readonly rootDir: string) {
+    super(schema);
+  }
+
+  async run(input: Record<string, unknown>, _ctx: ToolContext): Promise<ToolExecutionResult> {
+    const {
+      query,
+      mode = "hybrid",
+      pathPrefix,
+      glob,
+      include,
+      exclude,
+      ext,
+      symbolKinds,
+      regex = false,
+      caseSensitive = false,
+      includeHidden = false,
+      limit = 20,
+      offset = 0,
+      fields,
+      format = "compact",
+      includeStats = false,
+      reindex = false,
+      maxFileBytes = 1024 * 1024,
+      maxSnippetChars = 220,
+    } = input as {
+      query?: string;
+      mode?: CodebaseSearchMode;
+      pathPrefix?: string;
+      glob?: string;
+      include?: string[];
+      exclude?: string[];
+      ext?: string | string[];
+      symbolKinds?: CodebaseSymbolKind[];
+      regex?: boolean;
+      caseSensitive?: boolean;
+      includeHidden?: boolean;
+      limit?: number;
+      offset?: number;
+      fields?: SearchOutputField[];
+      format?: "compact" | "json";
+      includeStats?: boolean;
+      reindex?: boolean;
+      maxFileBytes?: number;
+      maxSnippetChars?: number;
+    };
+
+    const includeGlobs = [glob, ...(include ?? [])].filter((v): v is string => Boolean(v && v.trim()));
+    const extensions = normalizeExts(ext);
+
+    const searchMode = mode as CodebaseSearchMode;
+    const queryTrimmed = (query ?? "").trim();
+
+    if (!queryTrimmed && searchMode !== "path" && !pathPrefix && includeGlobs.length === 0) {
+      return {
+        success: false,
+        error: "Provide 'query' (or use path mode with pathPrefix/glob filters).",
+      };
+    }
+
+    const index = await CodebaseIndex.forRoot(this.rootDir);
+
+    if (!index.isIndexed() || reindex) {
+      index.rebuild(maxFileBytes);
+    }
+
+    let hits: CodebaseSearchHit[];
+    try {
+      hits = index.search({
+        query: queryTrimmed || undefined,
+        mode: searchMode,
+        pathPrefix: normalizePathPrefix(pathPrefix),
+        extensions,
+        includeGlobs,
+        excludeGlobs: exclude,
+        includeHidden,
+        limit,
+        offset,
+        regex,
+        caseSensitive,
+        symbolKinds,
+        maxSnippetChars,
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        success: false,
+        error: `search_code failed: ${message}`,
+      };
+    }
+
+    const selectedFields = (fields && fields.length > 0)
+      ? fields
+      : defaultFieldsForMode(searchMode);
+
+    const stats = includeStats ? index.getStats() : undefined;
+
+    if (format === "json") {
+      const payload: Record<string, unknown> = {
+        count: hits.length,
+        hits: hits.map((hit) => pickFields(hit, selectedFields)),
+      };
+      if (stats) payload["stats"] = stats;
+      return { success: true, output: JSON.stringify(payload) };
+    }
+
+    if (hits.length === 0) {
+      const statsLine = stats
+        ? `\nstats files=${stats.fileCount} symbols=${stats.symbolCount} fts=${stats.hasFts ? 1 : 0}`
+        : "";
+      return { success: true, output: `No files matched${statsLine}` };
+    }
+
+    const lines = hits.map((hit) => formatCompact(hit, selectedFields));
+    const statsLine = stats
+      ? `\nstats files=${stats.fileCount} symbols=${stats.symbolCount} fts=${stats.hasFts ? 1 : 0}`
+      : "";
+
+    return {
+      success: true,
+      output: `${hits.length} hits\n${lines.join("\n")}${statsLine}`,
+    };
+  }
+}
+
+/** Alias with a name matching "codebase" conventions used by prompts/runners. */
+export class SearchCodebaseTool extends SearchCodeTool {
+  readonly name = "search_codebase";
+}
+
+function normalizeExts(ext: string | string[] | undefined): string[] | undefined {
+  if (!ext) return undefined;
+  const raw = Array.isArray(ext) ? ext : [ext];
+  const cleaned = raw
+    .map((item) => item.trim().toLowerCase())
+    .filter(Boolean)
+    .map((item) => (item.startsWith(".") ? item : `.${item}`));
+  return cleaned.length > 0 ? Array.from(new Set(cleaned)) : undefined;
+}
+
+function normalizePathPrefix(pathPrefix?: string): string | undefined {
+  if (!pathPrefix) return undefined;
+  const trimmed = pathPrefix.trim().replace(/^\.\//, "");
+  return trimmed === "." || trimmed === "" ? undefined : trimmed;
+}
+
+function defaultFieldsForMode(mode: CodebaseSearchMode): SearchOutputField[] {
+  if (mode === "symbol") return ["path", "line", "symbol", "kind"];
+  if (mode === "path") return ["path", "source", "score"];
+  return ["path", "line", "snippet", "source"];
+}
+
+function pickFields(hit: CodebaseSearchHit, fields: SearchOutputField[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const field of fields) {
+    if (field === "path") out[field] = hit.path;
+    if (field === "line") out[field] = hit.line;
+    if (field === "column") out[field] = hit.column;
+    if (field === "snippet") out[field] = hit.snippet;
+    if (field === "symbol") out[field] = hit.symbol;
+    if (field === "kind") out[field] = hit.kind;
+    if (field === "source") out[field] = hit.source;
+    if (field === "score") out[field] = hit.score;
+  }
+  return out;
+}
+
+function formatCompact(hit: CodebaseSearchHit, fields: SearchOutputField[]): string {
+  const parts: string[] = [];
+  for (const field of fields) {
+    if (field === "path") {
+      parts.push(hit.path);
+      continue;
+    }
+    if (field === "line" && typeof hit.line === "number") {
+      parts.push(`line=${hit.line}`);
+      continue;
+    }
+    if (field === "column" && typeof hit.column === "number") {
+      parts.push(`col=${hit.column}`);
+      continue;
+    }
+    if (field === "snippet" && hit.snippet) {
+      parts.push(`snippet=${hit.snippet}`);
+      continue;
+    }
+    if (field === "symbol" && hit.symbol) {
+      parts.push(`symbol=${hit.symbol}`);
+      continue;
+    }
+    if (field === "kind" && hit.kind) {
+      parts.push(`kind=${hit.kind}`);
+      continue;
+    }
+    if (field === "source") {
+      parts.push(`src=${hit.source}`);
+      continue;
+    }
+    if (field === "score") {
+      parts.push(`score=${hit.score}`);
+    }
+  }
+  return parts.join(" | ");
+}

package/tsconfig.build.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "node_modules"]
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../core/tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "node_modules"]
+}