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(context): say what the neighbouring files define
KageBinary09b6e2b926c7
diff --git a/ix-cli/src/cli/__tests__/context-evidence-locations.test.ts b/ix-cli/src/cli/__tests__/context-evidence-locations.test.tsindex c1c05e99..26c6c869 100644--- a/ix-cli/src/cli/__tests__/context-evidence-locations.test.ts+++ b/ix-cli/src/cli/__tests__/context-evidence-locations.test.ts@@ -185,6 +185,33 @@ describe("ix context evidence says where things are", () => {expect(b.entities.map((e) => e.name)).toContain("resolve.ts");});+ it("names what the neighbouring files define, with where", () => {+ // Members were collected for the target alone, so "which function resolves+ // a workspace" got `config.ts` and nothing inside it: symbol recall was+ // 0.00 on 10 of 11 benchmark tasks even where the right file came back.+ const b = bundle({+ facts: facts({+ importRefs: [{ id: "i-config", name: "config.ts", kind: "file", path: "src/cli/config.ts" }],+ neighbourRefs: [+ { id: "n-resolve", name: "resolveWorkspaceRoot", kind: "function",+ path: "src/cli/config.ts", lineStart: 322, lineEnd: 342 },+ { id: "n-default", name: "getDefaultWorkspace", kind: "function",+ path: "src/cli/config.ts", lineStart: 289, lineEnd: 291 },+ ],+ }),+ });++ const defines = b.evidence.find((e) => e.title === "config.ts defines resolveWorkspaceRoot");+ expect(defines?.location).toEqual({ path: "src/cli/config.ts", lineStart: 322, lineEnd: 342 });+ expect(defines?.refs).toEqual(["n-resolve"]);+ // They are entities, which is what a retrieval score counts as a symbol.+ const names = b.entities.map((e) => e.name);+ expect(names).toContain("resolveWorkspaceRoot");+ expect(names).toContain("getDefaultWorkspace");+ // After the file they came from, so the budget keeps the file first.+ expect(names.indexOf("config.ts")).toBeLessThan(names.indexOf("resolveWorkspaceRoot"));+ });+it("reads provenance from the chain /v1/provenance actually returns", () => {const b = bundle({provenance: {diff --git a/ix-cli/src/cli/__tests__/facts-scope.test.ts b/ix-cli/src/cli/__tests__/facts-scope.test.tsindex 308b2157..c3d991e3 100644--- a/ix-cli/src/cli/__tests__/facts-scope.test.ts+++ b/ix-cli/src/cli/__tests__/facts-scope.test.ts@@ -61,14 +61,19 @@ describe("collectFacts scope", () => {const facts = await collectFacts(fakeClient(calls), TARGET, "config", "function", "context");- // One entity, six fixed expands (the sixth is the outbound IMPORTS the- // bundle navigates by), one provenance -- and nothing that grows with the- // graph.- expect(calls.filter((c) => c.method === "expand")).toHaveLength(6);+ // One entity, six fixed expands on the target (the sixth is the outbound+ // IMPORTS the bundle navigates by), one provenance, and one CONTAINS per+ // neighbouring file -- capped, so nothing here grows with the graph.+ const expands = calls.filter((c) => c.method === "expand");+ expect(expands.filter((c) => c.id === TARGET)).toHaveLength(6);expect(calls.some((c) => c.method === "expand" && c.predicates?.[0] === "IMPORTS"&& c.id === TARGET)).toBe(true);+ // The one neighbour in this graph is the file that imports the target.+ expect(expands.filter((c) => c.id !== TARGET))+ .toEqual([{ method: "expand", id: DEPENDENT, predicates: ["CONTAINS"], hops: undefined }]);+ // No entity lookups beyond the target, and no hierarchy walk: the+ // neighbour hop is expands only, and bounded.expect(calls.filter((c) => c.method === "entity").map((c) => c.id)).toEqual([TARGET]);- expect(calls.some((c) => c.id === DEPENDENT)).toBe(false);expect(calls.some((c) => c.predicates?.includes("IN_REGION"))).toBe(false);expect(facts.topDependents).toEqual(["user"]);@@ -138,6 +143,37 @@ function fileWithMembers(} as unknown as IxClient;}+describe("neighbour members", () => {+ it("takes one member from each neighbouring file before a second from any", async () => {+ // The evidence budget cuts the tail, and four members of the first import+ // crowded out every other file's -- including the file with the answer.+ const files = ["f-a", "f-b"];+ const client = {+ async entity(id: string) {+ return { node: { id, name: "entry.ts", kind: "file", attrs: {}, provenance: { sourceUri: "src/entry.ts" } }, edges: [] };+ },+ async expand(id: string, opts?: { direction?: string; predicates?: string[] }) {+ if (id === TARGET && opts?.direction === "out" && opts.predicates?.includes("IMPORTS")) {+ return { nodes: files.map((f, i) => ({ id: f, name: `dep${i}.ts`, kind: "file", attrs: {},+ provenance: { sourceUri: `src/dep${i}.ts` } })), edges: [] };+ }+ if (files.includes(id)) {+ const which = id.slice(-1);+ return { nodes: [1, 2, 3].map(n => ({ id: `${id}-m${n}`, name: `${which}${n}`, kind: "function",+ attrs: { line_start: n * 10, line_end: n * 10 + 9 - n },+ provenance: { sourceUri: `src/dep.ts` } })), edges: [] };+ }+ return { nodes: [], edges: [] };+ },+ async provenance(id: string) { return { entityId: id, chain: [] }; },+ } as unknown as IxClient;++ const facts = await collectFacts(client, TARGET, "entry.ts", "file", "context");++ expect(facts.neighbourRefs?.slice(0, 4).map(r => r.name)).toEqual(["a1", "b1", "a2", "b2"]);+ });+});+describe("collectFacts member ranking", () => {const members = [{ id: "m-real", name: "real", lines: [40, 41] as [number, number] },diff --git a/ix-cli/src/cli/commands/context.ts b/ix-cli/src/cli/commands/context.tsindex e2a46eb9..bc35952e 100644--- a/ix-cli/src/cli/commands/context.ts+++ b/ix-cli/src/cli/commands/context.ts@@ -1437,6 +1437,9 @@ export function buildBundle(input: BuildInput): ContextBundle {// an entry point is looking for where to go next....(facts.importRefs ?? []),...(facts.calleeRefs ?? []),+ // What those files define. Naming the file is half an answer to "which+ // function does X"; these are the other half.+ ...(facts.neighbourRefs ?? []),...(facts.topCallerRefs ?? []),...(facts.topDependentRefs ?? []),]);@@ -1650,6 +1653,14 @@ function rankEvidence(input: {reason: "the target calls this", refs: [ref.id], ...locationField(ref),});}+ for (const ref of (input.facts.neighbourRefs ?? []).slice(0, SHOWN_NEIGHBOUR_MEMBERS)) {+ const where = ref.path ? ref.path.split("/").pop() : undefined;+ structural.push({+ id: `defines:${ref.path ?? ""}:${ref.name}`, source: "facts.neighbours",+ title: `${where ?? "a neighbouring file"} defines ${ref.name}`,+ reason: "defined in a file next to the target", refs: [ref.id], ...locationField(ref),+ });+ }for (const { name, ref } of related(input.facts.topCallers, input.facts.topCallerRefs, 3)) {structural.push({id: `caller:${name}`, source: "facts.callers", title: `caller ${name}`,@@ -1824,6 +1835,9 @@ const LEADING_MEMBERS = 10;* where they cost a line each and can carry the answer's file. */const SHOWN_IMPORTS = 8;+/** Members of neighbouring files named in the evidence; the rest are entities. */+const SHOWN_NEIGHBOUR_MEMBERS = 10;+type Located = { path?: string; lineStart?: number; lineEnd?: number };/** `path`, `lineStart` and `lineEnd`, omitting the unknown ones rather than writing `undefined`. */diff --git a/ix-cli/src/cli/explain/facts.ts b/ix-cli/src/cli/explain/facts.tsindex f532e0f7..1f533054 100644--- a/ix-cli/src/cli/explain/facts.ts+++ b/ix-cli/src/cli/explain/facts.ts@@ -67,6 +67,14 @@ export interface EntityFacts {importRefs?: EntityLocation[];calleeRefs?: EntityLocation[];+ /**+ * What the neighbouring files define. Members are otherwise collected for the+ * target alone, so a bundle answered "which function does X" with a file name+ * and nothing in it: measured over 11 benchmark tasks, symbol recall was 0.00+ * on 10 of them even where the right file was returned.+ */+ neighbourRefs?: EntityLocation[];+// HistoryintroducedRev?: number;historyLength: number;@@ -105,6 +113,12 @@ export type ContextFacts = Omit<EntityFacts, ExplainOnlyFact> & { provenance?: uconst NO_DOWNSTREAM = { tree: [], truncated: false, nodesVisited: 0, maxDepthReached: 0 };+/** Neighbouring files opened one level deep, and how many of each one's members are kept. */+const MAX_NEIGHBOUR_FILES = 5;+const MAX_NEIGHBOUR_MEMBERS = 4;+/** Members of a neighbour whose use is measured before the best are kept. */+const NEIGHBOUR_USE_POOL = 6;+/** Outbound facts kept: enough to navigate by, few enough to leave room for the rest. */const MAX_IMPORT_REFS = 12;const MAX_CALLEE_REFS = 4;@@ -151,10 +165,13 @@ function toLocation(n: any): EntityLocation {* from other files rank first, then by total uses; ties keep the structural* order, which is itself deterministic.*/-async function rankMembersByUse(client: IxClient, members: EntityLocation[]): Promise<EntityLocation[]> {+/** Members a reader navigates by first: declaration kinds, then the big ones.+ * Deterministic, and costs nothing -- unlike the usage ranking, which pays an+ * expand per member and is reserved for the target's own. */+function structuralMemberOrder(members: EntityLocation[]): EntityLocation[] {const span = (m: EntityLocation) =>m.lineStart !== undefined && m.lineEnd !== undefined ? m.lineEnd - m.lineStart : 0;- const structural = members+ return members.map((m, index) => ({ m, index })).sort((a, b) =>Number(!PRIMARY_MEMBER_KINDS.has(a.m.kind)) - Number(!PRIMARY_MEMBER_KINDS.has(b.m.kind)) ||@@ -162,6 +179,51 @@ async function rankMembersByUse(client: IxClient, members: EntityLocation[]): Pr(a.m.name < b.m.name ? -1 : a.m.name > b.m.name ? 1 : 0) ||a.index - b.index).map(({ m }) => m);+}++/**+ * What the files around the target define.+ *+ * One `CONTAINS` expand per neighbouring file, for at most+ * `MAX_NEIGHBOUR_FILES` of them, keeping `MAX_NEIGHBOUR_MEMBERS` each in+ * structural order. Bounded on purpose: this is the hop that turns "the answer+ * is in config.ts" into "resolveWorkspaceRoot, config.ts:322".+ */+async function collectNeighbourMembers(+ client: IxClient, neighbours: EntityLocation[], targetId: string,+): Promise<EntityLocation[]> {+ 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+ try {+ const result = await client.expand(file.id, { direction: "out", predicates: ["CONTAINS"] });+ const candidates = structuralMemberOrder((result.nodes ?? [])+ .filter((n: any) => n?.id && n.id !== file.id)+ .map(toLocation)).slice(0, NEIGHBOUR_USE_POOL);+ // 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));+ } catch {+ found.push([]); // 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.+ const interleaved: EntityLocation[] = [];+ for (let rank = 0; rank < MAX_NEIGHBOUR_MEMBERS; rank++) {+ for (const members of found) {+ if (members[rank]) interleaved.push(members[rank]);+ }+ }+ return interleaved;+}++async function rankMembersByUse(client: IxClient, members: EntityLocation[]): Promise<EntityLocation[]> {+ const structural = structuralMemberOrder(members);const pool = structural.slice(0, MEMBER_USE_POOL);const measured: EntityLocation[] = new Array(pool.length);@@ -313,6 +375,12 @@ 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);@@ -414,6 +482,7 @@ export async function collectFacts(topDependentRefs,importRefs,calleeRefs,+ neighbourRefs,introducedRev: node.createdRev ?? node.created_rev,historyLength: history?.chain?.length ?? 0,callList,