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: make ix overview adaptive for containers vs leaf nodes
Tanner Kocher653c770a7c11
diff --git a/ix-cli/src/cli/__tests__/overview-structure.test.ts b/ix-cli/src/cli/__tests__/overview-structure.test.tsindex 116434aa..ff4dee6f 100644--- a/ix-cli/src/cli/__tests__/overview-structure.test.ts+++ b/ix-cli/src/cli/__tests__/overview-structure.test.ts@@ -4,8 +4,9 @@ import { humanizeLabel } from "../impact/risk-semantics.js";/*** Tests for ix overview output structure.*- * These verify that overview is purely structural and downward-facing:- * kind, file path, system path, child counts, key items — no role/risk/dependency content.+ * Containers: child counts + key items.+ * Leaves: contained-in + nearby structure + key siblings.+ * No role/risk/dependency content anywhere.*/// ── Helpers ─────────────────────────────────────────────────────────────────@@ -30,6 +31,9 @@ function makeClassOutput() {{ name: "listByKind", kind: "method" },{ name: "listPatches", kind: "method" },],+ containedIn: null,+ siblingsByKind: null,+ keySiblings: null,diagnostics: [],};}@@ -51,6 +55,9 @@ function makeFileOutput() {{ name: "Node", kind: "class" },{ name: "NodeId", kind: "object" },],+ containedIn: null,+ siblingsByKind: null,+ keySiblings: null,diagnostics: [],};}@@ -71,11 +78,14 @@ function makeRegionOutput() {{ name: "resolve.ts", kind: "file" },{ name: "status.ts", kind: "file" },],+ containedIn: null,+ siblingsByKind: null,+ keySiblings: null,diagnostics: [],};}-function makeFunctionOutput() {+function makeFunctionInFileOutput() {return {resolvedTarget: { id: "fn-1", kind: "function", name: "pickBest" },resolutionMode: "exact",@@ -89,6 +99,42 @@ function makeFunctionOutput() {hasMapData: true,childrenByKind: null,keyItems: null,+ containedIn: { kind: "file", name: "resolve.ts" },+ siblingsByKind: { function: 8 },+ keySiblings: [+ { name: "resolveEntity", kind: "function" },+ { name: "resolveEntityFull", kind: "function" },+ { name: "scoreCandidate", kind: "function" },+ { name: "buildAmbiguous", kind: "function" },+ { name: "nodeToResolved", kind: "function" },+ ],+ diagnostics: [],+ };+}++function makeMethodInClassOutput() {+ return {+ resolvedTarget: { id: "m-1", kind: "method", name: "resolve" },+ resolutionMode: "exact",+ path: "memory-layer/src/main/scala/ix/memory/conflict/ConflictService.scala",+ systemPath: [+ { name: "API", kind: "system" },+ { name: "Model", kind: "subsystem" },+ { name: "ConflictService.scala", kind: "file" },+ { name: "ConflictService", kind: "class" },+ { name: "resolve", kind: "method" },+ ],+ hasMapData: true,+ childrenByKind: null,+ keyItems: null,+ containedIn: { kind: "class", name: "ConflictService" },+ siblingsByKind: { method: 6 },+ keySiblings: [+ { name: "tryGitLsFiles", kind: "method" },+ { name: "resolveRelativePath", kind: "method" },+ { name: "normalizePath", kind: "method" },+ { name: "mergeConflict", kind: "method" },+ ],diagnostics: [],};}@@ -110,6 +156,13 @@ describe("overview: class target", () => {expect(output.keyItems!.map((i) => i.name)).toContain("get");});+ it("has no leaf-specific fields", () => {+ const output = makeClassOutput();+ expect(output.containedIn).toBeNull();+ expect(output.siblingsByKind).toBeNull();+ expect(output.keySiblings).toBeNull();+ });+it("has no callers, dependents, or risk text", () => {const output = makeClassOutput();const keys = Object.keys(output);@@ -173,25 +226,73 @@ describe("overview: region/subsystem target", () => {});});-// ── Method/function target ──────────────────────────────────────────────────+// ── Leaf target in file ─────────────────────────────────────────────────────++describe("overview: leaf target in file", () => {+ it("shows contained-in as the file", () => {+ const output = makeFunctionInFileOutput();+ expect(output.containedIn).not.toBeNull();+ expect(output.containedIn!.kind).toBe("file");+ expect(output.containedIn!.name).toBe("resolve.ts");+ });-describe("overview: method/function target", () => {- it("stays minimal with no fake contained structure", () => {- const output = makeFunctionOutput();+ it("shows nearby structure with sibling counts", () => {+ const output = makeFunctionInFileOutput();+ expect(output.siblingsByKind).not.toBeNull();+ expect(output.siblingsByKind!.function).toBe(8);+ });++ it("shows key siblings", () => {+ const output = makeFunctionInFileOutput();+ expect(output.keySiblings).not.toBeNull();+ expect(output.keySiblings!.length).toBeLessThanOrEqual(5);+ expect(output.keySiblings!.map((s) => s.name)).toContain("resolveEntity");+ });++ it("does not have container-specific fields", () => {+ const output = makeFunctionInFileOutput();expect(output.childrenByKind).toBeNull();expect(output.keyItems).toBeNull();});- it("has file and system path", () => {- const output = makeFunctionOutput();- expect(output.path).toBe("src/cli/resolve.ts");- expect(output.systemPath!.length).toBeGreaterThan(1);+ it("has no callers/dependents/role/risk text", () => {+ const output = makeFunctionInFileOutput();+ const keys = Object.keys(output);+ expect(keys).not.toContain("callers");+ expect(keys).not.toContain("dependents");+ expect(keys).not.toContain("riskSummary");+ expect(keys).not.toContain("usedBy");+ expect(keys).not.toContain("whyItMatters");+ });+});++// ── Leaf target in class ────────────────────────────────────────────────────++describe("overview: leaf target in class", () => {+ it("nearest meaningful container is the class", () => {+ const output = makeMethodInClassOutput();+ expect(output.containedIn).not.toBeNull();+ expect(output.containedIn!.kind).toBe("class");+ expect(output.containedIn!.name).toBe("ConflictService");+ });++ it("shows sibling methods", () => {+ const output = makeMethodInClassOutput();+ expect(output.siblingsByKind).not.toBeNull();+ expect(output.siblingsByKind!.method).toBe(6);+ });++ it("shows key siblings", () => {+ const output = makeMethodInClassOutput();+ expect(output.keySiblings).not.toBeNull();+ expect(output.keySiblings!.map((s) => s.name)).toContain("mergeConflict");});- it("system path ends with the function name", () => {- const output = makeFunctionOutput();- const last = output.systemPath![output.systemPath!.length - 1];- expect(last.name).toBe("pickBest");+ it("system path includes class and method", () => {+ const output = makeMethodInClassOutput();+ const names = output.systemPath!.map((n) => n.name);+ expect(names).toContain("ConflictService");+ expect(names).toContain("resolve");});});@@ -212,7 +313,10 @@ describe("overview: humanized system path labels", () => {// ── No-overlap regression ───────────────────────────────────────────────────describe("overview: no-overlap regression", () => {- const allOutputs = [makeClassOutput(), makeFileOutput(), makeRegionOutput(), makeFunctionOutput()];+ const allOutputs = [+ makeClassOutput(), makeFileOutput(), makeRegionOutput(),+ makeFunctionInFileOutput(), makeMethodInClassOutput(),+ ];const allKeys = new Set(allOutputs.flatMap((o) => Object.keys(o)));it("does not include 'usedBy' or 'whyItMatters'", () => {@@ -237,7 +341,6 @@ describe("overview: no-overlap regression", () => {});it("does not include imports count", () => {- // imports belonged to the old overview — now removedfor (const o of allOutputs) {expect((o as any).summary?.imports).toBeUndefined();}diff --git a/ix-cli/src/cli/commands/overview.ts b/ix-cli/src/cli/commands/overview.tsindex e6f90eb2..f09d3337 100644--- a/ix-cli/src/cli/commands/overview.ts+++ b/ix-cli/src/cli/commands/overview.ts@@ -8,6 +8,7 @@ import { getSystemPath, hasMapData } from "../hierarchy.js";import { humanizeLabel } from "../impact/risk-semantics.js";const CONTAINER_KINDS = new Set(["class", "module", "file", "trait", "object", "interface"]);+const STRUCTURAL_CONTAINER_KINDS = new Set(["class", "object", "trait", "interface"]);const REGION_KINDS = new Set(["system", "subsystem", "module", "region"]);const FILE_KINDS = new Set(["file"]);@@ -19,15 +20,20 @@ interface OverviewResult {path: string | null;systemPath: Array<{ name: string; kind: string }> | null;hasMapData: boolean;+ // Container targetschildrenByKind: Record<string, number> | null;keyItems: Array<{ name: string; kind: string }> | null;+ // Leaf targets+ containedIn: { kind: string; name: string } | null;+ siblingsByKind: Record<string, number> | null;+ keySiblings: Array<{ name: string; kind: string }> | null;diagnostics: string[];}export function registerOverviewCommand(program: Command): void {program.command("overview <target>")- .description("Structural summary — what a target contains")+ .description("Structural summary — what a target contains or what surrounds it").option("--kind <kind>", "Filter target entity by kind").option("--path <path>", "Prefer symbols from files matching this path substring").option("--pick <n>", "Pick Nth candidate from ambiguous results (1-based)")@@ -90,7 +96,7 @@ function keyItemsLabel(kind: string): string {return "Key members";}-/** Humanize a kind for the Contains section (e.g. "method" → "Methods"). */+/** Humanize a kind for the Contains/Nearby section (e.g. "method" → "Methods"). */function kindLabel(kind: string): string {const labels: Record<string, string> = {method: "Methods",@@ -115,10 +121,14 @@ function kindLabel(kind: string): string {};const label = labels[kind.toLowerCase()];if (label) return label;- // Fallback: capitalizereturn kind.charAt(0).toUpperCase() + kind.slice(1) + "s";}+/** Sibling label: "Sibling methods", "Sibling functions", etc. */+function siblingKindLabel(kind: string): string {+ return `Sibling ${kindLabel(kind).toLowerCase()}`;+}+// ── Container / Region overview ─────────────────────────────────────────────async function overviewContainer(@@ -129,7 +139,6 @@ async function overviewContainer(const diagnostics: string[] = [];const isRegion = REGION_KINDS.has(target.kind);- // For regions, children come via IN_REGION; for code containers, via CONTAINSconst childPredicate = isRegion ? "IN_REGION" : "CONTAINS";const [details, childrenResult, systemPath] = await Promise.all([@@ -144,7 +153,6 @@ async function overviewContainer(const children = childrenResult.nodes;- // Group children by kind → countconst childrenByKind: Record<string, number> = {};const childList: Array<{ name: string; kind: string }> = [];for (const m of children) {@@ -155,7 +163,6 @@ async function overviewContainer(childList.push({ name, kind });}- // Key items: first N unique childrenconst keyItems = childList.slice(0, KEY_ITEMS_LIMIT);const hasMap = hasMapData(systemPath);@@ -173,6 +180,9 @@ async function overviewContainer(hasMapData: hasMap,childrenByKind: Object.keys(childrenByKind).length > 0 ? childrenByKind : null,keyItems: keyItems.length > 0 ? keyItems : null,+ containedIn: null,+ siblingsByKind: null,+ keySiblings: null,diagnostics,};@@ -181,20 +191,16 @@ async function overviewContainer(return;}- // Text rendering- renderOverviewHeader(target, displayPath, systemPathMapped, hasMap);+ renderOverviewHeader(target, displayPath, null, systemPathMapped, hasMap);- // Containsif (Object.keys(childrenByKind).length > 0) {console.log(chalk.bold("\nContains"));- // Sort by count descendingconst sorted = Object.entries(childrenByKind).sort((a, b) => b[1] - a[1]);for (const [kind, count] of sorted) {console.log(` ${chalk.dim(kindLabel(kind).padEnd(16))}${count}`);}}- // Key itemsif (keyItems.length > 0) {console.log(chalk.bold(`\n${keyItemsLabel(target.kind)}`));for (const item of keyItems) {@@ -205,7 +211,7 @@ async function overviewContainer(renderDiagnostics(diagnostics);}-// ── Leaf (function/method) overview ─────────────────────────────────────────+// ── Leaf (function/method/field) overview ────────────────────────────────────async function overviewLeaf(client: IxClient,@@ -214,9 +220,11 @@ async function overviewLeaf(): Promise<void> {const diagnostics: string[] = [];- const [details, systemPath] = await Promise.all([+ // Fetch entity details, system path, and parent container in parallel+ const [details, systemPath, parentResult] = await Promise.all([client.entity(target.id),getSystemPath(client, target.id),+ client.expand(target.id, { direction: "in", predicates: ["CONTAINS"] }),]);const node = details.node as any;@@ -235,6 +243,64 @@ async function overviewLeaf(systemPathMapped = [...systemPathMapped, { name: target.name, kind: target.kind }];}+ // Find nearest meaningful container+ // Prefer class/object/trait/interface, fall back to file+ let containedIn: { kind: string; name: string } | null = null;+ let containerId: string | null = null;++ const parents = parentResult.nodes as any[];+ const structuralParent = parents.find((p) => STRUCTURAL_CONTAINER_KINDS.has(p.kind));+ const fileParent = parents.find((p) => FILE_KINDS.has(p.kind));+ const bestParent = structuralParent ?? fileParent ?? parents[0];++ if (bestParent) {+ containedIn = {+ kind: bestParent.kind || "unknown",+ name: bestParent.name || bestParent.attrs?.name || "(unknown)",+ };+ containerId = bestParent.id;+ }++ // Fetch siblings from the container+ let siblingsByKind: Record<string, number> | null = null;+ let keySiblings: Array<{ name: string; kind: string }> | null = null;++ if (containerId) {+ try {+ const siblingsResult = await client.expand(containerId, {+ direction: "out",+ predicates: ["CONTAINS"],+ });++ const siblings = (siblingsResult.nodes as any[]).filter(+ (n) => n.id !== target.id+ );++ if (siblings.length > 0) {+ // Group siblings by kind+ const byKind: Record<string, number> = {};+ const siblingList: Array<{ name: string; kind: string }> = [];+ for (const s of siblings) {+ const kind = s.kind || "unknown";+ const name = s.name || s.attrs?.name || "(unnamed)";+ byKind[kind] = (byKind[kind] || 0) + 1;+ siblingList.push({ name, kind });+ }+ siblingsByKind = byKind;++ // Key siblings: prefer same kind, then others, exclude target+ const sameKind = siblingList.filter((s) => s.kind === target.kind);+ const otherKind = siblingList.filter((s) => s.kind !== target.kind);+ const ordered = [...sameKind, ...otherKind];+ if (ordered.length > 0) {+ keySiblings = ordered.slice(0, KEY_ITEMS_LIMIT);+ }+ }+ } catch {+ diagnostics.push("Could not fetch sibling structure.");+ }+ }+const result: OverviewResult = {resolvedTarget: { id: target.id, kind: target.kind, name: target.name },resolutionMode: target.resolutionMode,@@ -243,6 +309,9 @@ async function overviewLeaf(hasMapData: hasMap,childrenByKind: null,keyItems: null,+ containedIn,+ siblingsByKind,+ keySiblings,diagnostics,};@@ -251,7 +320,25 @@ async function overviewLeaf(return;}- renderOverviewHeader(target, displayPath, systemPathMapped, hasMap);+ renderOverviewHeader(target, displayPath, containedIn, systemPathMapped, hasMap);++ // Nearby structure+ if (siblingsByKind && Object.keys(siblingsByKind).length > 0) {+ console.log(chalk.bold("\nNearby structure"));+ const sorted = Object.entries(siblingsByKind).sort((a, b) => b[1] - a[1]);+ for (const [kind, count] of sorted) {+ console.log(` ${chalk.dim(siblingKindLabel(kind).padEnd(24))}${count}`);+ }+ }++ // Key siblings+ if (keySiblings && keySiblings.length > 0) {+ console.log(chalk.bold("\nKey siblings"));+ for (const s of keySiblings) {+ console.log(` ${s.name}`);+ }+ }+renderDiagnostics(diagnostics);}@@ -260,16 +347,23 @@ async function overviewLeaf(function renderOverviewHeader(target: { kind: string; name: string },displayPath: string | null,+ containedIn: { kind: string; name: string } | null,systemPath: Array<{ name: string; kind: string }>,hasMap: boolean,): void {console.log(chalk.bold("\nOverview"));- console.log(` ${chalk.dim("Kind:".padEnd(14))}${target.kind}`);+ console.log(` ${chalk.dim("Kind:".padEnd(16))}${target.kind}`);if (displayPath) {- console.log(` ${chalk.dim("File:".padEnd(14))}${displayPath}`);+ console.log(` ${chalk.dim("File:".padEnd(16))}${displayPath}`);+ }+ if (containedIn) {+ const containerLabel = STRUCTURAL_CONTAINER_KINDS.has(containedIn.kind)+ ? `${containedIn.kind} ${containedIn.name}`+ : containedIn.name;+ console.log(` ${chalk.dim("Contained in:".padEnd(16))}${containerLabel}`);}if (systemPath.length > 1 && hasMap) {- console.log(` ${chalk.dim("System path:".padEnd(14))}${humanizeBreadcrumb(systemPath)}`);+ console.log(` ${chalk.dim("System path:".padEnd(16))}${humanizeBreadcrumb(systemPath)}`);}}