@hyperfrontend/versioning 0.1.0 → 0.2.0

package/workspace/discovery/index.esm.js

@@ -1,6 +1,6 @@
 import { join as join$1, resolve, parse as parse$1, dirname } from 'node:path';
-import 'node:util';
 import { existsSync, readFileSync, statSync, lstatSync, readdirSync } from 'node:fs';
+import 'node:util';
 import 'node:os';
 
 /**
@@ -73,6 +73,109 @@ const _Reflect = globalThis.Reflect;
  */
 const createSet = (iterable) => _Reflect.construct(_Set, iterable ? [iterable] : []);
 
+/**
+ * Safe copies of Array built-in static methods.
+ *
+ * These references are captured at module initialization time to protect against
+ * prototype pollution attacks. Import only what you need for tree-shaking.
+ *
+ * @module @hyperfrontend/immutable-api-utils/built-in-copy/array
+ */
+// Capture references at module initialization time
+const _Array = globalThis.Array;
+/**
+ * (Safe copy) Determines whether the passed value is an Array.
+ */
+const isArray = _Array.isArray;
+
+/**
+ * Safe copies of JSON built-in methods.
+ *
+ * These references are captured at module initialization time to protect against
+ * prototype pollution attacks. Import only what you need for tree-shaking.
+ *
+ * @module @hyperfrontend/immutable-api-utils/built-in-copy/json
+ */
+// Capture references at module initialization time
+const _JSON = globalThis.JSON;
+/**
+ * (Safe copy) Converts a JavaScript Object Notation (JSON) string into an object.
+ */
+const parse = _JSON.parse;
+/**
+ * (Safe copy) Converts a JavaScript value to a JavaScript Object Notation (JSON) string.
+ */
+const stringify = _JSON.stringify;
+
+/**
+ * Safe copies of Object built-in methods.
+ *
+ * These references are captured at module initialization time to protect against
+ * prototype pollution attacks. Import only what you need for tree-shaking.
+ *
+ * @module @hyperfrontend/immutable-api-utils/built-in-copy/object
+ */
+// Capture references at module initialization time
+const _Object = globalThis.Object;
+/**
+ * (Safe copy) Prevents modification of existing property attributes and values,
+ * and prevents the addition of new properties.
+ */
+const freeze = _Object.freeze;
+/**
+ * (Safe copy) Returns the names of the enumerable string properties and methods of an object.
+ */
+const keys = _Object.keys;
+/**
+ * (Safe copy) Returns an array of key/values of the enumerable own properties of an object.
+ */
+const entries = _Object.entries;
+/**
+ * (Safe copy) Returns an array of values of the enumerable own properties of an object.
+ */
+const values = _Object.values;
+/**
+ * (Safe copy) Adds one or more properties to an object, and/or modifies attributes of existing properties.
+ */
+const defineProperties = _Object.defineProperties;
+
+/**
+ * Create a structured error with code and optional context.
+ *
+ * @param message - The human-readable error message
+ * @param code - The machine-readable error code for programmatic handling
+ * @param context - Additional contextual information about the error
+ * @returns Structured error instance with code and context properties
+ *
+ * @example
+ * ```typescript
+ * import { createStructuredError } from '@hyperfrontend/project-scope'
+ *
+ * throw createStructuredError(
+ *   'Configuration file not found',
+ *   'CONFIG_NOT_FOUND',
+ *   { path: './config.json', searched: ['./config.json', './settings.json'] }
+ * )
+ * ```
+ */
+function createStructuredError(message, code, context) {
+    const error = createError(message);
+    error.code = code;
+    error.context = context ?? {};
+    return error;
+}
+/**
+ * Create a configuration-related error.
+ *
+ * @param message - The human-readable error message
+ * @param code - The machine-readable error code for programmatic handling
+ * @param context - Additional contextual information (e.g., file path, config key)
+ * @returns Structured error instance tagged with type 'config'
+ */
+function createConfigError(message, code, context) {
+    return createStructuredError(message, code, { ...context, type: 'config' });
+}
+
 /**
  * Safe copies of Console built-in methods.
  *
@@ -156,72 +259,6 @@ _console.timeEnd.bind(_console);
  */
 _console.timeLog.bind(_console);
 
-/**
- * Safe copies of Array built-in static methods.
- *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
- *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/array
- */
-// Capture references at module initialization time
-const _Array = globalThis.Array;
-/**
- * (Safe copy) Determines whether the passed value is an Array.
- */
-const isArray = _Array.isArray;
-
-/**
- * Safe copies of JSON built-in methods.
- *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
- *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/json
- */
-// Capture references at module initialization time
-const _JSON = globalThis.JSON;
-/**
- * (Safe copy) Converts a JavaScript Object Notation (JSON) string into an object.
- */
-const parse = _JSON.parse;
-/**
- * (Safe copy) Converts a JavaScript value to a JavaScript Object Notation (JSON) string.
- */
-const stringify = _JSON.stringify;
-
-/**
- * Safe copies of Object built-in methods.
- *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
- *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/object
- */
-// Capture references at module initialization time
-const _Object = globalThis.Object;
-/**
- * (Safe copy) Prevents modification of existing property attributes and values,
- * and prevents the addition of new properties.
- */
-const freeze = _Object.freeze;
-/**
- * (Safe copy) Returns the names of the enumerable string properties and methods of an object.
- */
-const keys = _Object.keys;
-/**
- * (Safe copy) Returns an array of key/values of the enumerable own properties of an object.
- */
-const entries = _Object.entries;
-/**
- * (Safe copy) Returns an array of values of the enumerable own properties of an object.
- */
-const values = _Object.values;
-/**
- * (Safe copy) Adds one or more properties to an object, and/or modifies attributes of existing properties.
- */
-const defineProperties = _Object.defineProperties;
-
 const registeredClasses = [];
 
 /**
@@ -779,43 +816,6 @@ function findUpwardWhere(startPath, test) {
     return traverseUpward(startPath, test);
 }
 
-/**
- * Create a structured error with code and optional context.
- *
- * @param message - The human-readable error message
- * @param code - The machine-readable error code for programmatic handling
- * @param context - Additional contextual information about the error
- * @returns Structured error instance with code and context properties
- *
- * @example
- * ```typescript
- * import { createStructuredError } from '@hyperfrontend/project-scope'
- *
- * throw createStructuredError(
- *   'Configuration file not found',
- *   'CONFIG_NOT_FOUND',
- *   { path: './config.json', searched: ['./config.json', './settings.json'] }
- * )
- * ```
- */
-function createStructuredError(message, code, context) {
-    const error = createError(message);
-    error.code = code;
-    error.context = context ?? {};
-    return error;
-}
-/**
- * Create a configuration-related error.
- *
- * @param message - The human-readable error message
- * @param code - The machine-readable error code for programmatic handling
- * @param context - Additional contextual information (e.g., file path, config key)
- * @returns Structured error instance tagged with type 'config'
- */
-function createConfigError(message, code, context) {
-    return createStructuredError(message, code, { ...context, type: 'config' });
-}
-
 const packageLogger = createScopedLogger('project-scope:project:package');
 /**
  * Verifies that a value is an object with only string values,
@@ -942,138 +942,51 @@ function findNearestPackageJson(startPath) {
     return locateByMarkers(startPath, ['package.json']);
 }
 
-createScopedLogger('project-scope:heuristics:deps');
-
+const rootLogger = createScopedLogger('project-scope:root');
 /**
- * Global registry of all caches for bulk operations.
+ * Files indicating workspace/monorepo root.
  */
-const cacheRegistry = createSet();
+const WORKSPACE_MARKERS = ['nx.json', 'turbo.json', 'lerna.json', 'pnpm-workspace.yaml', 'rush.json'];
 /**
- * Create a cache with optional TTL and size limits.
- *
- * The cache provides a simple key-value store with:
- * - Optional TTL (time-to-live) for automatic expiration
- * - Optional maxSize for limiting cache size with FIFO eviction
- * - Lazy expiration (entries are checked on access)
+ * Find workspace root (monorepo root).
+ * Searches up for workspace markers like nx.json, turbo.json, etc.
  *
- * @param options - Cache configuration options
- * @returns Cache instance
+ * @param startPath - Starting path
+ * @returns Workspace root path or null
  *
  * @example
  * ```typescript
- * // Basic cache
- * const cache = createCache<string, number>()
- * cache.set('answer', 42)
- * cache.get('answer') // 42
- *
- * // Cache with TTL (expires after 60 seconds)
- * const ttlCache = createCache<string, object>({ ttl: 60000 })
- *
- * // Cache with max size (evicts oldest when full)
- * const lruCache = createCache<string, object>({ maxSize: 100 })
+ * import { findWorkspaceRoot } from '@hyperfrontend/project-scope'
  *
- * // Combined options
- * const configCache = createCache<string, object>({
- *   ttl: 30000,
- *   maxSize: 50
- * })
+ * const root = findWorkspaceRoot('./libs/my-lib')
+ * if (root) {
+ *   console.log('Monorepo root:', root) // e.g., '/home/user/my-monorepo'
+ * }
  * ```
  */
-function createCache(options) {
-    const { ttl, maxSize } = options ?? {};
-    const store = createMap();
-    // Track insertion order for FIFO eviction
-    const insertionOrder = [];
-    /**
-     * Check if an entry is expired.
-     *
-     * @param entry - Cache entry to check
-     * @returns True if entry is expired
-     */
-    function isExpired(entry) {
-        if (ttl === undefined)
-            return false;
-        // eslint-disable-next-line workspace/no-unsafe-builtin-methods -- Date.now() is needed for Jest fake timers compatibility
-        return Date.now() - entry.timestamp > ttl;
+function findWorkspaceRoot(startPath) {
+    rootLogger.debug('Finding workspace root', { startPath });
+    const byMarker = locateByMarkers(startPath, WORKSPACE_MARKERS);
+    if (byMarker) {
+        rootLogger.debug('Found workspace root by marker', { root: byMarker });
+        return byMarker;
     }
-    /**
-     * Evict oldest entries to make room for new ones.
-     */
-    function evictIfNeeded() {
-        if (maxSize === undefined)
-            return;
-        while (store.size >= maxSize && insertionOrder.length > 0) {
-            const oldestKey = insertionOrder.shift();
-            if (oldestKey !== undefined) {
-                store.delete(oldestKey);
-            }
-        }
+    const byWorkspaces = findUpwardWhere(startPath, (dir) => {
+        const pkg = readPackageJsonIfExists(dir);
+        return pkg?.workspaces !== undefined;
+    });
+    if (byWorkspaces) {
+        rootLogger.debug('Found workspace root by workspaces field', { root: byWorkspaces });
+        return byWorkspaces;
     }
-    /**
-     * Remove key from insertion order tracking.
-     *
-     * @param key - Key to remove from order tracking
-     */
-    function removeFromOrder(key) {
-        const index = insertionOrder.indexOf(key);
-        if (index !== -1) {
-            insertionOrder.splice(index, 1);
-        }
+    const byPackage = findNearestPackageJson(startPath);
+    if (byPackage) {
+        rootLogger.debug('Found workspace root by package.json', { root: byPackage });
     }
-    const cache = {
-        get(key) {
-            const entry = store.get(key);
-            if (!entry)
-                return undefined;
-            if (isExpired(entry)) {
-                store.delete(key);
-                removeFromOrder(key);
-                return undefined;
-            }
-            return entry.value;
-        },
-        set(key, value) {
-            // If key exists, remove from order first
-            if (store.has(key)) {
-                removeFromOrder(key);
-            }
-            else {
-                // Evict if needed before adding new entry
-                evictIfNeeded();
-            }
-            // eslint-disable-next-line workspace/no-unsafe-builtin-methods -- Date.now() is needed for Jest fake timers compatibility
-            store.set(key, { value, timestamp: Date.now() });
-            insertionOrder.push(key);
-        },
-        has(key) {
-            const entry = store.get(key);
-            if (!entry)
-                return false;
-            if (isExpired(entry)) {
-                store.delete(key);
-                removeFromOrder(key);
-                return false;
-            }
-            return true;
-        },
-        delete(key) {
-            removeFromOrder(key);
-            return store.delete(key);
-        },
-        clear() {
-            store.clear();
-            insertionOrder.length = 0;
-        },
-        size() {
-            return store.size;
-        },
-        keys() {
-            return [...insertionOrder];
-        },
-    };
-    // Register cache for global operations
-    cacheRegistry.add(cache);
-    return freeze(cache);
+    else {
+        rootLogger.debug('Workspace root not found');
+    }
+    return byPackage;
 }
 
 /**
@@ -1481,107 +1394,6 @@ function findFiles(startPath, patterns, options) {
     return results;
 }
 
-createScopedLogger('project-scope:heuristics:entry-points');
-/**
- * Cache for entry point discovery results.
- * TTL: 60 seconds (entry points are relatively stable)
- */
-createCache({ ttl: 60000, maxSize: 50 });
-
-createScopedLogger('project-scope:tech');
-/**
- * Cache for tech detection results.
- * TTL: 60 seconds (tech stack can change during active development)
- */
-createCache({ ttl: 60000, maxSize: 50 });
-
-createScopedLogger('project-scope:heuristics:project-type');
-
-const rootLogger = createScopedLogger('project-scope:root');
-/**
- * Files indicating workspace/monorepo root.
- */
-const WORKSPACE_MARKERS = ['nx.json', 'turbo.json', 'lerna.json', 'pnpm-workspace.yaml', 'rush.json'];
-/**
- * Find workspace root (monorepo root).
- * Searches up for workspace markers like nx.json, turbo.json, etc.
- *
- * @param startPath - Starting path
- * @returns Workspace root path or null
- *
- * @example
- * ```typescript
- * import { findWorkspaceRoot } from '@hyperfrontend/project-scope'
- *
- * const root = findWorkspaceRoot('./libs/my-lib')
- * if (root) {
- *   console.log('Monorepo root:', root) // e.g., '/home/user/my-monorepo'
- * }
- * ```
- */
-function findWorkspaceRoot(startPath) {
-    rootLogger.debug('Finding workspace root', { startPath });
-    const byMarker = locateByMarkers(startPath, WORKSPACE_MARKERS);
-    if (byMarker) {
-        rootLogger.debug('Found workspace root by marker', { root: byMarker });
-        return byMarker;
-    }
-    const byWorkspaces = findUpwardWhere(startPath, (dir) => {
-        const pkg = readPackageJsonIfExists(dir);
-        return pkg?.workspaces !== undefined;
-    });
-    if (byWorkspaces) {
-        rootLogger.debug('Found workspace root by workspaces field', { root: byWorkspaces });
-        return byWorkspaces;
-    }
-    const byPackage = findNearestPackageJson(startPath);
-    if (byPackage) {
-        rootLogger.debug('Found workspace root by package.json', { root: byPackage });
-    }
-    else {
-        rootLogger.debug('Workspace root not found');
-    }
-    return byPackage;
-}
-
-createScopedLogger('project-scope:nx');
-
-createScopedLogger('project-scope:nx:devkit');
-
-createScopedLogger('project-scope:nx:config');
-
-createScopedLogger('project-scope:config');
-/**
- * Cache for config detection results.
- * TTL: 30 seconds (configs can change frequently during setup)
- */
-createCache({ ttl: 30000, maxSize: 50 });
-
-/** Logger for analysis operations */
-createScopedLogger('project-scope:analyze');
-
-/** Logger for CLI operations */
-createScopedLogger('project-scope:cli');
-
-createScopedLogger('project-scope:encoding');
-
-createScopedLogger('project-scope:encoding:convert');
-
-createScopedLogger('project-scope:heuristics:framework');
-/**
- * Cache for framework identification results.
- * TTL: 60 seconds (frameworks are stable but can change during development)
- */
-createCache({ ttl: 60000, maxSize: 50 });
-
-createScopedLogger('project-scope:vfs:tree');
-
-createScopedLogger('project-scope:vfs:factory');
-
-createScopedLogger('project-scope:vfs');
-
-createScopedLogger('project-scope:vfs:diff');
-
 /**
  * Project Model
  *
@@ -1965,6 +1777,194 @@ function transitivelyDependsOn(workspace, packageA, packageB) {
     return deps.has(packageB);
 }
 
+createScopedLogger('project-scope:heuristics:deps');
+
+/**
+ * Global registry of all caches for bulk operations.
+ */
+const cacheRegistry = createSet();
+/**
+ * Create a cache with optional TTL and size limits.
+ *
+ * The cache provides a simple key-value store with:
+ * - Optional TTL (time-to-live) for automatic expiration
+ * - Optional maxSize for limiting cache size with FIFO eviction
+ * - Lazy expiration (entries are checked on access)
+ *
+ * @param options - Cache configuration options
+ * @returns Cache instance
+ *
+ * @example
+ * ```typescript
+ * // Basic cache
+ * const cache = createCache<string, number>()
+ * cache.set('answer', 42)
+ * cache.get('answer') // 42
+ *
+ * // Cache with TTL (expires after 60 seconds)
+ * const ttlCache = createCache<string, object>({ ttl: 60000 })
+ *
+ * // Cache with max size (evicts oldest when full)
+ * const lruCache = createCache<string, object>({ maxSize: 100 })
+ *
+ * // Combined options
+ * const configCache = createCache<string, object>({
+ *   ttl: 30000,
+ *   maxSize: 50
+ * })
+ * ```
+ */
+function createCache(options) {
+    const { ttl, maxSize } = options ?? {};
+    const store = createMap();
+    // Track insertion order for FIFO eviction
+    const insertionOrder = [];
+    /**
+     * Check if an entry is expired.
+     *
+     * @param entry - Cache entry to check
+     * @returns True if entry is expired
+     */
+    function isExpired(entry) {
+        if (ttl === undefined)
+            return false;
+        // eslint-disable-next-line workspace/no-unsafe-builtin-methods -- Date.now() is needed for Jest fake timers compatibility
+        return Date.now() - entry.timestamp > ttl;
+    }
+    /**
+     * Evict oldest entries to make room for new ones.
+     */
+    function evictIfNeeded() {
+        if (maxSize === undefined)
+            return;
+        while (store.size >= maxSize && insertionOrder.length > 0) {
+            const oldestKey = insertionOrder.shift();
+            if (oldestKey !== undefined) {
+                store.delete(oldestKey);
+            }
+        }
+    }
+    /**
+     * Remove key from insertion order tracking.
+     *
+     * @param key - Key to remove from order tracking
+     */
+    function removeFromOrder(key) {
+        const index = insertionOrder.indexOf(key);
+        if (index !== -1) {
+            insertionOrder.splice(index, 1);
+        }
+    }
+    const cache = {
+        get(key) {
+            const entry = store.get(key);
+            if (!entry)
+                return undefined;
+            if (isExpired(entry)) {
+                store.delete(key);
+                removeFromOrder(key);
+                return undefined;
+            }
+            return entry.value;
+        },
+        set(key, value) {
+            // If key exists, remove from order first
+            if (store.has(key)) {
+                removeFromOrder(key);
+            }
+            else {
+                // Evict if needed before adding new entry
+                evictIfNeeded();
+            }
+            // eslint-disable-next-line workspace/no-unsafe-builtin-methods -- Date.now() is needed for Jest fake timers compatibility
+            store.set(key, { value, timestamp: Date.now() });
+            insertionOrder.push(key);
+        },
+        has(key) {
+            const entry = store.get(key);
+            if (!entry)
+                return false;
+            if (isExpired(entry)) {
+                store.delete(key);
+                removeFromOrder(key);
+                return false;
+            }
+            return true;
+        },
+        delete(key) {
+            removeFromOrder(key);
+            return store.delete(key);
+        },
+        clear() {
+            store.clear();
+            insertionOrder.length = 0;
+        },
+        size() {
+            return store.size;
+        },
+        keys() {
+            return [...insertionOrder];
+        },
+    };
+    // Register cache for global operations
+    cacheRegistry.add(cache);
+    return freeze(cache);
+}
+
+createScopedLogger('project-scope:heuristics:entry-points');
+/**
+ * Cache for entry point discovery results.
+ * TTL: 60 seconds (entry points are relatively stable)
+ */
+createCache({ ttl: 60000, maxSize: 50 });
+
+createScopedLogger('project-scope:tech');
+/**
+ * Cache for tech detection results.
+ * TTL: 60 seconds (tech stack can change during active development)
+ */
+createCache({ ttl: 60000, maxSize: 50 });
+
+createScopedLogger('project-scope:heuristics:project-type');
+
+createScopedLogger('project-scope:nx');
+
+createScopedLogger('project-scope:nx:devkit');
+
+createScopedLogger('project-scope:nx:config');
+
+createScopedLogger('project-scope:config');
+/**
+ * Cache for config detection results.
+ * TTL: 30 seconds (configs can change frequently during setup)
+ */
+createCache({ ttl: 30000, maxSize: 50 });
+
+/** Logger for analysis operations */
+createScopedLogger('project-scope:analyze');
+
+/** Logger for CLI operations */
+createScopedLogger('project-scope:cli');
+
+createScopedLogger('project-scope:encoding');
+
+createScopedLogger('project-scope:encoding:convert');
+
+createScopedLogger('project-scope:heuristics:framework');
+/**
+ * Cache for framework identification results.
+ * TTL: 60 seconds (frameworks are stable but can change during development)
+ */
+createCache({ ttl: 60000, maxSize: 50 });
+
+createScopedLogger('project-scope:vfs:tree');
+
+createScopedLogger('project-scope:vfs:factory');
+
+createScopedLogger('project-scope:vfs');
+
+createScopedLogger('project-scope:vfs:diff');
+
 /**
  * Changelog Discovery
  *
@@ -2055,12 +2055,6 @@ function discoverAllChangelogs(workspaceRoot, patterns = ['**/CHANGELOG.md', '**
     return results;
 }
 
-/**
- * Package Discovery
- *
- * Discovers packages within a workspace by finding package.json files
- * and extracting relevant metadata. Uses project-scope for file operations.
- */
 /**
  * Discovers all packages within a workspace.
  * Finds package.json files, parses them, and optionally discovers