Stream-count large files & detect ambiguous DB paths

- search-ql-code: use streaming (readline) for totalMatches counting on
  large files in the early-exit path; eliminates TOCTOU race from prior
  lstatSync check
- cli-tool-registry: resolveDatabasePath now collects all candidate
  children and throws on ambiguity instead of silently picking the first
- Add tests for cross-file totalMatches accuracy under truncation, single-
  child DB auto-resolve, and multi-child DB ambiguity error

Author: data-douser

client/integration-tests/primitives/tools/profile_codeql_query_from_logs/multi_query_raw_log/after/query-evaluation-detail.txt

@@ -1,5 +1,4 @@
 # CodeQL Evaluator Profile — Predicate Detail
-# Generated: 2026-03-10T18:36:19.438Z
 # Log format: raw
 # CodeQL version: 2.23.1
 # Use read_file with line ranges from the JSON response to access individual predicates.

client/integration-tests/primitives/tools/profile_codeql_query_from_logs/single_query_raw_log/after/query-evaluation-detail.txt

@@ -1,5 +1,4 @@
 # CodeQL Evaluator Profile — Predicate Detail
-# Generated: 2026-03-10T18:36:19.453Z
 # Log format: raw
 # CodeQL version: 2.23.1
 # Use read_file with line ranges from the JSON response to access individual predicates.

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

@@ -57013,17 +57013,30 @@ function resolveDatabasePath(dbPath) {
   }
   try {
     const entries = readdirSync2(dbPath);
+    const candidates = [];
     for (const entry of entries) {
       const candidate = join6(dbPath, entry);
       try {
         if (statSync2(candidate).isDirectory() && existsSync4(join6(candidate, "codeql-database.yml"))) {
-          logger.info(`Resolved multi-language database directory: ${dbPath} -> ${candidate}`);
-          return candidate;
+          candidates.push(candidate);
         }
       } catch {
       }
     }
-  } catch {
+    if (candidates.length === 1) {
+      logger.info(`Resolved database directory: ${dbPath} -> ${candidates[0]}`);
+      return candidates[0];
+    }
+    if (candidates.length > 1) {
+      const names = candidates.map((c) => basename2(c)).join(", ");
+      throw new Error(
+        `Ambiguous database path: ${dbPath} contains multiple databases (${names}). Specify the full path to the desired database subfolder.`
+      );
+    }
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith("Ambiguous database path")) {
+      throw err;
+    }
   }
   return dbPath;
 }
@@ -63058,9 +63071,21 @@ async function searchQlCode(params) {
   for (const file of filesToSearch) {
     if (collectedEnough) {
       try {
-        const content = readFileSync9(file, "utf-8");
-        for (const line of content.replace(/\r\n/g, "\n").split("\n")) {
-          if (regex.test(line)) totalMatches++;
+        const st = lstatSync(file);
+        if (!st.isFile()) continue;
+        if (st.size > MAX_FILE_SIZE_BYTES) {
+          const rl = createInterface3({
+            input: createReadStream3(file, { encoding: "utf-8" }),
+            crlfDelay: Infinity
+          });
+          for await (const line of rl) {
+            if (regex.test(line)) totalMatches++;
+          }
+        } else {
+          const content = readFileSync9(file, "utf-8");
+          for (const line of content.replace(/\r\n/g, "\n").split("\n")) {
+            if (regex.test(line)) totalMatches++;
+          }
         }
       } catch {
       }

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

@@ -18,29 +18,47 @@ export type { CLIExecutionResult } from './cli-executor';
 /**
  * Resolve a database path that may point to a multi-language database root
  * (i.e. a directory that does not contain `codeql-database.yml` itself but
- * has a single language subfolder that does). This handles the common case
- * where vscode-codeql stores databases in a parent directory with language
+ * has a language subfolder that does). This handles the common case where
+ * vscode-codeql stores databases in a parent directory with language
  * subfolders like `javascript/`, `python/`, etc.
+ *
+ * When multiple candidate children are found, throws an error describing
+ * the ambiguity so the caller can pick the right one explicitly.
  */
 function resolveDatabasePath(dbPath: string): string {
   if (existsSync(join(dbPath, 'codeql-database.yml'))) {
     return dbPath;
   }
   try {
     const entries = readdirSync(dbPath);
+    const candidates: string[] = [];
     for (const entry of entries) {
       const candidate = join(dbPath, entry);
       try {
         if (statSync(candidate).isDirectory() &&
             existsSync(join(candidate, 'codeql-database.yml'))) {
-          logger.info(`Resolved multi-language database directory: ${dbPath} -> ${candidate}`);
-          return candidate;
+          candidates.push(candidate);
         }
       } catch {
         // Skip inaccessible entries
       }
     }
-  } catch {
+    if (candidates.length === 1) {
+      logger.info(`Resolved database directory: ${dbPath} -> ${candidates[0]}`);
+      return candidates[0];
+    }
+    if (candidates.length > 1) {
+      const names = candidates.map((c) => basename(c)).join(', ');
+      throw new Error(
+        `Ambiguous database path: ${dbPath} contains multiple databases (${names}). ` +
+        'Specify the full path to the desired database subfolder.'
+      );
+    }
+  } catch (err) {
+    // Re-throw ambiguity errors
+    if (err instanceof Error && err.message.startsWith('Ambiguous database path')) {
+      throw err;
+    }
     // Parent directory not readable — return original path
   }
   return dbPath;

server/src/lib/cli-tool-registry.ts

@@ -293,11 +293,25 @@ export async function searchQlCode(params: {
   for (const file of filesToSearch) {
     if (collectedEnough) {
       // Still need totalMatches count but skip storing results.
-      // Read directly and catch errors to avoid TOCTOU race.
+      // Use streaming for large files to avoid loading into memory.
       try {
-        const content = readFileSync(file, 'utf-8');
-        for (const line of content.replace(/\r\n/g, '\n').split('\n')) {
-          if (regex.test(line)) totalMatches++;
+        const st = lstatSync(file);
+        if (!st.isFile()) continue;
+        if (st.size > MAX_FILE_SIZE_BYTES) {
+          // Stream large files line-by-line for counting
+          const rl = createInterface({
+            input: createReadStream(file, { encoding: 'utf-8' }),
+            crlfDelay: Infinity
+          });
+          for await (const line of rl) {
+            if (regex.test(line)) totalMatches++;
+          }
+        } else {
+          // Small files: read directly (fast path)
+          const content = readFileSync(file, 'utf-8');
+          for (const line of content.replace(/\r\n/g, '\n').split('\n')) {
+            if (regex.test(line)) totalMatches++;
+          }
         }
       } catch {
         // skip unreadable files

server/src/tools/codeql/search-ql-code.ts

@@ -3,18 +3,21 @@
  */
 
 import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { mkdirSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
 import { z } from 'zod';
-import { 
-  registerCLITool, 
-  defaultCLIResultProcessor, 
+import {
+  registerCLITool,
+  defaultCLIResultProcessor,
   createCodeQLSchemas,
   createQLTSchemas,
   createBQRSResultProcessor,
   createDatabaseResultProcessor,
   CLIToolDefinition
 } from '../../../src/lib/cli-tool-registry';
 import { CLIExecutionResult } from '../../../src/lib/cli-executor';
+import { createTestTempDir } from '../../utils/temp-dir';
 
 // Mock the CLI executor
 vi.mock('../../../src/lib/cli-executor', () => ({
@@ -335,6 +338,76 @@ describe('registerCLITool handler behavior', () => {
     );
   });
 
+  it('should auto-resolve single-child database directory for codeql_resolve_database', async () => {
+    // Create a parent directory with one database subdirectory
+    const parentDir = createTestTempDir('db-resolve-single-');
+    const dbDir = join(parentDir, 'javascript');
+    mkdirSync(dbDir, { recursive: true });
+    writeFileSync(join(dbDir, 'codeql-database.yml'), 'primaryLanguage: javascript\n');
+
+    const definition: CLIToolDefinition = {
+      name: 'codeql_resolve_database',
+      description: 'Resolve database',
+      command: 'codeql',
+      subcommand: 'resolve database',
+      inputSchema: { database: z.string() }
+    };
+
+    registerCLITool(mockServer, definition);
+    const handler = (mockServer.tool as ReturnType<typeof vi.fn>).mock.calls[0][3];
+
+    executeCodeQLCommand.mockResolvedValueOnce({
+      stdout: '{"languages": ["javascript"]}',
+      stderr: '',
+      success: true
+    });
+
+    await handler({ database: parentDir });
+
+    // Should resolve to the child directory
+    expect(executeCodeQLCommand).toHaveBeenCalledWith(
+      'resolve database',
+      expect.any(Object),
+      [dbDir],
+      undefined
+    );
+
+    // Cleanup
+    rmSync(parentDir, { recursive: true, force: true });
+  });
+
+  it('should error on ambiguous multi-database directory for codeql_resolve_database', async () => {
+    // Create a parent directory with two database subdirectories
+    const parentDir = createTestTempDir('db-resolve-ambiguous-');
+    for (const lang of ['javascript', 'python']) {
+      const dbDir = join(parentDir, lang);
+      mkdirSync(dbDir, { recursive: true });
+      writeFileSync(join(dbDir, 'codeql-database.yml'), `primaryLanguage: ${lang}\n`);
+    }
+
+    const definition: CLIToolDefinition = {
+      name: 'codeql_resolve_database',
+      description: 'Resolve database',
+      command: 'codeql',
+      subcommand: 'resolve database',
+      inputSchema: { database: z.string() }
+    };
+
+    registerCLITool(mockServer, definition);
+    const handler = (mockServer.tool as ReturnType<typeof vi.fn>).mock.calls[0][3];
+
+    const result = await handler({ database: parentDir });
+
+    // Should return an error about ambiguous databases
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('Ambiguous database path');
+    expect(result.content[0].text).toContain('javascript');
+    expect(result.content[0].text).toContain('python');
+
+    // Cleanup
+    rmSync(parentDir, { recursive: true, force: true });
+  });
+
   it('should handle database parameter as positional argument for codeql_database_create', async () => {
     const definition: CLIToolDefinition = {
       name: 'codeql_database_create',

server/test/src/lib/cli-tool-registry.test.ts

@@ -174,6 +174,26 @@ describe('searchQlCode', () => {
       expect(result.results).toHaveLength(5);
     });
 
+    it('should report accurate totalMatches across files when truncated', async () => {
+      tempDir = createTestTempDir('search-ql-code');
+      // Create 5 files, each with 4 matches = 20 total matches
+      for (let i = 0; i < 5; i++) {
+        const lines = Array.from({ length: 4 }, (_, j) => `match_${i}_${j}`).join('\n');
+        writeFileSync(join(tempDir, `File${i}.qll`), lines);
+      }
+
+      const result = await searchQlCode({
+        pattern: 'match_',
+        paths: [tempDir],
+        maxResults: 3
+      });
+
+      expect(result.returnedMatches).toBe(3);
+      expect(result.totalMatches).toBe(20);
+      expect(result.truncated).toBe(true);
+      expect(result.filesSearched).toBe(5);
+    });
+
     it('should not set truncated when within limit', async () => {
       const dir = setupTestFiles({
         'Test.qll': 'match1\nmatch2\nmatch3\n'