Skip to content

armgit / Ix

Public Imported from GitHub
0

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

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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.md
index 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) |