Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
fix(search): widen bounded keyword candidates for path filters (#648)
Hiro-Chiba6f563db67c39
diff --git a/ix-cli/src/cli/__tests__/search-path-window.test.ts b/ix-cli/src/cli/__tests__/search-path-window.test.tsnew file mode 100644index 00000000..28ec48d7--- /dev/null+++ b/ix-cli/src/cli/__tests__/search-path-window.test.ts@@ -0,0 +1,95 @@+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import { Command } from "commander";+import { registerSearchCommand } from "../commands/search.js";++const { search, semanticSearch } = vi.hoisted(() => ({ search: vi.fn(), semanticSearch: vi.fn() }));+vi.mock("../../client/api.js", () => ({+ IxClient: class {+ async search(...args: unknown[]) { return search(...args); }+ async semanticSearch(...args: unknown[]) { return semanticSearch(...args); }+ },+}));+vi.mock("../resolve.js", async (importOriginal) => ({+ ...await importOriginal<typeof import("../resolve.js")>(),+ resolveReadSystemId: async () => "test-system",+}));++const node = (i: number, path = "src/other.ts", role = "production") => ({+ id: `id-${i}`, name: `Service${i}`, kind: "class", provenance: { sourceUri: path }, attrs: { role },+});++async function run(args: string[], format = "json") {+ const program = new Command().name("ix").exitOverride();+ registerSearchCommand(program);+ const output: string[] = [];+ const errors: string[] = [];+ vi.spyOn(console, "log").mockImplementation((...parts) => { output.push(parts.join(" ")); });+ vi.spyOn(process.stderr, "write").mockImplementation(((part: string) => { errors.push(String(part)); return true; }) as never);+ await program.parseAsync(["search", "Service", "--kind", "class", ...args, "--format", format], { from: "user" });+ return { stdout: output.join("\n"), stderr: errors.join("") };+}++function dataset(nodes: ReturnType<typeof node>[]) {+ search.mockImplementation(async (_term, opts) => nodes.slice(0, opts.limit));+}++describe("keyword search path candidate window", () => {+ beforeEach(() => { search.mockReset(); semanticSearch.mockReset(); });+ afterEach(() => vi.restoreAllMocks());++ it("finds a path match after the old 60-candidate ceiling", async () => {+ dataset([...Array.from({ length: 70 }, (_, i) => node(i)), node(70, "src/target.ts")]);+ const { stdout } = await run(["--path", "SRC\\TARGET.ts", "--limit", "1000", "--language", "ts", "--as-of", "12"]);+ expect(JSON.parse(stdout).results.map((n: { id: string }) => n.id)).toEqual(["id-70"]);+ expect(search.mock.calls.length).toBeGreaterThan(1);+ expect(search.mock.calls.every(([, opts]) => opts.systemId === "test-system" && opts.kind === "class" && opts.language === "ts" && opts.asOfRev === 12)).toBe(true);+ });++ it("stops when enough matching results have been fetched", async () => {+ dataset([...Array.from({ length: 4 }, (_, i) => node(i)), node(4, "src/target.ts"), ...Array.from({ length: 50 }, (_, i) => node(i + 5))]);+ const output = JSON.parse((await run(["--path", "target.ts", "--limit", "1"])).stdout);+ expect(output.results).toHaveLength(1);+ expect(search.mock.calls).toHaveLength(2);+ });++ it.each(["json", "llm", "text"])("warns about the bounded candidate scan in %s", async (format) => {+ dataset(Array.from({ length: 2100 }, (_, i) => node(i)));+ const output = await run(["--path", "target.ts"], format);+ expect(output.stdout + output.stderr).toContain("Search inspected only the first 2000 candidates");+ expect(Math.max(...search.mock.calls.map(([, opts]) => opts.limit))).toBe(2000);+ expect(search.mock.calls.length).toBeLessThanOrEqual(5);+ });++ it("does not retry an exhausted response", async () => {+ dataset([node(1)]);+ expect(JSON.parse((await run(["--path", "target.ts"])).stdout).results).toEqual([]);+ expect(search).toHaveBeenCalledTimes(1);+ });++ it("does not widen an unscoped search", async () => {+ dataset(Array.from({ length: 100 }, (_, i) => node(i)));+ await run([]);+ expect(search).toHaveBeenCalledTimes(1);+ });++ it("does not widen a zero-result request", async () => {+ dataset(Array.from({ length: 100 }, (_, i) => node(i)));+ expect(JSON.parse((await run(["--path", "target.ts", "--limit", "0"])).stdout).results).toEqual([]);+ expect(search).toHaveBeenCalledTimes(1);+ });++ it("checks the requested role before deciding that enough matches exist", async () => {+ dataset([...Array.from({ length: 4 }, (_, i) => node(i, "src/target.ts")), node(4, "src/target.ts", "test")]);+ const output = JSON.parse((await run(["--path", "target.ts", "--limit", "1", "--tests-only"])).stdout);+ expect(output.results.map((n: { id: string }) => n.id)).toEqual(["id-4"]);+ expect(search).toHaveBeenCalledTimes(2);+ });++ it("preserves the semantic search request and ordering", async () => {+ semanticSearch.mockResolvedValue([node(2, "src/target.ts"), node(1, "src/target.ts")]);+ const output = JSON.parse((await run(["--path", "target.ts", "--semantic"])).stdout);+ expect(output.results.map((n: { id: string }) => n.id)).toEqual(["id-2", "id-1"]);+ expect(semanticSearch).toHaveBeenCalledTimes(1);+ expect(search).not.toHaveBeenCalled();+ });+});diff --git a/ix-cli/src/cli/commands/search.ts b/ix-cli/src/cli/commands/search.tsindex 2f2d77cd..335e619d 100644--- a/ix-cli/src/cli/commands/search.ts+++ b/ix-cli/src/cli/commands/search.ts@@ -102,6 +102,8 @@ function normalizePath(value: string | undefined): string {return (value ?? "").toLowerCase().replace(/\\/g, "/");}+const PATH_CANDIDATE_LIMIT = 2000;+export function registerSearchCommand(program: Command): void {program.command("search <term>")@@ -109,7 +111,7 @@ export function registerSearchCommand(program: Command): void {.option("--limit <n>", "Max results", "10").option("--kind <kind>", "Filter and boost results by node kind (e.g. class, function, decision)").option("--language <lang>", "Filter by language/file extension (e.g. scala, ts)")- .option("--path <path>", "Boost results from files matching this path substring")+ .option("--path <path>", "Filter results by file path (case-insensitive substring match)").option("--as-of <rev>", "Search as of a specific revision").option("--format <fmt>", "Output format (text|json|llm)", "text").option("--include-tests", "Include test and fixture entities in results")@@ -123,7 +125,9 @@ export function registerSearchCommand(program: Command): void {5. Container-aware near match6. Fuzzy/incidental match-Use --path to boost results from specific directories.+Use --path to filter results from specific directories.+Keyword searches with --path widen the candidate window up to 2000 nodes.+If that bound is reached, a diagnostic warns that matches may be missing.Examples:ix search IngestionService --kind class@@ -142,7 +146,7 @@ Examples:const effectivePathFilter = opts.path;// Fetch more results than requested so we can re-rank and trim- const fetchLimit = Math.min(limit * 3, 60);+ let fetchLimit = Math.min(limit * 3, 60);// Auto-detect a multi-repo system; when present, scope by system_id (which// spans all member repos) instead of the single-repo workspace_id.const systemId = await resolveReadSystemId(client);@@ -150,27 +154,41 @@ Examples:// Semantic search hits a different backend endpoint that embeds the term and// returns nodes already ordered by vector similarity. It ignores --language// and --as-of (the endpoint accepts neither); scoping is shared.- const rawNodes = opts.semantic- ? await client.semanticSearch(term, {- limit: fetchLimit,+ const fetchCandidates = (candidateLimit: number) => opts.semantic+ ? client.semanticSearch(term, {+ limit: candidateLimit,kind: opts.kind,workspaceId,systemId,})- : await client.search(term, {- limit: fetchLimit,+ : client.search(term, {+ limit: candidateLimit,kind: opts.kind,language: opts.language,asOfRev: opts.asOf ? parseInt(opts.asOf, 10) : undefined,workspaceId,systemId,});- const nodes = effectivePathFilter- ? rawNodes.filter((node: any) => {+ let rawNodes = await fetchCandidates(fetchLimit);+ const filterPath = (candidates: typeof rawNodes) => effectivePathFilter+ ? candidates.filter((node: any) => {const sourceUri = normalizePath(node.provenance?.sourceUri ?? node.provenance?.source_uri ?? "");return sourceUri.includes(normalizePath(effectivePathFilter));})- : rawNodes;+ : candidates;+ let nodes = filterPath(rawNodes);++ // The released search API cannot filter by path or paginate. Widen its+ // prefix only when filtering leaves too few results, with a finite bound.+ while (effectivePathFilter && !opts.semantic && fetchLimit > 0+ && rawNodes.length >= fetchLimit && fetchLimit < PATH_CANDIDATE_LIMIT+ && applyRoleFilter(nodes, opts).filtered.length < limit) {+ fetchLimit = Math.min(fetchLimit * 4, PATH_CANDIDATE_LIMIT);+ rawNodes = await fetchCandidates(fetchLimit);+ nodes = filterPath(rawNodes);+ }+ const pathWindowLimited = effectivePathFilter && !opts.semantic+ && fetchLimit === PATH_CANDIDATE_LIMIT && rawNodes.length >= fetchLimit;// Re-rank client-side using shared scoring + backend weight. The rank object// is still computed for display (tier/score), but for semantic search we keep@@ -193,6 +211,12 @@ Examples:const ranked = trimmed.map(s => s.node);const diagnostics: { code: string; message: string }[] = [];+ if (pathWindowLimited) {+ diagnostics.push({+ code: "path_search_truncated",+ message: `Search inspected only the first ${PATH_CANDIDATE_LIMIT} candidates before filtering by path; matching results may be missing. Use a more specific search term.`,+ });+ }if (!opts.kind) {diagnostics.push({code: "unfiltered_search",@@ -239,6 +263,7 @@ Examples:}, null, 2));} else {formatNodes(ranked, opts.format);+ if (pathWindowLimited) stderr(chalk.dim(diagnostics.find(d => d.code === "path_search_truncated")!.message));const hint = roleHint(hiddenTestCount);if (hint) stderr(chalk.dim(hint));}diff --git a/skills/ix/references/flags.md b/skills/ix/references/flags.mdindex 596e0d95..e712c14f 100644--- a/skills/ix/references/flags.md+++ b/skills/ix/references/flags.md@@ -505,7 +505,7 @@ Search the knowledge graph by term — ranked by structural relevance.| `--limit` | `<n>` | `10` | Max results || `--kind` | `<kind>` | — | Filter and boost results by node kind (e.g. class, function, decision) || `--language` | `<lang>` | — | Filter by language/file extension (e.g. scala, ts) |-| `--path` | `<path>` | — | Boost results from files matching this path substring |+| `--path` | `<path>` | — | Filter results by file path (case-insensitive substring match). Keyword searches widen the candidate window up to 2000 nodes and warn if that bound is reached. || `--as-of` | `<rev>` | — | Search as of a specific revision || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) || `--include-tests` | — | off | Include test and fixture entities in results |