Skip to content

armgit / Ix

Public Imported from GitHub
0

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

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

import * as fs from "node:fs";
import * as path from "node:path";
import { ingestMtimeCachePath, ingestOrphanSweepPath, ingestRebuildPath } from "./config.js";

interface SerializedIngestBaseline {
  root: string;
  files: Record<string, number>;
  deletedFiles?: Record<string, string[]>;
  currentRev?: number;
  lastIngestAt?: string;
  tracksMapBaseline?: boolean;
  extractor?: string;
  replayedFiles?: string[];
  pendingFiles?: string[];
  parseTimeouts?: string[];
}

export interface IngestBaseline {
  files: Map<string, number>;
  deletedFiles: Map<string, string[]>;
  currentRev: number;
  lastIngestAt: string;
  /**
   * Whether this baseline was written by a CLI that also maintains the
   * architecture-map marker.
   *
   * Absent on every baseline written before that marker existed, which is what
   * makes it usable as an upgrade signal: such a workspace has a clean source
   * ingest and no marker, and the CLI that produced it *reported that state as
   * map-complete*. Treating it as incomplete on the first run after an upgrade
   * would fail `ix doctor` on every existing workspace at once, for a claim
   * nothing has actually re-evaluated. See `hasCompletedMapFor`.
   */
  tracksMapBaseline: boolean;
  /**
   * The extractor (`extractorName()`) whose output the recorded files carry.
   * Null on a baseline written before this was recorded, which could have been
   * any extractor, so it counts as a change. See `extractorChanged`.
   */
  extractor: string | null;
  /**
   * Workspace-relative paths of changed files the last run sent and the
   * backend answered `Idempotent`: it already held that patch id and wrote
   * nothing, so the graph does not show these files as they are (F-01, a
   * revert or a restore). Empty when every change was applied. Their mtimes
   * are kept at the previous value, so the next run sends them again.
   */
  replayedFiles: string[];
  /**
   * Workspace-relative paths of changed files the last run could not ingest:
   * a read or build error, a failed commit, a parse lost to a dead worker.
   * Each keeps its previous mtime, so the next run retries it. A new file has
   * no previous mtime and is left out of `files`, and a file missing from
   * `files` is judged stale against `lastIngestAt`, which that same run moved
   * past the file's mtime -- so without this list `ix status` called the
   * graph current while the file was not in it.
   */
  pendingFiles: string[];
  /**
   * Workspace-relative paths of files whose parse ran past the per-file
   * budget (`IX_PARSE_BUDGET_MS`) on the last run, so they are not in the
   * graph. Not settled: like `pendingFiles` they keep their previous mtime
   * (or none) and every run tries them again, and `ix status` warns about
   * them rather than calling the graph current. A slow file times out on
   * every run, so recording it clean skipped it for good.
   */
  parseTimeouts: string[];
}

/** Per-file lists a baseline write records beside the mtimes. */
export interface BaselineFileNotes {
  /** See `IngestBaseline.replayedFiles`. */
  replayedFiles?: readonly string[];
  /** See `IngestBaseline.pendingFiles`. */
  pendingFiles?: readonly string[];
  /** See `IngestBaseline.parseTimeouts`. */
  parseTimeouts?: readonly string[];
}

const stringList = (value: unknown): string[] =>
  Array.isArray(value) ? value.filter((p): p is string => typeof p === "string") : [];

/**
 * What counts as a revision, for both sides of this file.
 *
 * The rev arrives off the backend's commit response, so it is response data
 * rather than anything this process computed, and `typeof` is not enough — the
 * read side has always insisted on a non-negative integer. One predicate so the
 * two sides cannot drift apart again; they were previously three lines apart
 * and disagreed.
 */
export function isRev(value: unknown): value is number {
  return typeof value === "number" && Number.isInteger(value) && value >= 0;
}

export function loadIngestBaseline(projectRoot: string): IngestBaseline | null {
  const cachePath = ingestMtimeCachePath(projectRoot);
  try {
    const data = JSON.parse(fs.readFileSync(cachePath, "utf-8")) as SerializedIngestBaseline;
    if (data.root !== projectRoot || !data.files || typeof data.files !== "object") return null;

    const files = new Map<string, number>();
    for (const [filePath, mtime] of Object.entries(data.files)) {
      if (Number.isFinite(mtime)) files.set(filePath, mtime);
    }
    const deletedFiles = new Map<string, string[]>();
    for (const [filePath, dependents] of Object.entries(data.deletedFiles ?? {})) {
      if (!Array.isArray(dependents)) continue;
      deletedFiles.set(
        filePath,
        dependents.filter((dependent): dependent is string => typeof dependent === "string"),
      );
    }

    const parsedTimestamp = data.lastIngestAt ? Date.parse(data.lastIngestAt) : Number.NaN;
    const lastIngestAt = Number.isFinite(parsedTimestamp)
      ? new Date(parsedTimestamp).toISOString()
      : fs.statSync(cachePath).mtime.toISOString();
    const currentRev = isRev(data.currentRev) ? data.currentRev : 0;

    return {
      files,
      deletedFiles,
      currentRev,
      lastIngestAt,
      tracksMapBaseline: data.tracksMapBaseline === true,
      extractor: typeof data.extractor === "string" ? data.extractor : null,
      replayedFiles: stringList(data.replayedFiles),
      pendingFiles: stringList(data.pendingFiles),
      parseTimeouts: stringList(data.parseTimeouts),
    };
  } catch {
    return null;
  }
}

export function saveIngestBaseline(
  projectRoot: string,
  mtimes: Map<string, number>,
  currentRev: number,
  now: Date = new Date(),
  deletedFiles: Map<string, string[]> = new Map(),
  extractor?: string | null,
  { replayedFiles = [], pendingFiles = [], parseTimeouts = [] }: BaselineFileNotes = {},
): void {
  try {
    // Keep the last good rev rather than writing a shape the read side will
    // reject. `ix status` is the only thing that reads this number, so a bad one
    // costs a wrong Revision line, not a re-ingest — incremental skipping runs
    // off the mtime map below and is unaffected either way. The lookup is lazy
    // because it parses the entire baseline for one integer, and the reject
    // branch is the only one that wants it: onCommitted calls this once per
    // deleted file, so an eager read would re-parse the whole map N times.
    const rev = isRev(currentRev) && currentRev > 0
      ? currentRev
      : (loadIngestBaseline(projectRoot)?.currentRev ?? 0);
    const data: SerializedIngestBaseline = {
      root: projectRoot,
      files: Object.fromEntries(mtimes),
      deletedFiles: Object.fromEntries(deletedFiles),
      currentRev: rev,
      lastIngestAt: now.toISOString(),
      // Written unconditionally from here on, so its absence dates a baseline
      // to before the map marker existed. The first ingest after an upgrade
      // sets it, which is what ends the grandfathering for this workspace.
      tracksMapBaseline: true,
      ...(extractor ? { extractor } : {}),
      ...(replayedFiles.length > 0 ? { replayedFiles: [...replayedFiles].sort() } : {}),
      ...(pendingFiles.length > 0 ? { pendingFiles: [...new Set(pendingFiles)].sort() } : {}),
      ...(parseTimeouts.length > 0 ? { parseTimeouts: [...new Set(parseTimeouts)].sort() } : {}),
    };
    const target = ingestMtimeCachePath(projectRoot);
    fs.mkdirSync(path.dirname(target), { recursive: true });
    // Via a temp file and rename: a process killed mid-write left a truncated
    // baseline, which reads as none, and the next map re-ingested everything.
    const tmp = `${target}.${process.pid}.tmp`;
    try {
      fs.writeFileSync(tmp, JSON.stringify(data));
      fs.renameSync(tmp, target);
    } catch (err) {
      // A failed rename (a locked target on Windows, say) must not leave the
      // temp file behind; one would pile up per failing run.
      fs.rmSync(tmp, { force: true });
      throw err;
    }
  } catch {
    // The cache is an optimization and freshness hint. Ingestion itself succeeded.
  }
}

/**
 * Whether the files in `baseline` were extracted by a different extractor.
 *
 * `ix map` skips a file whose mtime or source hash is unchanged, and neither
 * sees an extractor bump, so without this an unchanged file keeps the nodes and
 * edges the old extractor built until it is edited or `--force` runs. No
 * baseline means nothing was skipped anyway, so it is not a change.
 */
export function extractorChanged(baseline: IngestBaseline | null, current: string): boolean {
  return baseline !== null && baseline.extractor !== current;
}

/**
 * Files an unfinished re-ingest for `extractor` has already committed, with the
 * mtime each had then; null when there is none for this extractor.
 *
 * The re-ingest an extractor change forces takes about twice a first map, and
 * the mtime baseline is written only when a run finishes. So a run cut short --
 * an editor hook's timeout, a closed terminal -- used to leave nothing behind,
 * and every later run started over and could be cut short at the same point.
 * Recording progress as files land lets the next run skip what is done.
 */
export function loadRebuildProgress(projectRoot: string, extractor: string): Map<string, number> | null {
  try {
    const data = JSON.parse(fs.readFileSync(ingestRebuildPath(projectRoot), "utf-8")) as {
      root?: unknown; extractor?: unknown; files?: Record<string, unknown>;
    };
    if (data.root !== projectRoot || data.extractor !== extractor || !data.files || typeof data.files !== "object") {
      return null;
    }
    const files = new Map<string, number>();
    for (const [filePath, mtime] of Object.entries(data.files)) {
      if (typeof mtime === "number" && Number.isFinite(mtime)) files.set(filePath, mtime);
    }
    return files;
  } catch {
    return null;
  }
}

export function saveRebuildProgress(projectRoot: string, extractor: string, files: Map<string, number>): void {
  try {
    const target = ingestRebuildPath(projectRoot);
    fs.mkdirSync(path.dirname(target), { recursive: true });
    // Via a temp file and rename: a process killed mid-write would otherwise
    // leave a truncated file, and the next run would start over.
    const tmp = `${target}.${process.pid}.tmp`;
    fs.writeFileSync(tmp, JSON.stringify({ root: projectRoot, extractor, files: Object.fromEntries(files) }));
    fs.renameSync(tmp, target);
  } catch {
    // Progress is an optimization; losing it costs a longer re-ingest, not data.
  }
}

export function clearRebuildProgress(projectRoot: string): void {
  try { fs.rmSync(ingestRebuildPath(projectRoot), { force: true }); } catch { /* non-critical */ }
}

/**
 * Orphan sweeps (IN-20) an earlier run left unfinished, by the extractor whose
 * stored patches name the orphans: the workspace-relative files still to
 * sweep, or null for every file. An extractor change whose sweep could not run
 * (a backend without bulk deletes or the batched node read) records the
 * previous extractor for every file; one that ran out of budget records the
 * files it skipped. A repair run (`IX_RECONCILE_ON_FORCE=1 ix map --force`)
 * then reads only these patches, for only these files, so it reaches orphans
 * more than one extractor back and picks up where the last run stopped.
 */
export type OrphanSweepPending = Map<string, Set<string> | null>;

export function loadOrphanSweepPending(projectRoot: string): OrphanSweepPending {
  const pending: OrphanSweepPending = new Map();
  try {
    const data = JSON.parse(fs.readFileSync(ingestOrphanSweepPath(projectRoot), "utf-8")) as {
      root?: unknown; pending?: Record<string, unknown>;
    };
    if (data.root !== projectRoot || !data.pending || typeof data.pending !== "object") return pending;
    for (const [extractor, files] of Object.entries(data.pending)) {
      if (files === null) pending.set(extractor, null);
      else if (Array.isArray(files)) pending.set(extractor, new Set(stringList(files)));
    }
  } catch {
    // None recorded, or unreadable: a repair falls back to its default.
  }
  return pending;
}

export function saveOrphanSweepPending(projectRoot: string, pending: OrphanSweepPending): void {
  try {
    const target = ingestOrphanSweepPath(projectRoot);
    const entries = [...pending].filter(([, files]) => files === null || files.size > 0);
    if (entries.length === 0) {
      fs.rmSync(target, { force: true });
      return;
    }
    fs.mkdirSync(path.dirname(target), { recursive: true });
    const tmp = `${target}.${process.pid}.tmp`;
    const serialized = Object.fromEntries(entries.map(([extractor, files]) => [extractor, files === null ? null : [...files].sort()]));
    fs.writeFileSync(tmp, JSON.stringify({ root: projectRoot, pending: serialized }));
    fs.renameSync(tmp, target);
  } catch {
    // Losing it costs a repair that reads the default patch, not data.
  }
}