file-entry-cache - feat: renaming strictPaths to restrictAccessToCwd (#1397)

* file-entry-cache - feat: renaming strictPaths to restrictAccessToCwd

* create

* Update README.md

* Update README.md

* useAbsolutePathAsKey

* logger

Author: jaredwray

packages/file-entry-cache/README.md

@@ -72,6 +72,23 @@ fileDescriptor = cache.getFileDescriptor('./src/file.txt');
 console.log(fileDescriptor.changed); // true
 ```
 
+Using `create()` with options for more control:
+```javascript
+import fileEntryCache from 'file-entry-cache';
+
+// Create cache with options
+const cache = fileEntryCache.create('myCache', './.cache', {
+  useCheckSum: true,              // Use checksums for more reliable change detection
+  cwd: '/path/to/project',        // Custom working directory
+  restrictAccessToCwd: false,     // Allow access outside cwd (use with caution)
+  useAbsolutePathAsKey: false     // Store relative paths in cache
+});
+
+let fileDescriptor = cache.getFileDescriptor('./src/file.txt');
+console.log(fileDescriptor.changed); // true
+console.log(fileDescriptor.meta.hash); // checksum hash
+```
+
 Save it to Disk and Reconcile files that are no longer found
 ```javascript
 import fileEntryCache from 'file-entry-cache';
@@ -85,20 +102,80 @@ Load the cache from a file:
 
 ```javascript
 import fileEntryCache from 'file-entry-cache';
+
+// Basic usage
 const cache = fileEntryCache.createFromFile('/path/to/cache/file');
 let fileDescriptor = cache.getFileDescriptor('./src/file.txt');
 console.log(fileDescriptor.changed); // false as it has not changed from the saved cache.
+
+// With options
+const cache2 = fileEntryCache.createFromFile('/path/to/cache/file', {
+  useCheckSum: true,
+  cwd: '/path/to/project'
+});
 ```
 
 
 # Changes from v10 to v11
 
 **BREAKING CHANGES:**
-- **`strictPaths` now defaults to `true`** - Path traversal protection is enabled by default for security. To restore v10 behavior, explicitly set `strictPaths: false`
+
+- **`create()` and `createFromFile()` now use `CreateOptions` object** - The function signatures have changed to accept an options object instead of individual parameters for better extensibility and clarity.
+
+  **Old API (v10):**
+  ```javascript
+  // v10 - positional parameters
+  const cache = fileEntryCache.create(cacheId, cacheDirectory, useCheckSum, cwd);
+  const cache2 = fileEntryCache.createFromFile(filePath, useCheckSum, cwd);
+  ```
+
+  **New API (v11):**
+  ```javascript
+  // v11 - options object
+  const cache = fileEntryCache.create(cacheId, cacheDirectory, {
+    useCheckSum: true,
+    cwd: '/path/to/project',
+    restrictAccessToCwd: false
+  });
+
+  const cache2 = fileEntryCache.createFromFile(filePath, {
+    useCheckSum: true,
+    cwd: '/path/to/project',
+    restrictAccessToCwd: false
+  });
+  ```
+
+- **Renamed `strictPaths` to `restrictAccessToCwd`** - For better clarity and self-documentation, the option that restricts file access to the current working directory has been renamed.
+
+  **Migration:**
+  ```javascript
+  // Old
+  const cache = new FileEntryCache({ strictPaths: true });
+  cache.strictPaths = false;
+
+  // New
+  const cache = new FileEntryCache({ restrictAccessToCwd: true });
+  cache.restrictAccessToCwd = false;
+  ```
+
+- **Renamed `currentWorkingDirectory` to `cwd`** - For consistency with common conventions and brevity, the property has been renamed to `cwd`.
+
+  **Migration:**
+  ```javascript
+  // Old
+  const cache = new FileEntryCache({ currentWorkingDirectory: '/path/to/project' });
+  cache.currentWorkingDirectory = '/new/path';
+
+  // New
+  const cache = new FileEntryCache({ cwd: '/path/to/project' });
+  cache.cwd = '/new/path';
+  ```
 
 **NEW FEATURES:**
 - **Added `cwd` option** - You can now specify a custom current working directory for resolving relative paths
-- **Added `strictPaths` option** - Provides protection against path traversal attacks (enabled by default)
+- **Added `restrictAccessToCwd` option** - Provides protection against path traversal attacks (disabled by default for backwards compatibility)
+- **Added `useAbsolutePathAsKey` option** - When `true`, cache keys use absolute paths instead of the provided paths. Default is `false` for better cache portability with relative paths
+- **Added `logger` option** - Support for Pino-compatible logger instances to enable debugging and monitoring of cache operations. See [Logger Support](#logger-support) section for details
 - **Improved cache portability** - When using relative paths with the same `cwd`, cache files are portable across different environments
 
 # Changes from v9 to v10
@@ -114,15 +191,24 @@ There have been many features added and changes made to the `file-entry-cache` c
 - On `FileEntryDescriptor.meta` if using typescript you need to use the `meta.data` to set additional information. This is to allow for better type checking and to avoid conflicts with the `meta` object which was `any`.
 
 # Global Default Functions
-- `create(cacheId: string, cacheDirectory?: string, useCheckSum?: boolean, cwd?: string)` - Creates a new instance of the `FileEntryCache` class
-- `createFromFile(cachePath: string, useCheckSum?: boolean, cwd?: string)` - Creates a new instance of the `FileEntryCache` class and loads the cache from a file.
+- `create(cacheId: string, cacheDirectory?: string, options?: CreateOptions)` - Creates a new instance of the `FileEntryCache` class
+- `createFromFile(filePath: string, options?: CreateOptions)` - Creates a new instance of the `FileEntryCache` class and loads the cache from a file.
+
+## CreateOptions Type
+All options from `FileEntryCacheOptions` except `cache`:
+- `useCheckSum?` - If `true` it will use a checksum to determine if the file has changed. Default is `false`
+- `hashAlgorithm?` - The algorithm to use for the checksum. Default is `md5`
+- `cwd?` - The current working directory for resolving relative paths. Default is `process.cwd()`
+- `restrictAccessToCwd?` - If `true` restricts file access to within `cwd` boundaries. Default is `false`
+- `useAbsolutePathAsKey?` - If `true` uses absolute paths as cache keys. Default is `false`
+- `logger?` - A logger instance for debugging. Default is `undefined`
 
 # FileEntryCache Options (FileEntryCacheOptions)
 - `useModifiedTime?` - If `true` it will use the modified time to determine if the file has changed. Default is `true`
 - `useCheckSum?` - If `true` it will use a checksum to determine if the file has changed. Default is `false`
 - `hashAlgorithm?` - The algorithm to use for the checksum. Default is `md5` but can be any algorithm supported by `crypto.createHash`
 - `cwd?` - The current working directory for resolving relative paths. Default is `process.cwd()`
-- `strictPaths?` - If `true` restricts file access to within `cwd` boundaries, preventing path traversal attacks. Default is `true`
+- `restrictAccessToCwd?` - If `true` restricts file access to within `cwd` boundaries, preventing path traversal attacks. Default is `true`
 - `logger?` - A logger instance compatible with Pino logger interface for debugging and monitoring. Default is `undefined`
 - `cache.ttl?` - The time to live for the cache in milliseconds. Default is `0` which means no expiration
 - `cache.lruSize?` - The number of items to keep in the cache. Default is `0` which means no limit
@@ -141,9 +227,10 @@ There have been many features added and changes made to the `file-entry-cache` c
 - `hashAlgorithm: string` - The algorithm to use for the checksum. Default is `md5` but can be any algorithm supported by `crypto.createHash`
 - `getHash(buffer: Buffer): string` - Gets the hash of a buffer used for checksums
 - `cwd: string` - The current working directory for resolving relative paths. Default is `process.cwd()`
-- `strictPaths: boolean` - If `true` restricts file access to within `cwd` boundaries. Default is `true`
+- `restrictAccessToCwd: boolean` - If `true` restricts file access to within `cwd` boundaries. Default is `true`
+- `useAbsolutePathAsKey: boolean` - If `true` uses absolute paths as cache keys. Default is `false` to maintain better cache portability
 - `logger: ILogger | undefined` - A logger instance for debugging and monitoring cache operations
-- `createFileKey(filePath: string): string` - Returns the cache key for the file path (returns the path exactly as provided).
+- `createFileKey(filePath: string): string` - Returns the cache key for the file path (returns the path exactly as provided when `useAbsolutePathAsKey` is `false`, otherwise returns the absolute path).
 - `deleteCacheFile(): boolean` - Deletes the cache file from disk
 - `destroy(): void` - Destroys the cache. This will clear the cache in memory. If using cache persistence it will stop the interval.
 - `removeEntry(filePath: string): void` - Removes an entry from the cache.
@@ -154,8 +241,8 @@ There have been many features added and changes made to the `file-entry-cache` c
 - `analyzeFiles(files: string[])` will return `AnalyzedFiles` object with `changedFiles`, `notFoundFiles`, and `notChangedFiles` as FileDescriptor arrays.
 - `getUpdatedFiles(files: string[])` will return an array of `FileEntryDescriptor` objects that have changed.
 - `getFileDescriptorsByPath(filePath: string): FileEntryDescriptor[]` will return an array of `FileEntryDescriptor` objects that starts with the path prefix specified.
-- `getAbsolutePath(filePath: string): string` - Resolves a relative path to absolute using the configured `cwd`. Returns absolute paths unchanged. When `strictPaths` is enabled, throws an error if the path resolves outside `cwd`.
-- `getAbsolutePathWithCwd(filePath: string, cwd: string): string` - Resolves a relative path to absolute using a custom working directory. When `strictPaths` is enabled, throws an error if the path resolves outside the provided `cwd`.
+- `getAbsolutePath(filePath: string): string` - Resolves a relative path to absolute using the configured `cwd`. Returns absolute paths unchanged. When `restrictAccessToCwd` is enabled, throws an error if the path resolves outside `cwd`.
+- `getAbsolutePathWithCwd(filePath: string, cwd: string): string` - Resolves a relative path to absolute using a custom working directory. When `restrictAccessToCwd` is enabled, throws an error if the path resolves outside the provided `cwd`.
 
 # Get File Descriptor
 
@@ -175,9 +262,12 @@ The cache stores paths exactly as they are provided (relative or absolute). When
 // Default: uses process.cwd()
 const cache1 = fileEntryCache.create('cache1');
 
-// Custom working directory
-const cache2 = fileEntryCache.create('cache2', './cache', false, '/project/root');
-// Or with options object
+// Custom working directory using options object
+const cache2 = fileEntryCache.create('cache2', './cache', {
+  cwd: '/project/root'
+});
+
+// Or using the class constructor directly
 const cache3 = new FileEntryCache({ cwd: '/project/root' });
 
 // The cache key is always the provided path
@@ -192,12 +282,16 @@ Using relative paths with a consistent `cwd` (defaults to `process.cwd()`) makes
 
 ```javascript
 // On machine A (project at /home/user/project)
-const cacheA = fileEntryCache.create('build-cache', './cache', false, '/home/user/project');
+const cacheA = fileEntryCache.create('build-cache', './cache', {
+  cwd: '/home/user/project'
+});
 cacheA.getFileDescriptor('./src/index.js'); // Resolves to /home/user/project/src/index.js
 cacheA.reconcile();
 
 // On machine B (project at /workspace/project)
-const cacheB = fileEntryCache.create('build-cache', './cache', false, '/workspace/project');
+const cacheB = fileEntryCache.create('build-cache', './cache', {
+  cwd: '/workspace/project'
+});
 cacheB.getFileDescriptor('./src/index.js'); // Resolves to /workspace/project/src/index.js
 // Cache hit! File hasn't changed since machine A
 ```
@@ -208,11 +302,9 @@ For maximum cache portability across different environments, use checksums (`use
 
 ```javascript
 // Development machine
-const devCache = fileEntryCache.create(
-    '.buildcache',
-    './cache',                 // cache directory
-    true                      // Use checksums for content-based comparison
-);
+const devCache = fileEntryCache.create('.buildcache', './cache', {
+  useCheckSum: true  // Use checksums for content-based comparison
+});
 
 // Process files using relative paths
 const descriptor = devCache.getFileDescriptor('./src/index.js');
@@ -223,12 +315,10 @@ if (descriptor.changed) {
 devCache.reconcile(); // Save cache
 
 // CI/CD Pipeline or another developer's machine
-const ciCache = fileEntryCache.create(
-    '.buildcache',
-    './node_modules/.cache',
-    true,                      // Same checksum setting
-    process.cwd()              // Different absolute path, same relative structure
-);
+const ciCache = fileEntryCache.create('.buildcache', './node_modules/.cache', {
+  useCheckSum: true,      // Same checksum setting
+  cwd: process.cwd()      // Different absolute path, same relative structure
+});
 
 // Same relative path works across environments
 const descriptor2 = ciCache.getFileDescriptor('./src/index.js');
@@ -244,12 +334,18 @@ Cache remains valid even when projects are moved or renamed:
 
 ```javascript
 // Original location: /projects/my-app
-const cache1 = fileEntryCache.create('.cache', './cache', true, '/projects/my-app');
+const cache1 = fileEntryCache.create('.cache', './cache', {
+  useCheckSum: true,
+  cwd: '/projects/my-app'
+});
 cache1.getFileDescriptor('./src/app.js');
 cache1.reconcile();
 
 // After moving project to: /archived/2024/my-app
-const cache2 = fileEntryCache.create('.cache', './cache', true, '/archived/2024/my-app');
+const cache2 = fileEntryCache.create('.cache', './cache', {
+  useCheckSum: true,
+  cwd: '/archived/2024/my-app'
+});
 cache2.getFileDescriptor('./src/app.js'); // Still finds cached entry!
 // Cache valid as long as relative structure unchanged
 ```
@@ -270,12 +366,12 @@ if (fileDescriptor.notFound) {
 
 # Path Security and Traversal Prevention
 
-The `strictPaths` option provides security against path traversal attacks by restricting file access to within the configured `cwd` boundaries. **This is enabled by default (since v11)** to ensure secure defaults when processing untrusted input or when running in security-sensitive environments.
+The `restrictAccessToCwd` option provides security against path traversal attacks by restricting file access to within the configured `cwd` boundaries. **This is enabled by default (since v11)** to ensure secure defaults when processing untrusted input or when running in security-sensitive environments.
 
 ## Basic Usage
 
 ```javascript
-// strictPaths is enabled by default for security
+// restrictAccessToCwd is enabled by default for security
 const cache = new FileEntryCache({
     cwd: '/project/root'
 });
@@ -293,13 +389,13 @@ try {
 // To allow parent directory access (not recommended for untrusted input)
 const unsafeCache = new FileEntryCache({
     cwd: '/project/root',
-    strictPaths: false  // Explicitly disable protection
+    restrictAccessToCwd: false  // Explicitly disable protection
 });
 ```
 
 ## Security Features
 
-When `strictPaths` is enabled:
+When `restrictAccessToCwd` is enabled:
 - **Path Traversal Prevention**: Blocks attempts to access files outside the working directory using `../` sequences
 - **Null Byte Protection**: Automatically removes null bytes from paths to prevent injection attacks
 - **Path Normalization**: Cleans and normalizes paths to prevent bypass attempts
@@ -309,15 +405,11 @@ When `strictPaths` is enabled:
 ### Build Tools with Untrusted Input
 ```javascript
 // Secure build tool configuration
-const cache = fileEntryCache.create(
-    '.buildcache',
-    './cache',
-    true,  // useCheckSum
-    process.cwd()
-);
-
-// Enable strict path checking for security
-cache.strictPaths = true;
+const cache = fileEntryCache.create('.buildcache', './cache', {
+  useCheckSum: true,
+  cwd: process.cwd(),
+  restrictAccessToCwd: true  // Enable strict path checking for security
+});
 
 // Process user-provided file paths safely
 function processUserFile(userProvidedPath) {
@@ -340,7 +432,7 @@ function processUserFile(userProvidedPath) {
 // Strict security for CI/CD pipelines
 const cache = new FileEntryCache({
     cwd: process.env.GITHUB_WORKSPACE || process.cwd(),
-    strictPaths: true,  // Prevent access outside workspace
+    restrictAccessToCwd: true,  // Prevent access outside workspace
     useCheckSum: true   // Content-based validation
 });
 
@@ -355,20 +447,20 @@ cache.getFileDescriptor('../../../root'); // ✗ Blocked (path traversal)
 const cache = new FileEntryCache({ cwd: '/safe/directory' });
 
 // Start with relaxed mode for trusted operations
-cache.strictPaths = false;
+cache.restrictAccessToCwd = false;
 processInternalFiles();
 
 // Enable strict mode for untrusted input
-cache.strictPaths = true;
+cache.restrictAccessToCwd = true;
 processUserUploadedPaths();
 
 // Return to relaxed mode if needed
-cache.strictPaths = false;
+cache.restrictAccessToCwd = false;
 ```
 
 ## Default Behavior
 
-**As of v11, `strictPaths` is enabled by default** to provide secure defaults. This means:
+**As of v11, `restrictAccessToCwd` is enabled by default** to provide secure defaults. This means:
 - Path traversal attempts using `../` are blocked
 - File access is restricted to within the configured `cwd`
 - Null bytes in paths are automatically sanitized
@@ -380,11 +472,11 @@ If you're upgrading from v10 or earlier and need to maintain the previous behavi
 ```javascript
 const cache = new FileEntryCache({
     cwd: process.cwd(),
-    strictPaths: false  // Restore v10 behavior
+    restrictAccessToCwd: false  // Restore v10 behavior
 });
 ```
 
-However, we strongly recommend keeping `strictPaths: true` and adjusting your code to work within the security boundaries, especially when processing any untrusted input.
+However, we strongly recommend keeping `restrictAccessToCwd: true` and adjusting your code to work within the security boundaries, especially when processing any untrusted input.
 
 # Using Checksums to Determine if a File has Changed (useCheckSum)