Skip to content

armgit / Ix

Public Imported from GitHub
0

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

45.5 KB
Raw Blame
// Copyright 2026 Ix Infrastructure Inc.

import chalk from "chalk";
import { llmLine, llmShortId, type LlmValue } from "./llm.js";
import { projectRow, requestedFields } from "./output-shape.js";
import type { EdgeSite } from "./edge-sites.js";

export type ResultSource = "graph" | "text" | "graph+text" | "heuristic";

// ── JSON output shape ──────────────────────────────────────────────────────

/**
 * Whether the caller explicitly asked for indented JSON.
 *
 * False means nobody asked, and the shape then follows the destination:
 * indented for a terminal, compact for anything else. Two spaces of indent per
 * level is roughly a fifth of a JSON payload, and the only reader that gains
 * anything from it is a human looking at a screen. Every other reader — a pipe
 * into `jq`, an agent's tool result, the MCP child process — pays tokens for
 * whitespace it discards.
 */
let prettyJsonRequested = false;

/** Record `--pretty`. Called once from the root `preAction` hook. */
export function setPrettyJson(pretty: boolean): void {
  prettyJsonRequested = pretty;
}

/**
 * The indent `JSON.stringify` should use, read at print time.
 *
 * Deliberately not cached: `process.stdout.isTTY` is what makes this decision,
 * and a test that redirects stdout would otherwise get the shape from whatever
 * the process looked like at import time.
 */
function jsonIndent(): number | undefined {
  if (prettyJsonRequested) return 2;
  return process.stdout.isTTY ? 2 : undefined;
}

// ── Resolution notices ─────────────────────────────────────────────────────

/**
 * Notices about a guessed target (`ambiguous_target`, `fuzzy_match`) waiting for
 * the command's own json object. Module state: `ix mcp` runs commands in this
 * process by default (see mcp/runner.ts), so its runner calls
 * `resetResolutionNotices` before each command, and so should tests that call a
 * command in-process.
 */
let pendingResolutionNotices: unknown[] = [];

/** Queue notices for the next `printJson`. */
export function noteResolutionNotices(list: readonly unknown[]): void {
  pendingResolutionNotices.push(...list);
}

export function takeResolutionNotices(): unknown[] {
  const taken = pendingResolutionNotices;
  pendingResolutionNotices = [];
  return taken;
}

export function resetResolutionNotices(): void {
  pendingResolutionNotices = [];
}

/**
 * Merge pending notices into a plain object that is not an error record.
 * Anything else (an array, a scalar, an `{error}`) is printed untouched and the
 * notices are dropped: an error is its own answer, and the exit code is the same.
 */
function withResolutionNotices(value: unknown): unknown {
  const notices = takeResolutionNotices();
  if (notices.length === 0) return value;
  if (value === null || typeof value !== "object" || Array.isArray(value)) return value;
  const obj = value as Record<string, unknown>;
  if (typeof obj.error === "string") return value;
  const fuzzy = notices.some((n) => (n as { code?: string })?.code === "fuzzy_match");
  return {
    ...obj,
    ...(fuzzy && obj.resolutionMode === undefined ? { resolutionMode: "fuzzy" } : {}),
    resolutionNotices: notices,
  };
}

/** Set while {@link captureJson} runs: payloads are collected instead of printed. */
let jsonSink: unknown[] | undefined;

/** Print a JSON payload on stdout, indented only when that helps someone. */
export function printJson(value: unknown): void {
  const payload = withResolutionNotices(value);
  if (jsonSink) {
    jsonSink.push(payload);
    return;
  }
  console.log(JSON.stringify(payload, null, jsonIndent()));
}

/**
 * Run `fn` and return the payloads it passed to `printJson`, unprinted. A
 * multi-target command runs its one-target body per target and prints one
 * object grouping them, rather than several JSON documents on one stream.
 */
export async function captureJson(fn: () => Promise<void>): Promise<unknown[]> {
  const previous = jsonSink;
  const sink: unknown[] = [];
  jsonSink = sink;
  try {
    await fn();
  } finally {
    jsonSink = previous;
  }
  return sink;
}

// ── JSON optimization helpers ──────────────────────────────────────────────

/**
 * Strip the cwd prefix from absolute paths to save tokens in JSON output.
 *
 * Under the client-agnostic backend design, source_uri values are already
 * workspace-relative. For those we return the input unchanged. Legacy absolute
 * paths (e.g. from older graphs) are still handled the old way.
 */
export function relativePath(absPath: string | undefined | null): string | undefined {
  if (!absPath) return undefined;
  // Already relative (workspace-relative path from post-migration graphs).
  if (!absPath.startsWith("/") && !/^[A-Za-z]:[\\/]/.test(absPath)) return absPath;
  const cwd = process.cwd();
  if (absPath.startsWith(cwd + "/")) return absPath.slice(cwd.length + 1);
  // Also handle /Users/.../project/ style without trailing slash match
  const home = process.env.HOME;
  if (home && absPath.startsWith(home)) {
    return "~" + absPath.slice(home.length);
  }
  return absPath;
}

/** Round a number to N decimal places (default 2). */
export function roundFloat(n: number, decimals: number = 2): number {
  const factor = Math.pow(10, decimals);
  return Math.round(n * factor) / factor;
}

/** Remove keys with null/undefined values from an object (shallow). */
export function stripNulls<T extends Record<string, unknown>>(obj: T): Partial<T> {
  const result: Record<string, unknown> = {};
  for (const [k, v] of Object.entries(obj)) {
    if (v !== null && v !== undefined) result[k] = v;
  }
  return result as Partial<T>;
}

/** Compact a tree node for JSON output — drops UUIDs, resolved:true, sourceEdge, uses relative paths. */
export function compactTreeNode(node: any): any {
  const out: any = { name: node.name, kind: node.kind };
  if (node.relation) out.rel = node.relation;
  if (node.path) out.path = relativePath(node.path);
  if (node.cycle) out.cycle = true;
  if (node.resolved === false) out.resolved = false;
  if (node.children?.length > 0) {
    out.children = node.children.map(compactTreeNode);
  }
  return out;
}

// ── Bounded lists ──────────────────────────────────────────────────────────

/** A list that was cut to `--limit`, and what it left behind. */
export interface Slice<T> {
  /** The rows to print. */
  rows: T[];
  /** How many rows are printed. */
  shown: number;
  /** How many there were before the cut. */
  total: number;
  truncated: boolean;
  /** How many ranked rows were skipped before `rows` (paging); absent means 0. */
  offset?: number;
  /** The `--offset` of the next page; set only when rows remain. */
  nextOffset?: number;
  /** The command that prints the next page, when the caller can build one. */
  next?: string;
  /**
   * The server cut the list before this layer saw it, so `total` is a lower
   * bound: more rows may exist past it, and no `--offset` can reach them.
   */
  capped?: boolean;
}

/**
 * Rank, then cut, then report both numbers.
 *
 * Every one of these commands used to slice first and then report the length of
 * the slice as `total`, so `ix callers` on a symbol with 212 callers answered
 * `total=50` — a number an agent has no reason to disbelieve, and which reads
 * as "this symbol has 50 callers". The order matters as much as the count: a
 * cut applied to an unranked list keeps whichever rows the graph happened to
 * return first.
 *
 * `priority` is a small integer, low first, and the sort is stable, so rows
 * that rank equally keep the order the backend gave them. It is not a general
 * re-sort: the backend order carries information this layer cannot reconstruct,
 * and the only claim made here is that rows the caller can act on should
 * survive the cut before rows it cannot.
 */
export function sliceRanked<T>(all: T[], limit: number, priority?: (item: T) => number, offset = 0): Slice<T> {
  const ranked = priority ? [...all].sort((a, b) => priority(a) - priority(b)) : all;
  const rows = Number.isFinite(limit) ? ranked.slice(offset, offset + limit) : ranked.slice(offset);
  const truncated = offset + rows.length < all.length;
  const slice: Slice<T> = { rows, shown: rows.length, total: all.length, truncated };
  if (offset > 0) slice.offset = offset;
  // A page that printed nothing (`--limit 0`) has no next page to point at:
  // `next_offset` would equal this offset and a caller following it would loop.
  if (truncated && rows.length > 0) slice.nextOffset = offset + rows.length;
  return slice;
}

/**
 * A name the extractor could not resolve to an entity — a raw id standing in
 * for a call target that was never ingested.
 */
function isRawIdName(value: string): boolean {
  return /^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(value) || /^[0-9a-f]{32,}$/i.test(value);
}

function edgeRowPriority(node: any): number {
  // A dispatch row (`ix callers` through a supertype) follows every direct one.
  const dispatch = typeof node.dispatchVia === "string" ? 3 : 0;
  const name = node.name || node.attrs?.name || "";
  const resolved = !!name && !isRawIdName(name);
  if (!resolved) return dispatch + 2;
  const path = node.provenance?.source_uri ?? node.provenance?.sourceUri ?? node.attrs?.path;
  return dispatch + (path ? 0 : 1);
}

/** The supertype member a dispatch row's call targets (`via`), absent on a direct row. */
function dispatchVia(node: any): string | undefined {
  return typeof node.dispatchVia === "string" ? node.dispatchVia : undefined;
}

/**
 * Cut an edge expansion to `--limit`, keeping the rows a caller can follow.
 *
 * A row whose name is a raw id is a dangling reference: `explain`, `read` and
 * `callers` can all do nothing with it. A named row with no path costs the
 * caller a `locate` before it can be read. Neither should displace a row that
 * carries both.
 */
export function sliceEdgeResults(nodes: any[], limit: number, offset = 0, capped = false): Slice<any> {
  const slice = sliceRanked(nodes, limit, edgeRowPriority, offset);
  if (capped) {
    slice.capped = true;
    // The list is not known to end here, whatever this page holds.
    slice.truncated = true;
  }
  return slice;
}

/**
 * The most edges one /v1/expand call returns. The backend clamps the request's
 * `limit` to this (Ix-memory ArangoGraphQueryApi.expand / expandWith:
 * `maxEdges = min(limit, 1000)`, and ExpandRoutes defaults `limit` to 1000).
 */
export const EXPAND_MAX_EDGES = 1000;

/**
 * Whether an expand result may have been cut by the server's edge cap. The
 * server says so in `truncated` when it is new enough to; an older one only
 * shows it by returning a full cap's worth of edges or nodes.
 */
export function expandCapped(result: { nodes?: unknown[]; edges?: unknown[]; truncated?: unknown }): boolean {
  return result.truncated === true
    || (result.edges?.length ?? 0) >= EXPAND_MAX_EDGES
    || (result.nodes?.length ?? 0) >= EXPAND_MAX_EDGES;
}

/**
 * Which rows a page printed: `51-100` past the first page, the bare count on
 * it. A page that printed nothing is `0` — with `--limit 0 --offset 50` the
 * range form would read `51-50`.
 */
function pageRange(slice: Slice<unknown>): string {
  const offset = slice.offset ?? 0;
  return offset > 0 && slice.shown > 0 ? `${offset + 1}-${offset + slice.shown}` : `${slice.shown}`;
}

/**
 * What was left out, and the one flag that gets it.
 *
 * `next:` is printed only when the caller set `slice.next`: that is how a
 * command says it takes `--offset`. `sliceRanked` sets `nextOffset` on every
 * truncated slice, including slices cut by commands with no `--offset` (`ix
 * impact`'s leaf rows), and pointing those at a flag they reject would send the
 * reader into an unknown-option error.
 */
export function truncationHint(slice: Slice<unknown>, relation: string): string {
  if (slice.capped) return cappedHint(slice, relation);
  const range = pageRange(slice);
  if (slice.nextOffset === undefined || slice.next === undefined) return `${slice.total} ${relation}; showing ${range}. Raise --limit to see them.`;
  return `${slice.total} ${relation}; showing ${range}. next: ${slice.next}`;
}

/**
 * The hint for a list the server cut at EXPAND_MAX_EDGES: the count is a
 * floor, and paging stops where the server's rows do.
 */
function cappedHint(slice: Slice<unknown>, relation: string): string {
  const offset = slice.offset ?? 0;
  const head = `At least ${slice.total} ${relation} (the server returns at most ${EXPAND_MAX_EDGES} edges)`;
  if (slice.nextOffset !== undefined) {
    if (slice.next !== undefined) return `${head}; showing ${pageRange(slice)}. next: ${slice.next}`;
    return `${head}; showing ${pageRange(slice)}. Raise --limit, or narrow the target with --kind or --path, to see the rest.`;
  }
  const where = slice.shown > 0
    ? `showing ${pageRange(slice)}, the end of what it returned`
    : offset > 0 ? `--offset ${offset} is beyond the rows it returned` : "showing 0";
  return `${head}; ${where}. Narrow the target with --kind or --path to see the rest.`;
}

/** The message for a page that starts at or past the end of the list. */
function pastEndMessage(slice: Slice<unknown>, relation: string): string {
  return `${slice.total} ${relation}; --offset ${slice.offset ?? 0} is past the end.`;
}

function isPastEnd(slice: Slice<unknown>): boolean {
  // A capped list has no known end, so no offset is known to be past it.
  return !slice.capped && slice.total > 0 && (slice.offset ?? 0) >= slice.total;
}

// ── Row locations ──────────────────────────────────────────────────────────

function lineNumber(value: unknown): number | undefined {
  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
}

/**
 * Where a row's entity is, read off the graph node the row was built from.
 *
 * Every one of these rows already had the node in hand and printed a name from
 * it. A bare name costs the reader a `locate` before it can do anything, which
 * is a whole turn — around 30k tokens — against the ~30 bytes a path and a span
 * cost here.
 *
 * A file gets no span: its range is the whole file, which says nothing its path
 * does not. Same rule the context bundle's `toLocation` uses.
 */
export function rowLocation(node: any): { path?: string; lineStart?: number; lineEnd?: number } {
  const path = relativePath(
    node?.provenance?.source_uri ?? node?.provenance?.sourceUri ?? node?.attrs?.path ?? undefined,
  );
  if (String(node?.kind ?? "").toLowerCase() === "file") return { path };
  const lineStart = lineNumber(node?.attrs?.line_start);
  const lineEnd = lineNumber(node?.attrs?.line_end);
  return { path, lineStart, lineEnd };
}

/** `17-145`, or `17` when the entity is one line, or nothing when unknown. */
export function lineSpan(loc: { lineStart?: number; lineEnd?: number }): string | undefined {
  if (loc.lineStart === undefined) return undefined;
  return loc.lineEnd !== undefined && loc.lineEnd !== loc.lineStart
    ? `${loc.lineStart}-${loc.lineEnd}`
    : `${loc.lineStart}`;
}

/** `src/a.ts:17-145`, for a row a person reads. */
export function locationLabel(loc: { path?: string; lineStart?: number; lineEnd?: number }): string {
  if (!loc.path) return "";
  const span = lineSpan(loc);
  return span ? `${loc.path}:${span}` : loc.path;
}

/**
 * The ids a list of rows should print: only where nothing else on the row
 * tells it apart from another row in the same answer.
 *
 * Every search and edge row used to carry an 8-character id, and nothing an
 * agent does next takes one — `read`, `callers` and `explain` are all called
 * by name and narrowed with `--path`. Two rows with the same name, kind and
 * path are the exception: nothing a caller can pass tells them apart except
 * the id (every symbol command takes one), so those keep it. `lines` is not
 * part of the key because no command takes a span to pick by. A caller who
 * asks for ids with `--fields id` gets them on every row.
 */
export function disambiguatingIds<T>(
  rows: T[],
  key: (row: T) => string,
  id: (row: T) => string | undefined,
): Array<string | undefined> {
  const wanted = requestedFields()?.includes("id") ?? false;
  const counts = new Map<string, number>();
  for (const row of rows) counts.set(key(row), (counts.get(key(row)) ?? 0) + 1);
  return rows.map((row) => (wanted || (counts.get(key(row)) ?? 0) > 1 ? llmShortId(id(row)) : undefined));
}

/** `path:line`, the form an editor and every agent tool cites. */
export function siteLabel(site: EdgeSite): string {
  return `${site.path}:${site.line}`;
}

export function confidenceColor(score: number): (text: string) => string {
  if (score >= 0.8) return chalk.green;
  if (score >= 0.5) return chalk.yellow;
  return chalk.red;
}

export function formatContext(result: any, format: string): void {
  if (format === "json") {
    printJson(result);
    return;
  }

  // Text format
  const { claims, conflicts, decisions, intents, metadata } = result;

  console.log(
    "\n" + chalk.bold.cyan(`--- Ix Context: "${metadata.query}" ---`)
  );
  console.log(
    chalk.dim(
      `Seeds: ${metadata.seedEntities.length} | Hops: ${metadata.hopsExpanded} | Rev: ${metadata.asOfRev}`
    )
  );

  const useCompact = result.compactClaims?.length > 0;
  const displayClaims = useCompact ? result.compactClaims : (claims || []);
  const maxShow = 10;

  if (displayClaims.length > 0) {
    console.log(chalk.bold("\nClaims:"));
    displayClaims.slice(0, maxShow).forEach((c: any) => {
      if (useCompact) {
        const pct = Math.round((c.score ?? 0) * 100);
        const color = confidenceColor(c.score ?? 0);
        const loc = c.lineRange ? `:${c.lineRange[0]}-${c.lineRange[1]}` : '';
        const pathStr = c.path ? chalk.dim(` (${c.path}${loc})`) : '';
        console.log(`  ${color(`[${pct}%]`)} ${c.field}${pathStr}`);
      } else {
        const pct = Math.round((c.finalScore ?? 0) * 100);
        const color = confidenceColor(c.finalScore ?? 0);
        console.log(`  ${color(`[${pct}%]`)} ${c.claim?.statement || 'unknown'}`);
      }
    });
    if (displayClaims.length > maxShow) {
      console.log(chalk.dim(`  ... and ${displayClaims.length - maxShow} more`));
    }
  }

  if (conflicts && conflicts.length > 0) {
    console.log(`\nConflicts (${conflicts.length}):`);
    for (const c of conflicts) {
      console.log(
        `  ${chalk.red.bold("!")} ${c.reason}: ${c.recommendation}`
      );
    }
  }

  if (decisions && decisions.length > 0) {
    console.log(`\nDecisions (${decisions.length}):`);
    for (const d of decisions) {
      console.log(`  ${chalk.blue("*")} ${d.title}: ${d.rationale}`);
    }
  }

  if (intents && intents.length > 0) {
    console.log(`\nIntents (${intents.length}):`);
    for (const i of intents) {
      console.log(
        `  ${chalk.magenta(">")} ${i.statement} [${i.status}]`
      );
    }
  }
  console.log();
}

/** Render a flat node list as llm `node` records. */
export function renderNodesLlm(nodes: any[]): string[] {
  return nodes.map((n) => {
    const loc = rowLocation(n);
    return llmLine("node", projectRow([
      ["kind", n.kind],
      ["id", llmShortId(n.id)],
      ["name", n.name || n.attrs?.name || n.attrs?.title || "(unnamed)"],
      ["path", loc.path],
      ["lines", lineSpan(loc)],
    ]));
  });
}

export function formatNodes(nodes: any[], format: string): void {
  if (format === "json") {
    printJson(nodes);
    return;
  }
  if (format === "llm") {
    for (const line of renderNodesLlm(nodes)) console.log(line);
    return;
  }
  if (nodes.length === 0) {
    console.log("No results found.");
    return;
  }
  for (const n of nodes) {
    const shortId = n.id.length > 8 ? n.id.slice(0, 8) : n.id;
    const name = n.name || n.attrs?.name || n.attrs?.title || "(unnamed)";
    if (n.kind === "decision") {
      console.log(
        `  ${chalk.blue("decision")}  ${chalk.dim(shortId)}  ${name}`
      );
    } else {
      // The path is what makes a search row a place rather than a word: a
      // graph with four `config.ts` modules in it answered `ix search config`
      // with four identical-looking rows.
      const where = locationLabel(rowLocation(n));
      console.log(
        `  ${chalk.cyan(n.kind.padEnd(10))}  ${chalk.dim(shortId)}  ${chalk.bold(name)}`
        + (where ? `  ${chalk.dim(where)}` : ""),
      );
    }
  }
}

export function formatDecisions(nodes: any[], format: string): void {
  if (format === "json") {
    printJson(nodes);
    return;
  }
  if (nodes.length === 0) {
    console.log("No decisions found.");
    return;
  }
  for (const n of nodes) {
    const shortId = n.id.length > 8 ? n.id.slice(0, 8) : n.id;
    const title = n.name || n.attrs?.title || n.attrs?.name || "(untitled)";
    const rationale = n.attrs?.rationale ?? "";
    console.log(
      `  ${chalk.blue("*")} ${chalk.dim(shortId)}  ${chalk.bold(title)}`
    );
    if (rationale) {
      console.log(`    ${chalk.gray(rationale)}`);
    }
  }
}

const BUG_STATUS_ICONS: Record<string, string> = {
  open: "○",
  investigating: "◐",
  resolved: "●",
  closed: "✓",
};

export function formatBugs(nodes: any[], format: string): void {
  if (format === "json") {
    printJson(nodes);
    return;
  }
  if (nodes.length === 0) {
    console.log("No bugs found.");
    return;
  }
  for (const n of nodes) {
    const shortId = n.id.length > 8 ? n.id.slice(0, 8) : n.id;
    const title = n.name || n.attrs?.title || n.attrs?.name || "(untitled)";
    const status = n.attrs?.status ?? "open";
    const severity = n.attrs?.severity ?? "medium";
    const icon = BUG_STATUS_ICONS[status] ?? "?";
    console.log(
      `  ${icon} ${chalk.dim(`[${status}]`.padEnd(16))} ${chalk.red(severity.padEnd(8))} ${chalk.dim(shortId)}  ${chalk.bold(title)}`
    );
  }
}

/** Render patch records as llm `patch` lines. */
export function renderPatchesLlm(patches: any[]): string[] {
  return patches.map((p) => llmLine("patch", [
    ["rev", p.rev],
    ["id", p.patch_id?.slice(0, 12)],
    ["intent", p.intent || undefined],
    ["ts", p.timestamp],
    ["source", relativePath(p.source?.uri) || undefined],
  ]));
}

export function formatPatches(patches: any[], format: string): void {
  if (format === "json") {
    const compact = patches.map(p => ({
      rev: p.rev,
      patch_id: p.patch_id?.slice(0, 12),
      intent: p.intent || undefined,
      timestamp: p.timestamp,
      source: relativePath(p.source?.uri) || undefined,
    }));
    printJson(compact);
    return;
  }
  if (format === "llm") {
    for (const line of renderPatchesLlm(patches)) console.log(line);
    return;
  }
  if (patches.length === 0) {
    console.log("No patches found.");
    return;
  }
  for (const p of patches) {
    const shortPatchId =
      p.patch_id.length > 8 ? p.patch_id.slice(0, 8) : p.patch_id;
    const intentPart = p.intent
      ? chalk.white(p.intent)
      : chalk.dim("(no intent)");
    console.log(
      `  rev ${chalk.cyan.bold(String(p.rev))}  ${chalk.dim(shortPatchId)}  ${intentPart}`
    );
  }
}

export function formatIntents(intents: any[], format: string): void {
  if (format === "json") {
    printJson(intents);
    return;
  }
  if (intents.length === 0) {
    console.log("No intents found.");
    return;
  }

  // Build parent-child map
  const childrenMap = new Map<string, any[]>();
  const roots: any[] = [];

  for (const intent of intents) {
    const parentId = intent.attrs?.parent_intent ?? intent.parentIntent;
    if (parentId) {
      const siblings = childrenMap.get(parentId) || [];
      siblings.push(intent);
      childrenMap.set(parentId, siblings);
    } else {
      roots.push(intent);
    }
  }

  function printIntent(intent: any, indent: string, isChild: boolean): void {
    const prefix = isChild
      ? `${indent}${chalk.dim("\u2514\u2500")} `
      : `${indent}${chalk.magenta(">")} `;
    const statement = intent.attrs?.statement ?? intent.statement ?? "(unknown)";
    const status = intent.attrs?.status ?? intent.status ?? "unknown";
    const conf = intent.attrs?.confidence ?? intent.confidence ?? 0;
    const pctStr = `(${(conf * 100).toFixed(0)}%)`;
    const color = confidenceColor(conf);
    console.log(
      `${prefix}${statement} [${status}] ${color(pctStr)}`
    );

    const children = childrenMap.get(intent.id) || [];
    for (const child of children) {
      printIntent(child, indent + "  ", true);
    }
  }

  for (const root of roots) {
    printIntent(root, "  ", false);
  }
}

/** Render a revision diff as llm records: a header then one `change` row per entity change. */
export function renderDiffLlm(result: any): string[] {
  const changes = result.changes ?? [];
  const lines = [llmLine("diff", [["from", result.fromRev], ["to", result.toRev], ["changes", changes.length]])];
  for (const c of changes) {
    const node = c.changeType === "removed" ? c.atFromRev : c.atToRev;
    const name = node?.name || node?.attrs?.name || c.entityId?.substring(0, 8);
    lines.push(llmLine("change", [
      ["type", c.changeType],
      ["kind", node?.kind],
      ["name", name],
      ["summary", c.summary || undefined],
    ]));
  }
  return lines;
}

export function formatDiff(result: any, format: string): void {
  if (format === "json") {
    printJson(result);
    return;
  }
  if (format === "llm") {
    for (const line of renderDiffLlm(result)) console.log(line);
    return;
  }
  console.log(chalk.cyan.bold(`\nDiff: rev ${result.fromRev} → ${result.toRev}`));
  if (!result.changes?.length) {
    console.log(chalk.dim("  No changes in this range."));
    return;
  }

  const added = result.changes.filter((c: any) => c.changeType === "added");
  const modified = result.changes.filter((c: any) => c.changeType === "modified");
  const removed = result.changes.filter((c: any) => c.changeType === "removed");
  const legacy = result.changes.filter((c: any) => c.changeType === "added_or_modified");

  if (added.length > 0) {
    console.log(chalk.green.bold(`\n  Added (${added.length}):`));
    for (const c of added) {
      const node = c.atToRev;
      const name = node?.name || node?.attrs?.name || c.entityId?.substring(0, 8);
      const kind = node?.kind || "unknown";
      const summary = c.summary ? chalk.dim(` — ${c.summary}`) : "";
      console.log(`    ${chalk.green("+")} ${chalk.cyan(kind.padEnd(10))} ${chalk.bold(name)}${summary}`);
    }
  }

  if (modified.length > 0) {
    console.log(chalk.yellow.bold(`\n  Modified (${modified.length}):`));
    for (const c of modified) {
      const node = c.atToRev;
      const name = node?.name || node?.attrs?.name || c.entityId?.substring(0, 8);
      const kind = node?.kind || "unknown";
      const summary = c.summary ? chalk.dim(` — ${c.summary}`) : "";
      console.log(`    ${chalk.yellow("~")} ${chalk.cyan(kind.padEnd(10))} ${chalk.bold(name)}${summary}`);
    }
  }

  if (removed.length > 0) {
    console.log(chalk.red.bold(`\n  Removed (${removed.length}):`));
    for (const c of removed) {
      const node = c.atFromRev;
      const name = node?.name || node?.attrs?.name || c.entityId?.substring(0, 8);
      const kind = node?.kind || "unknown";
      console.log(`    ${chalk.red("-")} ${chalk.cyan(kind.padEnd(10))} ${chalk.bold(name)}`);
    }
  }

  if (legacy.length > 0) {
    console.log(chalk.yellow.bold(`\n  Changed (${legacy.length}):`));
    for (const c of legacy) {
      const node = c.atToRev;
      const name = node?.name || node?.attrs?.name || c.entityId?.substring(0, 8);
      const kind = node?.kind || "unknown";
      console.log(`    ${chalk.yellow("~")} ${chalk.cyan(kind.padEnd(10))} ${chalk.bold(name)}`);
    }
  }
  console.log();
}

export interface TextResult {
  path: string;
  line_start: number;
  line_end: number;
  snippet: string;
  engine: string;
  score: number;
  language?: string;
  symbol_hint?: string;
}

/** How `ix text` paged: whether the scan window filled before ripgrep ran out of matches. */
export interface TextPaging {
  /**
   * More matches existed than the scan window kept. Pages are cut from that
   * window, so the page that reaches its end has no next page even though the
   * search does — the caller has to narrow the search instead.
   */
  windowFull?: boolean;
}

/**
 * Whether a text page starts past the last match. Only when the scan window
 * held every match: a full window is not the end of the search, so an offset
 * beyond it is not past the end of anything the caller can know.
 */
function isTextPastEnd(slice: Slice<TextResult>, paging?: TextPaging): boolean {
  return !paging?.windowFull && isPastEnd(slice);
}

/**
 * What a text page left out, and how to get it: the next page while the scan
 * window has rows left, a narrower search once the page reached the window's
 * end. Undefined when nothing was left out.
 */
function textTruncationMessage(slice: Slice<TextResult>, paging?: TextPaging): string | undefined {
  if (isTextPastEnd(slice, paging)) return undefined;
  const range = pageRange(slice);
  if (slice.nextOffset !== undefined) {
    return `${slice.total} matches scanned; showing ${range}. next: ${slice.next ?? `--offset ${slice.nextOffset}`}`;
  }
  if (paging?.windowFull && slice.shown > 0) {
    return `${slice.total} matches scanned; showing ${range}; the scan stops at ${slice.total}. Narrow with --path or --language, or raise --limit.`;
  }
  if (paging?.windowFull && (slice.offset ?? 0) >= slice.total) {
    return `${slice.total} matches scanned; --offset ${slice.offset ?? 0} is past the scan window, which stops at ${slice.total}. Narrow with --path or --language, or raise --limit.`;
  }
  if (slice.truncated) {
    return `${slice.total} matches scanned; showing ${range}. Narrow with --path or --language, or raise --limit.`;
  }
  return undefined;
}

/**
 * Render lexical search hits as llm `match` records (one per line).
 *
 * No `lang=`: the extension on `path` already says it, and on a 20-row answer
 * the field was ~80 tokens of nothing. `--format json` keeps `language`.
 *
 * `scanned` is the size of the ranked scan window, not the number of matches
 * in the repo; pages (`--offset`) are cut from that window.
 */
export function renderTextResultsLlm(slice: Slice<TextResult>, paging?: TextPaging): string[] {
  const message = textTruncationMessage(slice, paging);
  const lines = [llmLine("text", [
    ["offset", slice.offset ? slice.offset : undefined],
    ["shown", slice.shown],
    ["scanned", slice.total],
    ["truncated", slice.truncated || message !== undefined || undefined],
  ])];
  if (message !== undefined) {
    lines.push(llmLine("diagnostic", [
      ["code", "results_truncated"],
      ["next_offset", slice.nextOffset],
      ["message", message],
    ]));
  }
  if (slice.rows.length === 0 && isTextPastEnd(slice, paging)) {
    lines.push(llmLine("diagnostic", [
      ["code", "offset_past_end"],
      ["message", pastEndMessage(slice, "matches scanned")],
    ]));
  }
  for (const r of slice.rows) {
    lines.push(llmLine("match", [
      ["path", relativePath(r.path) ?? r.path],
      ["line", r.line_start],
      ["symbol", r.symbol_hint],
      ["snippet", r.snippet.trim()],
    ]));
  }
  return lines;
}

export function formatTextResults(slice: Slice<TextResult>, format: string, paging?: TextPaging): void {
  const results = slice.rows;
  if (format === "json") {
    // A raw array on purpose: the plugin runners parse it as one. Paging state
    // stays out of it; a JSON caller's next offset is its offset plus the
    // array's length.
    const compact = results.map(r => ({
      ...r,
      path: relativePath(r.path) ?? r.path,
    }));
    printJson(compact);
    return;
  }
  if (format === "llm") {
    for (const line of renderTextResultsLlm(slice, paging)) console.log(line);
    return;
  }
  if (results.length === 0) {
    console.log(isTextPastEnd(slice, paging)
      ? pastEndMessage(slice, "matches scanned")
      : textTruncationMessage(slice, paging) ?? "No text matches found.");
    return;
  }
  for (const r of results) {
    const lang = r.language ? chalk.magenta(`[${r.language}]`) + " " : "";
    const sym = r.symbol_hint ? chalk.yellow(`(${r.symbol_hint})`) + " " : "";
    console.log(
      `  ${lang}${chalk.dim(r.path)}${chalk.cyan(":" + r.line_start)}  ${sym}${r.snippet.trim()}`
    );
  }
  const message = textTruncationMessage(slice, paging);
  if (message !== undefined) console.log(chalk.dim(`  ${message}`));
}

export interface LocateResult {
  kind: string;
  id?: string;
  name: string;
  file?: string;
  line?: number;
  source: "graph" | "ripgrep";
}

export function formatLocateResults(results: LocateResult[], format: string): void {
  if (format === "json") {
    printJson(results);
    return;
  }
  if (results.length === 0) {
    console.log("No matches found.");
    return;
  }
  for (const r of results) {
    const shortId = r.id ? chalk.dim(r.id.slice(0, 8)) + "  " : "";
    const filePart = r.file ? chalk.dim(r.file) + (r.line ? chalk.cyan(`:${r.line}`) : "") : "";
    console.log(`  ${chalk.cyan(r.kind)}  ${shortId}${chalk.bold(r.name)}`);
    if (filePart) {
      console.log(`    ${filePart}`);
    }
  }
}

/**
 * Render edge-query results (callers/callees/contains/imports/imported-by) as
 * llm records: a header line keyed by the relation, optional diagnostic lines,
 * then one `ref` row per related entity. Unresolved targets carry resolved=false.
 */
/**
 * The candidates an `--all` edge query ran over. Rows carry `candidate: <n>`,
 * numbering into this list.
 */
export interface EdgeCandidate {
  n: number;
  id: string;
  name: string;
  kind: string;
  path?: string;
}

export function renderEdgeResultsLlm(
  slice: Slice<any>, relation: string, symbol: string,
  source?: ResultSource, diagnostics?: Diagnostic[], candidates?: EdgeCandidate[],
): string[] {
  const refs = slice.rows.map((n: any) => {
    const name = n.name || n.attrs?.name || "";
    return {
      resolved: !!name && !isRawIdName(name),
      name,
      kind: n.kind ?? undefined,
      id: n.id ?? undefined,
      site: n.site as EdgeSite | undefined,
      candidate: typeof n.candidate === "number" ? n.candidate as number : undefined,
      via: dispatchVia(n),
      ...rowLocation(n),
    };
  });
  const ids = disambiguatingIds(
    refs,
    (r) => `${r.name}\u0000${r.kind ?? ""}\u0000${r.path ?? ""}`,
    (r) => r.id,
  );
  const unresolved = refs.filter((r) => !r.resolved).length;
  const lines = [llmLine(relation, [
    ["target", symbol],
    ["offset", slice.offset ? slice.offset : undefined],
    ["shown", slice.shown],
    ["total", slice.total],
    ["resolved", refs.length - unresolved],
    ["unresolved", unresolved > 0 ? unresolved : undefined],
    ["source", source && source !== "graph" ? source : undefined],
    ["candidates", candidates ? candidates.length : undefined],
  ])];
  for (const c of candidates ?? []) {
    lines.push(llmLine("candidate", [
      ["n", c.n], ["name", c.name], ["kind", c.kind],
      ["path", c.path ? relativePath(c.path) ?? c.path : undefined], ["id", llmShortId(c.id)],
    ]));
  }
  if (slice.truncated) {
    lines.push(llmLine("diagnostic", [
      ["code", "results_truncated"],
      ["next_offset", slice.nextOffset],
      ["message", truncationHint(slice, relation)],
    ]));
  }
  if (refs.length === 0 && isPastEnd(slice)) {
    lines.push(llmLine("diagnostic", [["code", "offset_past_end"], ["message", pastEndMessage(slice, relation)]]));
  } else if (refs.length === 0 && !slice.truncated && (!diagnostics || diagnostics.length === 0)) {
    lines.push(llmLine("diagnostic", [["code", "no_edges"], ["message", `No ${relation} edges found.`]]));
  }
  for (const d of diagnostics ?? []) {
    lines.push(llmLine("diagnostic", [["code", d.code], ["message", d.message]]));
  }
  refs.forEach((ref, i) => {
    // Which `--all` candidate the row belongs to. Outside projectRow: a row
    // that lost it under `--fields` could not be attributed at all.
    const tag: Array<[string, LlmValue]> = ref.candidate !== undefined ? [["candidate", ref.candidate]] : [];
    // A dispatch row: the call targets this supertype member.
    if (ref.via !== undefined) tag.push(["via", ref.via]);
    // An unresolved row has no name to go by, so its id is all there is.
    lines.push(ref.resolved
      ? llmLine("ref", [...projectRow([
          ["name", ref.name], ["kind", ref.kind], ["id", ids[i]],
          ["path", ref.path], ["lines", lineSpan(ref)],
          ["site", ref.site ? siteLabel(ref.site) : undefined],
          ["also", ref.site?.also?.join(",")],
          ["snippet", ref.site?.snippet],
        ]), ...tag])
      : llmLine("ref", [...projectRow([["kind", ref.kind], ["id", llmShortId(ref.id)], ["resolved", false]]), ...tag]));
  });
  return lines;
}

export function formatEdgeResults(
  slice: Slice<any>, relation: string, symbol: string, format: string,
  resolvedTarget?: { id: string; kind: string; name: string; resolutionMode?: string },
  source?: ResultSource,
  diagnostics?: Diagnostic[],
  candidates?: EdgeCandidate[],
): void {
  const nodes = slice.rows;

  if (format === "llm") {
    for (const line of renderEdgeResultsLlm(slice, relation, symbol, source, diagnostics, candidates)) {
      console.log(line);
    }
    return;
  }

  if (format === "json") {
    const results = nodes.map((n: any) => {
      const name = n.name || n.attrs?.name || "";
      const resolved = !!name && !isRawIdName(name);
      const ref: any = {
        name: resolved ? name : undefined,
        kind: n.kind ?? undefined,
        id: resolved ? n.id : undefined,
        ...rowLocation(n),
        ...(n.site ? { site: n.site } : {}),
        ...(typeof n.candidate === "number" ? { candidate: n.candidate } : {}),
        ...(dispatchVia(n) ? { via: dispatchVia(n) } : {}),
      };
      if (!resolved) {
        ref.resolved = false;
        if (n.id) {
          ref.rawId = n.id;
          ref.diagnostic = "unresolved_call_target";
        }
      }
      return ref;
    });

    const output: any = {
      results,
      resultSource: source ?? "graph",
    };
    if (resolvedTarget) {
      output.resolvedTarget = {
        ...resolvedTarget,
        path: relativePath((resolvedTarget as any).path),
      };
      if (resolvedTarget.resolutionMode && resolvedTarget.resolutionMode !== "exact") {
        output.resolutionMode = resolvedTarget.resolutionMode;
      }
    }
    if (candidates) {
      output.resolutionMode = "all";
      output.candidates = candidates.map((c) => ({ ...c, path: relativePath(c.path) ?? c.path }));
    }
    if (nodes.length === 0) {
      output.diagnostics = isPastEnd(slice)
        ? [{ code: "offset_past_end", message: pastEndMessage(slice, relation) }]
        : diagnostics ?? (slice.truncated ? undefined : [{ code: "no_edges", message: `No ${relation} edges found for resolved entity.` }]);
    } else if (diagnostics && diagnostics.length > 0) {
      output.diagnostics = diagnostics;
    }
    if (slice.truncated) {
      output.diagnostics = [
        ...(output.diagnostics ?? []),
        { code: "results_truncated", message: truncationHint(slice, relation) },
      ];
    }
    const unresolvedCount = results.filter((r: any) => r.resolved === false).length;
    if (unresolvedCount > 0) {
      output.diagnostics = [
        ...(output.diagnostics ?? []),
        { code: "dangling_reference_filtered", message: `${unresolvedCount} result(s) could not be resolved to named entities.` },
      ];
    }
    output.summary = {
      shown: slice.shown,
      total: slice.total,
      resolved: results.length - unresolvedCount,
      unresolved: unresolvedCount,
      truncated: slice.truncated,
      offset: slice.offset ?? 0,
      ...(slice.nextOffset !== undefined ? { nextOffset: slice.nextOffset } : {}),
      // `total` is then a lower bound: the server stopped at its edge cap.
      ...(slice.capped ? { capped: true } : {}),
    };
    printJson(output);
    return;
  }
  if (nodes.length === 0) {
    const reason = isPastEnd(slice)
      ? pastEndMessage(slice, relation)
      : slice.truncated
        ? truncationHint(slice, relation)
        : diagnostics?.[0]?.message ?? `No ${relation} found for "${symbol}".`;
    console.log(reason);
    return;
  }
  console.log(`${chalk.bold(relation)} of ${chalk.cyan(symbol)}:`);
  if (source && source !== "graph") {
    console.log(chalk.dim(`Source: ${source}`));
  }
  for (const c of candidates ?? []) {
    const where = c.path ? ` in ${relativePath(c.path) ?? c.path}` : "";
    console.log(chalk.dim(`  [${c.n}] ${c.kind} ${c.name}${where}`));
  }
  for (const n of nodes) {
    const name = n.name || n.attrs?.name || "";
    const shortId = n.id?.slice(0, 8) ?? "";
    if (!name || isRawIdName(name)) {
      console.log(`  ${chalk.cyan((n.kind ?? "").padEnd(10))}  ${chalk.dim(shortId)}  ${chalk.dim("(unresolved)")}`);
    } else {
      const where = locationLabel(rowLocation(n));
      console.log(
        `  ${chalk.cyan((n.kind ?? "").padEnd(10))}  ${chalk.dim(shortId)}  ${chalk.bold(name)}`
        + (where ? `  ${chalk.dim(where)}` : "")
        + (typeof n.candidate === "number" ? `  ${chalk.dim(`[${n.candidate}]`)}` : "")
        + (dispatchVia(n) ? `  ${chalk.dim(`(via ${dispatchVia(n)})`)}` : ""),
      );
      const site = n.site as EdgeSite | undefined;
      if (site) console.log(`      ${chalk.dim(`at ${siteLabel(site)}`)}  ${site.snippet}`);
    }
  }
  if (slice.truncated) console.log(chalk.dim(`  ${truncationHint(slice, relation)}`));
}

/** Render detected conflicts as llm `conflict` records. */
export function renderConflictsLlm(conflicts: any[]): string[] {
  const lines = [llmLine("conflicts", [["count", conflicts.length]])];
  for (const c of conflicts) {
    lines.push(llmLine("conflict", [
      ["reason", c.reason],
      ["recommendation", c.recommendation],
      ["claim_a", llmShortId(c.claimA)],
      ["claim_b", llmShortId(c.claimB)],
    ]));
  }
  return lines;
}

export function formatConflicts(conflicts: any[], format: string): void {
  if (format === "json") {
    printJson(conflicts);
    return;
  }
  if (format === "llm") {
    for (const line of renderConflictsLlm(conflicts)) console.log(line);
    return;
  }
  if (conflicts.length === 0) {
    console.log("No conflicts detected.");
    return;
  }
  for (const c of conflicts) {
    console.log(`  ${chalk.red.bold("!")} ${c.reason}`);
    console.log(`    ${chalk.yellow(c.recommendation)}`);
    console.log(`    Claims: ${c.claimA} vs ${c.claimB}`);
  }
}

/** A resolved or unresolved reference to a related entity. */
export interface EntityRef {
  name: string;
  kind?: string;
  id?: string;
  resolved: boolean;
  path?: string;
  lineStart?: number;
  lineEnd?: number;
  suggestedCommand?: string;
}

export type DiagnosticCode =
  | "unresolved_call_target"
  | "parser_gap_suspected"
  | "dangling_reference_filtered"
  | "ambiguous_resolution"
  | "no_edges"
  | "text_fallback_used"
  | "stale_source"
  | "unfiltered_search"
  | "graph_degraded"
  | "candidates_truncated";

export interface Diagnostic {
  code: DiagnosticCode;
  message: string;
}

export interface ExplainResult {
  kind: string;
  name: string;
  id: string;
  file?: string;
  chunkKind?: string;
  container?: { kind: string; name: string };
  introducedRev: number;
  calledBy: number;
  calls: number;
  contains: number;
  historyLength: number;
  signature?: string;
  docstring?: string;
  callList?: EntityRef[];
  diagnostics?: Diagnostic[];
}

export function formatExplain(result: ExplainResult, format: string): void {
  if (format === "json") {
    const output: any = {
      resolvedTarget: { id: result.id, kind: result.kind, name: result.name },
      result: stripNulls({
        kind: result.kind,
        name: result.name,
        id: result.id,
        file: relativePath(result.file),
        chunkKind: result.chunkKind ?? null,
        container: result.container,
        introducedRev: result.introducedRev,
        calledBy: result.calledBy,
        calls: result.calls,
        contains: result.contains,
        historyLength: result.historyLength,
        signature: result.signature ?? null,
        docstring: result.docstring ?? null,
        callList: result.callList,
      }),
    };
    if (result.diagnostics && result.diagnostics.length > 0) {
      output.diagnostics = result.diagnostics;
    }
    printJson(output);
    return;
  }
  const shortId = result.id.slice(0, 8);
  if (result.signature) {
    console.log(`  ${chalk.green(result.signature)}`);
  } else {
    console.log(`  ${chalk.cyan(result.kind)} ${chalk.bold(result.name)} ${chalk.dim(shortId)}`);
  }
  if (result.docstring) {
    console.log(`  ${chalk.dim('"' + result.docstring + '"')}`);
  }
  if (result.container) {
    console.log(`  ${chalk.dim("in")} ${chalk.cyan(result.container.kind)} ${result.container.name}`);
  }
  if (result.file) {
    console.log(`  ${chalk.dim("file")} ${result.file}`);
  }
  if (result.chunkKind) {
    console.log(`  ${chalk.dim("chunk kind")} ${result.chunkKind}`);
  }
  console.log(`  ${chalk.dim("introduced rev")} ${result.introducedRev}`);
  if (result.calledBy > 0) console.log(`  ${chalk.dim("called by")} ${result.calledBy} methods`);
  if (result.callList && result.callList.length > 0) {
    console.log(`  ${chalk.dim("calls:")}`);
    for (const c of result.callList) {
      const label = c.resolved
        ? c.name
        : chalk.dim(`${c.name} (unresolved)`);
      console.log(`    ${label}`);
    }
  } else if (result.calls > 0) {
    console.log(`  ${chalk.dim("calls")} ${result.calls} methods`);
  }
  if (result.contains > 0) console.log(`  ${chalk.dim("contains")} ${result.contains} members`);
  if (result.historyLength > 0) console.log(`  ${chalk.dim("history")} ${result.historyLength} patches`);
  if (result.diagnostics && result.diagnostics.length > 0) {
    for (const d of result.diagnostics) {
      console.log(`  ${chalk.dim(`[${d.code}]`)} ${d.message}`);
    }
  }
}