Skip to content

Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.

fix(mcp): apply search_graph label filter inside the BM25 candidate window (#2386)

harshitaajoshi19374f2d340d
diff --git a/src/mcp/mcp.c b/src/mcp/mcp.c
index 03741e23a..60cef5334 100644
--- a/src/mcp/mcp.c
+++ b/src/mcp/mcp.c
@@ -3969,6 +3969,7 @@ enum {
BM25_BIND_EXACT = 8,
BM25_BIND_KIND = 9,
BM25_BIND_NS = 10,
+ BM25_BIND_LABEL_WEIGHT = 11,
BM25_SQL_AUTO_LEN = -1,
/* Inner FTS5 candidate cap. SQLite can early-terminate a plain FTS5 query
* (no JOIN/WHERE on outer table) of the form:
@@ -3977,6 +3978,11 @@ enum {
* and then joining/filtering/re-ranking those, we bound all work to O(N) where
* N = BM25_INNER_LIMIT rather than the full match set size. */
BM25_INNER_LIMIT = 2000,
+ /* Longest label spliced into the MATCH pre-filter; real labels are short
+ * identifiers, so anything longer simply skips the pre-filter. */
+ BM25_LABEL_MAX = 64,
+ /* Room for "(<tokens>) AND label : \"<label>\"" around the token list. */
+ BM25_MATCH_BUF = BM25_QUERY_BUF + BM25_LABEL_MAX + 32,
};
/* Column weights for nodes_fts (name, qualified_name, label, file_path, body).
@@ -3995,8 +4001,15 @@ enum {
* Safe against a legacy four-column nodes_fts: FTS5's bm25() reads a weight
* only when an instance actually lands in that column (`nVal > ic`), so the
* fifth weight is simply never consulted on a table that has no fifth
- * column. */
-#define BM25_WEIGHTS "bm25(nodes_fts, 1.0, 1.0, 1.0, 1.0, 0.3)"
+ * column.
+ *
+ * The label weight is bound (?11): 1.0 normally, 0.0 when the MATCH is scoped
+ * to a label (#2386). Every candidate then carries that label, so a label hit
+ * cannot tell them apart, and a zero weight keeps the added `label : "..."`
+ * phrase from shifting BM25 order by row length. */
+#define BM25_WEIGHTS "bm25(nodes_fts, 1.0, 1.0, ?11, 1.0, 0.3)"
+static const double BM25_LABEL_WEIGHT = 1.0;
+static const double BM25_LABEL_WEIGHT_SCOPED = 0.0;
/* Module-local SQLITE_TRANSIENT wrapper to dodge performance-no-int-to-ptr.
* See the matching helper in src/store/store.c for the same pattern. */
@@ -4047,6 +4060,39 @@ static int bm25_build_match(const char *query, char *out, size_t out_size) {
return tokens;
}
+/* Scope an FTS5 MATCH expression to one node label (#2386). The label filter
+ * must choose the BM25_INNER_LIMIT candidate window, not trim it afterwards:
+ * otherwise a label that is rare among a common token's matches falls outside
+ * the window and the search returns 0 rows although matching nodes exist.
+ * FTS5 matching is case-insensitive, so this is a superset pre-filter; the
+ * caller keeps the exact `n.label = ?` check. Only a plain identifier is
+ * spliced in, as a quoted FTS5 string; any other label leaves `tokens`
+ * unscoped, which is the pre-#2386 behaviour. Returns the label-column weight
+ * to bind for the resulting MATCH. */
+static double bm25_scope_match_to_label(const char *tokens, const char *label, char *out,
+ size_t out_size) {
+ snprintf(out, out_size, "%s", tokens);
+ if (!label || !label[0]) {
+ return BM25_LABEL_WEIGHT;
+ }
+ size_t len = 0;
+ for (; label[len]; len++) {
+ char ch = label[len];
+ bool ident = (ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z') ||
+ (ch >= '0' && ch <= '9') || ch == '_';
+ if (!ident || len >= BM25_LABEL_MAX) {
+ return BM25_LABEL_WEIGHT;
+ }
+ }
+ char scoped[BM25_MATCH_BUF];
+ int n = snprintf(scoped, sizeof(scoped), "(%s) AND label : \"%s\"", tokens, label);
+ if (n <= 0 || (size_t)n >= sizeof(scoped) || (size_t)n >= out_size) {
+ return BM25_LABEL_WEIGHT;
+ }
+ memcpy(out, scoped, (size_t)n + 1);
+ return BM25_LABEL_WEIGHT_SCOPED;
+}
+
static char *bm25_file_pattern_like(const char *file_pattern) {
if (!file_pattern) {
return NULL;
@@ -4233,11 +4279,16 @@ static char *bm25_search(cbm_store_t *store, const char *project, const char *qu
if (!db) {
return NULL;
}
- char fts_query[BM25_QUERY_BUF];
- int tok_count = bm25_build_match(query, fts_query, sizeof(fts_query));
+ char fts_tokens[BM25_QUERY_BUF];
+ int tok_count = bm25_build_match(query, fts_tokens, sizeof(fts_tokens));
if (tok_count == 0) {
return NULL;
}
+ /* One MATCH string for the ranked query, the count and the saturation
+ * probe, so all three describe the same label-scoped window. */
+ char fts_query[BM25_MATCH_BUF];
+ double label_weight =
+ bm25_scope_match_to_label(fts_tokens, label, fts_query, sizeof(fts_query));
char *file_like = bm25_file_pattern_like(file_pattern);
/* BM25 ranked query using a two-step approach to enable FTS5 early termination.
@@ -4335,6 +4386,7 @@ static char *bm25_search(cbm_store_t *store, const char *project, const char *qu
} else {
sqlite3_bind_null(stmt, BM25_BIND_NS);
}
+ sqlite3_bind_double(stmt, BM25_BIND_LABEL_WEIGHT, label_weight);
/* Count hits within the same inner-limit window — capped at BM25_INNER_LIMIT.
* Uses the identical subquery structure so the FTS5 early-exit applies here too. */
@@ -4368,6 +4420,7 @@ static char *bm25_search(cbm_store_t *store, const char *project, const char *qu
sqlite3_bind_text(cs, BM25_BIND_PROJECT, project, BM25_SQL_AUTO_LEN,
MCP_SQLITE_TRANSIENT);
sqlite3_bind_int(cs, BM25_BIND_LIMIT, BM25_INNER_LIMIT);
+ sqlite3_bind_double(cs, BM25_BIND_LABEL_WEIGHT, label_weight);
if (file_like) {
sqlite3_bind_text(cs, BM25_BIND_FILE, file_like, BM25_SQL_AUTO_LEN,
MCP_SQLITE_TRANSIENT);
@@ -4400,9 +4453,10 @@ static char *bm25_search(cbm_store_t *store, const char *project, const char *qu
/* The top-candidate window is a performance ceiling, not an exact-total
* boundary. Probe one candidate beyond it so a broad query never presents
- * a window-local count as the complete match count. This is global to the
- * FTS table; saturation is therefore conservatively reported even when
- * later project/path filters might discard the hidden candidates. */
+ * a window-local count as the complete match count. The probe shares the
+ * label-scoped MATCH but is otherwise global to the FTS table; saturation
+ * is therefore conservatively reported even when later project/path
+ * filters might discard the hidden candidates. */
bool candidate_window_saturated = true;
{
const char *probe_sql = "SELECT rowid FROM nodes_fts WHERE nodes_fts MATCH ?1 "
diff --git a/tests/test_mcp.c b/tests/test_mcp.c
index 907471f30..78cf915a9 100644
--- a/tests/test_mcp.c
+++ b/tests/test_mcp.c
@@ -4373,6 +4373,154 @@ TEST(tool_search_graph_bm25_applies_label_filter) {
PASS();
}
+/* #2386: the label filter must choose the BM25 candidate window, not trim it
+ * afterwards. 2001 Functions fill the window ahead of 3 Classes that rank
+ * strictly lower (longer file_path), so a post-window filter returns 0 Classes
+ * while reporting a saturated window. */
+static char *bm25_label_window_search(cbm_mcp_server_t *srv, const char *label_json) {
+ char req[512];
+ snprintf(req, sizeof(req),
+ "{\"jsonrpc\":\"2.0\",\"id\":2386,\"method\":\"tools/call\","
+ "\"params\":{\"name\":\"search_graph\",\"arguments\":{"
+ "\"project\":\"bm25-label-window\",\"query\":\"windowneedle\","
+ "\"label\":%s,\"limit\":10,\"format\":\"json\"}}}",
+ label_json);
+ char *resp = cbm_mcp_server_handle(srv, req);
+ char *inner = resp ? extract_text_content(resp) : NULL;
+ free(resp);
+ return inner;
+}
+
+TEST(tool_search_graph_bm25_label_filter_selects_candidate_window) {
+ cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+ ASSERT_NOT_NULL(srv);
+ cbm_store_t *store = cbm_mcp_server_store(srv);
+ ASSERT_NOT_NULL(store);
+ const char *project = "bm25-label-window";
+ cbm_mcp_server_set_project(srv, project);
+ ASSERT_EQ(cbm_store_upsert_project(store, project, "/tmp/bm25-label-window"), CBM_STORE_OK);
+
+ for (int i = 0; i < 2001; i++) {
+ char qn[64];
+ snprintf(qn, sizeof(qn), "bm25-label-window.fn_%04d", i);
+ cbm_node_t node = {.project = project,
+ .label = "Function",
+ .name = "windowneedle",
+ .qualified_name = qn,
+ .file_path = "many.c",
+ .start_line = i + 1,
+ .end_line = i + 1};
+ ASSERT_GT(cbm_store_upsert_node(store, &node), 0);
+ }
+ for (int i = 0; i < 3; i++) {
+ char qn[64];
+ snprintf(qn, sizeof(qn), "bm25-label-window.cls_%d", i);
+ cbm_node_t node = {.project = project,
+ .label = "Class",
+ .name = "windowneedle",
+ .qualified_name = qn,
+ .file_path = "deeply/nested/package/layout/registry.c",
+ .start_line = i + 1,
+ .end_line = i + 1};
+ ASSERT_GT(cbm_store_upsert_node(store, &node), 0);
+ }
+ ASSERT_EQ(cbm_store_exec(store, "INSERT INTO nodes_fts(nodes_fts) VALUES('delete-all');"),
+ CBM_STORE_OK);
+ ASSERT_EQ(cbm_store_exec(store, "INSERT INTO nodes_fts(rowid, name, qualified_name, label, "
+ "file_path) SELECT id, cbm_camel_split(name), qualified_name, "
+ "label, file_path FROM nodes;"),
+ CBM_STORE_OK);
+
+ /* The rare label comes back in full, and the window is not saturated. */
+ char *inner = bm25_label_window_search(srv, "\"Class\"");
+ ASSERT_NOT_NULL(inner);
+ ASSERT_NOT_NULL(strstr(inner, "\"bm25-label-window.cls_0\""));
+ ASSERT_NOT_NULL(strstr(inner, "\"bm25-label-window.cls_2\""));
+ ASSERT_NULL(strstr(inner, "\"Function\""));
+ ASSERT_NOT_NULL(strstr(inner, "\"total\":3"));
+ ASSERT_NOT_NULL(strstr(inner, "\"total_relation\":\"eq\""));
+ ASSERT_NULL(strstr(inner, "candidate_window_saturated"));
+ free(inner);
+
+ /* The common label still overflows its own window and says so. */
+ inner = bm25_label_window_search(srv, "\"Function\"");
+ ASSERT_NOT_NULL(inner);
+ ASSERT_NOT_NULL(strstr(inner, "\"total\":2000"));
+ ASSERT_NOT_NULL(strstr(inner, "\"candidate_window_saturated\":true"));
+ free(inner);
+
+ /* A label carrying FTS5 syntax is never spliced into MATCH: the query
+ * stays in BM25 mode and the exact label check matches nothing. */
+ inner = bm25_label_window_search(srv, "\"Class\\\" OR windowneedle\"");
+ ASSERT_NOT_NULL(inner);
+ ASSERT_NOT_NULL(strstr(inner, "\"search_mode\":\"bm25\""));
+ ASSERT_NOT_NULL(strstr(inner, "\"total\":0"));
+ free(inner);
+
+ cbm_mcp_server_free(srv);
+ PASS();
+}
+
+/* Scoping the MATCH to a label must not reorder that label's rows: a
+ * label-filtered query lists its rows in the same order as the unfiltered
+ * query does. The fixture's four `table` Methods differ in row length, which
+ * is exactly what a scored label phrase would re-weight. */
+TEST(tool_search_graph_bm25_label_scope_keeps_rank_order) {
+ cbm_mcp_server_t *srv = cbm_mcp_server_new(NULL);
+ ASSERT_NOT_NULL(srv);
+ cbm_store_t *store = cbm_mcp_server_store(srv);
+ ASSERT_NOT_NULL(store);
+ cbm_mcp_server_set_project(srv, "bm25-find");
+ bm25_findability_fixture(store, "bm25-find");
+
+ char *all_resp = cbm_mcp_server_handle(
+ srv, "{\"jsonrpc\":\"2.0\",\"id\":2387,\"method\":\"tools/call\","
+ "\"params\":{\"name\":\"search_graph\",\"arguments\":{"
+ "\"project\":\"bm25-find\",\"query\":\"table\",\"limit\":20,\"format\":\"json\"}}}");
+ char *methods_resp = cbm_mcp_server_handle(
+ srv, "{\"jsonrpc\":\"2.0\",\"id\":2388,\"method\":\"tools/call\","
+ "\"params\":{\"name\":\"search_graph\",\"arguments\":{"
+ "\"project\":\"bm25-find\",\"query\":\"table\",\"label\":\"Method\","
+ "\"limit\":20,\"format\":\"json\"}}}");
+ ASSERT_NOT_NULL(all_resp);
+ ASSERT_NOT_NULL(methods_resp);
+ char *all = extract_text_content(all_resp);
+ char *methods = extract_text_content(methods_resp);
+ free(all_resp);
+ free(methods_resp);
+ ASSERT_NOT_NULL(all);
+ ASSERT_NOT_NULL(methods);
+ ASSERT_NOT_NULL(strstr(methods, "\"total\":4"));
+
+ static const char *const qns[] = {
+ "\"bm25-find.core.Table.Table.unquoted\"",
+ "\"bm25-find.core.Table.Table.describe\"",
+ "\"bm25-find.tests.SchemaTests.table_references_table_with_same_name\"",
+ "\"bm25-find.tests.SchemaTests.table_references_table_with_same_name_mysql\"",
+ };
+ enum { QN_COUNT = sizeof(qns) / sizeof(qns[0]) };
+ for (int i = 0; i < QN_COUNT; i++) {
+ for (int j = 0; j < QN_COUNT; j++) {
+ if (i == j) {
+ continue;
+ }
+ const char *ai = strstr(all, qns[i]);
+ const char *aj = strstr(all, qns[j]);
+ const char *mi = strstr(methods, qns[i]);
+ const char *mj = strstr(methods, qns[j]);
+ ASSERT_NOT_NULL(ai);
+ ASSERT_NOT_NULL(aj);
+ ASSERT_NOT_NULL(mi);
+ ASSERT_NOT_NULL(mj);
+ ASSERT_EQ(ai < aj, mi < mj);
+ }
+ }
+ free(all);
+ free(methods);
+ cbm_mcp_server_free(srv);
+ PASS();
+}
+
/* The definition whose NAME is the query ranks first: the `Table` class above
* its own methods and above test methods that repeat "table" three times; the
* `get_object_or_404` function above the test methods that contain it. */
@@ -24695,6 +24843,8 @@ SUITE(mcp) {
RUN_TEST(tool_search_graph_query_honors_file_pattern_issue552);
RUN_TEST(tool_search_graph_bm25_reports_candidate_saturation);
RUN_TEST(tool_search_graph_bm25_applies_label_filter);
+ RUN_TEST(tool_search_graph_bm25_label_filter_selects_candidate_window);
+ RUN_TEST(tool_search_graph_bm25_label_scope_keeps_rank_order);
RUN_TEST(tool_search_graph_bm25_ranks_exact_name_first);
RUN_TEST(tool_search_graph_rejects_bm25_and_semantic_query_together);
RUN_TEST(tool_search_graph_semantic_ceiling_never_emits_unusable_continuation);