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 { IxClient } from "../../client/api.js";
import { createClient } from "../../client/factory.js";
import { activeReadScope, ensureReadScope } from "../resolve.js";
import { llmLine } from "../llm.js";
import { normalizePathSeparators } from "../path-match.js";
import { printJson } from "../format.js";
import { mapLimit } from "../../client/request-memo.js";
type Metric = "dependents" | "callers" | "importers" | "members";
/** Render `ix rank` as llm records: a header line then one `entity` row per result (rank = line order). */
export function renderRankLlm(
metric: string, kind: string, scope: string | null,
results: Array<{ name: string; kind: string; score: number }>,
evaluated: number, diagnostics: string[],
): string[] {
const lines = [llmLine("rank", [
["metric", metric], ["kind", kind], ["scope", scope ?? undefined],
["evaluated", evaluated], ["returned", results.length],
])];
for (const d of diagnostics) lines.push(llmLine("diagnostic", [["message", d]]));
for (const r of results) {
lines.push(llmLine("entity", [["name", r.name], ["kind", r.kind], ["score", r.score]]));
}
return lines;
}
const METRIC_CONFIG: Record<Metric, { direction: string; predicates: string[] }> = {
dependents: { direction: "in", predicates: ["CALLS", "IMPORTS", "REFERENCES"] },
callers: { direction: "in", predicates: ["CALLS", "REFERENCES"] },
importers: { direction: "in", predicates: ["IMPORTS"] },
members: { direction: "out", predicates: ["CONTAINS"] },
};
const VALID_METRICS = Object.keys(METRIC_CONFIG) as Metric[];
/** Get source URI from a node, checking common locations */
export function getSourceUri(node: any): string {
return (
node.provenance?.sourceUri ??
node.provenance?.source_uri ??
node.attrs?.sourceUri ??
node.attrs?.source_uri ??
""
);
}
/**
* Apply path inclusion and exclusion filters to a list of nodes.
*
* Both sides go through `normalizePathSeparators`, so `--path src\cli` (what a
* Windows user types) matches the `src/cli` that is actually stored. Case is
* left alone — see `path-match.ts` and Ix#636.
*/
export function applyPathFilters(
nodes: any[],
includePath?: string,
excludePath?: string
): any[] {
let result = nodes;
if (includePath) {
const needle = normalizePathSeparators(includePath);
result = result.filter((node: any) => normalizePathSeparators(getSourceUri(node)).includes(needle));
}
if (excludePath) {
const needle = normalizePathSeparators(excludePath);
result = result.filter((node: any) => !normalizePathSeparators(getSourceUri(node)).includes(needle));
}
return result;
}
/** Filter nodes by excluding specified kinds */
export function applyKindExclusion(nodes: any[], excludeKinds: string[]): any[] {
if (excludeKinds.length === 0) return nodes;
const excluded = new Set(excludeKinds);
return nodes.filter((node: any) => !excluded.has(node.kind));
}
/** Pluralize an entity kind for display */
export function pluralize(kind: string): string {
if (kind.endsWith("ss") || kind.endsWith("ch") || kind.endsWith("sh") || kind.endsWith("x")) return kind + "es";
if (kind.endsWith("s")) return kind + "es";
if (kind.endsWith("y") && !/[aeiou]y$/i.test(kind)) return kind.slice(0, -1) + "ies";
return kind + "s";
}
interface ScoredEntity {
id: string;
name: string;
kind: string;
score: number;
}
/**
* Requests in flight while scoring. The same peak load as the old batches of
* 20, but a sliding window: a batch waited for its slowest expand before the
* next one started, so one slow node held nineteen slots idle. Measured on the
* Ix repository's graph (1284 functions): 4.3 s to ~1.9 s, same requests.
*/
const SCORE_CONCURRENCY = 20;
/** Score all candidates, a bounded number at a time, in candidate order. */
async function scoreAllCandidates(
candidates: any[],
config: { direction: string; predicates: string[] },
client: IxClient,
diagnostics: string[],
entityKind: string,
): Promise<ScoredEntity[]> {
const failed = new Array<boolean>(candidates.length).fill(false);
const results = await mapLimit(candidates, SCORE_CONCURRENCY, async (node: any, index): Promise<ScoredEntity> => {
try {
const result = await client.expand(node.id, {
direction: config.direction,
predicates: config.predicates,
});
const seen = new Set<string>();
for (const n of result.nodes) seen.add(n.id);
return {
id: node.id,
name: node.name || node.attrs?.name || "(unnamed)",
kind: node.kind || entityKind,
score: seen.size,
};
} catch {
failed[index] = true;
return {
id: node.id,
name: node.name || node.attrs?.name || "(unnamed)",
kind: node.kind || entityKind,
score: 0,
};
}
});
// In candidate order, not in the order the failures happened to land.
candidates.forEach((node: any, index) => {
if (failed[index]) diagnostics.push(`Failed to expand entity ${node.id}`);
});
return results;
}
export function registerRankCommand(program: Command): void {
program
.command("rank")
.description("Rank entities by graph-derived importance (dependents, callers, importers, members)")
.requiredOption("--by <metric>", `Metric to rank by (${VALID_METRICS.join(", ")})`)
.requiredOption("--kind <kind>", "Entity kind to rank (e.g. class, method, module)")
.option("--top <n>", "Number of results to return", "10")
.option("--path <path>", "Filter entities by source path substring")
.option("--exclude-path <path>", "Exclude entities whose source path contains this substring")
.option("--exclude-kind <kinds>", "Comma-separated kinds to exclude from results")
.option("--format <fmt>", "Output format (text|json|llm)", "text")
.addHelpText(
"after",
`\nExamples:
ix rank --by dependents --kind class --top 10
ix rank --by callers --kind method --top 20
ix rank --by importers --kind module --top 10
ix rank --by members --kind class --top 20
ix rank --by dependents --kind class --path memory-layer --top 10
ix rank --by dependents --kind class --exclude-path test --top 10
ix rank --by dependents --kind class --exclude-kind config_entry --top 10
ix rank --format json --by dependents --kind class`
)
.action(
async (opts: {
by: string;
kind: string;
top: string;
path?: string;
excludePath?: string;
excludeKind?: string;
format: string;
}) => {
const metric = opts.by as Metric;
if (!VALID_METRICS.includes(metric)) {
console.error(
`Error: invalid metric "${opts.by}". Must be one of: ${VALID_METRICS.join(", ")}`
);
process.exit(1);
}
const topN = parseInt(opts.top, 10);
const isJson = opts.format === "json";
const client = createClient();
const diagnostics: string[] = [];
// 1. Fetch all entities of the given kind
await ensureReadScope(client); // fold in a Path-2 stitched system (Ix#225 Half B)
// The backend's scope is a raw AQL CONTAINS against source_uri, which is
// always POSIX — send the separator-normalized needle or a Windows-style
// --path silently matches nothing server-side too (Ix#636).
const scopeNeedle = opts.path ? normalizePathSeparators(opts.path) : undefined;
const allNodes = await client.listByKind(opts.kind, { limit: 2000, scope: scopeNeedle, ...activeReadScope() });
if (allNodes.length === 0) {
if (opts.format === "llm") {
for (const line of renderRankLlm(metric, opts.kind, opts.path ?? null, [], 0, ["No entities found for the given kind."])) console.log(line);
} else if (isJson) {
printJson({
metric,
kind: opts.kind,
scope: opts.path ?? null,
results: [],
summary: { evaluated: 0, totalCandidates: 0, returned: 0 },
diagnostics: ["No entities found for the given kind."],
});
} else {
console.log(chalk.dim("No entities found for the given kind."));
}
return;
}
// 2. Apply path inclusion filter
let candidates = applyPathFilters(allNodes, opts.path, opts.excludePath);
// 3. Apply kind exclusion filter
const excludeKinds = opts.excludeKind ? opts.excludeKind.split(",").map(s => s.trim()) : [];
candidates = applyKindExclusion(candidates, excludeKinds);
if (candidates.length === 0) {
const filterDesc = [
opts.path ? `path "${opts.path}"` : null,
opts.excludePath ? `exclude-path "${opts.excludePath}"` : null,
excludeKinds.length > 0 ? `exclude-kind "${excludeKinds.join(",")}"` : null,
].filter(Boolean).join(", ");
if (opts.format === "llm") {
for (const line of renderRankLlm(metric, opts.kind, opts.path ?? null, [], 0, [`No entities matched filters: ${filterDesc}.`])) console.log(line);
} else if (isJson) {
printJson({
metric,
kind: opts.kind,
scope: opts.path ?? null,
results: [],
summary: { evaluated: 0, totalCandidates: 0, returned: 0 },
diagnostics: [`No entities matched filters: ${filterDesc}.`],
});
} else {
console.log(chalk.dim(`No entities matched filters: ${filterDesc}.`));
}
return;
}
// 4. Score ALL candidates (batched for performance)
const config = METRIC_CONFIG[metric];
const scored = await scoreAllCandidates(candidates, config, client, diagnostics, opts.kind);
// 6. Sort descending, take top N
scored.sort((a, b) => b.score - a.score);
const results = scored.slice(0, topN);
// 7. Output
if (opts.format === "llm") {
for (const line of renderRankLlm(metric, opts.kind, opts.path ?? null, results.map(r => ({ name: r.name, kind: r.kind, score: r.score })), candidates.length, diagnostics)) console.log(line);
} else if (isJson) {
printJson({
metric,
kind: opts.kind,
scope: scopeNeedle,
results: results.map(r => ({ name: r.name, kind: r.kind, score: r.score })),
summary: { evaluated: candidates.length, returned: results.length },
diagnostics: diagnostics.length > 0 ? diagnostics : undefined,
});
} else {
console.log(chalk.bold(`Top ${results.length} ${pluralize(opts.kind)} by ${metric}:`));
const maxNameLen = Math.max(...results.map((r) => r.name.length), 1);
for (let i = 0; i < results.length; i++) {
const r = results[i];
const rank = String(i + 1).padStart(4);
const name = r.name.padEnd(maxNameLen);
console.log(`${rank}. ${name} ${r.score}`);
}
if (diagnostics.length > 0) {
console.log(chalk.dim(`\n${diagnostics.join("\n")}`));
}
}
}
);
}