Skip to content

armgit / Ix

Public Imported from GitHub
0

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

16.9 KB
Raw Blame
// 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);
  }
}