Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

fix(ingest): index a directory when the build root is a symlink (#154)

Frankie-Xu63421bca5e23
diff --git a/src/ingest/fs.ts b/src/ingest/fs.ts
index 940ff3a0..1f24567d 100644
--- a/src/ingest/fs.ts
+++ b/src/ingest/fs.ts
@@ -2,8 +2,8 @@
* Filesystem walking used by `init`/`check` to enumerate a repo's source files.
*/
import { spawnSync } from "node:child_process";
-import { existsSync, lstatSync, readdirSync, statSync } from "node:fs";
-import { join, relative, resolve } from "node:path";
+import { existsSync, lstatSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
/** Directories that are dependency/build output, never source. */
export const SKIP_DIRS = new Set([
@@ -86,12 +86,80 @@ export interface WalkOptions {
followNestedRepos?: boolean;
}
+/**
+ * Directory `walkDir` actually enumerates.
+ *
+ * `path.resolve` does not follow a symlink, and git discovers the repo from the
+ * child cwd. Unwrap a symlink-to-directory once so the walk runs inside the
+ * target. Ordinary directories stay as `resolve(dir)` — not `realpath` — so a
+ * macOS `/var/folders/…` scratch path is the path the caller handed us.
+ *
+ * A broken symlink throws instead of the `scandir ENOENT` `readdirSync` would
+ * raise after git fails. Internal symlink policy is not decided here.
+ */
+export function canonicalWalkRoot(dir: string): string {
+ const abs = resolve(dir);
+ let st: ReturnType<typeof lstatSync>;
+ try {
+ st = lstatSync(abs);
+ } catch {
+ return abs;
+ }
+ if (!st.isSymbolicLink()) return abs;
+
+ let real: string;
+ try {
+ real = realpathSync(abs);
+ } catch (err) {
+ const code = err && typeof err === "object" && "code" in err ? String((err as NodeJS.ErrnoException).code) : "";
+ if (code === "ELOOP") throw new Error(`symbolic link loop: ${abs}`);
+ throw new Error(`broken symbolic link: ${abs}`);
+ }
+ let realSt: ReturnType<typeof statSync>;
+ try {
+ realSt = statSync(real);
+ } catch {
+ throw new Error(`broken symbolic link: ${abs}`);
+ }
+ if (!realSt.isDirectory()) return abs;
+ return real;
+}
+
+function escapedCanonical(canonical: string, abs: string): boolean {
+ const rel = relative(canonical, abs);
+ return rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+}
+
+/** Keep emitted paths on the requested root so relative paths stay stable. */
+function remapWalkPaths(requested: string, canonical: string, files: string[]): string[] {
+ if (requested === canonical) return files;
+ const out: string[] = [];
+ for (const abs of files) {
+ if (escapedCanonical(canonical, abs)) continue;
+ const rel = relative(canonical, abs);
+ if (rel === "") continue;
+ out.push(join(requested, rel));
+ }
+ return out;
+}
+
+/**
+ * Recursively list source files under `dir`. A directory symlink as the *input
+ * root* is unwrapped once ({@link canonicalWalkRoot}); emitted paths are remapped
+ * onto the caller-facing root so `relPosix` stays `src/foo.ts` rather than a
+ * `../` escape through the physical path (macOS `/tmp` → `/private/tmp`).
+ * Symlinks *inside* the tree are not followed: git still `lstat`s each listed
+ * path, and the filesystem walk still requires `Dirent.isFile` / `isDirectory`.
+ */
export function walkDir(
dir: string,
includes?: ReadonlySet<string>,
opts: WalkOptions = {},
): string[] {
- return gitVisibleFiles(dir, includes, opts) ?? walkFilesystem(dir, includes);
+ const requested = resolve(dir);
+ const root = canonicalWalkRoot(requested);
+ const files = gitVisibleFiles(root, includes, opts) ?? walkFilesystem(root, includes);
+ return remapWalkPaths(requested, root, files);
}
/** Git's canonical working-tree file set, relative to `dir`. Tracked files are
diff --git a/test/graph-root.test.ts b/test/graph-root.test.ts
index 3a116e2a..2f67fc04 100644
--- a/test/graph-root.test.ts
+++ b/test/graph-root.test.ts
@@ -8,8 +8,8 @@
*/
import { test } from "node:test";
import assert from "node:assert/strict";
-import { mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { mkdirSync, symlinkSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
import { nearestGraftRoot, hasGraftIndex } from "../src/graph/root.js";
import { tmpRepo } from "./helpers.js";
@@ -72,3 +72,16 @@ test("an explicit --dir override short-circuits the walk", () => {
// mislead here.
assert.deepEqual(nearestGraftRoot(deep, join(repo, "graft")), { root: deep, levels: 0 });
});
+
+test("a symlink to a built repo is a graft root at the symlink path, not the physical target (#143)", () => {
+ // Query-root walking is not the place we unwrap a build input. existsSync
+ // follows the link, so the index is visible, but the returned root stays the
+ // caller-facing path — the same stability walkDir keeps for emitted files.
+ const repo = builtRepo(tmpRepo("root-symlink-real"));
+ const link = join(tmpRepo("root-symlink-wrap"), "via-link");
+ symlinkSync(repo, link, process.platform === "win32" ? "junction" : "dir");
+
+ assert.ok(hasGraftIndex(link), "the wiring files are visible through the symlink");
+ assert.deepEqual(nearestGraftRoot(link), { root: resolve(link), levels: 0 });
+ assert.notEqual(resolve(link), repo);
+});
diff --git a/test/ingest-fs.test.ts b/test/ingest-fs.test.ts
index c2cd324c..65bfbd74 100644
--- a/test/ingest-fs.test.ts
+++ b/test/ingest-fs.test.ts
@@ -1,9 +1,9 @@
import { execFileSync } from "node:child_process";
import { test } from "node:test";
import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
-import { join, relative } from "node:path";
+import { join, relative, resolve, sep, isAbsolute } from "node:path";
import { shouldSkipDir, walkDir, SKIP_DIRS } from "../src/ingest/fs.js";
import { discoverScopes, discoverWorkspaceChildren } from "../src/graph/scopes.js";
@@ -330,3 +330,124 @@ test("workspace-glob resolution (scopes.ts's resolveGlob over visible-file dirs)
rmSync(dir, { recursive: true, force: true });
}
});
+
+/**
+ * #143 — the *input root* may be a directory symlink (nix-store -devel paths).
+ * Follow that root once. Do not follow symlinks *inside* the tree: that is how
+ * loops and outside-root escapes are prevented, and it keeps git-tracked
+ * symlink files skipped via `lstat`.
+ *
+ * Windows: directory links are junctions so CI does not need Developer Mode.
+ */
+function symlinkDirectory(target: string, path: string): void {
+ symlinkSync(target, path, process.platform === "win32" ? "junction" : "dir");
+}
+
+function underRoot(root: string, abs: string): boolean {
+ const rel = relative(root, abs);
+ return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+test("walkDir indexes a directory when the input root itself is a symlink (#143)", () => {
+ const real = mkdtempSync(join(tmpdir(), "graft-walk-symlink-real-"));
+ const wrap = mkdtempSync(join(tmpdir(), "graft-walk-symlink-wrap-"));
+ const link = join(wrap, "root");
+ try {
+ write(real, "src/app.ts");
+ write(real, "src/util.ts", "export const util = 2;\n");
+ symlinkDirectory(real, link);
+
+ const rels = walked(link);
+ assert.deepEqual(rels, ["src/app.ts", "src/util.ts"]);
+ assert.ok(rels.every((r) => !r.startsWith("..")), "relative paths must stay inside the requested root");
+ for (const abs of walkDir(link)) {
+ assert.ok(underRoot(resolve(link), abs), "emitted paths stay on the caller-facing root, not a leaked realpath");
+ }
+ } finally {
+ rmSync(wrap, { recursive: true, force: true });
+ rmSync(real, { recursive: true, force: true });
+ }
+});
+
+test("walkDir indexes a Git repo when the input root is a symlink to that repo (#143)", () => {
+ const real = fixture("symlink-git-real");
+ const wrap = mkdtempSync(join(tmpdir(), "graft-walk-symlink-gitwrap-"));
+ const link = join(wrap, "root");
+ try {
+ write(real, "src/app.ts");
+ symlinkDirectory(real, link);
+ assert.deepEqual(walked(link), ["src/app.ts"]);
+ } finally {
+ rmSync(wrap, { recursive: true, force: true });
+ rmSync(real, { recursive: true, force: true });
+ }
+});
+
+test("walkDir reports a broken symlink root instead of a generic scandir ENOENT (#143)", (t) => {
+ const wrap = mkdtempSync(join(tmpdir(), "graft-walk-broken-link-"));
+ const link = join(wrap, "root");
+ try {
+ try {
+ symlinkSync(join(wrap, "missing-target"), link, process.platform === "win32" ? "junction" : "dir");
+ } catch (err) {
+ t.skip(`cannot create a dangling directory link (${err instanceof Error ? err.message : err})`);
+ return;
+ }
+ assert.throws(() => walkDir(link), (err: unknown) => {
+ assert.ok(err instanceof Error);
+ assert.match(err.message, /broken symbolic link/i);
+ assert.doesNotMatch(err.message, /scandir/i);
+ return true;
+ });
+ } finally {
+ rmSync(wrap, { recursive: true, force: true });
+ }
+});
+
+test("walkDir does not follow an internal file or directory symlink (#143)", (t) => {
+ const dir = mkdtempSync(join(tmpdir(), "graft-walk-internal-link-"));
+ const outside = mkdtempSync(join(tmpdir(), "graft-walk-outside-"));
+ try {
+ write(dir, "src/app.ts");
+ write(dir, "src/real.ts", "export const real = 1;\n");
+ write(outside, "leaked.ts", "export const leaked = 1;\n");
+ let fileLink = false;
+ try {
+ symlinkSync(join(dir, "src", "real.ts"), join(dir, "src", "alias.ts"));
+ fileLink = true;
+ } catch (err) {
+ t.diagnostic(`skipping internal file-symlink assertion: ${err instanceof Error ? err.message : err}`);
+ }
+ symlinkDirectory(outside, join(dir, "escape"));
+
+ const rels = walked(dir);
+ assert.deepEqual(rels, ["src/app.ts", "src/real.ts"]);
+ if (fileLink) assert.ok(!rels.includes("src/alias.ts"), "an internal file symlink is not a source file");
+ assert.ok(!rels.some((r) => r.includes("leaked.ts")), "a directory symlink must not escape the root");
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ rmSync(outside, { recursive: true, force: true });
+ }
+});
+
+test("walkDir does not recurse forever through an internal symlink to the root (#143)", { timeout: 5_000 }, () => {
+ const dir = mkdtempSync(join(tmpdir(), "graft-walk-loop-"));
+ try {
+ write(dir, "src/app.ts");
+ symlinkDirectory(dir, join(dir, "src", "loop"));
+ assert.deepEqual(walked(dir), ["src/app.ts"]);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("walkDir on an ordinary directory is unchanged when siblings are symlink fixtures (#143)", () => {
+ const dir = mkdtempSync(join(tmpdir(), "graft-walk-ordinary-"));
+ try {
+ write(dir, "src/app.ts");
+ write(dir, "node_modules/pkg/index.ts");
+ assert.deepEqual(walked(dir), ["src/app.ts"]);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});