Find code by asking what it does. A CLI for coding agents that uses Jev to discover relevant files and source context.
TypeScript ai-sdkclaude-codeclicode-searchcodexcoding-agentscontext-retrievaldeveloper-toolsjevsemantic-searchtypescriptvercel-ai-gateway
Add shared filesystem eligibility and immutable snapshots
David Zhang2dabf4b5603b
diff --git a/bun.lock b/bun.lockindex 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.jsonindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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();+ }+});