Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

feat: add ix locate and ix explain commands

riley02273f7cfd3acc72
diff --git a/ix-cli/src/cli/commands/explain.ts b/ix-cli/src/cli/commands/explain.ts
new file mode 100644
index 00000000..c1410a3b
--- /dev/null
+++ b/ix-cli/src/cli/commands/explain.ts
@@ -0,0 +1,62 @@
+import type { Command } from "commander";
+import { IxClient } from "../../client/api.js";
+import { getEndpoint } from "../config.js";
+import { formatExplain, type ExplainResult } from "../format.js";
+
+export function registerExplainCommand(program: Command): void {
+ program
+ .command("explain <symbol>")
+ .description("Explain an entity — shows structure, container, and history")
+ .option("--format <fmt>", "Output format (text|json)", "text")
+ .action(async (symbol: string, opts: { format: string }) => {
+ const client = new IxClient(getEndpoint());
+
+ // Step 1: Find the entity
+ const nodes = await client.search(symbol, { limit: 1 });
+ if (nodes.length === 0) {
+ console.log(`No entity found matching "${symbol}".`);
+ return;
+ }
+ const node = nodes[0] as any;
+ const entityId = node.id;
+
+ // Step 2: Get entity details (claims, edges)
+ const details = await client.entity(entityId);
+
+ // Step 3: Get history
+ let history: any = { entityId, chain: [] };
+ try {
+ history = await client.provenance(entityId);
+ } catch { /* no history */ }
+
+ // Step 4: Find container (CONTAINS edge pointing to this entity)
+ const edges = (details.edges ?? []) as any[];
+ const containsEdge = edges.find((e: any) => e.predicate === "CONTAINS" && e.dst === entityId);
+ let container: any = undefined;
+ if (containsEdge) {
+ try {
+ const containerDetails = await client.entity(containsEdge.src);
+ container = containerDetails.node;
+ } catch { /* no container */ }
+ }
+
+ // Step 5: Count connections
+ const callEdges = edges.filter((e: any) => e.predicate === "CALLS");
+ const containedEdges = edges.filter((e: any) => e.predicate === "CONTAINS" && e.src === entityId);
+
+ const result: ExplainResult = {
+ kind: node.kind,
+ name: node.attrs?.name ?? node.name ?? symbol,
+ id: entityId,
+ file: node.provenance?.source_uri ?? node.provenance?.sourceUri,
+ container: container ? { kind: container.kind, name: container.attrs?.name ?? container.name } : undefined,
+ introducedRev: node.createdRev ?? node.created_rev,
+ calledBy: callEdges.filter((e: any) => e.dst === entityId).length,
+ calls: callEdges.filter((e: any) => e.src === entityId).length,
+ contains: containedEdges.length,
+ historyLength: (history as any)?.chain?.length ?? 0,
+ };
+
+ formatExplain(result, opts.format);
+ });
+}
diff --git a/ix-cli/src/cli/commands/locate.ts b/ix-cli/src/cli/commands/locate.ts
new file mode 100644
index 00000000..7b6bcfa1
--- /dev/null
+++ b/ix-cli/src/cli/commands/locate.ts
@@ -0,0 +1,79 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { Command } from "commander";
+import { IxClient } from "../../client/api.js";
+import { getEndpoint } from "../config.js";
+import { formatLocateResults, type LocateResult } from "../format.js";
+
+const execFileAsync = promisify(execFile);
+
+export function registerLocateCommand(program: Command): void {
+ program
+ .command("locate <symbol>")
+ .description("Find a symbol in code and resolve to graph entities")
+ .option("--limit <n>", "Max text hits to check", "10")
+ .option("--format <fmt>", "Output format (text|json)", "text")
+ .action(async (symbol: string, opts: { limit: string; format: string }) => {
+ const client = new IxClient(getEndpoint());
+ const limit = parseInt(opts.limit, 10);
+
+ // Step 1: Search the graph for matching entities
+ const graphNodes = await client.search(symbol, { limit: 5 });
+
+ // Step 2: Run ripgrep for text hits
+ let textHits: Array<{ path: string; line: number }> = [];
+ try {
+ const { stdout } = await execFileAsync("rg", [
+ "--json", "--max-count", String(limit),
+ "--no-heading", "--word-regexp",
+ symbol, ".",
+ ], { maxBuffer: 10 * 1024 * 1024 });
+
+ for (const line of stdout.split("\n")) {
+ if (!line.trim()) continue;
+ try {
+ const parsed = JSON.parse(line);
+ if (parsed.type === "match") {
+ textHits.push({
+ path: parsed.data.path?.text ?? "",
+ line: parsed.data.line_number ?? 0,
+ });
+ }
+ } catch { /* skip */ }
+ }
+ } catch (err: any) {
+ if (err.code !== 1 && err.status !== 1 && err.code !== "ENOENT") throw err;
+ }
+
+ // Step 3: Build results — graph entities first, then unmatched text hits
+ const results: LocateResult[] = [];
+ for (const node of graphNodes) {
+ const n = node as any;
+ results.push({
+ kind: n.kind,
+ id: n.id,
+ name: n.attrs?.name ?? n.name ?? symbol,
+ file: n.provenance?.source_uri ?? n.provenance?.sourceUri,
+ source: "graph",
+ });
+ }
+
+ // Add text-only hits that didn't match any graph entity
+ const graphFiles = new Set(results.map(r => r.file).filter(Boolean));
+ const seenPaths = new Set<string>();
+ for (const hit of textHits) {
+ if (!seenPaths.has(hit.path) && !graphFiles.has(hit.path)) {
+ seenPaths.add(hit.path);
+ results.push({
+ kind: "text-match",
+ name: symbol,
+ file: hit.path,
+ line: hit.line,
+ source: "ripgrep",
+ });
+ }
+ }
+
+ formatLocateResults(results, opts.format);
+ });
+}
diff --git a/ix-cli/src/cli/format.ts b/ix-cli/src/cli/format.ts
index 1c030095..12f39da5 100644
--- a/ix-cli/src/cli/format.ts
+++ b/ix-cli/src/cli/format.ts
@@ -240,6 +240,34 @@ export function formatTextResults(results: TextResult[], format: string): void {
}
}
+export interface LocateResult {
+ kind: string;
+ id?: string;
+ name: string;
+ file?: string;
+ line?: number;
+ source: "graph" | "ripgrep";
+}
+
+export function formatLocateResults(results: LocateResult[], format: string): void {
+ if (format === "json") {
+ console.log(JSON.stringify(results, null, 2));
+ return;
+ }
+ if (results.length === 0) {
+ console.log("No matches found.");
+ return;
+ }
+ for (const r of results) {
+ const shortId = r.id ? chalk.dim(r.id.slice(0, 8)) + " " : "";
+ const filePart = r.file ? chalk.dim(r.file) + (r.line ? chalk.cyan(`:${r.line}`) : "") : "";
+ console.log(` ${chalk.cyan(r.kind)} ${shortId}${chalk.bold(r.name)}`);
+ if (filePart) {
+ console.log(` ${filePart}`);
+ }
+ }
+}
+
export function formatConflicts(conflicts: any[], format: string): void {
if (format === "json") {
console.log(JSON.stringify(conflicts, null, 2));
@@ -255,3 +283,36 @@ export function formatConflicts(conflicts: any[], format: string): void {
console.log(` Claims: ${c.claimA} vs ${c.claimB}`);
}
}
+
+export interface ExplainResult {
+ kind: string;
+ name: string;
+ id: string;
+ file?: string;
+ container?: { kind: string; name: string };
+ introducedRev: number;
+ calledBy: number;
+ calls: number;
+ contains: number;
+ historyLength: number;
+}
+
+export function formatExplain(result: ExplainResult, format: string): void {
+ if (format === "json") {
+ console.log(JSON.stringify(result, null, 2));
+ return;
+ }
+ const shortId = result.id.slice(0, 8);
+ console.log(` ${chalk.cyan(result.kind)} ${chalk.bold(result.name)} ${chalk.dim(shortId)}`);
+ if (result.container) {
+ console.log(` ${chalk.dim("in")} ${chalk.cyan(result.container.kind)} ${result.container.name}`);
+ }
+ if (result.file) {
+ console.log(` ${chalk.dim("file")} ${result.file}`);
+ }
+ console.log(` ${chalk.dim("introduced rev")} ${result.introducedRev}`);
+ if (result.calledBy > 0) console.log(` ${chalk.dim("called by")} ${result.calledBy} methods`);
+ if (result.calls > 0) console.log(` ${chalk.dim("calls")} ${result.calls} methods`);
+ if (result.contains > 0) console.log(` ${chalk.dim("contains")} ${result.contains} members`);
+ if (result.historyLength > 0) console.log(` ${chalk.dim("history")} ${result.historyLength} patches`);
+}
diff --git a/ix-cli/src/cli/main.ts b/ix-cli/src/cli/main.ts
index 6502e9b6..7a357dac 100644
--- a/ix-cli/src/cli/main.ts
+++ b/ix-cli/src/cli/main.ts
@@ -15,6 +15,8 @@ import { registerDiffCommand } from "./commands/diff.js";
import { registerInitCommand } from "./commands/init.js";
import { registerMcpInstallCommand } from "./commands/mcp-install.js";
import { registerTextCommand } from "./commands/text.js";
+import { registerLocateCommand } from "./commands/locate.js";
+import { registerExplainCommand } from "./commands/explain.js";
const program = new Command();
program
@@ -37,6 +39,8 @@ registerDiffCommand(program);
registerInitCommand(program);
registerMcpInstallCommand(program);
registerTextCommand(program);
+registerLocateCommand(program);
+registerExplainCommand(program);
program
.command("mcp-start")