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
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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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")