node:fs: propagate symlink destination errors across sync, callback, and promise APIs

[andrewtdiz]

Summary

Node allows dangling symlink targets, but still reports destination-side symlink creation failures such as a missing destination parent or an existing destination path. Perry's current symlink helper reduces std::os::*::fs::symlink* failures to 0, and the callback/promise wrappers ignore that status, so failed symlink creation can look like success.

This can hide package-manager/workspace link setup failures and leave later code debugging a missing link instead of the original symlink error.

Node behavior

Local Node probe on v25.9.0:

const fs = require("node:fs");
const fsp = require("node:fs/promises");

fs.symlinkSync("missing-target.txt", "dangling-link.txt");
// succeeds: dangling symlinks are allowed

fs.symlinkSync("missing-target.txt", "missing-parent/link.txt");
// throws Error ENOENT, syscall "symlink", path target, dest link path

fs.symlinkSync("missing-target.txt", "existing.txt");
// throws Error EEXIST, syscall "symlink", path target, dest link path

fs.symlink("missing-target.txt", "existing.txt", (err) => {
  console.log(err.code, err.syscall, err.path, err.dest);
});

await fsp.symlink("missing-target.txt", "existing.txt");
// rejects with the same EEXIST / symlink / path / dest shape

Observed shape:

dangling target: succeeds and readlink returns the target string
missing destination parent: Error ENOENT syscall=symlink path=<target> dest=<link>
existing destination: Error EEXIST syscall=symlink path=<target> dest=<link>
callback and promises report/reject with the same fields

Perry evidence from origin/main

crates/perry-runtime/src/fs/mod.rs::js_fs_symlink_sync() returns only a success/failure sentinel:

#[cfg(unix)]
{
    if std::os::unix::fs::symlink(target, path).is_ok() {
        1
    } else {
        0
    }
}
#[cfg(windows)]
{
    if std::os::windows::fs::symlink_file(target, path).is_ok() {
        1
    } else {
        0
    }
}

crates/perry-runtime/src/fs/callbacks.rs::js_fs_symlink_callback() ignores that status and always calls success:

let _ = js_fs_symlink_sync(from_value, to_value);
call_cb0(last_callback(&[arg2, arg3]));

crates/perry-runtime/src/node_submodules/fs_promises.rs::thunk_fs_promises_symlink() also ignores the status and always resolves:

let _ = crate::fs::js_fs_symlink_sync(target, path);
promise_undefined()

The sync path uses the same status-returning helper, so symlink creation failures have no typed error value to throw.

Expected compatibility

• fs.symlinkSync(target, path[, type]) should still allow dangling target values, matching Node.
• It should throw a Node-shaped fs error when creating the link path fails.
• fs.symlink(target, path[, type], cb) should pass that error to the callback.
• fs.promises.symlink(target, path[, type]) should reject with that error.
• Error shape should include at least code, syscall: "symlink", path, and dest.

Suggested test surface

Add deterministic parity tests for:

• dangling target succeeds across sync/callback/promise APIs;
• missing destination parent reports ENOENT across all three forms;
• existing destination reports EEXIST across all three forms;
• successful symlink can be read back with readlink.

Scope / non-goals

• This is limited to symlink creation error propagation and preserving dangling-target success.
• It does not cover hard-link behavior (node:fs: propagate hard-link errors across sync, callback, and promise APIs #2738), readlink errors (node:fs: report readlink errors instead of empty targets #2733), or recursive cp symlink semantics (node:fs: complete cp/cpSync advanced copy semantics #2516).
• It does not require exact platform wording beyond Node-compatible code, syscall, path, and dest fields.

Duplicate check

Searched issues and PRs for:

• fs symlink EEXIST ENOENT
• fs.promises.symlink
• symlinkSync
• fs symlink error

Related but not duplicate: #2516 covers cp / cpSync advanced copy and symlink semantics, and #2738 covers hard-link creation errors.

[andrewtdiz]

I’m taking this as part of a focused node:fs error-propagation PR cut covering readlink, rename, copyFile, link, and symlink across sync, callback, and fs/promises surfaces.

[andrewtdiz]

Opened PR #3490: https://github.com/PerryTS/perry/pull/3490\n\nCoverage in this PR: sync, callback, and node:fs/promises error propagation for the readlink/rename/copyFile/link/symlink cluster, including Node-style err.code, err.syscall, err.path, and err.dest where applicable.\n\nVerified with the focused path-mutator parity fixture, full node-suite fs, full node-suite fs-promises, cargo check, fs runtime unit smoke, fmt, diff whitespace, and file-size checks.