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
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.tsnew file mode 100644index 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.tsindex 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[]): Prreturn [...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 IDconst 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",