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): rank code definitions above imports, non-code and build output

KageBinaryef416f218c25
diff --git a/ix-cli/src/cli/__tests__/search-definitions-first.test.ts b/ix-cli/src/cli/__tests__/search-definitions-first.test.ts
new file mode 100644
index 00000000..889dbf33
--- /dev/null
+++ b/ix-cli/src/cli/__tests__/search-definitions-first.test.ts
@@ -0,0 +1,216 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Command } from "commander";
+import { registerSearchCommand } from "../commands/search.js";
+
+/**
+ * `ix search <code name>` must lead with the code definition.
+ *
+ * Seen on SWE-PolyBench while resolving names from issue text: an import of a
+ * name (a `module` entity whose path is the IMPORTING file) came back instead
+ * of the file that defines it, and code-like terms matched CSS selectors,
+ * markdown headings, JSON keys and build output ahead of code. Those rows are
+ * demoted, never removed.
+ */
+
+const { search } = vi.hoisted(() => ({ search: vi.fn() }));
+vi.mock("../../client/api.js", () => ({
+ IxClient: class {
+ async search(...args: unknown[]) { return search(...args); }
+ async semanticSearch() { return []; }
+ },
+}));
+vi.mock("../resolve.js", async (importOriginal) => ({
+ ...await importOriginal<typeof import("../resolve.js")>(),
+ resolveReadSystemId: async () => "test-system",
+}));
+
+type Node = { id: string; name: string; kind: string; provenance: { sourceUri: string }; attrs: Record<string, unknown> };
+
+function n(
+ id: string, name: string, kind: string, path: string, weight: number,
+ extra: Record<string, unknown> = {},
+): Node {
+ const ext = path.slice(path.lastIndexOf(".") + 1);
+ const language = ({ js: "javascript", ts: "typescript", css: "css", md: "markdown", json: "json" } as Record<string, string>)[ext];
+ return {
+ id, name, kind, provenance: { sourceUri: path },
+ attrs: { language, line_start: 1, line_end: 20, role: "production", _search_weight: weight, ...extra },
+ };
+}
+
+/** An import entity: single-line `module` in the importing file. */
+function imp(id: string, name: string, path: string, line = 3): Node {
+ return n(id, name, "module", path, 100, { line_start: line, line_end: line });
+}
+
+/** A fake backend: honours `kind` and `limit` like `/v1/search` does. */
+function dataset(nodes: Node[]) {
+ search.mockImplementation(async (_term: string, opts: { limit?: number; kind?: string }) => {
+ const matching = opts.kind ? nodes.filter((x) => x.kind === opts.kind) : nodes;
+ return matching.slice(0, opts.limit);
+ });
+}
+
+async function run(term: string, args: string[] = []) {
+ const program = new Command().name("ix").exitOverride();
+ registerSearchCommand(program);
+ const output: string[] = [];
+ vi.spyOn(console, "log").mockImplementation((...parts) => { output.push(parts.join(" ")); });
+ vi.spyOn(process.stderr, "write").mockImplementation((() => true) as never);
+ await program.parseAsync(["search", term, ...args, "--format", "json"], { from: "user" });
+ return JSON.parse(output.join("\n")) as {
+ results: Array<{ id: string; tier: number; score: number; matchSource: string }>;
+ };
+}
+
+const ids = (out: { results: Array<{ id: string }> }) => out.results.map((r) => r.id);
+
+describe("search: definitions rank above import entities", () => {
+ beforeEach(() => { search.mockReset(); });
+ afterEach(() => vi.restoreAllMocks());
+
+ it("ranks the defining file above an import of the same name (tailwind borderStylesReset)", async () => {
+ // The generator is an anonymous default export, so the only definition row
+ // is its file; the backend scores the file as a partial name match.
+ dataset([
+ imp("import", "borderStylesReset", "src/lib/generateUtilities.js"),
+ n("file", "borderStylesReset.js", "file", "src/generators/borderStylesReset.js", 60, { line_end: 8 }),
+ ]);
+ const out = await run("borderStylesReset");
+ expect(ids(out)).toEqual(["file", "import"]);
+ expect(out.results[0].tier).toBeLessThan(out.results[1].tier);
+ });
+
+ it("ranks a same-named function above its import", async () => {
+ dataset([
+ imp("import", "parseConfig", "src/cli.ts"),
+ n("fn", "parseConfig", "function", "src/config.ts", 100),
+ ]);
+ expect(ids(await run("parseConfig"))).toEqual(["fn", "import"]);
+ });
+
+ it("finds the defining file even when imports fill the candidate window", async () => {
+ // 40 importers of the name, then the file itself as a partial match: the
+ // default window (limit * 3 = 30) never reaches it.
+ dataset([
+ ...Array.from({ length: 40 }, (_, i) => imp(`import-${i}`, "borderStylesReset", `src/lib/user${i}.js`)),
+ n("file", "borderStylesReset.js", "file", "src/generators/borderStylesReset.js", 60),
+ ]);
+ const out = await run("borderStylesReset");
+ expect(ids(out)[0]).toBe("file");
+ expect(out.results.length).toBe(10);
+ });
+
+ it("does not spend an extra request when a definition is already in the window", async () => {
+ dataset([
+ n("fn", "parseConfig", "function", "src/config.ts", 100),
+ ...Array.from({ length: 40 }, (_, i) => imp(`import-${i}`, "parseConfig", `src/user${i}.ts`)),
+ ]);
+ const out = await run("parseConfig");
+ expect(ids(out)[0]).toBe("fn");
+ expect(search).toHaveBeenCalledTimes(1);
+ });
+});
+
+describe("search: code definitions rank above non-code and generated matches", () => {
+ beforeEach(() => { search.mockReset(); });
+ afterEach(() => vi.restoreAllMocks());
+
+ it("demotes a CSS selector in build output below a code definition (flex)", async () => {
+ dataset([
+ n("css", "flex", "class", "tailwind-output.css", 100),
+ n("fn", "flex", "function", "src/plugins/flex.js", 100),
+ ]);
+ const out = await run("flex");
+ expect(ids(out)).toEqual(["fn", "css"]);
+ });
+
+ it("demotes a markdown heading below a code definition (TypeScript)", async () => {
+ dataset([
+ n("heading", "TypeScript", "heading", "CHANGELOG.md", 100),
+ n("cls", "TypeScript", "class", "src/language-js/TypeScript.js", 100),
+ ]);
+ expect(ids(await run("TypeScript"))).toEqual(["cls", "heading"]);
+ });
+
+ it("demotes JSON keys and CSS selectors below a code definition (version)", async () => {
+ dataset([
+ n("json", "version", "config_entry", "package.json", 100),
+ n("css", "version", "class", "src/browser/media/code.css", 100),
+ n("const", "version", "constant", "src/node/constants.ts", 100),
+ ]);
+ const out = await run("version");
+ expect(ids(out)[0]).toBe("const");
+ expect(ids(out).sort()).toEqual(["const", "css", "json"]);
+ });
+
+ it("demotes definitions in dist/, build/, minified and fixture files below the source one", async () => {
+ dataset([
+ n("dist", "code", "function", "dist/index.js", 100),
+ n("build", "code", "function", "build/lib/code.js", 100),
+ n("min", "code", "function", "vendor/code.min.js", 100),
+ n("fixture", "code", "function", "test-plugin/fixtures/plugin.js", 100),
+ n("sample", "code", "function", "samples/plugin.js", 100),
+ n("src", "code", "function", "src/node/code.ts", 100),
+ ]);
+ const out = await run("code");
+ expect(ids(out)[0]).toBe("src");
+ expect(out.results).toHaveLength(6);
+ });
+
+ it("keeps a demoted row when it is the only match", async () => {
+ dataset([n("css", "flex", "class", "tailwind-output.css", 100)]);
+ expect(ids(await run("flex"))).toEqual(["css"]);
+ });
+
+ it("does not demote CSS for a term that is not a code identifier", async () => {
+ dataset([
+ n("fn", "border-solid", "function", "src/util.js", 60),
+ n("css", "border-solid", "class", "src/css/base.css", 100),
+ ]);
+ const out = await run("border-solid");
+ expect(ids(out)[0]).toBe("css");
+ expect(out.results[0].tier).toBeLessThanOrEqual(1);
+ });
+
+ it("does not demote the kind the caller asked for", async () => {
+ dataset([
+ n("heading", "Installation", "heading", "README.md", 100),
+ n("heading2", "Installation", "heading", "docs/setup.md", 100),
+ ]);
+ const out = await run("Installation", ["--kind", "heading"]);
+ expect(out.results.every((r) => r.tier <= 1)).toBe(true);
+ });
+});
+
+describe("search: role filtering is unchanged by the demotion", () => {
+ beforeEach(() => { search.mockReset(); });
+ afterEach(() => vi.restoreAllMocks());
+
+ const rows = () => [
+ n("fixture", "prettier", "function", "tests/fixtures/plugin/prettier.js", 100, { role: "fixture" }),
+ n("test", "prettier", "function", "tests/format.test.js", 100, { role: "test" }),
+ n("src", "prettier", "function", "src/index.js", 100),
+ ];
+
+ it("hides test and fixture rows by default", async () => {
+ dataset(rows());
+ expect(ids(await run("prettier"))).toEqual(["src"]);
+ });
+
+ it("--include-tests keeps every row, the fixture stand-in last", async () => {
+ // A test is code under test's own name and keeps its place; a fixture is a
+ // stand-in and is demoted like a sample.
+ dataset(rows());
+ const out = await run("prettier", ["--include-tests"]);
+ expect(ids(out)).toHaveLength(3);
+ expect(ids(out)[2]).toBe("fixture");
+ });
+
+ it("--tests-only keeps only test and fixture rows", async () => {
+ dataset(rows());
+ expect(ids(await run("prettier", ["--tests-only"])).sort()).toEqual(["fixture", "test"]);
+ });
+});
diff --git a/ix-cli/src/cli/commands/search.ts b/ix-cli/src/cli/commands/search.ts
index 67241692..56fba737 100644
--- a/ix-cli/src/cli/commands/search.ts
+++ b/ix-cli/src/cli/commands/search.ts
@@ -6,7 +6,8 @@ import { IxClient } from "../../client/api.js";
import { getEndpoint } from "../config.js";
import { resolveWorkspaceId } from "../bootstrap.js";
import { formatNodes, relativePath, printJson } from "../format.js";
-import { scoreCandidate, resolveReadSystemId } from "../resolve.js";
+import { baseScore, originPenalty, hasDefinitionOf, mergeById, resolveReadSystemId } from "../resolve.js";
+import { isFileStemMatch } from "../candidate-origin.js";
import { applyRoleFilter, roleHint } from "../role-filter.js";
import { stderr } from "../stderr.js";
import { llmLine, llmShortId } from "../llm.js";
@@ -44,12 +45,21 @@ const STRUCTURAL_KINDS = new Set([
* Lower score = better match.
*
* Combines backend weight (_search_weight from AQL) with client-side
- * resolver scoring for fine-grained ranking.
+ * resolver scoring for fine-grained ranking. The backend weighs only how the
+ * NAME matched, so the kind of thing that matched is judged here:
+ *
+ * - A file whose stem is the term (`borderStylesReset.js`) is weighed as an
+ * exact name, not the partial match the backend scores it as — it is the
+ * definition of an anonymous default export.
+ * - An exact-name row that is not a code definition — an import entity, a
+ * CSS selector / markdown heading / JSON key for a code-like term, or a
+ * copy in build output, a fixture or a sample (`originPenalty`) — is capped
+ * at tier 2 and sorts behind the definitions in it. Demoted, not dropped.
*
* Tiers (for JSON output):
* 0 — exact name + exact kind
* 1 — exact name + structural kind
- * 2 — exact name (any kind)
+ * 2 — exact name (any kind), or an exact name that is not a code definition
* 3 — partial name match (backend weight 60)
* 4 — provenance/claim/decision match
* 5 — fuzzy/incidental match
@@ -58,35 +68,57 @@ function rankScore(
node: any,
term: string,
requestedKind: string | undefined,
- pathFilter: string | undefined
+ pathFilter: string | undefined,
+ requestedLanguage?: string,
): { tier: number; score: number; matchSource: string } {
+ const rank = baseRank(node, term, requestedKind, pathFilter, requestedLanguage);
+ // Only the name tiers are capped: a demoted row stays a name match, it just
+ // no longer claims to be the best kind of one.
+ if (rank.demoted && rank.tier < 2) rank.tier = 2;
+ return { tier: rank.tier, score: rank.score, matchSource: rank.matchSource };
+}
+
+function baseRank(
+ node: any,
+ term: string,
+ requestedKind: string | undefined,
+ pathFilter: string | undefined,
+ requestedLanguage: string | undefined,
+): { tier: number; score: number; matchSource: string; demoted: boolean } {
// Weight is embedded in attrs by the backend AQL (survives parseNode → GraphNode → JSON)
- const backendWeight: number = node.attrs?._search_weight ?? (node as any)._search_weight ?? 0;
- const resolverScore = scoreCandidate(node, term, { kind: requestedKind, path: pathFilter });
+ const reportedWeight: number = node.attrs?._search_weight ?? (node as any)._search_weight ?? 0;
+ const stemMatch = reportedWeight < 100 && isFileStemMatch(node, term);
+ const backendWeight = stemMatch && reportedWeight >= 60 ? 100 : reportedWeight;
+ const nameScore = baseScore(node, term, { kind: requestedKind, path: pathFilter });
+ const penalty = originPenalty(node, term, { kind: requestedKind, language: requestedLanguage });
+ const demoted = penalty > 0;
+ // The tier comes from how the name matched; the penalty only orders rows
+ // inside a tier (and caps the name tiers, above).
+ const resolverScore = nameScore + penalty;
+ const exactSource = stemMatch ? "file_stem" : "name_exact";
// Backend weight provides relevance signal, resolver refines within tier
if (backendWeight >= 100) {
// Exact backend name match — use resolver to sub-rank
- if (resolverScore <= -3) return { tier: 0, score: -backendWeight + resolverScore, matchSource: "name_exact" };
- if (resolverScore <= 0) return { tier: 1, score: -backendWeight + resolverScore, matchSource: "name_exact" };
- return { tier: 2, score: -backendWeight + resolverScore, matchSource: "name_exact" };
+ if (nameScore <= -3) return { tier: 0, score: -backendWeight + resolverScore, matchSource: exactSource, demoted };
+ if (nameScore <= 0) return { tier: 1, score: -backendWeight + resolverScore, matchSource: exactSource, demoted };
+ return { tier: 2, score: -backendWeight + resolverScore, matchSource: exactSource, demoted };
}
if (backendWeight >= 60) {
- return { tier: 3, score: -backendWeight + resolverScore, matchSource: "name_partial" };
+ return { tier: 3, score: -backendWeight + resolverScore, matchSource: "name_partial", demoted };
}
if (backendWeight >= 40) {
- return { tier: 4, score: -backendWeight, matchSource: "provenance" };
+ return { tier: 4, score: -backendWeight, matchSource: "provenance", demoted };
}
if (backendWeight >= 20) {
- return { tier: 4, score: -backendWeight, matchSource: "claim_or_decision" };
+ return { tier: 4, score: -backendWeight, matchSource: "claim_or_decision", demoted };
}
// No backend weight — fall back to pure resolver scoring
- if (resolverScore <= -8) return { tier: 0, score: resolverScore, matchSource: "resolver" };
- if (resolverScore <= -3) return { tier: 0, score: resolverScore, matchSource: "resolver" };
- if (resolverScore <= 0) return { tier: 1, score: resolverScore, matchSource: "resolver" };
- if (resolverScore <= 2) return { tier: 2, score: resolverScore, matchSource: "resolver" };
- return { tier: 5, score: resolverScore, matchSource: "attrs" };
+ if (nameScore <= -3) return { tier: 0, score: resolverScore, matchSource: "resolver", demoted };
+ if (nameScore <= 0) return { tier: 1, score: resolverScore, matchSource: "resolver", demoted };
+ if (nameScore <= 2) return { tier: 2, score: resolverScore, matchSource: "resolver", demoted };
+ return { tier: 5, score: resolverScore, matchSource: "attrs", demoted: false };
}
/**
@@ -184,6 +216,9 @@ function normalizePath(value: string | undefined): string {
const PATH_CANDIDATE_LIMIT = 2000;
+/** How far the window is widened, once, to reach a definition crowded out by same-named rows. */
+const DEFINITION_WINDOW = 200;
+
export function registerSearchCommand(program: Command): void {
program
.command("search <term>")
@@ -199,8 +234,12 @@ export function registerSearchCommand(program: Command): void {
.option("--semantic", "Use vector-similarity (embedding) search instead of keyword matching")
.addHelpText("after", `\nRanking priority (score 1.00 down to 0.17):
1. Exact name + exact kind match
- 2. Exact name + structural kind (class, function, etc.)
- 3. Exact name (any kind)
+ 2. Exact name + structural kind (class, function, etc.), or the file named
+ after the term (borderStylesReset.js for borderStylesReset)
+ 3. Exact name (any kind). Same-named rows that are not the code definition
+ rank here, behind it: imports of the name, CSS selectors, markdown
+ headings and JSON keys (for a code-like term), and copies in build
+ output (dist/, build/, *.min.js, *-output.*), fixtures and samples
4. Exact filename/module match
5. Container-aware near match
6. Fuzzy/incidental match — dropped when any of 1-5 matched
@@ -282,13 +321,46 @@ Examples:
const pathWindowLimited = effectivePathFilter && !opts.semantic
&& fetchLimit === PATH_CANDIDATE_LIMIT && rawNodes.length >= fetchLimit;
+ // Definitions first (see rankScore) only helps if the definition is in
+ // the window. The backend fills it by weight — every exact name before
+ // any partial one, in no useful order within a weight — so a name that is
+ // imported in thirty files can fill the window with imports while the
+ // definition sits past it. When the window came back full and holds no
+ // definition of the term, look further, at most twice:
+ // 1. the window ends on an exact-name row, so more exact names follow:
+ // re-fetch once with a wider window;
+ // 2. still none: ask for files by that name — the definition of an
+ // anonymous default export is its file, a partial match the backend
+ // may rank anywhere among the partials.
+ if (!opts.semantic && limit > 0 && rawNodes.length >= fetchLimit && !hasDefinitionOf(nodes, term)) {
+ const last: any = rawNodes[rawNodes.length - 1];
+ if (fetchLimit < DEFINITION_WINDOW && (last?.attrs?._search_weight ?? last?._search_weight ?? 0) >= 100) {
+ fetchLimit = DEFINITION_WINDOW;
+ rawNodes = await fetchCandidates(fetchLimit);
+ nodes = filterPath(rawNodes);
+ }
+ if (!hasDefinitionOf(nodes, term) && (!opts.kind || opts.kind === "file")) {
+ const files = await client.search(term, {
+ limit: 20,
+ kind: "file",
+ language: opts.language,
+ asOfRev: opts.asOf ? parseInt(opts.asOf, 10) : undefined,
+ workspaceId,
+ systemId,
+ scope: effectivePathFilter ? normalizePathSeparators(effectivePathFilter) : undefined,
+ });
+ rawNodes = mergeById(rawNodes, files.filter((n: any) => isFileStemMatch(n, term)));
+ nodes = filterPath(rawNodes);
+ }
+ }
+
// 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
// the backend's vector-similarity order and skip the keyword-based re-sort,
// which would otherwise demote semantically-relevant results lacking the term.
const scored = nodes.map(n => ({
node: n,
- rank: rankScore(n, term, opts.kind, effectivePathFilter),
+ rank: rankScore(n, term, opts.kind, effectivePathFilter, opts.language),
}));
if (!opts.semantic) scored.sort(searchSort);