fs.realpath 1.0.0: realpathSync

audit=false
fund=false
update-notifier=false

# CSX Sample Notes: fs.realpath.realpathSync canonical resolution and symlink handling

## 1. Search Result
`search_known_solution` returned `NO_SAFE_MATCH` for `verify fs.realpath.realpathSync in pkg:npm/fs.realpath@1.0.0`. Existing samples cover general `fs.realpath` verification, while this sample specifically verifies synchronous canonical resolution, multi-hop symlink traversal, cache handling, and error contracts for `fs.realpath.realpathSync`.

## 2. What a Model Would Have Written
A naive model would:
1. Use `import { realpathSync } from 'fs.realpath'`, which resolves to `undefined` in Node ESM because `fs.realpath` exports a function via `module.exports = realpath` rather than named ESM exports.
2. Hardcode platform-dependent absolute paths in assertions or test fixtures instead of dynamically creating isolated temporary directories.
3. Assume `realpathSync` returns null or undefined on non-existent paths instead of throwing `ENOENT`.

## 3. How the Wrong Version Fails
1. Direct named import `import { realpathSync } from 'fs.realpath'` fails with `TypeError: realpathSync is not a function`.
2. Hardcoding `/tmp` or fixed paths causes test failures on systems where `os.tmpdir()` points elsewhere or fails leakage detection.
3. Expecting non-existent paths to return `null` directly from `realpathSync` fails because Node throws an `ENOENT` error synchronously.

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify fs.realpath.realpathSync in pkg:npm/fs.realpath@1.0.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/fs.realpath@1.0.0
Demonstrate these symbols/APIs:
  - fs.realpath.realpathSync

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:4e78555f02298d722783d4bc495c2f9697611fd1b20bd0f6453d2578574c2b5f","constraints":{"executionContext":"node"},"contract":["fs.realpath.realpathSync resolves an existing canonical file to its absolute path","fs.realpath.realpathSync resolves single and multi-hop symlinks to their ultimate target path","fs.realpath.realpathSync accepts an optional cache mapping object","fs.realpath.realpathSync throws an ENOENT error when target path does not exist","fs.realpath.realpathSync is exported directly as realpathSync and aliased as sync on fs.realpath","safeResolvePath returns canonical path for existing target and null for non-existent target"],"goal":"verify fs.realpath.realpathSync in pkg:npm/fs.realpath@1.0.0","kind":"HOW","packages":["pkg:npm/fs.realpath@1.0.0"],"schemaVersion":1,"symbols":["fs.realpath.realpathSync"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/fs.realpath@1.0.0"],"schemaVersion":1,"subject":"pkg:npm/fs.realpath@1.0.0","symbols":["fs.realpath.realpathSync"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-fs-realpath-sync",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-fs-realpath-sync",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "fs.realpath": "1.0.0"
      }
    },
    "node_modules/fs.realpath": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz",
      "integrity": "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==",
      "license": "ISC"
    }
  }
}

{
  "name": "sample-fs-realpath-sync",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "fs.realpath": "1.0.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify fs.realpath.realpathSync in pkg:npm/fs.realpath@1.0.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/fs.realpath@1.0.0"
  ],
  "symbols": [
    "fs.realpath.realpathSync"
  ]
}

import realpathPkg from 'fs.realpath';

const { realpathSync, sync } = realpathPkg;

/**
 * Resolves a given path to its canonical absolute path synchronously.
 *
 * @param {string} targetPath - Path to resolve.
 * @param {object} [cache] - Optional cache object.
 * @returns {string} The canonical absolute path.
 */
export function resolveCanonicalPath(targetPath, cache) {
  return realpathSync(targetPath, cache);
}

/**
 * Resolves a path using the sync alias.
 *
 * @param {string} targetPath - Path to resolve.
 * @param {object} [cache] - Optional cache object.
 * @returns {string} The canonical absolute path.
 */
export function resolveUsingSyncAlias(targetPath, cache) {
  return sync(targetPath, cache);
}

/**
 * Safely resolves a path, returning null if ENOENT is thrown.
 *
 * @param {string} targetPath - Path to resolve.
 * @returns {string|null} The canonical path, or null if non-existent.
 */
export function safeResolvePath(targetPath) {
  try {
    return realpathSync(targetPath);
  } catch (err) {
    if (err && err.code === 'ENOENT') {
      return null;
    }
    throw err;
  }
}

import assert from 'node:assert/strict';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import realpathPkg from 'fs.realpath';
import {
  resolveCanonicalPath,
  resolveUsingSyncAlias,
  safeResolvePath
} from '../src/index.mjs';

const { realpathSync, sync } = realpathPkg;

const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'csx-fs-realpath-sync-'));

try {
  const targetFile = path.join(tmpDir, 'target.txt');
  fs.writeFileSync(targetFile, 'content');
  const linkFile1 = path.join(tmpDir, 'link1.txt');
  fs.symlinkSync(targetFile, linkFile1);
  const linkFile2 = path.join(tmpDir, 'link2.txt');
  fs.symlinkSync(linkFile1, linkFile2);

  const subDir = path.join(tmpDir, 'nested');
  fs.mkdirSync(subDir);
  const subFile = path.join(subDir, 'inner.txt');
  fs.writeFileSync(subFile, 'inner-content');
  const subLink = path.join(tmpDir, 'nested-link');
  fs.symlinkSync(subDir, subLink);

  // 1. fs.realpath.realpathSync resolves an existing canonical file to its absolute path
  {
    const resolved = realpathSync(targetFile);
    assert.equal(typeof resolved, 'string');
    assert.equal(resolved, fs.realpathSync(targetFile));
    assert.equal(resolveCanonicalPath(targetFile), resolved);
  }

  // 2. fs.realpath.realpathSync resolves single and multi-hop symlinks to their ultimate target path
  {
    const resolvedLink1 = realpathSync(linkFile1);
    const resolvedLink2 = realpathSync(linkFile2);
    const resolvedTarget = realpathSync(targetFile);
    assert.equal(resolvedLink1, resolvedTarget);
    assert.equal(resolvedLink2, resolvedTarget);

    const resolvedNested = realpathSync(path.join(subLink, 'inner.txt'));
    assert.equal(resolvedNested, realpathSync(subFile));
  }

  // 3. fs.realpath.realpathSync accepts an optional cache mapping object
  {
    const cache = {};
    const resolvedWithCache = realpathSync(targetFile, cache);
    assert.equal(resolvedWithCache, realpathSync(targetFile));
    assert.equal(resolveCanonicalPath(targetFile, cache), resolvedWithCache);
  }

  // 4. fs.realpath.realpathSync throws an ENOENT error when target path does not exist
  {
    const nonExistent = path.join(tmpDir, 'non-existent-file.txt');
    assert.throws(
      () => {
        realpathSync(nonExistent);
      },
      (err) => {
        return err && err.code === 'ENOENT';
      }
    );
  }

  // 5. fs.realpath.realpathSync is exported directly as realpathSync and aliased as sync on fs.realpath
  {
    assert.equal(typeof realpathPkg.realpathSync, 'function');
    assert.equal(typeof realpathPkg.sync, 'function');
    assert.equal(realpathPkg.realpathSync, realpathPkg.sync);
    assert.equal(sync(targetFile), realpathSync(targetFile));
    assert.equal(resolveUsingSyncAlias(targetFile), realpathSync(targetFile));
  }

  // 6. safeResolvePath returns canonical path for existing target and null for non-existent target
  {
    const resolved = safeResolvePath(targetFile);
    assert.equal(resolved, realpathSync(targetFile));

    const nonExistent = path.join(tmpDir, 'does-not-exist.txt');
    const resultNonExistent = safeResolvePath(nonExistent);
    assert.equal(resultNonExistent, null);
  }
} finally {
  fs.rmSync(tmpDir, { recursive: true, force: true });
}