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
// Copyright 2026 Ix Infrastructure Inc.
import type { Command } from "commander";
import { IxClient } from "../../client/api.js";
import { createClient } from "../../client/factory.js";
import { resolveFileOrReport, printResolved } from "../resolve.js";
import { getEffectiveSystemPath, getSystemPath, hasMapData } from "../hierarchy.js";
import { humanizeLabel } from "../impact/risk-semantics.js";
import { relativePath, printJson } from "../format.js";
import { llmLine, type LlmValue } from "../llm.js";
import { parsePickOption } from "../options.js";
import { renderSection, renderKeyValue, renderNote, renderBreadcrumb } from "../ui.js";
import { forMcp } from "../next-step.js";
import { ensureFreshMapState, mapStaleJson, mapStaleLlm, type MapStaleState } from "../map-freshness.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"]);
const KEY_ITEMS_LIMIT = 5;
interface OverviewResult {
resolvedTarget: { id: string; kind: string; name: string };
resolutionMode: string;
path: string | null;
systemPath: Array<{ name: string; kind: string }> | null;
hasMapData: boolean;
// Container targets
childrenByKind: 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 or what surrounds it")
.option("--kind <kind>", "Filter target entity by kind")
.option("--path <path>", "Restrict to symbols from files matching this path substring")
.option("--pick <n>", "Pick Nth candidate from ambiguous results (1-based)", parsePickOption)
.option("--format <fmt>", "Output format (text|json|llm)", "text")
.addHelpText(
"after",
`\nUse overview for structural summaries. Use 'ix locate' for position.
Use 'ix explain' for role. Use 'ix impact' for risk.
Examples:
ix overview IngestionService
ix overview IngestionService --kind class
ix overview verify_token --kind function --format json
ix overview src/cli/commands/overview.ts
ix overview overview.ts
ix overview scoreCandidate --pick 2`
)
.action(async (symbol: string, opts: { kind?: string; path?: string; pick?: number; format: string }) => {
const client = createClient({ query: true });
const resolveOpts = { kind: opts.kind, path: opts.path, pick: opts.pick };
const target = await resolveFileOrReport(client, symbol, resolveOpts, opts.format);
if (!target) return;
if (opts.format === "text") printResolved(target);
// An `ix map` after an edit may have left the map for this read (CL-13).
// Never throws and never moves the exit code. The json and llm answers
// say so too: the system path below comes from the map's regions.
const mapState = await ensureFreshMapState();
const isContainer = CONTAINER_KINDS.has(target.kind);
const isRegion = REGION_KINDS.has(target.kind);
if (isContainer || isRegion) {
await overviewContainer(client, target, opts.format, mapState);
} else {
await overviewLeaf(client, target, opts.format, mapState);
}
});
}
// ── Helpers ──────────────────────────────────────────────────────────────────
function toRepoRelative(filePath: string): string {
return relativePath(filePath) ?? filePath;
}
function humanizeBreadcrumb(nodes: Array<{ name: string; kind: string }>): string {
const humanized = nodes.map((n) => {
if (REGION_KINDS.has(n.kind)) return humanizeLabel(n.name).replace(/ layer$/, "");
return n.name;
});
return renderBreadcrumb(humanized.map((name) => ({ name })));
}
/** Label for the "Key ..." section based on target kind. */
function keyItemsLabel(kind: string): string {
if (FILE_KINDS.has(kind)) return "Key definitions";
if (REGION_KINDS.has(kind)) return "Key files";
return "Key members";
}
/** Humanize a kind for the Contains/Nearby section (e.g. "method" → "Methods"). */
function kindLabel(kind: string): string {
const labels: Record<string, string> = {
method: "Methods",
function: "Functions",
field: "Fields",
class: "Classes",
interface: "Interfaces",
trait: "Traits",
object: "Objects",
file: "Files",
enum: "Enums",
type: "Types",
type_alias: "Type aliases",
module: "Modules",
region: "Regions",
subsystem: "Subsystems",
constructor: "Constructors",
def: "Methods",
fun: "Functions",
val: "Fields",
var: "Fields",
};
const label = labels[kind.toLowerCase()];
if (label) return label;
return 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(
client: IxClient,
target: { id: string; kind: string; name: string; resolutionMode: string },
format: string,
mapState: MapStaleState = {},
): Promise<void> {
const diagnostics: string[] = [];
const isRegion = REGION_KINDS.has(target.kind);
const childPredicate = isRegion ? "IN_REGION" : "CONTAINS";
const [details, childrenResult, systemPath] = await Promise.all([
client.entity(target.id),
client.expand(target.id, { direction: "out", predicates: [childPredicate] }),
getSystemPath(client, target.id),
]);
const node = details.node as any;
const rawPath = node.provenance?.source_uri ?? node.provenance?.sourceUri ?? null;
const displayPath = rawPath ? toRepoRelative(rawPath) : null;
const children = childrenResult.nodes;
const childrenByKind: Record<string, number> = {};
const childList: Array<{ name: string; kind: string }> = [];
for (const m of children) {
const member = m as any;
const kind = member.kind || "unknown";
const name = member.name || member.attrs?.name || "(unnamed)";
childrenByKind[kind] = (childrenByKind[kind] || 0) + 1;
childList.push({ name, kind });
}
const keyItems = childList.slice(0, KEY_ITEMS_LIMIT);
const hasMap = hasMapData(systemPath);
if (!hasMap) {
diagnostics.push(`No system map. Run ${forMcp() ? "ix_map" : "`ix map`"} to see hierarchy.`);
}
// Append container symbol to system path for non-file, non-region containers
let systemPathMapped = systemPath.map((n) => ({ name: n.name, kind: n.kind }));
if (!FILE_KINDS.has(target.kind) && !isRegion) {
const lastInPath = systemPathMapped[systemPathMapped.length - 1];
if (!lastInPath || lastInPath.name !== target.name) {
systemPathMapped = [...systemPathMapped, { name: target.name, kind: target.kind }];
}
}
const result: OverviewResult = {
resolvedTarget: { id: target.id, kind: target.kind, name: target.name },
resolutionMode: target.resolutionMode,
path: displayPath,
systemPath: systemPathMapped,
hasMapData: hasMap,
childrenByKind: Object.keys(childrenByKind).length > 0 ? childrenByKind : null,
keyItems: keyItems.length > 0 ? keyItems : null,
containedIn: null,
siblingsByKind: null,
keySiblings: null,
diagnostics,
};
if (format === "json") {
printJson({ ...result, ...mapStaleJson(mapState) });
return;
}
if (format === "llm") {
// With the answer, not before it (mapStaleLlm).
for (const line of mapStaleLlm(mapState)) console.log(line);
for (const line of overviewContainerLlm({ target, displayPath, systemPath: systemPathMapped, hasMap, childrenByKind, keyItems, diagnostics })) {
console.log(line);
}
return;
}
renderOverviewHeader(target, displayPath, null, systemPathMapped, hasMap);
if (Object.keys(childrenByKind).length > 0) {
renderSection("Contains");
const sorted = Object.entries(childrenByKind).sort((a, b) => b[1] - a[1]);
for (const [kind, count] of sorted) {
renderKeyValue(kindLabel(kind), String(count));
}
}
if (keyItems.length > 0) {
renderSection(keyItemsLabel(target.kind));
for (const item of keyItems) {
console.log(` ${item.name}`);
}
}
renderDiagnostics(diagnostics);
}
// ── Leaf (function/method/field) overview ────────────────────────────────────
async function overviewLeaf(
client: IxClient,
target: { id: string; kind: string; name: string; resolutionMode: string },
format: string,
mapState: MapStaleState = {},
): Promise<void> {
const diagnostics: string[] = [];
// Fetch entity details, system path, and parent container in parallel
const [details, systemPath, parentResult] = await Promise.all([
client.entity(target.id),
getEffectiveSystemPath(client, target.id),
client.expand(target.id, { direction: "in", predicates: ["CONTAINS"] }),
]);
const node = details.node as any;
const rawPath = node.provenance?.source_uri ?? node.provenance?.sourceUri ?? null;
const displayPath = rawPath ? toRepoRelative(rawPath) : null;
const hasMap = hasMapData(systemPath);
if (!hasMap) {
diagnostics.push(`No system map. Run ${forMcp() ? "ix_map" : "`ix map`"} to see hierarchy.`);
}
// Append target to system path if not already there
let systemPathMapped = systemPath.map((n) => ({ name: n.name, kind: n.kind }));
const lastInPath = systemPathMapped[systemPathMapped.length - 1];
if (!lastInPath || lastInPath.name !== target.name) {
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,
path: displayPath,
systemPath: systemPathMapped,
hasMapData: hasMap,
childrenByKind: null,
keyItems: null,
containedIn,
siblingsByKind,
keySiblings,
diagnostics,
};
if (format === "json") {
printJson({ ...result, ...mapStaleJson(mapState) });
return;
}
if (format === "llm") {
// With the answer, not before it (mapStaleLlm).
for (const line of mapStaleLlm(mapState)) console.log(line);
for (const line of overviewLeafLlm({ target, displayPath, containedIn, systemPath: systemPathMapped, hasMap, siblingsByKind, keySiblings, diagnostics })) {
console.log(line);
}
return;
}
renderOverviewHeader(target, displayPath, containedIn, systemPathMapped, hasMap);
// Nearby structure
if (siblingsByKind && Object.keys(siblingsByKind).length > 0) {
renderSection("Nearby structure");
const sorted = Object.entries(siblingsByKind).sort((a, b) => b[1] - a[1]);
for (const [kind, count] of sorted) {
renderKeyValue(siblingKindLabel(kind), String(count));
}
}
// Key siblings
if (keySiblings && keySiblings.length > 0) {
renderSection("Key siblings");
for (const s of keySiblings) {
console.log(` ${s.name}`);
}
}
renderDiagnostics(diagnostics);
}
// ── llm rendering ────────────────────────────────────────────────────────────
function systemPathField(systemPath: Array<{ name: string }>, hasMap: boolean): LlmValue {
return systemPath.length > 1 && hasMap ? systemPath.map((n) => n.name).join(",") : undefined;
}
export function overviewContainerLlm(d: {
target: { name: string; kind: string };
displayPath: string | null;
systemPath: Array<{ name: string; kind: string }>;
hasMap: boolean;
childrenByKind: Record<string, number>;
keyItems: Array<{ name: string; kind: string }>;
diagnostics: string[];
}): string[] {
const lines = [llmLine("overview", [
["target", d.target.name],
["kind", d.target.kind],
["file", d.displayPath],
["system_path", systemPathField(d.systemPath, d.hasMap)],
])];
const containsEntries = Object.entries(d.childrenByKind).sort((a, b) => b[1] - a[1]);
if (containsEntries.length > 0) {
lines.push(llmLine("contains", containsEntries as Array<[string, LlmValue]>));
}
for (const item of d.keyItems) {
lines.push(llmLine("item", [["name", item.name], ["kind", item.kind]]));
}
for (const note of d.diagnostics) lines.push(llmLine("note", [["text", note]]));
return lines;
}
export function overviewLeafLlm(d: {
target: { name: string; kind: string };
displayPath: string | null;
containedIn: { kind: string; name: string } | null;
systemPath: Array<{ name: string; kind: string }>;
hasMap: boolean;
siblingsByKind: Record<string, number> | null;
keySiblings: Array<{ name: string; kind: string }> | null;
diagnostics: string[];
}): string[] {
const lines = [llmLine("overview", [
["target", d.target.name],
["kind", d.target.kind],
["file", d.displayPath],
["contained_in", d.containedIn ? `${d.containedIn.kind} ${d.containedIn.name}` : undefined],
["system_path", systemPathField(d.systemPath, d.hasMap)],
])];
if (d.siblingsByKind && Object.keys(d.siblingsByKind).length > 0) {
const entries = Object.entries(d.siblingsByKind).sort((a, b) => b[1] - a[1]);
lines.push(llmLine("nearby", entries as Array<[string, LlmValue]>));
}
for (const s of d.keySiblings ?? []) {
lines.push(llmLine("sibling", [["name", s.name], ["kind", s.kind]]));
}
for (const note of d.diagnostics) lines.push(llmLine("note", [["text", note]]));
return lines;
}
// ── Shared rendering ────────────────────────────────────────────────────────
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 {
renderSection("Overview");
renderKeyValue("Kind", target.kind);
if (displayPath) {
renderKeyValue("File", displayPath);
}
if (containedIn) {
const containerLabel = STRUCTURAL_CONTAINER_KINDS.has(containedIn.kind)
? `${containedIn.kind} ${containedIn.name}`
: containedIn.name;
renderKeyValue("Contained in", containerLabel);
}
if (systemPath.length > 1 && hasMap) {
renderKeyValue("System path", humanizeBreadcrumb(systemPath));
}
}
function renderDiagnostics(diagnostics: string[]): void {
for (const d of diagnostics) {
renderNote(d);
}
}