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 target imports and calls
KageBinary289565181313
diff --git a/ix-cli/src/cli/__tests__/context-evidence-locations.test.ts b/ix-cli/src/cli/__tests__/context-evidence-locations.test.tsindex cc6846fb..c1c05e99 100644--- a/ix-cli/src/cli/__tests__/context-evidence-locations.test.ts+++ b/ix-cli/src/cli/__tests__/context-evidence-locations.test.ts@@ -156,6 +156,35 @@ describe("ix context evidence says where things are", () => {expect(b.entities).toHaveLength(50);});+ it("says what the target imports and calls, ahead of what points back at it", () => {+ // The answer to a question asked from an entry point is most often in a+ // file that entry point imports. Before this the bundle only pointed+ // inward -- members, callers, dependents -- and never named it.+ const imports: EntityLocation[] = [+ { id: "i-resolve", name: "resolve.ts", kind: "file", path: "src/cli/resolve.ts" },+ ];+ const callees: EntityLocation[] = [+ { id: "c-scope", name: "ensureReadScope", kind: "function", path: "src/cli/resolve.ts",+ lineStart: 56, lineEnd: 80 },+ ];+ const b = bundle({ facts: facts({ importRefs: imports, calleeRefs: callees }) });++ const structural = b.evidence.filter((e) => e.kind === "structural").map((e) => e.title);+ expect(structural).toContain("imports resolve.ts");+ expect(structural).toContain("calls ensureReadScope");+ expect(structural.indexOf("imports resolve.ts"))+ .toBeLessThan(structural.indexOf("dependent stats.ts"));++ const imported = b.evidence.find((e) => e.title === "imports resolve.ts");+ expect(imported?.location).toEqual({ path: "src/cli/resolve.ts" });+ expect(imported?.reason).toBe("the target imports this");+ expect(b.evidence.find((e) => e.title === "calls ensureReadScope")?.location)+ .toEqual({ path: "src/cli/resolve.ts", lineStart: 56, lineEnd: 80 });++ // And they are entities, so the file an answer lives in is in the bundle.+ expect(b.entities.map((e) => e.name)).toContain("resolve.ts");+ });+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 3fc6afbe..308b2157 100644--- a/ix-cli/src/cli/__tests__/facts-scope.test.ts+++ b/ix-cli/src/cli/__tests__/facts-scope.test.ts@@ -39,9 +39,14 @@ function fakeClient(calls: Call[]): IxClient {async expand(id: string, opts?: { direction?: string; predicates?: string[]; hops?: number }) {calls.push({ method: "expand", id, predicates: opts?.predicates, hops: opts?.hops });const importedBy = id === TARGET && opts?.direction === "in" && opts.predicates?.includes("IMPORTS");- return importedBy- ? { nodes: [node(DEPENDENT, "user", "file")], edges: [{ src: DEPENDENT, dst: TARGET, predicate: "IMPORTS" }] }- : { nodes: [], edges: [] };+ const calls_out = id === TARGET && opts?.direction === "out" && opts.predicates?.includes("CALLS");+ if (importedBy) {+ return { nodes: [node(DEPENDENT, "user", "file")], edges: [{ src: DEPENDENT, dst: TARGET, predicate: "IMPORTS" }] };+ }+ if (calls_out) {+ return { nodes: [node(CALLEE, "callee", "function")], edges: [{ src: TARGET, dst: CALLEE, predicate: "CALLS" }] };+ }+ return { nodes: [], edges: [] };},async provenance(id: string) {calls.push({ method: "provenance", id });@@ -56,14 +61,19 @@ describe("collectFacts scope", () => {const facts = await collectFacts(fakeClient(calls), TARGET, "config", "function", "context");- // One entity, five fixed expands, one provenance -- and nothing that- // grows with the graph.- expect(calls.filter((c) => c.method === "expand")).toHaveLength(5);+ // 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);+ expect(calls.some((c) => c.method === "expand" && c.predicates?.[0] === "IMPORTS"+ && c.id === TARGET)).toBe(true);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"]);+ // The fake graph's only outbound edge is the target's CALLS to CALLEE.+ expect(facts.calleeRefs?.map((r) => r.name)).toEqual(["callee"]);expect(facts.historyLength).toBe(2);// Handed on so `ix context` does not fetch the same provenance twice.expect(calls.filter((c) => c.method === "provenance")).toHaveLength(1);diff --git a/ix-cli/src/cli/commands/context.ts b/ix-cli/src/cli/commands/context.tsindex 2a24ffce..e2a46eb9 100644--- a/ix-cli/src/cli/commands/context.ts+++ b/ix-cli/src/cli/commands/context.ts@@ -1433,6 +1433,10 @@ export function buildBundle(input: BuildInput): ContextBundle {};pushLocated([...memberRefs.slice(0, LEADING_MEMBERS),+ // What the target reaches, before what reaches it: an agent starting from+ // an entry point is looking for where to go next.+ ...(facts.importRefs ?? []),+ ...(facts.calleeRefs ?? []),...(facts.topCallerRefs ?? []),...(facts.topDependentRefs ?? []),]);@@ -1630,6 +1634,22 @@ function rankEvidence(input: {): Array<{ name: string; ref?: EntityLocation }> =>(refs ? refs.map((ref) => ({ name: ref.name, ref })) : names.map((name) => ({ name }))).slice(0, limit);+ // Outward first. Everything below points inward -- what contains the target,+ // what calls it -- and the file an answer lives in is most often one the+ // target imports: measured on the benchmark task set, 6 of 19 tasks' answers+ // are a direct import of their entry point, and none were in the bundle.+ for (const ref of (input.facts.importRefs ?? []).slice(0, SHOWN_IMPORTS)) {+ structural.push({+ id: `imports:${ref.name}`, source: "facts.imports", title: `imports ${ref.name}`,+ reason: "the target imports this", refs: [ref.id], ...locationField(ref),+ });+ }+ for (const ref of input.facts.calleeRefs ?? []) {+ structural.push({+ id: `calls:${ref.name}`, source: "facts.callees", title: `calls ${ref.name}`,+ reason: "the target calls this", 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}`,@@ -1800,6 +1820,10 @@ export function renderBundle(bundle: ContextBundle, format: string): void {/** Members placed ahead of the backend's context nodes; the evidence shows as many. */const LEADING_MEMBERS = 10;+/** Imports named in the evidence. The rest still enter the bundle as entities,+ * where they cost a line each and can carry the answer's file. */+const SHOWN_IMPORTS = 8;+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 9bb99b06..f532e0f7 100644--- a/ix-cli/src/cli/explain/facts.ts+++ b/ix-cli/src/cli/explain/facts.ts@@ -58,6 +58,15 @@ export interface EntityFacts {topCallerRefs?: EntityLocation[];topDependentRefs?: EntityLocation[];+ /**+ * What the target itself reaches: the files it imports and the functions it+ * calls. Everything else here points *inward* -- what contains the target,+ * what calls it, what it defines -- and an agent starting from a command or+ * an entry point has to go the other way to find an implementation.+ */+ importRefs?: EntityLocation[];+ calleeRefs?: EntityLocation[];+// HistoryintroducedRev?: number;historyLength: number;@@ -96,6 +105,10 @@ export type ContextFacts = Omit<EntityFacts, ExplainOnlyFact> & { provenance?: uconst NO_DOWNSTREAM = { tree: [], truncated: false, nodesVisited: 0, maxDepthReached: 0 };+/** 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;+/** Members probed for usage; the rest keep their structural order after them. */const MEMBER_USE_POOL = 40;/** Inbound edges read per member. Enough to rank by; a hub is a hub at 50. */@@ -219,11 +232,12 @@ export async function collectFacts(const forExplain = scope === "explain";// Run parallel graph queries (including, for explain, a bounded downstream tree)- const [details, callersResult, calleesResult, dependentsResult, importersResult, membersResult, provenance, downstream, hierarchyPath] =+ const [details, callersResult, calleesResult, importsResult, dependentsResult, importersResult, membersResult, provenance, downstream, hierarchyPath] =await Promise.all([client.entity(targetId),client.expand(targetId, { direction: "in", predicates: ["CALLS"] }),client.expand(targetId, { direction: "out", predicates: ["CALLS"] }),+ client.expand(targetId, { direction: "out", predicates: ["IMPORTS"] }),client.expand(targetId, { direction: "in", predicates: ["CALLS", "IMPORTS", "REFERENCES"] }),client.expand(targetId, { direction: "in", predicates: ["IMPORTS"] }),client.expand(targetId, { direction: "out", predicates: ["CONTAINS"] }),@@ -284,6 +298,21 @@ export async function collectFacts(};const topCallerRefs = extractRefs(callersResult.nodes, 3);const topDependentRefs = extractRefs(uniqueDependents, 3);+ // Where the target leads. Self-edges are dropped: a file that imports its own+ // directory index resolves back to itself and says nothing.+ const outward = (nodes: any[], limit: number): EntityLocation[] =>+ extractRefs(nodes.filter((n: any) => n?.id !== targetId), limit);+ // Repository files first. `ingest.ts` imports 26 modules, a third of them+ // packages (`node:os`, `chalk`) that no question is ever answered in, and in+ // graph order they pushed `supported-extensions.ts` -- the answer to "which+ // extensions does the walker use" -- past the cut. An external package is a+ // `module` node; its provenance names the file that imports it, not the+ // package, so the path cannot be used to tell the two apart.+ const importRefs = outward(+ [...importsResult.nodes].sort((a: any, b: any) =>+ Number(a?.kind !== "file") - Number(b?.kind !== "file")),+ MAX_IMPORT_REFS);+ const calleeRefs = outward(calleesResult.nodes, MAX_CALLEE_REFS);const topCallers = topCallerRefs.map((r) => r.name);const topDependents = topDependentRefs.map((r) => r.name);@@ -383,6 +412,8 @@ export async function collectFacts(topDependents,topCallerRefs,topDependentRefs,+ importRefs,+ calleeRefs,introducedRev: node.createdRev ?? node.created_rev,historyLength: history?.chain?.length ?? 0,callList,