Skip to content

armgit / Ix

Public Imported from GitHub
0

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

perf(context): overlap the independent reads in collectFacts

KageBinary024125cf024c
diff --git a/ix-cli/src/cli/__tests__/facts-concurrency.test.ts b/ix-cli/src/cli/__tests__/facts-concurrency.test.ts
new file mode 100644
index 00000000..7ce48b2a
--- /dev/null
+++ b/ix-cli/src/cli/__tests__/facts-concurrency.test.ts
@@ -0,0 +1,88 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+import { describe, expect, it } from "vitest";
+
+import type { IxClient } from "../../client/api.js";
+import { collectFacts } from "../explain/facts.js";
+
+/**
+ * `collectFacts` runs its second round of reads -- the container, the target's
+ * members, the neighbouring files' members -- together, and the neighbouring
+ * files together with each other. What it returns must not depend on which
+ * read finished first. The fake graph below answers the FIRST file slowest, so
+ * a result assembled in completion order would come out reversed.
+ */
+const TARGET = "t";
+const FILES = ["f1", "f2", "f3"];
+
+function node(id: string, kind: string, line = 1) {
+ return { id, name: id, kind, attrs: { line_start: line, line_end: line + 9 }, provenance: { sourceUri: `src/${id}.ts` } };
+}
+
+function slowFirstClient(): { client: IxClient; inFlightPeak: () => number } {
+ let inFlight = 0;
+ let peak = 0;
+ const delay = (id: string) => (id.startsWith("f1") ? 30 : id.startsWith("f2") ? 15 : 1);
+ const answer = async <T>(id: string, value: T): Promise<T> => {
+ inFlight++;
+ peak = Math.max(peak, inFlight);
+ await new Promise((resolve) => setTimeout(resolve, delay(id)));
+ inFlight--;
+ return value;
+ };
+ const client = {
+ async entity(id: string) {
+ return answer(id, {
+ node: node(id, "function"),
+ claims: [],
+ edges: id === TARGET ? [{ src: "container", dst: TARGET, predicate: "CONTAINS" }] : [],
+ });
+ },
+ async expand(id: string, opts?: { direction?: string; predicates?: string[] }) {
+ const preds = opts?.predicates ?? [];
+ if (id === TARGET && opts?.direction === "out" && preds[0] === "IMPORTS") {
+ return answer(id, { nodes: FILES.map((f) => node(f, "file")), edges: [] });
+ }
+ if (FILES.includes(id) && opts?.direction === "out" && preds[0] === "CONTAINS") {
+ // Two functions per file; the second one is longer, so it leads the
+ // structural order and the ranking has something to reorder.
+ return answer(id, { nodes: [node(`${id}.a`, "function", 1), node(`${id}.b`, "function", 20)], edges: [] });
+ }
+ if (opts?.direction === "in" && preds.includes("CALLS") && preds.includes("IMPORTS") && id.includes(".")) {
+ // Use counts: `.a` is used from two files, `.b` from one.
+ const users = id.endsWith(".a")
+ ? [node(`u1-${id}`, "function"), { ...node(`u2-${id}`, "function"), provenance: { sourceUri: "src/elsewhere.ts" } }]
+ : [node(`u1-${id}`, "function")];
+ return answer(id, { nodes: users, edges: [] });
+ }
+ return answer(id, { nodes: [], edges: [] });
+ },
+ async provenance(id: string) {
+ return answer(id, { entityId: id, chain: [] });
+ },
+ } as unknown as IxClient;
+ return { client, inFlightPeak: () => peak };
+}
+
+describe("collectFacts with concurrent second-round reads", () => {
+ it("returns neighbour members in file order, whichever file answers first", async () => {
+ const { client, inFlightPeak } = slowFirstClient();
+
+ const facts = await collectFacts(client, TARGET, "t", "function", "context");
+
+ // One member from each file before a second from any, files in import
+ // order, each file's members by measured use (`.a` has more users).
+ expect(facts.neighbourRefs?.map((r) => r.id)).toEqual([
+ "f1.a", "f2.a", "f3.a", "f1.b", "f2.b", "f3.b",
+ ]);
+ expect(facts.container?.id).toBe("container");
+ // The neighbour files really were read together.
+ expect(inFlightPeak()).toBeGreaterThan(1);
+ });
+
+ it("gives the same facts on every run", async () => {
+ const runs = await Promise.all([0, 1, 2].map(() => collectFacts(slowFirstClient().client, TARGET, "t", "function", "context")));
+ const [first, ...rest] = runs.map((f) => JSON.stringify(f));
+ for (const r of rest) expect(r).toBe(first);
+ });
+});
diff --git a/ix-cli/src/cli/explain/facts.ts b/ix-cli/src/cli/explain/facts.ts
index 178717f8..931b5a6b 100644
--- a/ix-cli/src/cli/explain/facts.ts
+++ b/ix-cli/src/cli/explain/facts.ts
@@ -220,8 +220,10 @@ async function collectNeighbourMembers(
const files = neighbours
.filter(ref => ref.kind === "file" && ref.id !== targetId)
.slice(0, MAX_NEIGHBOUR_FILES);
- const found: EntityLocation[][] = [];
- for (const file of files) { // one file at a time: each ranks its own members
+ // Each file ranks its own members, so the files are independent and run
+ // together; `found` stays in file order however they finish. The requests
+ // they make are bounded by the query client's in-flight cap.
+ const found: EntityLocation[][] = await Promise.all(files.map(async (file) => {
try {
const result = await client.expand(file.id, { direction: "out", predicates: ["CONTAINS"] });
const direct = structuralMemberOrder((result.nodes ?? [])
@@ -247,11 +249,11 @@ async function collectNeighbourMembers(
// Ranked by measured use, like the target's own members: by size alone
// `config.ts` offered `saveConfig` (48 lines, 5 users) ahead of
// `resolveWorkspaceRoot` (20 lines, 12 users, and the answer).
- found.push((await rankMembersByUse(client, candidates)).slice(0, MAX_NEIGHBOUR_MEMBERS));
+ return (await rankMembersByUse(client, candidates)).slice(0, MAX_NEIGHBOUR_MEMBERS);
} catch {
- found.push([]); // one unreadable neighbour must not lose the others
+ return []; // one unreadable neighbour must not lose the others
}
- }
+ }));
// One member from each file before a second from any: the evidence budget cut
// the tail, and four members of the first import crowded out every other
// file's -- including the one holding the answer.
@@ -302,6 +304,52 @@ async function rankMembersByUse(client: IxClient, members: EntityLocation[]): Pr
return [...ranked, ...structural.slice(MEMBER_USE_POOL)];
}
+/** The entity that contains the target, or undefined when it cannot be read. */
+async function lookUpContainer(client: IxClient, containerId: string): Promise<EntityLocation | undefined> {
+ try {
+ const containerDetails = await client.entity(containerId);
+ return toLocation(containerDetails.node);
+ } catch {
+ return undefined; // no container
+ }
+}
+
+/** The target's callees by name, one entity read each, in edge order. */
+function resolveCallList(client: IxClient, calleeEdges: any[]): Promise<EntityRef[]> {
+ return Promise.all(
+ calleeEdges.map(async (e: any): Promise<EntityRef> => {
+ try {
+ const callee = await client.entity(e.dst);
+ const calleeNode = callee.node as any;
+ const name = calleeNode.name || calleeNode.attrs?.name || "";
+ if (!name || isRawId(name)) {
+ return {
+ name: name || e.dst,
+ kind: calleeNode.kind,
+ resolved: false,
+ suggestedCommand: `ix text "${e.dst.slice(0, 8)}"`,
+ };
+ }
+ return {
+ name,
+ kind: calleeNode.kind,
+ id: e.dst,
+ resolved: true,
+ path: relativePath(calleeNode.provenance?.source_uri ?? calleeNode.provenance?.sourceUri),
+ suggestedCommand: `ix explain "${name}"`,
+ };
+ } catch {
+ return {
+ name: e.dst,
+ resolved: false,
+ diagnostic: "unresolved_call_target",
+ suggestedCommand: `ix text "${e.dst.slice(0, 8)}"`,
+ } as EntityRef;
+ }
+ }),
+ );
+}
+
/**
* Collect the structural facts about one entity.
*
@@ -362,15 +410,6 @@ export async function collectFacts(
const containsEdge = edges.find(
(e: any) => e.predicate === "CONTAINS" && e.dst === targetId,
);
- let container: EntityLocation | undefined;
- if (containsEdge) {
- try {
- const containerDetails = await client.entity(containsEdge.src);
- container = toLocation(containerDetails.node);
- } catch {
- /* no container */
- }
- }
// Deduplicate dependents by node ID
const seenIds = new Set<string>();
@@ -380,12 +419,6 @@ export async function collectFacts(
return true;
});
- // Members. `ix context` ranks them by use; `ix explain` keeps graph order.
- const memberRefs = forExplain
- ? membersResult.nodes.map(toLocation)
- : await rankMembersByUse(client, membersResult.nodes.map(toLocation));
- const memberNames = memberRefs.map((m) => m.name);
-
// Named usage examples (up to 3 resolved names from callers/dependents)
const extractRefs = (nodes: any[], limit: number): EntityLocation[] => {
const refs: EntityLocation[] = [];
@@ -413,55 +446,37 @@ export async function collectFacts(
Number(a?.kind !== "file") - Number(b?.kind !== "file")),
MAX_IMPORT_REFS);
const calleeRefs = outward(calleesResult.nodes, MAX_CALLEE_REFS);
- // One level into the files around the target -- imports first, then the
- // files that import it. `ix explain` describes one entity and does not need
- // it, so it is not paid for there.
- const neighbourRefs = forExplain
- ? undefined
- : await collectNeighbourMembers(client, [...importRefs, ...topDependentRefs], targetId);
- const topCallers = topCallerRefs.map((r) => r.name);
- const topDependents = topDependentRefs.map((r) => r.name);
// Build callList from outgoing CALLS edges (reuse logic from explain.ts)
const calleeEdges = edges.filter(
(e: any) => e.predicate === "CALLS" && e.src === targetId,
);
- let callList: EntityRef[] | undefined;
- if (forExplain && calleeEdges.length > 0 && calleeEdges.length <= 20) {
- const refs = await Promise.all(
- calleeEdges.map(async (e: any): Promise<EntityRef> => {
- try {
- const callee = await client.entity(e.dst);
- const calleeNode = callee.node as any;
- const name = calleeNode.name || calleeNode.attrs?.name || "";
- if (!name || isRawId(name)) {
- return {
- name: name || e.dst,
- kind: calleeNode.kind,
- resolved: false,
- suggestedCommand: `ix text "${e.dst.slice(0, 8)}"`,
- };
- }
- return {
- name,
- kind: calleeNode.kind,
- id: e.dst,
- resolved: true,
- path: relativePath(calleeNode.provenance?.source_uri ?? calleeNode.provenance?.sourceUri),
- suggestedCommand: `ix explain "${name}"`,
- };
- } catch {
- return {
- name: e.dst,
- resolved: false,
- diagnostic: "unresolved_call_target",
- suggestedCommand: `ix text "${e.dst.slice(0, 8)}"`,
- } as EntityRef;
- }
- }),
- );
- callList = refs;
- const unresolvedCount = refs.filter((r) => !r.resolved).length;
+
+ // The second round of reads. Each step needs only the first round, not the
+ // others, so they run together: this used to be three or four round trips
+ // one after another, plus one per neighbouring file.
+ const [container, memberRefs, neighbourRefs, callList] = await Promise.all([
+ containsEdge ? lookUpContainer(client, containsEdge.src) : Promise.resolve(undefined),
+ // Members. `ix context` ranks them by use; `ix explain` keeps graph order.
+ forExplain
+ ? Promise.resolve(membersResult.nodes.map(toLocation))
+ : rankMembersByUse(client, membersResult.nodes.map(toLocation)),
+ // One level into the files around the target -- imports first, then the
+ // files that import it. `ix explain` describes one entity and does not need
+ // it, so it is not paid for there.
+ forExplain
+ ? Promise.resolve(undefined)
+ : collectNeighbourMembers(client, [...importRefs, ...topDependentRefs], targetId),
+ forExplain && calleeEdges.length > 0 && calleeEdges.length <= 20
+ ? resolveCallList(client, calleeEdges)
+ : Promise.resolve(undefined),
+ ]);
+ const memberNames = memberRefs.map((m) => m.name);
+ const topCallers = topCallerRefs.map((r) => r.name);
+ const topDependents = topDependentRefs.map((r) => r.name);
+
+ if (callList) {
+ const unresolvedCount = callList.filter((r) => !r.resolved).length;
if (unresolvedCount > 0) {
diagnostics.push({
code: "unresolved_call_target",