Skip to content

armgit / Ix

Public Imported from GitHub
0

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

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

import * as fs from "node:fs";
import * as path from "node:path";
import { canonicalWorkspacePath, resolveWorkspaceRoot } from "./config.js";
import { loadIngestBaseline, type IngestBaseline } from "./ingest-baseline.js";
import { hasCompletedMapFor } from "./map-baseline.js";
import { readMapRefreshOutcome, readMapStale } from "./map-freshness.js";
import { canonicalizeDiscoveredFilePath, discoverSourceFiles } from "./file-discovery.js";

export interface StaleInfo {
  graphCompleted: boolean;
  mapCompleted: boolean;
  /**
   * The last `ix map` deferred the map after an edit (CL-13): regions are the
   * last computed map's until a region view or `ix map --remap` refreshes
   * them. `mapCompleted` keeps its strict meaning and reads false meanwhile;
   * this says why.
   */
  mapStale: boolean;
  /**
   * While `mapStale`: why the last background refresh failed, when it did
   * (`readMapRefreshOutcome`); null otherwise.
   */
  mapRefreshError: string | null;
  lastIngestAt: string | null;
  currentRev: number;
  staleFiles: number;
  sampleChangedFiles: string[];
  /** Changed files the last run could not get applied (F-01); see `IngestBaseline.replayedFiles`. */
  replayedFiles: string[];
  /**
   * Files the last run skipped because their parse ran past the budget, still
   * on disk; see `IngestBaseline.parseTimeouts`. Not counted in `staleFiles`:
   * another run will not fix them, a larger IX_PARSE_BUDGET_MS will.
   */
  parseTimeouts: string[];
}

/**
 * Most files `ix status` reads when the workspace is not a git work tree; the
 * cap the old status walk had. A walk has no bound of its own, and status runs
 * on every agent turn: from a home directory it would read the whole disk.
 * Files past the cap are not checked for changes. They do not look deleted:
 * a baseline entry counts as deleted only when the file is gone from disk.
 */
const STATUS_WALK_LIMIT = 5000;

/**
 * The files `ix map` would discover (see `file-discovery.ts`), so "changed
 * since the last ingest" is judged over the same set the ingest recorded. A
 * git listing is complete; a walk stops at `walkLimit`.
 */
function collectFiles(dir: string, walkLimit: number): string[] {
  return discoverSourceFiles(dir, { walkLimit });
}

function differsFromIngestBaseline(
  filePath: string,
  mtimeMs: number,
  ingestedMtimes: Map<string, number>,
  lastIngestAt: string,
): boolean {
  const ingestedMtime = ingestedMtimes.get(filePath);
  return ingestedMtime === undefined
    ? mtimeMs > Date.parse(lastIngestAt)
    : ingestedMtime !== mtimeMs;
}

/**
 * Absolute paths for a baseline's list of files the last run could not
 * ingest. They count as changed whatever their mtime: a new one is absent from
 * `files` with an mtime older than `lastIngestAt`, which would otherwise read
 * as current.
 */
function absoluteSet(workspaceRoot: string, relPaths: readonly string[]): Set<string> {
  return new Set(relPaths.map((rel) => path.resolve(workspaceRoot, rel)));
}

/**
 * Detect files that have been modified since the last ingest.
 * Uses the workspace-local ingest baseline so another workspace cannot advance it.
 *
 * Takes no client and is not async, by construction rather than by discipline.
 * Staleness used to be decided from `listPatches({ limit: 1 })`, which carries
 * no workspace, so it answered with whatever repo was mapped most recently
 * anywhere on the machine (#353). Keeping an unused client parameter around
 * left the door open to reaching for it again; without one there is nothing to
 * reach for, and the local-only property holds because it is the only thing the
 * signature permits.
 */
export function detectStaleFiles(
  root: string,
  maxSamples: number = 5,
  walkLimit: number = STATUS_WALK_LIMIT,
): StaleInfo {
  const workspaceRoot = path.resolve(root);
  const baseline = loadIngestBaseline(workspaceRoot);
  if (!baseline) {
    return {
      graphCompleted: false,
      mapCompleted: false,
      mapStale: false,
      mapRefreshError: null,
      lastIngestAt: null,
      currentRev: 0,
      staleFiles: 0,
      sampleChangedFiles: [],
      replayedFiles: [],
      parseTimeouts: [],
    };
  }

  // Discovery returns canonical paths (macOS `/var` is `/private/var`, a
  // Windows 8.3 name is expanded), while the baseline's keys sit under the root
  // as it was given. Compare and display both under the canonical root.
  const canonicalRoot = canonicalizeDiscoveredFilePath(workspaceRoot);
  const underCanonicalRoot = (absolutePath: string): string =>
    canonicalRoot !== workspaceRoot && absolutePath.startsWith(workspaceRoot + path.sep)
      ? canonicalRoot + absolutePath.slice(workspaceRoot.length)
      : absolutePath;
  const ingestedMtimes = new Map<string, number>();
  for (const [ingestedPath, mtime] of baseline.files) {
    const absolutePath = path.isAbsolute(ingestedPath)
      ? path.resolve(ingestedPath)
      : path.resolve(workspaceRoot, ingestedPath);
    ingestedMtimes.set(underCanonicalRoot(absolutePath), mtime);
  }

  const files = collectFiles(workspaceRoot, walkLimit).map(underCanonicalRoot);
  const currentFiles = new Set(files);
  const changedFiles: string[] = [];
  // Under the canonical root, like everything else compared here.
  const canonicalSet = (relPaths: readonly string[]): Set<string> =>
    new Set([...absoluteSet(workspaceRoot, relPaths)].map(underCanonicalRoot));
  const pending = canonicalSet(baseline.pendingFiles);
  // Canonical path -> the baseline's own workspace-relative spelling, which is
  // what status reports: POSIX separators on every platform, as the ingest
  // summary names them.
  const timedOut = new Map(
    baseline.parseTimeouts.map((rel) => [underCanonicalRoot(path.resolve(workspaceRoot, rel)), rel]),
  );
  const parseTimeouts: string[] = [];

  for (const filePath of files) {
    const timedOutAs = timedOut.get(filePath);
    if (timedOutAs !== undefined) {
      parseTimeouts.push(timedOutAs);
      continue;
    }
    try {
      const stat = fs.statSync(filePath);
      if (
        pending.has(filePath)
        || differsFromIngestBaseline(filePath, stat.mtimeMs, ingestedMtimes, baseline.lastIngestAt)
      ) {
        // Make path relative to root for display
        changedFiles.push(path.relative(canonicalRoot, filePath));
      }
    } catch {
      // skip inaccessible files
    }
  }

  for (const absolutePath of ingestedMtimes.keys()) {
    if (!currentFiles.has(absolutePath) && !fs.existsSync(absolutePath)) {
      changedFiles.push(path.relative(canonicalRoot, absolutePath));
    }
  }

  const mapStale = readMapStale(workspaceRoot) !== null;
  const lastRefresh = mapStale ? readMapRefreshOutcome(workspaceRoot) : null;
  const mapRefreshError = lastRefresh?.ok === false ? (lastRefresh.reason ?? "no reason recorded") : null;
  return {
    graphCompleted: true,
    mapCompleted: hasCompletedMapFor(workspaceRoot, baseline),
    mapStale,
    mapRefreshError,
    lastIngestAt: baseline.lastIngestAt,
    currentRev: baseline.currentRev,
    staleFiles: changedFiles.length,
    sampleChangedFiles: changedFiles.slice(0, maxSamples),
    replayedFiles: baseline.replayedFiles,
    parseTimeouts,
  };
}

/**
 * The ingest baseline for `root`, and the spelling of the root it is stored
 * under. The baselines match their root as a string. `ix map` stores the
 * canonical root, so a symlinked or 8.3-named spelling of it (RUNNER~1 on
 * Windows) read as never mapped; a root stored as given (`ix ingest` of a path
 * spelled that way) is still found under its own spelling first.
 */
function loadBaselineUnderEitherSpelling(root: string): { root: string; baseline: IngestBaseline } | null {
  const resolved = path.resolve(root);
  const asGiven = loadIngestBaseline(resolved);
  if (asGiven) return { root: resolved, baseline: asGiven };
  const canonical = canonicalWorkspacePath(resolved);
  if (canonical === resolved) return null;
  const baseline = loadIngestBaseline(canonical);
  return baseline ? { root: canonical, baseline } : null;
}

/**
 * Whether the active workspace has a completed map baseline.
 *
 * The marker is written only after a non-empty hierarchy response and is tied
 * to the source revision it mapped. A later clean ingest therefore leaves the
 * source graph usable while making the prior hierarchy incomplete for the new
 * revision.
 */
export function hasCompletedMapBaseline(root?: string): boolean {
  try {
    const found = loadBaselineUnderEitherSpelling(root ?? resolveWorkspaceRoot());
    return found !== null && hasCompletedMapFor(found.root, found.baseline);
  } catch {
    return false;
  }
}

/** Whether source ingestion completed cleanly for the active workspace. */
export function hasCompletedSourceGraphBaseline(root?: string): boolean {
  try {
    return loadBaselineUnderEitherSpelling(root ?? resolveWorkspaceRoot()) !== null;
  } catch {
    return false;
  }
}

/**
 * Check if a specific file path differs from the active workspace's ingest baseline.
 *
 * Synchronous now that it reads a local file instead of the patch log. It is
 * called per result on `ix explain`, `ix locate` and `ix read`, so the `await`
 * this used to need was once a backend round-trip per file.
 */
export function isFileStale(filePath: string): boolean {
  return createStaleProbe()(filePath);
}

/**
 * A staleness predicate that loads the ingest baseline once.
 *
 * `isFileStale` re-reads and re-parses the whole mtime cache on every call,
 * which is fine for the handful of results `ix explain` / `ix locate` /
 * `ix read` check but not for a caller asking about many files at once — that
 * turns one JSON parse of a file holding every ingested path into N of them.
 * Callers with a list should take a probe and reuse it.
 */
export function createStaleProbe(): (filePath: string) => boolean {
  const workspaceRoot = path.resolve(resolveWorkspaceRoot());
  const baseline = loadIngestBaseline(workspaceRoot);
  const pending = baseline
    ? absoluteSet(workspaceRoot, [...baseline.pendingFiles, ...baseline.parseTimeouts])
    : new Set<string>();

  return (filePath: string): boolean => {
    // No baseline means the question this probe answers — "did this file change
    // since it was ingested?" — has no answer, not that the answer is yes. The
    // baseline is absent for a cloud-ingested workspace and for any workspace
    // whose ingest never completed cleanly, so answering `true` reported every
    // result of every command as modified in repos that were perfectly current.
    // That unverified state is carried by `ix context`'s freshness
    // classification instead, which can say so without claiming a file changed.
    if (!baseline) return false;

    const absolutePath = path.isAbsolute(filePath)
      ? path.resolve(filePath)
      : path.resolve(workspaceRoot, filePath);
    if (!fs.existsSync(absolutePath)) {
      return baseline.files.has(absolutePath) || baseline.files.has(filePath);
    }
    if (pending.has(absolutePath)) return true;

    try {
      return differsFromIngestBaseline(
        absolutePath,
        fs.statSync(absolutePath).mtimeMs,
        baseline.files,
        baseline.lastIngestAt,
      );
    } catch {
      return false;
    }
  };
}