Address second round of PR #169 review comments

- Bound metadataCache to 256 entries with oldest-first eviction
- Make SqliteStore.initialize() idempotent (close existing db first)
- Fix TOCTOU in initialize(): try readFileSync directly instead of existsSync
- Atomic flush: write to temp file + renameSync to prevent corruption
- Clarify annotation_search uses substring LIKE matching, not FTS
- Close store in monitoring-tools test afterEach to prevent timer leaks

Author: data-douser

server/dist/codeql-development-mcp-server.js

@@ -184863,6 +184863,7 @@ var BUILT_IN_EVALUATORS = {
   "csv-decode": "CSV format decoder for query results",
   "mermaid-graph": "Mermaid diagram generator for @kind graph queries (like PrintAST)"
 };
+var METADATA_CACHE_MAX = 256;
 var metadataCache = /* @__PURE__ */ new Map();
 async function extractQueryMetadata(queryPath) {
   try {
@@ -184886,6 +184887,10 @@ async function extractQueryMetadata(queryPath) {
     if (tagsMatch) {
       metadata.tags = tagsMatch[1].split(/\s+/).filter((t) => t.length > 0);
     }
+    if (metadataCache.size >= METADATA_CACHE_MAX) {
+      const firstKey = metadataCache.keys().next().value;
+      if (firstKey !== void 0) metadataCache.delete(firstKey);
+    }
     metadataCache.set(queryPath, { mtime, metadata });
     return metadata;
   } catch (error2) {
@@ -185129,7 +185134,7 @@ import { randomUUID as randomUUID2 } from "crypto";
 // src/lib/sqlite-store.ts
 var import_sql_asm = __toESM(require_sql_asm(), 1);
 init_logger();
-import { existsSync as existsSync6, mkdirSync as mkdirSync5, readFileSync as readFileSync5, writeFileSync as writeFileSync2 } from "fs";
+import { mkdirSync as mkdirSync5, readFileSync as readFileSync5, renameSync, writeFileSync as writeFileSync2 } from "fs";
 import { join as join8 } from "path";
 var SqliteStore = class _SqliteStore {
   db = null;
@@ -185145,19 +185150,18 @@ var SqliteStore = class _SqliteStore {
   }
   /**
    * Initialize the database. Must be called (and awaited) before any other method.
+   * Safe to call more than once — an already-open database is closed first.
    */
   async initialize() {
+    if (this.db) {
+      this.close();
+    }
     mkdirSync5(this.storageDir, { recursive: true });
     const SQL = await (0, import_sql_asm.default)();
-    if (existsSync6(this.dbPath)) {
-      try {
-        const fileBuffer = readFileSync5(this.dbPath);
-        this.db = new SQL.Database(fileBuffer);
-      } catch {
-        logger.warn("Failed to read existing database, creating new one");
-        this.db = new SQL.Database();
-      }
-    } else {
+    try {
+      const fileBuffer = readFileSync5(this.dbPath);
+      this.db = new SQL.Database(fileBuffer);
+    } catch {
       this.db = new SQL.Database();
     }
     this.createSchema();
@@ -185256,6 +185260,9 @@ var SqliteStore = class _SqliteStore {
   }
   /**
    * Write the in-memory database to disk.
+   *
+   * Uses write-to-temp + atomic rename so a crash mid-write cannot
+   * corrupt the database file.
    */
   flush() {
     if (this.flushTimer) {
@@ -185265,7 +185272,9 @@ var SqliteStore = class _SqliteStore {
     if (!this.db) return;
     const data = this.db.export();
     const buffer = Buffer.from(data);
-    writeFileSync2(this.dbPath, buffer);
+    const tmpPath = this.dbPath + ".tmp";
+    writeFileSync2(tmpPath, buffer);
+    renameSync(tmpPath, this.dbPath);
     this.dirty = false;
   }
   /**
@@ -186391,7 +186400,7 @@ Warning: Query processing error - ${error2}`
 // src/lib/cli-tool-registry.ts
 init_package_paths();
 init_temp_dir();
-import { writeFileSync as writeFileSync4, rmSync, existsSync as existsSync7, mkdirSync as mkdirSync8 } from "fs";
+import { writeFileSync as writeFileSync4, rmSync, existsSync as existsSync6, mkdirSync as mkdirSync8 } from "fs";
 import { dirname as dirname5, isAbsolute as isAbsolute4, join as join10, resolve as resolve4 } from "path";
 var defaultCLIResultProcessor = (result, _params) => {
   if (!result.success) {
@@ -186718,7 +186727,7 @@ function registerCLITool(server, definition) {
             cwd = isAbsolute4(rawCwd) ? rawCwd : resolve4(getUserWorkspaceDir(), rawCwd);
           }
           const defaultExamplesPath = resolve4(packageRootDir, "ql", "javascript", "examples");
-          const additionalPacksPath = process.env.CODEQL_ADDITIONAL_PACKS || (existsSync7(defaultExamplesPath) ? defaultExamplesPath : void 0);
+          const additionalPacksPath = process.env.CODEQL_ADDITIONAL_PACKS || (existsSync6(defaultExamplesPath) ? defaultExamplesPath : void 0);
           if (additionalPacksPath && (name === "codeql_test_run" || name === "codeql_query_run" || name === "codeql_query_compile" || name === "codeql_database_analyze")) {
             options["additional-packs"] = additionalPacksPath;
           }
@@ -186739,7 +186748,7 @@ function registerCLITool(server, definition) {
         }
         if ((name === "codeql_query_run" || name === "codeql_database_analyze") && result.success && queryLogDir) {
           const evalLogPath = options["evaluator-log"];
-          if (evalLogPath && existsSync7(evalLogPath)) {
+          if (evalLogPath && existsSync6(evalLogPath)) {
             try {
               const summaryPath = evalLogPath.replace(/\.jsonl$/, ".summary.jsonl");
               const summaryResult = await executeCodeQLCommand(
@@ -190045,7 +190054,7 @@ var codeqlGenerateQueryHelpTool = {
 };
 
 // src/tools/codeql/list-databases.ts
-import { existsSync as existsSync9, readdirSync as readdirSync4, readFileSync as readFileSync8, statSync as statSync4 } from "fs";
+import { existsSync as existsSync8, readdirSync as readdirSync4, readFileSync as readFileSync8, statSync as statSync4 } from "fs";
 import { join as join12 } from "path";
 
 // src/lib/discovery-config.ts
@@ -190098,7 +190107,7 @@ function parseDatabaseYml(ymlPath) {
 async function discoverDatabases(baseDirs, language) {
   const databases = [];
   for (const baseDir of baseDirs) {
-    if (!existsSync9(baseDir)) {
+    if (!existsSync8(baseDir)) {
       continue;
     }
     let entries;
@@ -190117,7 +190126,7 @@ async function discoverDatabases(baseDirs, language) {
         continue;
       }
       const ymlPath = join12(entryPath, "codeql-database.yml");
-      if (!existsSync9(ymlPath)) {
+      if (!existsSync8(ymlPath)) {
         continue;
       }
       const metadata = parseDatabaseYml(ymlPath);
@@ -190199,15 +190208,15 @@ function registerListDatabasesTool(server) {
 }
 
 // src/tools/codeql/list-mrva-run-results.ts
-import { existsSync as existsSync10, readdirSync as readdirSync5, readFileSync as readFileSync9, statSync as statSync5 } from "fs";
+import { existsSync as existsSync9, readdirSync as readdirSync5, readFileSync as readFileSync9, statSync as statSync5 } from "fs";
 import { join as join13 } from "path";
 init_logger();
 var NUMERIC_DIR_PATTERN = /^\d+$/;
 var SKIP_DIRS = /* @__PURE__ */ new Set([".DS_Store", "exported-results"]);
 async function discoverMrvaRunResults(resultsDirs, runId) {
   const results = [];
   for (const dir of resultsDirs) {
-    if (!existsSync10(dir)) {
+    if (!existsSync9(dir)) {
       continue;
     }
     let entries;
@@ -190233,7 +190242,7 @@ async function discoverMrvaRunResults(resultsDirs, runId) {
       }
       let timestamp2;
       const timestampPath = join13(entryPath, "timestamp");
-      if (existsSync10(timestampPath)) {
+      if (existsSync9(timestampPath)) {
         try {
           timestamp2 = readFileSync9(timestampPath, "utf-8").trim();
         } catch {
@@ -190289,7 +190298,7 @@ function discoverRepoResults(runPath) {
       let analysisStatus;
       let resultCount;
       const repoTaskPath = join13(repoPath, "repo_task.json");
-      if (existsSync10(repoTaskPath)) {
+      if (existsSync9(repoTaskPath)) {
         try {
           const raw = readFileSync9(repoTaskPath, "utf-8");
           const task = JSON.parse(raw);
@@ -190302,8 +190311,8 @@ function discoverRepoResults(runPath) {
         } catch {
         }
       }
-      const hasSarif = existsSync10(join13(repoPath, "results", "results.sarif"));
-      const hasBqrs = existsSync10(join13(repoPath, "results", "results.bqrs"));
+      const hasSarif = existsSync9(join13(repoPath, "results", "results.sarif"));
+      const hasBqrs = existsSync9(join13(repoPath, "results", "results.bqrs"));
       repos.push({
         analysisStatus,
         fullName,
@@ -190386,7 +190395,7 @@ function registerListMrvaRunResultsTool(server) {
 }
 
 // src/tools/codeql/list-query-run-results.ts
-import { existsSync as existsSync11, readdirSync as readdirSync6, readFileSync as readFileSync10, statSync as statSync6 } from "fs";
+import { existsSync as existsSync10, readdirSync as readdirSync6, readFileSync as readFileSync10, statSync as statSync6 } from "fs";
 import { join as join14 } from "path";
 init_logger();
 var QUERY_RUN_DIR_PATTERN = /^(.+\.ql)-(.+)$/;
@@ -190423,7 +190432,7 @@ async function discoverQueryRunResults(resultsDirs, filter) {
   const normalizedFilter = typeof filter === "string" ? { queryName: filter } : filter;
   const results = [];
   for (const dir of resultsDirs) {
-    if (!existsSync11(dir)) {
+    if (!existsSync10(dir)) {
       continue;
     }
     let entries;
@@ -190449,14 +190458,14 @@ async function discoverQueryRunResults(resultsDirs, filter) {
       if (normalizedFilter?.queryName && name !== normalizedFilter.queryName) {
         continue;
       }
-      const hasEvaluatorLog = existsSync11(join14(entryPath, "evaluator-log.jsonl"));
-      const hasBqrs = existsSync11(join14(entryPath, "results.bqrs"));
-      const hasSarif = existsSync11(join14(entryPath, "results-interpreted.sarif"));
-      const hasQueryLog = existsSync11(join14(entryPath, "query.log"));
-      const hasSummaryLog = existsSync11(join14(entryPath, "evaluator-log.summary.jsonl"));
+      const hasEvaluatorLog = existsSync10(join14(entryPath, "evaluator-log.jsonl"));
+      const hasBqrs = existsSync10(join14(entryPath, "results.bqrs"));
+      const hasSarif = existsSync10(join14(entryPath, "results-interpreted.sarif"));
+      const hasQueryLog = existsSync10(join14(entryPath, "query.log"));
+      const hasSummaryLog = existsSync10(join14(entryPath, "evaluator-log.summary.jsonl"));
       let timestamp2;
       const timestampPath = join14(entryPath, "timestamp");
-      if (existsSync11(timestampPath)) {
+      if (existsSync10(timestampPath)) {
         try {
           timestamp2 = readFileSync10(timestampPath, "utf-8").trim();
         } catch {
@@ -190638,7 +190647,7 @@ var codeqlPackLsTool = {
 };
 
 // src/tools/codeql/profile-codeql-query-from-logs.ts
-import { existsSync as existsSync12, mkdirSync as mkdirSync9, writeFileSync as writeFileSync5 } from "fs";
+import { existsSync as existsSync11, mkdirSync as mkdirSync9, writeFileSync as writeFileSync5 } from "fs";
 import { basename as basename6, dirname as dirname7, join as join15 } from "path";
 
 // src/lib/evaluator-log-parser.ts
@@ -191075,7 +191084,7 @@ function registerProfileCodeQLQueryFromLogsTool(server) {
       try {
         const { evaluatorLog, outputDir, topN } = params;
         const effectiveTopN = topN ?? 20;
-        if (!existsSync12(evaluatorLog)) {
+        if (!existsSync11(evaluatorLog)) {
           return {
             content: [
               {
@@ -191128,7 +191137,7 @@ function registerProfileCodeQLQueryFromLogsTool(server) {
 // src/tools/codeql/profile-codeql-query.ts
 init_cli_executor();
 init_logger();
-import { writeFileSync as writeFileSync6, existsSync as existsSync13 } from "fs";
+import { writeFileSync as writeFileSync6, existsSync as existsSync12 } from "fs";
 import { createReadStream as createReadStream2 } from "fs";
 import { join as join16, dirname as dirname8, basename as basename7 } from "path";
 import { mkdirSync as mkdirSync10 } from "fs";
@@ -191331,7 +191340,7 @@ function registerProfileCodeQLQueryTool(server) {
               isError: true
             };
           }
-          if (existsSync13(bqrsPath)) {
+          if (existsSync12(bqrsPath)) {
             try {
               const sarifResult = await executeCodeQLCommand(
                 "bqrs interpret",
@@ -191346,7 +191355,7 @@ function registerProfileCodeQLQueryTool(server) {
             }
           }
         }
-        if (!existsSync13(logPath)) {
+        if (!existsSync12(logPath)) {
           return {
             content: [
               {
@@ -191377,7 +191386,7 @@ function registerProfileCodeQLQueryTool(server) {
         if (bqrsPath) {
           outputFiles.push(`Query Results (BQRS): ${bqrsPath}`);
         }
-        if (sarifPath && existsSync13(sarifPath)) {
+        if (sarifPath && existsSync12(sarifPath)) {
           outputFiles.push(`Query Results (SARIF): ${sarifPath}`);
         }
         const responseText = [
@@ -191575,7 +191584,7 @@ function registerQuickEvaluateTool(server) {
 
 // src/tools/codeql/read-database-source.ts
 var import_adm_zip = __toESM(require_adm_zip(), 1);
-import { existsSync as existsSync14, readdirSync as readdirSync7, readFileSync as readFileSync11, statSync as statSync7 } from "fs";
+import { existsSync as existsSync13, readdirSync as readdirSync7, readFileSync as readFileSync11, statSync as statSync7 } from "fs";
 import { join as join18, resolve as resolve7 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 init_logger();
@@ -191657,13 +191666,13 @@ function applyLineRange(content, startLine, endLine) {
 async function readDatabaseSource(params) {
   const { databasePath, endLine, filePath, maxEntries, prefix, startLine } = params;
   const resolvedDbPath = resolve7(databasePath);
-  if (!existsSync14(resolvedDbPath)) {
+  if (!existsSync13(resolvedDbPath)) {
     throw new Error(`Database path does not exist: ${databasePath}`);
   }
   const srcZipPath = join18(resolvedDbPath, "src.zip");
   const srcDirPath = join18(resolvedDbPath, "src");
-  const hasSrcZip = existsSync14(srcZipPath);
-  const hasSrcDir = existsSync14(srcDirPath);
+  const hasSrcZip = existsSync13(srcZipPath);
+  const hasSrcDir = existsSync13(srcDirPath);
   if (!hasSrcZip && !hasSrcDir) {
     throw new Error(
       `No source archive found in database: expected src.zip or src/ in ${databasePath}`
@@ -195346,9 +195355,9 @@ function registerAnnotationDeleteTool(server) {
 function registerAnnotationSearchTool(server) {
   server.tool(
     "annotation_search",
-    "Full-text search across annotation content, metadata, and labels.",
+    "Substring search across annotation content, metadata, and labels (case-insensitive SQL LIKE matching).",
     {
-      query: external_exports.string().describe("Search term (matched against content, metadata, and label)."),
+      query: external_exports.string().describe("Search term \u2014 matched as a substring against content, metadata, and label."),
       category: external_exports.string().optional().describe("Restrict search to a specific category."),
       limit: external_exports.number().optional().describe("Maximum number of results (default: 50).")
     },

server/dist/codeql-development-mcp-server.js.map

@@ -37,7 +37,10 @@ export type BuiltInEvaluator = keyof typeof BUILT_IN_EVALUATORS;
 /**
  * In-memory cache for extracted query metadata, keyed by file path.
  * Stores the file modification time to invalidate when the file changes.
+ * Bounded to {@link METADATA_CACHE_MAX} entries; oldest entries are evicted
+ * when the limit is reached (Map iteration order = insertion order).
  */
+const METADATA_CACHE_MAX = 256;
 const metadataCache = new Map<string, { mtime: number; metadata: QueryMetadata }>();
 
 /**
@@ -75,6 +78,11 @@ export async function extractQueryMetadata(queryPath: string): Promise<QueryMeta
       metadata.tags = tagsMatch[1].split(/\s+/).filter(t => t.length > 0);
     }
 
+    // Evict oldest entries when the cache exceeds the size limit.
+    if (metadataCache.size >= METADATA_CACHE_MAX) {
+      const firstKey = metadataCache.keys().next().value;
+      if (firstKey !== undefined) metadataCache.delete(firstKey);
+    }
     metadataCache.set(queryPath, { mtime, metadata });
     return metadata;
   } catch (error) {

server/src/lib/query-results-evaluator.ts

@@ -13,7 +13,7 @@
 
 import initSqlJs from 'sql.js/dist/sql-asm.js';
 import type { Database as SqlJsDatabase } from 'sql.js';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { logger } from '../utils/logger';
 
@@ -65,21 +65,22 @@ export class SqliteStore {
 
   /**
    * Initialize the database. Must be called (and awaited) before any other method.
+   * Safe to call more than once — an already-open database is closed first.
    */
   async initialize(): Promise<void> {
+    if (this.db) {
+      this.close();
+    }
+
     mkdirSync(this.storageDir, { recursive: true });
 
     const SQL = await initSqlJs();
 
-    if (existsSync(this.dbPath)) {
-      try {
-        const fileBuffer = readFileSync(this.dbPath);
-        this.db = new SQL.Database(fileBuffer);
-      } catch {
-        logger.warn('Failed to read existing database, creating new one');
-        this.db = new SQL.Database();
-      }
-    } else {
+    try {
+      const fileBuffer = readFileSync(this.dbPath);
+      this.db = new SQL.Database(fileBuffer);
+    } catch {
+      // File doesn't exist or is unreadable — start with a fresh database.
       this.db = new SQL.Database();
     }
 
@@ -194,6 +195,9 @@ export class SqliteStore {
 
   /**
    * Write the in-memory database to disk.
+   *
+   * Uses write-to-temp + atomic rename so a crash mid-write cannot
+   * corrupt the database file.
    */
   flush(): void {
     if (this.flushTimer) {
@@ -203,7 +207,9 @@ export class SqliteStore {
     if (!this.db) return;
     const data = this.db.export();
     const buffer = Buffer.from(data);
-    writeFileSync(this.dbPath, buffer);
+    const tmpPath = this.dbPath + '.tmp';
+    writeFileSync(tmpPath, buffer);
+    renameSync(tmpPath, this.dbPath);
     this.dirty = false;
   }