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 * as fs from "node:fs";
import * as path from "node:path";
import chalk from "chalk";
import type { IxClient } from "../client/api.js";
import { stderr } from "./stderr.js";
import { applyRoleFilter } from "./role-filter.js";
import { detectSystem } from "./system.js";
import { requireReadWorkspaceId, resolveWorkspaceId } from "./bootstrap.js";
import { readStitchScope, resolveWorkspaceRoot, stitchScopeCachePath, writeStitchScope } from "./config.js";
import { ixHome } from "./ix-home.js";
import { checkGraphHealth, isUnhealthy, type GraphHealth } from "./graph-health.js";
import { reportAmbiguousTarget, reportResolutionFailure, reportResolutionNotices } from "./ui.js";
import { relativePath } from "./format.js";
import { isQuiet } from "./output-shape.js";
import { disambiguationHint } from "./next-step.js";
import { explainSymbolMiss, missProbeWouldRun } from "./miss-reason.js";
import { isBackendUnreachable } from "./errors.js";
import {
candidateOrigin, isFileStemMatch, looksLikeCodeIdentifier, requestsNonCode,
} from "./candidate-origin.js";
/**
* The read scope for the current working directory: a co-ingested multi-repo system
* scopes by system_id (spanning all members); otherwise by the single workspace_id.
* Computed once per cwd (detectSystem does FS reads) since a command never changes cwd.
* Mirrors the server-side scoping that search/inventory/stats already apply — without
* it, entity resolution searched the whole backend and a stale absolute path filter
* (getActiveWorkspaceRoot vs. workspace-relative source_uri) dropped every candidate
* (issue #228, originally fixed in search.ts only).
*/
let _scopeCache: {
cwd: string;
workspaceId?: string;
systemId?: string;
stitchChecked?: boolean;
/** scopeKey() when this was computed; a different key means it is stale. */
key: string;
} | undefined;
function mtimeOf(file: string): string {
try {
return String(fs.statSync(file).mtimeMs);
} catch {
return "-";
}
}
/**
* What a cached scope depends on besides the cwd: config.yaml, where `ix map`
* registers a workspace, and the workspace's stitch-scope file, which a map or
* ingest clears. `ix mcp` keeps this cache for the whole session, and the map
* that changes either one usually runs in another process -- an editor hook,
* a terminal -- that resetReadScope() never hears about. Two stats per read.
*/
function scopeKey(workspaceId: string | undefined): string {
const stitch = workspaceId ? mtimeOf(stitchScopeCachePath(workspaceId)) : "-";
return `${mtimeOf(path.join(ixHome(), "config.yaml"))}|${stitch}`;
}
/** The cached scope for `cwd`, if it is still current. */
function currentCache(cwd: string): NonNullable<typeof _scopeCache> | undefined {
if (_scopeCache?.cwd !== cwd) return undefined;
const ws = _scopeCache.workspaceId ?? resolveWorkspaceIdQuiet(cwd);
if (_scopeCache.key !== scopeKey(ws)) return undefined;
return _scopeCache;
}
// The workspace id for the stitch-file part of the key. Only consulted for a
// system-scoped entry, where the cache holds no workspace id of its own.
function resolveWorkspaceIdQuiet(cwd: string): string | undefined {
try {
return resolveWorkspaceId(cwd);
} catch {
return undefined;
}
}
/**
* Drop the cached scope so the next read resolves it again.
*
* The cache is keyed on cwd alone and never expires, which was safe while a
* command's process ended with it. `ix mcp` runs many commands in one
* long-lived process, so it calls this after anything that can change what a
* repo is scoped to — an ingest, or a map that stitches the repo into a System
* server-side. Without it, every later read in the session still answers
* against the pre-map workspace.
*/
export function resetReadScope(): void {
_scopeCache = undefined;
}
export function activeReadScope(): { workspaceId?: string; systemId?: string } {
return activeScope();
}
function activeScope(): { workspaceId?: string; systemId?: string } {
const cwd = process.cwd();
const cached = currentCache(cwd);
if (cached) return cached;
const systemId = detectSystem(cwd)?.systemId;
const workspaceId = systemId ? undefined : resolveWorkspaceId(cwd);
const scope = { cwd, workspaceId, systemId, stitchChecked: false, key: scopeKey(workspaceId) };
// "No workspace here" is never cached: it is exactly the answer an `ix map`
// run elsewhere changes, and recomputing it is a few file reads.
_scopeCache = workspaceId || systemId ? scope : undefined;
return scope;
}
/**
* Make the read scope aware of a Path-2 STITCHED system (Ix#225 Half B): a
* separately-ingested repo has no local system marker (detectSystem returns none),
* but the stitcher may have joined it into a system server-side. Look that up once
* and fold it into the same cache activeScope() reads, so every read that calls
* this (then resolves) spans the whole stitched system — matching `ix map`.
* Best-effort + cached (one lookup per cwd); an older backend or a true singleton
* leaves the scope at workspace level. Read commands `await` this before resolving.
*/
export async function ensureReadScope(
client: Pick<IxClient, "workspaceSystem">,
opts?: { allowUnmapped?: boolean },
): Promise<void> {
await foldStitchedSystem(client);
// A read with neither a workspace nor a system would run unscoped, across
// every workspace on the backend: the same function once per checkout, from
// repositories the caller never asked about. Refused with the fix instead.
// `ix doctor` opts out -- reporting this state is its job, not failing on it.
if (!opts?.allowUnmapped && !_scopeCache?.workspaceId && !_scopeCache?.systemId) {
requireReadWorkspaceId(process.cwd());
}
}
async function foldStitchedSystem(client: Pick<IxClient, "workspaceSystem">): Promise<void> {
const cwd = process.cwd();
if (currentCache(cwd)?.stitchChecked) return;
const localSystem = detectSystem(cwd)?.systemId;
if (localSystem) {
_scopeCache = { cwd, systemId: localSystem, stitchChecked: true, key: scopeKey(resolveWorkspaceIdQuiet(cwd)) };
return;
}
const ws = resolveWorkspaceId(cwd);
let systemId: string | undefined;
if (ws) {
// Disk first. This lookup is ~1.5 s on a large graph and its answer changes
// only when the workspace is mapped or ingested — both of which clear the
// file — so asking the backend once per process was paying it on every
// single `ix` invocation. `null` is a cached answer too: "not stitched" is
// the common case and the one worth not re-asking.
const cached = readStitchScope(ws);
if (cached) {
systemId = cached.systemId ?? undefined;
} else {
try {
const answer = (await client.workspaceSystem(ws)).systemId ?? null;
writeStitchScope(ws, answer);
systemId = answer ?? undefined;
} catch { /* best-effort: leave the scope at workspace level, cache nothing */ }
}
}
// Unmapped: leave nothing cached, so the next read looks again (see activeScope).
_scopeCache = ws || systemId
? { cwd, workspaceId: systemId ? undefined : ws, systemId, stitchChecked: true, key: scopeKey(ws) }
: undefined;
}
/**
* The system_id an aggregate read (inventory/search/stats/smells/subsystems) should
* scope to: a co-ingest system (detectSystem) OR a Path-2 stitched system (backend
* lookup), else undefined (workspace-scoped). Drop-in for `detectSystem(cwd)?.systemId`.
*/
export async function resolveReadSystemId(
client: Pick<IxClient, "workspaceSystem">,
opts?: { allowUnmapped?: boolean },
): Promise<string | undefined> {
await ensureReadScope(client, opts);
return activeReadScope().systemId;
}
export type ResolutionMode = "exact" | "preferred-kind" | "scored" | "ambiguous" | "heuristic" | "fuzzy";
export interface ResolvedEntity {
id: string;
kind: string;
name: string;
path?: string;
resolutionMode: ResolutionMode;
}
export interface AmbiguousResult {
resolutionMode: "ambiguous";
/**
* `container`: the type that holds the candidate (its CONTAINS parent, never
* a file), when the graph names one. Added after the list is ranked.
*/
candidates: Array<{ id: string; name: string; kind: string; path?: string; line?: number; score?: number; rank?: number; container?: string }>;
diagnostics?: Array<{ code: string; message: string }>;
/** How many candidates tied (the candidate list shows at most 8 of them). */
total?: number;
/** True when the search window came back full, so `total` is a lower bound. */
truncated?: boolean;
}
/**
* A resolved target that was a guess worth reporting. The result still resolves
* (exit 0); the notice says which candidates were passed over, or that the
* match was fuzzy. It is never an `error`, so plugin runners see no failure.
*/
export interface ResolutionNotice {
code: "ambiguous_target" | "fuzzy_match";
target: string;
message: string;
chosen: { id: string; name: string; kind: string; path?: string };
candidates: AmbiguousResult["candidates"];
total: number;
truncated?: boolean;
/** Extra diagnostics, e.g. `pick_out_of_range`. */
diagnostics?: Array<{ code: string; message: string }>;
}
/**
* A near-miss worth naming when a target does not resolve.
*
* A miss is a dead end for the caller: an agent that gets "no entity found"
* spends its next turn running `ix search` by hand, and a person retypes the
* name. The candidates are already in hand (or one search away), so they are
* cheaper to hand over than to make the caller ask for.
*/
/**
* What a resolver needs from its caller.
*
* `format` is here so a miss is reported once. The prose ("No entity found
* matching …") goes to stderr for a person; a json or llm caller gets the same
* fact as a record on stdout from `reportUnresolvedTarget`, and printing both
* means an agent running `ix … 2>&1` reads the miss twice.
*/
export interface ResolveOpts {
kind?: string;
path?: string;
pick?: number;
includeTests?: boolean;
testsOnly?: boolean;
searchLimit?: number;
format?: string;
/** Internal: the caller reports the miss itself (a file target's miss). */
silentMiss?: boolean;
/** The command takes `--all`, so an ambiguity's hint names it. */
offerAll?: boolean;
}
export interface Suggestion {
id: string;
name: string;
kind: string;
path?: string;
}
export type ResolveResult =
| { resolved: true; entity: ResolvedEntity; hiddenTestCount?: number; notices?: ResolutionNotice[] }
| { resolved: false; ambiguous: true; result: AmbiguousResult; hiddenTestCount?: number }
| {
resolved: false;
ambiguous: false;
hiddenTestCount?: number;
suggestions?: Suggestion[];
/**
* Why it missed, when that is more than "no such name": a file target
* that is on disk but not in the graph (`file_not_in_graph`), or on
* neither (`file_not_found`). The message then replaces the generic one.
*/
reason?: string;
message?: string;
/** For a symbol miss with a `symbol_*` reason: the files the name appears in. */
files?: string[];
/** Set by the reporter's caller when the graph itself is empty or degraded. */
graph?: GraphHealth;
};
// ── Structural kind sets ──────────────────────────────────────────────────
/** High-value container kinds — typically what callers want when resolving a bare name. */
const CONTAINER_KINDS = new Set(["file", "class", "object", "trait", "interface", "module"]);
/** All kinds that represent real code structure (vs. config/doc/decision). */
const STRUCTURAL_KINDS = new Set([
...CONTAINER_KINDS, "function", "method", "constant",
]);
/**
* Report a miss to a person, once.
*
* Under `--format json|llm` the reporter writes a machine-readable record for
* the same miss on stdout, and an agent almost always runs with `2>&1`, so this
* prose would be a second copy of an answer it already has.
*/
function missProse(opts: ResolveOpts | undefined, message: string): void {
const format = opts?.format;
if (opts?.silentMiss || format === "json" || format === "llm") return;
stderr(message);
}
/** The best few near-misses to offer, newest scoring first, deduped by id. */
function toSuggestions(nodes: any[], limit = 3): Suggestion[] {
const seen = new Set<string>();
const out: Suggestion[] = [];
for (const n of nodes) {
const id = String(n.id ?? "");
if (!id || seen.has(id)) continue;
seen.add(id);
const uri = n.provenance?.sourceUri ?? n.provenance?.source_uri;
out.push({
id,
name: String(n.name ?? n.attrs?.name ?? ""),
kind: String(n.kind ?? ""),
path: uri ? (relativePath(uri) ?? uri) : undefined,
});
if (out.length >= limit) break;
}
return out;
}
function looksTypeLikeSymbol(symbol: string): boolean {
return /^[A-Z][A-Za-z0-9_]*$/.test(symbol);
}
function normalizeForPathMatch(value: string | undefined): string {
return (value ?? "").toLowerCase().replace(/\\/g, "/");
}
// ── Scoring ───────────────────────────────────────────────────────────────
/**
* Score added to a candidate that shares the name but is not the code
* definition (see candidate-origin.ts for how each is recognised).
*
* - An import entity is a single-line `module`: +5 cancels the -3 container
* boost it gets as a `module` and leaves it +2 behind a bare exact match, so
* a same-named function (-1), class (-3) or defining file (0) all beat it.
* - A CSS selector, markdown heading or JSON key (+10, only for a term that
* looks like a code identifier and only when the caller did not ask for that
* kind or language) and a copy in build output, a fixture or a sample (+10)
* land behind the import: an import at least points at the definition. 10
* is enough to put even a PascalCase CSS class (-7 with the type boost)
* behind a same-named function (-1).
*
* A demotion, never a filter — when nothing else shares the name these are
* still the best (and only) answer.
*/
export function originPenalty(
node: any,
symbol: string,
opts?: { kind?: string; language?: string },
): number {
switch (candidateOrigin(node)) {
case "import": return 5;
case "generated": return 10;
case "non-code": return looksLikeCodeIdentifier(symbol) && !requestsNonCode(opts) ? 10 : 0;
default: return 0;
}
}
/**
* Score a candidate node for resolution.
* Lower is better. Combines:
* - exact name match (0), defining-file stem match (3), prefix (15), other (30)
* - exact kind match when --kind provided (-5)
* - strong path match when --path provided (-4)
* - structural kind boost (-3 for container, -1 for method/function)
* - penalty for an import / non-code / generated candidate (originPenalty)
*/
export function scoreCandidate(
node: any,
symbol: string,
opts?: { kind?: string; path?: string; language?: string }
): number {
return baseScore(node, symbol, opts) + originPenalty(node, symbol, opts);
}
/** `scoreCandidate` without the origin penalty: how well the NAME matched. */
export function baseScore(
node: any,
symbol: string,
opts?: { kind?: string; path?: string }
): number {
const name: string = (node.name || node.attrs?.name || "").toLowerCase();
const kind: string = (node.kind || "").toLowerCase();
const symbolLower = symbol.toLowerCase();
const sourceUri = normalizeForPathMatch(node.provenance?.sourceUri ?? node.provenance?.source_uri ?? "");
let score = 50; // baseline
// ── Name match ──────────────────────────────────────────────────────
if (name === symbolLower) {
score = 0; // exact name match — best tier
} else if (isFileStemMatch(node, symbol)) {
// `borderStylesReset.js` for `borderStylesReset`: the file is the
// definition of an anonymous default export. Behind a same-named symbol
// (a function nets -1, this nets 0), ahead of an import of it (+2).
score = 3;
} else if (name.startsWith(symbolLower)) {
score = 15; // prefix match — moderate
} else {
score = 30; // fuzzy / incidental — poor
}
// ── Kind match ──────────────────────────────────────────────────────
if (opts?.kind && kind === opts.kind.toLowerCase()) {
score -= 5; // exact kind requested by user
}
// ── Structural boost ────────────────────────────────────────────────
if (CONTAINER_KINDS.has(kind)) {
score -= 3; // containers are high-value resolution targets
} else if (STRUCTURAL_KINDS.has(kind)) {
score -= 1; // methods/functions are useful but lower than containers
} else if (kind === "chunk") {
score += 5; // chunks are retrieval units, not useful as trace starting points
}
// non-structural kinds (config_entry, doc, decision, etc.) get no boost
if (looksTypeLikeSymbol(symbol) && name === symbolLower) {
if (kind === "class" || kind === "interface" || kind === "trait" || kind === "object") {
score -= 4;
}
// No penalty for method/function: the +3 that was here caused chunks (score=0)
// to outscore structural entities (function/method net score=2) for PascalCase
// names like "Apply", "StartEtcd", "Range". Chunks are now penalised explicitly above.
}
// ── Path match ──────────────────────────────────────────────────────
if (opts?.path) {
const pathLower = normalizeForPathMatch(opts.path);
if (sourceUri.includes(pathLower)) {
// Specificity bonus: a longer/more specific filter string gives a larger
// score reduction, breaking ties when many entities share the same short
// path prefix (e.g. 8 structs named Handle all under "tokio/").
const specificityRatio = pathLower.length / Math.max(sourceUri.length, 1);
score -= 4 + Math.round(specificityRatio * 6); // bonus from 4 to 10
}
}
return score;
}
// ── Public API ────────────────────────────────────────────────────────────
/**
* Resolve a symbol to a single entity, preferring specific kinds and path filters.
* Returns null and prints guidance if no match or ambiguous.
*/
export async function resolveEntity(
client: IxClient,
symbol: string,
preferredKinds: string[],
opts?: ResolveOpts
): Promise<ResolvedEntity | null> {
const result = await resolveEntityFull(client, symbol, preferredKinds, opts);
if (result.resolved) {
if (result.notices?.length) reportResolutionNotices(result.notices, "text", opts);
return result.entity;
}
if (result.ambiguous) {
reportAmbiguousTarget(symbol, result.result, "text", opts);
}
return null;
}
/**
* Full resolution returning structured result for JSON consumers.
*
* Two-phase ranking:
* Phase 1: Score exact-name candidates. If a clear winner exists, return it.
* Phase 2: If no exact-name candidates or still ambiguous, include fuzzy matches.
*/
export async function resolveEntityFull(
client: IxClient,
symbol: string,
preferredKinds: string[],
opts?: ResolveOpts
): Promise<ResolveResult> {
return withContainers(client, await rankEntity(client, symbol, preferredKinds, opts));
}
/**
* `resolveEntityFull` without the candidates' containers: for lookups inside
* the resolver, and for a caller that may re-resolve before it reports (add
* them with `withContainers` on the result it keeps).
*/
export async function rankEntity(
client: IxClient,
symbol: string,
preferredKinds: string[],
opts?: ResolveOpts
): Promise<ResolveResult> {
// Scope is applied server-side (workspace_id, or system_id for a co-ingest). Only an
// EXPLICIT --path narrows further, client-side; we no longer default the path filter
// to the absolute workspace root, which never matched workspace-relative source_uris.
const effectivePath = opts?.path;
await ensureReadScope(client); // fold in a Path-2 stitched system (Ix#225 Half B)
const { workspaceId, systemId } = activeScope();
const kindFilter = opts?.kind;
const searchLimit = opts?.searchLimit ?? (effectivePath ? 200 : looksTypeLikeSymbol(symbol) ? 50 : 30);
let nodes = await client.search(symbol, {
limit: searchLimit,
kind: kindFilter,
nameOnly: true,
workspaceId,
systemId,
});
const windowFull = nodes.length >= searchLimit;
// `--path` is applied client-side, after the backend has cut its
// weight-ordered window. A common name (`add`, `get`) declared in hundreds
// of files can fill that window before the row under --path arrives, and
// the read then misses a name the file plainly declares. Only when the
// window came back full, ask again with the path as `scope`, which the
// backend applies before its limit. An older backend ignores `scope` and
// returns the same window, so the merge changes nothing there.
if (effectivePath && windowFull) {
const scoped = await client.search(symbol, {
limit: searchLimit,
kind: kindFilter,
nameOnly: true,
workspaceId,
systemId,
scope: effectivePath.replace(/\\/g, "/"),
});
nodes = mergeById(nodes, scoped);
}
// The backend orders its window by weight — every exact name before every
// partial one — so when a name is imported in dozens of files, the window is
// all imports and the file that DEFINES it (`borderStylesReset.js`, a
// partial match for `borderStylesReset`) never arrives. Only when the window
// came back full and holds no definition of the name, ask for files by that
// name directly: a handful of rows, merged in and scored like the rest.
if (nodes.length >= searchLimit && (!kindFilter || kindFilter === "file")
&& !hasDefinitionOf(nodes, symbol)) {
const files = await client.search(symbol, {
limit: 20, kind: "file", nameOnly: true, workspaceId, systemId,
});
nodes = mergeById(nodes, files.filter((n: any) => isFileStemMatch(n, symbol)));
}
if (nodes.length === 0) {
// The backend matches names by substring, so a typo (`parseBudgetOptoin`)
// matches nothing -- and re-running without `nameOnly` returns the same
// empty set (measured against a 1.4M-node graph on three terms). What does
// find it is a fragment of the name: one request each for a leading and a
// trailing fragment, ranked by edit distance. Only on this miss path.
missProse(opts, `No entity found matching "${symbol}".`);
const near = await nearestNames(client, symbol, { kind: kindFilter, workspaceId, systemId });
return { resolved: false, ambiguous: false, ...(near.length ? { suggestions: near } : {}) };
}
// Apply role filter before scoring
const { filtered: roleFiltered, hiddenTestCount } = applyRoleFilter(nodes, opts ?? {});
// Hard path filter: when --path is provided, exclude candidates whose sourceUri does not
// contain the filter string. If no candidates survive, return "not found" rather than
// falling back to cross-repo results.
const filteredNodes = effectivePath
? roleFiltered.filter((n: any) => {
const uri = normalizeForPathMatch(n.provenance?.sourceUri ?? n.provenance?.source_uri ?? "");
return uri.includes(normalizeForPathMatch(effectivePath));
})
: roleFiltered;
if (effectivePath && filteredNodes.length === 0) {
missProse(opts, `No entity named "${symbol}" found in paths matching "${effectivePath}".`);
// The name exists — just not under --path. Saying where it does live is the
// whole answer to the question the filter was asking.
const suggestions = toSuggestions(roleFiltered);
return { resolved: false, ambiguous: false, hiddenTestCount, ...(suggestions.length ? { suggestions } : {}) };
}
// ── Phase 1: Exact-name candidates ──────────────────────────────────
const symbolLower = symbol.toLowerCase();
// Prefer case-sensitive exact matches. Fall back to case-insensitive only if none found.
// This prevents e.g. 'Apply' (capital A) from matching lowercase 'apply' module import
// aliases before finding the actual 'Apply' method entities.
// A file whose stem is the symbol counts as an exact name: it is the only
// definition an anonymous default export has, and scoring then puts it
// behind a same-named symbol but ahead of an import of the name. It joins
// whichever set the NAMES chose and never chooses it: `paginator` must fall
// back to the class `Paginator`, not stop at `paginator.py` because only
// the file's stem matched case-sensitively.
const exactCaseSymbols = filteredNodes.filter((n: any) => (n.name || n.attrs?.name || "") === symbol);
const exactName = exactCaseSymbols.length > 0
? [
...exactCaseSymbols,
...filteredNodes.filter((n: any) =>
isFileStemMatch(n, symbol) && (n.name || n.attrs?.name || "").startsWith(symbol)),
]
: filteredNodes.filter((n: any) => {
const name = (n.name || n.attrs?.name || "").toLowerCase();
return name === symbolLower || isFileStemMatch(n, symbol);
});
// Finish a pick: --pick selects among an ambiguous result's candidates, or
// among the candidates a resolved result's notice passed over.
const finish = (winner: ResolveResult): ResolveResult => {
const picked = applyPick(winner, opts);
if (picked) return { ...picked, hiddenTestCount } as ResolveResult;
return { ...pickFromNotice(winner, opts), hiddenTestCount } as ResolveResult;
};
const pickOpts = { ...opts, path: effectivePath, windowFull };
// Score exact-name candidates
if (exactName.length > 0) {
const winner = pickBest(exactName, symbol, preferredKinds, pickOpts);
if (winner) return finish(winner);
}
// ── Phase 2: Fall back to all candidates ────────────────────────────
// No candidate carries the name, so whatever wins is a fuzzy match: it
// resolves (exit 0 as before) but is labelled, and the notice says so.
const winner = pickBest(filteredNodes, symbol, preferredKinds, pickOpts);
if (winner) {
if (winner.resolved) {
const e = winner.entity;
return finish({
...winner,
entity: { ...e, resolutionMode: "fuzzy" },
notices: [fuzzyNotice(symbol, e), ...(winner.notices ?? [])],
});
}
if (winner.ambiguous) {
winner.result.diagnostics = [
...(winner.result.diagnostics ?? []),
{ code: "fuzzy_match", message: `No exact match for ${symbol}; these are fuzzy matches.` },
];
// --pick among fuzzy candidates is still a fuzzy match: keep the label.
const picked = applyPick(winner, opts);
if (picked?.resolved) {
const e = picked.entity;
return {
...picked,
entity: { ...e, resolutionMode: "fuzzy" },
notices: [fuzzyNotice(symbol, e)],
hiddenTestCount,
};
}
}
return finish(winner);
}
// Nothing resolved at all
missProse(opts, `No entity found matching "${symbol}".`);
const suggestions = toSuggestions(filteredNodes);
return { resolved: false, ambiguous: false, hiddenTestCount, ...(suggestions.length ? { suggestions } : {}) };
}
/**
* True when some candidate is a code definition named `symbol` (or its defining file).
*
* Code kinds only: `candidateOrigin` calls anything it cannot place a
* definition, and that includes the `region` nodes `ix map` names after
* directories and modules (`Format`, `Search`, `CLI`, provenance `ix:map`).
* Counting one would skip the lookup for the file that defines the name.
*/
export function hasDefinitionOf(nodes: any[], symbol: string): boolean {
const symbolLower = symbol.toLowerCase();
return nodes.some((n: any) => {
const name = String(n.name || n.attrs?.name || "").toLowerCase();
const sourceUri = String(n.provenance?.sourceUri ?? n.provenance?.source_uri ?? "");
return (name === symbolLower || isFileStemMatch(n, symbol))
&& STRUCTURAL_KINDS.has(String(n.kind || "").toLowerCase())
&& !sourceUri.startsWith("ix:")
&& candidateOrigin(n) === "definition";
});
}
export function mergeById<T extends { id?: unknown }>(base: T[], extra: T[]): T[] {
const seen = new Set(base.map((n) => n.id));
return [...base, ...extra.filter((n) => !seen.has(n.id))];
}
/** Start line of a node, for a stable candidate order. Missing sorts last. */
function lineOf(node: any): number {
const v = Number(node?.attrs?.line_start ?? node?.attrs?.lineStart ?? node?.line_start);
return Number.isFinite(v) ? v : Number.MAX_SAFE_INTEGER;
}
function nodePath(node: any): string {
return normalizeForPathMatch(node?.provenance?.sourceUri ?? node?.provenance?.source_uri ?? node?.path ?? "");
}
function cmpStr(a: string, b: string): number {
return a < b ? -1 : a > b ? 1 : 0;
}
/** Tiebreak for equal candidates: (path, line, id), independent of backend order. */
function displayOrder(a: any, b: any): number {
return cmpStr(nodePath(a), nodePath(b)) || lineOf(a) - lineOf(b) || cmpStr(String(a.id), String(b.id));
}
/**
* A ranked candidate list dealt round-robin by file: the best of each file
* (files in the order of their best), then each file's second-best, and so on.
* Within a file the ranked order stands. Only 8 are listed, and a file that
* defines the name eight times would otherwise fill the page alone, with the
* definitions the caller wants in other files out of sight. This is the order
* the list is numbered in, so `--pick n` and `--all`'s `candidate=<n>` follow it.
* Files compare as lower-cased posix paths, so `src\a.py` and `src/a.py` are one file.
*/
export function roundRobinByFile<T>(ranked: readonly T[], nodeOf: (item: T) => any = (item) => item): T[] {
const files = new Map<string, T[]>();
for (const item of ranked) {
const key = nodePath(nodeOf(item));
const group = files.get(key);
if (group) group.push(item);
else files.set(key, [item]);
}
const groups = [...files.values()];
const dealt: T[] = [];
for (let round = 0; dealt.length < ranked.length; round++) {
for (const group of groups) if (round < group.length) dealt.push(group[round]);
}
return dealt;
}
function entityPath(node: any): string | undefined {
return node.provenance?.sourceUri ?? node.provenance?.source_uri ?? node.path;
}
/** The one-line notice for a target resolved by a fuzzy (non-exact) name. */
function fuzzyNotice(symbol: string, e: ResolvedEntity): ResolutionNotice {
const where = e.path ? ` (${e.path})` : "";
return {
code: "fuzzy_match",
target: symbol,
message: `No exact match for ${symbol}; using fuzzy match ${e.name}${where}`,
chosen: { id: e.id, name: e.name, kind: e.kind, path: e.path },
candidates: [{ id: e.id, name: e.name, kind: e.kind, path: e.path, rank: 1 }],
total: 1,
};
}
/**
* The notice for a pick among equal candidates: resolved, but say what else
* tied. `tier` is only the candidates at the chosen one's score (the true
* ties); `lowerCount` is how many more scored close but worse. Those are only
* counted in the message, so `total`, the listed candidates and `--pick n` all
* describe the same set.
*/
function tieNotice(
symbol: string,
chosen: any,
tier: Array<{ node: any; score: number }>,
windowFull: boolean | undefined,
lowerCount = 0,
): ResolutionNotice {
const amb = buildAmbiguous(tier.map((s) => s.node), tier.map((s) => s.score), {
total: tier.length,
truncated: windowFull,
});
const where = entityPath(chosen);
const lower = lowerCount > 0
? ` ${lowerCount} more scored lower and ${lowerCount === 1 ? "is" : "are"} not listed.`
: "";
const notice: ResolutionNotice = {
code: "ambiguous_target",
target: symbol,
message: `"${symbol}" matches ${windowFull ? "at least " : ""}${tier.length} candidates equally; using ${chosen.name || symbol}${where ? ` (${where})` : ""}.${lower}`,
chosen: { id: chosen.id, name: chosen.name || chosen.attrs?.name || symbol, kind: chosen.kind ?? "", path: where },
candidates: amb.candidates,
total: tier.length,
...(windowFull ? { truncated: true } : {}),
};
rememberAll(notice, amb.candidates, allCandidatesOf(amb), importIdsOf(amb));
return notice;
}
/**
* Given a candidate set, score them, dedup, and either pick a winner or declare ambiguity.
*/
function pickBest(
candidates: any[],
symbol: string,
preferredKinds: string[],
opts?: { kind?: string; path?: string; windowFull?: boolean }
): ResolveResult | null {
// Score all candidates
const scored = candidates.map(n => ({
node: n,
score: scoreCandidate(n, symbol, opts),
}));
const kindRank = (n: any) => {
const idx = preferredKinds.indexOf(n.kind);
return idx >= 0 ? idx : preferredKinds.length;
};
// Sort by score ascending (lower = better); ties by preferred kind, then by
// (path, line, id) so the pick never depends on the order the backend sent.
scored.sort((a, b) => {
if (a.score !== b.score) return a.score - b.score;
return kindRank(a.node) - kindRank(b.node) || displayOrder(a.node, b.node);
});
// Dedup by id
const seen = new Set<string>();
const unique = scored.filter(s => {
if (seen.has(s.node.id)) return false;
seen.add(s.node.id);
return true;
});
if (unique.length === 0) return null;
// If the best candidate has a clearly better score than the second, it wins
const best = unique[0];
const second = unique[1];
// Single candidate — clear winner
if (unique.length === 1) {
return { resolved: true, entity: nodeToResolved(best.node, symbol, resolutionMode(best, symbol)) };
}
// Best is significantly better than second (score gap >= 3) — winner
if (second && best.score + 3 <= second.score) {
return { resolved: true, entity: nodeToResolved(best.node, symbol, resolutionMode(best, symbol)) };
}
// Check if all top candidates at the same score tier are the same entity
const topScore = best.score;
const topTier = unique.filter(s => s.score === topScore);
const topIds = new Set(topTier.map(s => s.node.id));
if (topIds.size === 1) {
return { resolved: true, entity: nodeToResolved(best.node, symbol, resolutionMode(best, symbol)) };
}
// Candidates within range of the top score: the ambiguous record's list.
const eligible = unique.filter(s => s.score <= topScore + 5);
// A tie rule's notice lists only the true ties (the top score tier); the
// near-misses below it are counted, not presented as equal.
const tied = (mode: ResolutionMode): ResolveResult => ({
resolved: true,
entity: nodeToResolved(best.node, symbol, mode),
notices: [tieNotice(symbol, best.node, topTier, opts?.windowFull, eligible.length - topTier.length)],
});
// If the best candidate ranks strictly higher in the kind preference list than all
// other top-tier candidates, auto-pick it — the preference list is the tiebreaker.
const topTierKindRanks = topTier.map(s => {
const idx = preferredKinds.indexOf((s.node.kind || "").toLowerCase());
return idx >= 0 ? idx : preferredKinds.length;
});
const bestKindRank = topTierKindRanks[0];
if (topTier.length > 1 && topTierKindRanks.every((r, i) => i === 0 || r > bestKindRank)) {
return tied("preferred-kind");
}
// If best is a container kind and second is a method/function, prefer the container
const bestKind = (best.node.kind || "").toLowerCase();
const secondKind = (second.node.kind || "").toLowerCase();
if (CONTAINER_KINDS.has(bestKind) && !CONTAINER_KINDS.has(secondKind)) {
return tied("scored");
}
// If path was provided and best matches path but second doesn't, best wins
if (opts?.path) {
const bestUri = normalizeForPathMatch(best.node.provenance?.sourceUri ?? best.node.provenance?.source_uri ?? "");
const secondUri = normalizeForPathMatch(second.node.provenance?.sourceUri ?? second.node.provenance?.source_uri ?? "");
const pathLower = normalizeForPathMatch(opts.path);
if (bestUri.includes(pathLower) && !secondUri.includes(pathLower)) {
return { resolved: true, entity: nodeToResolved(best.node, symbol, "scored") };
}
}
// Genuinely ambiguous — return only structurally relevant candidates
return {
resolved: false,
ambiguous: true,
result: buildAmbiguous(eligible.map(s => s.node), eligible.map(s => s.score), {
total: eligible.length,
truncated: opts?.windowFull,
}),
};
}
/**
* When --pick is set and the result is ambiguous, select the candidate by 1-based index.
* Returns the resolved result, an error result, or null if --pick is not set.
*/
export function applyPick(
result: ResolveResult,
opts?: { pick?: number }
): ResolveResult | null {
if (opts?.pick == null) return null;
if (result.resolved) return null; // already resolved, no need to pick
if (!result.ambiguous) return null;
// Every tied candidate, the shown 8 first: `--all` numbers past 8 (n=9...)
// and `--pick` must reach them by the same numbers.
const candidates = allCandidatesOf(result.result);
const idx = opts.pick - 1; // convert 1-based to 0-based
if (idx < 0 || idx >= candidates.length) {
const message = `--pick ${opts.pick} is out of range (1-${candidates.length}).`;
stderr(message);
return {
...result,
result: {
...result.result,
diagnostics: [
{ code: "pick_out_of_range", message },
...(result.result.diagnostics ?? []),
],
},
};
}
const picked = candidates[idx];
return {
resolved: true,
entity: {
id: picked.id,
kind: picked.kind,
name: picked.name,
path: picked.path,
resolutionMode: "scored",
},
};
}
/**
* `--pick n` on a resolved result that carries an ambiguous_target notice picks
* among the notice's candidates. Unlike applyPick on an ambiguous result, an
* out-of-range pick keeps the default choice and the exit code stays 0: --pick
* must not create a new non-zero exit.
*/
export function pickFromNotice(
result: ResolveResult,
opts?: { pick?: number },
): ResolveResult {
if (opts?.pick == null || !result.resolved || !result.notices) return result;
const at = result.notices.findIndex((n) => n.code === "ambiguous_target");
if (at < 0) return result;
const notice = result.notices[at];
const candidates = allCandidatesOf(notice);
const idx = opts.pick - 1;
if (idx < 0 || idx >= candidates.length) {
const message = `--pick ${opts.pick} is out of range (1-${candidates.length}).`;
stderr(message);
const notices = result.notices.slice();
notices[at] = { ...notice, diagnostics: [{ code: "pick_out_of_range", message }, ...(notice.diagnostics ?? [])] };
return { ...result, notices };
}
const picked = candidates[idx];
const keepFuzzy = result.entity.resolutionMode === "fuzzy";
return {
...result,
entity: {
id: picked.id,
kind: picked.kind,
name: picked.name,
path: picked.path,
resolutionMode: keepFuzzy ? "fuzzy" : "scored",
},
notices: result.notices
.filter((_, i) => i !== at)
.map((n) => {
if (n.code !== "fuzzy_match") return n;
const where = picked.path ? ` (${picked.path})` : "";
return {
...n,
message: `No exact match for ${n.target}; using fuzzy match ${picked.name}${where}`,
chosen: { id: picked.id, name: picked.name, kind: picked.kind, path: picked.path },
candidates: [{ ...picked, rank: 1 }],
};
}),
};
}
/** "exact" only for a case-sensitive exact name; otherwise the score bands. */
function resolutionMode(scored: { node: any; score: number }, symbol: string): ResolutionMode {
const name = scored.node?.name || scored.node?.attrs?.name || "";
if (scored.score <= 0 && name === symbol) return "exact";
if (scored.score <= 5) return "preferred-kind";
return "scored";
}
// ── Helpers ───────────────────────────────────────────────────────────────
function nodeToResolved(node: any, symbol: string, mode: ResolutionMode): ResolvedEntity {
return {
id: node.id,
kind: node.kind,
name: node.name || node.attrs?.name || symbol,
path: node.provenance?.sourceUri ?? node.provenance?.source_uri ?? node.path,
resolutionMode: mode,
};
}
/**
* Every tied candidate behind an ambiguous result or notice, not only the 8
* shown. Kept beside the object rather than on it, so no json or llm renderer
* that prints the result can leak a list of hundreds. `--all` reads it
* (`allCandidatesOf`): the shown 8 first, numbered as `--pick` numbers them,
* then the rest in display order. `imports` holds the ids of the candidates
* that are imports of the name rather than definitions (candidate-origin.ts),
* which `--all` skips when a definition is listed too.
*/
const fullCandidates = new WeakMap<object, { all: AmbiguousResult["candidates"]; imports: Set<string> }>();
function rememberAll(
owner: object,
shown: AmbiguousResult["candidates"],
all: AmbiguousResult["candidates"],
imports: Set<string> = new Set(),
): void {
const shownIds = new Set(shown.map((c) => c.id));
fullCandidates.set(owner, { all: [...shown, ...all.filter((c) => !shownIds.has(c.id))], imports });
}
/** The full candidate list behind an ambiguous result or notice (falls back to the shown ones). */
export function allCandidatesOf(owner: AmbiguousResult | ResolutionNotice): AmbiguousResult["candidates"] {
return fullCandidates.get(owner)?.all ?? owner.candidates;
}
/** The ids among `allCandidatesOf(owner)` that are imports of the name, not definitions. */
function importIdsOf(owner: object): Set<string> {
return fullCandidates.get(owner)?.imports ?? new Set();
}
/** At most this many names are asked for containers; candidates usually share one. */
const CONTAINER_NAME_LOOKUPS = 3;
/**
* The container lookup is decoration on an answer that is already complete,
* and `/v1/expand-by-name` is not scoped to the workspace: on a large shared
* graph a common name (`get`, `__init__`) can be slow. Past this the rows go
* out without `container` rather than hold up the exit-2 record.
*/
export const CONTAINER_LOOKUP_TIMEOUT_MS = 5_000;
/**
* Name the type that holds each candidate of an ambiguous result: its
* `container`, the CONTAINS parent the graph has for it unless that is a file
* (a top-level definition has none). Eight `crop` rows in one file cannot be
* told apart without it.
*
* Entities carry no container attribute, so it comes from the edges: one
* `/v1/expand-by-name` per distinct candidate name (one in the usual case,
* where every candidate has the name that was asked for), never a request per
* candidate. That endpoint answers for every entity of the name, so only
* edges into a listed candidate are read. Best effort: a backend that cannot
* answer (or not within CONTAINER_LOOKUP_TIMEOUT_MS) leaves the rows as they
* were, and `container` is then absent.
*
* Only the ambiguous record (exit 2) pays for this. A resolved target, a
* `--pick` and a tie notice make no extra request.
*/
export async function withContainers(client: IxClient, result: ResolveResult): Promise<ResolveResult> {
if (result.resolved || !result.ambiguous) return result;
const all = allCandidatesOf(result.result);
const ids = new Set(all.map((c) => c.id));
const names = [...new Set(result.result.candidates.map((c) => c.name).filter(Boolean))].slice(0, CONTAINER_NAME_LOOKUPS);
const answers = await Promise.all(names.map(async (name) => {
try {
return await client.expandByName(name, { direction: "in", predicates: ["CONTAINS"], timeoutMs: CONTAINER_LOOKUP_TIMEOUT_MS });
} catch {
return null;
}
}));
const owners = new Map<string, Set<string>>();
for (const answer of answers) {
if (!answer || !Array.isArray(answer.nodes) || !Array.isArray(answer.edges)) continue;
const byId = new Map(answer.nodes.map((n: any) => [String(n?.id), n]));
for (const e of answer.edges) {
if (e?.predicate !== "CONTAINS" || !ids.has(String(e.dst))) continue;
const parent = byId.get(String(e.src));
const name = parent?.name || parent?.attrs?.name;
if (!name || String(parent.kind ?? "").toLowerCase() === "file") continue;
const set = owners.get(String(e.dst)) ?? new Set<string>();
set.add(String(name));
owners.set(String(e.dst), set);
}
}
// Added in place: the listed rows are the same objects as the head of the
// full list, so `--pick` and the shown page stay one list. Two different
// owners for one candidate is not an answer.
for (const c of all) {
const found = owners.get(c.id);
if (found?.size === 1) c.container = [...found][0];
}
return result;
}
/** Consecutive runs of equal score, in order; no scores is one run. */
function scoreTiers<T extends { score?: number }>(ranked: readonly T[]): T[][] {
const tiers: T[][] = [];
for (const item of ranked) {
const last = tiers[tiers.length - 1];
if (last && last[0].score === item.score) last.push(item);
else tiers.push([item]);
}
return tiers;
}
function buildAmbiguous(
nodes: any[],
scores?: number[],
extra?: { total?: number; truncated?: boolean; diagnostics?: Array<{ code: string; message: string }> },
): AmbiguousResult {
// The caller's ranking dealt round-robin by file within each score tier,
// then the first 8 shown and numbered for --pick. A tier is a run of equal
// scores: spreading never puts a worse score (an import's +5) ahead of a
// better one, so the page is still the 8 best by score. The ranking breaks
// ties by (path, line, id), so `--pick n` means the same thing on every run.
const seen = new Set<string>();
const ranked: Array<{ node: any; score?: number }> = [];
for (let i = 0; i < nodes.length; i++) {
const node = nodes[i] as any;
if (seen.has(node.id)) continue;
seen.add(node.id);
ranked.push({ node, score: scores?.[i] });
}
const dealt = scoreTiers(ranked).flatMap((tier) => roundRobinByFile(tier, (r) => r.node));
const picked = dealt.slice(0, 8);
const candidates: AmbiguousResult["candidates"] = picked.map(({ node, score }, i) => {
const line = lineOf(node);
const rank = i + 1;
return {
id: node.id,
name: node.name || node.attrs?.name || "(unnamed)",
kind: node.kind ?? "",
path: entityPath(node),
...(line !== Number.MAX_SAFE_INTEGER ? { line } : {}),
score,
rank,
};
});
const result: AmbiguousResult = {
resolutionMode: "ambiguous",
candidates,
...(extra?.total != null ? { total: extra.total } : {}),
...(extra?.truncated ? { truncated: true } : {}),
diagnostics: [
{ code: "ambiguous_resolution", message: disambiguationHint("Use --pick <n> or --path to disambiguate.") },
...(extra?.diagnostics ?? []),
],
};
const imports = new Set(ranked.filter(({ node }) => candidateOrigin(node) === "import").map(({ node }) => String(node.id)));
rememberAll(result, candidates, dealt.map(({ node }) => candidateOf(node)), imports);
return result;
}
export function printAmbiguous(symbol: string, result: AmbiguousResult, opts?: { kind?: string; path?: string }): void {
reportAmbiguousTarget(symbol, result, "text", opts);
}
/**
* Print the resolved target before showing results (text mode only).
* Callers should skip this when format === "json" to keep JSON strict.
*/
export function printResolved(target: ResolvedEntity): void {
if (isQuiet()) return;
const shortId = target.id.slice(0, 8);
const modeStr = target.resolutionMode !== "exact"
? chalk.dim(` (${target.resolutionMode})`)
: "";
stderr(`${chalk.dim("Resolved:")} ${chalk.cyan(target.kind)} ${chalk.dim(shortId)} ${chalk.bold(target.name)}${modeStr}\n`);
}
/** Check if a string looks like a raw UUID (not a human-readable name). */
export function isRawId(s: string): boolean {
// Anchored at both ends: a UUID followed by anything else (`<uuid>/../health`)
// is a name to search for, not an id to put into a URL path.
return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(s)
|| /^[0-9a-f]{32,}$/i.test(s);
}
// ── Scoped symbol parsing (e.g. C++ ClassName::methodName) ────────────────
/**
* Convert a CamelCase or PascalCase identifier to snake_case.
* Used to derive a file path hint from a C++/Rust class name.
* Examples: "CompactionJob" → "compaction_job", "DBImpl" → "db_impl"
*/
function camelToSnake(s: string): string {
return s
.replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
.replace(/([a-z\d])([A-Z])/g, '$1_$2')
.toLowerCase();
}
/**
* Parse a scoped symbol like "ClassName::methodName" (C++/Rust/PHP style), or
* the `Class.method` / `Class#method` spellings (JS, Java, Python docs).
* Splits on the *last* separator so nested scopes like `ns::Class::method`
* resolve to `{ className: "ns::Class", methodName: "method" }`. `.` and `#`
* need identifier parts on both sides and a target that is not a file name;
* `allowFileName` lifts the last rule, for `Response.json` once no file of
* that name is found.
*/
function parseScopedSymbol(
symbol: string,
allowFileName = false,
): { className: string; methodName: string; sep: "::" | "." | "#" } | null {
const idx = symbol.lastIndexOf('::');
if (idx >= 1) {
const className = symbol.slice(0, idx);
const methodName = symbol.slice(idx + 2);
if (className && methodName) return { className, methodName, sep: "::" };
return null;
}
if (!allowFileName && looksFileLike(symbol)) return null;
const at = Math.max(symbol.lastIndexOf('#'), symbol.lastIndexOf('.'));
if (at < 1) return null;
const className = symbol.slice(0, at);
const methodName = symbol.slice(at + 1);
if (!/^[A-Za-z_$][\w$]*$/.test(methodName)) return null;
if (!/^[A-Za-z_$][\w$]*([.#][A-Za-z_$][\w$]*)*$/.test(className)) return null;
return { className, methodName, sep: symbol[at] as "." | "#" };
}
/** The separator when `target` is `Class::method`, `Class.method` or `Class#method`, else null. */
export function qualifiedSeparator(target: string): "::" | "." | "#" | null {
return parseScopedSymbol(target)?.sep ?? null;
}
// ── File-first resolution ─────────────────────────────────────────────────
/** Common file extensions that signal the target is file-like, not a symbol name. */
const FILE_EXTENSIONS = new Set([
".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
".scala", ".sc", ".java", ".py", ".rb", ".go", ".rs",
".md", ".mdx", ".rst", ".txt",
".json", ".yaml", ".yml", ".toml", ".ini", ".conf",
".sql", ".graphql", ".gql", ".sh", ".bash",
".html", ".css", ".scss", ".less",
]);
export function looksFileLike(target: string): boolean {
if (target.includes("/") || target.includes("\\")) return true;
const ext = path.extname(target).toLowerCase();
return ext !== "" && FILE_EXTENSIONS.has(ext);
}
/**
* Resolve a target to a graph entity ID, trying file paths first.
*
* Resolution order:
* 1. Raw UUID → return directly
* 2. File-like input → search graph for matching file entity
* 3. Symbol name → use scored resolver
*
* Keeps ambiguity distinct from a genuine miss so machine callers can act on it.
*/
export async function resolveFileOrEntityFull(
client: IxClient,
target: string,
opts?: ResolveOpts
): Promise<ResolveResult> {
return withContainers(client, await rankFileOrEntity(client, target, opts));
}
/** `resolveFileOrEntityFull` without the candidates' containers (`--all` lists none). */
async function rankFileOrEntity(
client: IxClient,
target: string,
opts?: ResolveOpts
): Promise<ResolveResult> {
// 1. Raw UUID
if (isRawId(target)) {
let n: any;
try {
n = (await client.entity(target))?.node;
} catch (err) {
// Only "no such id" is a miss. A backend that is down, refusing or
// erroring is a real error (exit 1), not a missing symbol (exit 3).
if (!isLookupMiss(err)) throw err;
}
// A 200 without a node names nothing too: a miss, not a cli_error.
if (!n || typeof n !== "object") {
missProse(opts, `Entity not found: ${target}`);
return { resolved: false, ambiguous: false };
}
return {
resolved: true,
entity: {
id: target,
kind: n.kind || "unknown",
name: n.name || target,
resolutionMode: "exact",
},
};
}
// 1.5 Short ID prefix (8–31 hex chars, e.g. "aacc3359" from CLI output)
if (/^[0-9a-f]{8,31}$/i.test(target)) {
try {
const fullId = await client.resolvePrefix(target);
const details = await client.entity(fullId);
const n = details.node as any;
return {
resolved: true,
entity: {
id: fullId,
kind: n.kind || "unknown",
name: n.name || target,
resolutionMode: "exact",
},
};
} catch (err) {
// A hex-looking target can still be a symbol name (`deadbeef`), so any
// answer short of an unreachable backend falls through to the name
// search rather than failing a symbol that exists. Unreachable is
// rethrown only because the name search would fail the same way.
if (isBackendUnreachable(err)) throw err;
}
}
// 2. File-like input → try graph file search
if (looksFileLike(target)) {
const fileResult = await tryFileGraphMatch(client, target, opts);
// `Response.json`, `Template.html`, `Tree.go`: a method name can end in a
// file extension. When no file has exactly that name, the qualified
// reading is tried before a weaker file match or a miss; a file that has
// the name still wins.
const dotted = /[\\/]/.test(target) ? null : parseScopedSymbol(target, true);
const namesFile = fileResult?.resolved && fileResult.entity.name.toLowerCase() === target.toLowerCase();
if (fileResult && (!dotted || namesFile)) return fileResult;
if (dotted) {
const qualified = await resolveQualified(client, dotted, opts, true);
if (qualified?.resolved) return qualified;
}
if (fileResult) return fileResult;
// Fall through to symbol resolution
}
// 2.5 Scoped symbol (e.g. "CompactionJob::Run", "ns::Class::method")
const scoped = parseScopedSymbol(target);
if (scoped?.sep === "::") {
// Not found is returned as is (no fall-through to a literal "Foo::Bar" search).
return (await resolveQualified(client, scoped, opts, false))!;
}
// 3. Symbol resolution (handles all entity kinds)
//
// Order is a tie-break, not a filter — an unlisted kind still resolves, it
// just sorts last among equal-scoring candidates. `constant` is here so a
// module-level constant is not ranked behind every config entry and heading
// that happens to share its name (Ix#679).
const allKinds = ["file", "class", "object", "trait", "interface", "module", "method", "function", "constant"];
if (scoped) {
// `Class.method` / `Class#method`: a name stored with a dot (`os.path`)
// resolves literally, so the qualified reading is tried only when the
// literal lookup finds nothing, and only if the class itself is found.
// A literal hit that is only fuzzy (no exact name) does not stop the
// qualified reading, but the qualified one replaces it only where that
// keeps the exit code: a resolved literal is replaced only by a resolved one.
const literal = await rankEntity(client, target, allKinds, { ...opts, silentMiss: true });
if ((literal.resolved || literal.ambiguous) && !isFuzzyResult(literal)) return literal;
const qualified = await resolveQualified(client, scoped, opts, true);
if (qualified?.resolved) return qualified;
if (literal.resolved || literal.ambiguous) return literal;
if (qualified?.ambiguous) return qualified;
missProse(opts, opts?.path
? `No entity named "${target}" found in paths matching "${opts.path}".`
: `No entity found matching "${target}".`);
return literal;
}
if (!looksFileLike(target)) return rankEntity(client, target, allKinds, opts);
// A path is a question about a file. "No entity found" answered it as if it
// were a symbol, which does not say whether the file exists, was never
// ingested, or was mistyped -- three different next steps.
const result = await rankEntity(client, target, allKinds, { ...opts, silentMiss: true });
if (result.resolved || result.ambiguous) return result;
return fileMiss(client, target, opts);
}
/**
* Resolve `Class<sep>method`. For `::` (requireClass false): find the class for
* its source file, then the method boosted toward that file, as before. With
* `requireClass` (the `.`/`#` spellings) the method must be contained by the
* class (its CONTAINS children, else the class's exact source file); a class
* that is not found, found only by a fuzzy match, or holding no such member
* gives null, so a miss never becomes an unlabelled guess.
*/
async function resolveQualified(
client: IxClient,
scoped: { className: string; methodName: string; sep: "::" | "." | "#" },
opts: ResolveOpts | undefined,
requireClass: boolean,
): Promise<ResolveResult | null> {
// Phase A: resolve the class entity to obtain its actual source file path.
// This gives a precise path hint rather than a guess from snake_case conversion.
// The lookup is silent: no "not found" or ambiguity text for the class.
const shortClassName = scoped.className.split(/::|[.#]/).pop()!;
const classResult = await rankEntity(
client,
shortClassName,
['class', 'interface', 'struct', 'trait', 'object', 'function'],
// No kind constraint for the class lookup. For `.`/`#`, --pick selects the
// method, not the class, so it is not spent on the class lookup.
{ ...opts, kind: undefined, silentMiss: true, ...(requireClass ? { pick: undefined } : {}) },
);
// For `.`/`#` the class must exist by name: a fuzzy class (`User` matching
// `UserService`) would turn a miss into a confident wrong answer.
if (requireClass) {
if (isFuzzyResult(classResult)) return null;
// The method must live IN the class. A class name held by several classes
// (ambiguous, or resolved by a tie rule) is still a class that exists: the
// method is looked for in each of them rather than reported as a miss.
if (classResult.resolved) {
const tie = classResult.notices?.find((n) => n.code === "ambiguous_target");
const e = classResult.entity;
const classes = tie ? tie.candidates : [{ id: e.id, name: e.name, kind: e.kind, path: e.path }];
return resolveInClasses(client, scoped, classes, !!tie?.truncated || (tie ? tie.total > tie.candidates.length : false), opts);
}
if (classResult.ambiguous) {
const classes = classResult.result;
return resolveInClasses(client, scoped, classes.candidates,
!!classes.truncated || (classes.total ?? 0) > classes.candidates.length, opts);
}
return null;
}
const classEntity = classResult.resolved ? classResult.entity : null;
// Determine the best path hint: prefer the actual file path from phase A,
// fall back to snake_case conversion of the class name.
let pathHint: string;
if (classEntity?.path) {
// Extract basename without extension (e.g. "/db/flush_job.h" → "flush_job")
const basename = classEntity.path.replace(/\\/g, '/').split('/').pop() ?? '';
pathHint = basename.replace(/\.[^.]+$/, '').toLowerCase();
} else {
// Fallback: CamelCase → snake_case (e.g. "CompactionJob" → "compaction_job")
pathHint = camelToSnake(shortClassName);
}
// Phase B: find the method, boosting candidates in the class's source file.
// Use pathHint (derived from the class entity's actual source file) as the
// path constraint — it is always more specific than the user's broad --path
// workspace filter (e.g. "rocksdb"), so it takes priority.
// Use a higher search limit so that methods in the correct file are not
// pushed out by unrelated Run/Execute methods in other classes.
// We deliberately do NOT force kind=method because some parsers classify
// class methods as kind "function".
const scopedOpts = {
...opts,
path: pathHint, // always use the class-derived hint, not opts?.path
searchLimit: 50,
};
const result = await rankEntity(client, scoped.methodName, ['method', 'function'], scopedOpts);
if (result.resolved) {
// Rewrite the display name to show the full scoped form, as the user typed it
return {
...result,
entity: { ...result.entity, name: `${scoped.className}${scoped.sep}${scoped.methodName}` },
};
}
return result;
}
/** A result that came from resolveEntityFull's fuzzy phase (no exact name). */
export function isFuzzyResult(r: ResolveResult): boolean {
if (r.resolved) {
return r.entity.resolutionMode === "fuzzy" || !!r.notices?.some((n) => n.code === "fuzzy_match");
}
return r.ambiguous && !!r.result.diagnostics?.some((d) => d.code === "fuzzy_match");
}
type Candidate = AmbiguousResult["candidates"][number];
function candidateOf(n: any): Candidate {
const line = lineOf(n);
return {
id: String(n.id),
name: n.name || n.attrs?.name || "",
kind: n.kind ?? "",
path: entityPath(n),
...(line !== Number.MAX_SAFE_INTEGER ? { line } : {}),
};
}
/**
* The members of `cls` named exactly `memberName`. Containment comes from the
* graph: the class's CONTAINS children. Only when the graph has no CONTAINS
* children for the class (or cannot be asked) does it fall back to the same
* source file, compared exactly, never as a substring: `a/config.ts` is not
* `xa/config.ts`.
*/
async function membersOf(
client: IxClient,
cls: { id: string; path?: string },
memberName: string,
): Promise<{ found: Candidate[]; truncated: boolean }> {
const named = (n: any) => n && String(n.id) !== cls.id && (n.name || n.attrs?.name) === memberName;
let children: any[] | null;
try {
const expanded = await client.expand(cls.id, { direction: "out", predicates: ["CONTAINS"] });
children = Array.isArray(expanded?.nodes) ? expanded.nodes.filter((n: any) => String(n?.id) !== cls.id) : null;
} catch {
children = null;
}
if (children && children.length > 0) {
return { found: children.filter(named).map(candidateOf), truncated: false };
}
if (!cls.path) return { found: [], truncated: false };
const classFile = normalizeForPathMatch(cls.path);
const { workspaceId, systemId } = activeScope();
const limit = 50;
const nodes = await client.search(memberName, { limit, nameOnly: true, workspaceId, systemId, scope: cls.path });
const found = nodes
.filter((n: any) => named(n) && nodePath(n) === classFile)
.map(candidateOf);
return { found, truncated: nodes.length >= limit };
}
/**
* `Class.method` / `Class#method`: the method looked up IN each class (one
* class, or every class that holds the name). One method found resolves; several
* are the ambiguous record (exit 1, the same code as the miss this replaces),
* sorted by (path, line, id) and dealt round-robin by file (roundRobinByFile)
* so `--pick n` selects among them. None is null,
* which the caller reports as the miss.
*/
async function resolveInClasses(
client: IxClient,
scoped: { className: string; methodName: string; sep: "::" | "." | "#" },
classes: Candidate[],
classesTruncated: boolean,
opts: ResolveOpts | undefined,
): Promise<ResolveResult | null> {
// Only the listed classes are searched; when more classes tied, the method
// list is a lower bound and is marked truncated.
let truncated = classesTruncated;
const found = new Map<string, Candidate>();
const seenClasses = new Set<string>();
for (const cls of classes) {
if (seenClasses.has(cls.id)) continue;
seenClasses.add(cls.id);
const r = await membersOf(client, cls, scoped.methodName);
if (r.truncated) truncated = true;
for (const c of r.found) if (!found.has(c.id)) found.set(c.id, c);
}
if (found.size === 0) return null;
const display = `${scoped.className}${scoped.sep}${scoped.methodName}`;
const ordered = roundRobinByFile([...found.values()].sort((a, b) =>
cmpStr(normalizeForPathMatch(a.path), normalizeForPathMatch(b.path))
|| (a.line ?? Number.MAX_SAFE_INTEGER) - (b.line ?? Number.MAX_SAFE_INTEGER)
|| cmpStr(a.id, b.id)));
if (ordered.length === 1) {
const only = ordered[0];
return {
resolved: true,
entity: { id: only.id, kind: only.kind, name: display, path: only.path, resolutionMode: "scored" },
};
}
const qualifiedResult: AmbiguousResult = {
resolutionMode: "ambiguous",
candidates: ordered.slice(0, 8).map((c, i) => ({ ...c, rank: i + 1 })),
total: ordered.length,
...(truncated ? { truncated: true } : {}),
diagnostics: [
{ code: "ambiguous_resolution", message: disambiguationHint("Use --pick <n> or --path to disambiguate.") },
],
};
rememberAll(qualifiedResult, qualifiedResult.candidates, ordered);
const ambiguous: ResolveResult = { resolved: false, ambiguous: true, result: qualifiedResult };
const picked = applyPick(ambiguous, opts);
if (picked?.resolved) return { ...picked, entity: { ...picked.entity, name: display } };
return picked ?? ambiguous;
}
/**
* The miss for a file target: on disk but not in the graph, or on neither,
* with the graph's nearest file names as suggestions.
*/
async function fileMiss(client: IxClient, target: string, opts?: ResolveOpts): Promise<ResolveResult> {
const candidates = path.isAbsolute(target)
? [target]
: [path.resolve(resolveWorkspaceRoot(), target), path.resolve(process.cwd(), target)];
const onDisk = candidates.some((p) => { try { return fs.statSync(p).isFile(); } catch { return false; } });
const message = onDisk
? `"${target}" exists on disk but is not in the graph: it has not been ingested yet (run \`ix map\`), ` +
"or it is ignored or of a type Ix does not parse."
: `No file "${target}" in the graph, and none at that path on disk.`;
missProse(opts, message);
const { workspaceId, systemId } = activeScope();
const stem = path.basename(target).replace(/\.[^.]+$/, "");
const near = (await nearestNames(client, stem, { kind: "file", workspaceId, systemId }, (n) => {
const name = String(n.name ?? "");
return name.replace(/\.[^.]+$/, "");
})).filter((sug) => !opts?.path || (sug.path ?? "").toLowerCase().includes(opts.path.toLowerCase()));
return {
resolved: false,
ambiguous: false,
reason: onDisk ? "file_not_in_graph" : "file_not_found",
message,
...(near.length ? { suggestions: near } : {}),
};
}
/** Levenshtein distance, case-insensitive. Small inputs only (names). */
export function editDistance(a: string, b: string): number {
const x = a.toLowerCase();
const y = b.toLowerCase();
if (x === y) return 0;
let prev = Array.from({ length: y.length + 1 }, (_, i) => i);
for (let i = 1; i <= x.length; i++) {
const cur = [i];
for (let j = 1; j <= y.length; j++) {
cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (x[i - 1] === y[j - 1] ? 0 : 1));
}
prev = cur;
}
return prev[y.length];
}
/**
* The graph names closest to `symbol`, for a miss. Two name-only searches, for
* a leading and a trailing fragment (a typo sits in one half or the other),
* then ranked by edit distance and kept only when close enough to be a
* plausible intent. Best-effort: any failure is "no suggestions".
*/
export async function nearestNames(
client: Pick<IxClient, "search">,
symbol: string,
scope: { kind?: string; workspaceId?: string; systemId?: string },
nameOf: (node: any) => string = (n) => String(n.name ?? n.attrs?.name ?? ""),
limit = 3,
): Promise<Suggestion[]> {
if (symbol.length < 4) return [];
const width = Math.max(3, Math.ceil(symbol.length * 0.5));
const fragments = [...new Set([symbol.slice(0, width), symbol.slice(-width)])];
try {
const found = (await Promise.all(fragments.map((term) => client.search(term, {
limit: 30, kind: scope.kind, nameOnly: true, workspaceId: scope.workspaceId, systemId: scope.systemId,
})))).flat();
const maxDistance = Math.max(2, Math.floor(symbol.length / 3));
const ranked = found
.filter((n: any) => n?.id && n.kind !== "chunk")
.map((n: any) => ({ n, d: editDistance(nameOf(n), symbol) }))
.filter(({ d }) => d <= maxDistance)
.sort((a, b) => a.d - b.d
|| Number(!STRUCTURAL_KINDS.has(a.n.kind)) - Number(!STRUCTURAL_KINDS.has(b.n.kind))
|| cmpStr(String(nameOf(a.n)), String(nameOf(b.n)))
|| cmpStr(nodePath(a.n), nodePath(b.n))
|| cmpStr(String(a.n.id), String(b.n.id)));
// One row per name and file: an import of the name in the same file adds nothing.
const seen = new Set<string>();
const unique = ranked.map(({ n }) => n).filter((n: any) => {
const key = `${n.name}|${n.provenance?.sourceUri ?? n.provenance?.source_uri ?? ""}`;
if (seen.has(key)) return false;
seen.add(key);
return true;
});
return toSuggestions(unique, limit);
} catch {
return [];
}
}
export async function resolveFileOrEntity(
client: IxClient,
target: string,
opts?: ResolveOpts,
): Promise<ResolvedEntity | null> {
const result = await resolveFileOrEntityFull(client, target, opts);
if (result.resolved) {
if (result.notices?.length) reportResolutionNotices(result.notices, "text", opts);
return result.entity;
}
if (result.ambiguous) reportAmbiguousTarget(target, result.result, "text", opts);
return null;
}
export async function resolveFileOrReport(
client: IxClient,
target: string,
opts: ResolveOpts | undefined,
format: string,
): Promise<ResolvedEntity | null> {
// The format goes in so the resolver knows whether a person will read its
// prose, or whether the structured record below is the only copy that should
// reach stdout.
const result = await resolveFileOrEntityFull(client, target, { ...opts, format });
if (result.resolved) {
if (result.notices?.length) reportResolutionNotices(result.notices, format, opts);
return result.entity;
}
await reportUnresolved(client, target, result, opts, format);
return null;
}
/**
* Report a target that did not resolve, with the best "why" available: the
* graph is empty or degraded, or (for a symbol) what the workspace's text says
* about the name. Sets the exit code (outcome.ts).
*/
export async function reportUnresolved(
client: IxClient,
target: string,
result: Exclude<ResolveResult, { resolved: true }>,
opts: ResolveOpts | undefined,
format: string,
): Promise<void> {
if (result.ambiguous) {
reportResolutionFailure(target, result, format, opts);
return;
}
// A miss on an empty or hollowed graph is not evidence the name does not
// exist. Only on this path, and cached per backend revision.
const graph = await checkGraphHealth(client, activeScope());
if (isUnhealthy(graph)) {
reportResolutionFailure(target, { ...result, graph }, format, opts);
return;
}
reportResolutionFailure(target, await withMissReason(client, target, result, opts, format), format, opts);
}
/**
* A symbol miss with the reason the workspace's text gives (miss-reason.ts).
* A file target already carries its own; a raw id has no text to look for.
*/
export async function withMissReason<T extends { reason?: string; message?: string; hiddenTestCount?: number }>(
client: IxClient,
target: string,
result: T,
opts: ResolveOpts | undefined,
format: string | undefined,
): Promise<T> {
if (result.reason || isRawId(target) || looksFileLike(target)) return result;
// filteredOut costs a search: not for a probe that is off or out of budget.
if (!missProbeWouldRun(target)) return result;
if (await filteredOut(client, target, result, opts)) return result;
const why = await explainSymbolMiss(client, target, { path: opts?.path, ...activeScope() });
if (!why) return result;
// The resolver already wrote the bare miss for a person; this is the part
// that says what to do about it. Machine formats get it in the record.
if (format !== "json" && format !== "llm") stderr(chalk.dim(why.message));
return { ...result, reason: why.reason, message: why.message, ...(why.files ? { files: why.files } : {}) };
}
/**
* Whether the miss is the filters' doing: `--kind`, `--path` or the test
* filter set aside an entity that does carry the name. The probe judges by
* the text alone, so it would call such a name never extracted and send the
* agent to `ix text`; the plain miss, with its suggestions, is the true
* answer. One unfiltered search, and only when a filter was in play. A failed
* search counts as filtered out: it is no evidence the entity is missing.
*/
async function filteredOut(
client: IxClient,
target: string,
result: { hiddenTestCount?: number },
opts: ResolveOpts | undefined,
): Promise<boolean> {
if (!opts?.kind && !opts?.path && !opts?.testsOnly && !result.hiddenTestCount) return false;
const name = target.split(/::|[.#]/).filter(Boolean).pop() ?? target;
const { workspaceId, systemId } = activeScope();
try {
const nodes = await client.search(name, { limit: 50, nameOnly: true, workspaceId, systemId });
return (nodes as any[]).some((n) => (n?.name || n?.attrs?.name || "") === name);
} catch {
return true;
}
}
/** The entities a command with `--all` runs over. */
export interface TargetSet {
/**
* Under `--all`, each entity's `n` is its `--pick` number in the ambiguity
* list, so numbers can skip a candidate `--all` leaves out (an import).
*/
entities: Array<ResolvedEntity & { n?: number }>;
/**
* Present when `--all` expanded the target to its candidates. `capped`:
* more candidates were listed than `ALL_CANDIDATE_CAP`, so only the first
* ones are answered.
*/
all?: { total: number; truncated?: boolean; capped?: boolean };
}
/**
* The one entity a target resolves to or, under `--all`, every listed
* candidate of an ambiguous one (and of a target that resolved by choosing
* among equal ties). `null` after reporting a miss.
*
* Without `--all`, or with `--pick`, this is `resolveFileOrReport`.
*/
export async function resolveTargetSetOrReport(
client: IxClient,
target: string,
opts: (ResolveOpts & { all?: boolean }) | undefined,
format: string,
): Promise<TargetSet | null> {
const withAll = { ...opts, offerAll: true };
if (!opts?.all || opts.pick !== undefined) {
const entity = await resolveFileOrReport(client, target, withAll, format);
return entity ? { entities: [entity] } : null;
}
// The --all candidate list does not show containers: no request for them.
const result = await rankFileOrEntity(client, target, { ...opts, format });
if (result.resolved) {
const tie = result.notices?.find((n) => n.code === "ambiguous_target");
if (!tie || tie.candidates.length <= 1) {
if (result.notices?.length) reportResolutionNotices(result.notices, format, opts);
return { entities: [result.entity] };
}
return candidateSet(tie, tie.total, tie.truncated);
}
if (result.ambiguous) {
return candidateSet(result.result, result.result.total, result.result.truncated);
}
await reportUnresolved(client, target, result, withAll, format);
return null;
}
/**
* The most candidates one `--all` call answers for. Each is at least one
* backend query (`impact` runs a whole analysis per candidate, one after
* another), so a common name must not turn one call into hundreds of round
* trips; past the cap, `--kind`/`--path` or `--pick` reach the rest.
*/
export const ALL_CANDIDATE_CAP = 25;
/**
* Why an `--all` answer may not cover every candidate, or undefined when it
* does: `ALL_CANDIDATE_CAP` stopped it, or the resolver's search window came
* back full, so names past it were never seen.
*/
export function candidatesCut(set: TargetSet, answered: number, verb: string): string | undefined {
if (!set.all) return undefined;
if (set.all.capped) {
return `${verb} the first ${answered} of ${set.all.total}${set.all.truncated ? "+" : ""} candidates ` +
`(--all answers at most ${ALL_CANDIDATE_CAP}); narrow with --kind or --path, or reach one with --pick <n>.`;
}
if (!set.all.truncated && set.all.total <= answered) return undefined;
return `${verb} ${answered} candidates, but the name search was cut off, so there may be more; ` +
"narrow with --kind or --path to cover the rest.";
}
/**
* The candidates `--all` answers for, each keeping its `--pick` number. An
* import of the name (`from app.utils import clamp`) is listed in an ambiguity
* but is not a definition: when a definition is listed too, the import is
* skipped, since its callers are the definition's. When only imports are
* listed they are still the answer (the same demotion-not-filter rule as
* `originPenalty`).
*/
function candidateSet(owner: AmbiguousResult | ResolutionNotice, total?: number, truncated?: boolean): TargetSet {
const numbered = allCandidatesOf(owner).map((c, i) => ({ c, n: i + 1 }));
const imports = importIdsOf(owner);
const definitions = numbered.filter(({ c }) => !imports.has(c.id));
const kept = definitions.length > 0 ? definitions : numbered;
const skipped = numbered.length - kept.length;
const answered = kept.slice(0, ALL_CANDIDATE_CAP);
return {
entities: answered.map(({ c, n }) => ({ id: c.id, kind: c.kind, name: c.name, path: c.path, resolutionMode: "ambiguous", n })),
all: {
total: Math.max((total ?? numbered.length) - skipped, kept.length),
...(truncated ? { truncated: true } : {}),
...(kept.length > answered.length ? { capped: true } : {}),
},
};
}
/**
* Whether an id lookup failed because the id names nothing: the backend's
* 400/404/410 (`<status>: ...`, see `httpError`) or `resolvePrefix`'s own
* no-match and ambiguous-prefix errors. Anything else -- a refused
* connection, a 5xx, a 401 -- is not evidence about the id.
*/
export function isLookupMiss(err: unknown): boolean {
const message = err instanceof Error ? err.message : String(err);
return /^(400|404|410):/.test(message)
|| message.startsWith("No entity found for prefix:")
|| message.startsWith("Ambiguous prefix ");
}
/**
* Search the graph for a file entity matching the target path or filename.
*
* Tiers, best first:
* quality: 0 the full path: equal to the uri, relative to the cwd, or an
* absolute path ending in it (the longest uri wins); or a
* filename inside --path
* quality: 1 a path suffix on a '/' boundary (`src/index.ts` in `pkg/src/index.ts`)
* quality: 2 a suffix not on a boundary (`li/config.ts`): kept so a path
* that names one file is not sent to the file miss, but
* labelled fuzzy with a fuzzy_match notice (`site/package.json`
* is not `docs-site/package.json`)
* quality: 3 the exact filename
* quality: 4 the filename without its extension
* Within a tier, the shortest uri, then uri, then id. It never returns
* ambiguous (a file target never newly exits 1): equal candidates resolve to
* the first and carry an ambiguous_target notice listing the rest.
*/
async function tryFileGraphMatch(
client: IxClient,
target: string,
opts?: { path?: string; pick?: number },
): Promise<ResolveResult | null> {
const basename = path.basename(target);
const targetHasPath = target.includes("/") || target.includes("\\");
// Explicit --path only (not the absolute workspace root); scope server-side instead.
const effectivePath = opts?.path;
await ensureReadScope(client); // fold in a Path-2 stitched system (Ix#225 Half B)
const { workspaceId, systemId } = activeScope();
// Search for file entities matching the basename
const limit = effectivePath ? 200 : 50;
const nodes = await client.search(basename, {
limit,
kind: "file",
nameOnly: true,
workspaceId,
systemId,
});
// Filter to actual matches. Leading `./` and `../` say where the caller is
// standing, not where the file is, so they are not part of the suffix match.
const targetLower = normalizeForPathMatch(target).replace(/^(\.\.?\/)+/, "");
const basenameLower = basename.toLowerCase();
const basenameNoExt = basename.replace(/\.[^.]+$/, "").toLowerCase();
const normalizedPathHint = normalizeForPathMatch(effectivePath);
const isAbsolute = path.isAbsolute(target) || /^[a-z]:\//.test(targetLower);
let fromCwd = "";
if (targetHasPath && !isAbsolute) {
try { fromCwd = normalizeForPathMatch(path.relative(resolveWorkspaceRoot(), path.resolve(process.cwd(), target))); }
catch { fromCwd = ""; }
}
const matches: Array<{ node: any; quality: number; uri: string; fuzzy?: boolean }> = [];
for (const n of nodes as any[]) {
const name = (n.name || "").toLowerCase();
const uri = normalizeForPathMatch(n.provenance?.sourceUri ?? n.provenance?.source_uri ?? "");
const add = (quality: number, fuzzy = false) => { matches.push({ node: n, quality, uri, fuzzy }); };
if (targetHasPath && (uri === targetLower || (fromCwd && uri === fromCwd))) {
add(0);
} else if (targetHasPath && isAbsolute && uri.includes("/") && targetLower.endsWith("/" + uri)) {
add(0);
}
// Filename match in user-requested path
else if (normalizedPathHint && uri.includes(normalizedPathHint) && name === basenameLower) {
add(0);
}
// Suffix on a '/' boundary
else if (targetHasPath && uri.endsWith("/" + targetLower)) {
add(1);
}
// Suffix that is not on a boundary
// (a target longer than the uri, ending in it on a boundary, is not fuzzy)
else if (targetHasPath && (uri.endsWith(targetLower) || (uri.includes("/") && targetLower.endsWith(uri)))) {
add(2, !targetLower.endsWith("/" + uri));
}
// Exact filename match
else if (name === basenameLower) {
add(3);
}
// Bare name match (no extension)
else if (name.replace(/\.[^.]+$/, "") === basenameNoExt) {
add(4);
}
}
if (matches.length === 0) return null;
// A path names one file. When no node sits at it, a same-named file
// elsewhere is a different file: `docs-site/package.json` resolved to the
// repo-root `package.json` and was answered about with full confidence. The
// miss is reported instead, with that file among its suggestions.
if (targetHasPath && !effectivePath && !matches.some((m) => m.quality <= 2)) return null;
// Quality, then the shortest uri (closer to the root = more prominent; for an
// absolute path the longest, the deepest file it ends in), then uri, then id.
matches.sort((a, b) => {
if (a.quality !== b.quality) return a.quality - b.quality;
const byLength = isAbsolute && a.quality === 0 ? b.uri.length - a.uri.length : a.uri.length - b.uri.length;
return byLength || cmpStr(a.uri, b.uri) || cmpStr(String(a.node.id), String(b.node.id));
});
const best = matches[0];
// The candidates that tie with the best: same tier (and, for an absolute
// path, the same file).
const tied: typeof matches = [];
const seenIds = new Set<string>();
for (const m of matches) {
if (m.quality !== best.quality) break;
if (isAbsolute && best.quality === 0 && m.uri !== best.uri) continue;
if (seenIds.has(m.node.id)) continue;
seenIds.add(m.node.id);
tied.push(m);
}
const entityOf = (m: typeof best, mode: ResolutionMode) => nodeToResolved(m.node, m.node.name || basename, mode);
const fuzzy = !!best.fuzzy;
if (tied.length <= 1) {
if (fuzzy) {
const entity = entityOf(best, "fuzzy");
return { resolved: true, entity, notices: [fuzzyNotice(target, entity)] };
}
return { resolved: true, entity: entityOf(best, best.quality === 0 ? "exact" : "scored") };
}
const truncated = nodes.length >= limit;
const amb = buildAmbiguous(tied.map((m) => m.node), undefined, { total: tied.length, truncated });
const chosen = entityOf(best, fuzzy ? "fuzzy" : "scored");
const notice: ResolutionNotice = {
code: "ambiguous_target",
target,
message: `"${target}" matches ${truncated ? "at least " : ""}${tied.length} files equally; using ${chosen.path ?? chosen.name}.`,
chosen: { id: chosen.id, name: chosen.name, kind: chosen.kind, path: chosen.path },
candidates: amb.candidates,
total: tied.length,
...(truncated ? { truncated: true } : {}),
};
rememberAll(notice, amb.candidates, allCandidatesOf(amb), importIdsOf(amb));
const notices = fuzzy ? [notice, fuzzyNotice(target, chosen)] : [notice];
return pickFromNotice({ resolved: true, entity: chosen, notices }, opts);
}