pi-readcache 0.1.0

package/src/diff.ts

@@ -0,0 +1,130 @@
+import { formatPatch, structuredPatch } from "diff";
+import {
+	MAX_DIFF_FILE_BYTES,
+	MAX_DIFF_FILE_LINES,
+	MAX_DIFF_TO_BASE_RATIO,
+} from "./constants.js";
+
+const PATCH_SEPARATOR_LINE = "===================================================================";
+
+export interface DiffLimits {
+	maxFileBytes: number;
+	maxFileLines: number;
+	maxDiffToBaseRatio: number;
+}
+
+export interface DiffComputation {
+	diffText: string;
+	changedLines: number;
+	addedLines: number;
+	removedLines: number;
+	diffBytes: number;
+}
+
+export const DEFAULT_DIFF_LIMITS: DiffLimits = {
+	maxFileBytes: MAX_DIFF_FILE_BYTES,
+	maxFileLines: MAX_DIFF_FILE_LINES,
+	maxDiffToBaseRatio: MAX_DIFF_TO_BASE_RATIO,
+};
+
+function sanitizePathForPatch(pathDisplay: string): string {
+	const trimmed = pathDisplay.trim();
+	if (!trimmed) {
+		return "unknown";
+	}
+	return trimmed.replace(/[\t\r\n]/g, "_");
+}
+
+function stripPatchSeparator(patch: string): string {
+	const lines = patch.split("\n");
+	if (lines[0] === PATCH_SEPARATOR_LINE) {
+		return lines.slice(1).join("\n").trimEnd();
+	}
+	return patch.trimEnd();
+}
+
+function lineCount(text: string): number {
+	if (text.length === 0) {
+		return 1;
+	}
+	return text.split("\n").length;
+}
+
+function countChangedLinesFromPatch(diffText: string): { added: number; removed: number } {
+	let added = 0;
+	let removed = 0;
+	for (const line of diffText.split("\n")) {
+		if (!line) {
+			continue;
+		}
+		if (line.startsWith("+++") || line.startsWith("---") || line.startsWith("@@")) {
+			continue;
+		}
+		if (line.startsWith("+")) {
+			added += 1;
+			continue;
+		}
+		if (line.startsWith("-")) {
+			removed += 1;
+		}
+	}
+	return { added, removed };
+}
+
+export function computeUnifiedDiff(baseText: string, currentText: string, pathDisplay: string): DiffComputation | undefined {
+	const safePath = sanitizePathForPatch(pathDisplay);
+	const patch = structuredPatch(`a/${safePath}`, `b/${safePath}`, baseText, currentText, "", "", {
+		context: 3,
+	});
+	if (patch.hunks.length === 0) {
+		return undefined;
+	}
+
+	const diffText = stripPatchSeparator(formatPatch(patch));
+	if (!diffText.includes("@@")) {
+		return undefined;
+	}
+
+	const { added, removed } = countChangedLinesFromPatch(diffText);
+	return {
+		diffText,
+		changedLines: Math.max(added, removed),
+		addedLines: added,
+		removedLines: removed,
+		diffBytes: Buffer.byteLength(diffText, "utf-8"),
+	};
+}
+
+export function isDiffUseful(
+	diffText: string,
+	selectedBaseText: string,
+	selectedCurrentText: string,
+	limits: DiffLimits = DEFAULT_DIFF_LIMITS,
+): boolean {
+	if (diffText.trim().length === 0 || !diffText.includes("@@")) {
+		return false;
+	}
+
+	const baseBytes = Buffer.byteLength(selectedBaseText, "utf-8");
+	const currentBytes = Buffer.byteLength(selectedCurrentText, "utf-8");
+	const selectedBytes = Math.max(baseBytes, currentBytes);
+	if (selectedBytes === 0) {
+		return false;
+	}
+
+	if (selectedBytes > limits.maxFileBytes) {
+		return false;
+	}
+
+	const maxLines = Math.max(lineCount(selectedBaseText), lineCount(selectedCurrentText));
+	if (maxLines > limits.maxFileLines) {
+		return false;
+	}
+
+	const diffBytes = Buffer.byteLength(diffText, "utf-8");
+	if (diffBytes === 0) {
+		return false;
+	}
+
+	return diffBytes < selectedBytes * limits.maxDiffToBaseRatio;
+}

package/src/meta.ts

@@ -0,0 +1,222 @@
+import type { SessionEntry } from "@mariozechner/pi-coding-agent";
+import { READCACHE_CUSTOM_TYPE, READCACHE_META_VERSION, SCOPE_FULL } from "./constants.js";
+import type {
+	ReadCacheDebugV1,
+	ReadCacheInvalidationV1,
+	ReadCacheMetaV1,
+	ReadCacheMode,
+	ScopeKey,
+} from "./types.js";
+
+const RANGE_SCOPE_RE = /^r:(\d+):(\d+)$/;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function isPositiveInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+
+function isNonNegativeInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+
+function isReadCacheMode(value: unknown): value is ReadCacheMode {
+	return (
+		value === "full" ||
+		value === "unchanged" ||
+		value === "unchanged_range" ||
+		value === "diff" ||
+		value === "full_fallback"
+	);
+}
+
+function isReadCacheDebugReason(value: unknown): value is ReadCacheDebugV1["reason"] {
+	return (
+		value === "no_base_hash" ||
+		value === "hash_match" ||
+		value === "base_object_missing" ||
+		value === "range_slice_unchanged" ||
+		value === "range_slice_changed" ||
+		value === "diff_file_too_large_bytes" ||
+		value === "diff_file_too_large_lines" ||
+		value === "diff_unavailable_or_empty" ||
+		value === "diff_not_useful" ||
+		value === "diff_payload_truncated" ||
+		value === "diff_emitted"
+	);
+}
+
+function isOptionalBoolean(value: unknown): value is boolean | undefined {
+	return value === undefined || typeof value === "boolean";
+}
+
+function isOptionalPositiveInteger(value: unknown): value is number | undefined {
+	return value === undefined || isPositiveInteger(value);
+}
+
+function isOptionalNonNegativeInteger(value: unknown): value is number | undefined {
+	return value === undefined || isNonNegativeInteger(value);
+}
+
+function isReadCacheDebugV1(value: unknown): value is ReadCacheDebugV1 {
+	if (!isRecord(value)) {
+		return false;
+	}
+
+	if (!isReadCacheDebugReason(value.reason)) {
+		return false;
+	}
+
+	if (value.scope !== "full" && value.scope !== "range") {
+		return false;
+	}
+
+	if (typeof value.baseHashFound !== "boolean" || typeof value.diffAttempted !== "boolean") {
+		return false;
+	}
+
+	return (
+		isOptionalBoolean(value.outsideRangeChanged) &&
+		isOptionalBoolean(value.baseObjectFound) &&
+		isOptionalPositiveInteger(value.largestBytes) &&
+		isOptionalPositiveInteger(value.maxLines) &&
+		isOptionalNonNegativeInteger(value.diffBytes) &&
+		isOptionalNonNegativeInteger(value.diffChangedLines)
+	);
+}
+
+export function isScopeKey(value: unknown): value is ScopeKey {
+	if (value === SCOPE_FULL) {
+		return true;
+	}
+	if (typeof value !== "string") {
+		return false;
+	}
+
+	const match = RANGE_SCOPE_RE.exec(value);
+	if (!match) {
+		return false;
+	}
+
+	const startRaw = match[1];
+	const endRaw = match[2];
+	if (!startRaw || !endRaw) {
+		return false;
+	}
+
+	const start = Number.parseInt(startRaw, 10);
+	const end = Number.parseInt(endRaw, 10);
+	return Number.isInteger(start) && Number.isInteger(end) && start > 0 && end >= start;
+}
+
+export function isReadCacheMetaV1(value: unknown): value is ReadCacheMetaV1 {
+	if (!isRecord(value)) {
+		return false;
+	}
+
+	if (value.v !== READCACHE_META_VERSION) {
+		return false;
+	}
+
+	if (typeof value.pathKey !== "string" || value.pathKey.length === 0) {
+		return false;
+	}
+
+	if (!isScopeKey(value.scopeKey)) {
+		return false;
+	}
+
+	if (typeof value.servedHash !== "string" || value.servedHash.length === 0) {
+		return false;
+	}
+
+	if (!isReadCacheMode(value.mode)) {
+		return false;
+	}
+
+	const requiresBaseHash = value.mode === "unchanged" || value.mode === "unchanged_range" || value.mode === "diff";
+	if (requiresBaseHash) {
+		if (typeof value.baseHash !== "string" || value.baseHash.length === 0) {
+			return false;
+		}
+	} else if (value.baseHash !== undefined && (typeof value.baseHash !== "string" || value.baseHash.length === 0)) {
+		return false;
+	}
+
+	return (
+		isPositiveInteger(value.totalLines) &&
+		isPositiveInteger(value.rangeStart) &&
+		isPositiveInteger(value.rangeEnd) &&
+		value.rangeEnd >= value.rangeStart &&
+		isNonNegativeInteger(value.bytes) &&
+		(value.debug === undefined || isReadCacheDebugV1(value.debug))
+	);
+}
+
+export function isReadCacheInvalidationV1(value: unknown): value is ReadCacheInvalidationV1 {
+	if (!isRecord(value)) {
+		return false;
+	}
+
+	return (
+		value.v === READCACHE_META_VERSION &&
+		value.kind === "invalidate" &&
+		typeof value.pathKey === "string" &&
+		value.pathKey.length > 0 &&
+		isScopeKey(value.scopeKey) &&
+		isPositiveInteger(value.at)
+	);
+}
+
+export function buildReadCacheMetaV1(meta: Omit<ReadCacheMetaV1, "v">): ReadCacheMetaV1 {
+	return {
+		v: READCACHE_META_VERSION,
+		...meta,
+	};
+}
+
+export function buildInvalidationV1(pathKey: string, scopeKey: ScopeKey, at = Date.now()): ReadCacheInvalidationV1 {
+	return {
+		v: READCACHE_META_VERSION,
+		kind: "invalidate",
+		pathKey,
+		scopeKey,
+		at,
+	};
+}
+
+export function extractReadMetaFromSessionEntry(entry: SessionEntry): ReadCacheMetaV1 | undefined {
+	if (entry.type !== "message") {
+		return undefined;
+	}
+
+	const message = entry.message;
+	if (message.role !== "toolResult" || message.toolName !== "read") {
+		return undefined;
+	}
+
+	if (!isRecord(message.details)) {
+		return undefined;
+	}
+
+	const candidate = message.details.readcache;
+	if (!isReadCacheMetaV1(candidate)) {
+		return undefined;
+	}
+
+	return candidate;
+}
+
+export function extractInvalidationFromSessionEntry(entry: SessionEntry): ReadCacheInvalidationV1 | undefined {
+	if (entry.type !== "custom" || entry.customType !== READCACHE_CUSTOM_TYPE) {
+		return undefined;
+	}
+
+	if (!isReadCacheInvalidationV1(entry.data)) {
+		return undefined;
+	}
+
+	return entry.data;
+}

package/src/object-store.ts

@@ -0,0 +1,190 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { access, mkdir, open, readdir, readFile, rename, stat, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { READCACHE_OBJECT_MAX_AGE_MS, READCACHE_OBJECTS_DIR, READCACHE_TMP_DIR } from "./constants.js";
+
+const HASH_HEX_RE = /^[a-f0-9]{64}$/;
+
+export interface ObjectStorePaths {
+	objectsDir: string;
+	tmpDir: string;
+}
+
+export interface PersistObjectResult {
+	hash: string;
+	path: string;
+	written: boolean;
+}
+
+export interface ObjectStoreStats {
+	objects: number;
+	bytes: number;
+}
+
+export interface PruneObjectsResult {
+	scanned: number;
+	deleted: number;
+	cutoffMs: number;
+}
+
+function ensureValidHash(hash: string): void {
+	if (!HASH_HEX_RE.test(hash)) {
+		throw new Error(`Invalid sha256 hash "${hash}".`);
+	}
+}
+
+function isObjectFileName(name: string): boolean {
+	return name.startsWith("sha256-") && name.endsWith(".txt");
+}
+
+export function hashBytes(buffer: Buffer): string {
+	return createHash("sha256").update(buffer).digest("hex");
+}
+
+export function hashText(text: string): string {
+	return hashBytes(Buffer.from(text, "utf-8"));
+}
+
+export function getStorePaths(repoRoot: string): ObjectStorePaths {
+	return {
+		objectsDir: join(repoRoot, READCACHE_OBJECTS_DIR),
+		tmpDir: join(repoRoot, READCACHE_TMP_DIR),
+	};
+}
+
+export function objectPathForHash(repoRoot: string, hash: string): string {
+	ensureValidHash(hash);
+	const { objectsDir } = getStorePaths(repoRoot);
+	return join(objectsDir, `sha256-${hash}.txt`);
+}
+
+export async function ensureStoreDirs(repoRoot: string): Promise<ObjectStorePaths> {
+	const paths = getStorePaths(repoRoot);
+	await mkdir(paths.objectsDir, { recursive: true, mode: 0o700 });
+	await mkdir(paths.tmpDir, { recursive: true, mode: 0o700 });
+	return paths;
+}
+
+async function exists(path: string): Promise<boolean> {
+	try {
+		await access(path, constants.F_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export async function persistObjectIfAbsent(repoRoot: string, hash: string, text: string): Promise<PersistObjectResult> {
+	ensureValidHash(hash);
+	const { tmpDir } = await ensureStoreDirs(repoRoot);
+	const objectPath = objectPathForHash(repoRoot, hash);
+
+	if (await exists(objectPath)) {
+		return { hash, path: objectPath, written: false };
+	}
+
+	const tempPath = join(tmpDir, `sha256-${hash}-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.tmp`);
+	let tempFileCreated = false;
+
+	try {
+		const handle = await open(tempPath, "wx", 0o600);
+		tempFileCreated = true;
+		try {
+			await handle.writeFile(text, "utf-8");
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+
+		await rename(tempPath, objectPath);
+		return { hash, path: objectPath, written: true };
+	} catch (error) {
+		const errorCode = (error as NodeJS.ErrnoException).code;
+		if (errorCode === "EEXIST") {
+			if (tempFileCreated && (await exists(tempPath))) {
+				await unlink(tempPath);
+			}
+			return { hash, path: objectPath, written: false };
+		}
+
+		if (tempFileCreated && (await exists(tempPath))) {
+			await unlink(tempPath);
+		}
+		throw error;
+	}
+}
+
+export async function loadObject(repoRoot: string, hash: string): Promise<string | undefined> {
+	ensureValidHash(hash);
+	const objectPath = objectPathForHash(repoRoot, hash);
+	try {
+		return await readFile(objectPath, "utf-8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			return undefined;
+		}
+		throw error;
+	}
+}
+
+export async function getStoreStats(repoRoot: string): Promise<ObjectStoreStats> {
+	const { objectsDir } = await ensureStoreDirs(repoRoot);
+	const entries = await readdir(objectsDir, { withFileTypes: true });
+
+	let objects = 0;
+	let bytes = 0;
+
+	for (const entry of entries) {
+		if (!entry.isFile() || !isObjectFileName(entry.name)) {
+			continue;
+		}
+		objects += 1;
+		const info = await stat(join(objectsDir, entry.name));
+		bytes += info.size;
+	}
+
+	return { objects, bytes };
+}
+
+export async function pruneObjectsOlderThan(
+	repoRoot: string,
+	maxAgeMs = READCACHE_OBJECT_MAX_AGE_MS,
+	nowMs = Date.now(),
+): Promise<PruneObjectsResult> {
+	if (!Number.isFinite(maxAgeMs) || maxAgeMs < 0) {
+		throw new Error(`Invalid maxAgeMs "${String(maxAgeMs)}".`);
+	}
+
+	const { objectsDir } = await ensureStoreDirs(repoRoot);
+	const entries = await readdir(objectsDir, { withFileTypes: true });
+	const cutoffMs = nowMs - maxAgeMs;
+
+	let scanned = 0;
+	let deleted = 0;
+
+	for (const entry of entries) {
+		if (!entry.isFile() || !isObjectFileName(entry.name)) {
+			continue;
+		}
+		scanned += 1;
+		const filePath = join(objectsDir, entry.name);
+		let info;
+		try {
+			info = await stat(filePath);
+		} catch {
+			continue;
+		}
+		if (info.mtimeMs > cutoffMs) {
+			continue;
+		}
+		try {
+			await unlink(filePath);
+			deleted += 1;
+		} catch {
+			// Fail-open: stale-object pruning must not break extension startup.
+		}
+	}
+
+	return { scanned, deleted, cutoffMs };
+}