pi-readseek 0.1.0

package/src/pending-diff-preview.ts

@@ -0,0 +1,269 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { generateDiffString, normalizeToLF, replaceText } from "./edit-diff.js";
+import { applyHashlineEdits, type HashlineEditItem } from "./hashline.js";
+import { replaceSymbol } from "./replace-symbol.js";
+
+export const PENDING_DIFF_MAX_BYTES = 1024 * 1024;
+
+export interface PendingDiffPreviewData {
+	filePath: string;
+	previousContent: string;
+	nextContent: string;
+	fileExistedBeforeWrite: boolean;
+	headerLabel: "pending edit" | "pending overwrite" | "pending create";
+	diff: string;
+}
+
+export type PendingDiffPreviewResult =
+	| { type: "ok"; data: PendingDiffPreviewData }
+	| { type: "skip"; reason: string };
+
+function skip(reason: string): PendingDiffPreviewResult {
+	return { type: "skip", reason };
+}
+
+function isInsidePath(parent: string, child: string): boolean {
+	const rel = relative(parent, child);
+	return rel === "" || (rel !== "" && !rel.startsWith("..") && !rel.startsWith(sep) && !resolve(rel).startsWith(".." + sep));
+}
+
+function resolveWorkspacePreviewPath(rawPath: unknown, cwd: string, allowMissing: boolean): { type: "ok"; path: string; existed: boolean } | { type: "skip"; reason: string } {
+	if (typeof rawPath !== "string" || rawPath.trim() === "") return { type: "skip", reason: "missing path" };
+	const workspace = realpathSync(cwd);
+	const normalizedPath = rawPath.replace(/^@/, "");
+	const explicitAbsolute = isAbsolute(normalizedPath);
+	const requested = resolve(workspace, normalizedPath);
+	if (existsSync(requested)) {
+		const realTarget = realpathSync(requested);
+		if (!explicitAbsolute && !isInsidePath(workspace, realTarget)) return { type: "skip", reason: "path outside workspace" };
+		return { type: "ok", path: realTarget, existed: true };
+	}
+
+	if (!explicitAbsolute && !isInsidePath(workspace, requested)) return { type: "skip", reason: "path outside workspace" };
+
+	if (!allowMissing) return { type: "skip", reason: "file not found" };
+	const parent = dirname(requested);
+	if (!existsSync(parent)) return { type: "skip", reason: "parent directory not found" };
+	return { type: "ok", path: requested, existed: false };
+}
+
+function readUtf8File(filePath: string): { type: "ok"; content: string } | { type: "skip"; reason: string } {
+	const stat = statSync(filePath);
+	if (!stat.isFile()) return { type: "skip", reason: "not a file" };
+	if (stat.size > PENDING_DIFF_MAX_BYTES) return { type: "skip", reason: "file too large" };
+	const content = readFileSync(filePath, "utf-8");
+	if (content.includes("\0")) return { type: "skip", reason: "binary file" };
+	return { type: "ok", content };
+}
+
+function buildData(
+	filePath: string,
+	previousContent: string,
+	nextContent: string,
+	existed: boolean,
+	headerLabel: PendingDiffPreviewData["headerLabel"],
+): PendingDiffPreviewResult {
+	const diff = generateDiffString(normalizeToLF(previousContent), normalizeToLF(nextContent)).diff;
+	return {
+		type: "ok",
+		data: {
+			filePath,
+			previousContent,
+			nextContent,
+			fileExistedBeforeWrite: existed,
+			headerLabel,
+			diff,
+		},
+	};
+}
+
+type ReplaceEdit = { replace: { old_text: string; new_text: string; all?: boolean; fuzzy?: boolean } };
+type PendingEditInput = { path?: unknown; edits?: unknown[] };
+
+function getEdits(input: PendingEditInput): unknown[] {
+	return Array.isArray(input.edits) ? input.edits : [];
+}
+
+function isReplaceEdit(edit: unknown): edit is ReplaceEdit {
+	if (!edit || typeof edit !== "object" || !("replace" in edit)) return false;
+	const replace = (edit as { replace?: { old_text?: unknown; new_text?: unknown } }).replace;
+	return typeof replace?.old_text === "string" && typeof replace?.new_text === "string";
+}
+
+type AnchorEdit =
+	| { set_line: { anchor: string; new_text: string } }
+	| { replace_lines: { start_anchor: string; end_anchor: string; new_text: string } }
+	| { insert_after: { anchor: string; new_text: string; text?: string } };
+
+function isAnchorEdit(edit: unknown): edit is AnchorEdit {
+	return !!edit && typeof edit === "object" && ("set_line" in edit || "replace_lines" in edit || "insert_after" in edit);
+}
+
+function applyAnchoredPreview(content: string, edits: AnchorEdit[]): { type: "ok"; content: string } | { type: "skip"; reason: string } {
+	try {
+		return { type: "ok", content: applyHashlineEdits(content, edits as HashlineEditItem[]).content };
+	} catch (err: any) {
+		return { type: "skip", reason: `anchor projection failed: ${err?.message ?? String(err)}` };
+	}
+}
+
+type ReplaceSymbolEdit = { replace_symbol: { symbol: string; new_body: string } };
+
+function isReplaceSymbolEdit(edit: unknown): edit is ReplaceSymbolEdit {
+	if (!edit || typeof edit !== "object" || !("replace_symbol" in edit)) return false;
+	const replaceSymbol = (edit as { replace_symbol?: { symbol?: unknown; new_body?: unknown } }).replace_symbol;
+	return typeof replaceSymbol?.symbol === "string" && typeof replaceSymbol?.new_body === "string";
+}
+
+async function applyReplaceSymbolPreview(filePath: string, content: string, edit: ReplaceSymbolEdit): Promise<{ type: "ok"; content: string } | { type: "skip"; reason: string }> {
+	try {
+		if (!edit.replace_symbol.new_body.trim()) return { type: "skip", reason: "replace_symbol new_body is empty" };
+		const probe = await replaceSymbol({
+			filePath,
+			content,
+			symbol: edit.replace_symbol.symbol,
+			newBody: edit.replace_symbol.new_body,
+		});
+		if (probe.type !== "ok") return { type: "skip", reason: `symbol projection failed: ${probe.message}` };
+		return { type: "ok", content: probe.content };
+	} catch (err: any) {
+		return { type: "skip", reason: `symbol projection failed: ${err?.message ?? String(err)}` };
+	}
+}
+
+
+function applyReplacePreview(content: string, edit: ReplaceEdit): { type: "ok"; content: string } | { type: "skip"; reason: string } {
+	const { old_text, new_text } = edit.replace;
+	if (!old_text.length) return { type: "skip", reason: "replace old_text is empty" };
+	const replacement = replaceText(content, old_text, new_text, {
+		all: edit.replace.all ?? false,
+		fuzzy: edit.replace.fuzzy ?? false,
+	});
+	if (!replacement.count) return { type: "skip", reason: "replace old_text was not found" };
+	return { type: "ok", content: replacement.content };
+}
+
+export function buildPendingWritePreviewData(input: { path?: unknown; content?: unknown }, cwd: string): PendingDiffPreviewResult {
+	if (typeof input.content !== "string") return skip("missing content");
+	if (Buffer.byteLength(input.content, "utf8") > PENDING_DIFF_MAX_BYTES) return skip("content too large");
+	const resolved = resolveWorkspacePreviewPath(input.path, cwd, true);
+	if (resolved.type === "skip") return resolved;
+	const previous = resolved.existed ? readUtf8File(resolved.path) : { type: "ok" as const, content: "" };
+	if (previous.type === "skip") return previous;
+	return buildData(resolved.path, previous.content, input.content, resolved.existed, resolved.existed ? "pending overwrite" : "pending create");
+}
+
+export async function buildPendingEditPreviewData(input: PendingEditInput, cwd: string): Promise<PendingDiffPreviewResult> {
+	const edits = getEdits(input);
+	if (edits.length === 0) return skip("missing edits");
+	const resolved = resolveWorkspacePreviewPath(input.path, cwd, false);
+	if (resolved.type === "skip") return resolved;
+	const previous = readUtf8File(resolved.path);
+	if (previous.type === "skip") return previous;
+	let next = normalizeToLF(previous.content);
+	const anchorBatch: AnchorEdit[] = [];
+
+	for (const edit of edits) {
+		if (isReplaceEdit(edit)) {
+			if (anchorBatch.length > 0) {
+				const anchored = applyAnchoredPreview(next, anchorBatch);
+				if (anchored.type === "skip") return anchored;
+				next = anchored.content;
+				anchorBatch.length = 0;
+			}
+			const projected = applyReplacePreview(next, edit);
+			if (projected.type === "skip") return projected;
+			next = projected.content;
+			continue;
+		}
+		if (isAnchorEdit(edit)) {
+			anchorBatch.push(edit);
+			continue;
+		}
+		if (isReplaceSymbolEdit(edit)) {
+			if (anchorBatch.length > 0) {
+				const anchored = applyAnchoredPreview(next, anchorBatch);
+				if (anchored.type === "skip") return anchored;
+				next = anchored.content;
+				anchorBatch.length = 0;
+			}
+			const projected = await applyReplaceSymbolPreview(resolved.path, next, edit);
+			if (projected.type === "skip") return projected;
+			next = projected.content;
+			continue;
+		}
+		return skip("unsupported edit variant");
+	}
+
+	if (anchorBatch.length > 0) {
+		const anchored = applyAnchoredPreview(next, anchorBatch);
+		if (anchored.type === "skip") return anchored;
+		next = anchored.content;
+	}
+	return buildData(resolved.path, previous.content, next, true, "pending edit");
+}
+
+export interface PendingDiffPreviewCacheSlot<T = PendingDiffPreviewResult> {
+	key?: string;
+	data?: T;
+	pending?: boolean;
+}
+
+export function buildEditPreviewKey(input: PendingEditInput): string | undefined {
+	if (typeof input.path !== "string") return undefined;
+	const edits = getEdits(input);
+	if (edits.length === 0) return undefined;
+	return JSON.stringify({ path: input.path, edits });
+}
+
+export function buildWritePreviewKey(input: { path?: unknown; content?: unknown }): string | undefined {
+	if (typeof input.path !== "string" || typeof input.content !== "string") return undefined;
+	return JSON.stringify({ path: input.path, content: input.content });
+}
+
+export function resolvePendingDiffPreview<T extends PendingDiffPreviewResult>(
+	context: { state?: Record<string, PendingDiffPreviewCacheSlot<T>>; invalidate?: () => void } | undefined,
+	stateKey: string,
+	previewKey: string | undefined,
+	compute: () => T | Promise<T>,
+): T | undefined {
+	if (!previewKey) return undefined;
+	const root = context?.state;
+	if (!root) return undefined;
+	const slot = (root[stateKey] ??= {} as PendingDiffPreviewCacheSlot<T>);
+	if (slot.key !== previewKey) {
+		slot.key = previewKey;
+		slot.data = undefined;
+		slot.pending = false;
+	}
+	if (slot.data !== undefined) return slot.data;
+	if (slot.pending) return undefined;
+
+	let value: T | Promise<T>;
+	try {
+		value = compute();
+	} catch (err: any) {
+		const skipped = { type: "skip", reason: `projection failed: ${err?.message ?? String(err)}` } as T;
+		slot.data = skipped;
+		return skipped;
+	}
+	if (value && typeof (value as any).then === "function") {
+		slot.pending = true;
+		void (value as Promise<T>).then((resolved) => {
+			if (slot.key !== previewKey) return;
+			slot.data = resolved;
+			slot.pending = false;
+			context?.invalidate?.();
+		}).catch((err: any) => {
+			if (slot.key !== previewKey) return;
+			slot.data = { type: "skip", reason: `projection failed: ${err?.message ?? String(err)}` } as T;
+			slot.pending = false;
+			context?.invalidate?.();
+		});
+		return undefined;
+	}
+
+	slot.data = value as T;
+	return slot.data;
+}

package/src/persistent-map-cache.ts

@@ -0,0 +1,251 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import { open, readFile, writeFile as fsWriteFile, mkdir as fsMkdir, rename, readdir, stat, unlink } from "node:fs/promises";
+import xxhashWasm from "xxhash-wasm";
+import type { FileMap } from "./readseek/types.js";
+import { resolveReadseekJsonSettings } from "./readseek-settings.js";
+
+/**
+ * Resolve the on-disk map-cache directory using config precedence:
+ * 1. `PI_HASHLINE_MAP_CACHE_DIR` (when non-empty) — used verbatim.
+ * 2. JSON `mapCache.dir` (when configured).
+ * 3. `$XDG_CACHE_HOME/pi-readseek/maps` (when non-empty).
+ * 4. `~/.cache/pi-readseek/maps`.
+ */
+export function resolveCacheDir(): string {
+  const explicit = process.env.PI_HASHLINE_MAP_CACHE_DIR;
+  if (explicit && explicit.length > 0) return explicit;
+
+  const configured = resolveReadseekJsonSettings().settings.mapCache?.dir;
+  if (configured && configured.length > 0) return configured;
+
+  const xdg = process.env.XDG_CACHE_HOME;
+  if (xdg && xdg.length > 0) return join(xdg, "pi-readseek/maps");
+
+  return join(homedir(), ".cache/pi-readseek/maps");
+}
+
+export function persistenceEnabled(): boolean {
+  if (process.env.PI_HASHLINE_NO_PERSIST_MAPS === "1") return false;
+  const configured = resolveReadseekJsonSettings().settings.mapCache?.enabled;
+  if (configured !== undefined) return configured;
+  return true;
+}
+
+/**
+ * Build a deterministic hex cache key from the five input components.
+ * Uses SHA-256 truncated to 32 hex chars; collision-safe for our purposes
+ * and short enough for readable filenames.
+ */
+export function computeKey(
+  absolutePath: string,
+  mtimeMs: number,
+  contentHash: string,
+  mapperName: string,
+  mapperVersion: number,
+): string {
+  return createHash("sha256")
+    .update(`${absolutePath}\0${mtimeMs}\0${contentHash}\0${mapperName}\0${mapperVersion}`)
+    .digest("hex")
+    .slice(0, 32);
+}
+
+const CONTENT_HASH_WINDOW_BYTES = 64 * 1024;
+
+let xxhashReady: Promise<{ h32Raw: (b: Uint8Array, seed?: number) => number }> | null = null;
+
+function loadXxhash(): Promise<{ h32Raw: (b: Uint8Array, seed?: number) => number }> {
+  if (!xxhashReady) {
+    xxhashReady = xxhashWasm().then((h) => ({ h32Raw: h.h32Raw }));
+  }
+
+  return xxhashReady;
+}
+
+/**
+ * xxHash32 hex digest over the first 64 KB of `absPath`. Returns "" if the
+ * file cannot be opened or read — the caller treats that as a miss.
+ */
+export async function contentHashFor64k(absPath: string): Promise<string> {
+  try {
+    const fh = await open(absPath, "r");
+    try {
+      const buf = Buffer.alloc(CONTENT_HASH_WINDOW_BYTES);
+      const { bytesRead } = await fh.read(buf, 0, CONTENT_HASH_WINDOW_BYTES, 0);
+      const view = buf.subarray(0, bytesRead);
+      const { h32Raw } = await loadXxhash();
+      const n = h32Raw(view, 0) >>> 0;
+      return n.toString(16).padStart(8, "0");
+    } finally {
+      await fh.close();
+    }
+  } catch {
+    return "";
+  }
+}
+
+function keyPath(key: string): string {
+  return join(resolveCacheDir(), `${key}.json`);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function isFileSymbolLike(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  if (typeof value.name !== "string") return false;
+  if (typeof value.kind !== "string") return false;
+  if (typeof value.startLine !== "number") return false;
+  if (typeof value.endLine !== "number") return false;
+  if (value.signature !== undefined && typeof value.signature !== "string") return false;
+  if (value.children !== undefined && (!Array.isArray(value.children) || !value.children.every(isFileSymbolLike))) {
+    return false;
+  }
+  if (value.modifiers !== undefined && !isStringArray(value.modifiers)) return false;
+  if (value.docstring !== undefined && typeof value.docstring !== "string") return false;
+  if (value.isExported !== undefined && typeof value.isExported !== "boolean") return false;
+  return true;
+}
+
+function isTruncatedInfoLike(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  return (
+    typeof value.totalSymbols === "number"
+    && typeof value.shownSymbols === "number"
+    && typeof value.omittedSymbols === "number"
+  );
+}
+
+const DETAIL_LEVELS = new Set(["full", "compact", "minimal", "outline", "truncated"]);
+
+function isFileMap(value: unknown): value is FileMap {
+  if (!isRecord(value)) return false;
+  if (typeof value.path !== "string") return false;
+  if (typeof value.totalLines !== "number") return false;
+  if (typeof value.totalBytes !== "number") return false;
+  if (typeof value.language !== "string") return false;
+  if (!Array.isArray(value.symbols) || !value.symbols.every(isFileSymbolLike)) return false;
+  if (!isStringArray(value.imports)) return false;
+  if (typeof value.detailLevel !== "string" || !DETAIL_LEVELS.has(value.detailLevel)) return false;
+  if (value.truncatedInfo !== undefined && !isTruncatedInfoLike(value.truncatedInfo)) return false;
+  return true;
+}
+
+/** Read a cached FileMap. Returns null on any failure (missing, corrupt, unreadable). */
+export async function readCached(key: string): Promise<FileMap | null> {
+  if (!persistenceEnabled()) return null;
+
+  try {
+    const raw = await readFile(keyPath(key), "utf-8");
+    const parsed: unknown = JSON.parse(raw);
+    return isFileMap(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+async function tryWriteCachedRaw(key: string, map: FileMap): Promise<boolean> {
+  if (!persistenceEnabled()) return false;
+  const dir = resolveCacheDir();
+  const target = join(dir, `${key}.json`);
+  const tmp = join(dir, `${key}.${randomBytes(6).toString("hex")}.tmp`);
+  try {
+    await fsMkdir(dir, { recursive: true });
+    await fsWriteFile(tmp, JSON.stringify(map));
+    await rename(tmp, target);
+    return true;
+  } catch {
+    try {
+      await unlink(tmp);
+    } catch {
+      // ignore temp-file cleanup failures
+    }
+    return false;
+  }
+}
+
+/**
+ * Low-level atomic write. Internal helper (exported so tests can seed fixtures
+ * without going through the eviction counter).
+ */
+export async function writeCachedRaw(key: string, map: FileMap): Promise<void> {
+  await tryWriteCachedRaw(key, map);
+}
+
+const DEFAULT_EVICTION_INTERVAL = 20;
+const DEFAULT_EVICTION_CAP = 5000;
+let writeCounter = 0;
+let evictionInterval = DEFAULT_EVICTION_INTERVAL;
+let evictionCap = DEFAULT_EVICTION_CAP;
+
+export function __setEvictionHooksForTest(
+  hooks: { interval?: number; cap?: number } | null,
+): void {
+  if (hooks === null) {
+    evictionInterval = DEFAULT_EVICTION_INTERVAL;
+    evictionCap = DEFAULT_EVICTION_CAP;
+    return;
+  }
+
+  if (typeof hooks.interval === "number") evictionInterval = hooks.interval;
+  if (typeof hooks.cap === "number") evictionCap = hooks.cap;
+}
+
+const CACHE_KEY_FILE = /^[0-9a-f]{32}\.json$/;
+async function maybeEvict(): Promise<void> {
+  try {
+    const dir = resolveCacheDir();
+    const names = (await readdir(dir)).filter((n) => CACHE_KEY_FILE.test(n));
+    if (names.length <= evictionCap) return;
+
+    const entries: Array<{ path: string; age: number }> = [];
+    for (const name of names) {
+      const path = join(dir, name);
+      try {
+        const s = await stat(path);
+        const age = (s.atimeMs ?? s.mtimeMs) || 0;
+        entries.push({ path, age });
+      } catch {
+        // ignore individual stat failures
+      }
+    }
+
+    entries.sort((a, b) => a.age - b.age);
+    const excess = entries.length - evictionCap;
+    for (let i = 0; i < excess; i += 1) {
+      try {
+        await unlink(entries[i].path);
+      } catch {
+        // ignore individual unlink failures
+      }
+    }
+  } catch {
+    // Swallow eviction errors — never propagate.
+  }
+}
+
+/**
+ * Public atomic write. Counts successful invocations so eviction can trigger lazily.
+ */
+export async function writeCached(key: string, map: FileMap): Promise<void> {
+  if (!(await tryWriteCachedRaw(key, map))) return;
+  writeCounter += 1;
+  if (writeCounter % evictionInterval === 0) {
+    try {
+      await maybeEvict();
+    } catch {
+      // Swallow eviction errors at the call site too.
+    }
+  }
+}
+
+// Test-only: reset the write counter between suites.
+export function __resetWriteCounter(): void {
+  writeCounter = 0;
+}

package/src/read-local-bundle.ts

@@ -0,0 +1,87 @@
+import { SymbolKind } from "./readseek/enums.js";
+import type { SymbolMatch } from "./readseek/symbol-lookup.js";
+import type { FileMap, FileSymbol } from "./readseek/types.js";
+
+export interface LocalBundleSupport {
+  symbol: SymbolMatch;
+  lines: string[];
+}
+
+export interface LocalBundlePlan {
+  requested: SymbolMatch;
+  support: LocalBundleSupport[];
+}
+
+interface FlatSymbol {
+  symbol: FileSymbol;
+  parentName?: string;
+}
+
+const CONTAINER_KINDS = new Set<SymbolKind>([
+  SymbolKind.Class,
+  SymbolKind.Module,
+  SymbolKind.Namespace,
+]);
+
+function flattenSymbols(symbols: FileSymbol[], parentName?: string): FlatSymbol[] {
+  const flattened: FlatSymbol[] = [];
+
+  for (const symbol of symbols) {
+    flattened.push({ symbol, parentName });
+    if (symbol.children?.length) {
+      flattened.push(...flattenSymbols(symbol.children, symbol.name));
+    }
+  }
+
+  return flattened;
+}
+
+export function buildLocalBundle(
+  fileMap: FileMap,
+  requested: SymbolMatch,
+  allLines: string[],
+): LocalBundlePlan | null {
+  const requestedText = allLines.slice(requested.startLine - 1, requested.endLine).join("\n");
+  const identifiers = new Set(requestedText.match(/\b[A-Za-z_][A-Za-z0-9_]*\b/g) ?? []);
+
+  const candidates = flattenSymbols(fileMap.symbols).filter(({ symbol }) => {
+    if (CONTAINER_KINDS.has(symbol.kind as SymbolKind)) return false;
+    return !(symbol.name === requested.name && symbol.startLine === requested.startLine && symbol.endLine === requested.endLine);
+  });
+
+  const symbolsByName = new Map<string, FlatSymbol[]>();
+  for (const candidate of candidates) {
+    const bucket = symbolsByName.get(candidate.symbol.name) ?? [];
+    bucket.push(candidate);
+    symbolsByName.set(candidate.symbol.name, bucket);
+  }
+
+  const support: LocalBundleSupport[] = [];
+  for (const identifier of identifiers) {
+    const matches = symbolsByName.get(identifier) ?? [];
+    if (matches.length === 0) continue;
+    if (matches.length > 1) return null;
+
+    const match = matches[0];
+    support.push({
+      symbol: {
+        name: match.symbol.name,
+        kind: match.symbol.kind,
+        startLine: match.symbol.startLine,
+        endLine: match.symbol.endLine,
+        ...(match.parentName ? { parentName: match.parentName } : {}),
+      },
+      lines: allLines.slice(match.symbol.startLine - 1, match.symbol.endLine),
+    });
+  }
+
+  support.sort((a, b) => {
+    if (a.symbol.startLine !== b.symbol.startLine) return a.symbol.startLine - b.symbol.startLine;
+    return a.symbol.name.localeCompare(b.symbol.name);
+  });
+
+  return {
+    requested,
+    support,
+  };
+}