Skip to content

armgit / Ix

Public Imported from GitHub
0

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

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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[];
+
// History
introducedRev?: number;
historyLength: number;
@@ -105,6 +113,12 @@ export type ContextFacts = Omit<EntityFacts, ExplainOnlyFact> & { provenance?: u
const 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,