Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

8.4 KB
Raw Blame
/**
 * Which mode Lens runs in, and how fresh the index is. Same discovery order as
 * the VS Code extension: lock file, pid alive, /health probe. Read-only
 * throughout: nothing here starts, stops or writes anything.
 */

import { getHealth } from "@repowise-dev/api-client/health";
import { listRepos } from "@repowise-dev/api-client/repos";
import { ApiClientError } from "@repowise-dev/api-client";
import { normalizeRepoPath } from "@repowise-dev/types/repos";
import { isLoopbackUrl, isServeLock, type ServeLock } from "@repowise-dev/types/serve-lock";
import type { Host } from "../host";
import type { IndexFreshness, LiteReason, Mode } from "../model/session";
import { connectApiClient, withTimeout } from "./transport";

export interface Discovery {
  mode: Mode;
  liteReason?: LiteReason;
  repoRoot: string | null;
  /** In full mode: the local server's id for this repo, and when it last indexed it. */
  repo?: { id: string; updatedAt: string | null };
}

const HEALTH_TIMEOUT_MS = 800;
const LIST_TIMEOUT_MS = 3_000;
/** A little over the engine's own 30 s MCP connection timeout. */
const CONNECT_TIMEOUT_MS = 35_000;
const GIT_TIMEOUT_MS = 5_000;
const MAX_WALK = 20;
const SHA = /^[0-9a-f]{7,64}$/i;

export function isWindowsPath(p: string): boolean {
  return /^[A-Za-z]:[\\/]/.test(p) || p.startsWith("\\\\");
}

function join(dir: string, rel: string): string {
  return `${dir.replace(/[\\/]+$/, "")}/${rel}`;
}

function parentDir(p: string): string | null {
  const trimmed = p.replace(/[\\/]+$/, "");
  const cut = Math.max(trimmed.lastIndexOf("/"), trimmed.lastIndexOf("\\"));
  if (cut < 0) return null;
  if (cut === 0) return trimmed === "" ? null : "/";
  return trimmed.slice(0, cut);
}

/**
 * The nearest directory at or above `cwd` holding an index. The marker is
 * `.repowise/state.json`, not the bare directory: `~/.repowise` is the user
 * config dir and has no state file, so it never reads as an indexed repo.
 */
export async function findIndexedRoot(host: Host, cwd: string): Promise<string | null> {
  let dir: string | null = cwd;
  for (let i = 0; dir !== null && i < MAX_WALK; i++) {
    if (await host.fs.exists(join(dir, ".repowise/state.json"))) return dir;
    dir = parentDir(dir);
  }
  return null;
}

async function readJson(host: Host, path: string): Promise<unknown> {
  try {
    return JSON.parse(await host.fs.read(path)) as unknown;
  } catch {
    return null;
  }
}

/** The parsed lock, or null when missing or malformed. A stale lock still parses: gate on the pid. */
export async function readServeLock(host: Host, repoRoot: string): Promise<ServeLock | null> {
  const parsed = await readJson(host, join(repoRoot, ".repowise/serve.lock.json"));
  return isServeLock(parsed) ? parsed : null;
}

/**
 * Whether a process with this pid exists: true, false, or null when the probe
 * could not run (no process API on this surface). A null does not block the
 * /health probe, which still has to answer.
 */
export async function isPidAlive(host: Host, pid: number, cwd: string): Promise<boolean | null> {
  try {
    if (isWindowsPath(cwd)) {
      const out = await host.process.run(["tasklist", "/FI", `PID eq ${pid}`, "/NH", "/FO", "CSV"], cwd);
      return out.exitCode === 0 && out.stdout.includes(`"${pid}"`);
    }
    const out = await host.process.run(["ps", "-p", String(pid), "-o", "pid="], cwd);
    return out.exitCode === 0 && out.stdout.trim() === String(pid);
  } catch {
    return null;
  }
}

type ServerProbe = { kind: "ok"; repoId: string; updatedAt: string | null } | { kind: "down" } | { kind: "auth" } | { kind: "unlisted" };

/**
 * Health-probes the server the lock names, then finds this repo in its list.
 * A server can list several repos (a workspace DB), so the match is on
 * `local_path`, never the first row. Loopback needs no key; a 401 means one
 * is configured, which Lens will not read.
 */
export async function probeServer(host: Host, lock: ServeLock, repoRoot: string): Promise<ServerProbe> {
  connectApiClient(host, lock.url);
  try {
    await withTimeout(getHealth(), HEALTH_TIMEOUT_MS, "health");
  } catch {
    return { kind: "down" };
  }
  try {
    const repos = await withTimeout(listRepos(), LIST_TIMEOUT_MS, "listRepos");
    const win = isWindowsPath(repoRoot);
    const target = normalizeRepoPath(repoRoot, win);
    const match = repos.find((r) => r.local_path && normalizeRepoPath(r.local_path, win) === target);
    return match ? { kind: "ok", repoId: match.id, updatedAt: match.updated_at ?? null } : { kind: "unlisted" };
  } catch (err) {
    if (err instanceof ApiClientError && (err.status === 401 || err.status === 403)) return { kind: "auth" };
    return { kind: "down" };
  }
}

/**
 * Whether this plugin's MCP server connects. Connecting, not calling a tool:
 * a single-repo server does not list `list_repos`, and the engine's own
 * connect says outright when `repowise mcp` cannot start.
 */
export async function mcpReachable(host: Host): Promise<boolean> {
  try {
    return await withTimeout(host.mcp.connect(), CONNECT_TIMEOUT_MS, "mcp connect");
  } catch {
    return false;
  }
}

/** Mode for a directory with no index: quiet outside a git work tree, else depends on the CLI. */
async function unindexedMode(host: Host, cwd: string): Promise<Mode> {
  const inWorkTree = (await git(host, cwd, ["rev-parse", "--is-inside-work-tree"]))?.trim() === "true";
  if (!inWorkTree) return "no-repo";
  return (await mcpReachable(host)) ? "no-index" : "no-cli";
}

/** The local server's state: only a loopback lock with a pid not known dead is probed. */
async function serverState(host: Host, repoRoot: string): Promise<ServerProbe> {
  const lock = await readServeLock(host, repoRoot);
  if (!lock || !isLoopbackUrl(lock.url)) return { kind: "down" };
  if ((await isPidAlive(host, lock.pid, repoRoot)) === false) return { kind: "down" };
  return probeServer(host, lock, repoRoot);
}

export async function discover(host: Host): Promise<Discovery> {
  const cwd = await host.session.cwd();
  const repoRoot = await findIndexedRoot(host, cwd);
  if (repoRoot === null) return { mode: await unindexedMode(host, cwd), repoRoot };
  const server = await serverState(host, repoRoot);
  if (server.kind === "ok") return { mode: "full", repoRoot, repo: { id: server.repoId, updatedAt: server.updatedAt } };
  if (!(await mcpReachable(host))) return { mode: "no-cli", repoRoot };
  const liteReason: LiteReason = server.kind === "down" ? "no-server" : server.kind;
  return { mode: "lite", liteReason, repoRoot };
}

async function git(host: Host, cwd: string, args: string[]): Promise<string | null> {
  try {
    const out = await withTimeout(host.process.run(["git", ...args], cwd), GIT_TIMEOUT_MS, "git");
    return out.exitCode === 0 ? out.stdout : null;
  } catch {
    return null;
  }
}

/**
 * True while `repowise update` holds its lock with a live pid. The band stays
 * quiet then rather than asking for an update that is already running.
 * Ceiling: the post-commit hook's short-lived `.update.queued` marker is not
 * read, so the row can show for the few seconds before the update starts.
 */
async function updateRunning(host: Host, repoRoot: string): Promise<boolean> {
  const lock = await readJson(host, join(repoRoot, ".repowise/.update.lock"));
  const pid = (lock as { pid?: unknown } | null)?.pid;
  return typeof pid === "number" && (await isPidAlive(host, pid, repoRoot)) === true;
}

/**
 * Index freshness, compared the way the SessionStart hook does it: the
 * state file's `last_sync_commit` against `git rev-parse HEAD`, and the count
 * from `git diff --name-only`. Read-only git only. null means nothing to
 * say: current, unknown, or an update already running.
 */
export async function readFreshness(host: Host, repoRoot: string): Promise<IndexFreshness | null> {
  const state = await readJson(host, join(repoRoot, ".repowise/state.json"));
  const indexed = (state as { last_sync_commit?: unknown } | null)?.last_sync_commit;
  // The state file is repo content: only a bare hex sha may reach git's argv.
  if (typeof indexed !== "string" || !SHA.test(indexed)) return null;
  const head = (await git(host, repoRoot, ["rev-parse", "HEAD"]))?.trim();
  if (!head || !SHA.test(head) || head === indexed) return null;
  if (await updateRunning(host, repoRoot)) return null;
  const diff = await git(host, repoRoot, ["diff", "--name-only", indexed, head, "--"]);
  const changedFiles = diff === null ? null : diff.split("\n").filter((l) => l.trim() !== "").length;
  return { changedFiles };
}