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
// Copyright 2026 Ix Infrastructure Inc.
import type { Command } from "commander";
import chalk from "chalk";
import { createClient } from "../../client/factory.js";
import { resolveWorkspaceId } from "../bootstrap.js";
import { disambiguatingIds, formatNodes, lineSpan, relativePath, printJson, rowLocation } from "../format.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 } from "../llm.js";
import { isQuiet, projectRow } from "../output-shape.js";
import { normalizePathSeparators } from "../path-match.js";
import { checkGraphHealth } from "../graph-health.js";
/** One `ix search` row as the llm renderer takes it. */
export interface SearchLlmRow {
name: string;
kind: string;
id?: string;
path?: string;
/** `320-340`, from the graph's span; absent for a file or an unknown span. */
lines?: string;
score?: number;
/** Set only for a row that matched on something other than its name. */
match?: string;
}
/**
* Render `ix search` as llm records: a header line then one `node` row per hit
* (rank = order).
*
* `path` and `lines` together are the answer — the tool is described to agents
* as returning path:lines, and a row without the span sent them to grep for
* it. The id is printed only where two rows would otherwise read the same (see
* `disambiguatingIds`). A row that did not match by name says what it matched
* on in `match=`, so it cannot be mistaken for a definition.
*/
export function renderSearchLlm(
results: SearchLlmRow[],
totalCandidates: number, diagnostics: Array<{ code: string; message: string }>,
hint?: string,
): string[] {
const lines = [llmLine("search", [["count", results.length], ["candidates", totalCandidates]])];
const ids = disambiguatingIds(
results,
(r) => `${r.name}\u0000${r.kind}\u0000${r.path ?? ""}`,
(r) => r.id,
);
results.forEach((r, i) => {
lines.push(llmLine("node", projectRow([
["name", r.name], ["kind", r.kind], ["id", ids[i]],
["path", r.path], ["lines", r.lines], ["score", r.score], ["match", r.match],
])));
});
// Advice, not findings: `--quiet` drops it. An error still reaches the
// caller through the error path, which this is not.
if (!isQuiet()) {
for (const d of diagnostics) lines.push(llmLine("diagnostic", [["code", d.code], ["message", d.message]]));
if (hint && results.length === 0) lines.push(llmLine("hint", [["text", hint]]));
}
return lines;
}
/**
* What to try after a search that found nothing.
*
* A bare `count=0` left an agent to guess why, and the usual reason is that it
* searched a phrase: search matches entity names, and no name contains
* "workspace resolve read".
*/
export function emptySearchHint(term: string, opts: { kind?: string; path?: string; language?: string } = {}): string {
const words = term.trim().split(/\s+/).filter((w) => w !== "");
if (words.length > 1) {
const longest = [...words].sort((a, b) => b.length - a.length)[0];
return `search matches one identifier by name, not a phrase. Search one word (e.g. ${longest}), or use ix text for a phrase.`;
}
const narrowed = [opts.kind && "--kind", opts.path && "--path", opts.language && "--language"].filter(Boolean);
const drop = narrowed.length > 0 ? `drop ${narrowed.join("/")}, ` : "";
return `No entity name matches. Try part of the name, ${drop}or use ix text for a literal string.`;
}
/** Said instead of {@link emptySearchHint} when the scope holds no nodes at all. */
export const WORKSPACE_EMPTY_MESSAGE =
"The graph for this workspace has no nodes, so no search can match. Run ix map to build it.";
/** Structural kinds that should rank higher than incidental matches. */
const STRUCTURAL_KINDS = new Set([
"class", "trait", "object", "interface", "function", "method", "module", "file",
"constant",
]);
/**
* Compute a ranking score for a search result.
* Lower score = better match.
*
* Combines backend weight (_search_weight from AQL) with client-side
* 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), 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
*/
export function rankScore(
node: any,
term: string,
requestedKind: 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 };
}
export 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 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 (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", demoted };
}
if (backendWeight >= 40) {
return { tier: 4, score: -backendWeight, matchSource: "provenance", demoted };
}
if (backendWeight >= 20) {
return { tier: 4, score: -backendWeight, matchSource: "claim_or_decision", demoted };
}
// No backend weight — fall back to pure resolver scoring
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 };
}
/**
* Full sort key: (tier, sub-score, structural-boost, name, id).
*/
export function searchSort(
a: { node: any; rank: { tier: number; score: number; matchSource: string } },
b: { node: any; rank: { tier: number; score: number; matchSource: string } }
): number {
if (a.rank.tier !== b.rank.tier) return a.rank.tier - b.rank.tier;
if (a.rank.score !== b.rank.score) return a.rank.score - b.rank.score;
// Within same tier: structural kinds first
const aStructural = STRUCTURAL_KINDS.has((a.node.kind || "").toLowerCase()) ? 0 : 1;
const bStructural = STRUCTURAL_KINDS.has((b.node.kind || "").toLowerCase()) ? 0 : 1;
if (aStructural !== bStructural) return aStructural - bStructural;
const aName = (a.node.name || a.node.attrs?.name || "").toLowerCase();
const bName = (b.node.name || b.node.attrs?.name || "").toLowerCase();
const byName = aName.localeCompare(bName);
if (byName !== 0) return byName;
// Last resort: node id (plain compare, locale-independent) so fully tied rows
// sort the same whatever order the backend returned them in.
const aId = String(a.node.id ?? "");
const bId = String(b.node.id ?? "");
return aId < bId ? -1 : aId > bId ? 1 : 0;
}
/** Tier 0 through tier 5 — see `rankScore`. */
const TIER_COUNT = 6;
/** The lowest tier: nothing in the name matched, only an attribute did. */
const INCIDENTAL_TIER = 5;
/**
* The tier as a 0-1 relevance, best first.
*
* The internal sort key is negative and "lower is better" — `score=-101` above
* `score=-31` — which is exactly backwards from what every other score an agent
* meets means, and it leaked into `--format json` and `--format llm` as the only
* number on the row. There are six tiers, so each is worth a sixth: 1.00 for an
* exact name and kind, down to 0.17 for a match that came from an attribute.
*
* Deliberately per-tier and not per-row: the sub-score that separates two rows
* inside a tier is a sum of two heuristics with no calibrated meaning, and the
* order it produces is already carried by the order the rows are printed in
* (and by `rank` in JSON). A number that looks more precise than it is invites
* an agent to threshold on it.
*/
export function tierRelevance(tier: number): number {
const clamped = Math.min(Math.max(tier, 0), TIER_COUNT - 1);
return Math.round(((TIER_COUNT - clamped) / TIER_COUNT) * 100) / 100;
}
type Scored = { node: any; rank: { tier: number; score: number; matchSource: string } };
function rowPath(node: any): string {
return normalizePath(node.provenance?.sourceUri ?? node.provenance?.source_uri ?? "");
}
/**
* Drop a chunk row when the symbol it was cut from is already in the answer.
*
* A chunk is a retrieval unit: the ingester emits one per symbol, named after
* that symbol and carrying a `DEFINES` edge to it (core-ingestion
* `patch-builder.ts`). So a search that matches a function by name matches its
* chunk too, and the pair arrives as two rows with the same name and the same
* file — one of which no command can then do anything with, because `explain`,
* `callers` and `read` all want the symbol.
*
* A chunk with no twin survives: an unnamed `file_body:` chunk is the only row
* standing for that part of the file, and dropping it would lose the hit.
*/
export function foldChunkTwins(scored: Scored[]): Scored[] {
const symbols = new Set(
scored
.filter((s) => (s.node.kind || "").toLowerCase() !== "chunk")
.map((s) => `${(s.node.name || "").toLowerCase()}\u0000${rowPath(s.node)}`),
);
if (symbols.size === 0) return scored;
return scored.filter((s) => {
if ((s.node.kind || "").toLowerCase() !== "chunk") return true;
return !symbols.has(`${(s.node.name || "").toLowerCase()}\u0000${rowPath(s.node)}`);
});
}
/**
* Drop the bottom tier once something actually matched by name.
*
* Tier 5 is the resolver's fallback: no part of the name matched and the row is
* here because a term appeared somewhere in the node's attributes. Next to a
* real hit it is filler that pushes a relevant row off the end of `--limit`.
* With nothing better in the set it is the only answer there is, so it stays.
*/
export function dropIncidentalMatches(scored: Scored[]): Scored[] {
const named = scored.some((s) => s.rank.tier < INCIDENTAL_TIER);
return named ? scored.filter((s) => s.rank.tier < INCIDENTAL_TIER) : scored;
}
/** The name tiers: exact name (0-2). A partial name (3) is still a name match, but not a definition. */
const EXACT_NAME_TIER = 2;
/** Tier 4: the row matched on its provenance or a claim about it, not its name. */
const NON_NAME_TIER = 4;
/**
* Drop rows that did not match by name once one matched the name exactly.
*
* Searching `resolveWorkspaceRoot` returned its four definitions and then six
* rows at 0.33 — `absoluteFromSourceUri`, `createStaleProbe` — that matched a
* claim mentioning the term, because they call it. That is a callers answer
* served as a search answer, and an agent looking for a definition read it as
* padding. With no exact name in the set those rows can be the only lead, so
* they stay, marked `match=` in llm output.
*/
export function dropNonNameMatches(scored: Scored[]): Scored[] {
const exact = scored.some((s) => s.rank.tier <= EXACT_NAME_TIER);
return exact ? scored.filter((s) => s.rank.tier < NON_NAME_TIER) : scored;
}
function normalizePath(value: string | undefined): string {
return (value ?? "").toLowerCase().replace(/\\/g, "/");
}
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>")
.description("Search the knowledge graph by term — ranked by structural relevance")
.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>", "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")
.option("--tests-only", "Show only test and fixture entities")
.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.), 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/, *.min.js, *-output.*), fixtures and samples
4. Partial name match
5. Matched on provenance or a claim, not the name — dropped when any of
1-3 matched; marked match=<source> in --format llm
6. Fuzzy/incidental match — dropped when any of 1-5 matched
A chunk is folded away when the symbol it was cut from is already in the answer.
Use --path to filter results from specific directories.
Keyword searches send --path to the backend as a candidate filter (backend 1.0.31+)
and widen the candidate window up to 2000 nodes on older backends.
If that bound is reached, a diagnostic warns that matches may be missing.
Examples:
ix search IngestionService --kind class
ix search auth --language python --limit 10
ix search expand --path memory-layer
ix search "" --kind file --limit 50 --format json`)
.action(async (term: string, opts: {
limit: string; kind?: string; language?: string; path?: string; asOf?: string; format: string; includeTests?: boolean; testsOnly?: boolean; semantic?: boolean
}) => {
const client = createClient();
const limit = parseInt(opts.limit, 10);
// Only an explicit --path scopes results. The active workspace is already
// applied server-side via workspaceId (below), and provenance.sourceUri is
// workspace-RELATIVE, so defaulting this to the absolute getActiveWorkspaceRoot()
// made the substring filter below drop every match (see issue #228).
const effectivePathFilter = opts.path;
// Fetch more results than requested so we can re-rank and trim
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);
const workspaceId = systemId ? undefined : resolveWorkspaceId();
// 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 fetchCandidates = (candidateLimit: number) => opts.semantic
? client.semanticSearch(term, {
limit: candidateLimit,
kind: opts.kind,
workspaceId,
systemId,
})
: client.search(term, {
limit: candidateLimit,
kind: opts.kind,
language: opts.language,
asOfRev: opts.asOf ? parseInt(opts.asOf, 10) : undefined,
workspaceId,
systemId,
// Push --path down as `scope` so a backend that knows the field
// (Ix-memory ≥ 1.0.31) filters candidates BEFORE its limit and the
// window below holds only matching paths (Ix#647: the target sat
// at candidate 71 and 386 and no --limit could reach it). An older
// backend ignores the unknown field, and the client-side filter
// and widening loop below still apply either way. Separators only:
// the backend lowercases both sides itself, and the stored side is
// POSIX by construction (see path-match.ts).
scope: effectivePathFilter ? normalizePathSeparators(effectivePathFilter) : undefined,
});
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));
})
: 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;
// 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, opts.language),
}));
if (!opts.semantic) scored.sort(searchSort);
// Rank, then prune, then cut. Both passes run before `--limit` so a row
// dropped here makes room for a real one instead of leaving a shorter
// answer. Semantic search keeps its own ordering but is pruned the same
// way: a chunk twin is just as useless there.
const hygienic = dropNonNameMatches(dropIncidentalMatches(foldChunkTwins(scored)));
const { filtered: roleFiltered, hiddenTestCount } = applyRoleFilter(
hygienic.map(s => s.node),
{ includeTests: opts.includeTests, testsOnly: opts.testsOnly },
);
// Re-wrap with scores for trimming
const roleFilteredScored = hygienic.filter(s => roleFiltered.includes(s.node));
const trimmed = roleFilteredScored.slice(0, limit);
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",
message: "Results may be broad. Use --kind to filter and boost structural matches.",
});
}
if (hiddenTestCount > 0) {
diagnostics.push({
code: "test_candidates_hidden",
message: roleHint(hiddenTestCount)!,
});
}
// `unfiltered_search` fires on every search that did not pass `--kind`,
// which is most of them, and says the same eighteen words each time
// about results the caller can already see. It stays in JSON, where a
// program may be keyed to it, and stays out of the record stream an
// agent reads.
//
// Taken after every push, not before: `test_candidates_hidden` is the
// one diagnostic here that names rows the caller CANNOT see, and it is
// added below the `unfiltered_search` push.
// Nothing came back at all: before suggesting a better term, ask whether
// there is anything to search. An empty workspace answered "No entity
// name matches. Try part of the name" to every term. One cached stats
// read, only on this path.
if (rawNodes.length === 0 && (workspaceId || systemId)) {
const graph = await checkGraphHealth(client, { workspaceId, systemId });
if (graph.status === "empty") {
diagnostics.push({ code: "workspace_empty", message: WORKSPACE_EMPTY_MESSAGE });
}
}
const workspaceEmpty = diagnostics.some((d) => d.code === "workspace_empty");
const llmDiagnostics = diagnostics.filter((d) => d.code !== "unfiltered_search");
if (opts.format === "llm") {
const rows: SearchLlmRow[] = trimmed.map((s) => ({
name: s.node.name || (s.node.attrs as any)?.name || "(unnamed)",
kind: s.node.kind,
id: s.node.id,
path: relativePath(s.node.provenance?.sourceUri) ?? undefined,
lines: lineSpan(rowLocation(s.node)),
score: tierRelevance(s.rank.tier),
match: s.rank.tier >= NON_NAME_TIER ? s.rank.matchSource : undefined,
}));
const hint = workspaceEmpty ? undefined : emptySearchHint(term, opts);
for (const line of renderSearchLlm(rows, rawNodes.length, llmDiagnostics, hint)) console.log(line);
return;
}
if (opts.format === "json") {
printJson({
results: trimmed.map((s, i) => ({
id: s.node.id,
name: s.node.name || (s.node.attrs as any)?.name || "(unnamed)",
kind: s.node.kind,
path: relativePath(s.node.provenance?.sourceUri) ?? undefined,
language: (s.node.attrs as any)?.language ?? undefined,
rank: i + 1,
tier: s.rank.tier,
score: tierRelevance(s.rank.tier),
matchSource: s.rank.matchSource,
})),
summary: {
count: ranked.length,
totalCandidates: rawNodes.length,
},
diagnostics: ranked.length === 0
? [...diagnostics, { code: "no_results", message: workspaceEmpty ? WORKSPACE_EMPTY_MESSAGE : emptySearchHint(term, opts) }]
: diagnostics,
});
} else {
formatNodes(ranked, opts.format);
if (ranked.length === 0 && !isQuiet()) {
stderr(chalk.dim(workspaceEmpty ? WORKSPACE_EMPTY_MESSAGE : emptySearchHint(term, opts)));
}
if (pathWindowLimited) stderr(chalk.dim(diagnostics.find(d => d.code === "path_search_truncated")!.message));
const hint = roleHint(hiddenTestCount);
if (hint) stderr(chalk.dim(hint));
}
});
}