Path Normalizer (path-utils.js)

💡 Overview

In cross-platform frameworks, path consistency is critical. On Linux and macOS, file paths are case-sensitive. On Windows (win32), they are case-insensitive, but drive letters can resolve inconsistently (e.g. C:\project vs c:\project).

The path-utils.js utility resolves this inconsistency. It normalizes drive letter cases to ensure cache keys and registry lookups match consistently across platforms.

📊 Normalization Flow

The flowchart below shows how path drive letters are evaluated and normalized:

⚡ Windows Cache Key Issues

Why is drive-letter casing critical for frameworks?

• Require Cache Duplication: Node's internal module loader (require.cache) matches files using their absolute path string as the key. If an import resolves to C:\file.js and another resolves to c:\file.js, Node will compile and cache the module twice, leading to state duplication bugs.
• VFS Matching Mismatches: The virtual filesystem (vfs.js) matches paths using exact string matches. Case mismatches would cause file checks to fail.

⚙️ Complete Code Walkthrough

Below is the full, complete code of path-utils.js:

function normalizePathCase(p) {
  // 1. Check if running on Windows (win32) and starts with a drive letter (e.g. C:)
  if (process.platform === "win32" && typeof p === "string" && p[1] === ":") {
    // 2. Convert drive letter to lowercase: C:\path -> c:\path
    return p.charAt(0).toLowerCase() + p.slice(1);
  }
  
  // 3. Fallback: Return POSIX/Linux path unmodified
  return p;
}

module.exports = {
  normalizePathCase,
};