Cross Platform Stability

Cross-Platform Stability 🪟🐧

Urja is engineered to provide identical build outputs on Linux, macOS, and Windows. This is achieved through a multi-layered normalization strategy.

1. Path Normalization Strategy

The most common cause of CI failure in build tools is path separator inconsistency. Urja solves this at the resolver level:

• Canonical Slashes: Every path is converted to forward slashes (/) internally.
• Drive Letter Normalization: Windows drive letters (e.g., C:\) are always lowercased to ensure identical hashes and module IDs regardless of the shell (CMD, PowerShell, or Bash).
• Native Relativization: When calculating relative paths for the dependency graph, Urja temporarily switches back to native separators (using path.sep) to work with the OS's internal logic, then converts back to the canonical format.

2. CI/CD Pipeline

Our GitHub Actions suite ensures stability across both ubuntu-latest and windows-latest:

• Cross-Env Support: We use cross-env for all scripts that set environment variables (like NODE_OPTIONS) to ensure the shell doesn't crash on Windows.
• Snapshot Stability: We run a Snapshot Stability Audit that compares the generated dependency graph against a baseline. Any OS-level discrepancy in filenames or edge connections triggers a pipeline failure.

3. Tooling Compatibility

• npm vs npm.cmd: Our validation scripts dynamically detect the OS and invoke the correct executable for dependency management.
• Rust Native Workers: Pre-compiled binaries are provided for all major architectures, ensuring that the performance gains of Rust are available everywhere.