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
fix(cli): support path disambiguation in graph queries (#628)
Hiro-Chiba4073fc98bba7
diff --git a/ix-cli/src/cli/__tests__/path-disambiguation.test.ts b/ix-cli/src/cli/__tests__/path-disambiguation.test.tsnew file mode 100644index 00000000..2e87803d--- /dev/null+++ b/ix-cli/src/cli/__tests__/path-disambiguation.test.ts@@ -0,0 +1,82 @@+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import { Command } from "commander";+import { registerCallersCommand } from "../commands/callers.js";+import { registerImpactCommand } from "../commands/impact.js";+import { registerImportsCommand } from "../commands/imports.js";++const { search, expand } = vi.hoisted(() => ({ search: vi.fn(), expand: vi.fn() }));++vi.mock("../../client/api.js", () => ({+ IxClient: class {+ async workspaceSystem() { return { systemId: null }; }+ async search(...args: unknown[]) { return search(...args); }+ async expand(...args: unknown[]) { return expand(...args); }+ },+}));++vi.mock("../config.js", async (importOriginal) => ({+ ...await importOriginal<typeof import("../config.js")>(),+ readStitchScope: () => undefined,+ writeStitchScope: vi.fn(),+}));++vi.mock("../hierarchy.js", async (importOriginal) => ({+ ...await importOriginal<typeof import("../hierarchy.js")>(),+ getSystemPath: async () => [],+ bucketByHierarchy: async () => [],+}));++async function run(command: string, args: string[]) {+ const program = new Command().name("ix").exitOverride();+ registerCallersCommand(program);+ registerImpactCommand(program);+ registerImportsCommand(program);+ const output: string[] = [];+ vi.spyOn(console, "log").mockImplementation((...parts) => { output.push(parts.join(" ")); });+ await program.parseAsync([command, "Duplicate", ...args, "--format", "json"], { from: "user" });+ return JSON.parse(output.join("\n"));+}++describe.each(["impact", "callers", "callees", "imports", "imported-by"])("%s path disambiguation", (command) => {+ let savedExitCode: typeof process.exitCode;++ beforeEach(() => {+ savedExitCode = process.exitCode;+ process.exitCode = undefined;+ search.mockReset().mockResolvedValue([+ { id: "first-id", kind: "function", name: "Duplicate", provenance: { sourceUri: "src/first.ts" } },+ { id: "second-id", kind: "function", name: "Duplicate", provenance: { sourceUri: "src/second.ts" } },+ ]);+ expand.mockReset().mockResolvedValue({+ nodes: command === "impact" ? [] : [{ id: "related-id", kind: "function", name: "Related" }],+ edges: [],+ });+ });++ afterEach(() => {+ process.exitCode = savedExitCode;+ vi.restoreAllMocks();+ });++ it("selects only the candidate matching --path", async () => {+ const output = await run(command, ["--path", "second.ts"]);+ expect(process.exitCode).toBeUndefined();+ expect(output.resolvedTarget).toMatchObject({ name: "Duplicate", kind: "function" });+ expect(expand).toHaveBeenCalled();+ expect(expand.mock.calls.every(([id]) => id === "second-id")).toBe(true);+ });++ it("does not silently select a candidate outside --path", async () => {+ const output = await run(command, ["--path", "missing.ts"]);+ expect(process.exitCode).toBe(1);+ expect(output.error).toBe("unresolved_target");+ expect(expand).not.toHaveBeenCalled();+ });++ it("preserves ambiguity when no filter is supplied", async () => {+ const output = await run(command, []);+ expect(process.exitCode).toBe(1);+ expect(output.error).toBe("ambiguous_target");+ expect(expand).not.toHaveBeenCalled();+ });+});diff --git a/ix-cli/src/cli/commands/callers.ts b/ix-cli/src/cli/commands/callers.tsindex 92e4a79d..4922a60a 100644--- a/ix-cli/src/cli/commands/callers.ts+++ b/ix-cli/src/cli/commands/callers.ts@@ -17,14 +17,15 @@ export function registerCallersCommand(program: Command): void {.command("callers <symbol>").description("Show methods/functions that call the given symbol (cross-file)").option("--kind <kind>", "Filter target entity by kind")+ .option("--path <path>", "Filter target entity by file path (substring match)").option("--pick <n>", "Pick Nth candidate from ambiguous results (1-based)", parsePickOption).option("--limit <n>", "Max results to show", "50").option("--format <fmt>", "Output format (text|json|llm)", "text").addHelpText("after", "\nExamples:\n ix callers verify_token\n ix callers processPayment --format json\n ix callers parse --kind method --limit 20")- .action(async (symbol: string, opts: { kind?: string; pick?: number; limit: string; format: string }) => {+ .action(async (symbol: string, opts: { kind?: string; path?: string; pick?: number; limit: string; format: string }) => {const client = new IxClient(getEndpoint());const limit = parseInt(opts.limit, 10);- const resolveOpts = { kind: opts.kind, pick: opts.pick };+ const resolveOpts = { kind: opts.kind, path: opts.path, pick: opts.pick };const target = await resolveFileOrReport(client, symbol, resolveOpts, opts.format);if (!target) return;if (opts.format === "text") printResolved(target);@@ -120,14 +121,15 @@ export function registerCallersCommand(program: Command): void {.command("callees <symbol>").description("Show methods/functions called by the given symbol (cross-file)").option("--kind <kind>", "Filter target entity by kind")+ .option("--path <path>", "Filter target entity by file path (substring match)").option("--pick <n>", "Pick Nth candidate from ambiguous results (1-based)", parsePickOption).option("--limit <n>", "Max results to show", "50").option("--format <fmt>", "Output format (text|json|llm)", "text").addHelpText("after", "\nExamples:\n ix callees processPayment\n ix callees parse --format json")- .action(async (symbol: string, opts: { kind?: string; pick?: number; limit: string; format: string }) => {+ .action(async (symbol: string, opts: { kind?: string; path?: string; pick?: number; limit: string; format: string }) => {const client = new IxClient(getEndpoint());const calleeLimit = parseInt(opts.limit, 10);- const resolveOpts = { kind: opts.kind, pick: opts.pick };+ const resolveOpts = { kind: opts.kind, path: opts.path, pick: opts.pick };const target = await resolveFileOrReport(client, symbol, resolveOpts, opts.format);if (!target) return;if (opts.format === "text") printResolved(target);diff --git a/ix-cli/src/cli/commands/impact.ts b/ix-cli/src/cli/commands/impact.tsindex d1fa6495..837338fb 100644--- a/ix-cli/src/cli/commands/impact.ts+++ b/ix-cli/src/cli/commands/impact.ts@@ -17,6 +17,7 @@ export function registerImpactCommand(program: Command): void {.command("impact <target>").description("System risk analysis — what behavior is at risk if this changes").option("--kind <kind>", "Filter target entity by kind")+ .option("--path <path>", "Filter target entity by file path (substring match)").option("--pick <n>", "Pick Nth candidate from ambiguous results (1-based)", parsePickOption).option("--depth <n>", "Expansion depth for callers/importers (default 1, max 3)", "1").option("--limit <n>", "Max top-impacted members to show", "10")@@ -28,13 +29,13 @@ export function registerImpactCommand(program: Command): void {.action(async (symbol: string,- opts: { kind?: string; pick?: number; depth: string; limit: string; format: string }+ opts: { kind?: string; path?: string; pick?: number; depth: string; limit: string; format: string }) => {const client = new IxClient(getEndpoint());const limit = parseInt(opts.limit, 10);const depth = Math.min(Math.max(parseInt(opts.depth, 10) || 1, 1), 3);- const resolveOpts = { kind: opts.kind, pick: opts.pick };+ const resolveOpts = { kind: opts.kind, path: opts.path, pick: opts.pick };const target = await resolveFileOrReport(client, symbol, resolveOpts, opts.format);if (!target) return;diff --git a/ix-cli/src/cli/commands/imports.ts b/ix-cli/src/cli/commands/imports.tsindex a2b20c8a..027e0fda 100644--- a/ix-cli/src/cli/commands/imports.ts+++ b/ix-cli/src/cli/commands/imports.ts@@ -10,14 +10,15 @@ export function registerImportsCommand(program: Command): void {.command("imports <symbol>").description("Show what the given entity imports").option("--kind <kind>", "Filter target entity by kind")+ .option("--path <path>", "Filter target entity by file path (substring match)").option("--pick <n>", "Pick Nth candidate from ambiguous results (1-based)", parsePickOption).option("--limit <n>", "Max results to show", "50").option("--format <fmt>", "Output format (text|json|llm)", "text").addHelpText("after", "\nExamples:\n ix imports auth.py\n ix imports IngestionService --format json")- .action(async (symbol: string, opts: { kind?: string; pick?: number; limit: string; format: string }) => {+ .action(async (symbol: string, opts: { kind?: string; path?: string; pick?: number; limit: string; format: string }) => {const client = new IxClient(getEndpoint());const limit = parseInt(opts.limit, 10);- const resolveOpts = { kind: opts.kind, pick: opts.pick };+ const resolveOpts = { kind: opts.kind, path: opts.path, pick: opts.pick };const target = await resolveFileOrReport(client, symbol, resolveOpts, opts.format);if (!target) return;if (opts.format === "text") printResolved(target);@@ -29,14 +30,15 @@ export function registerImportsCommand(program: Command): void {.command("imported-by <symbol>").description("Show what imports the given entity").option("--kind <kind>", "Filter target entity by kind")+ .option("--path <path>", "Filter target entity by file path (substring match)").option("--pick <n>", "Pick Nth candidate from ambiguous results (1-based)", parsePickOption).option("--limit <n>", "Max results to show", "50").option("--format <fmt>", "Output format (text|json|llm)", "text").addHelpText("after", "\nExamples:\n ix imported-by AuthProvider\n ix imported-by io.circe.Json --format json")- .action(async (symbol: string, opts: { kind?: string; pick?: number; limit: string; format: string }) => {+ .action(async (symbol: string, opts: { kind?: string; path?: string; pick?: number; limit: string; format: string }) => {const client = new IxClient(getEndpoint());const limit = parseInt(opts.limit, 10);- const resolveOpts = { kind: opts.kind, pick: opts.pick };+ const resolveOpts = { kind: opts.kind, path: opts.path, pick: opts.pick };const target = await resolveFileOrReport(client, symbol, resolveOpts, opts.format);if (!target) return;if (opts.format === "text") printResolved(target);diff --git a/skills/ix/references/flags.md b/skills/ix/references/flags.mdindex 82abda15..85c6a882 100644--- a/skills/ix/references/flags.md+++ b/skills/ix/references/flags.md@@ -70,6 +70,7 @@ Show methods/functions called by the given symbol (cross-file).| Flag | Value | Default | Effect ||---|---|---|---|| `--kind` | `<kind>` | — | Filter target entity by kind |+| `--path` | `<path>` | — | Filter target entity by file path (substring match) || `--pick` | `<n>` | — | Pick Nth candidate from ambiguous results (1-based) || `--limit` | `<n>` | `50` | Max results to show || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) |@@ -81,6 +82,7 @@ Show methods/functions that call the given symbol (cross-file).| Flag | Value | Default | Effect ||---|---|---|---|| `--kind` | `<kind>` | — | Filter target entity by kind |+| `--path` | `<path>` | — | Filter target entity by file path (substring match) || `--pick` | `<n>` | — | Pick Nth candidate from ambiguous results (1-based) || `--limit` | `<n>` | `50` | Max results to show || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) |@@ -287,6 +289,7 @@ System risk analysis — what behavior is at risk if this changes.| Flag | Value | Default | Effect ||---|---|---|---|| `--kind` | `<kind>` | — | Filter target entity by kind |+| `--path` | `<path>` | — | Filter target entity by file path (substring match) || `--pick` | `<n>` | — | Pick Nth candidate from ambiguous results (1-based) || `--depth` | `<n>` | `1` | Expansion depth for callers/importers (default 1, max 3) || `--limit` | `<n>` | `10` | Max top-impacted members to show |@@ -299,6 +302,7 @@ Show what imports the given entity.| Flag | Value | Default | Effect ||---|---|---|---|| `--kind` | `<kind>` | — | Filter target entity by kind |+| `--path` | `<path>` | — | Filter target entity by file path (substring match) || `--pick` | `<n>` | — | Pick Nth candidate from ambiguous results (1-based) || `--limit` | `<n>` | `50` | Max results to show || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) |@@ -310,6 +314,7 @@ Show what the given entity imports.| Flag | Value | Default | Effect ||---|---|---|---|| `--kind` | `<kind>` | — | Filter target entity by kind |+| `--path` | `<path>` | — | Filter target entity by file path (substring match) || `--pick` | `<n>` | — | Pick Nth candidate from ambiguous results (1-based) || `--limit` | `<n>` | `50` | Max results to show || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) |