Skip to content

Find code by asking what it does. A CLI for coding agents that uses Jev to discover relevant files and source context.

11.7 KB
Raw Blame
import { createHash, randomUUID } from "node:crypto";
import { constants } from "node:fs";
import { chmod, lstat, mkdir, open, opendir, rename, rm, unlink } from "node:fs/promises";
import { join, resolve } from "node:path";

export type JsonValue =
  | null
  | boolean
  | number
  | string
  | readonly JsonValue[]
  | { readonly [key: string]: JsonValue | undefined };
export type CacheInput = {
  request: JsonValue;
  namespace: { model: string; provider: string; policyVersion: string; [key: string]: string };
};
export type CacheAnswers = Record<string, number>;
export type CacheIssue = "cache_unavailable" | "cache_corrupt" | "cache_limit";
export type CacheOptions = {
  /** Caller supplies the storage location; this directory contains only Jevgrep cache data. */
  directory: string;
  enabled?: boolean;
  ttlMs?: number;
  maxBytes?: number;
  now?: () => number;
};
const schema = 1;
const entryName = /^[a-f0-9]{64}\.json$/;
const pendingName = /^\.pending-[a-f0-9-]+$/;
// Abandoned publications after a crash must not accumulate forever; current writes get an hour.
const pendingLifetimeMs = 60 * 60 * 1000;
const maintenanceIntervalMs = 60 * 60 * 1000;
/** Tiny answer files still occupy whole filesystem blocks; the byte bound counts that space. */
function allocated(size: number, blocks = 0) {
  return Math.max(Math.ceil(size / 4096) * 4096, blocks * 512);
}

function validAnswers(value: unknown): value is CacheAnswers {
  return (
    !!value &&
    typeof value === "object" &&
    !Array.isArray(value) &&
    Object.values(value).every((answer) => typeof answer === "number" && Number.isFinite(answer))
  );
}
function missing(error: unknown) {
  return (error as NodeJS.ErrnoException).code === "ENOENT";
}

/** Answer-only, best-effort storage; the evaluator must validate success before calling put. */
export function createEvaluationCache(options: CacheOptions) {
  const directory = resolve(options.directory);
  const entries = join(directory, "entries");
  const enabled = options.enabled !== false;
  const ttlMs = options.ttlMs ?? 7 * 24 * 60 * 60 * 1000;
  const maxBytes = options.maxBytes ?? 256 * 1024 * 1024;
  const now = options.now ?? Date.now;
  if (
    !Number.isSafeInteger(ttlMs) ||
    ttlMs <= 0 ||
    !Number.isSafeInteger(maxBytes) ||
    maxBytes <= 0
  )
    throw new Error("Invalid cache limits");
  const maxEntryBytes = Math.min(maxBytes, 1024 * 1024);
  const issues = new Map<CacheIssue, number>();
  let hits = 0,
    misses = 0;
  function warn(kind: CacheIssue) {
    issues.set(kind, (issues.get(kind) ?? 0) + 1);
  }
  function key(input: CacheInput) {
    // Preserve request/question ordering. Only this digest, never the serialized request, reaches disk.
    return createHash("sha256")
      .update(JSON.stringify([schema, input.namespace, input.request]))
      .digest("hex");
  }
  async function checkDirectory(path: string, create: boolean) {
    if (create) await mkdir(path, { recursive: true, mode: 0o700 });
    const info = await lstat(path);
    if (!info.isDirectory() || info.isSymbolicLink())
      throw new Error("Cache path is not a directory");
    if (create && (info.mode & 0o777) !== 0o700) await chmod(path, 0o700);
  }
  async function prepare(create: boolean) {
    await checkDirectory(directory, create);
    await checkDirectory(entries, create);
  }
  async function get(input: CacheInput): Promise<CacheAnswers | undefined> {
    if (!enabled) {
      misses++;
      return undefined;
    }
    let handle;
    try {
      await prepare(false);
      handle = await open(
        join(entries, `${key(input)}.json`),
        constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0),
      );
      const info = await handle.stat();
      if (!info.isFile() || info.size > maxEntryBytes) {
        warn("cache_corrupt");
        misses++;
        return undefined;
      }
      const buffer = Buffer.allocUnsafe(maxEntryBytes + 1);
      let length = 0;
      while (length < buffer.length) {
        const result = await handle.read(buffer, length, buffer.length - length, null);
        if (!result.bytesRead) break;
        length += result.bytesRead;
      }
      if (length > maxEntryBytes) {
        warn("cache_corrupt");
        misses++;
        return undefined;
      }
      let value;
      try {
        value = JSON.parse(
          new TextDecoder("utf-8", { fatal: true }).decode(buffer.subarray(0, length)),
        );
      } catch {
        warn("cache_corrupt");
        misses++;
        return undefined;
      }
      if (
        value?.schema !== schema ||
        typeof value.createdAt !== "number" ||
        !Number.isFinite(value.createdAt) ||
        !validAnswers(value.answers)
      ) {
        warn("cache_corrupt");
        misses++;
        return undefined;
      }
      const age = now() - value.createdAt;
      if (age < 0 || age >= ttlMs) {
        misses++;
        return undefined;
      }
      hits++;
      return value.answers;
    } catch (error) {
      if (!missing(error)) warn("cache_unavailable");
      misses++;
      return undefined;
    } finally {
      try {
        await handle?.close();
      } catch {
        warn("cache_unavailable");
      }
    }
  }
  async function remove(path: string) {
    try {
      await unlink(path);
    } catch (error) {
      if (!missing(error)) throw error;
    }
  }
  let checked = false;
  let sweeping: Promise<void> | undefined;
  /** Allocated bytes seen by the last sweep plus this process's writes since then. */
  let estimate = 0;
  // Its mtime records the last completed sweep by any process, on the cache clock.
  const stamp = join(directory, "maintained");
  async function maintenanceDue() {
    try {
      const info = await lstat(stamp);
      const age = now() - info.mtimeMs;
      return !info.isFile() || age < 0 || age >= maintenanceIntervalMs;
    } catch {
      return true;
    }
  }
  /** A directory pass runs at most once per interval across processes, or when this process's
   * writes exceed the budget. Entry age is its mtime on the cache clock, so no entry is opened.
   * Between passes the budget can be exceeded by recent writes. Eviction is deliberately not LRU:
   * reads never write, and the oldest answers go first. */
  async function maintain(): Promise<number> {
    await cleanupDetached();
    const names: string[] = [];
    for await (const entry of await opendir(entries))
      if (entryName.test(entry.name) || pendingName.test(entry.name)) names.push(entry.name);
    const retained: Array<{ name: string; mtimeMs: number; bytes: number }> = [];
    let total = 0;
    await pooled(names, async (name) => {
      const path = join(entries, name);
      try {
        const info = await lstat(path);
        // lstat does not follow links: symlinks and special files are skipped, never touched.
        if (!info.isFile()) return;
        // Future timestamps are other writers' fresh entries or clock changes, never expiry.
        const age = now() - info.mtimeMs;
        if (pendingName.test(name)) {
          if (age > pendingLifetimeMs) await remove(path);
        } else if (age >= ttlMs) await remove(path);
        else {
          const bytes = allocated(info.size, info.blocks);
          retained.push({ name, mtimeMs: info.mtimeMs, bytes });
          total += bytes;
        }
      } catch (error) {
        if (!missing(error)) warn("cache_unavailable");
      }
    });
    if (total > maxBytes) {
      // Leave headroom so the next few writes do not immediately trigger another pass.
      const target = maxBytes - Math.floor(maxBytes / 8);
      retained.sort((a, b) => a.mtimeMs - b.mtimeMs || (a.name < b.name ? -1 : 1));
      const evicted: typeof retained = [];
      for (const entry of retained) {
        if (total <= target) break;
        evicted.push(entry);
        total -= entry.bytes;
      }
      await pooled(evicted, async (entry) => {
        try {
          await remove(join(entries, entry.name));
        } catch {
          total += entry.bytes;
          warn("cache_unavailable");
        }
      });
    }
    return total;
  }
  /** Bounded parallel filesystem work; each task handles its own errors. */
  async function pooled<T>(items: T[], work: (item: T) => Promise<void>) {
    let next = 0;
    await Promise.all(
      Array.from({ length: Math.min(16, items.length) }, async () => {
        while (next < items.length) await work(items[next++]!);
      }),
    );
  }
  function sweep() {
    sweeping ??= (async () => {
      try {
        estimate = await maintain();
        const handle = await open(
          stamp,
          constants.O_WRONLY | constants.O_CREAT | constants.O_NOFOLLOW,
          0o600,
        );
        try {
          await handle.utimes(now() / 1000, now() / 1000);
        } finally {
          await handle.close();
        }
      } catch (error) {
        if (!missing(error)) warn("cache_unavailable");
      } finally {
        sweeping = undefined;
      }
    })();
    return sweeping;
  }
  async function cleanupDetached() {
    const scan = await opendir(directory);
    for await (const entry of scan) {
      if (!/^\.cleared-[a-f0-9-]+$/.test(entry.name)) continue;
      try {
        await rm(join(directory, entry.name), { recursive: true, force: true });
      } catch (error) {
        if (!missing(error)) warn("cache_unavailable");
      }
    }
  }
  async function put(input: CacheInput, answers: CacheAnswers): Promise<void> {
    if (!enabled) return;
    let temporary: string | undefined;
    let handle;
    try {
      if (!validAnswers(answers)) {
        warn("cache_corrupt");
        return;
      }
      const createdAt = now();
      const payload = JSON.stringify({ schema, createdAt, answers });
      const size = Buffer.byteLength(payload);
      if (size > maxEntryBytes || allocated(size) > maxBytes) {
        warn("cache_limit");
        return;
      }
      const destination = join(entries, `${key(input)}.json`);
      await prepare(true);
      temporary = join(entries, `.pending-${randomUUID()}`);
      handle = await open(
        temporary,
        constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0),
        0o600,
      );
      await handle.writeFile(payload);
      // Maintenance reads age from mtime; keep it on the same clock as createdAt.
      await handle.utimes(createdAt / 1000, createdAt / 1000);
      await handle.close();
      handle = undefined;
      await rename(temporary, destination);
      temporary = undefined;
      estimate += allocated(size);
      if (!checked) {
        checked = true;
        if (await maintenanceDue()) await sweep();
      } else if (estimate > maxBytes) await sweep();
    } catch {
      warn("cache_unavailable");
    } finally {
      try {
        await handle?.close();
      } catch {
        warn("cache_unavailable");
      }
      if (temporary) {
        try {
          await remove(temporary);
        } catch {
          warn("cache_unavailable");
        }
      }
    }
  }
  async function clear(): Promise<void> {
    // Detach the current generation atomically. Later writers create a new one; no global lock or pause.
    const detached = join(directory, `.cleared-${randomUUID()}`);
    try {
      await checkDirectory(directory, false);
      try {
        await checkDirectory(entries, false);
        await rename(entries, detached);
        estimate = 0;
      } catch (error) {
        if (!missing(error)) throw error;
      }
      await remove(stamp);
      await cleanupDetached();
    } catch (error) {
      if (!missing(error)) warn("cache_unavailable");
    }
  }
  function stats() {
    return { hits, misses, issues: [...issues].map(([kind, count]) => ({ kind, count })) };
  }
  return { get, put, clear, stats };
}
export type EvaluationCache = ReturnType<typeof createEvaluationCache>;