mkdirp 1.0.4: manual, native, sync

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/mkdirp@1.0.4
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/mkdirp@1.0.4
Demonstrate these symbols/APIs:
  - mkdirp
  - mkdirp.manual
  - mkdirp.native
  - mkdirp.sync

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:e0f8dfcba5e507e080cb9b40da6f576dcd6f9557d84a127b3575430a80772f58","contract":["mkdirp is exported as a callable function with sync, native, and manual methods","mkdirp asynchronously creates nested directories and resolves to the first created path","mkdirp resolves to undefined when the target directory already exists","mkdirp rejects with ENOTDIR when target path collides with an existing file","mkdirp.sync synchronously creates nested directories and returns the first created path","mkdirp.sync returns undefined when the target directory already exists","mkdirp.native asynchronously creates nested directories using native recursive method","mkdirp.manual asynchronously creates nested directories using manual traversal method"],"goal":"verify pkg:npm/mkdirp@1.0.4","kind":"HOW","packages":["pkg:npm/mkdirp@1.0.4"],"schemaVersion":1,"symbols":["mkdirp","mkdirp.manual","mkdirp.native","mkdirp.sync"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/mkdirp@1.0.4"],"schemaVersion":1,"subject":"pkg:npm/mkdirp@1.0.4","symbols":["mkdirp","mkdirp.manual","mkdirp.native","mkdirp.sync"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-mkdirp",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-mkdirp",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "mkdirp": "1.0.4"
      }
    },
    "node_modules/mkdirp": {
      "version": "1.0.4",
      "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-1.0.4.tgz",
      "integrity": "sha512-vVqVZQyf3WLx2Shd0qJ9xuvqgAyKPLAiqITEtqW0oIUjzo3PePDd6fW9iFz30ef7Ysp/oiWqbhszeGWW2T6Gzw==",
      "license": "MIT",
      "bin": {
        "mkdirp": "bin/cmd.js"
      },
      "engines": {
        "node": ">=10"
      }
    }
  }
}

{
  "name": "sample-mkdirp",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room code sample for mkdirp in pkg:npm/mkdirp@1.0.4",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "mkdirp": "1.0.4"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/mkdirp@1.0.4",
  "kind": "HOW",
  "packages": [
    "pkg:npm/mkdirp@1.0.4"
  ],
  "symbols": [
    "mkdirp",
    "mkdirp.manual",
    "mkdirp.native",
    "mkdirp.sync"
  ]
}

const mkdirp = require('mkdirp');

/**
 * Recursively create nested directories asynchronously using default strategy.
 *
 * @param {string} dirPath - Directory path to create.
 * @param {object|number} [options] - Optional mode or configuration options.
 * @returns {Promise<string|undefined>} First directory created or undefined if directory already exists.
 */
async function makeDirectory(dirPath, options) {
  return mkdirp(dirPath, options);
}

/**
 * Recursively create nested directories synchronously.
 *
 * @param {string} dirPath - Directory path to create.
 * @param {object|number} [options] - Optional mode or configuration options.
 * @returns {string|undefined} First directory created or undefined if directory already exists.
 */
function makeDirectorySync(dirPath, options) {
  return mkdirp.sync(dirPath, options);
}

/**
 * Recursively create nested directories asynchronously using Node's native recursive implementation.
 *
 * @param {string} dirPath - Directory path to create.
 * @param {object|number} [options] - Optional mode or configuration options.
 * @returns {Promise<string|undefined>} First directory created or undefined if directory already exists.
 */
async function makeDirectoryNative(dirPath, options) {
  return mkdirp.native(dirPath, options);
}

/**
 * Recursively create nested directories asynchronously using manual path traversal.
 *
 * @param {string} dirPath - Directory path to create.
 * @param {object|number} [options] - Optional mode or configuration options.
 * @returns {Promise<string|undefined>} First directory created or undefined if directory already exists.
 */
async function makeDirectoryManual(dirPath, options) {
  return mkdirp.manual(dirPath, options);
}

module.exports = {
  mkdirp,
  makeDirectory,
  makeDirectorySync,
  makeDirectoryNative,
  makeDirectoryManual
};

import assert from 'node:assert/strict';
import fs from 'node:fs';
import path from 'node:path';
import os from 'node:os';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const {
  mkdirp,
  makeDirectory,
  makeDirectorySync,
  makeDirectoryNative,
  makeDirectoryManual
} = require('../src/index.js');

function createTempDir(prefix) {
  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
}

async function runTests() {
  // 1. mkdirp is exported as a callable function with sync, native, and manual methods
  assert.equal(typeof mkdirp, 'function', 'mkdirp must be exported as a function');
  assert.equal(typeof mkdirp.sync, 'function', 'mkdirp.sync must be a function');
  assert.equal(typeof mkdirp.native, 'function', 'mkdirp.native must be a function');
  assert.equal(typeof mkdirp.manual, 'function', 'mkdirp.manual must be a function');
  assert.equal(typeof makeDirectory, 'function', 'makeDirectory helper must be a function');
  assert.equal(typeof makeDirectorySync, 'function', 'makeDirectorySync helper must be a function');
  assert.equal(typeof makeDirectoryNative, 'function', 'makeDirectoryNative helper must be a function');
  assert.equal(typeof makeDirectoryManual, 'function', 'makeDirectoryManual helper must be a function');

  // 2. mkdirp asynchronously creates nested directories and resolves to the first created path
  {
    const tempDir = createTempDir('csx-mkdirp-async-');
    const targetPath = path.join(tempDir, 'sub1', 'sub2', 'sub3');
    assert.equal(fs.existsSync(targetPath), false, 'Target path must not exist prior to creation');

    const made = await mkdirp(targetPath);
    assert.equal(fs.existsSync(targetPath), true, 'Target directory must exist after mkdirp call');
    assert.equal(typeof made, 'string', 'mkdirp must resolve with string path of first created directory');
    assert.equal(made, path.join(tempDir, 'sub1'), 'mkdirp must return the root-most created directory');

    fs.rmSync(tempDir, { recursive: true, force: true });
  }

  // 3. mkdirp resolves to undefined when the target directory already exists
  {
    const tempDir = createTempDir('csx-mkdirp-exist-');
    const existingDir = path.join(tempDir, 'already-exists');
    fs.mkdirSync(existingDir);

    const made = await makeDirectory(existingDir);
    assert.equal(made, undefined, 'mkdirp must resolve to undefined if directory already exists');

    fs.rmSync(tempDir, { recursive: true, force: true });
  }

  // 4. mkdirp rejects with ENOTDIR when target path collides with an existing file
  {
    const tempDir = createTempDir('csx-mkdirp-conflict-');
    const filePath = path.join(tempDir, 'file.txt');
    fs.writeFileSync(filePath, 'sample content', 'utf8');

    const invalidTargetPath = path.join(filePath, 'sub');
    await assert.rejects(
      async () => {
        await mkdirp(invalidTargetPath);
      },
      (err) => {
        return err && (err.code === 'ENOTDIR' || err.code === 'EEXIST');
      },
      'mkdirp must reject when path component is a regular file'
    );

    fs.rmSync(tempDir, { recursive: true, force: true });
  }

  // 5. mkdirp.sync synchronously creates nested directories and returns the first created path
  {
    const tempDir = createTempDir('csx-mkdirp-sync-');
    const targetPath = path.join(tempDir, 'sync1', 'sync2', 'sync3');
    assert.equal(fs.existsSync(targetPath), false, 'Target path must not exist prior to sync creation');

    const made = mkdirp.sync(targetPath);
    assert.equal(fs.existsSync(targetPath), true, 'Target directory must exist after mkdirp.sync call');
    assert.equal(typeof made, 'string', 'mkdirp.sync must return string path of first created directory');
    assert.equal(made, path.join(tempDir, 'sync1'), 'mkdirp.sync must return root-most created directory');

    fs.rmSync(tempDir, { recursive: true, force: true });
  }

  // 6. mkdirp.sync returns undefined when the target directory already exists
  {
    const tempDir = createTempDir('csx-mkdirp-sync-exist-');
    const existingDir = path.join(tempDir, 'sync-exists');
    fs.mkdirSync(existingDir);

    const made = makeDirectorySync(existingDir);
    assert.equal(made, undefined, 'mkdirp.sync must return undefined if directory already exists');

    fs.rmSync(tempDir, { recursive: true, force: true });
  }

  // 7. mkdirp.native asynchronously creates nested directories using native recursive method
  {
    const tempDir = createTempDir('csx-mkdirp-native-');
    const targetPath = path.join(tempDir, 'nat1', 'nat2', 'nat3');
    assert.equal(fs.existsSync(targetPath), false, 'Target path must not exist prior to native creation');

    const made = await makeDirectoryNative(targetPath);
    assert.equal(fs.existsSync(targetPath), true, 'Target directory must exist after mkdirp.native call');
    assert.equal(typeof made, 'string', 'mkdirp.native must resolve with string path');
    assert.equal(made, path.join(tempDir, 'nat1'), 'mkdirp.native must return root-most created directory');

    fs.rmSync(tempDir, { recursive: true, force: true });
  }

  // 8. mkdirp.manual asynchronously creates nested directories using manual traversal method
  {
    const tempDir = createTempDir('csx-mkdirp-manual-');
    const targetPath = path.join(tempDir, 'man1', 'man2', 'man3');
    assert.equal(fs.existsSync(targetPath), false, 'Target path must not exist prior to manual creation');

    const made = await makeDirectoryManual(targetPath);
    assert.equal(fs.existsSync(targetPath), true, 'Target directory must exist after mkdirp.manual call');
    assert.equal(typeof made, 'string', 'mkdirp.manual must resolve with string path');
    assert.equal(made, path.join(tempDir, 'man1'), 'mkdirp.manual must return root-most created directory');

    fs.rmSync(tempDir, { recursive: true, force: true });
  }

  console.log('All contract assertions for mkdirp passed successfully.');
}

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