@wrongstack/tools 0.9.20 → 0.10.0

package/dist/codebase-index/index.d.ts

@@ -6,13 +6,33 @@ import '@wrongstack/core';
  * SQLite storage layer for the codebase index.
  *
  * Uses `node:sqlite` (synchronous API — DatabaseSync class).
- * Database file: {projectRoot}/.codebase-index/index.db
+ * Database file: ~/.wrongstack/projects/<hash>/codebase-index/index.db — kept
+ * out of the repo so it never clutters the working tree or needs gitignoring.
  */
 
+/**
+ * Resolve the per-project index directory. By default it lives under the
+ * global project dir (`~/.wrongstack/projects/<hash>/codebase-index`),
+ * matching every other piece of per-project state. Callers may pass an
+ * explicit `override` (used by tests and any wiring that already resolved the
+ * path) to avoid touching the real home directory.
+ */
+declare function resolveIndexDir(projectRoot: string, override?: string): string;
+/**
+ * Optional index-directory override carried on the run context's `meta` bag.
+ * Production leaves it unset (the index resolves to the global per-project
+ * dir); tests and bespoke wiring set `meta.codebaseIndexDir` to redirect it.
+ */
+declare function codebaseIndexDirOverride(ctx: {
+    meta?: Record<string, unknown>;
+}): string | undefined;
 declare class IndexStore {
-    private projectRoot;
     private db;
-    constructor(projectRoot: string);
+    /** Absolute path to this project's index directory. */
+    private readonly indexDir;
+    constructor(projectRoot: string, opts?: {
+        indexDir?: string;
+    });
     private initSchema;
     insertSymbols(symbols: Symbol[], nextId: number): number;
     deleteSymbolsForFile(file: string): void;
@@ -117,4 +137,4 @@ declare function lspKindToInternalKind(k: number): SymbolKind | null;
  */
 declare function internalKindToLspKind(k: SymbolKind): number | null;
 
-export { FileMeta, IndexStats, IndexStore, SearchResult, Symbol, SymbolKind, SymbolLang, buildBm25Index, buildIndexableText, internalKindToLspKind, lspKindToInternalKind, tokenise };
+export { FileMeta, IndexStats, IndexStore, SearchResult, Symbol, SymbolKind, SymbolLang, buildBm25Index, buildIndexableText, codebaseIndexDirOverride, internalKindToLspKind, lspKindToInternalKind, resolveIndexDir, tokenise };

package/dist/codebase-index/index.js

@@ -1,6 +1,6 @@
 import * as fs2 from 'node:fs/promises';
 import * as path4 from 'node:path';
-import { compileGlob } from '@wrongstack/core';
+import { resolveWstackPaths, compileGlob } from '@wrongstack/core';
 import { createRequire } from 'node:module';
 import * as fs from 'node:fs';
 import { mkdirSync, writeFileSync } from 'node:fs';
@@ -81,8 +81,14 @@ function internalKindToLspKind(k) {
 }
 
 // src/codebase-index/writer.ts
-var INDEX_DIR = ".codebase-index";
 var DB_FILE = "index.db";
+function resolveIndexDir(projectRoot, override) {
+  return override ?? resolveWstackPaths({ projectRoot }).projectCodebaseIndex;
+}
+function codebaseIndexDirOverride(ctx) {
+  const v = ctx.meta?.["codebaseIndexDir"];
+  return typeof v === "string" ? v : void 0;
+}
 var warningSilenced = false;
 function silenceSqliteExperimentalWarning() {
   if (warningSilenced) return;
@@ -110,16 +116,16 @@ function loadDatabaseSync() {
   return DatabaseSyncCtor;
 }
 var IndexStore = class {
-  constructor(projectRoot) {
-    this.projectRoot = projectRoot;
-    const dir = path4.join(projectRoot, INDEX_DIR);
-    fs.mkdirSync(dir, { recursive: true });
+  db;
+  /** Absolute path to this project's index directory. */
+  indexDir;
+  constructor(projectRoot, opts = {}) {
+    this.indexDir = resolveIndexDir(projectRoot, opts.indexDir);
+    fs.mkdirSync(this.indexDir, { recursive: true });
     const Database = loadDatabaseSync();
-    this.db = new Database(path4.join(dir, DB_FILE));
+    this.db = new Database(path4.join(this.indexDir, DB_FILE));
     this.initSchema();
   }
-  projectRoot;
-  db;
   initSchema() {
     this.db.exec(`
       CREATE TABLE IF NOT EXISTS metadata (
@@ -310,7 +316,7 @@ var IndexStore = class {
       totalFiles,
       byLang,
       byKind,
-      indexPath: path4.join(this.projectRoot, INDEX_DIR),
+      indexPath: this.indexDir,
       lastIndexed,
       sizeBytes,
       version: SCHEMA_VERSION
@@ -403,7 +409,7 @@ var IndexStore = class {
     }));
   }
   sizeBytes() {
-    const dbPath = path4.join(this.projectRoot, INDEX_DIR, DB_FILE);
+    const dbPath = path4.join(this.indexDir, DB_FILE);
     try {
       return fs.statSync(dbPath).size;
     } catch {
@@ -1679,8 +1685,8 @@ async function parseFile(file, content, lang) {
   }
 }
 async function runIndexer(_ctx, opts) {
-  const { projectRoot, force = false, langs, ignore = [] } = opts;
-  const store = new IndexStore(projectRoot);
+  const { projectRoot, force = false, langs, ignore = [], indexDir } = opts;
+  const store = new IndexStore(projectRoot, { indexDir });
   const startMs = Date.now();
   const errors = [];
   const langStats = {};
@@ -1797,8 +1803,8 @@ async function runIndexer(_ctx, opts) {
 var codebaseIndexTool = {
   name: "codebase-index",
   category: "Project",
-  description: "Build or update the symbol index for the project. Runs incrementally by default \u2014 only re-indexes files that changed since the last run.",
-  usageHint: "Call with `force: true` to wipe and rebuild the index from scratch. Use `langs` to limit to specific languages. First call without arguments to do an incremental index.",
+  description: "Build or incrementally update the project-wide symbol index. This powers fast codebase search and understanding. By default it only processes files that have changed since the last indexing run.",
+  usageHint: "IMPORTANT FOR LARGE CODEBASES:\n\n- First run (or after major changes): consider `force: true` for a clean rebuild.\n- Normal usage: call without arguments for fast incremental updates.\n- Use `langs` to restrict to specific languages if you only care about certain parts of the project.\nThis tool is relatively expensive \u2014 do not call it on every turn. Use it when the index is stale or before heavy codebase-search sessions.",
   permission: "auto",
   mutating: true,
   timeoutMs: 12e4,
@@ -1820,7 +1826,8 @@ var codebaseIndexTool = {
     const result = await runIndexer(ctx, {
       projectRoot: ctx.projectRoot,
       force: input.force ?? false,
-      langs: input.langs
+      langs: input.langs,
+      indexDir: codebaseIndexDirOverride(ctx)
     });
     return result;
   }
@@ -1918,10 +1925,11 @@ var Bm25Index = class {
 var codebaseSearchTool = {
   name: "codebase-search",
   category: "Project",
-  description: "Search indexed code symbols by name, signature, or doc comment. Uses BM25 ranking for relevance.",
-  usageHint: "Pass `query` for keyword search. Filter with `kind` (class/function/interface/etc), `lang` (ts/js/etc), `file` (substring). `limit` caps results (default 20).",
+  description: "Semantic/keyword search over the indexed codebase symbols (functions, classes, interfaces, etc.). Uses BM25 ranking. Much more powerful and structured than raw `grep` for finding code by name or concept.",
+  usageHint: "PREFERRED FOR CODE UNDERSTANDING:\n\n- Use when you need to find where something is defined or used by name.\n- `kind` filter is very useful (e.g. only functions or only interfaces).\n- Combine with `file` filter to scope to a specific directory or module.\nThis is generally better than `grep` when you are looking for symbols rather than arbitrary text patterns.",
   permission: "auto",
   mutating: false,
+  capabilities: ["fs.read"],
   timeoutMs: 1e4,
   inputSchema: {
     type: "object",
@@ -1956,7 +1964,7 @@ var codebaseSearchTool = {
     required: ["query"]
   },
   async execute(input, ctx) {
-    const store = new IndexStore(ctx.projectRoot);
+    const store = new IndexStore(ctx.projectRoot, { indexDir: codebaseIndexDirOverride(ctx) });
     try {
       const limit = Math.min(input.limit ?? 20, 100);
       const candidates = store.search(input.query, {
@@ -2001,10 +2009,11 @@ var codebaseSearchTool = {
 var codebaseStatsTool = {
   name: "codebase-stats",
   category: "Project",
-  description: "Return statistics about the symbol index: total symbols, files, breakdown by language and kind, index size, and last update time.",
-  usageHint: "No arguments needed. Use to check if the index is stale or healthy before running a search.",
+  description: "Return health and statistics about the current symbol index (total symbols, files, language/kind breakdown, size, last update). Useful to decide whether to re-index.",
+  usageHint: "CALL BEFORE HEAVY CODEBASE-SEARCH WORK:\n\n- Use to see if the index is up-to-date or needs a refresh.\n- No arguments required.\n- Helps avoid wasting tokens on searches against a stale index.\nLightweight and safe to call frequently.",
   permission: "auto",
   mutating: false,
+  capabilities: ["fs.read"],
   timeoutMs: 5e3,
   inputSchema: {
     type: "object",
@@ -2012,7 +2021,7 @@ var codebaseStatsTool = {
     additionalProperties: false
   },
   async execute(_input, ctx) {
-    const store = new IndexStore(ctx.projectRoot);
+    const store = new IndexStore(ctx.projectRoot, { indexDir: codebaseIndexDirOverride(ctx) });
     try {
       const stats = store.getStats();
       return {
@@ -2031,6 +2040,6 @@ var codebaseStatsTool = {
   }
 };
 
-export { IndexStore, SCHEMA_VERSION, buildBm25Index, buildIndexableText, codebaseIndexTool, codebaseSearchTool, codebaseStatsTool, internalKindToLspKind, lspKindToInternalKind, tokenise };
+export { IndexStore, SCHEMA_VERSION, buildBm25Index, buildIndexableText, codebaseIndexDirOverride, codebaseIndexTool, codebaseSearchTool, codebaseStatsTool, internalKindToLspKind, lspKindToInternalKind, resolveIndexDir, tokenise };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map