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): 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.tsnew file mode 100644index 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.tsindex 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 tierif (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 samples4. Exact filename/module match5. Container-aware near match6. 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);