@photostructure/fs-metadata 0.4.0 → 0.5.0

package/C++_REVIEW_TODO.md

@@ -0,0 +1,291 @@
+# C++ Code Review TODO List
+
+This document outlines a comprehensive review of all C++ files in the fs-metadata project to identify memory leaks, resource management issues, and API usage improvements.
+
+## Common Patterns to Review
+
+### Memory Management
+- [x] All `malloc`/`free` pairs are properly matched - No malloc/free used, using RAII throughout
+- [x] RAII patterns are used consistently for resource management - Excellent RAII usage across codebase
+- [x] No raw pointers that could leak on exceptions - All resources properly wrapped
+- [x] Smart pointers used appropriately - Consistent use of unique_ptr and custom RAII wrappers
+- [x] All API-allocated resources are properly freed - RAII ensures cleanup
+
+### Platform API Usage
+- [x] Verify API availability for target OS versions - APIs match stated OS requirements
+- [x] Check for deprecated API usage - No deprecated N-API functions found
+- [x] Ensure error handling follows platform conventions - Platform-specific error handling implemented
+- [x] Validate string encoding conversions - UTF-8/wide conversions properly sized
+
+### Security and Input Validation
+- [x] Comprehensive path validation to prevent directory traversal - Added ".." checks to Windows/Darwin hidden.cpp
+- [ ] Input validation for empty/null mount points across all platforms
+- [x] Buffer size constants defined for platform-specific limits - Fixed Windows buffer sizes
+- [ ] Null byte and special character handling in paths
+
+### Thread Safety
+- [x] Replace volatile with std::atomic for thread synchronization - Fixed in drive_status.h
+- [x] Review N-API threadsafe function patterns - All async workers use proper patterns
+- [ ] Document thread safety requirements
+- [x] Ensure proper synchronization in async operations - Using atomic operations with proper memory ordering
+
+## File-by-File Review Checklist
+
+### 1. `src/binding.cpp` ✅
+- [x] Review NAPI memory management patterns - No issues found
+- [x] Check for proper cleanup in async worker lifecycles - Properly managed
+- [x] Verify promise deferred resolution/rejection paths - Correct implementation
+- [x] Validate string conversions between JS and C++ - Using Napi::String correctly
+- [x] **Added**: const-correctness for Napi::Env variables
+- **Platform APIs verified**: Node-API v9 compatibility
+
+### 2. Darwin/macOS Files
+
+#### `src/darwin/volume_metadata.cpp` ✅
+- [x] Verify CFRelease for all CoreFoundation objects - Using CFReleaser RAII wrapper
+  - DADisk objects properly managed with CFReleaser
+  - Disk descriptions properly managed with CFReleaser
+  - DASession objects properly managed with CFReleaser
+- [x] Check DiskArbitration API cleanup - RAII ensures cleanup via CFReleaser
+- [x] Review CFStringToString conversion for memory leaks - No leaks, proper string handling
+- [x] Validate statvfs/statfs error handling - Comprehensive error checking
+- [x] Check overflow protection in size calculations - Excellent overflow protection (lines 91-104)
+- **Platform APIs verified**: 
+  - DiskArbitration framework APIs (macOS 14+) - Proper RAII usage
+  - IOKit framework APIs - Not directly used
+  - CoreFoundation string handling - CFReleaser ensures proper cleanup
+- **Notes**: Exemplary code with proper RAII, overflow protection, and error handling
+
+#### `src/darwin/volume_mount_points.cpp` ✅
+- [x] Review getmntinfo usage and buffer management - Using getmntinfo_r_np with MountBufferRAII
+- [x] Verify CFURLRef lifecycle management - No CFURLRef used in this file
+- [x] Check DADiskCreateFromBSDName cleanup - Not used in this file
+- **Platform APIs verified**:
+  - `getmntinfo_r_np` with MNT_NOWAIT for thread safety
+  - BSD mount structure compatibility - Properly handled
+- **Notes**: Good use of RAII, async/future for timeout handling, and faccessat for security
+
+#### `src/darwin/hidden.cpp` ✅
+- [x] Review NSURL object lifecycle - No NSURL/CFURLRef used, using stat/chflags
+- [x] Check CFURLRef release patterns - Not applicable
+- [x] Verify resource value key handling - Using UF_HIDDEN flag directly
+- **Platform APIs verified**:
+  - File attribute APIs (UF_HIDDEN) - Proper usage with stat/chflags
+  - Path validation implemented (checks for "..")
+- **Notes**: Simple and correct implementation using BSD APIs
+
+### 3. Windows Files
+
+#### `src/windows/volume_metadata.cpp` ✅
+- [x] Review WNetConnection RAII wrapper completeness - **FIXED**: Now handles ERROR_MORE_DATA
+  - Dynamic buffer resize implemented when ERROR_MORE_DATA is returned
+- [x] Check GetVolumeInformation error handling - **FIXED**: Now uses MAX_PATH+1
+  - Using proper VOLUME_NAME_SIZE constant (MAX_PATH+1) for buffers
+- [x] Verify wide string conversion cleanup - Proper PathConverter usage
+- [x] Validate DeviceIoControl buffer management - Not used in this file
+- **Platform APIs verified**:
+  - WNet APIs properly handle ERROR_MORE_DATA
+  - GetVolumeInformation uses correct MAX_PATH+1 buffers
+- **Notes**: All buffer issues resolved, proper RAII patterns throughout
+
+#### `src/windows/volume_mount_points.cpp` ✅
+- [x] Review GetLogicalDrives usage - Proper usage with unique_ptr buffer
+- [x] Check QueryDosDevice buffer allocation - Not used in this file
+- [x] Verify GetVolumePathNamesForVolumeName memory management - Not used in this file
+- **Platform APIs verified**:
+  - GetLogicalDriveStringsW - Proper buffer sizing and iteration
+  - GetVolumeInformationW - Using MAX_PATH+1 correctly
+  - Parallel drive status checking implemented
+- **Notes**: Good implementation with proper buffer management
+
+#### `src/windows/hidden.cpp` ✅
+- [x] Review GetFileAttributes error handling - FileAttributeHandler RAII properly throws on error
+- [x] Check SetFileAttributes validation - Proper error checking with exceptions
+- [x] Verify wide string conversions - PathConverter properly handles UTF-8 to wide
+- [x] **Added**: Path validation for directory traversal (".." check)
+- **Platform APIs verified**:
+  - GetFileAttributesW/SetFileAttributesW - Proper usage with error handling
+  - FILE_ATTRIBUTE_HIDDEN - Correctly manipulated
+- **Notes**: Excellent RAII implementation with FileAttributeHandler, now with path validation
+
+### 4. Linux Files (Completed)
+
+#### `src/linux/volume_metadata.cpp` ✅
+- [x] Review BlkidCache RAII wrapper - Already excellent
+- [x] Check blkid_get_tag_value free() calls - Correctly using free()
+- [x] Verify GIO integration memory management - Proper smart pointers
+- [x] Validate statvfs error handling - Already comprehensive
+- [x] **Added**: Input validation for empty mount points
+- **Platform APIs verified**:
+  - libblkid API availability
+  - GIO optional dependency handling
+  - statvfs behavior
+
+#### `src/linux/blkid_cache.cpp` ✅
+- [x] Verify blkid_cache lifecycle - Already has proper RAII
+- [x] Check error handling for cache operations - Good error handling
+- [x] **Improved**: Double-check pattern in destructor for thread safety
+- [x] **Added**: const-correctness for std::lock_guard instances
+- **Platform APIs verified**:
+  - libblkid cache APIs - Proper use of blkid_get_cache/blkid_put_cache
+
+#### `src/linux/gio_utils.cpp` (if GIO enabled) ✅
+- [x] Review g_object_unref patterns - Already using GioResource RAII
+- [x] Check GError cleanup - Not used in this file (GError-free patterns)
+- [x] Verify GMount/GVolume reference counting - Proper ref/unref pairs
+- [x] **Added**: Exception handling in forEachMount callback
+- [x] **Added**: Null checks for root.get() before G_IS_FILE
+- [x] **Added**: const-correctness for GioResource and callback results
+- **Platform APIs verified**:
+  - GLib/GIO APIs (GNOME) - Proper memory management patterns
+  - GVfs mount integration
+
+#### `src/linux/gio_mount_points.cpp` (if GIO enabled) ✅
+- [x] Review g_volume_monitor lifecycle - Correct usage (singleton pattern)
+- [x] Check GList cleanup patterns - Using g_list_free_full correctly
+- [x] Verify string ownership - Proper GCharPtr smart pointers
+- [x] **Added**: const-correctness for local variables (GCharPtr, GFileInfoPtr, etc.)
+- **Platform APIs verified**:
+  - GVolumeMonitor APIs - Reference counting rules
+  - Mount enumeration
+
+#### `src/linux/gio_volume_metadata.cpp` (if GIO enabled) ✅
+- [x] Review g_drive object management - Using GObjectPtr smart pointers
+- [x] Check g_icon handling - No GIcon usage in this file
+- [x] Verify string ownership - Proper GCharPtr usage
+- [x] **Added**: Defensive null checks for GObjectPtr::get()
+- [x] **Added**: Null checks for string getters
+- [x] **Added**: const-correctness for all GCharPtr and GObjectPtr locals
+- **Platform APIs verified**:
+  - GDrive/GVolume metadata APIs - Ownership transfer rules
+
+## Testing Strategy
+
+### Memory Leak Detection ✅
+1. [x] Run valgrind, LeakSanitizer, and AddressSanitizer on Linux builds
+   - **Implemented**: Comprehensive memory testing infrastructure
+   - Valgrind: `npm run test:valgrind` with suppressions in `.valgrind.supp`
+   - AddressSanitizer: `npm run asan` with proper clang integration
+   - LeakSanitizer: Integrated with ASan, suppressions in `.lsan-suppressions.txt`
+   - All tests show 0 memory leaks in fs-metadata code
+2. [ ] Use Application Verifier on Windows
+3. [ ] Enable address sanitizer for macOS builds
+4. [x] Run existing memory.test.ts with extended iterations
+   - JavaScript memory tests: `npm run test:memory`
+   - Comprehensive suite: `npm run tests:memory`
+
+### API Verification
+1. [ ] Use Perplexity/WebSearch to verify:
+   - Minimum OS version requirements for each API
+   - Deprecated API alternatives
+   - Thread safety guarantees
+   - Memory ownership rules
+2. [ ] Cross-reference with official documentation:
+   - Apple Developer Documentation
+   - Microsoft Win32 API Reference
+   - Linux man pages and library docs
+
+### Resource Management
+1. [ ] Add stress tests for mount/unmount cycles
+2. [ ] Test with network filesystem timeouts
+3. [ ] Verify cleanup on exception paths
+4. [ ] Test with maximum path lengths
+
+## Priority Items
+
+1. ~~**Critical**: Thread safety in Windows DriveHealthChecker (src/windows/drive_status.h)~~ ✅ Completed
+   - ✅ Replaced `volatile bool shouldTerminate` with `std::atomic<bool>`
+   - ✅ Replaced `DriveStatus result` with `std::atomic<DriveStatus>`
+   - ✅ Removed dangerous `TerminateThread` usage
+   - ✅ Increased graceful shutdown timeout from 100ms to 1000ms
+2. ~~**High**: Windows API buffer issues~~ ✅ Completed
+   - ✅ WNetConnection: Handle ERROR_MORE_DATA with dynamic buffer resize
+   - ✅ GetVolumeInformation: Use MAX_PATH+1 instead of BUFFER_SIZE
+3. ~~**High**: CoreFoundation reference counting in macOS code~~ ✅ Completed - CFReleaser RAII wrapper
+4. ~~**High**: GIO object lifecycle management~~ ✅ Completed - Using smart pointers throughout
+5. ~~**Medium**: Security - Add comprehensive path validation~~ ✅ Completed
+   - ✅ Check for ".." in all platforms (Windows/Darwin have it, Linux doesn't have hidden file support)
+   - Validate against null bytes and special characters (remaining)
+   - Add input validation for empty mount points (remaining)
+6. ~~**Medium**: String encoding conversions across platforms~~ ✅ Completed - Proper UTF-8/wide conversions
+7. ~~**Medium**: Buffer overflow protection in size calculations~~ ✅ Completed - Darwin has exemplary protection
+
+### Completed Items
+- ✅ Linux memory management review (all files)
+- ✅ Darwin/macOS memory management review (all files)
+- ✅ Windows memory management review (all files including drive_status.h)
+- ✅ const-correctness improvements across codebase
+- ✅ Memory leak detection infrastructure (Valgrind + ASan)
+- ✅ Static analysis integration (clang-tidy)
+- ✅ Comprehensive memory testing documentation
+- ✅ RAII patterns verified across all platforms
+- ✅ N-API usage verified - no deprecated functions
+- ✅ Platform API compatibility verified
+- ✅ Thread safety issues resolved (std::atomic usage)
+- ✅ Windows API buffer handling fixed
+- ✅ Path validation for directory traversal added
+
+## Recent Improvements (Completed)
+
+### Code Quality
+1. **const-correctness**: Added `const` qualifiers to all appropriate local variables across the codebase
+   - All Napi::Env instances
+   - All GCharPtr, GObjectPtr, GFileInfoPtr instances  
+   - All std::lock_guard instances
+   - Improves code safety and enables compiler optimizations
+
+2. **Static Analysis**: Integrated clang-tidy
+   - Added to CI/CD pipeline
+   - Uses bear to generate compile_commands.json
+   - Runs only on platform-relevant files
+   - Added to precommit checks
+
+3. **Memory Testing Infrastructure**
+   - Created comprehensive memory testing documentation (`docs/MEMORY_TESTING.md`)
+   - Improved ASan configuration with proper suppressions
+   - Created standalone test runner (`scripts/run-asan.sh`)
+   - Updated `scripts/check-memory.mjs` with better ASan support
+   - All memory tests integrated into CI/CD
+
+## Documentation Updates Needed
+
+- [x] Document RAII pattern usage guidelines - See existing code patterns
+- [x] Add platform-specific memory management notes - Added to MEMORY_TESTING.md
+- [x] Create error handling best practices - Documented in code
+- [ ] Document thread safety requirements
+
+## Platform API Resources
+
+### macOS/Darwin
+- Core Foundation Memory Management: Functions with "Create" or "Copy" require CFRelease
+- DiskArbitration: Follows standard Core Foundation ownership rules
+- Key Documentation: Apple Developer Documentation for DiskArbitration framework
+- **Review Status**: ✅ All files use proper RAII with CFReleaser template
+
+### Windows
+- WNetGetConnection: Start with 256 chars, handle ERROR_MORE_DATA
+- GetVolumeInformation: Fixed buffers of MAX_PATH+1
+- Key Documentation: Microsoft Learn Win32 API Reference
+- **Review Status**: ⚠️ Buffer handling needs fixes, thread safety critical issue
+
+### Linux
+- libblkid: Use free() for blkid_get_tag_value results, blkid_put_cache() for cache
+- GLib/GIO: Use g_object_unref() or g_clear_object(), match allocation functions
+- Key Documentation: libblkid man pages, GNOME Developer Documentation
+- **Review Status**: ✅ All files properly reviewed and use smart pointers
+
+## Critical Windows Thread Safety Issue ✅ FIXED
+
+File: `src/windows/drive_status.h`
+```cpp
+// Fixed code:
+std::atomic<bool> shouldTerminate{false};  // Using atomic with proper memory ordering
+std::atomic<DriveStatus> result{DriveStatus::Unknown};  // Thread-safe result storage
+// Removed TerminateThread - now uses graceful shutdown with 1000ms timeout
+```
+
+This critical issue has been resolved:
+- ✅ Race conditions eliminated with std::atomic
+- ✅ Removed dangerous TerminateThread call
+- ✅ Proper memory ordering with acquire/release semantics
+- ✅ Graceful thread shutdown with increased timeout

package/CHANGELOG.md

@@ -14,6 +14,34 @@ Fixed for any bug fixes.
 Security in case of vulnerabilities.
 -->
 
+## [0.5.0] - 2025-06-01
+
+### Added
+
+- Comprehensive memory testing framework with Valgrind and AddressSanitizer support
+- Thread safety tests for Windows platform
+- Platform-specific build scripts with automatic OS detection
+- Clang-tidy integration for C++ code analysis
+
+### Breaking
+
+- Dropped support for Node.js v18, added support for Node.js v24
+
+### Changed
+
+- Simplified ESM/CJS dual module support with unified build configuration
+- Enhanced test coverage with additional error handling and edge case tests
+- Updated all imports to use `node:` prefix for built-in modules
+
+### Fixed
+
+- Added path validation to prevent directory traversal vulnerabilities in hidden file operations
+- Improved error handling and null checks across Linux GIO implementation
+- Fixed buffer allocation issues in Windows networking and volume operations
+- Enhanced resource management with better validation for empty mount points
+- Made `SystemPathPatternsDefault` values visible in TypeScript typings
+- Improved test reliability across different CI environments
+
 ## [0.4.0] - 2025-01-09
 
 - `Fixed`: Switch to thread-safe `getmntinfo_r_np()` for macOS. Improved darwin resource management.
@@ -23,7 +51,7 @@ Security in case of vulnerabilities.
 - `Packaging`: Improved ESM/CJS support with common `__dirname` implementation thanks to `tsup` [shims](https://tsup.egoist.dev/#inject-cjs-and-esm-shims).
 
   This change simplifies the implementation and improves inline jsdocs as the exported code and docs have been inlined.
-  
+
 - `Packaging`: Re-enabled test coverage assertions (after finding the magicks to get istanbul to see what the tests were exercising)
 
 - `Packaging`: Added debuglog tests

package/CLAUDE.md

@@ -0,0 +1,169 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is @photostructure/fs-metadata - a cross-platform native Node.js module for retrieving filesystem metadata, including mount points, volume information, and space utilization statistics.
+
+### Key Features
+- Cross-platform support: Windows 10+ (x64), macOS 14+, Ubuntu 22+ (x64, arm64)
+- Lists all mounted volumes/drives
+- Gets detailed volume metadata (size, usage, filesystem type, etc.)
+- Hidden file/directory attribute support (get/set)
+- Non-blocking async native implementations
+- Timeout handling for unresponsive network volumes
+- ESM and CJS module support
+- Full TypeScript type definitions
+
+### Platform-Specific Notes
+- **Linux**: Optional GIO/GVfs mount support via Gnome libraries
+- **Windows**: Uses separate threads per mountpoint for health checks to handle blocked system calls
+- **System Volumes**: Each platform handles system volumes differently; the library uses heuristics to identify them
+
+## Common Commands
+
+### Build and Development
+```bash
+# Install dependencies and build native modules
+npm install
+
+# Configure platform-specific build settings
+npm run configure
+
+# Build native bindings
+npm run node-gyp-rebuild
+
+# Create prebuilds for distribution  
+npm run prebuild
+
+# Bundle TypeScript to dist/
+npm run bundle
+```
+
+### Testing
+```bash
+# Run all tests with coverage (includes memory tests on Linux)
+npm run tests
+
+# Run CommonJS tests
+npm test cjs
+
+# Run ESM tests
+npm test esm
+
+# Test memory leaks (JavaScript)
+npm run test:memory
+
+# Run valgrind memory analysis (Linux only)
+npm run test:valgrind
+
+# Run comprehensive memory tests (JavaScript + valgrind on Linux)
+npm run tests:memory
+
+# Run AddressSanitizer tests (Linux only)
+npm run asan
+
+# Run a specific test file (no coverage)
+npm test volume_metadata
+```
+
+### Code Quality
+```bash
+# Run ESLint
+npm run lint
+
+# Fix ESLint issues
+npm run lint:fix
+
+# Format code (all formats)
+npm run fmt
+
+# Format C++ code only
+npm run fmt:cpp
+
+# Format TypeScript only
+npm run fmt:ts
+
+# Type checking
+npm run compile
+```
+
+### Pre-commit
+```bash
+# Full precommit check (fmt, clean, prebuild, tests)
+npm run precommit
+```
+
+### Documentation
+```bash
+# Generate API documentation
+npm run docs
+```
+
+## Architecture Overview
+
+### Core Structure
+- **Native binding layer** (`src/binding.cpp`): Node-API v9 bridge between JavaScript and platform-specific implementations
+- **Platform abstractions** in `src/common/`: Shared C++ interfaces for cross-platform functionality
+- **Platform implementations**:
+  - `src/darwin/`: macOS-specific code using Core Foundation APIs
+  - `src/linux/`: Linux-specific code with optional GIO support for GNOME/GVfs
+  - `src/windows/`: Windows-specific code using Win32 APIs
+
+### Key Features
+- **Volume Metadata**: Retrieves filesystem information (mount points, disk usage, health status)
+- **Hidden File Support**: Cross-platform hidden file detection and manipulation
+- **Async Operations**: All native operations use Worker threads to avoid blocking
+
+### Build System
+- Uses `node-gyp` for native compilation
+- Conditionally enables GIO support on Linux via `scripts/configure.mjs`
+- Provides prebuilt binaries via `prebuildify` for common platforms
+- Supports both ESM and CJS module formats
+
+### Testing Strategy
+- Jest for both CJS and ESM test suites
+- Platform-specific test expectations handled via `isWindows`, `isMacOS`, `isLinux` helpers
+- Memory leak testing with garbage collection monitoring
+- Coverage thresholds: 80% for all metrics
+
+### Memory Testing
+- JavaScript memory tests: `npm run test:memory` - uses GC and heap monitoring
+- Valgrind integration: `npm run test:valgrind` - runs on Linux only, checks for memory leaks
+- AddressSanitizer: `npm run asan` - runs on Linux only, detects memory errors and leaks (~2x faster than Valgrind)
+- Comprehensive memory tests: `npm run tests:memory` - runs all memory tests appropriate for the platform
+- Automated test runners: `scripts/valgrind-test.mjs` and `scripts/run-asan.sh`
+- CI/CD includes both valgrind and ASAN tests via `.github/workflows/memory-tests.yml`
+- Cross-platform memory check script: `scripts/check-memory.mjs` handles platform differences
+- Suppression files: `.valgrind.supp` (Valgrind), `.lsan-suppressions.txt` (LeakSanitizer)
+- Memory tests are integrated into `npm run tests` pipeline on Linux
+- See `docs/MEMORY_TESTING.md` for detailed memory testing guide
+
+### Timeout Handling
+- Default timeout for volume operations to handle unresponsive network mounts
+- Windows uses separate threads per mountpoint for health checks
+- Configurable via `Options` interface
+
+### Debug Logging
+- Enable with `NODE_DEBUG=fs-meta` or `NODE_DEBUG=photostructure:fs-metadata`
+- Debug messages from both JavaScript and native code are sent to `stderr`
+- Uses native Node.js debuglog for determining if logging is enabled
+
+## Example Usage
+
+```typescript
+import { getVolumeMountPoints, getVolumeMetadata } from "@photostructure/fs-metadata";
+
+// List all mounted volumes
+const mountPoints = await getVolumeMountPoints();
+console.dir({ mountPoints });
+
+// Get metadata for a specific volume
+const volumeMetadata = await getVolumeMetadata(mountPoints[0]);
+console.dir({ volumeMetadata });
+
+// Check if a file is hidden
+import { isHidden } from "@photostructure/fs-metadata";
+const hidden = await isHidden("/path/to/file");
+```

package/CONTRIBUTING.md

@@ -44,3 +44,28 @@ into account both Windows and POSIX systems.
 - Windows on x64
 - glibc Linux on x64 and arm64, with or without Gnome GIO support
 - MUSL Alpine Linux on x64 and arm64
+
+## Development Gotchas
+
+### Windows Shell Parsing in npm Scripts
+
+**Problem**: npm scripts containing Unix shell operators like `||` with complex commands will fail on Windows with syntax errors like `$' was unexpected at this time.`
+
+**Why**: Windows Command Prompt/PowerShell parses the entire command line before execution, including the Unix-specific parts that would never run on Windows. Even though constructs like `node scripts/is-platform.mjs win32 || <unix-command>` would exit early on Windows, the shell still tries to parse the syntax after `||`.
+
+**Solution**: For platform-specific npm scripts that use shell operators:
+- Create a wrapper Node.js script that handles platform detection internally (see `scripts/clang-tidy.mjs`)
+- The wrapper can use `process.platform` or `os.platform()` to detect Windows and exit early
+- Unix-specific commands can then be spawned using `child_process.spawn()` with `sh -c`
+
+**Example**: The `clang-tidy` npm script was moved from:
+```json
+"clang-tidy": "node scripts/is-platform.mjs win32 || (npm run configure && bear -- npm run node-gyp-rebuild && find src -name '*.cpp' -o -name '*.h' | grep -E '\\.(cpp|h)$' | grep -v -E '(windows|darwin)/' | xargs clang-tidy)"
+```
+
+To:
+```json
+"clang-tidy": "node scripts/clang-tidy.mjs"
+```
+
+Where the script handles platform detection and command execution internally.