Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

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.ts
new file mode 100644
index 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.ts
index 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 match
6. 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.md
index 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 |