@codragraph/cli 2.1.4 → 2.1.6

package/dist/core/search/bm25-index.d.ts

@@ -15,18 +15,26 @@ export interface BM25SearchResult {
     score: number;
     rank: number;
     nodeIds?: string[];
+    /** False when results came from the bounded fallback scan instead of FTS. */
+    ftsUsed?: boolean;
 }
 /**
- * Drop all ensured-FTS cache entries for a given repoId.
+ * FTS table set served by `searchFTSFromCgdb`. Centralised so that both
+ * the CLI/pipeline path and the MCP pool path stay in lockstep.
  *
- * Called from the pool-close listener so that a pool teardown / recreation
- * forces the next `searchFTSFromCgdb` call to re-issue `CREATE_FTS_INDEX`
- * against the fresh connection rather than trust stale ensure-state from a
- * previous pool lifetime.
- *
- * Exported for tests; the listener wiring is internal.
+ * The properties list is computed at FTS-create time via `ftsPropertiesFor`
+ * — for repos that were analysed with `--compress brotli|zstd`, the
+ * `content` column holds base64-of-encoded-bytes and would tokenise to
+ * useless tokens. Those repos get name-only FTS so search at least
+ * matches function/class names instead of returning random hits on
+ * base64 alphabet. Plain (compress='none' / unset) repos get the full
+ * `name + content` index for body-text matches. RFC 0001 Phase 2.5.
  */
-export declare function invalidateEnsuredFTSForRepo(repoId: string): void;
+export declare const FTS_TABLES: ReadonlyArray<{
+    table: string;
+    indexName: string;
+}>;
+export declare const ftsPropertiesFor: (compress: "none" | "brotli" | "zstd" | undefined) => readonly string[];
 /**
  * Search using LadybugDB's built-in FTS (always fresh, reads from disk)
  *

package/dist/core/search/bm25-index.js

@@ -23,22 +23,21 @@ import { queryFTS, ensureFTSIndex, executeQuery as executeCoreQuery, } from '../
  * base64 alphabet. Plain (compress='none' / unset) repos get the full
  * `name + content` index for body-text matches. RFC 0001 Phase 2.5.
  */
-const FTS_TABLES = [
+export const FTS_TABLES = [
     { table: 'File', indexName: 'file_fts' },
     { table: 'Function', indexName: 'function_fts' },
     { table: 'Class', indexName: 'class_fts' },
     { table: 'Method', indexName: 'method_fts' },
     { table: 'Interface', indexName: 'interface_fts' },
 ];
-const ftsPropertiesFor = (compress) => !compress || compress === 'none' ? ['name', 'content'] : ['name'];
+export const ftsPropertiesFor = (compress) => (!compress || compress === 'none' ? ['name', 'content'] : ['name']);
 /**
- * Look up `meta.compress` for a repo. The MCP path passes `repoId`
- * (registry-derived); the CLI path passes nothing and we walk up from
- * cwd. Returns `'none'` whenever the lookup fails so the safe default
- * (full FTS index) is used — the failure mode is reduced search
- * quality, never wrong results.
+ * Look up query-related index metadata for a repo. The MCP path passes `repoId`
+ * (registry-derived); the CLI/core path passes nothing and we walk up from
+ * cwd. Read-only callers use `ftsReady` to avoid expensive probes for
+ * FTS indexes that older analyses never wrote.
  */
-async function getCompressMode(repoId) {
+async function getSearchMeta(repoId) {
     try {
         const repoMod = await import('../../storage/repo-manager.js');
         if (repoId) {
@@ -50,16 +49,22 @@ async function getCompressMode(repoId) {
                 const base = entry.name.toLowerCase();
                 if (base === repoId || repoId.startsWith(`${base}-`)) {
                     const meta = await repoMod.loadMeta(entry.storagePath);
-                    return meta?.compress ?? 'none';
+                    return {
+                        compress: meta?.compress ?? 'none',
+                        ftsReady: meta?.searchIndexes?.fts === true,
+                    };
                 }
             }
-            return 'none';
+            return { compress: 'none', ftsReady: false };
         }
         const repo = await repoMod.findRepo(process.cwd());
-        return repo?.meta?.compress ?? 'none';
+        return {
+            compress: repo?.meta?.compress ?? 'none',
+            ftsReady: repo?.meta?.searchIndexes?.fts,
+        };
     }
     catch {
-        return 'none';
+        return { compress: 'none', ftsReady: repoId ? false : undefined };
     }
 }
 const FALLBACK_SCAN_LIMIT = 50_000;
@@ -69,76 +74,6 @@ const FALLBACK_FIELD_WEIGHTS = {
     content: 2,
     description: 1,
 };
-/**
- * Per-process cache for the MCP pool path: tracks which `(repoId, table)`
- * pairs have been ensured. The CLI/pipeline path gets its own cache inside
- * `cgdb-adapter.ts` keyed by table/index, scoped to the singleton connection.
- *
- * IMPORTANT: an entry is added ONLY when the index was confirmed to exist
- * (CREATE_FTS_INDEX succeeded, or failed with `'already exists'`). Other
- * failures (transient lock errors, missing extension, etc.) leave the key
- * unset so the next query retries instead of silently caching the failure.
- *
- * Entries for a given repoId are invalidated when its pool is closed —
- * see the `addPoolCloseListener` registration in `searchFTSFromCgdb`.
- */
-const ensuredPoolFTS = new Set();
-/**
- * Drop all ensured-FTS cache entries for a given repoId.
- *
- * Called from the pool-close listener so that a pool teardown / recreation
- * forces the next `searchFTSFromCgdb` call to re-issue `CREATE_FTS_INDEX`
- * against the fresh connection rather than trust stale ensure-state from a
- * previous pool lifetime.
- *
- * Exported for tests; the listener wiring is internal.
- */
-export function invalidateEnsuredFTSForRepo(repoId) {
-    const prefix = `${repoId}:`;
-    for (const key of ensuredPoolFTS) {
-        if (key.startsWith(prefix))
-            ensuredPoolFTS.delete(key);
-    }
-}
-/**
- * Tracks whether we've already wired the pool-close listener for this
- * process. The pool adapter is dynamically imported, so registration
- * happens lazily on the first MCP-pool-backed FTS query.
- */
-let poolCloseListenerRegistered = false;
-function registerPoolCloseListenerOnce(addPoolCloseListener) {
-    if (poolCloseListenerRegistered)
-        return;
-    poolCloseListenerRegistered = true;
-    addPoolCloseListener((repoId) => invalidateEnsuredFTSForRepo(repoId));
-}
-async function ensureFTSIndexViaExecutor(executor, repoId, table, indexName, properties) {
-    const key = `${repoId}:${table}:${indexName}`;
-    if (ensuredPoolFTS.has(key))
-        return;
-    const propList = properties.map((p) => `'${p}'`).join(', ');
-    try {
-        await executor(`CALL CREATE_FTS_INDEX('${table}', '${indexName}', [${propList}], stemmer := 'porter')`);
-        // Index was created successfully — safe to cache.
-        ensuredPoolFTS.add(key);
-    }
-    catch (e) {
-        // 'already exists' is the happy path (index persists on disk between
-        // process invocations) — cache it. Anything else is treated as a
-        // transient failure: surface a one-time warning and leave the key
-        // unset so the NEXT query retries rather than silently using a
-        // cached failure (which previously disabled BM25 for the whole
-        // process for that repo).
-        const msg = String(e?.message ?? '');
-        if (msg.includes('already exists')) {
-            ensuredPoolFTS.add(key);
-        }
-        else {
-            console.warn(`[codragraph] FTS index ensure failed for repo "${repoId}" table "${table}" ` +
-                `(index "${indexName}"): ${msg || e}. Will retry on next query.`);
-        }
-    }
-}
 /**
  * Execute a single FTS query via a custom executor (for MCP connection pool).
  * Returns the same shape as core queryFTS (from LadybugDB adapter).
@@ -175,6 +110,22 @@ function searchTerms(query) {
         ?.filter((term) => term.length > 1 && !BOOLEAN_QUERY_TOKENS.has(term));
     return [...new Set(terms ?? [])];
 }
+function searchTermVariants(query) {
+    const rawTerms = query.match(/[\p{L}\p{N}_]+/gu) ?? [];
+    const variants = new Set();
+    for (const raw of rawTerms) {
+        const lower = raw.toLowerCase();
+        if (raw.length <= 1 || BOOLEAN_QUERY_TOKENS.has(lower))
+            continue;
+        variants.add(raw);
+        variants.add(lower);
+        variants.add(raw.charAt(0).toUpperCase() + raw.slice(1).toLowerCase());
+    }
+    return [...variants];
+}
+function cypherString(value) {
+    return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "''")}'`;
+}
 function scoreFallbackNode(node, query, properties) {
     const terms = searchTerms(query);
     if (terms.length === 0)
@@ -201,10 +152,15 @@ function scoreFallbackNode(node, query, properties) {
 }
 async function queryFallbackViaExecutor(executor, tableName, properties, query, limit) {
     try {
+        const variants = searchTermVariants(query);
+        const conditions = variants.flatMap((term) => properties.map((property) => `node.${property} CONTAINS ${cypherString(term)}`));
+        const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' OR ')}` : '';
+        const candidateLimit = Math.min(FALLBACK_SCAN_LIMIT, Math.max(limit * 25, 200));
         const rows = await executor(`
       MATCH (node:${tableName})
+      ${whereClause}
       RETURN node
-      LIMIT ${FALLBACK_SCAN_LIMIT}
+      LIMIT ${candidateLimit}
     `);
         return rows
             .map((row) => {
@@ -228,10 +184,7 @@ async function fallbackSearchAllTables(executor, query, limit,
 // pre-Phase-2 behaviour (`['name', 'content']`) for callers that don't
 // pass a value.
 properties = ['name', 'content']) {
-    const results = [];
-    for (const { table } of FTS_TABLES) {
-        results.push(await queryFallbackViaExecutor(executor, table, properties, query, limit));
-    }
+    const results = await Promise.all(FTS_TABLES.map(({ table }) => queryFallbackViaExecutor(executor, table, properties, query, limit)));
     return results;
 }
 /**
@@ -249,50 +202,56 @@ export const searchFTSFromCgdb = async (query, limit = 20, repoId) => {
     if (!query.trim() || limit <= 0)
         return [];
     let fileResults, functionResults, classResults, methodResults, interfaceResults;
+    let usedFallback = false;
     if (repoId) {
         // Use MCP connection pool via dynamic import
         // IMPORTANT: FTS queries run sequentially to avoid connection contention.
         // The MCP pool supports multiple connections, but FTS is best run serially.
         const poolMod = await import('../cgdb/pool-adapter.js');
-        const { executeQuery, addPoolCloseListener } = poolMod;
-        // Register the pool-close listener lazily on first use so a teardown of
-        // the pool entry (LRU eviction, idle timeout, explicit close) drops the
-        // matching `ensuredPoolFTS` entries. Without this, stale ensure-state
-        // can outlive the pool that produced it.
-        registerPoolCloseListenerOnce(addPoolCloseListener);
+        const { executeQuery } = poolMod;
         const executor = (cypher) => executeQuery(repoId, cypher);
-        // Lazy-create FTS indexes on first query for this repo (analyze no longer
-        // creates them up-front, so we ensure them here). Cached per-process.
-        // RFC 0001 Phase 2.5: drop `content` from FTS properties for repos
-        // analysed with --compress brotli|zstd — the column holds encoded
-        // bytes and would tokenise to garbage.
-        const compress = await getCompressMode(repoId);
-        const properties = ftsPropertiesFor(compress);
-        for (const { table, indexName } of FTS_TABLES) {
-            await ensureFTSIndexViaExecutor(executor, repoId, table, indexName, properties);
+        // The MCP/LocalBackend pool is opened read-only so it can safely coexist
+        // with `codragraph analyze`. Do not issue CREATE_FTS_INDEX here: when
+        // persisted FTS indexes are missing, meta.searchIndexes lets us skip
+        // QUERY_FTS_INDEX and go straight to the bounded fallback below.
+        // RFC 0001 Phase 2.5: drop `content` from fallback scoring for repos
+        // analysed with --compress brotli|zstd — the column holds encoded bytes.
+        const meta = await getSearchMeta(repoId);
+        const properties = ftsPropertiesFor(meta.compress);
+        if (meta.ftsReady) {
+            fileResults = await queryFTSViaExecutor(executor, 'File', 'file_fts', query, limit);
+            functionResults = await queryFTSViaExecutor(executor, 'Function', 'function_fts', query, limit);
+            classResults = await queryFTSViaExecutor(executor, 'Class', 'class_fts', query, limit);
+            methodResults = await queryFTSViaExecutor(executor, 'Method', 'method_fts', query, limit);
+            interfaceResults = await queryFTSViaExecutor(executor, 'Interface', 'interface_fts', query, limit);
+        }
+        else {
+            usedFallback = true;
+            fileResults = [];
+            functionResults = [];
+            classResults = [];
+            methodResults = [];
+            interfaceResults = [];
         }
-        fileResults = await queryFTSViaExecutor(executor, 'File', 'file_fts', query, limit);
-        functionResults = await queryFTSViaExecutor(executor, 'Function', 'function_fts', query, limit);
-        classResults = await queryFTSViaExecutor(executor, 'Class', 'class_fts', query, limit);
-        methodResults = await queryFTSViaExecutor(executor, 'Method', 'method_fts', query, limit);
-        interfaceResults = await queryFTSViaExecutor(executor, 'Interface', 'interface_fts', query, limit);
         if (fileResults.length +
             functionResults.length +
             classResults.length +
             methodResults.length +
             interfaceResults.length ===
             0) {
+            usedFallback = true;
             [fileResults, functionResults, classResults, methodResults, interfaceResults] =
                 await fallbackSearchAllTables(executor, query, limit, properties);
         }
     }
     else {
         // Use core cgdb adapter (CLI / pipeline context) — also sequential for safety.
-        // Lazy-create FTS indexes on first query (analyze no longer does it).
+        // Defensive fallback for older indexes or direct core callers: create FTS
+        // indexes on first query when this process owns a writable connection.
         // RFC 0001 Phase 2.5 — same `compress`-aware property selection as the MCP
         // path; the CLI walks up from cwd to find the repo's meta.json.
-        const compress = await getCompressMode();
-        const properties = ftsPropertiesFor(compress);
+        const meta = await getSearchMeta();
+        const properties = ftsPropertiesFor(meta.compress);
         for (const { table, indexName } of FTS_TABLES) {
             await ensureFTSIndex(table, indexName, [...properties]).catch(() => { });
         }
@@ -307,6 +266,7 @@ export const searchFTSFromCgdb = async (query, limit = 20, repoId) => {
             methodResults.length +
             interfaceResults.length ===
             0) {
+            usedFallback = true;
             [fileResults, functionResults, classResults, methodResults, interfaceResults] =
                 await fallbackSearchAllTables(executeCoreQuery, query, limit, properties);
         }
@@ -335,6 +295,7 @@ export const searchFTSFromCgdb = async (query, limit = 20, repoId) => {
             filePath,
             score: top3.reduce((acc, e) => acc + e.score, 0),
             nodeIds: top3.map((e) => e.nodeId).filter((id) => id),
+            ftsUsed: !usedFallback,
         });
     }
     // Sort by score descending and add rank
@@ -346,5 +307,6 @@ export const searchFTSFromCgdb = async (query, limit = 20, repoId) => {
         score: r.score,
         rank: index + 1,
         nodeIds: r.nodeIds,
+        ftsUsed: r.ftsUsed,
     }));
 };

package/dist/mcp/local/local-backend.d.ts

@@ -186,7 +186,9 @@ export declare class LocalBackend {
      */
     private semanticSearch;
     executeCypher(repoName: string, query: string): Promise<any>;
+    private trySimpleGraphstoreNodeScan;
     private cypher;
+    private executeLabellessNodeScan;
     /**
      * Format raw Cypher result rows as a markdown table for LLM readability.
      * Falls back to raw result if rows aren't tabular objects.