@photostructure/fs-metadata 0.5.0 → 0.6.0

package/C++_REVIEW_TODO.md

@@ -243,7 +243,7 @@ This document outlines a comprehensive review of all C++ files in the fs-metadat
 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`)
+   - Created standalone test runner (`scripts/sanitizers-test.sh`)
    - Updated `scripts/check-memory.mjs` with better ASan support
    - All memory tests integrated into CI/CD
 

package/CHANGELOG.md

@@ -14,7 +14,7 @@ Fixed for any bug fixes.
 Security in case of vulnerabilities.
 -->
 
-## [0.5.0] - 2025-06-01
+## [0.6.0] - 2025-06-03
 
 ### Added
 
@@ -22,6 +22,8 @@ Security in case of vulnerabilities.
 - 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
 
 ### Breaking
 
@@ -32,6 +34,8 @@ Security in case of vulnerabilities.
 - 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
 
 ### Fixed
 
@@ -41,6 +45,12 @@ Security in case of vulnerabilities.
 - Enhanced resource management with better validation for empty mount points
 - Made `SystemPathPatternsDefault` values visible in TypeScript typings
 - Improved test reliability across different CI environments
+- Added Napi::HandleScope to OnOK and OnError methods for proper scope management
+- Removed unnecessary std::move operations in worker implementations
+- Updated filesystem metadata tests to verify type and existence instead of specific values
+- Improved error handling and messages in various components
+- Enhanced error message validation for file access in worker thread tests
+- Updated tests to use healthy mount points for volume metadata retrieval
 
 ## [0.4.0] - 2025-01-09
 

package/CLAUDE.md

@@ -15,6 +15,7 @@ This is @photostructure/fs-metadata - a cross-platform native Node.js module for
 - 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
@@ -29,7 +30,7 @@ This is @photostructure/fs-metadata - a cross-platform native Node.js module for
 npm install
 
 # Configure platform-specific build settings
-npm run configure
+npm run configure:native
 
 # Build native bindings
 npm run node-gyp-rebuild
@@ -37,32 +38,32 @@ npm run node-gyp-rebuild
 # Create prebuilds for distribution  
 npm run prebuild
 
-# Bundle TypeScript to dist/
-npm run bundle
+# Assemble TypeScript to dist/
+npm run build:dist
 ```
 
 ### Testing
 ```bash
 # Run all tests with coverage (includes memory tests on Linux)
-npm run tests
+npm run test:all
 
 # Run CommonJS tests
-npm test cjs
+npm test:cjs
 
 # Run ESM tests
-npm test esm
+npm test:esm
 
 # Test memory leaks (JavaScript)
 npm run test:memory
 
 # Run valgrind memory analysis (Linux only)
-npm run test:valgrind
+bash scripts/valgrind-test.sh
 
-# Run comprehensive memory tests (JavaScript + valgrind on Linux)
-npm run tests:memory
+# Run AddressSanitizer and LeakSanitizer (Linux only)
+bash scripts/sanitizers-test.sh
 
-# Run AddressSanitizer tests (Linux only)
-npm run asan
+# Run comprehensive memory tests (JavaScript + valgrind + sanitizers)
+npm run test:memory
 
 # Run a specific test file (no coverage)
 npm test volume_metadata
@@ -86,7 +87,7 @@ npm run fmt:cpp
 npm run fmt:ts
 
 # Type checking
-npm run compile
+npm run build:ts
 ```
 
 ### Pre-commit
@@ -122,23 +123,29 @@ npm run docs
 - 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
 
-### 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
+### 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

package/CONTRIBUTING.md

@@ -54,18 +54,59 @@ into account both Windows and POSIX systems.
 **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.
+
+## npm Script Naming Conventions
+
+This project follows consistent naming patterns for npm scripts to improve discoverability and maintainability:
+
+### Action:Target Format
+
+Scripts follow an `action:target` pattern where:
+
+- **action**: The operation being performed (`build`, `clean`, `lint`, `test`)
+- **target**: What the action operates on (`native`, `ts`, `dist`)
+
+Examples:
+
+- `build:native` - Build native C++ code
+- `lint:ts` - Lint TypeScript code
+- `clean:dist` - Clean distribution files
+
+### Parallel Execution
+
+Actions that have multiple targets can be run in parallel using wildcards:
+
+- `npm run clean` runs all `clean:*` scripts
+- `npm run lint` runs all `lint:*` scripts
+- Uses `run-p` from npm-run-all for parallel execution
+
+### Special Namespaces
+
+- **memory:\*** - Memory testing scripts that should not run automatically with `test:*`
+  - `memory:test` - Comprehensive memory testing suite
+  - Run with `ENABLE_ASAN=1` to include sanitizer tests
+
+### Naming Guidelines
+
+- Use explicit names to avoid ambiguity (e.g., `configure:native` instead of just `configure`)
+- Group related scripts by action prefix for easy wildcard execution
+- Avoid names that could cause npm lifecycle conflicts (e.g., `prebuild` vs `build`)
+- Use descriptive suffixes that clearly indicate the target or purpose

package/binding.gyp

@@ -16,7 +16,8 @@
         "<!(node -p \"require('node-addon-api').gyp\")"
       ],
       "defines": [
-        "NAPI_CPP_EXCEPTIONS"
+        "NAPI_CPP_EXCEPTIONS",
+        "NAPI_VERSION=9"
       ],
       "conditions": [
         [