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.

Add shared filesystem eligibility and immutable snapshots

David Zhang2dabf4b5603b
diff --git a/bun.lock b/bun.lock
index 70e5e0d..41192f9 100644
--- a/bun.lock
+++ b/bun.lock
@@ -32,6 +32,7 @@
"version": "0.0.0",
"dependencies": {
"ai": "7.0.107",
+ "ignore": "7.0.5",
},
"devDependencies": {
"@repo/typescript-config": "workspace:*",
@@ -175,6 +176,8 @@
"fast-wrap-ansi": ["[email protected]", "", { "dependencies": { "fast-string-width": "^3.0.2" } }, "sha512-7F2Fl+TjRSenLqlU3UjSH0iyqopqoZIu7eZVpEirP2g1GtWa2G/ecEmBdgz31+Mxr+ELclgg6sokpSFIQiZ02Q=="],
+ "ignore": ["[email protected]", "", {}, "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg=="],
+
"json-schema": ["[email protected]", "", {}, "sha512-es94M3nTIfsEPisRafak+HDLfHXnKBhV3vU5eqPcS3flIWqcxJWgXHXiey3YrpaNsanY5ei1VoYEbOzijuq9BA=="],
"oxfmt": ["[email protected]", "", { "dependencies": { "tinypool": "2.1.0" }, "optionalDependencies": { "@oxfmt/binding-android-arm-eabi": "0.57.0", "@oxfmt/binding-android-arm64": "0.57.0", "@oxfmt/binding-darwin-arm64": "0.57.0", "@oxfmt/binding-darwin-x64": "0.57.0", "@oxfmt/binding-freebsd-x64": "0.57.0", "@oxfmt/binding-linux-arm-gnueabihf": "0.57.0", "@oxfmt/binding-linux-arm-musleabihf": "0.57.0", "@oxfmt/binding-linux-arm64-gnu": "0.57.0", "@oxfmt/binding-linux-arm64-musl": "0.57.0", "@oxfmt/binding-linux-ppc64-gnu": "0.57.0", "@oxfmt/binding-linux-riscv64-gnu": "0.57.0", "@oxfmt/binding-linux-riscv64-musl": "0.57.0", "@oxfmt/binding-linux-s390x-gnu": "0.57.0", "@oxfmt/binding-linux-x64-gnu": "0.57.0", "@oxfmt/binding-linux-x64-musl": "0.57.0", "@oxfmt/binding-openharmony-arm64": "0.57.0", "@oxfmt/binding-win32-arm64-msvc": "0.57.0", "@oxfmt/binding-win32-ia32-msvc": "0.57.0", "@oxfmt/binding-win32-x64-msvc": "0.57.0" }, "peerDependencies": { "svelte": "^5.0.0", "vite-plus": "*" }, "optionalPeers": ["svelte", "vite-plus"], "bin": { "oxfmt": "bin/oxfmt" } }, "sha512-ZB7Bi+rGDSqmVIo9jwcLyFgjxXvQhDdU+jx+ZrVy6VRiVXK2+CHc4hO3J4dUQjHe7V0ymHB+MDuv5z+NhK07HA=="],
diff --git a/packages/core/package.json b/packages/core/package.json
index 6eb72b4..7241a27 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -11,7 +11,8 @@
"lint": "oxlint src"
},
"dependencies": {
- "ai": "7.0.107"
+ "ai": "7.0.107",
+ "ignore": "7.0.5"
},
"devDependencies": {
"@repo/typescript-config": "workspace:*",
diff --git a/packages/core/src/filesystem.ts b/packages/core/src/filesystem.ts
new file mode 100644
index 0000000..a44842d
--- /dev/null
+++ b/packages/core/src/filesystem.ts
@@ -0,0 +1,432 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants, type BigIntStats, type Dir } from "node:fs";
+import { lstat, open, opendir, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import ignore, { type Ignore } from "ignore";
+
+/** These independent switches broaden only their named exclusion category. */
+export type FilesystemPolicy = {
+ hidden?: boolean;
+ noIgnore?: boolean;
+ includeDependencies?: boolean;
+ includeSensitive?: boolean;
+};
+export type Snapshot = Readonly<{ path: string; contentHash: string; source: string }>;
+export type FilesystemIssue = {
+ kind: "unreadable" | "changed" | "resource_limit" | "interrupted";
+ path: string;
+};
+type Excluded = { status: "excluded"; reason: string };
+type Issue = { status: "issue"; issue: FilesystemIssue };
+export type SnapshotResult = { status: "ok"; snapshot: Snapshot } | Excluded | Issue;
+export type DirectoryEntry = { path: string; kind: "file" | "directory" };
+export type DirectoryPage = {
+ entries: DirectoryEntry[];
+ nextCursor?: string;
+ issues: FilesystemIssue[];
+};
+
+/** Exact default name policy. Dot paths require hidden independently of the other switches. */
+export const filesystemDefaults = Object.freeze({
+ dependencyDirectories: [
+ "node_modules",
+ "vendor",
+ "venv",
+ ".venv",
+ ".tox",
+ "__pycache__",
+ "dist",
+ "build",
+ "coverage",
+ "target",
+ ".next",
+ ".nuxt",
+ ".turbo",
+ ] as readonly string[],
+ sensitiveNames: [
+ "credentials",
+ "credentials.json",
+ "secrets.json",
+ "secrets.yaml",
+ "secrets.yml",
+ "id_rsa",
+ "id_dsa",
+ "id_ecdsa",
+ "id_ed25519",
+ ".netrc",
+ ".npmrc",
+ ".pypirc",
+ ] as readonly string[],
+ sensitiveSuffixes: [".pem", ".key", ".p12", ".pfx"] as readonly string[],
+ pageSize: 128,
+ maxOpenDirectories: 64,
+ maxFileBytes: 16 * 1024 * 1024,
+ maxIgnoreBytes: 1024 * 1024,
+});
+export type FilesystemOptions = {
+ root: string;
+ policy?: FilesystemPolicy;
+ /** Absolute credential/cache locations beyond the default XDG locations. Always excluded. */
+ protectedPaths?: readonly string[];
+ limits?: Partial<
+ Pick<
+ typeof filesystemDefaults,
+ "pageSize" | "maxOpenDirectories" | "maxFileBytes" | "maxIgnoreBytes"
+ >
+ >;
+ signal?: AbortSignal;
+};
+
+type Scope = { directory: string; git?: Ignore; search?: Ignore };
+type Eligible = {
+ status: "eligible";
+ path: string;
+ absolute: string;
+ stat: BigIntStats;
+ ancestors: Array<{ path: string; stat: BigIntStats }>;
+};
+type Eligibility = Eligible | Excluded | Issue;
+type Cursor = { directory: string; handle: Dir; identity: Eligible };
+const excluded = (reason: string): Excluded => ({ status: "excluded", reason });
+const issue = (kind: FilesystemIssue["kind"], path: string): Issue => ({
+ status: "issue",
+ issue: { kind, path },
+});
+function same(a: BigIntStats, b: BigIntStats) {
+ return (
+ a.dev === b.dev &&
+ a.ino === b.ino &&
+ a.size === b.size &&
+ a.mtimeNs === b.mtimeNs &&
+ a.ctimeNs === b.ctimeNs
+ );
+}
+function within(root: string, path: string) {
+ const rel = relative(root, path);
+ return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+function errorKind(error: unknown): FilesystemIssue["kind"] {
+ const code = (error as NodeJS.ErrnoException).code;
+ return code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP" ? "changed" : "unreadable";
+}
+function isSensitive(name: string) {
+ const lower = name.toLowerCase();
+ return (
+ lower === ".env" ||
+ lower.startsWith(".env.") ||
+ filesystemDefaults.sensitiveNames.includes(lower) ||
+ filesystemDefaults.sensitiveSuffixes.some((suffix) => lower.endsWith(suffix))
+ );
+}
+
+/** One invocation-scoped owner for eligibility, metadata reads, enumeration and content snapshots. */
+export async function createFilesystem(options: FilesystemOptions) {
+ const root = await realpath(resolve(options.root));
+ const rootStat = await lstat(root, { bigint: true });
+ if (!rootStat.isDirectory()) throw new Error("Search root must be a directory");
+ const policy = Object.freeze({ ...options.policy });
+ const limits = { ...filesystemDefaults, ...options.limits };
+ for (const name of [
+ "pageSize",
+ "maxOpenDirectories",
+ "maxFileBytes",
+ "maxIgnoreBytes",
+ ] as const) {
+ if (!Number.isSafeInteger(limits[name]) || limits[name] < 1)
+ throw new Error(`Invalid filesystem limit: ${name}`);
+ }
+ const protectedPaths = await Promise.all(
+ [
+ join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "jevgrep"),
+ join(process.env.XDG_CACHE_HOME || join(homedir(), ".cache"), "jevgrep"),
+ ...(options.protectedPaths ?? []),
+ ].map(async (path) => {
+ const absolute = resolve(path);
+ try {
+ return await realpath(absolute);
+ } catch {
+ return absolute;
+ }
+ }),
+ );
+ const cursors = new Map<string, Cursor>();
+ let closed = false;
+ let openingDirectories = 0;
+
+ function pathName(path: string) {
+ if (isAbsolute(path)) return undefined;
+ const absolute = resolve(root, path);
+ return within(root, absolute)
+ ? { absolute, path: relative(root, absolute).split(sep).join("/") }
+ : undefined;
+ }
+ function stopped(path: string): Issue | undefined {
+ return closed || options.signal?.aborted ? issue("interrupted", path) : undefined;
+ }
+ function hardExcluded(path: string) {
+ return (
+ path.split(sep).includes(".git") ||
+ protectedPaths.some((protectedPath) => within(protectedPath, path))
+ );
+ }
+ async function stable(identity: Eligible) {
+ for (const ancestor of identity.ancestors) {
+ const current = await lstat(ancestor.path, { bigint: true });
+ // Child modifications legitimately change a directory's timestamps; its identity must stay fixed.
+ if (
+ !current.isDirectory() ||
+ current.dev !== ancestor.stat.dev ||
+ current.ino !== ancestor.stat.ino
+ )
+ return false;
+ }
+ return (
+ same(identity.stat, await lstat(identity.absolute, { bigint: true })) &&
+ (await realpath(identity.absolute)) === identity.absolute
+ );
+ }
+ async function readBytes(
+ identity: Eligible,
+ ceiling: number,
+ ): Promise<{ status: "ok"; bytes: Buffer } | Issue> {
+ const interrupted = stopped(identity.path);
+ if (interrupted) return interrupted;
+ if (identity.stat.size > BigInt(ceiling)) return issue("resource_limit", identity.path);
+ let handle;
+ try {
+ // NONBLOCK prevents a concurrent replacement with a FIFO from hanging the process.
+ handle = await open(
+ identity.absolute,
+ constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
+ );
+ const before = await handle.stat({ bigint: true });
+ if (!before.isFile() || !same(identity.stat, before)) return issue("changed", identity.path);
+ const chunks: Buffer[] = [];
+ let total = 0;
+ while (true) {
+ const interruption = stopped(identity.path);
+ if (interruption) return interruption;
+ const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, ceiling - total + 1));
+ const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
+ if (!bytesRead) break;
+ total += bytesRead;
+ if (total > ceiling) return issue("resource_limit", identity.path);
+ chunks.push(chunk.subarray(0, bytesRead));
+ }
+ if (!same(before, await handle.stat({ bigint: true })) || !(await stable(identity)))
+ return issue("changed", identity.path);
+ return { status: "ok", bytes: Buffer.concat(chunks, total) };
+ } catch (error) {
+ return issue(errorKind(error), identity.path);
+ } finally {
+ await handle?.close();
+ }
+ }
+ async function ruleFile(directory: string, name: string): Promise<Ignore | Issue | undefined> {
+ const absolute = join(directory, name);
+ try {
+ const stat = await lstat(absolute, { bigint: true });
+ if (!stat.isFile() || stat.isSymbolicLink()) return undefined;
+ const bytes = await readBytes(
+ { status: "eligible", path: relative(root, absolute), absolute, stat, ancestors: [] },
+ limits.maxIgnoreBytes,
+ );
+ if (bytes.status === "issue") return bytes;
+ try {
+ return ignore().add(new TextDecoder("utf-8", { fatal: true }).decode(bytes.bytes));
+ } catch {
+ return issue("unreadable", relative(root, absolute));
+ }
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+ return issue(errorKind(error), relative(root, absolute));
+ }
+ }
+ async function eligibility(input: string): Promise<Eligibility> {
+ const named = pathName(input);
+ if (!named) return excluded("outside_root");
+ const interruption = stopped(named.path);
+ if (interruption) return interruption;
+ if (hardExcluded(named.absolute)) return excluded("protected");
+ const components = named.path ? named.path.split("/") : [];
+ const scopes: Scope[] = [];
+ const ancestors: Eligible["ancestors"] = [];
+ let directory = root;
+ try {
+ const currentRoot = await lstat(root, { bigint: true });
+ if (
+ !currentRoot.isDirectory() ||
+ currentRoot.ino !== rootStat.ino ||
+ currentRoot.dev !== rootStat.dev
+ )
+ return issue("changed", named.path);
+ if (!components.length) return { status: "eligible", ...named, stat: currentRoot, ancestors };
+ ancestors.push({ path: root, stat: currentRoot });
+ for (let index = 0; index < components.length; index++) {
+ if (!policy.noIgnore) {
+ if (directory !== root) {
+ try {
+ const git = await lstat(join(directory, ".git"));
+ if (git.isDirectory() || git.isFile()) for (const scope of scopes) delete scope.git;
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code !== "ENOENT")
+ return issue(errorKind(error), named.path);
+ }
+ }
+ const git = await ruleFile(directory, ".gitignore");
+ if (git && "status" in git) return git;
+ const search = await ruleFile(directory, ".ignore");
+ if (search && "status" in search) return search;
+ scopes.push({ directory, git, search });
+ }
+ const name = components[index]!;
+ const absolute = join(directory, name);
+ if (hardExcluded(absolute)) return excluded("protected");
+ if (!policy.hidden && name.startsWith(".")) return excluded("hidden");
+ if (!policy.includeSensitive && isSensitive(name)) return excluded("sensitive_name");
+ const stat = await lstat(absolute, { bigint: true });
+ if (stat.isSymbolicLink()) return excluded("symlink");
+ if (!stat.isDirectory() && !stat.isFile()) return excluded("special_file");
+ if (
+ stat.isDirectory() &&
+ !policy.includeDependencies &&
+ filesystemDefaults.dependencyDirectories.includes(name)
+ )
+ return excluded("dependency");
+ let ignored = false;
+ for (const scope of scopes) {
+ const candidate =
+ relative(scope.directory, absolute).split(sep).join("/") +
+ (stat.isDirectory() ? "/" : "");
+ for (const matcher of [scope.git, scope.search]) {
+ if (!matcher) continue;
+ const result = matcher.test(candidate);
+ if (result.ignored) ignored = true;
+ else if (result.unignored) ignored = false;
+ }
+ }
+ if (ignored) return excluded("ignored");
+ if (index === components.length - 1)
+ return { status: "eligible", ...named, stat, ancestors };
+ if (!stat.isDirectory()) return excluded("not_directory");
+ ancestors.push({ path: absolute, stat });
+ directory = absolute;
+ }
+ return excluded("outside_root");
+ } catch (error) {
+ return issue(errorKind(error), named.path);
+ }
+ }
+ async function readSnapshot(path: string): Promise<SnapshotResult> {
+ const admitted = await eligibility(path);
+ if (admitted.status !== "eligible") return admitted;
+ if (!admitted.stat.isFile()) return excluded("not_file");
+ const read = await readBytes(admitted, limits.maxFileBytes);
+ if (read.status !== "ok") return read;
+ const current = await eligibility(path);
+ if (current.status !== "eligible") return current;
+ if (!same(admitted.stat, current.stat)) return issue("changed", admitted.path);
+ if (read.bytes.some((byte) => (byte < 32 && ![9, 10, 12, 13].includes(byte)) || byte === 127))
+ return excluded("binary");
+ let source: string;
+ try {
+ source = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(read.bytes);
+ } catch {
+ return excluded("invalid_utf8");
+ }
+ if (!policy.includeSensitive && /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY-----/.test(source))
+ return excluded("private_key");
+ return {
+ status: "ok",
+ snapshot: Object.freeze({
+ path: admitted.path,
+ source,
+ contentHash: createHash("sha256").update(read.bytes).digest("hex"),
+ }),
+ };
+ }
+ async function discard(token: string) {
+ const cursor = cursors.get(token);
+ cursors.delete(token);
+ if (cursor) await cursor.handle.close();
+ }
+ /** Consume a cursor serially; closeCursor releases a deliberately pruned directory without draining it. */
+ async function listPage(path = ".", token?: string): Promise<DirectoryPage> {
+ const entries: DirectoryEntry[] = [];
+ const issues: FilesystemIssue[] = [];
+ const named = pathName(path);
+ if (!named) return { entries, issues };
+ let cursor = token ? cursors.get(token) : undefined;
+ if (token && (!cursor || cursor.directory !== named.path))
+ throw new Error("Invalid directory cursor");
+ try {
+ if (!cursor) {
+ const admitted = await eligibility(path);
+ if (admitted.status === "issue") return { entries, issues: [admitted.issue] };
+ if (admitted.status !== "eligible" || !admitted.stat.isDirectory())
+ return { entries, issues };
+ if (cursors.size + openingDirectories >= limits.maxOpenDirectories)
+ return { entries, issues: [issue("resource_limit", named.path).issue] };
+ openingDirectories++;
+ try {
+ cursor = {
+ directory: named.path,
+ handle: await opendir(admitted.absolute, { bufferSize: limits.pageSize }),
+ identity: admitted,
+ };
+ } finally {
+ openingDirectories--;
+ }
+ if (stopped(named.path)) {
+ await cursor.handle.close();
+ return { entries, issues: [issue("interrupted", named.path).issue] };
+ }
+ token = randomUUID();
+ cursors.set(token, cursor);
+ }
+ if (stopped(named.path) || !(await stable(cursor.identity))) {
+ issues.push(issue(stopped(named.path) ? "interrupted" : "changed", named.path).issue);
+ await discard(token!);
+ return { entries, issues };
+ }
+ for (let scanned = 0; scanned < limits.pageSize; scanned++) {
+ const entry = await cursor.handle.read();
+ if (!entry) {
+ const unchanged = await stable(cursor.identity);
+ await discard(token!);
+ return unchanged
+ ? { entries, issues }
+ : { entries: [], issues: [...issues, issue("changed", named.path).issue] };
+ }
+ const relativePath = named.path ? `${named.path}/${entry.name}` : entry.name;
+ const admitted = await eligibility(relativePath);
+ if (admitted.status === "issue") {
+ issues.push(admitted.issue);
+ if (admitted.issue.kind === "interrupted") {
+ await discard(token!);
+ return { entries, issues };
+ }
+ } else if (admitted.status === "eligible")
+ entries.push({
+ path: relativePath,
+ kind: admitted.stat.isDirectory() ? "directory" : "file",
+ });
+ }
+ if (!(await stable(cursor.identity))) {
+ await discard(token!);
+ return { entries: [], issues: [...issues, issue("changed", named.path).issue] };
+ }
+ return { entries, nextCursor: token, issues };
+ } catch (error) {
+ if (token) await discard(token);
+ return { entries: [], issues: [...issues, issue(errorKind(error), named.path).issue] };
+ }
+ }
+ async function close() {
+ closed = true;
+ await Promise.all([...cursors.keys()].map(discard));
+ }
+ return { root, readSnapshot, listPage, closeCursor: discard, close };
+}
+export type FilesystemReader = Awaited<ReturnType<typeof createFilesystem>>;
diff --git a/packages/core/test/filesystem.test.ts b/packages/core/test/filesystem.test.ts
new file mode 100644
index 0000000..c835bc3
--- /dev/null
+++ b/packages/core/test/filesystem.test.ts
@@ -0,0 +1,340 @@
+import { afterEach, expect, test, spyOn } from "bun:test";
+import { mkdtemp, mkdir, writeFile, rm, symlink, chmod, open, utimes } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createFilesystem } from "../src/filesystem";
+
+const roots: string[] = [];
+afterEach(async () => {
+ await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+async function fixture(files: Record<string, string | Uint8Array>) {
+ const root = await mkdtemp(join(tmpdir(), "jevgrep-filesystem-"));
+ roots.push(root);
+ for (const [path, content] of Object.entries(files)) {
+ await mkdir(join(root, path, ".."), { recursive: true });
+ await writeFile(join(root, path), content);
+ }
+ return root;
+}
+
+test("one reader excludes ignored, hidden, dependent, sensitive and binary content from plain roots", async () => {
+ const root = await fixture({
+ ".gitignore": "ignored.txt\n",
+ "visible.ts": "export const answer = 42;\n",
+ "ignored.txt": "IGNORE_SENTINEL",
+ ".hidden": "HIDDEN_SENTINEL",
+ "node_modules/pkg.js": "DEPENDENCY_SENTINEL",
+ "credentials.json": "SECRET_SENTINEL",
+ "key.txt": "-----BEGIN PRIVATE KEY-----\nSECRET",
+ binary: new Uint8Array([0, 255]),
+ });
+ const reader = await createFilesystem({ root });
+ try {
+ expect(await reader.readSnapshot("visible.ts")).toMatchObject({
+ status: "ok",
+ snapshot: { path: "visible.ts", source: "export const answer = 42;\n" },
+ });
+ for (const path of [
+ "ignored.txt",
+ ".hidden",
+ "node_modules/pkg.js",
+ "credentials.json",
+ "key.txt",
+ "binary",
+ ]) {
+ expect(await reader.readSnapshot(path)).toMatchObject({ status: "excluded" });
+ }
+ } finally {
+ await reader.close();
+ }
+});
+
+test("closer ignore rules and same-scope .ignore overrides apply, while excluded parents cannot be rescued", async () => {
+ const root = await fixture({
+ ".gitignore": "*.txt\nblocked/\n!keep.txt\n",
+ ".ignore": "keep.txt\n!search.txt\n",
+ "keep.txt": "hidden by search rules",
+ "search.txt": "allowed by search rules",
+ "child/.gitignore": "!local.txt\n",
+ "child/local.txt": "local exception",
+ "child/other.txt": "ancestor exclusion",
+ "blocked/.gitignore": "!inside.ts\n",
+ "blocked/inside.ts": "still blocked",
+ "nested/.git": "gitdir: elsewhere",
+ "nested/value.txt": "repository resets git rules",
+ "nested/keep.txt": "search rules remain",
+ });
+ const reader = await createFilesystem({ root });
+ try {
+ for (const path of ["search.txt", "child/local.txt", "nested/value.txt"])
+ expect(await reader.readSnapshot(path)).toMatchObject({ status: "ok" });
+ for (const path of ["keep.txt", "child/other.txt", "blocked/inside.ts", "nested/keep.txt"])
+ expect(await reader.readSnapshot(path)).toMatchObject({
+ status: "excluded",
+ reason: "ignored",
+ });
+ } finally {
+ await reader.close();
+ }
+});
+
+test("pages advance past excluded entries, preserve unusual names, and release completed cursors", async () => {
+ const root = await fixture({
+ ".gitignore": "skip*\n",
+ skip1: "excluded",
+ skip2: "excluded",
+ "a.ts": "a",
+ "line\nbreak.ts": "b",
+ "last.ts": "c",
+ });
+ const reader = await createFilesystem({ root, limits: { pageSize: 1, maxOpenDirectories: 1 } });
+ try {
+ const names: string[] = [];
+ let cursor: string | undefined;
+ do {
+ const page = await reader.listPage(".", cursor);
+ expect(page.issues).toEqual([]);
+ names.push(...page.entries.map((entry) => entry.path));
+ cursor = page.nextCursor;
+ } while (cursor);
+ expect(names.sort()).toEqual(["a.ts", "last.ts", "line\nbreak.ts"]);
+ expect((await reader.listPage()).issues).toEqual([]);
+ } finally {
+ await reader.close();
+ }
+});
+
+test("policy overrides are independent and never admit protected storage or binary bytes", async () => {
+ const root = await fixture({
+ ".gitignore": "plain\n",
+ plain: "ignored",
+ ".env": "secret",
+ "node_modules/a": "dependency",
+ "cache/a": "persisted",
+ ".git/config": "metadata",
+ binary: new Uint8Array([0]),
+ "ordinary.key": "key",
+ "key-source": "-----BEGIN RSA PRIVATE KEY-----\nsecret",
+ });
+ const broad = await createFilesystem({
+ root,
+ protectedPaths: [join(root, "cache")],
+ policy: { hidden: true, noIgnore: true, includeDependencies: true, includeSensitive: true },
+ });
+ try {
+ for (const path of ["plain", ".env", "node_modules/a", "ordinary.key", "key-source"])
+ expect(await broad.readSnapshot(path)).toMatchObject({ status: "ok" });
+ for (const path of ["cache/a", ".git/config", "binary"])
+ expect(await broad.readSnapshot(path)).toMatchObject({ status: "excluded" });
+ } finally {
+ await broad.close();
+ }
+ for (const policy of [
+ { hidden: true },
+ { noIgnore: true },
+ { includeSensitive: true },
+ { includeDependencies: true },
+ ]) {
+ const reader = await createFilesystem({ root, policy });
+ try {
+ expect((await reader.readSnapshot("plain")).status).toBe(
+ "noIgnore" in policy ? "ok" : "excluded",
+ );
+ expect((await reader.readSnapshot("ordinary.key")).status).toBe(
+ "includeSensitive" in policy ? "ok" : "excluded",
+ );
+ expect((await reader.readSnapshot("node_modules/a")).status).toBe(
+ "includeDependencies" in policy ? "ok" : "excluded",
+ );
+ expect((await reader.readSnapshot(".env")).status).toBe("excluded");
+ } finally {
+ await reader.close();
+ }
+ }
+});
+
+test("root normalization does not follow descendant links or special files and permission errors stay issues", async () => {
+ const root = await fixture({ visible: "ok", unreadable: "unreadable sentinel" });
+ const outside = await fixture({ outside: "OUTSIDE_SENTINEL" });
+ await symlink(outside, join(root, "escape"));
+ await symlink(root, join(root, "cycle"));
+ await chmod(join(root, "unreadable"), 0);
+ const fifo = Bun.spawnSync(["mkfifo", join(root, "pipe")]);
+ expect(fifo.exitCode).toBe(0);
+ const reader = await createFilesystem({ root });
+ try {
+ for (const path of [
+ "escape/outside",
+ "cycle/visible",
+ "pipe",
+ "../outside",
+ join(outside, "outside"),
+ ])
+ expect(await reader.readSnapshot(path)).toMatchObject({ status: "excluded" });
+ expect(await reader.readSnapshot("unreadable")).toMatchObject({
+ status: "issue",
+ issue: { kind: "unreadable" },
+ });
+ expect(await reader.readSnapshot("visible")).toMatchObject({ status: "ok" });
+ } finally {
+ await reader.close();
+ }
+});
+
+test("snapshots preserve exact source and change hashes for same-size edits with restored mtime", async () => {
+ const root = await fixture({ "source.ts": "\uFEFFconst x = 1;\r\n" });
+ const reader = await createFilesystem({ root });
+ try {
+ const first = await reader.readSnapshot("source.ts");
+ expect(first).toMatchObject({ status: "ok", snapshot: { source: "\uFEFFconst x = 1;\r\n" } });
+ const handle = await open(join(root, "source.ts"));
+ const before = await handle.stat();
+ await handle.close();
+ await writeFile(join(root, "source.ts"), "\uFEFFconst x = 2;\r\n");
+ await utimes(join(root, "source.ts"), before.atime, before.mtime);
+ const second = await reader.readSnapshot("source.ts");
+ if (first.status !== "ok" || second.status !== "ok")
+ throw new Error("Expected eligible snapshots");
+ expect(second.snapshot.contentHash).not.toBe(first.snapshot.contentHash);
+ expect(first.snapshot.source).toBe("\uFEFFconst x = 1;\r\n");
+ expect(second.snapshot.source).toBe("\uFEFFconst x = 2;\r\n");
+ } finally {
+ await reader.close();
+ }
+});
+
+test("a file changed between OS reads is incomplete and never yields mixed source", async () => {
+ const root = await fixture({ changing: "original bytes" });
+ const probe = await open(join(root, "changing"));
+ const prototype = Object.getPrototypeOf(probe);
+ const originalRead = prototype.read;
+ await probe.close();
+ let injected = false;
+ // Interpose only at the OS-read boundary: a deterministic concurrent writer, not a reader-internal hook.
+ const read = spyOn(prototype, "read").mockImplementation(async function (
+ this: unknown,
+ ...args: unknown[]
+ ) {
+ const result = await originalRead.apply(this, args);
+ if (!injected) {
+ injected = true;
+ await writeFile(join(root, "changing"), "modified bytes");
+ }
+ return result;
+ });
+ const reader = await createFilesystem({ root });
+ try {
+ expect(await reader.readSnapshot("changing")).toMatchObject({
+ status: "issue",
+ issue: { kind: "changed" },
+ });
+ } finally {
+ read.mockRestore();
+ await reader.close();
+ }
+});
+
+test("limits and directory changes are visible issues, and fresh queries observe ignore edits and additions", async () => {
+ const root = await fixture({ one: "12345", "sub/a": "a", ".ignore": "later\n" });
+ const reader = await createFilesystem({
+ root,
+ limits: { pageSize: 1, maxOpenDirectories: 1, maxFileBytes: 4 },
+ });
+ try {
+ expect(await reader.readSnapshot("one")).toMatchObject({
+ status: "issue",
+ issue: { kind: "resource_limit" },
+ });
+ const first = await reader.listPage();
+ expect(first.nextCursor).toBeDefined();
+ expect((await reader.listPage("sub")).issues).toEqual([
+ { kind: "resource_limit", path: "sub" },
+ ]);
+ await writeFile(join(root, "later"), "yes");
+ expect((await reader.listPage(".", first.nextCursor)).issues).toEqual([
+ { kind: "changed", path: "" },
+ ]);
+ expect(await reader.readSnapshot("later")).toMatchObject({
+ status: "excluded",
+ reason: "ignored",
+ });
+ await writeFile(join(root, ".ignore"), "");
+ expect(await reader.readSnapshot("later")).toMatchObject({
+ status: "ok",
+ snapshot: { source: "yes" },
+ });
+ } finally {
+ await reader.close();
+ }
+});
+
+test("protected storage remains excluded when explicit root resolves through its alias", async () => {
+ const store = await fixture({ credential: "NEVER_UPLOAD" });
+ const root = await fixture({});
+ await symlink(store, join(root, "alias"));
+ const reader = await createFilesystem({
+ root: store,
+ protectedPaths: [join(root, "alias")],
+ policy: { hidden: true, noIgnore: true, includeSensitive: true, includeDependencies: true },
+ });
+ try {
+ expect(await reader.readSnapshot("credential")).toMatchObject({
+ status: "excluded",
+ reason: "protected",
+ });
+ } finally {
+ await reader.close();
+ }
+});
+
+test("discarding a pruned directory releases its cursor and cancellation stops subsequent work", async () => {
+ const root = await fixture({ "a/file": "a", "b/file": "b" });
+ const controller = new AbortController();
+ const reader = await createFilesystem({
+ root,
+ signal: controller.signal,
+ limits: { pageSize: 1, maxOpenDirectories: 1 },
+ });
+ try {
+ const a = await reader.listPage("a");
+ expect(a.nextCursor).toBeDefined();
+ await reader.closeCursor(a.nextCursor!);
+ expect((await reader.listPage("b")).issues).toEqual([]);
+ controller.abort();
+ expect(await reader.readSnapshot("a/file")).toMatchObject({
+ status: "issue",
+ issue: { kind: "interrupted" },
+ });
+ } finally {
+ await reader.close();
+ }
+});
+
+test("valid UTF-8 control-byte binary and invalid UTF-8 remain excluded under every override", async () => {
+ const root = await fixture({
+ control: new Uint8Array([1, 2, 3]),
+ invalid: new Uint8Array([255]),
+ plain: "one\ttwo\r\nthree\f",
+ });
+ const reader = await createFilesystem({
+ root,
+ policy: { hidden: true, noIgnore: true, includeDependencies: true, includeSensitive: true },
+ });
+ try {
+ expect(await reader.readSnapshot("control")).toMatchObject({
+ status: "excluded",
+ reason: "binary",
+ });
+ expect(await reader.readSnapshot("invalid")).toMatchObject({
+ status: "excluded",
+ reason: "invalid_utf8",
+ });
+ expect(await reader.readSnapshot("plain")).toMatchObject({
+ status: "ok",
+ snapshot: { source: "one\ttwo\r\nthree\f" },
+ });
+ } finally {
+ await reader.close();
+ }
+});