@photostructure/fs-metadata 0.4.0 → 0.5.1

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/sanitizers-test.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,43 @@ Fixed for any bug fixes.
 Security in case of vulnerabilities.
 -->
 
+## [0.6.0] - 2025-06-09
+
+### 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
+- Worker thread helper for volume metadata operations
+- NAPI_VERSION=9 definition for improved compatibility
+- Dynamic test timeout configuration based on environment (CI, platform, architecture)
+- Prebuild script for Linux GLIBC compatibility in Docker environments
+
+### 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
+- Reorganized build and test scripts for better clarity
+- Improved memory test workflow for cross-platform compatibility
+- Renamed native module target from `node_fs_meta` to `fs_metadata` for consistency
+
+### 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
+- Added Napi::HandleScope to OnOK and OnError methods for proper scope management
+- Removed unnecessary std::move operations in worker implementations
+- Resolved CI test reliability issues across different environments, particularly Alpine ARM64 emulation timeouts
+
 ## [0.4.0] - 2025-01-09
 
 - `Fixed`: Switch to thread-safe `getmntinfo_r_np()` for macOS. Improved darwin resource management.
@@ -23,7 +60,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,346 @@
+# 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
+- Worker threads support with proper context isolation
+
+### 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
+
+## 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
+
+### Cross-Module Compatibility
+- **Directory Path Resolution**: Use `_dirname()` from `./dirname` instead of `__dirname`
+  - Works in both CommonJS and ESM contexts
+  - Handles Jest test environments correctly
+  - Example: `const dir = _dirname()` instead of `const dir = __dirname`
+
+### 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
+
+### Testing File System Metadata
+- **Important**: File system metadata like `available` space, `used` space, and other dynamic properties change continuously as other processes run on the machine
+- Tests should **never** expect exact equality for these values between multiple calls
+- **Do not** make range assertions (e.g., `available > 0` or `used < size`) because:
+  - Files can be created or deleted between calls (potentially gigabytes)
+  - The changes can be dramatic and unpredictable
+- Instead, for dynamic metadata:
+  - Only verify the value exists and has the correct type
+  - Use `typeof result.available === 'number'` rather than range checks
+  - Focus on testing static properties (e.g., `size`, `mountFrom`, `fstype`) for exact equality
+  - Consider using snapshot testing only for stable properties
+
+### 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");
+```
+
+## CI/CD Test Reliability Guidelines
+
+Based on analysis of recent test failures, here are critical patterns to avoid flaky tests:
+
+### 1. Benchmark and Performance Tests
+- **Problem**: "Cannot log after tests are done" errors in worker_threads.test.ts
+- **Solution**: 
+  - Always await all async operations before test completion
+  - Use proper test lifecycle hooks (afterEach/afterAll) for cleanup
+  - Avoid console.log in async contexts without proper synchronization
+  - Consider using test.concurrent with explicit done() callbacks
+
+### 2. Alpine Linux ARM64 Issues
+- **Problem**: Tests timeout on emulated Alpine ARM64 environments
+- **Solution**:
+  - Skip process-spawning tests on Alpine ARM64 (`if (isAlpine && isARM64)`)
+  - Use increased timeout multipliers (20x) for emulated environments
+  - Detect emulation via `/proc/cpuinfo` or environment checks
+  - Consider separate test suites for native vs emulated environments
+
+### 3. Worker Thread Management
+- **Problem**: Race conditions in concurrent worker operations
+- **Solution**:
+  - Implement proper worker pool management with size limits
+  - Use Promise.allSettled() instead of Promise.all() for parallel operations
+  - Add explicit cleanup in test teardown to terminate all workers
+  - Set reasonable concurrency limits based on environment (CPU cores)
+
+### 4. Timeout Test Reliability
+- **Problem**: Timeout tests fail due to timing precision issues
+- **Solution**:
+  - Never use exact timing assertions (e.g., expect 100ms)
+  - Use ranges with adequate margins (e.g., 90-110ms)
+  - Account for CI environment variability (slower machines)
+  - Consider mocking timers for deterministic behavior
+
+### 5. File System Operations
+- **Problem**: ENOENT errors for test directories, permission issues
+- **Solution**:
+  - Always use unique temporary directories per test
+  - Clean up test artifacts in afterEach hooks
+  - Check directory existence before operations
+  - Handle platform-specific path separators
+
+### 6. Memory and Resource Leaks
+- **Problem**: Tests don't properly clean up resources
+- **Solution**:
+  - Explicitly close all file handles, network connections
+  - Use try-finally blocks for resource cleanup
+  - Monitor memory usage in long-running tests
+  - Implement proper garbage collection triggers
+
+### 7. Platform-Specific Failures
+- **Problem**: Different behavior across Windows/macOS/Linux
+- **Solution**:
+  - Use platform detection helpers consistently
+  - Skip platform-specific tests appropriately
+  - Account for filesystem differences (case sensitivity, path formats)
+  - Test with platform-specific CI matrices
+
+### 8. Jest Configuration
+- **Problem**: Tests interfere with each other
+- **Solution**:
+  - Use `--runInBand` for tests with shared resources
+  - Clear module cache between tests when needed
+  - Isolate tests that spawn processes
+  - Configure proper test timeouts per environment
+
+### Async Cleanup Anti-Patterns
+
+**IMPORTANT**: The following approaches are NOT valid solutions for async cleanup issues:
+
+```javascript
+// BAD: Arbitrary timeouts in tests
+await new Promise((resolve) => setTimeout(resolve, 100));
+
+// BAD: Forcing garbage collection
+if (global.gc) {
+  global.gc();
+}
+
+// BAD: Adding setImmediate in afterAll to "fix" hanging tests
+afterAll(async () => {
+  await new Promise((resolve) => setImmediate(resolve));
+});
+```
+
+**Why these are problematic:**
+
+1. **Arbitrary timeouts** are race conditions waiting to happen. They might work on fast machines but fail on slower CI runners.
+2. **Forcing GC** should never be required for correct behavior. If your code depends on GC for correctness, it has a fundamental design flaw.
+3. **setImmediate/nextTick delays** in cleanup hooks don't fix the root cause - they just paper over the real issue.
+4. These approaches mask the real problem instead of fixing it.
+
+**Note**: This is different from legitimate uses of timeouts, such as:
+
+- Waiting for time to pass to test timestamp changes
+- Rate limiting or throttling tests
+- Testing timeout behavior itself
+
+The anti-pattern is using timeouts or GC to "fix" async cleanup issues.
+
+**What to do instead:**
+
+1. Find the actual resource that's keeping the process alive (use `--detectOpenHandles`)
+2. Ensure all database connections are properly closed
+3. Ensure all file handles are closed
+4. Cancel or await all pending async operations
+5. Use proper resource management patterns (RAII, try-finally, using statements)
+
+### Windows-Compatible Directory Cleanup
+
+**IMPORTANT**: Never use `fs.rmSync()` or `fs.rm()` without proper Windows retry logic for directory cleanup in tests.
+
+**Problem**: On Windows, file handles and directory locks can remain active longer than on Unix systems, causing `EBUSY` errors during cleanup.
+
+**Proper Solution**: Use `fsp.rm()` (async) with retry options:
+
+```typescript
+await fsp.rm(tempDir, {
+  recursive: true,
+  force: true,
+  maxRetries: process.platform === "win32" ? 3 : 1,
+  retryDelay: process.platform === "win32" ? 100 : 0,
+});
+```
+
+**Best Practice**: Use existing test utilities that handle Windows-compatible cleanup patterns. Don't manually clean up temp directories - let the test framework handle it with proper retry logic.
+
+### Adaptive Timeout Testing
+
+**Problem**: Fixed timeouts don't account for varying CI environment performance.
+
+**Root Causes**:
+
+- Alpine Linux (musl libc) is 2x slower than glibc
+- ARM64 emulation on x64 runners is 5x slower
+- Windows process operations are 4x slower
+- macOS VMs are 4x slower
+- CI environments have resource constraints
+
+**Solutions**:
+
+```typescript
+// DON'T: Use fixed timeouts
+test("my test", async () => {
+  // Test code
+}, 10000);
+
+// DO: Use adaptive timeouts based on environment
+import { getTestTimeout } from "./test-utils/test-timeout-config";
+
+test(
+  "my test",
+  async () => {
+    // Test code
+  },
+  getTestTimeout(10000),
+);
+
+// DO: Account for platform timing differences
+const timingMultiplier = process.platform === "win32" ? 4 :
+                        process.platform === "darwin" ? 4 :
+                        process.env.CI ? 2 : 1;
+```
+
+### Multi-Process Test Synchronization
+
+**Problem**: Multi-process tests failing due to race conditions between process startup and test assertions.
+
+**Root Cause**: The timing between process startup and resource acquisition varies significantly by platform.
+
+**Solutions**:
+
+```typescript
+// DON'T: Assume immediate process readiness
+const proc = spawn(nodeCmd, [script]);
+const result = await waitForProcessResult(proc);
+expect(result).toBe("expected_outcome"); // May fail due to timing
+
+// DO: Use explicit synchronization signals
+const script = `
+  // Setup code
+  console.log("READY");  // Signal readiness
+  // Main test logic
+  console.log("RESULT:" + outcome);
+`;
+
+const proc = spawn(process.execPath, ["-e", script]);
+await waitForOutput(proc, "READY"); // Wait for process to be ready
+const result = await waitForOutput(proc, "RESULT:");
+expect(result.split(":")[1]).toBe("expected_outcome");
+```
+
+### Wait-for-Condition Pattern
+
+**Problem**: Tests failing because they don't wait for asynchronous conditions to be met.
+
+**Solution**: Implement robust condition waiting with platform-aware timing:
+
+```typescript
+async function waitForCondition(
+  check: () => boolean | Promise<boolean>,
+  options: {
+    maxAttempts?: number;
+    delay?: number;
+    timeoutMs?: number;
+  } = {}
+) {
+  const {
+    maxAttempts = 50,
+    delay = 100,
+    timeoutMs = 30000
+  } = options;
+  
+  const startTime = Date.now();
+  
+  for (let i = 0; i < maxAttempts; i++) {
+    if (Date.now() - startTime > timeoutMs) {
+      throw new Error(`Condition not met within ${timeoutMs}ms`);
+    }
+    
+    if (await check()) return true;
+    await new Promise((resolve) => setTimeout(resolve, delay));
+  }
+  
+  return false;
+}
+
+// Usage example
+await waitForCondition(
+  () => fs.existsSync(expectedFile),
+  { timeoutMs: getTestTimeout(10000) }
+);
+```
+
+### Best Practices Summary
+1. **Always clean up**: Resources, timers, workers, file handles
+2. **Never assume timing**: Use ranges and adaptive timeouts, not exact values
+3. **Isolate tests**: Each test should be independent
+4. **Platform awareness**: Skip tests that can't work on certain platforms
+5. **Proper async handling**: Always await or return promises
+6. **Resource limits**: Don't spawn unlimited workers/processes
+7. **Environment detection**: Adjust behavior for CI vs local
+8. **Deterministic tests**: Mock external dependencies when possible
+9. **Explicit synchronization**: Use signals for multi-process coordination
+10. **Robust waiting**: Use condition-based waiting instead of arbitrary timeouts
+11. **Windows compatibility**: Use retry logic for file operations on Windows
+12. **Anti-pattern awareness**: Avoid masking problems with timeouts or forced GC