fs.realpath 1.0.0: realpath, realpathSync

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 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:
  - 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:93b33461520a713cd642ceef8f287ec42dc807b5e62c06278f774273830d5961","contract":["fs.realpath.realpath asynchronously resolves canonical absolute path for existing files and symlinks via callback","fs.realpath.realpathSync synchronously resolves canonical absolute path for existing files and symlinks","fs.realpath.realpath returns ENOENT error for non-existent path in callback","fs.realpath.realpathSync throws ENOENT error for non-existent path","fs.realpath exports realpath and realpathSync functions matching fs module interface"],"goal":"verify pkg:npm/fs.realpath@1.0.0","kind":"HOW","packages":["pkg:npm/fs.realpath@1.0.0"],"schemaVersion":1,"symbols":["realpath","realpathSync"]},"contractCommand":["node","test/contract.cjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","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":["realpath","realpathSync"],"verifierAdapter":"node-typescript@1"}

'use strict';

const fsRealPath = require('fs.realpath');

function resolvePathAsync(targetPath) {
  return new Promise((resolve, reject) => {
    fsRealPath.realpath(targetPath, (err, resolved) => {
      if (err) {
        return reject(err);
      }
      resolve(resolved);
    });
  });
}

function resolvePathSync(targetPath) {
  return fsRealPath.realpathSync(targetPath);
}

module.exports = {
  resolvePathAsync,
  resolvePathSync,
  fsRealPath
};

{
  "name": "sample-fs-realpath",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-fs-realpath",
      "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",
  "version": "1.0.0",
  "private": true,
  "description": "verify pkg:npm/fs.realpath@1.0.0",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.cjs"
  },
  "dependencies": {
    "fs.realpath": "1.0.0"
  },
  "license": "MIT-0"
}

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

'use strict';

const assert = require('assert');
const fs = require('fs');
const path = require('path');
const os = require('os');
const fsRealPath = require('fs.realpath');
const { resolvePathAsync, resolvePathSync } = require('../index.js');

async function run() {
  const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), 'csx-realpath-'));
  // Ensure the base directory path itself is canonicalized
  const tmpDir = fs.realpathSync(tmpBase);

  const targetFile = path.join(tmpDir, 'target.txt');
  const targetDir = path.join(tmpDir, 'subfolder');
  const fileInSubDir = path.join(targetDir, 'nested.txt');

  const fileSymlink = path.join(tmpDir, 'file-link.txt');
  const dirSymlink = path.join(tmpDir, 'dir-link');
  const missingPath = path.join(tmpDir, 'non-existent-file.txt');

  try {
    fs.writeFileSync(targetFile, 'fs.realpath test content', 'utf8');
    fs.mkdirSync(targetDir, { recursive: true });
    fs.writeFileSync(fileInSubDir, 'nested content', 'utf8');

    fs.symlinkSync(targetFile, fileSymlink);
    fs.symlinkSync(targetDir, dirSymlink);

    // 1. Asynchronous realpath with callback
    await new Promise((resolve, reject) => {
      fsRealPath.realpath(fileSymlink, (err, resolved) => {
        if (err) return reject(err);
        try {
          assert.strictEqual(resolved, targetFile, 'fs.realpath callback must resolve symlink to target file');
          resolve();
        } catch (e) {
          reject(e);
        }
      });
    });

    // 2. Asynchronous realpath on non-existent path
    await new Promise((resolve, reject) => {
      fsRealPath.realpath(missingPath, (err, resolved) => {
        try {
          assert.ok(err, 'fs.realpath must yield an error for non-existent path');
          assert.strictEqual(err.code, 'ENOENT', 'error code must be ENOENT');
          assert.strictEqual(resolved, undefined, 'resolved path must be undefined on error');
          resolve();
        } catch (e) {
          reject(e);
        }
      });
    });

    // 3. Synchronous realpathSync
    const resolvedFileSync = fsRealPath.realpathSync(fileSymlink);
    assert.strictEqual(resolvedFileSync, targetFile, 'fs.realpathSync must resolve symlink to target file');

    const resolvedDirSync = fsRealPath.realpathSync(dirSymlink);
    assert.strictEqual(resolvedDirSync, targetDir, 'fs.realpathSync must resolve directory symlink to target directory');

    // 4. Synchronous realpathSync on non-existent path
    assert.throws(
      () => {
        fsRealPath.realpathSync(missingPath);
      },
      (err) => {
        return err && err.code === 'ENOENT';
      },
      'fs.realpathSync must throw ENOENT error for non-existent path'
    );

    // 5. Helper functions from index.js
    const helperResolved = await resolvePathAsync(fileSymlink);
    assert.strictEqual(helperResolved, targetFile, 'resolvePathAsync must resolve symlink to target file');

    const helperResolvedSync = resolvePathSync(dirSymlink);
    assert.strictEqual(helperResolvedSync, targetDir, 'resolvePathSync must resolve directory symlink');

    // 6. Aliases and interface checks
    assert.strictEqual(typeof fsRealPath, 'function', 'fsRealPath itself must be callable');
    assert.strictEqual(typeof fsRealPath.realpath, 'function', 'fsRealPath.realpath must be a function');
    assert.strictEqual(typeof fsRealPath.realpathSync, 'function', 'fsRealPath.realpathSync must be a function');
    assert.strictEqual(typeof fsRealPath.sync, 'function', 'fsRealPath.sync alias must be a function');
    assert.strictEqual(typeof fsRealPath.monkeypatch, 'function', 'fsRealPath.monkeypatch must be a function');
    assert.strictEqual(typeof fsRealPath.unmonkeypatch, 'function', 'fsRealPath.unmonkeypatch must be a function');

    console.log('Contract tests passed successfully.');
    process.exit(0);
  } finally {
    try {
      if (fs.existsSync(tmpBase)) {
        fs.rmSync(tmpBase, { recursive: true, force: true });
      }
    } catch (e) {
      // Ignore cleanup error
    }
  }
}

run().catch((err) => {
  console.error('Contract test failed:', err);
  process.exit(1);
});