Skip to content

armgit / Ix

Public Imported from GitHub
0

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

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

import type { Command } from "commander";
import { renderSection, renderKeyValue, renderWarning, renderNote, renderSuccess } from "../ui.js";
import { createClient } from "../../client/factory.js";
import { readBackendHealth } from "./upgrade.js";
import { findWorkspaceForCwd, getEndpoint, resolveWorkspaceRoot } from "../config.js";
import { detectStaleFiles } from "../stale.js";
import { llmError, llmLine, printLlmLines } from "../llm.js";
import { backendUnreachableError, isBackendUnreachable } from "../errors.js";
import { printJson } from "../format.js";
import {
  checkGraphHealth,
  describeReplayedChanges,
  GRAPH_REBUILD_FIX,
  graphHealthJson,
  graphHealthLlmFields,
  graphHealthProse,
  isUnhealthy,
  type GraphHealth,
  type GraphHealthScope,
} from "../graph-health.js";
import { detectSystem } from "../system.js";
import { loadVerifyRecord, verifyRecordOutdated, type VerifyRecord } from "../verify.js";

interface StatusStaleInfo {
  graphCompleted: boolean;
  mapCompleted: boolean;
  /** The map was deferred after an edit (CL-13); see `StaleInfo.mapStale`. */
  mapStale?: boolean;
  /** Why the last background map refresh failed, while the map is stale; see `StaleInfo.mapRefreshError`. */
  mapRefreshError?: string | null;
  currentRev: number;
  lastIngestAt: string | null;
  staleFiles: number;
  sampleChangedFiles: string[];
  /** Changed files the last run could not get applied (F-01); see `IngestBaseline.replayedFiles`. */
  replayedFiles?: string[];
  /** Files skipped because their parse ran past the budget; see `IngestBaseline.parseTimeouts`. */
  parseTimeouts?: string[];
}

/**
 * `ix status --format llm`.
 *
 * The reason to call `status` from an agent is to decide one thing: is the
 * source graph current enough to trust, or does it need `ix map` first. `text` buries
 * that behind section headers, a "Last ingest" field humanised to "3h ago", and
 * a sampled file list. The `stale` field answers it directly, and
 * `last_ingest_at` stays ISO so the consumer can do its own arithmetic instead
 * of parsing prose. `map_complete` separately reports whether an architecture
 * hierarchy exists for that source revision. `verified_*` come from the last
 * whole-root `ix verify`, and are absent when there has been none
 * (`verified_graph` is its verdict: clean, stale, diverged or unverified);
 * `verified_outdated=true` says the workspace was ingested after it ran, so
 * its counts describe an earlier graph.
 */
export function renderStatusLlm(
  backend: string,
  endpoint: string,
  staleInfo: StatusStaleInfo | null,
  graph?: GraphHealth,
  verified?: VerifyRecord | null,
): string[] {
  const lines = [llmLine("status", [
    ["backend", backend],
    ["endpoint", endpoint],
    ["graph_health", graph ? graphHealthWord(graph) : null],
    ["graph_complete", staleInfo ? String(staleInfo.graphCompleted) : null],
    ["map_complete", staleInfo ? String(staleInfo.mapCompleted) : null],
    // CL-13: why map_complete is false right after an edit. Only when true,
    // per the zero-drop rule.
    ["map_stale", staleInfo?.mapStale ? "true" : null],
    ["map_refresh_error", staleInfo?.mapStale ? staleInfo.mapRefreshError ?? null : null],
    ["rev", staleInfo ? String(staleInfo.currentRev) : null],
    ["last_ingest_at", staleInfo?.lastIngestAt ?? null],
    ["stale_files", staleInfo ? String(staleInfo.staleFiles) : null],
    ["not_applied", staleInfo ? String(staleInfo.replayedFiles?.length ?? 0) : null],
    ["parse_timeouts", staleInfo ? String(staleInfo.parseTimeouts?.length ?? 0) : null],
    ["stale", staleInfo
      ? (!staleInfo.graphCompleted || staleInfo.staleFiles > 0 || (staleInfo.replayedFiles?.length ?? 0) > 0
        || (staleInfo.parseTimeouts?.length ?? 0) > 0 ? "true" : "false")
      : null],
    ["verified_at", verified?.at ?? null],
    ["verified_files", verified ? String(verified.files) : null],
    ["verified_diverged", verified ? String(verified.diverged) : null],
    ["verified_outdated", verified ? String(verifyRecordOutdated(verified, staleInfo?.lastIngestAt)) : null],
    // Last, so the fields before it keep their place.
    ["verified_graph", verified?.graph ?? null],
  ])];
  if (graph && isUnhealthy(graph)) lines.push(llmLine("graph", graphHealthLlmFields(graph)));
  for (const f of staleInfo?.sampleChangedFiles ?? []) {
    lines.push(llmLine("changed", [["path", f]]));
  }
  for (const f of staleInfo?.replayedFiles ?? []) {
    lines.push(llmLine("not_applied", [["path", f]]));
  }
  for (const f of staleInfo?.parseTimeouts ?? []) {
    lines.push(llmLine("parse_timeout", [["path", f]]));
  }
  return lines;
}

/**
 * The graph verdict as `ix status` says it. "unknown" reads as "unverified":
 * the check could not run (no workspace here, an old backend, a slow stats
 * probe), which is not the same as a graph that was checked and is fine.
 */
export function graphHealthWord(graph: GraphHealth): string {
  return graph.status === "unknown" ? "unverified" : graph.status;
}

/**
 * The read scope for the status root: its system when it is in one, else the
 * workspace containing it. None when the root is in no registered workspace,
 * so the graph check answers "unverified" rather than judging another repo.
 */
export function statusGraphScope(root: string): GraphHealthScope | undefined {
  const systemId = detectSystem(root)?.systemId;
  if (systemId) return { systemId };
  const workspaceId = findWorkspaceForCwd(root)?.workspace_id;
  return workspaceId ? { workspaceId } : undefined;
}

/** The `ix status` warning for files the last run skipped on the parse budget. */
function describeStatusParseTimeouts(files: readonly string[], sample = 5): string {
  const shown = files.slice(0, sample).join(", ");
  const more = files.length > sample ? ` and ${files.length - sample} more` : "";
  return `${files.length} file(s) are not in the graph: their parse ran past the per-file budget (${shown}${more}). ` +
    "Raise IX_PARSE_BUDGET_MS (milliseconds, 0 = none) and run ix map.";
}

export function registerStatusCommand(program: Command): void {
  program
    .command("status")
    .description("Show Ix backend health and status")
    .option("--format <fmt>", "Output format (text|json|llm)", "text")
    .option("--root <dir>", "Workspace root directory")
    .action(async (opts: { format: string; root?: string }) => {
      const client = createClient();
      try {
        const health = await readBackendHealth(client);
        const root = resolveWorkspaceRoot(opts.root);
        // "No files changed" is about mtimes; whether the graph behind them is
        // whole is a separate question, asked of the backend. Cached per
        // backend revision, bounded, and never throws.
        const scope = statusGraphScope(root);
        const graphCheck: Promise<GraphHealth> = scope
          ? checkGraphHealth(client, scope)
          : Promise.resolve({ status: "unknown" });

        // Detect stale files
        let staleInfo;
        try {
          staleInfo = detectStaleFiles(root);
        } catch {
          staleInfo = null;
        }

        const graph = await graphCheck;
        // The last whole-root `ix verify`, if any. Read only: status never runs one.
        const verified = loadVerifyRecord(root);
        const verifiedOutdated = verified !== null && verifyRecordOutdated(verified, staleInfo?.lastIngestAt);

        if (opts.format === "llm") {
          printLlmLines(renderStatusLlm(health.status, getEndpoint(), staleInfo ?? null, graph, verified));
        } else if (opts.format === "json") {
          const result: any = {
            backend: health.status,
            graphCompleted: staleInfo?.graphCompleted ?? null,
            mapCompleted: staleInfo?.mapCompleted ?? null,
            mapStale: staleInfo?.mapStale ?? false,
            mapRefreshError: staleInfo?.mapStale ? staleInfo.mapRefreshError ?? null : null,
            currentRev: staleInfo?.currentRev ?? null,
            lastIngestAt: staleInfo?.lastIngestAt ?? null,
            staleFiles: staleInfo?.staleFiles ?? 0,
            sampleChangedFiles: staleInfo?.sampleChangedFiles ?? [],
            replayedFiles: staleInfo?.replayedFiles ?? [],
            parseTimeouts: staleInfo?.parseTimeouts ?? [],
            graphHealth: { ...graphHealthJson(graph), status: graphHealthWord(graph) },
            verify: verified
              ? { at: verified.at, graph: verified.graph, files: verified.files, diverged: verified.diverged,
                  stale: verified.stale, unverified: verified.unverified, lastIngestAt: verified.lastIngestAt,
                  outdated: verifiedOutdated, fix: verified.fix }
              : null,
          };
          printJson(result);
        } else {
          renderSection("Status");
          renderKeyValue("Ix Memory", health.status);
          renderKeyValue("Endpoint", getEndpoint());
          renderKeyValue("Graph", graphHealthWord(graph));
          if (staleInfo) {
            renderKeyValue("Revision", String(staleInfo.currentRev));
            if (staleInfo.lastIngestAt) {
              const ago = timeSince(staleInfo.lastIngestAt);
              renderKeyValue("Last ingest", ago);
            }
            if (!staleInfo.graphCompleted) {
              renderWarning("No completed source graph ingest is recorded for this workspace.");
              renderNote("Run ix map to build a trustworthy graph.");
            } else if ((staleInfo.replayedFiles?.length ?? 0) > 0) {
              // Ahead of the stale-file check: a restored file can look current
              // by mtime while the graph still holds the content in between.
              renderWarning(describeReplayedChanges(staleInfo.replayedFiles!));
            } else if (staleInfo.staleFiles > 0) {
              renderWarning(`${staleInfo.staleFiles} file(s) changed since last ingest:`);
              for (const f of staleInfo.sampleChangedFiles) {
                console.log(`    ${f}`);
              }
              if (staleInfo.staleFiles > staleInfo.sampleChangedFiles.length) {
                renderNote(`... and ${staleInfo.staleFiles - staleInfo.sampleChangedFiles.length} more`);
              }
              renderNote("Run ix map to update.");
            } else if (staleInfo.parseTimeouts.length === 0) {
              // Only what was checked: no file's mtime moved. The graph's own
              // state is the "Graph" line above and the warning below.
              renderSuccess("No files changed since the last ingest.");
            }
            if (staleInfo.graphCompleted && staleInfo.parseTimeouts.length > 0) {
              // Beside the other states, not instead of them: another map
              // will not bring these files in, a larger budget will.
              renderWarning(describeStatusParseTimeouts(staleInfo.parseTimeouts));
            }
            if (staleInfo.graphCompleted && staleInfo.mapStale) {
              // Deferred after an edit, not missing: the last map's regions
              // stand until something reads them.
              renderKeyValue("Map", "stale");
              if (staleInfo.mapRefreshError) {
                renderWarning(`The last background map refresh failed: ${staleInfo.mapRefreshError}`);
                renderNote("run ix map --remap to recompute the map");
              } else {
                renderNote("a region view refreshes it in the background, or run ix map --remap");
              }
            } else if (staleInfo.graphCompleted && !staleInfo.mapCompleted) {
              renderWarning("No completed architecture map is recorded for this source revision.");
              renderNote("Source graph reads remain available, but hierarchy views may be incomplete.");
            }
          }
          if (isUnhealthy(graph)) renderWarning(graphHealthProse(graph));
          if (verified) {
            // A verify from before the last ingest describes a graph that has
            // since been written to (perhaps by the very fix it suggested):
            // show it, labelled, and ask for a new verify instead of a fix.
            const before = verifiedOutdated ? " (before last ingest)" : "";
            // An unverified record judged no file, so "0 diverged" would read
            // as a pass: name the verdict instead.
            const outcome = verified.graph === "unverified"
              ? `unverified (${verified.files === 0 ? "no files sampled" : "no file verified"})`
              : verified.graph === "stale"
                ? `0 diverged, ${verified.stale} stale (not verified clean)`
                : `${verified.diverged} diverged`;
            renderKeyValue("Verified", `${timeSince(verified.at)}, ${verified.files} files, ${outcome}${before}`);
            if (verified.diverged > 0 && verifiedOutdated) {
              renderNote(`The last ix verify found ${verified.diverged} file(s) whose nodes did not match their source, ` +
                "but the workspace has been ingested since. Run ix verify to check the graph as it is now.");
            } else if (verified.diverged > 0) {
              renderWarning(`The last ix verify found ${verified.diverged} file(s) whose nodes do not match their source. ` +
                `Fix: ${verified.fix ?? GRAPH_REBUILD_FIX}`);
            }
          }
        }
      } catch (err) {
        // Only a transport failure is "not reachable". Anything else — a 500
        // from a backend that is up, a malformed response — went out under
        // this message too, which sent people to restart a container that was
        // running fine. Those now reach the shared boundary, which names them.
        if (!isBackendUnreachable(err)) throw err;
        // The spec's uniform error record, so a consumer that pipes `--format
        // llm` parses the failure the same way it parses a result rather than
        // hitting an unparseable human sentence. Exit code is unchanged.
        const unreachable = backendUnreachableError(getEndpoint());
        if (opts.format === "llm") {
          console.log(llmError(unreachable.error, unreachable.message, [["hint", unreachable.next ?? null]]));
        } else {
          console.error(unreachable.message);
          if (unreachable.next) console.error(unreachable.next);
        }
        process.exit(1);
      }
    });
}

function timeSince(isoString: string): string {
  const diff = Date.now() - new Date(isoString).getTime();
  const seconds = Math.floor(diff / 1000);
  if (seconds < 60) return `${seconds}s ago`;
  const minutes = Math.floor(seconds / 60);
  if (minutes < 60) return `${minutes}m ago`;
  const hours = Math.floor(minutes / 60);
  if (hours < 24) return `${hours}h ago`;
  const days = Math.floor(hours / 24);
  return `${days}d ago`;
}