fix(targets): use relative symlinks on non-Win

src/cache/targets.ts

@@ -69,7 +69,11 @@ export const applyTargetDir = async (params: TargetParams) => {
 
 	const type = process.platform === "win32" ? "junction" : "dir";
 	try {
-		await deps.symlink(sourceDir, params.targetDir, type);
+		const linkTarget =
+			process.platform === "win32"
+				? sourceDir
+				: path.relative(parentDir, sourceDir);
+		await deps.symlink(linkTarget, params.targetDir, type);
 	} catch (error) {
 		const code = getErrnoCode(error);
 		const fallbackCodes = new Set(["EPERM", "EACCES", "ENOTSUP", "EINVAL"]);

tests/targets.test.js

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { cp, mkdir, readFile, readlink, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { test } from "node:test";
@@ -45,3 +45,28 @@ test("applyTargetDir warns and falls back to copy when symlink fails", async ()
 	assert.equal(data, "hello");
 	assert.match(stderr, /Warning: Failed to create symlink/i);
 });
+
+test("applyTargetDir uses relative symlink targets on non-Windows", async (t) => {
+	if (process.platform === "win32") {
+		t.skip("Relative symlink targets are not used on Windows.");
+	}
+	const tmpRoot = path.join(
+		tmpdir(),
+		`docs-cache-target-relative-${Date.now().toString(36)}`,
+	);
+	const sourceDir = path.join(tmpRoot, "source");
+	const targetDir = path.join(tmpRoot, "target");
+	const parentDir = path.dirname(targetDir);
+
+	await mkdir(sourceDir, { recursive: true });
+	await writeFile(path.join(sourceDir, "README.md"), "hello", "utf8");
+
+	await applyTargetDir({
+		sourceDir,
+		targetDir,
+		mode: "symlink",
+	});
+
+	const linkTarget = await readlink(targetDir);
+	assert.equal(linkTarget, path.relative(parentDir, sourceDir));
+});