Skip to content

armgit / Ix

Public Imported from GitHub
0

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

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

import type { Command } from "commander";
import chalk from "chalk";
import { renderSection, renderSuccess, renderError } from "../ui.js";
import { createClient } from "../../client/factory.js";
import { IxClient } from "../../client/api.js";
import {
  canonicalWorkspacePath,
  ConfigParseError,
  DEFAULT_ENDPOINT,
  findWorkspaceForCwd,
  getDefaultWorkspace,
  getEndpoint,
  gitRootFor,
  loadConfig,
  loadWorkspaces,
  selectWorkspaceForCwd,
  type WorkspaceConfig,
} from "../config.js";
import { ixHome } from "../ix-home.js";
import { isLocalEndpoint } from "../backend-version.js";
import { resolveReadSystemId } from "../resolve.js";
import { assessGraphStats } from "../graph-health.js";
import { llmLine, printLlmLines } from "../llm.js";
import { existsSync, readFileSync } from "node:fs";
import { execFileSync } from "node:child_process";
import { parse as parseYaml } from "yaml";
import { join as pathJoin, resolve as resolvePath, win32 as winPath } from "node:path";
import { homedir } from "node:os";
import {
  BACKEND_IMAGE,
  checkBackendImage,
  checkBackendSchema,
  isNonStandardBackend,
  dockerAvailable,
  diagnoseBackendStack,
} from "../backend-status.js";
import { backendCeiling, isNewer, readBackendHealth } from "./upgrade.js";
import { loadIngestBaseline } from "../ingest-baseline.js";
import { isCloudReady } from "../remote.js";
import { hasCompletedMapBaseline } from "../stale.js";
import { readMapRefreshOutcome, readMapStale } from "../map-freshness.js";
import { loadMapBaseline } from "../map-baseline.js";
import { printJson } from "../format.js";
import { runVerify, type VerifyReport } from "../verify.js";
import { healthFromError } from "../database-probe.js";
import type { CapabilitiesResponse, HealthResponse } from "../../client/types.js";

interface CheckResult {
  ok: boolean;
  detail: string;
  // A warning is surfaced (yellow) but does not fail the overall run — e.g. an
  // intentional local dev backend, or an inconclusive image comparison.
  warn?: boolean;
}

/**
 * `ix doctor --format llm`.
 *
 * `text` renders a ✓/!/✗ glyph per check and then, on failure, the singularly
 * unhelpful "Run with --format json for details" — the details were already in
 * hand, they were just not printed. Every check's status and detail is emitted
 * here, so an agent never has to make a second call to find out what broke.
 *
 * Status is a word rather than a symbol because `ok`/`warn`/`fail` survives
 * being read back by something that is not a terminal.
 */
export function renderDoctorLlm(
  results: Array<{ name: string } & CheckResult>,
  hasFailure: boolean,
  hasWarning: boolean,
): string[] {
  const lines = [llmLine("doctor", [
    ["healthy", hasFailure ? "false" : "true"],
    ["warnings", hasWarning ? "true" : "false"],
    ["checks", String(results.length)],
  ])];
  for (const r of results) {
    lines.push(llmLine("check", [
      ["name", r.name],
      // Same precedence as the glyphs and as `hasFailure` below: a warning is
      // `{ ok: false, warn: true }`, so `warn` has to be checked on the
      // not-ok branch. Testing it on the ok branch reports every warning as a
      // hard failure, which is the opposite of what `hasFailure` concludes.
      ["status", r.ok ? "ok" : r.warn ? "warn" : "fail"],
      ["detail", r.detail],
    ]));
  }
  return lines;
}

interface Check {
  name: string;
  run: () => Promise<CheckResult>;
}

/**
 * Does `%IX_HOME%\bin\ix.cmd` still point at a CLI that exists?
 *
 * `ix upgrade` before 0.9.0 refreshed only the bash shim and left this launcher
 * aimed at a `cli\ix.cmd` the upgrade had just replaced with a version-nested
 * directory (Ix#385).
 *
 * The obvious objection is that a user whose launcher is broken cannot run
 * `ix doctor` to be told so. True from PowerShell — which is why the launcher
 * now diagnoses itself. This check covers the case that shim cannot: the *bash*
 * shim under Git Bash / MSYS is refreshed by every version, so `ix` keeps
 * working there while the native launcher is quietly dead. Someone who lives in
 * Git Bash can be broken in PowerShell for weeks without knowing.
 */
export function checkWindowsLauncher(
  ixHome: string,
  readShim: (path: string) => string | null,
  exists: (path: string) => boolean,
): CheckResult {
  const shimPath = pathJoin(ixHome, "bin", "ix.cmd");
  const body = readShim(shimPath);
  if (body === null) {
    return { ok: true, detail: "no ix.cmd launcher (not installed by install.ps1)" };
  }

  // The launcher invokes its target as the first quoted %~dp0-relative path.
  const target = body.match(/"(%~dp0[^"]+)"/)?.[1];
  if (!target) {
    return { ok: true, warn: true, detail: `${shimPath}: unrecognized launcher, left alone` };
  }

  // %~dp0 is the directory of ix.cmd itself — IX_HOME\bin — and the target is
  // written with backslashes. Resolve with win32 semantics explicitly rather
  // than the ambient `path`, so the separator handling does not depend on which
  // OS happens to be evaluating it. (Production only reaches here on Windows,
  // but a resolver that silently misreads its input off-Windows is untestable.)
  const resolved = winPath.join(ixHome, "bin", target.replace(/^%~dp0/, ""));
  if (exists(resolved)) return { ok: true, detail: `ix.cmd → ${target}` };

  return {
    ok: false,
    detail:
      `${shimPath} points at ${target}, which does not exist — ` +
      "an upgrade from before 0.9.0 moved the CLI. Reinstall to repair: " +
      "irm https://ix-infra.com/install.ps1 | iex",
  };
}

/** A registered workspace sitting inside another one. */
export interface NestedWorkspace {
  nested: WorkspaceConfig;
  parent: WorkspaceConfig;
}

/**
 * Registered workspaces nested inside another registered workspace whose own
 * root is not a git root.
 *
 * Before `ix ingest <path>` looked for the workspace a path belongs to, it
 * registered the path itself (or a file's directory) as a new workspace: `ix
 * ingest src/a.ts` in a mapped repo left a `repo/src` workspace holding one
 * file, and every read under `src/` resolved to it from then on. A nested
 * workspace that is its own git root is the legitimate shape -- a member repo
 * of a multi-repo system mapped on its own -- and is not reported.
 *
 * `isGitRoot` is injected so the rule can be tested without spawning git.
 */
export function findStrayNestedWorkspaces(
  workspaces: WorkspaceConfig[],
  isGitRoot: (root: string) => boolean,
): NestedWorkspace[] {
  const found: NestedWorkspace[] = [];
  for (const ws of workspaces) {
    const root = canonicalWorkspacePath(ws.root_path);
    const others = workspaces.filter(o => o !== ws && canonicalWorkspacePath(o.root_path) !== root);
    const parent = selectWorkspaceForCwd(others, root);
    if (parent && !isGitRoot(root)) found.push({ nested: ws, parent });
  }
  return found;
}

/** Whether `dir` is the top level of a git working tree. */
export function isGitTopLevel(dir: string): boolean {
  const top = gitRootFor(dir);
  return top !== undefined && canonicalWorkspacePath(top) === canonicalWorkspacePath(dir);
}

/**
 * The doctor check over {@link findStrayNestedWorkspaces}. Read-only: it names
 * the repair and leaves the deleting to the user. There is no command that
 * unregisters a workspace, so the repair is the scoped graph reset (run from
 * inside the stray workspace, which `ix reset --workspace` resolves to because
 * the nearest registration wins) and then removing its entry by hand.
 */
export function checkNestedWorkspaces(
  workspaces: WorkspaceConfig[],
  isGitRoot: (root: string) => boolean,
  configPath: string,
): CheckResult {
  const stray = findStrayNestedWorkspaces(workspaces, isGitRoot);
  if (stray.length === 0) return { ok: true, detail: "no stray workspace registered inside another" };
  const lines = stray.map(({ nested, parent }) =>
    `'${nested.workspace_name}' (${nested.root_path}) is inside '${parent.workspace_name}' (${parent.root_path}) ` +
    `and is not a git root, so reads under it resolve to it instead of '${parent.workspace_name}'. ` +
    `Fix: cd "${nested.root_path}" && ix reset --workspace --yes, ` +
    `then delete its entry (root_path: ${nested.root_path}) from ${configPath}`,
  );
  return {
    ok: false,
    warn: true,
    detail:
      `${stray.length} workspace(s) registered inside another, most likely left by \`ix ingest <path>\` ` +
      `on a path below a mapped workspace, which older versions registered as a workspace of its own:\n  ` +
      lines.join("\n  "),
  };
}

/** A remote backend that asks for the local token: this CLI never sends one off the machine. */
const REMOTE_TOKEN_HINT =
  "this CLI sends its token (IX_TOKEN or the stored one) only to a backend on this machine; " +
  "reach that backend through a local port forward and point IX_ENDPOINT at it";

/**
 * Does the backend require the local bearer token, and does this CLI have the
 * one it accepts? `caps` is the `/v1/capabilities` answer, or the error asking
 * for it threw. A refused token fails the run, because every command fails the
 * same way; a token the backend ignores is only a warning.
 */
export function assessLocalAuth(
  caps: CapabilitiesResponse | Error,
  sendsToken: boolean,
  local: boolean,
): CheckResult {
  if (caps instanceof Error && caps.name === "LocalTokenRequiredError") {
    return {
      ok: false,
      detail: sendsToken
        ? "the backend refused this CLI's token — " +
          (local ? "run 'ix docker start --local-token' to give the backend the stored one" : REMOTE_TOKEN_HINT)
        : "the backend requires a token and this CLI has none — " +
          (local ? "run 'ix docker start --local-token', or set IX_TOKEN" : REMOTE_TOKEN_HINT),
    };
  }
  if (caps instanceof Error) return { ok: true, detail: "backend unreachable (skipped)" };
  if (caps.local_auth === undefined) return { ok: true, detail: "backend predates the token guard (skipped)" };
  if (caps.local_auth_enforcing) return { ok: true, detail: "required, and this CLI's token is accepted" };
  if (sendsToken) {
    return {
      ok: false, warn: true,
      detail: "this CLI has a token but the backend does not require it — " +
        (local ? "run 'ix docker start --local-token' to apply it" : "the backend ignores it"),
    };
  }
  return {
    ok: true,
    detail: local ? "not required (opt in with 'ix docker start --local-token')" : "not required",
  };
}

// Shared with the ingest's database probe; re-exported for existing importers.
export { healthFromError };

/**
 * "Database reachable" from the health answer. A backend that reports
 * `database` says so itself; an older one never touched the database for
 * health, so `probe` asks a route that does (`/v1/revisions/current`).
 */
export async function assessDatabase(
  health: HealthResponse | Error,
  probe: () => Promise<unknown>,
): Promise<CheckResult> {
  if (health instanceof Error) return { ok: true, detail: "backend unreachable (skipped)" };
  if (health.database === "reachable") return { ok: true, detail: "reachable (backend health)" };
  if (health.database === "unreachable") {
    return { ok: false, detail: "the memory layer cannot reach ArangoDB — check 'ix docker status' and 'ix docker logs'" };
  }
  try {
    await probe();
    return { ok: true, detail: "reachable (read the current revision)" };
  } catch (e) {
    // The read was refused for want of the token, so it says nothing about the
    // database; "Backend token" reports the refusal.
    if ((e as Error)?.name === "LocalTokenRequiredError") {
      return { ok: true, detail: "not checked: the backend refused this CLI's token (see Backend token)" };
    }
    const msg = (e as Error)?.message ?? String(e);
    return { ok: false, detail: `the backend could not read its database: ${msg.slice(0, 200)}` };
  }
}

/** What every other command does with a config.yaml that does not parse (#807). */
const CONFIG_REFUSAL = "other ix commands refuse to run until it is fixed";

/**
 * "Config file parses". A config.yaml that does not parse stops every other
 * command (`loadConfig` throws ConfigParseError), so this is a failure, and the
 * one doctor is still able to report: it catches that error itself.
 */
export function assessConfigFile(configPath: string, read: (p: string) => string | null): CheckResult {
  const raw = read(configPath);
  if (raw === null) return { ok: true, detail: "no config file (defaults)" };
  try {
    const parsed = parseYaml(raw);
    if (parsed !== null && parsed !== undefined && (typeof parsed !== "object" || Array.isArray(parsed))) {
      return { ok: false, detail: `${configPath} is not a mapping of settings, so ${CONFIG_REFUSAL}` };
    }
    return { ok: true, detail: configPath };
  } catch (e) {
    const first = ((e as Error)?.message ?? String(e)).split("\n")[0];
    return { ok: false, detail: `${configPath} does not parse, so ${CONFIG_REFUSAL}: ${first}` };
  }
}

/** The answer of a check that needs config.yaml when config.yaml does not parse. */
const CONFIG_NOT_CHECKED: CheckResult = { ok: true, detail: "not checked: config.yaml does not parse" };

function isConfigParseError(e: unknown): e is ConfigParseError {
  return (e as Error | undefined)?.name === "ConfigParseError";
}

/**
 * The endpoint and client doctor checks with. A config.yaml that does not parse
 * is the one failure doctor must survive, since reporting it is its job: the
 * endpoint falls back to IX_ENDPOINT or the default, and the client is built
 * without the stored token, which lives in the file that does not parse.
 */
function doctorClient(): { endpoint: string; client: IxClient } {
  let endpoint: string;
  try {
    endpoint = getEndpoint();
  } catch (e) {
    if (!isConfigParseError(e)) throw e;
    endpoint = process.env.IX_ENDPOINT || DEFAULT_ENDPOINT;
  }
  try {
    return { endpoint, client: createClient({ endpoint }) };
  } catch (e) {
    if (!isConfigParseError(e)) throw e;
    // createClient read the stored token from the file that does not parse.
    // Loopback only, as getLocalToken would have decided.
    const token = isLocalEndpoint(endpoint) ? process.env.IX_TOKEN?.trim() : undefined;
    // eslint-disable-next-line no-restricted-syntax -- the factory cannot build a client without config.yaml
    return { endpoint, client: new IxClient(endpoint, undefined, token ? { token } : {}) };
  }
}

/** A workspace lookup, or none when config.yaml (where workspaces live) does not parse. */
function workspaceOrNone(lookup: () => WorkspaceConfig | undefined): WorkspaceConfig | undefined {
  try {
    return lookup();
  } catch (e) {
    if (isConfigParseError(e)) return undefined;
    throw e;
  }
}

/**
 * The "Completed map for this workspace" check, for one resolved root.
 * Exported for tests.
 */
export async function assessMapCompletion(
  root: string,
  cloudReady: () => Promise<boolean> = isCloudReady,
): Promise<CheckResult> {
  const source = loadIngestBaseline(root);
  if (!source) {
    // No local baseline means one of: never mapped, an initial map
    // that committed patches but never finished, or a workspace fed
    // by the cloud runner — which writes none by design. Only the
    // last is healthy, and only a registered runner makes it
    // possible, so that is the one case this warns instead of fails.
    const cloud = await cloudReady();
    return cloud
      ? { ok: false, warn: true, detail: "no local baseline — expected for a cloud-ingested workspace" }
      : { ok: false, detail: "no completed map baseline — the graph may be partial. Run `ix map`." };
  }
  if (!hasCompletedMapBaseline(root)) {
    // CL-13: an `ix map` after an edit defers the map, so the
    // marker trails the source revision until a region view
    // refreshes it. That is the design working, not a partial map,
    // and failing here would make `ix doctor` exit 1 after every edit.
    const stale = readMapStale(root);
    if (stale !== null) {
      // Deferred maps are only ever served from a map that completed once;
      // without one there is nothing to be merely stale against.
      if (loadMapBaseline(root) === null && loadMapBaseline(canonicalWorkspacePath(root)) === null) {
        return {
          ok: false,
          detail: "no architecture map has ever completed for this workspace — run `ix map --remap`",
        };
      }
      // A background refresh that failed is reported, not failed on: a
      // map that takes longer than the refresh's limit, or a backend that was
      // briefly down, must not keep `ix doctor` exiting 1 after every edit.
      // The regions are the last completed map's, and `--remap` brings them
      // up to date.
      const last = readMapRefreshOutcome(root);
      if (last?.ok === false) {
        return {
          ok: false,
          warn: true,
          detail: `architecture map is stale; its last background refresh failed (${last.reason ?? "no reason recorded"}) — run \`ix map --remap\``,
        };
      }
      return {
        ok: false,
        warn: true,
        detail: "architecture map is stale (deferred after an edit); a region view refreshes it in the background, or run `ix map --remap`",
      };
    }
    return {
      ok: false,
      detail: `source graph at revision ${source.currentRev} has no completed architecture map — run \`ix map\``,
    };
  }
  return { ok: true, detail: `recorded at revision ${source.currentRev}` };
}

/** "ripgrep on PATH": `ix text` needs it; everything else works without it. */
export function checkRipgrep(run: () => string = () => execFileSync("rg", ["--version"], { encoding: "utf-8", timeout: 5000 })): CheckResult {
  try {
    const first = run().split("\n")[0]?.trim();
    return { ok: true, detail: first || "rg found" };
  } catch {
    return { ok: false, warn: true, detail: "rg not found on PATH — 'ix text' needs ripgrep" };
  }
}

/**
 * "Graph matches a re-parse": the last line of defence for a graph whose
 * counts look fine and whose nodes do not (see `verify.ts`).
 *
 * Never a failure. A diverged sample is a warning with the fix, and anything
 * that stops the comparison -- no workspace, an old backend that 404s, a
 * parser that will not load, any throw at all -- is "not checked", so this
 * check cannot give `ix doctor` an exit code it did not have.
 */
/** `ix doctor`'s verify: a few files, and never more than about this long. */
export const DOCTOR_VERIFY_SAMPLE = 5;
export const DOCTOR_VERIFY_BUDGET_MS = 5_000;
/** Past the budget, how long an in-flight read may still take before doctor gives up. */
const DOCTOR_VERIFY_GRACE_MS = 2_000;

export async function assessGraphVerify(run: () => Promise<VerifyReport>, budgetMs?: number): Promise<CheckResult> {
  let timer: ReturnType<typeof setTimeout> | undefined;
  try {
    // The budget stops new work; this stops a read that never returns.
    const report = budgetMs === undefined ? await run() : await Promise.race([
      run(),
      new Promise<never>((_, reject) => {
        timer = setTimeout(() => reject(new Error(`timed out after ${Math.round(budgetMs / 1000)} s`)), budgetMs + DOCTOR_VERIFY_GRACE_MS);
        timer.unref?.();
      }),
    ]);
    const { files, clean, diverged, stale } = report.counts;
    // "partial: 3 of 5" — a run that ran out of budget says how much it saw.
    const partial = report.partial ? ` (partial: ${files} of ${report.sample} files checked within ${Math.round((budgetMs ?? 0) / 1000)} s)` : "";
    if (report.graph === "diverged") {
      const paths = report.files.filter((f) => f.state === "diverged").map((f) => f.path);
      const shown = paths.slice(0, 3).join(", ") + (paths.length > 3 ? `, and ${paths.length - 3} more` : "");
      return {
        ok: false,
        warn: true,
        detail: `${diverged} of ${files} sampled files diverged (${shown})${partial}. Fix: ${report.fix}`,
      };
    }
    if (report.graph === "unverified") {
      return { ok: true, detail: `not checked: ${(report.reason ?? "nothing to compare").replace(/_/g, " ")}${partial}` };
    }
    // Stale is not a pass, but it is what any edit since the last map looks
    // like, so it stays a note (as `ix status` treats changed files).
    if (report.graph === "stale") {
      return { ok: true, detail: `not verified: ${stale} of ${files} sampled files changed since the last ingest${partial} — run \`ix map\`` };
    }
    // Only files judged clean "match"; unverified ones are not counted as such.
    const of = clean === files ? `${files}` : `${clean} of ${files}`;
    return { ok: true, detail: `${of} sampled files match a re-parse (nodes only)${partial}` };
  } catch (e: any) {
    return { ok: true, detail: `not checked: ${e?.message ?? String(e)}` };
  } finally {
    if (timer) clearTimeout(timer);
  }
}

export function registerDoctorCommand(program: Command): void {
  program
    .command("doctor")
    .description("Check Ix system health — server, database, graph integrity")
    .option("--format <fmt>", "Output format (text|json|llm)", "text")
    .action(async (opts: { format: string }) => {
      const { endpoint, client } = doctorClient();
      // Asked of the file directly: with IX_ENDPOINT and IX_TOKEN set,
      // building the client never reads it.
      let configBroken = false;
      try { loadConfig(); } catch (e) {
        if (!isConfigParseError(e)) throw e;
        configBroken = true;
      }

      // "Graph has nodes" and "Graph has edges" are two questions about one
      // response. They were two `client.stats()` calls, run back to back by the
      // sequential loop below — and `/v1/stats` is 3-4 s on a large graph, so
      // the second one was most of what `ix doctor` spent. Memoized rather than
      // hoisted so a run that never reaches those checks still never asks, and
      // so a failure is still reported per check rather than aborting both.
      // Counting only the active scope makes the number correct and, on its own,
      // less self-evident: "0 nodes" against a backend holding thousands reads
      // as a broken install until it says whose nodes it counted. The scope
      // travels with the count so the check explains itself.
      // Resolved here rather than through `resolveWorkspaceId()`, which answers a
      // directory that matches no workspace by substituting whichever one carries
      // `default: true`. That collapses two states doctor has to tell apart — cwd
      // matched THIS workspace, and cwd matched nothing so here is an unrelated
      // one — into a single id. Reporting the second as "this workspace" is how a
      // never-ingested directory passed every check while quoting another repo's
      // graph (#518). Local, so it still answers when the backend is unreachable.
      const cwd = process.cwd();
      const matchedWorkspace = workspaceOrNone(() => findWorkspaceForCwd(cwd));
      const substitutedWorkspace = matchedWorkspace ? undefined : workspaceOrNone(getDefaultWorkspace);

      let statsOnce: Promise<{ stats: any; scope: string; systemId?: string }> | undefined;
      const sharedStats = (): Promise<{ stats: any; scope: string; systemId?: string }> => (statsOnce ??= (async () => {
        // Without the workspaces there is no scope to count in, and an
        // unscoped count would be reported as if it were this directory's.
        if (configBroken) throw new ConfigParseError(pathJoin(ixHome(), "config.yaml"), "see Config file parses");
        // Scoped the same way `ix stats` scopes, because doctor disagreeing with
        // stats about the size of the graph is the whole of #510. Not a
        // tombstone fix: /v1/stats filters `deleted_rev == null` in every one of
        // its queries, scoped or not, so deleted nodes were never in either
        // count. What the unscoped call added was every *live* node belonging to
        // some other workspace on the same backend, which is how a freshly
        // reset workspace still looked like a 17k-node graph.
        const systemId = await resolveReadSystemId(client, { allowUnmapped: true });
        const workspace = systemId ? undefined : (matchedWorkspace ?? substitutedWorkspace);
        const stats = await client.stats({ workspaceId: workspace?.workspace_id, systemId });
        // Named, not deictic. "this workspace" is only true when cwd actually
        // matched one, and the case where it has not is exactly the case where
        // the reader most needs to know whose count they are being shown.
        // No workspace at all means the request really was unscoped — say that
        // rather than name a scope.
        const scope = systemId
          ? "this system"
          : workspace
            ? `workspace '${workspace.workspace_name}'`
            : "all workspaces";
        return { stats, scope, systemId };
      })());

      // One /v1/health for "Server reachable" and "Database reachable". A 503
      // with a health body is the backend reporting a dead database, so it is
      // an answer, not a failure to reach the server.
      let healthOnce: Promise<HealthResponse> | undefined;
      const health = (): Promise<HealthResponse> => (healthOnce ??= readBackendHealth(client).catch((e: unknown) => {
        const degraded = healthFromError(e);
        if (degraded) return degraded;
        throw e;
      }));

      const checks: Check[] = [
        {
          name: "Server reachable",
          run: async () => {
            try {
              // Records what the backend says it is running; see
              // backend-version.ts. Free — this response is already needed.
              const h = await health();
              // A degraded answer is still a server that answered; the
              // database check below names what is wrong with it.
              return { ok: h.status === "ok" || h.status === "degraded", detail: `${endpoint} → ${h.status}` };
            } catch (e: any) {
              // An unreachable backend is where a fatal Arango boot loop hides:
              // the container restarts forever, memory-layer never leaves
              // `Created` behind `service_healthy`, and from out here that is
              // indistinguishable from "not started yet". Say what the stack
              // actually reported. Ix#614.
              const base = e.message ?? "unreachable";
              const failure = isLocalEndpoint(endpoint) && dockerAvailable() ? diagnoseBackendStack() : null;
              if (!failure) return { ok: false, detail: base };
              const parts = [`${base} — ${failure.service} is ${failure.state}`];
              if (failure.lastError) parts.push(`  last log: ${failure.lastError}`);
              if (failure.remedy) parts.push(`  fix: ${failure.remedy}`);
              return { ok: false, detail: parts.join("\n") };
            }
          },
        },
        {
          name: "Database reachable",
          run: async () => {
            let h: HealthResponse | Error;
            try {
              h = await health();
            } catch (e) {
              h = e instanceof Error ? e : new Error(String(e));
            }
            return assessDatabase(h, () => client.currentRevision());
          },
        },
        {
          name: "Backend token",
          run: async () => {
            let caps: CapabilitiesResponse | Error;
            try {
              caps = await client.fetchCapabilities();
            } catch (e) {
              caps = e instanceof Error ? e : new Error(String(e));
            }
            return assessLocalAuth(caps, client.sendsToken === true, isLocalEndpoint(endpoint));
          },
        },
        {
          name: "Workspace for this directory",
          run: async () => {
            // A system scope supersedes the per-directory workspace, so ask what
            // the read path resolved to before judging cwd. Best-effort: if the
            // backend is unreachable the local answer below is still the right
            // one, and "Server reachable" already reports the outage.
            let systemScoped = false;
            try {
              systemScoped = Boolean((await sharedStats()).systemId);
            } catch { /* fall through to the local answer */ }

            if (systemScoped) return { ok: true, detail: "scoped to the active system" };
            if (configBroken) return CONFIG_NOT_CHECKED;
            if (matchedWorkspace) return { ok: true, detail: `workspace '${matchedWorkspace.workspace_name}'` };
            if (substitutedWorkspace) {
              return {
                ok: false,
                detail:
                  `no workspace registered for ${cwd} — graph reads here fail with workspace_not_mapped ` +
                  `(they no longer fall back to the default workspace '${substitutedWorkspace.workspace_name}'). ` +
                  "Run `ix map` in this directory.",
              };
            }
            // Nothing registered anywhere: honest and self-explanatory, and the
            // graph checks below already fail on the empty count. Warn rather
            // than fail so a fresh install reports one problem, not three.
            // `{ ok: false, warn: true }` is the shape a warning takes — `warn`
            // is read on the not-ok branch, so `ok: true` here would render as a
            // clean pass and say nothing.
            return { ok: false, warn: true, detail: "none registered yet — run `ix map`" };
          },
        },
        {
          name: "No stray nested workspaces",
          run: async () =>
            checkNestedWorkspaces(loadWorkspaces(), isGitTopLevel, pathJoin(ixHome(), "config.yaml")),
        },
        {
          // Ix#525: a partially committed graph still has nodes and edges, so
          // every check below it passes and doctor calls a half-built graph
          // healthy. The completion markers are the only thing that knows.
          //
          // Reads the two marker files rather than calling `detectStaleFiles`:
          // that walks the workspace and stats every file to answer a question
          // about *changed* files, and this check needs neither the walk nor
          // the answer. On a large workspace it is the whole tree per `ix
          // doctor`.
          name: "Completed map for this workspace",
          run: async () => {
            if (configBroken) return CONFIG_NOT_CHECKED;
            if (!matchedWorkspace) {
              return { ok: false, warn: true, detail: "no local workspace to check" };
            }
            try {
              // Resolve once: both marker files are keyed by the exact root
              // string, and `hasCompletedMapBaseline` resolves internally.
              return await assessMapCompletion(resolvePath(matchedWorkspace.root_path));
            } catch (e: any) {
              return { ok: false, detail: e.message ?? "map completion check failed" };
            }
          },
        },
        {
          name: "Graph has nodes",
          run: async () => {
            try {
              const { stats, scope } = await sharedStats();
              const total = stats.nodes?.total ?? 0;
              return { ok: total > 0, detail: `${total} nodes in ${scope}` };
            } catch (e: any) {
              if (isConfigParseError(e)) return CONFIG_NOT_CHECKED;
              return { ok: false, detail: e.message ?? "stats failed" };
            }
          },
        },
        {
          name: "Graph has edges",
          run: async () => {
            try {
              const { stats, scope } = await sharedStats();
              const total = stats.edges?.total ?? 0;
              return { ok: total > 0, detail: `${total} edges in ${scope}` };
            } catch (e: any) {
              if (isConfigParseError(e)) return CONFIG_NOT_CHECKED;
              return { ok: false, detail: e.message ?? "stats failed" };
            }
          },
        },
        {
          // A graph can keep every node and lose nearly every edge (another
          // checkout's ingest, Ix-memory#211): both counts above stay non-zero
          // and every answer is quietly wrong. Same judgement as the query
          // paths use (graph-health.ts), from the stats already fetched.
          name: "Graph structure intact",
          run: async () => {
            try {
              const { stats, scope } = await sharedStats();
              const health = assessGraphStats(stats);
              if (health.status === "degraded") {
                return { ok: false, detail: `${scope}: ${health.message} Fix: ${health.fix}` };
              }
              if (health.status === "ok") {
                return {
                  ok: true,
                  detail: `${health.structuralEdges} structural edges for ${health.symbols} symbols in ${scope}`,
                };
              }
              // Empty (which "Graph has nodes" already fails) or a stats body
              // without the per-predicate breakdown: nothing to judge by, and
              // not a second failure for one problem.
              return { ok: true, detail: `not judged: no ${health.status === "empty" ? "nodes" : "edge breakdown"} in ${scope}` };
            } catch (e: any) {
              if (isConfigParseError(e)) return CONFIG_NOT_CHECKED;
              return { ok: false, detail: e.message ?? "stats failed" };
            }
          },
        },
        {
          // Counts can all be healthy while a file's nodes are not what its
          // source says (F-01). A small sampled re-parse; see verify.ts.
          name: "Graph matches a re-parse",
          run: async () => {
            if (configBroken) return CONFIG_NOT_CHECKED;
            if (!matchedWorkspace) return { ok: true, detail: "not checked: no local workspace" };
            // Parsing costs nothing to report when nobody can answer the
            // reads, so ask the (already memoized) health first.
            try {
              const h = await health();
              if (h.status !== "ok") return { ok: true, detail: `not checked: backend ${h.status}` };
            } catch {
              return { ok: true, detail: "not checked: backend not reachable" };
            }
            return assessGraphVerify(
              () => runVerify(client, resolvePath(matchedWorkspace.root_path), {
                sample: DOCTOR_VERIFY_SAMPLE, record: false, budgetMs: DOCTOR_VERIFY_BUDGET_MS,
              }),
              DOCTOR_VERIFY_BUDGET_MS,
            );
          },
        },
        {
          name: "No unresolved conflicts",
          run: async () => {
            try {
              const c = await client.conflicts();
              const count = Array.isArray(c) ? c.length : 0;
              return { ok: count === 0, detail: count === 0 ? "clean" : `${count} conflict(s)` };
            } catch (e: any) {
              if (isConfigParseError(e)) return CONFIG_NOT_CHECKED;
              return { ok: false, detail: e.message ?? "conflicts check failed" };
            }
          },
        },
        {
          // Ix#270: trust the running container, not the version stamp.
          name: "Backend is the released image",
          run: async () => {
            const status = checkBackendImage(endpoint);
            switch (status.kind) {
              case "ok": {
                if (isNonStandardBackend(status.container)) {
                  return {
                    ok: false, warn: true,
                    detail: `released image, but via a non-standard compose project (${status.container.composeProject ?? "unknown"})`,
                  };
                }
                return { ok: true, detail: "running the released image" };
              }
              case "local-build":
                return {
                  ok: false, warn: true,
                  detail: `running a local build (${status.container.imageRef}), not the released image — ` +
                    `'ix docker stop && ix docker start' pulls ${BACKEND_IMAGE}:latest`,
                };
              case "digest-mismatch":
                return {
                  ok: false, warn: true,
                  detail: "running an older image digest than :latest — " +
                    "'ix docker stop && ix docker start' pulls the released image",
                };
              case "latest-not-pulled":
                return { ok: true, warn: true, detail: `can't verify — ${BACKEND_IMAGE}:latest not pulled locally` };
              case "not-running":
                return { ok: true, detail: `no backend container for ${endpoint} (skipped)` };
              case "remote":
                return { ok: true, detail: "remote endpoint, no local container (skipped)" };
              case "docker-unavailable":
                return { ok: true, detail: "docker unavailable (skipped)" };
            }
          },
        },
        {
          // Ix#271: a graph written by an older engine fails scoped reads silently.
          name: "Graph schema matches engine",
          run: async () => {
            const s = await checkBackendSchema(client, backendCeiling(), isNewer);
            if (!s.reachable) return { ok: true, detail: "backend unreachable (skipped)" };
            if (s.serverVersion === null) return { ok: true, detail: "backend does not report a schema version" };
            if (s.matches) return { ok: true, detail: `schema v${s.serverVersion}` };
            return {
              ok: false, warn: true,
              detail: `graph schema v${s.serverVersion}, this CLI expects v${s.expected} — ` +
                "re-map to rebuild the graph: 'ix map .'",
            };
          },
        },
      ];

      checks.push(
        {
          name: "Config file parses",
          run: async () => assessConfigFile(
            pathJoin(ixHome(), "config.yaml"),
            (p) => { try { return readFileSync(p, "utf-8"); } catch { return null; } },
          ),
        },
        { name: "ripgrep on PATH", run: async () => checkRipgrep() },
      );

      // Windows-only: a launcher pointing at a CLI the upgrade moved (Ix#385).
      if (process.platform === "win32") {
        checks.push({
          name: "Windows launcher",
          run: async () =>
            checkWindowsLauncher(
              process.env.IX_HOME || pathJoin(homedir(), ".ix"),
              (p) => { try { return readFileSync(p, "utf-8"); } catch { return null; } },
              existsSync,
            ),
        });
      }

      const results: Array<{ name: string } & CheckResult> = [];
      for (const check of checks) {
        let result: CheckResult;
        try {
          result = await check.run();
        } catch (e) {
          // A check that reached for config.yaml and found it unparseable. Any
          // other throw is a bug in the check and still surfaces.
          if (!isConfigParseError(e)) throw e;
          result = CONFIG_NOT_CHECKED;
        }
        results.push({ name: check.name, ...result });
      }

      const hasFailure = results.some((r) => !r.ok && !r.warn);
      const hasWarning = results.some((r) => r.warn);
      if (hasFailure) process.exitCode = 1;

      if (opts.format === "llm") {
        printLlmLines(renderDoctorLlm(results, hasFailure, hasWarning));
        return;
      }

      if (opts.format === "json") {
        printJson({ healthy: !hasFailure, hasWarnings: hasWarning, checks: results });
        return;
      }

      renderSection("Ix Doctor");
      console.log();
      for (const r of results) {
        const icon = r.ok ? chalk.green("✓") : r.warn ? chalk.yellow("!") : chalk.red("✗");
        const detail = chalk.dim(` — ${r.detail}`);
        console.log(`  ${icon} ${r.name}${detail}`);
      }

      console.log();
      if (hasFailure) {
        renderError("Some checks failed.");
      } else if (hasWarning) {
        renderSuccess("All checks passed (with warnings).");
      } else {
        renderSuccess("All checks passed.");
      }
      console.log();
    });
}