@hyperfrontend/versioning 0.1.0

package/workspace/index.cjs.js

@@ -0,0 +1,4445 @@
+'use strict';
+
+var node_path = require('node:path');
+require('node:util');
+var node_fs = require('node:fs');
+require('node:os');
+
+/**
+ * Safe copies of Map built-in via factory function.
+ *
+ * Since constructors cannot be safely captured via Object.assign, this module
+ * provides a factory function that uses Reflect.construct internally.
+ *
+ * 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/map
+ */
+// Capture references at module initialization time
+const _Map = globalThis.Map;
+const _Reflect$2 = globalThis.Reflect;
+/**
+ * (Safe copy) Creates a new Map using the captured Map constructor.
+ * Use this instead of `new Map()`.
+ *
+ * @param iterable - Optional iterable of key-value pairs.
+ * @returns A new Map instance.
+ */
+const createMap = (iterable) => _Reflect$2.construct(_Map, iterable ? [iterable] : []);
+
+/**
+ * Safe copies of Console 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/console
+ */
+// Capture references at module initialization time
+const _console = globalThis.console;
+/**
+ * (Safe copy) Outputs a message to the console.
+ */
+const log = _console.log.bind(_console);
+/**
+ * (Safe copy) Outputs a warning message to the console.
+ */
+const warn = _console.warn.bind(_console);
+/**
+ * (Safe copy) Outputs an error message to the console.
+ */
+const error = _console.error.bind(_console);
+/**
+ * (Safe copy) Outputs an informational message to the console.
+ */
+const info = _console.info.bind(_console);
+/**
+ * (Safe copy) Outputs a debug message to the console.
+ */
+const debug = _console.debug.bind(_console);
+/**
+ * (Safe copy) Outputs a stack trace to the console.
+ */
+_console.trace.bind(_console);
+/**
+ * (Safe copy) Displays an interactive listing of the properties of a specified object.
+ */
+_console.dir.bind(_console);
+/**
+ * (Safe copy) Displays tabular data as a table.
+ */
+_console.table.bind(_console);
+/**
+ * (Safe copy) Writes an error message to the console if the assertion is false.
+ */
+_console.assert.bind(_console);
+/**
+ * (Safe copy) Clears the console.
+ */
+_console.clear.bind(_console);
+/**
+ * (Safe copy) Logs the number of times that this particular call to count() has been called.
+ */
+_console.count.bind(_console);
+/**
+ * (Safe copy) Resets the counter used with console.count().
+ */
+_console.countReset.bind(_console);
+/**
+ * (Safe copy) Creates a new inline group in the console.
+ */
+_console.group.bind(_console);
+/**
+ * (Safe copy) Creates a new inline group in the console that is initially collapsed.
+ */
+_console.groupCollapsed.bind(_console);
+/**
+ * (Safe copy) Exits the current inline group.
+ */
+_console.groupEnd.bind(_console);
+/**
+ * (Safe copy) Starts a timer with a name specified as an input parameter.
+ */
+_console.time.bind(_console);
+/**
+ * (Safe copy) Stops a timer that was previously started.
+ */
+_console.timeEnd.bind(_console);
+/**
+ * (Safe copy) Logs the current value of a timer that was previously started.
+ */
+_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;
+
+/**
+ * Safe copies of Set built-in via factory function.
+ *
+ * Since constructors cannot be safely captured via Object.assign, this module
+ * provides a factory function that uses Reflect.construct internally.
+ *
+ * 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/set
+ */
+// Capture references at module initialization time
+const _Set = globalThis.Set;
+const _Reflect$1 = globalThis.Reflect;
+/**
+ * (Safe copy) Creates a new Set using the captured Set constructor.
+ * Use this instead of `new Set()`.
+ *
+ * @param iterable - Optional iterable of values.
+ * @returns A new Set instance.
+ */
+const createSet = (iterable) => _Reflect$1.construct(_Set, iterable ? [iterable] : []);
+
+const registeredClasses = [];
+
+/**
+ * Returns the data type of the target.
+ * Uses native `typeof` operator, however, makes distinction between `null`, `array`, and `object`.
+ * Also, when classes are registered via `registerClass`, it checks if objects are instance of any known registered class.
+ *
+ * @param target - The target to get the data type of.
+ * @returns The data type of the target.
+ */
+const getType = (target) => {
+    if (target === null)
+        return 'null';
+    const nativeDataType = typeof target;
+    if (nativeDataType === 'object') {
+        if (isArray(target))
+            return 'array';
+        for (const registeredClass of registeredClasses) {
+            if (target instanceof registeredClass)
+                return registeredClass.name;
+        }
+    }
+    return nativeDataType;
+};
+
+/**
+ * Safe copies of Error built-ins via factory functions.
+ *
+ * Since constructors cannot be safely captured via Object.assign, this module
+ * provides factory functions that use Reflect.construct internally.
+ *
+ * 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/error
+ */
+// Capture references at module initialization time
+const _Error = globalThis.Error;
+const _Reflect = globalThis.Reflect;
+/**
+ * (Safe copy) Creates a new Error using the captured Error constructor.
+ * Use this instead of `new Error()`.
+ *
+ * @param message - Optional error message.
+ * @param options - Optional error options.
+ * @returns A new Error instance.
+ */
+const createError = (message, options) => _Reflect.construct(_Error, [message, options]);
+
+/**
+ * Safe copies of Math 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/math
+ */
+// Capture references at module initialization time
+const _Math = globalThis.Math;
+// ============================================================================
+// Min/Max
+// ============================================================================
+/**
+ * (Safe copy) Returns the larger of zero or more numbers.
+ */
+const max = _Math.max;
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Creates a wrapper function that only executes the wrapped function if the condition function returns true.
+ *
+ * @param func - The function to be conditionally executed.
+ * @param conditionFunc - A function that returns a boolean, determining if `func` should be executed.
+ * @returns A wrapped version of `func` that executes conditionally.
+ */
+function createConditionalExecutionFunction(func, conditionFunc) {
+    return function (...args) {
+        if (conditionFunc()) {
+            return func(...args);
+        }
+    };
+}
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Creates a wrapper function that silently ignores any errors thrown by the wrapped void function.
+ * This function is specifically for wrapping functions that do not return a value (void functions).
+ * Exceptions are swallowed without any logging or handling.
+ *
+ * @param func - The void function to be wrapped.
+ * @returns A wrapped version of the input function that ignores errors.
+ */
+function createErrorIgnoringFunction(func) {
+    return function (...args) {
+        try {
+            func(...args);
+        }
+        catch {
+            // Deliberately swallowing/ignoring the exception
+        }
+    };
+}
+
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/**
+ * A no-operation function (noop) that does nothing regardless of the arguments passed.
+ * It is designed to be as permissive as possible in its typing without using the `Function` keyword.
+ *
+ * @param args - Any arguments passed to the function (ignored)
+ */
+const noop = (...args) => {
+    // Intentionally does nothing
+};
+
+const logLevels = ['none', 'error', 'warn', 'log', 'info', 'debug'];
+const priority = {
+    error: 4,
+    warn: 3,
+    log: 2,
+    info: 1,
+    debug: 0,
+};
+/**
+ * Validates whether a given string is a valid log level.
+ *
+ * @param level - The log level to validate
+ * @returns True if the level is valid, false otherwise
+ */
+function isValidLogLevel(level) {
+    return logLevels.includes(level);
+}
+/**
+ * Creates a log level configuration manager for controlling logging behavior.
+ * Provides methods to get, set, and evaluate log levels based on priority.
+ *
+ * @param level - The initial log level (defaults to 'error')
+ * @returns A configuration object with log level management methods
+ * @throws {Error} When the provided level is not a valid log level
+ */
+function createLogLevelConfig(level = 'error') {
+    if (!isValidLogLevel(level)) {
+        throw createError('Cannot create log level configuration with a valid default log level');
+    }
+    const state = { level };
+    const getLogLevel = () => state.level;
+    const setLogLevel = (level) => {
+        if (!isValidLogLevel(level)) {
+            throw createError(`Cannot set value '${level}' level. Expected levels are ${logLevels}.`);
+        }
+        state.level = level;
+    };
+    const shouldLog = (level) => {
+        if (state.level === 'none' || level === 'none' || !isValidLogLevel(level)) {
+            return false;
+        }
+        return priority[level] >= priority[state.level];
+    };
+    return freeze({
+        getLogLevel,
+        setLogLevel,
+        shouldLog,
+    });
+}
+
+/**
+ * Creates a logger instance with configurable log level filtering.
+ * Each log function is wrapped to respect the current log level setting.
+ *
+ * @param error - Function to handle error-level logs (required)
+ * @param warn - Function to handle warning-level logs (optional, defaults to noop)
+ * @param log - Function to handle standard logs (optional, defaults to noop)
+ * @param info - Function to handle info-level logs (optional, defaults to noop)
+ * @param debug - Function to handle debug-level logs (optional, defaults to noop)
+ * @returns A frozen logger object with log methods and level control
+ * @throws {ErrorLevelFn} When any provided log function is invalid
+ */
+function createLogger(error, warn = noop, log = noop, info = noop, debug = noop) {
+    if (notValidLogFn(error)) {
+        throw createError(notFnMsg('error'));
+    }
+    if (notValidLogFn(warn)) {
+        throw createError(notFnMsg('warn'));
+    }
+    if (notValidLogFn(log)) {
+        throw createError(notFnMsg('log'));
+    }
+    if (notValidLogFn(info)) {
+        throw createError(notFnMsg('info'));
+    }
+    if (notValidLogFn(debug)) {
+        throw createError(notFnMsg('debug'));
+    }
+    const { setLogLevel, getLogLevel, shouldLog } = createLogLevelConfig();
+    const wrapLogFn = (fn, level) => {
+        if (fn === noop)
+            return fn;
+        const condition = () => shouldLog(level);
+        return createConditionalExecutionFunction(createErrorIgnoringFunction(fn), condition);
+    };
+    return freeze({
+        error: wrapLogFn(error, 'error'),
+        warn: wrapLogFn(warn, 'warn'),
+        log: wrapLogFn(log, 'log'),
+        info: wrapLogFn(info, 'info'),
+        debug: wrapLogFn(debug, 'debug'),
+        setLogLevel,
+        getLogLevel,
+    });
+}
+/**
+ * Validates whether a given value is a valid log function.
+ *
+ * @param fn - The value to validate
+ * @returns True if the value is not a function (invalid), false if it is valid
+ */
+function notValidLogFn(fn) {
+    return getType(fn) !== 'function' && fn !== noop;
+}
+/**
+ * Generates an error message for invalid log function parameters.
+ *
+ * @param label - The name of the log function that failed validation
+ * @returns A formatted error message string
+ */
+function notFnMsg(label) {
+    return `Cannot create a logger when ${label} is not a function`;
+}
+
+createLogger(error, warn, log, info, debug);
+
+/**
+ * Global log level registry.
+ * Tracks all created scoped loggers to allow global log level changes.
+ */
+const loggerRegistry = createSet();
+/** Redacted placeholder for sensitive values */
+const REDACTED = '[REDACTED]';
+/**
+ * Patterns that indicate a sensitive key name.
+ * Keys containing these patterns will have their values sanitized.
+ */
+const SENSITIVE_KEY_PATTERNS = [
+    /token/i,
+    /key/i,
+    /password/i,
+    /secret/i,
+    /credential/i,
+    /auth/i,
+    /bearer/i,
+    /api[_-]?key/i,
+    /private/i,
+    /passphrase/i,
+];
+/**
+ * Checks if a key name indicates sensitive data.
+ *
+ * @param key - Key name to check
+ * @returns True if the key indicates sensitive data
+ */
+function isSensitiveKey(key) {
+    return SENSITIVE_KEY_PATTERNS.some((pattern) => pattern.test(key));
+}
+/**
+ * Sanitizes an object by replacing sensitive values with REDACTED.
+ * This function recursively processes nested objects and arrays.
+ *
+ * @param obj - Object to sanitize
+ * @returns New object with sensitive values redacted
+ */
+function sanitize(obj) {
+    if (obj === null || obj === undefined) {
+        return obj;
+    }
+    if (isArray(obj)) {
+        return obj.map((item) => sanitize(item));
+    }
+    if (typeof obj === 'object') {
+        const result = {};
+        for (const [key, value] of entries(obj)) {
+            if (isSensitiveKey(key)) {
+                result[key] = REDACTED;
+            }
+            else if (typeof value === 'object' && value !== null) {
+                result[key] = sanitize(value);
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+    return obj;
+}
+/**
+ * Formats a log message with optional metadata.
+ *
+ * @param namespace - Logger namespace prefix
+ * @param message - Log message
+ * @param meta - Optional metadata object
+ * @returns Formatted log string
+ */
+function formatMessage(namespace, message, meta) {
+    const prefix = `[${namespace}]`;
+    if (meta && keys(meta).length > 0) {
+        const sanitizedMeta = sanitize(meta);
+        return `${prefix} ${message} ${stringify(sanitizedMeta)}`;
+    }
+    return `${prefix} ${message}`;
+}
+/**
+ * Creates a scoped logger with namespace prefix and optional secret sanitization.
+ * All log messages will be prefixed with [namespace] and sensitive metadata
+ * values will be automatically redacted.
+ *
+ * @param namespace - Logger namespace (e.g., 'project-scope', 'analyze')
+ * @param options - Logger configuration options
+ * @returns A configured scoped logger instance
+ *
+ * @example
+ * ```typescript
+ * const logger = createScopedLogger('project-scope')
+ * logger.setLogLevel('debug')
+ *
+ * // Basic logging
+ * logger.info('Starting analysis', { path: './project' })
+ *
+ * // Sensitive data is automatically redacted
+ * logger.debug('Config loaded', { apiKey: 'secret123' })
+ * // Output: [project-scope] Config loaded {"apiKey":"[REDACTED]"}
+ * ```
+ */
+function createScopedLogger(namespace, options = {}) {
+    const { level = 'error', sanitizeSecrets = true } = options;
+    // Create wrapper functions that add namespace prefix and sanitization
+    const createLogFn = (baseFn) => (message, meta) => {
+        const processedMeta = sanitizeSecrets && meta ? sanitize(meta) : meta;
+        baseFn(formatMessage(namespace, message, processedMeta));
+    };
+    // Create base logger with wrapped functions
+    const baseLogger = createLogger(createLogFn(error), createLogFn(warn), createLogFn(log), createLogFn(info), createLogFn(debug));
+    // Set initial log level (use global override if set)
+    baseLogger.setLogLevel(level);
+    const scopedLogger = freeze({
+        error: (message, meta) => baseLogger.error(message, meta),
+        warn: (message, meta) => baseLogger.warn(message, meta),
+        log: (message, meta) => baseLogger.log(message, meta),
+        info: (message, meta) => baseLogger.info(message, meta),
+        debug: (message, meta) => baseLogger.debug(message, meta),
+        setLogLevel: baseLogger.setLogLevel,
+        getLogLevel: baseLogger.getLogLevel,
+    });
+    // Register logger for global level management
+    loggerRegistry.add(scopedLogger);
+    return scopedLogger;
+}
+/**
+ * Default logger instance for the project-scope library.
+ * Use this for general logging within the library.
+ *
+ * @example
+ * ```typescript
+ * import { logger } from '@hyperfrontend/project-scope/core'
+ *
+ * logger.setLogLevel('debug')
+ * logger.debug('Analyzing project', { path: './src' })
+ * ```
+ */
+createScopedLogger('project-scope');
+
+const fsLogger = createScopedLogger('project-scope:fs');
+/**
+ * Create a file system error with code and context.
+ *
+ * @param message - The error message describing what went wrong
+ * @param code - The category code for this type of filesystem failure
+ * @param context - Additional context including path, operation, and cause
+ * @returns A configured Error object with code and context properties
+ */
+function createFileSystemError(message, code, context) {
+    const error = createError(message);
+    defineProperties(error, {
+        code: { value: code, enumerable: true },
+        context: { value: context, enumerable: true },
+    });
+    return error;
+}
+/**
+ * Read file contents as string.
+ *
+ * @param filePath - Path to file
+ * @param encoding - File encoding (default: utf-8)
+ * @returns File contents as string
+ * @throws {Error} If file doesn't exist or can't be read
+ *
+ * @example
+ * ```typescript
+ * import { readFileContent } from '@hyperfrontend/project-scope'
+ *
+ * const content = readFileContent('./package.json')
+ * console.log(content) // JSON string
+ * ```
+ */
+function readFileContent(filePath, encoding = 'utf-8') {
+    if (!node_fs.existsSync(filePath)) {
+        fsLogger.debug('File not found', { path: filePath });
+        throw createFileSystemError(`File not found: ${filePath}`, 'FS_NOT_FOUND', { path: filePath, operation: 'read' });
+    }
+    try {
+        return node_fs.readFileSync(filePath, { encoding });
+    }
+    catch (error) {
+        fsLogger.warn('Failed to read file', { path: filePath });
+        throw createFileSystemError(`Failed to read file: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read', cause: error });
+    }
+}
+/**
+ * Read file if exists, return null otherwise.
+ *
+ * @param filePath - Path to file
+ * @param encoding - File encoding (default: utf-8)
+ * @returns File contents or null if file doesn't exist
+ */
+function readFileIfExists(filePath, encoding = 'utf-8') {
+    if (!node_fs.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        return node_fs.readFileSync(filePath, { encoding });
+    }
+    catch {
+        return null;
+    }
+}
+
+const fsWriteLogger = createScopedLogger('project-scope:fs:write');
+/**
+ * Ensure directory exists, create recursively if not.
+ *
+ * @param dirPath - Directory path to ensure exists
+ */
+function ensureDir(dirPath) {
+    if (!node_fs.existsSync(dirPath)) {
+        fsWriteLogger.debug('Creating directory recursively', { path: dirPath });
+        node_fs.mkdirSync(dirPath, { recursive: true });
+    }
+}
+/**
+ * Write string content to file.
+ * Creates parent directories if needed.
+ *
+ * @param filePath - Absolute or relative path to the target file
+ * @param content - String content to write to the file
+ * @param options - Optional write configuration (encoding, mode)
+ * @throws {Error} If write fails
+ *
+ * @example
+ * ```typescript
+ * import { writeFileContent } from '@hyperfrontend/project-scope'
+ *
+ * // Write a simple text file
+ * writeFileContent('./output/data.txt', 'Hello, World!')
+ *
+ * // Write with custom encoding
+ * writeFileContent('./output/data.txt', 'Content', { encoding: 'utf-8' })
+ * ```
+ */
+function writeFileContent(filePath, content, options) {
+    try {
+        fsWriteLogger.debug('Writing file content', { path: filePath, size: content.length, encoding: options?.encoding ?? 'utf-8' });
+        ensureDir(node_path.dirname(filePath));
+        node_fs.writeFileSync(filePath, content, {
+            encoding: options?.encoding ?? 'utf-8',
+            mode: options?.mode,
+        });
+        fsWriteLogger.debug('File written successfully', { path: filePath });
+    }
+    catch (error) {
+        fsWriteLogger.warn('Failed to write file', { path: filePath, error: error instanceof Error ? error.message : String(error) });
+        throw createFileSystemError(`Failed to write file: ${filePath}`, 'FS_WRITE_ERROR', { path: filePath, operation: 'write', cause: error });
+    }
+}
+
+/**
+ * Get file stats with error handling.
+ *
+ * @param filePath - Path to file
+ * @param followSymlinks - Whether to follow symlinks (default: true)
+ * @returns File stats or null if path doesn't exist
+ */
+function getFileStat(filePath, followSymlinks = true) {
+    if (!node_fs.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const stat = followSymlinks ? node_fs.statSync(filePath) : node_fs.lstatSync(filePath);
+        return {
+            isFile: stat.isFile(),
+            isDirectory: stat.isDirectory(),
+            isSymlink: stat.isSymbolicLink(),
+            size: stat.size,
+            created: stat.birthtime,
+            modified: stat.mtime,
+            accessed: stat.atime,
+            mode: stat.mode,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if path is a directory.
+ *
+ * @param dirPath - Path to check
+ * @returns True if path is a directory
+ */
+function isDirectory(dirPath) {
+    const stats = getFileStat(dirPath);
+    return stats?.isDirectory ?? false;
+}
+/**
+ * Check if path exists.
+ *
+ * @param filePath - Path to check
+ * @returns True if path exists
+ */
+function exists(filePath) {
+    return node_fs.existsSync(filePath);
+}
+
+const fsDirLogger = createScopedLogger('project-scope:fs:dir');
+/**
+ * List immediate contents of a directory.
+ *
+ * @param dirPath - Absolute or relative path to the directory
+ * @returns Array of entries with metadata for each file/directory
+ * @throws {Error} If directory doesn't exist or isn't a directory
+ *
+ * @example
+ * ```typescript
+ * import { readDirectory } from '@hyperfrontend/project-scope'
+ *
+ * const entries = readDirectory('./src')
+ * for (const entry of entries) {
+ *   console.log(entry.name, entry.isFile ? 'file' : 'directory')
+ * }
+ * ```
+ */
+function readDirectory(dirPath) {
+    fsDirLogger.debug('Reading directory', { path: dirPath });
+    if (!node_fs.existsSync(dirPath)) {
+        fsDirLogger.debug('Directory not found', { path: dirPath });
+        throw createFileSystemError(`Directory not found: ${dirPath}`, 'FS_NOT_FOUND', { path: dirPath, operation: 'readdir' });
+    }
+    if (!isDirectory(dirPath)) {
+        fsDirLogger.debug('Path is not a directory', { path: dirPath });
+        throw createFileSystemError(`Not a directory: ${dirPath}`, 'FS_NOT_A_DIRECTORY', { path: dirPath, operation: 'readdir' });
+    }
+    try {
+        const entries = node_fs.readdirSync(dirPath, { withFileTypes: true });
+        fsDirLogger.debug('Directory read complete', { path: dirPath, entryCount: entries.length });
+        return entries.map((entry) => ({
+            name: entry.name,
+            path: node_path.join(dirPath, entry.name),
+            isFile: entry.isFile(),
+            isDirectory: entry.isDirectory(),
+            isSymlink: entry.isSymbolicLink(),
+        }));
+    }
+    catch (error) {
+        fsDirLogger.warn('Failed to read directory', { path: dirPath, error: error instanceof Error ? error.message : String(error) });
+        throw createFileSystemError(`Failed to read directory: ${dirPath}`, 'FS_READ_ERROR', {
+            path: dirPath,
+            operation: 'readdir',
+            cause: error,
+        });
+    }
+}
+
+/**
+ * Join path segments.
+ * Uses platform-specific separators (e.g., / or \).
+ *
+ * @param paths - Path segments to join
+ * @returns Joined path
+ */
+function join(...paths) {
+    return node_path.join(...paths);
+}
+
+const fsTraversalLogger = createScopedLogger('project-scope:fs:traversal');
+/**
+ * Generic upward directory traversal.
+ * Name avoids similarity to fs.readdir/fs.readdirSync.
+ *
+ * @param startPath - Starting directory
+ * @param predicate - Function to test each directory
+ * @returns First matching directory or null
+ */
+function traverseUpward(startPath, predicate) {
+    fsTraversalLogger.debug('Starting upward traversal', { startPath });
+    let currentPath = node_path.resolve(startPath);
+    const rootPath = node_path.parse(currentPath).root;
+    while (currentPath !== rootPath) {
+        if (predicate(currentPath)) {
+            fsTraversalLogger.debug('Upward traversal found match', { startPath, foundPath: currentPath });
+            return currentPath;
+        }
+        currentPath = node_path.dirname(currentPath);
+    }
+    // Check root directory
+    if (predicate(rootPath)) {
+        fsTraversalLogger.debug('Upward traversal found match at root', { startPath, foundPath: rootPath });
+        return rootPath;
+    }
+    fsTraversalLogger.debug('Upward traversal found no match', { startPath });
+    return null;
+}
+/**
+ * Find directory containing any of the specified marker files.
+ *
+ * @param startPath - Starting directory
+ * @param markers - Array of marker file names to search for
+ * @returns First directory containing any marker, or null
+ */
+function locateByMarkers(startPath, markers) {
+    fsTraversalLogger.debug('Locating by markers', { startPath, markers });
+    const result = traverseUpward(startPath, (dir) => markers.some((marker) => exists(join(dir, marker))));
+    if (result) {
+        fsTraversalLogger.debug('Found directory with marker', { startPath, foundPath: result });
+    }
+    return result;
+}
+/**
+ * Find directory where predicate returns true, starting from given path.
+ *
+ * @param startPath - Starting directory
+ * @param test - Function to test if directory matches criteria
+ * @returns Matching directory path or null
+ */
+function findUpwardWhere(startPath, test) {
+    fsTraversalLogger.debug('Finding upward where condition met', { startPath });
+    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,
+ * used for validating dependency maps and script definitions.
+ *
+ * @param value - Value to check
+ * @returns True if value is a record of strings
+ */
+function isStringRecord(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    return values(value).every((v) => typeof v === 'string');
+}
+/**
+ * Extracts and normalizes the workspaces field from package.json,
+ * supporting both array format and object with packages array.
+ *
+ * @param value - Raw workspaces value from package.json
+ * @returns Normalized workspace patterns or undefined if invalid
+ */
+function parseWorkspaces(value) {
+    if (isArray(value) && value.every((v) => typeof v === 'string')) {
+        return value;
+    }
+    if (typeof value === 'object' && value !== null) {
+        const obj = value;
+        if (isArray(obj['packages'])) {
+            return { packages: obj['packages'] };
+        }
+    }
+    return undefined;
+}
+/**
+ * Validate and normalize package.json data.
+ *
+ * @param data - Raw parsed data
+ * @returns Validated package.json
+ */
+function validatePackageJson(data) {
+    if (typeof data !== 'object' || data === null) {
+        throw createError('package.json must be an object');
+    }
+    const pkg = data;
+    return {
+        name: typeof pkg['name'] === 'string' ? pkg['name'] : undefined,
+        version: typeof pkg['version'] === 'string' ? pkg['version'] : undefined,
+        description: typeof pkg['description'] === 'string' ? pkg['description'] : undefined,
+        main: typeof pkg['main'] === 'string' ? pkg['main'] : undefined,
+        module: typeof pkg['module'] === 'string' ? pkg['module'] : undefined,
+        browser: typeof pkg['browser'] === 'string' ? pkg['browser'] : undefined,
+        types: typeof pkg['types'] === 'string' ? pkg['types'] : undefined,
+        bin: typeof pkg['bin'] === 'string' || isStringRecord(pkg['bin']) ? pkg['bin'] : undefined,
+        scripts: isStringRecord(pkg['scripts']) ? pkg['scripts'] : undefined,
+        dependencies: isStringRecord(pkg['dependencies']) ? pkg['dependencies'] : undefined,
+        devDependencies: isStringRecord(pkg['devDependencies']) ? pkg['devDependencies'] : undefined,
+        peerDependencies: isStringRecord(pkg['peerDependencies']) ? pkg['peerDependencies'] : undefined,
+        optionalDependencies: isStringRecord(pkg['optionalDependencies']) ? pkg['optionalDependencies'] : undefined,
+        workspaces: parseWorkspaces(pkg['workspaces']),
+        exports: typeof pkg['exports'] === 'object' ? pkg['exports'] : undefined,
+        engines: isStringRecord(pkg['engines']) ? pkg['engines'] : undefined,
+        ...pkg,
+    };
+}
+/**
+ * Reads and parses package.json from a directory, validating
+ * the structure and normalizing fields to the PackageJson interface.
+ *
+ * @param projectPath - Project directory path or path to package.json
+ * @returns Parsed package.json
+ * @throws {Error} Error if file doesn't exist or is invalid
+ */
+function readPackageJson(projectPath) {
+    const packageJsonPath = projectPath.endsWith('package.json') ? projectPath : node_path.join(projectPath, 'package.json');
+    packageLogger.debug('Reading package.json', { path: packageJsonPath });
+    const content = readFileContent(packageJsonPath);
+    try {
+        const data = parse(content);
+        const validated = validatePackageJson(data);
+        packageLogger.debug('Package.json read successfully', { path: packageJsonPath, name: validated.name });
+        return validated;
+    }
+    catch (error) {
+        packageLogger.warn('Failed to parse package.json', {
+            path: packageJsonPath,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        throw createConfigError(`Failed to parse package.json: ${packageJsonPath}`, 'CONFIG_PARSE_ERROR', {
+            filePath: packageJsonPath,
+            cause: error,
+        });
+    }
+}
+/**
+ * Attempts to read and parse package.json if it exists,
+ * returning null on missing file or parse failure.
+ *
+ * @param projectPath - Project directory path or path to package.json
+ * @returns Parsed package.json or null if not found
+ */
+function readPackageJsonIfExists(projectPath) {
+    const packageJsonPath = projectPath.endsWith('package.json') ? projectPath : node_path.join(projectPath, 'package.json');
+    const content = readFileIfExists(packageJsonPath);
+    if (!content) {
+        packageLogger.debug('Package.json not found', { path: packageJsonPath });
+        return null;
+    }
+    try {
+        const validated = validatePackageJson(parse(content));
+        packageLogger.debug('Package.json loaded', { path: packageJsonPath, name: validated.name });
+        return validated;
+    }
+    catch {
+        packageLogger.debug('Failed to parse package.json, returning null', { path: packageJsonPath });
+        return null;
+    }
+}
+/**
+ * Find nearest package.json by walking up the directory tree.
+ *
+ * @param startPath - Starting path
+ * @returns Path to directory containing package.json, or null if not found
+ */
+function findNearestPackageJson(startPath) {
+    return locateByMarkers(startPath, ['package.json']);
+}
+
+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);
+}
+
+/**
+ * Pattern matching utilities with ReDoS protection.
+ * Uses character-by-character matching instead of regex where possible.
+ */
+/**
+ * Match path against glob pattern using safe character iteration.
+ * Avoids regex to prevent ReDoS attacks.
+ *
+ * Supported patterns:
+ * - * matches any characters except /
+ * - ** matches any characters including /
+ * - ? matches exactly one character except /
+ * - {a,b,c} matches any of the alternatives
+ *
+ * @param path - The filesystem path to test against the pattern
+ * @param pattern - The glob pattern to match against
+ * @returns True if path matches pattern
+ *
+ * @example
+ * ```typescript
+ * import { matchGlobPattern } from '@hyperfrontend/project-scope'
+ *
+ * matchGlobPattern('src/utils/helper.ts', '\*\*\/*.ts')     // true
+ * matchGlobPattern('test.spec.ts', '\*.spec.ts')          // true
+ * matchGlobPattern('config.json', '\*.{json,yaml}')       // true
+ * matchGlobPattern('src/index.ts', 'src/\*.ts')           // true
+ * ```
+ */
+function matchGlobPattern(path, pattern) {
+    return matchSegments(path.split('/'), pattern.split('/'), 0, 0);
+}
+/**
+ * Internal recursive function to match path segments against pattern segments.
+ *
+ * @param pathParts - Array of path segments split by '/'
+ * @param patternParts - Array of pattern segments split by '/'
+ * @param pathIdx - Current index in pathParts being examined
+ * @param patternIdx - Current index in patternParts being examined
+ * @returns True if remaining segments match
+ */
+function matchSegments(pathParts, patternParts, pathIdx, patternIdx) {
+    // Base cases
+    if (pathIdx === pathParts.length && patternIdx === patternParts.length) {
+        return true; // Both exhausted = match
+    }
+    if (patternIdx >= patternParts.length) {
+        return false; // Pattern exhausted but path remains
+    }
+    const patternPart = patternParts[patternIdx];
+    // Handle ** (globstar) - matches zero or more directories
+    if (patternPart === '**') {
+        // Try matching rest of pattern against current position and all future positions
+        for (let i = pathIdx; i <= pathParts.length; i++) {
+            if (matchSegments(pathParts, patternParts, i, patternIdx + 1)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    if (pathIdx >= pathParts.length) {
+        return false; // Path exhausted but pattern remains (and it's not **)
+    }
+    const pathPart = pathParts[pathIdx];
+    // Match current segment
+    if (matchSegment(pathPart, patternPart)) {
+        return matchSegments(pathParts, patternParts, pathIdx + 1, patternIdx + 1);
+    }
+    return false;
+}
+/**
+ * Match a single path segment against a pattern segment.
+ * Handles *, ?, and {a,b,c} patterns.
+ *
+ * @param text - The path segment text to match
+ * @param pattern - The pattern segment to match against
+ * @returns True if the text matches the pattern
+ */
+function matchSegment(text, pattern) {
+    let textIdx = 0;
+    let patternIdx = 0;
+    while (patternIdx < pattern.length) {
+        const char = pattern[patternIdx];
+        if (char === '*') {
+            // * matches zero or more characters
+            patternIdx++;
+            if (patternIdx === pattern.length) {
+                return true; // * at end matches rest of string
+            }
+            // Try matching rest of pattern at each position in text
+            for (let i = textIdx; i <= text.length; i++) {
+                if (matchSegmentFrom(text, i, pattern, patternIdx)) {
+                    return true;
+                }
+            }
+            return false;
+        }
+        else if (char === '?') {
+            // ? matches exactly one character
+            if (textIdx >= text.length) {
+                return false;
+            }
+            textIdx++;
+            patternIdx++;
+        }
+        else if (char === '{') {
+            // {a,b,c} matches any alternative
+            const closeIdx = findClosingBrace(pattern, patternIdx);
+            if (closeIdx === -1) {
+                // Unmatched brace, treat as literal
+                if (textIdx >= text.length || text[textIdx] !== char) {
+                    return false;
+                }
+                textIdx++;
+                patternIdx++;
+            }
+            else {
+                const alternatives = extractAlternatives(pattern.slice(patternIdx + 1, closeIdx));
+                for (const alt of alternatives) {
+                    if (matchSegmentFrom(text, textIdx, text.slice(0, textIdx) + alt + pattern.slice(closeIdx + 1), textIdx)) {
+                        return true;
+                    }
+                }
+                return false;
+            }
+        }
+        else {
+            // Literal character
+            if (textIdx >= text.length || text[textIdx] !== char) {
+                return false;
+            }
+            textIdx++;
+            patternIdx++;
+        }
+    }
+    return textIdx === text.length;
+}
+/**
+ * Helper to match from a specific position.
+ *
+ * @param text - The full text being matched
+ * @param textIdx - The starting index in text to match from
+ * @param pattern - The full pattern being matched
+ * @param patternIdx - The starting index in pattern to match from
+ * @returns True if the text matches the pattern from the given positions
+ */
+function matchSegmentFrom(text, textIdx, pattern, patternIdx) {
+    const remainingText = text.slice(textIdx);
+    const remainingPattern = pattern.slice(patternIdx);
+    return matchSegment(remainingText, remainingPattern);
+}
+/**
+ * Find closing brace for {a,b,c} pattern.
+ *
+ * @param pattern - The pattern string to search within
+ * @param startIdx - The index of the opening brace
+ * @returns The index of the matching closing brace, or -1 if not found
+ */
+function findClosingBrace(pattern, startIdx) {
+    let depth = 0;
+    for (let i = startIdx; i < pattern.length; i++) {
+        if (pattern[i] === '{') {
+            depth++;
+        }
+        else if (pattern[i] === '}') {
+            depth--;
+            if (depth === 0) {
+                return i;
+            }
+        }
+    }
+    return -1;
+}
+/**
+ * Extract alternatives from {a,b,c} pattern content.
+ *
+ * @param content - The content between braces (without the braces themselves)
+ * @returns Array of alternative strings split by commas at depth 0
+ */
+function extractAlternatives(content) {
+    const alternatives = [];
+    let current = '';
+    let depth = 0;
+    for (let i = 0; i < content.length; i++) {
+        const char = content[i];
+        if (char === '{') {
+            depth++;
+            current += char;
+        }
+        else if (char === '}') {
+            depth--;
+            current += char;
+        }
+        else if (char === ',' && depth === 0) {
+            alternatives.push(current);
+            current = '';
+        }
+        else {
+            current += char;
+        }
+    }
+    if (current) {
+        alternatives.push(current);
+    }
+    return alternatives;
+}
+
+const walkLogger = createScopedLogger('project-scope:project:walk');
+/**
+ * Reads .gitignore file from the given directory and extracts
+ * non-comment patterns for use in file traversal filtering.
+ *
+ * @param startPath - Directory containing the .gitignore file
+ * @returns Array of gitignore patterns
+ */
+function loadGitignorePatterns(startPath) {
+    const patterns = [];
+    const gitignorePath = node_path.join(startPath, '.gitignore');
+    const content = readFileIfExists(gitignorePath);
+    if (content) {
+        const lines = content.split('\n');
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed && !trimmed.startsWith('#')) {
+                patterns.push(trimmed);
+            }
+        }
+    }
+    return patterns;
+}
+/**
+ * Evaluates whether a relative path should be ignored based on
+ * a list of gitignore-style patterns.
+ *
+ * @param relativePath - Path relative to the root directory
+ * @param patterns - Array of gitignore-style patterns to test
+ * @returns True if the path matches any ignore pattern
+ */
+function matchesIgnorePattern(relativePath, patterns) {
+    for (const pattern of patterns) {
+        if (matchPattern(relativePath, pattern)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Tests if the given path matches a gitignore-style pattern,
+ * supporting negation patterns with '!' prefix.
+ * Uses safe character-by-character matching to prevent ReDoS attacks.
+ *
+ * @param path - File or directory path to test
+ * @param pattern - Gitignore-style pattern (may include wildcards)
+ * @returns True if the path matches the pattern (or doesn't match if negated)
+ */
+function matchPattern(path, pattern) {
+    const normalizedPattern = pattern.startsWith('/') ? pattern.slice(1) : pattern;
+    const isNegation = normalizedPattern.startsWith('!');
+    const actualPattern = isNegation ? normalizedPattern.slice(1) : normalizedPattern;
+    const matchesFullPath = matchGlobPattern(path, actualPattern) || matchGlobPattern(path, `**/${actualPattern}`);
+    const matchesSegment = path.split('/').some((segment) => matchGlobPattern(segment, actualPattern));
+    const matches = matchesFullPath || matchesSegment;
+    return isNegation ? !matches : matches;
+}
+/**
+ * Traverses a directory tree synchronously, calling a visitor function
+ * for each file and directory encountered. Supports depth limiting,
+ * hidden file filtering, and gitignore pattern matching.
+ *
+ * @param startPath - Root directory to begin traversal
+ * @param visitor - Callback function invoked for each file system entry
+ * @param options - Configuration for traversal behavior
+ */
+function walkDirectory(startPath, visitor, options) {
+    walkLogger.debug('Starting directory walk', {
+        startPath,
+        maxDepth: options?.maxDepth ?? -1,
+        includeHidden: options?.includeHidden ?? false,
+        respectGitignore: options?.respectGitignore ?? true,
+        ignorePatterns: options?.ignorePatterns?.length ?? 0,
+    });
+    const maxDepth = options?.maxDepth ?? -1;
+    const includeHidden = options?.includeHidden ?? false;
+    const ignorePatterns = options?.ignorePatterns ?? [];
+    const respectGitignore = options?.respectGitignore ?? true;
+    const gitignorePatterns = respectGitignore ? loadGitignorePatterns(startPath) : [];
+    const allIgnorePatterns = [...ignorePatterns, ...gitignorePatterns];
+    if (gitignorePatterns.length > 0) {
+        walkLogger.debug('Loaded gitignore patterns', { count: gitignorePatterns.length });
+    }
+    /**
+     * Recursively walks directory entries, applying visitor to each.
+     *
+     * @param currentPath - Absolute path to current directory
+     * @param relativePath - Path relative to the starting directory
+     * @param depth - Current recursion depth
+     * @returns False to stop walking, true to continue
+     */
+    function walk(currentPath, relativePath, depth) {
+        if (maxDepth !== -1 && depth > maxDepth) {
+            return true;
+        }
+        let entries;
+        try {
+            entries = readDirectory(currentPath);
+        }
+        catch {
+            return true;
+        }
+        for (const entry of entries) {
+            if (!includeHidden && entry.name.startsWith('.')) {
+                continue;
+            }
+            const entryRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+            if (matchesIgnorePattern(entryRelativePath, allIgnorePatterns)) {
+                continue;
+            }
+            const walkEntry = {
+                name: entry.name,
+                path: entry.path,
+                relativePath: entryRelativePath,
+                isFile: entry.isFile,
+                isDirectory: entry.isDirectory,
+                isSymlink: entry.isSymlink,
+                depth,
+            };
+            const result = visitor(walkEntry);
+            if (result === 'stop') {
+                return false;
+            }
+            if (result === 'skip') {
+                continue;
+            }
+            if (entry.isDirectory) {
+                const shouldContinue = walk(entry.path, entryRelativePath, depth + 1);
+                if (!shouldContinue) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+    walk(startPath, '', 0);
+    walkLogger.debug('Directory walk complete', { startPath });
+}
+
+const searchLogger = createScopedLogger('project-scope:project:search');
+/**
+ * Tests if a path matches at least one pattern from an array of globs,
+ * enabling flexible multi-pattern file filtering.
+ * Uses safe character-by-character matching to prevent ReDoS attacks.
+ *
+ * @param path - File path to test
+ * @param patterns - Array of glob patterns
+ * @returns True if path matches any pattern
+ */
+function matchesPatterns(path, patterns) {
+    return patterns.some((pattern) => matchGlobPattern(path, pattern));
+}
+/**
+ * Searches a directory tree for files matching one or more glob patterns,
+ * returning relative or absolute paths based on options.
+ *
+ * @param startPath - Root directory to begin the search
+ * @param patterns - Glob patterns (e.g., '*.ts', '**\/*.json') to filter files
+ * @param options - Configuration for search behavior
+ * @returns List of relative file paths that match the patterns
+ *
+ * @example
+ * ```typescript
+ * import { findFiles } from '@hyperfrontend/project-scope'
+ *
+ * // Find all TypeScript files
+ * const tsFiles = findFiles('./src', '\*\*\/*.ts')
+ *
+ * // Find multiple file types
+ * const configFiles = findFiles('./', ['\*.json', '\*.yaml', '\*.yml'])
+ *
+ * // Limit results and get absolute paths
+ * const first10 = findFiles('./src', '\*\*\/*.ts', {
+ *   maxResults: 10,
+ *   absolutePaths: true
+ * })
+ * ```
+ */
+function findFiles(startPath, patterns, options) {
+    const normalizedPatterns = isArray(patterns) ? patterns : [patterns];
+    searchLogger.debug('Finding files', { startPath, patterns: normalizedPatterns, maxResults: options?.maxResults });
+    const results = [];
+    const maxResults = options?.maxResults ?? Infinity;
+    walkDirectory(startPath, (entry) => {
+        if (results.length >= maxResults) {
+            return 'stop';
+        }
+        if (!entry.isFile) {
+            return undefined;
+        }
+        if (matchesPatterns(entry.relativePath, normalizedPatterns)) {
+            results.push(options?.absolutePaths ? entry.path : entry.relativePath);
+        }
+        return undefined;
+    }, options);
+    searchLogger.debug('File search complete', { startPath, matchCount: results.length });
+    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 });
+
+/**
+ * Safe copies of Number built-in methods and constants.
+ *
+ * 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/number
+ */
+// Capture references at module initialization time
+const _parseInt = globalThis.parseInt;
+const _isNaN = globalThis.isNaN;
+// ============================================================================
+// Parsing
+// ============================================================================
+/**
+ * (Safe copy) Parses a string and returns an integer.
+ */
+const parseInt = _parseInt;
+// ============================================================================
+// Global Type Checking (legacy, less strict)
+// ============================================================================
+/**
+ * (Safe copy) Global isNaN function (coerces to number first, less strict than Number.isNaN).
+ */
+const globalIsNaN = _isNaN;
+
+/** 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');
+
+/**
+ * Dependency Graph
+ *
+ * Builds and analyzes dependency relationships between workspace projects.
+ * Provides functions for traversing the dependency graph and determining
+ * build/release order.
+ */
+/**
+ * Finds internal dependencies in a package.json.
+ * Returns names of workspace packages that this package depends on.
+ *
+ * @param packageJson - Parsed package.json content
+ * @param workspacePackageNames - Set of all package names in the workspace
+ * @returns Array of internal dependency names
+ *
+ * @example
+ * ```typescript
+ * const internalDeps = findInternalDependencies(packageJson, allPackageNames)
+ * // ['@scope/lib-a', '@scope/lib-b']
+ * ```
+ */
+function findInternalDependencies(packageJson, workspacePackageNames) {
+    const internal = [];
+    const allDeps = {
+        ...packageJson.dependencies,
+        ...packageJson.devDependencies,
+        ...packageJson.peerDependencies,
+        ...packageJson.optionalDependencies,
+    };
+    for (const depName of keys(allDeps)) {
+        if (workspacePackageNames.has(depName)) {
+            internal.push(depName);
+        }
+    }
+    return internal;
+}
+/**
+ * Finds internal dependencies with type information.
+ *
+ * @param packageName - Name of the package being analyzed
+ * @param packageJson - Parsed package.json content
+ * @param workspacePackageNames - Set of all package names in the workspace
+ * @returns Array of dependency edges with type information
+ */
+function findInternalDependenciesWithTypes(packageName, packageJson, workspacePackageNames) {
+    const edges = [];
+    const depTypes = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+    for (const depType of depTypes) {
+        const deps = packageJson[depType];
+        if (deps) {
+            for (const [depName, versionRange] of entries(deps)) {
+                if (workspacePackageNames.has(depName)) {
+                    edges.push({
+                        from: packageName,
+                        to: depName,
+                        type: depType,
+                        versionRange,
+                    });
+                }
+            }
+        }
+    }
+    return edges;
+}
+/**
+ * Builds a complete dependency graph from a list of projects.
+ *
+ * @param projects - List of projects to analyze
+ * @returns Dependency graph analysis result
+ *
+ * @example
+ * ```typescript
+ * import { buildDependencyGraph, discoverPackages } from '@hyperfrontend/versioning'
+ *
+ * const { projects } = discoverPackages()
+ * const analysis = buildDependencyGraph(projects)
+ *
+ * // Get packages that depend on 'lib-utils'
+ * const dependents = analysis.dependencyGraph.get('lib-utils') ?? []
+ *
+ * // Get packages in topological order for building
+ * const buildOrder = getTopologicalOrder(analysis)
+ * ```
+ */
+function buildDependencyGraph(projects) {
+    const packageNames = createSet(projects.map((p) => p.name));
+    const edges = [];
+    // Collect all edges
+    for (const project of projects) {
+        const projectEdges = findInternalDependenciesWithTypes(project.name, project.packageJson, packageNames);
+        edges.push(...projectEdges);
+    }
+    // Build forward graph (dependency -> dependents)
+    const dependencyGraph = createMap();
+    for (const name of packageNames) {
+        dependencyGraph.set(name, []);
+    }
+    for (const edge of edges) {
+        const dependents = dependencyGraph.get(edge.to);
+        if (dependents) {
+            dependents.push(edge.from);
+        }
+    }
+    // Build reverse graph (package -> dependencies)
+    const reverseDependencyGraph = createMap();
+    for (const name of packageNames) {
+        reverseDependencyGraph.set(name, []);
+    }
+    for (const edge of edges) {
+        const deps = reverseDependencyGraph.get(edge.from);
+        if (deps) {
+            deps.push(edge.to);
+        }
+    }
+    // Find leaf packages (no dependents)
+    const leafPackages = [];
+    for (const [name, dependents] of dependencyGraph) {
+        if (dependents.length === 0) {
+            leafPackages.push(name);
+        }
+    }
+    // Find root packages (no dependencies)
+    const rootPackages = [];
+    for (const [name, deps] of reverseDependencyGraph) {
+        if (deps.length === 0) {
+            rootPackages.push(name);
+        }
+    }
+    // Detect circular dependencies
+    const { hasCircular, cycles } = detectCircularDependencies(reverseDependencyGraph);
+    // Convert to readonly maps
+    const readonlyDependencyGraph = createMap();
+    for (const [key, value] of dependencyGraph) {
+        readonlyDependencyGraph.set(key, [...value]);
+    }
+    const readonlyReverseDependencyGraph = createMap();
+    for (const [key, value] of reverseDependencyGraph) {
+        readonlyReverseDependencyGraph.set(key, [...value]);
+    }
+    return {
+        dependencyGraph: readonlyDependencyGraph,
+        reverseDependencyGraph: readonlyReverseDependencyGraph,
+        edges,
+        leafPackages,
+        rootPackages,
+        hasCircularDependencies: hasCircular,
+        circularDependencies: cycles,
+    };
+}
+/**
+ * Detects circular dependencies in the graph using DFS.
+ *
+ * @param reverseDependencyGraph - Map of package to its dependencies
+ * @returns Detection result with cycle information
+ */
+function detectCircularDependencies(reverseDependencyGraph) {
+    const cycles = [];
+    const visited = createSet();
+    const recursionStack = createSet();
+    const path = [];
+    /**
+     * Depth-first search to detect cycles.
+     *
+     * @param node - Current node being visited
+     * @returns True if a cycle was found
+     */
+    function dfs(node) {
+        visited.add(node);
+        recursionStack.add(node);
+        path.push(node);
+        const deps = reverseDependencyGraph.get(node) ?? [];
+        for (const dep of deps) {
+            if (!visited.has(dep)) {
+                if (dfs(dep)) {
+                    return true;
+                }
+            }
+            else if (recursionStack.has(dep)) {
+                // Found a cycle
+                const cycleStart = path.indexOf(dep);
+                const cycle = path.slice(cycleStart);
+                cycle.push(dep); // Close the cycle
+                cycles.push(cycle);
+            }
+        }
+        path.pop();
+        recursionStack.delete(node);
+        return false;
+    }
+    for (const node of reverseDependencyGraph.keys()) {
+        if (!visited.has(node)) {
+            dfs(node);
+        }
+    }
+    return {
+        hasCircular: cycles.length > 0,
+        cycles,
+    };
+}
+/**
+ * Gets a topological ordering of packages for building.
+ * Packages with no dependencies come first.
+ *
+ * @param analysis - Dependency graph analysis result
+ * @returns Array of package names in build order
+ * @throws {Error} If circular dependencies exist
+ *
+ * @example
+ * ```typescript
+ * const buildOrder = getTopologicalOrder(analysis)
+ * for (const pkg of buildOrder) {
+ *   await build(pkg)
+ * }
+ * ```
+ */
+function getTopologicalOrder(analysis) {
+    if (analysis.hasCircularDependencies) {
+        throw createError(`Circular dependencies detected: ${analysis.circularDependencies.map((c) => c.join(' -> ')).join(', ')}`);
+    }
+    const result = [];
+    const inDegree = createMap();
+    const adjacency = createMap();
+    // Initialize
+    for (const [name, deps] of analysis.reverseDependencyGraph) {
+        inDegree.set(name, deps.length);
+        adjacency.set(name, []);
+    }
+    // Build adjacency list (dependency -> dependents)
+    for (const [name, deps] of analysis.reverseDependencyGraph) {
+        for (const dep of deps) {
+            const adj = adjacency.get(dep);
+            if (adj) {
+                adj.push(name);
+            }
+        }
+    }
+    // Kahn's algorithm
+    const queue = [...analysis.rootPackages];
+    while (queue.length > 0) {
+        const node = queue.shift();
+        if (node === undefined) {
+            break;
+        }
+        result.push(node);
+        const dependents = adjacency.get(node) ?? [];
+        for (const dependent of dependents) {
+            const degree = inDegree.get(dependent) ?? 0;
+            inDegree.set(dependent, degree - 1);
+            if (degree - 1 === 0) {
+                queue.push(dependent);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Gets all transitive dependents of a package (direct and indirect).
+ *
+ * @param workspace - The workspace containing projects
+ * @param packageName - Name of the package to analyze
+ * @returns Set of all packages that depend on this package
+ *
+ * @example
+ * ```typescript
+ * // If lib-a depends on lib-utils and app-main depends on lib-a
+ * // Then getTransitiveDependents('lib-utils') returns ['lib-a', 'app-main']
+ * ```
+ */
+function getTransitiveDependents(workspace, packageName) {
+    const dependents = createSet();
+    const queue = [packageName];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === undefined) {
+            break;
+        }
+        const directDependents = workspace.dependencyGraph.get(current) ?? [];
+        for (const dep of directDependents) {
+            if (!dependents.has(dep)) {
+                dependents.add(dep);
+                queue.push(dep);
+            }
+        }
+    }
+    return dependents;
+}
+/**
+ * Gets all transitive dependencies of a package (direct and indirect).
+ *
+ * @param workspace - The workspace containing projects
+ * @param packageName - Name of the package to analyze
+ * @returns Set of all packages this package depends on
+ */
+function getTransitiveDependencies(workspace, packageName) {
+    const dependencies = createSet();
+    const queue = [packageName];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === undefined) {
+            break;
+        }
+        const directDeps = workspace.reverseDependencyGraph.get(current) ?? [];
+        for (const dep of directDeps) {
+            if (!dependencies.has(dep)) {
+                dependencies.add(dep);
+                queue.push(dep);
+            }
+        }
+    }
+    return dependencies;
+}
+/**
+ * Checks if package A transitively depends on package B.
+ *
+ * @param workspace - The workspace containing projects
+ * @param packageA - Name of the potentially dependent package
+ * @param packageB - Name of the potential dependency
+ * @returns True if packageA transitively depends on packageB
+ */
+function transitivelyDependsOn(workspace, packageA, packageB) {
+    const deps = getTransitiveDependencies(workspace, packageA);
+    return deps.has(packageB);
+}
+
+/**
+ * Project Model
+ *
+ * Represents a single project/package within a workspace.
+ * Contains package.json data, paths, and dependency information.
+ */
+/**
+ * Creates a new Project object.
+ *
+ * @param options - Project properties
+ * @returns A new Project object
+ */
+function createProject(options) {
+    const isPrivate = options.packageJson['private'] === true;
+    const publishable = !isPrivate && options.name !== undefined && options.version !== undefined;
+    return {
+        name: options.name,
+        version: options.version,
+        path: options.path,
+        packageJsonPath: options.packageJsonPath,
+        packageJson: options.packageJson,
+        changelogPath: options.changelogPath ?? null,
+        internalDependencies: options.internalDependencies ?? [],
+        internalDependents: options.internalDependents ?? [],
+        publishable,
+        private: isPrivate,
+    };
+}
+/**
+ * Checks if a project is publishable (public and has name/version).
+ *
+ * @param project - The project to check
+ * @returns True if the project can be published
+ */
+function isPublishable(project) {
+    return project.publishable;
+}
+/**
+ * Checks if a project is private.
+ *
+ * @param project - The project to check
+ * @returns True if the project is marked as private
+ */
+function isPrivate(project) {
+    return project.private;
+}
+/**
+ * Checks if a project has a changelog file.
+ *
+ * @param project - The project to check
+ * @returns True if changelog exists
+ */
+function hasChangelog$1(project) {
+    return project.changelogPath !== null;
+}
+/**
+ * Checks if a project has any internal dependencies.
+ *
+ * @param project - The project to check
+ * @returns True if project depends on other workspace packages
+ */
+function hasInternalDependencies(project) {
+    return project.internalDependencies.length > 0;
+}
+/**
+ * Checks if a project has any internal dependents.
+ *
+ * @param project - The project to check
+ * @returns True if other workspace packages depend on this project
+ */
+function hasInternalDependents(project) {
+    return project.internalDependents.length > 0;
+}
+/**
+ * Gets the dependency count (internal dependencies).
+ *
+ * @param project - Project instance to analyze
+ * @returns Number of internal dependencies
+ */
+function getDependencyCount(project) {
+    return project.internalDependencies.length;
+}
+/**
+ * Gets the dependent count (packages that depend on this one).
+ *
+ * @param project - Project instance to analyze
+ * @returns Number of internal dependents
+ */
+function getDependentCount(project) {
+    return project.internalDependents.length;
+}
+/**
+ * Creates a copy of a project with updated internal dependents.
+ *
+ * @param project - The project to update
+ * @param dependents - New list of internal dependents
+ * @returns A new Project with updated dependents
+ */
+function withDependents(project, dependents) {
+    return {
+        ...project,
+        internalDependents: dependents,
+    };
+}
+/**
+ * Creates a copy of a project with an added internal dependent.
+ *
+ * @param project - The project to update
+ * @param dependent - Name of the dependent to add
+ * @returns A new Project with the added dependent
+ */
+function addDependent(project, dependent) {
+    if (project.internalDependents.includes(dependent)) {
+        return project;
+    }
+    return {
+        ...project,
+        internalDependents: [...project.internalDependents, dependent],
+    };
+}
+
+/**
+ * Workspace Model
+ *
+ * Represents a monorepo workspace with multiple projects.
+ * Used for package discovery, dependency tracking, and coordinated versioning.
+ */
+/**
+ * Default workspace discovery patterns.
+ */
+const DEFAULT_PATTERNS = [
+    'libs/*/package.json',
+    'apps/*/package.json',
+    'packages/*/package.json',
+    'tools/*/package.json',
+    'plugins/*/package.json',
+];
+/**
+ * Default exclusion patterns.
+ */
+const DEFAULT_EXCLUDE = ['**/node_modules/**', '**/dist/**', '**/coverage/**', '**/.git/**'];
+/**
+ * Default workspace configuration.
+ */
+const DEFAULT_WORKSPACE_CONFIG = {
+    patterns: DEFAULT_PATTERNS,
+    exclude: DEFAULT_EXCLUDE,
+    includeChangelogs: true,
+    trackDependencies: true,
+};
+/**
+ * Creates a new workspace configuration by merging with defaults.
+ *
+ * @param options - Partial configuration options
+ * @returns Complete workspace configuration
+ */
+function createWorkspaceConfig(options) {
+    return {
+        patterns: options?.patterns ?? DEFAULT_PATTERNS,
+        exclude: options?.exclude ?? DEFAULT_EXCLUDE,
+        includeChangelogs: options?.includeChangelogs ?? true,
+        trackDependencies: options?.trackDependencies ?? true,
+    };
+}
+/**
+ * Creates a new workspace object.
+ *
+ * @param options - Workspace properties
+ * @param options.root - Absolute path to workspace root directory
+ * @param options.type - Type of workspace (nx, turbo, etc.)
+ * @param options.projects - Map of project names to project objects
+ * @param options.config - Configuration used for workspace discovery
+ * @param options.dependencyGraph - Map of package names to their dependents
+ * @param options.reverseDependencyGraph - Map of package names to their dependencies
+ * @returns A new Workspace object
+ */
+function createWorkspace(options) {
+    const projectList = [...options.projects.values()].sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        root: options.root,
+        type: options.type,
+        projects: options.projects,
+        projectList,
+        config: options.config,
+        dependencyGraph: options.dependencyGraph,
+        reverseDependencyGraph: options.reverseDependencyGraph,
+    };
+}
+/**
+ * Gets a project by name from the workspace.
+ *
+ * @param workspace - Workspace to search in
+ * @param projectName - Identifier of the project to retrieve
+ * @returns The project or undefined if not found
+ */
+function getProject(workspace, projectName) {
+    return workspace.projects.get(projectName);
+}
+/**
+ * Checks if a project exists in the workspace.
+ *
+ * @param workspace - Workspace to search in
+ * @param projectName - Identifier of the project to check
+ * @returns True if the project exists
+ */
+function hasProject(workspace, projectName) {
+    return workspace.projects.has(projectName);
+}
+/**
+ * Gets all project names in the workspace.
+ *
+ * @param workspace - Workspace to retrieve project names from
+ * @returns Array of project names
+ */
+function getProjectNames(workspace) {
+    return workspace.projectList.map((p) => p.name);
+}
+/**
+ * Gets the count of projects in the workspace.
+ *
+ * @param workspace - Workspace to count projects in
+ * @returns Number of projects
+ */
+function getProjectCount(workspace) {
+    return workspace.projects.size;
+}
+/**
+ * Gets projects that depend on the given project.
+ *
+ * @param workspace - Workspace containing the dependency graph
+ * @param projectName - Name of the dependency
+ * @returns Array of dependent project names
+ */
+function getDependents(workspace, projectName) {
+    return workspace.dependencyGraph.get(projectName) ?? [];
+}
+/**
+ * Gets projects that the given project depends on.
+ *
+ * @param workspace - Workspace containing the dependency graph
+ * @param projectName - Identifier of the project to look up
+ * @returns Array of dependency project names
+ */
+function getDependencies(workspace, projectName) {
+    return workspace.reverseDependencyGraph.get(projectName) ?? [];
+}
+/**
+ * Checks if projectA depends on projectB.
+ *
+ * @param workspace - Workspace containing the dependency graph
+ * @param projectA - Name of the potentially dependent project
+ * @param projectB - Name of the potential dependency
+ * @returns True if projectA depends on projectB
+ */
+function dependsOn(workspace, projectA, projectB) {
+    const deps = getDependencies(workspace, projectA);
+    return deps.includes(projectB);
+}
+
+/**
+ * Changelog Discovery
+ *
+ * Discovers CHANGELOG.md files within workspace projects.
+ */
+/**
+ * Common changelog file names in priority order.
+ */
+const CHANGELOG_NAMES = ['CHANGELOG.md', 'Changelog.md', 'changelog.md', 'HISTORY.md', 'CHANGES.md'];
+/**
+ * Finds changelog files for a list of packages.
+ * Returns a map of project path to changelog absolute path.
+ *
+ * @param workspaceRoot - Workspace root path
+ * @param packages - List of packages to find changelogs for
+ * @returns Map of project path to changelog path
+ */
+function findChangelogs(workspaceRoot, packages) {
+    const result = createMap();
+    for (const pkg of packages) {
+        const changelogPath = findProjectChangelog(pkg.path);
+        if (changelogPath) {
+            result.set(pkg.path, changelogPath);
+        }
+    }
+    return result;
+}
+/**
+ * Finds the changelog file for a single project.
+ * Checks for common changelog names in order of priority.
+ *
+ * @param projectPath - Path to project directory
+ * @returns Absolute path to changelog or null if not found
+ *
+ * @example
+ * ```typescript
+ * import { findProjectChangelog } from '@hyperfrontend/versioning'
+ *
+ * const changelogPath = findProjectChangelog('./libs/my-lib')
+ * if (changelogPath) {
+ *   console.log('Found changelog:', changelogPath)
+ * }
+ * ```
+ */
+function findProjectChangelog(projectPath) {
+    for (const name of CHANGELOG_NAMES) {
+        const changelogPath = node_path.join(projectPath, name);
+        if (exists(changelogPath)) {
+            return changelogPath;
+        }
+    }
+    return null;
+}
+/**
+ * Discovers all changelog files within a workspace.
+ *
+ * @param workspaceRoot - Workspace root path
+ * @param patterns - Glob patterns for finding changelogs (default: all CHANGELOGs)
+ * @returns Array of discovered changelog information
+ *
+ * @example
+ * ```typescript
+ * import { discoverAllChangelogs } from '@hyperfrontend/versioning'
+ *
+ * const changelogs = discoverAllChangelogs('/path/to/workspace')
+ * for (const changelog of changelogs) {
+ *   console.log(`${changelog.projectPath} -> ${changelog.path}`)
+ * }
+ * ```
+ */
+function discoverAllChangelogs(workspaceRoot, patterns = ['**/CHANGELOG.md', '**/Changelog.md', '**/changelog.md']) {
+    const results = [];
+    const files = findFiles(workspaceRoot, [...patterns], {
+        ignorePatterns: ['**/node_modules/**', '**/dist/**'],
+        absolutePaths: false,
+    });
+    for (const relativePath of files) {
+        const absolutePath = node_path.join(workspaceRoot, relativePath);
+        const projectPath = node_path.dirname(absolutePath);
+        const filename = relativePath.split('/').pop() ?? 'CHANGELOG.md';
+        results.push({
+            path: absolutePath,
+            relativePath,
+            projectPath,
+            filename,
+        });
+    }
+    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
+ * changelogs and internal dependencies.
+ *
+ * @param options - Discovery options
+ * @returns Discovery result with all found packages
+ * @throws {Error} If workspace root cannot be found
+ *
+ * @example
+ * ```typescript
+ * import { discoverPackages } from '@hyperfrontend/versioning'
+ *
+ * // Discover all packages in current workspace
+ * const result = discoverPackages()
+ *
+ * // Discover with custom patterns
+ * const result = discoverPackages({
+ *   patterns: ['packages/*\/package.json'],
+ *   includeChangelogs: true
+ * })
+ *
+ * // Access discovered projects
+ * for (const project of result.projects) {
+ *   console.log(`${project.name}@${project.version}`)
+ * }
+ * ```
+ */
+function discoverPackages(options = {}) {
+    // Resolve workspace root
+    const workspaceRoot = options.workspaceRoot ?? findWorkspaceRoot(process.cwd());
+    if (!workspaceRoot) {
+        throw createError('Could not find workspace root. Ensure you are in a monorepo with nx.json, turbo.json, or workspaces field.');
+    }
+    // Build configuration
+    const config = {
+        patterns: options.patterns ?? DEFAULT_WORKSPACE_CONFIG.patterns,
+        exclude: options.exclude ?? DEFAULT_WORKSPACE_CONFIG.exclude,
+        includeChangelogs: options.includeChangelogs ?? DEFAULT_WORKSPACE_CONFIG.includeChangelogs,
+        trackDependencies: options.trackDependencies ?? DEFAULT_WORKSPACE_CONFIG.trackDependencies,
+    };
+    // Find all package.json files
+    const packageJsonPaths = findPackageJsonFiles(workspaceRoot, config);
+    // Parse package.json files
+    const rawPackages = parsePackageJsonFiles(workspaceRoot, packageJsonPaths);
+    // Collect all package names for internal dependency detection
+    const packageNames = createSet(rawPackages.map((p) => p.name));
+    // Find changelogs if requested
+    const changelogMap = config.includeChangelogs ? findChangelogs(workspaceRoot, rawPackages) : createMap();
+    // Build projects with changelog paths
+    const rawWithChangelogs = rawPackages.map((pkg) => ({
+        ...pkg,
+        changelogPath: changelogMap.get(pkg.path) ?? null,
+    }));
+    // Calculate internal dependencies
+    const projects = config.trackDependencies
+        ? buildProjectsWithDependencies(rawWithChangelogs, packageNames)
+        : rawWithChangelogs.map((pkg) => createProject(pkg));
+    // Build project map
+    const projectMap = createMap();
+    for (const project of projects) {
+        projectMap.set(project.name, project);
+    }
+    return {
+        projects,
+        projectMap,
+        packageNames,
+        workspaceRoot,
+        config,
+    };
+}
+/**
+ * Finds all package.json files matching the configured patterns.
+ *
+ * @param workspaceRoot - Root directory to search from
+ * @param config - Workspace configuration
+ * @returns Array of relative paths to package.json files
+ */
+function findPackageJsonFiles(workspaceRoot, config) {
+    const patterns = [...config.patterns];
+    const excludePatterns = [...config.exclude];
+    return findFiles(workspaceRoot, patterns, {
+        ignorePatterns: excludePatterns,
+    });
+}
+/**
+ * Parses package.json files and extracts metadata.
+ *
+ * @param workspaceRoot - Workspace root path
+ * @param packageJsonPaths - Relative paths to package.json files
+ * @returns Array of raw package info objects
+ */
+function parsePackageJsonFiles(workspaceRoot, packageJsonPaths) {
+    const packages = [];
+    for (const relativePath of packageJsonPaths) {
+        const absolutePath = node_path.join(workspaceRoot, relativePath);
+        const projectPath = node_path.dirname(absolutePath);
+        try {
+            const packageJson = readPackageJson(absolutePath);
+            // Skip packages without a name
+            if (!packageJson.name) {
+                continue;
+            }
+            packages.push({
+                name: packageJson.name,
+                version: packageJson.version ?? '0.0.0',
+                path: projectPath,
+                packageJsonPath: absolutePath,
+                packageJson,
+                changelogPath: null,
+            });
+        }
+        catch {
+            // Skip packages that can't be parsed
+            continue;
+        }
+    }
+    return packages;
+}
+/**
+ * Builds projects with internal dependency information.
+ *
+ * @param rawPackages - Raw package info objects
+ * @param packageNames - Set of all package names
+ * @returns Array of Project objects with dependencies populated
+ */
+function buildProjectsWithDependencies(rawPackages, packageNames) {
+    // First pass: create projects with dependencies
+    const projectsWithDeps = [];
+    for (const pkg of rawPackages) {
+        const internalDeps = findInternalDependencies(pkg.packageJson, packageNames);
+        projectsWithDeps.push({
+            ...pkg,
+            internalDependencies: internalDeps,
+        });
+    }
+    // Build dependency -> dependents map
+    const dependentsMap = createMap();
+    for (const pkg of projectsWithDeps) {
+        for (const dep of pkg.internalDependencies) {
+            const existing = dependentsMap.get(dep) ?? [];
+            existing.push(pkg.name);
+            dependentsMap.set(dep, existing);
+        }
+    }
+    // Second pass: add dependents to each project
+    return projectsWithDeps.map((pkg) => {
+        const dependents = dependentsMap.get(pkg.name) ?? [];
+        return createProject({
+            ...pkg,
+            internalDependents: dependents,
+        });
+    });
+}
+/**
+ * Discovers a single project by path.
+ *
+ * @param projectPath - Path to project directory or package.json
+ * @returns The discovered project or null if not found
+ */
+function discoverProject(projectPath) {
+    const packageJsonPath = projectPath.endsWith('package.json') ? projectPath : node_path.join(projectPath, 'package.json');
+    const projectDir = projectPath.endsWith('package.json') ? node_path.dirname(projectPath) : projectPath;
+    try {
+        const packageJson = readPackageJson(packageJsonPath);
+        if (!packageJson.name) {
+            return null;
+        }
+        return createProject({
+            name: packageJson.name,
+            version: packageJson.version ?? '0.0.0',
+            path: projectDir,
+            packageJsonPath,
+            packageJson,
+            changelogPath: null,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Discovers a project by name within a workspace.
+ *
+ * @param projectName - Name of the project to find
+ * @param options - Discovery options
+ * @returns The project or null if not found
+ */
+function discoverProjectByName(projectName, options = {}) {
+    const result = discoverPackages(options);
+    return result.projectMap.get(projectName) ?? null;
+}
+
+/**
+ * Changelog Path Utilities
+ *
+ * Functions for checking changelog existence and resolving expected paths.
+ */
+/**
+ * Checks if a project has a changelog file.
+ *
+ * @param projectPath - Directory containing the project to check
+ * @returns True if changelog exists
+ */
+function hasChangelog(projectPath) {
+    return findProjectChangelog(projectPath) !== null;
+}
+/**
+ * Gets the expected changelog path for a project.
+ * Returns the standard CHANGELOG.md path regardless of whether it exists.
+ *
+ * @param projectPath - Directory containing the project files
+ * @returns Absolute path to CHANGELOG.md in the project directory
+ */
+function getExpectedChangelogPath(projectPath) {
+    return node_path.join(projectPath, 'CHANGELOG.md');
+}
+
+/**
+ * Converts a SemVer to its canonical string representation.
+ *
+ * @param version - The version to format
+ * @returns The version string (e.g., "1.2.3-alpha.1+build.123")
+ */
+function format(version) {
+    let result = `${version.major}.${version.minor}.${version.patch}`;
+    if (version.prerelease.length > 0) {
+        result += '-' + version.prerelease.join('.');
+    }
+    if (version.build.length > 0) {
+        result += '+' + version.build.join('.');
+    }
+    return result;
+}
+
+/**
+ * Creates a new SemVer object.
+ *
+ * @param options - Version components
+ * @returns A new SemVer object
+ */
+function createSemVer(options) {
+    return {
+        major: options.major,
+        minor: options.minor,
+        patch: options.patch,
+        prerelease: options.prerelease ?? [],
+        build: options.build ?? [],
+        raw: options.raw,
+    };
+}
+
+/**
+ * Increments a version based on the bump type.
+ *
+ * @param version - The version to increment
+ * @param type - The type of bump (major, minor, patch, etc.)
+ * @param prereleaseId - Optional prerelease identifier for prerelease bumps
+ * @returns A new incremented SemVer
+ *
+ * @example
+ * increment(parseVersion('1.2.3'), 'minor') // 1.3.0
+ * increment(parseVersion('1.2.3'), 'major') // 2.0.0
+ * increment(parseVersion('1.2.3'), 'prerelease', 'alpha') // 1.2.4-alpha.0
+ */
+function increment(version, type, prereleaseId) {
+    switch (type) {
+        case 'major':
+            return createSemVer({
+                major: version.major + 1,
+                minor: 0,
+                patch: 0,
+                prerelease: [],
+                build: [],
+            });
+        case 'minor':
+            return createSemVer({
+                major: version.major,
+                minor: version.minor + 1,
+                patch: 0,
+                prerelease: [],
+                build: [],
+            });
+        case 'patch':
+            // If version has prerelease, just remove it (1.2.3-alpha -> 1.2.3)
+            if (version.prerelease.length > 0) {
+                return createSemVer({
+                    major: version.major,
+                    minor: version.minor,
+                    patch: version.patch,
+                    prerelease: [],
+                    build: [],
+                });
+            }
+            return createSemVer({
+                major: version.major,
+                minor: version.minor,
+                patch: version.patch + 1,
+                prerelease: [],
+                build: [],
+            });
+        case 'premajor':
+            return createSemVer({
+                major: version.major + 1,
+                minor: 0,
+                patch: 0,
+                prerelease: [prereleaseId ?? 'alpha', '0'],
+                build: [],
+            });
+        case 'preminor':
+            return createSemVer({
+                major: version.major,
+                minor: version.minor + 1,
+                patch: 0,
+                prerelease: [prereleaseId ?? 'alpha', '0'],
+                build: [],
+            });
+        case 'prepatch':
+            return createSemVer({
+                major: version.major,
+                minor: version.minor,
+                patch: version.patch + 1,
+                prerelease: [prereleaseId ?? 'alpha', '0'],
+                build: [],
+            });
+        case 'prerelease':
+            return incrementPrerelease(version, prereleaseId);
+        case 'none':
+        default:
+            return version;
+    }
+}
+/**
+ * Increments the prerelease portion of a version.
+ *
+ * @param version - The version to increment
+ * @param id - Optional prerelease identifier
+ * @returns A new version with incremented prerelease
+ */
+function incrementPrerelease(version, id) {
+    const prerelease = [...version.prerelease];
+    if (prerelease.length === 0) {
+        // No existing prerelease - start at patch+1 with id.0
+        return createSemVer({
+            major: version.major,
+            minor: version.minor,
+            patch: version.patch + 1,
+            prerelease: [id ?? 'alpha', '0'],
+            build: [],
+        });
+    }
+    // Check if the last identifier is numeric
+    const lastIdx = prerelease.length - 1;
+    const last = prerelease[lastIdx];
+    const lastNum = parseInt(last, 10);
+    if (!globalIsNaN(lastNum)) {
+        // Increment the numeric part
+        prerelease[lastIdx] = String(lastNum + 1);
+    }
+    else {
+        // Append .0
+        prerelease.push('0');
+    }
+    // If a different id is specified, replace the base identifier
+    if (id && prerelease.length > 0 && prerelease[0] !== id) {
+        prerelease[0] = id;
+        // Reset numeric part
+        if (prerelease.length > 1) {
+            prerelease[prerelease.length - 1] = '0';
+        }
+    }
+    return createSemVer({
+        major: version.major,
+        minor: version.minor,
+        patch: version.patch,
+        prerelease,
+        build: [],
+    });
+}
+
+/**
+ * Maximum version string length to prevent memory exhaustion.
+ */
+const MAX_VERSION_LENGTH = 256;
+/**
+ * Parses a semantic version string.
+ *
+ * Accepts versions in the format: MAJOR.MINOR.PATCH[-prerelease][+build]
+ * Optional leading 'v' or '=' prefixes are stripped.
+ *
+ * @param input - The version string to parse
+ * @returns A ParseVersionResult with the parsed version or error
+ *
+ * @example
+ * parseVersion('1.2.3') // { success: true, version: { major: 1, minor: 2, patch: 3, ... } }
+ * parseVersion('v1.0.0-alpha.1+build.123') // { success: true, ... }
+ * parseVersion('invalid') // { success: false, error: '...' }
+ */
+function parseVersion(input) {
+    // Input validation
+    if (!input || typeof input !== 'string') {
+        return { success: false, error: 'Version string is required' };
+    }
+    if (input.length > MAX_VERSION_LENGTH) {
+        return { success: false, error: `Version string exceeds maximum length of ${MAX_VERSION_LENGTH}` };
+    }
+    // Strip leading whitespace
+    let pos = 0;
+    while (pos < input.length && isWhitespace(input.charCodeAt(pos))) {
+        pos++;
+    }
+    // Strip trailing whitespace
+    let end = input.length;
+    while (end > pos && isWhitespace(input.charCodeAt(end - 1))) {
+        end--;
+    }
+    // Strip optional leading 'v' or '='
+    if (pos < end) {
+        const code = input.charCodeAt(pos);
+        if (code === 118 || code === 86) {
+            // 'v' or 'V'
+            pos++;
+        }
+        else if (code === 61) {
+            // '='
+            pos++;
+        }
+    }
+    // Parse major version
+    const majorResult = parseNumericIdentifier(input, pos, end);
+    if (!majorResult.success) {
+        return { success: false, error: majorResult.error ?? 'Invalid major version' };
+    }
+    pos = majorResult.endPos;
+    // Expect dot
+    if (pos >= end || input.charCodeAt(pos) !== 46) {
+        // '.'
+        return { success: false, error: 'Expected "." after major version' };
+    }
+    pos++;
+    // Parse minor version
+    const minorResult = parseNumericIdentifier(input, pos, end);
+    if (!minorResult.success) {
+        return { success: false, error: minorResult.error ?? 'Invalid minor version' };
+    }
+    pos = minorResult.endPos;
+    // Expect dot
+    if (pos >= end || input.charCodeAt(pos) !== 46) {
+        // '.'
+        return { success: false, error: 'Expected "." after minor version' };
+    }
+    pos++;
+    // Parse patch version
+    const patchResult = parseNumericIdentifier(input, pos, end);
+    if (!patchResult.success) {
+        return { success: false, error: patchResult.error ?? 'Invalid patch version' };
+    }
+    pos = patchResult.endPos;
+    // Parse optional prerelease
+    const prerelease = [];
+    if (pos < end && input.charCodeAt(pos) === 45) {
+        // '-'
+        pos++;
+        const prereleaseResult = parseIdentifiers(input, pos, end, [43]); // Stop at '+'
+        if (!prereleaseResult.success) {
+            return { success: false, error: prereleaseResult.error ?? 'Invalid prerelease' };
+        }
+        prerelease.push(...prereleaseResult.identifiers);
+        pos = prereleaseResult.endPos;
+    }
+    // Parse optional build metadata
+    const build = [];
+    if (pos < end && input.charCodeAt(pos) === 43) {
+        // '+'
+        pos++;
+        const buildResult = parseIdentifiers(input, pos, end, []);
+        if (!buildResult.success) {
+            return { success: false, error: buildResult.error ?? 'Invalid build metadata' };
+        }
+        build.push(...buildResult.identifiers);
+        pos = buildResult.endPos;
+    }
+    // Check for trailing characters
+    if (pos < end) {
+        return { success: false, error: `Unexpected character at position ${pos}: "${input[pos]}"` };
+    }
+    return {
+        success: true,
+        version: createSemVer({
+            major: majorResult.value,
+            minor: minorResult.value,
+            patch: patchResult.value,
+            prerelease,
+            build,
+            raw: input,
+        }),
+    };
+}
+/**
+ * Parses a numeric identifier (non-negative integer, no leading zeros except for "0").
+ *
+ * @param input - Input string to parse
+ * @param start - Start position in the input
+ * @param end - End position in the input
+ * @returns Numeric parsing result
+ */
+function parseNumericIdentifier(input, start, end) {
+    if (start >= end) {
+        return { success: false, value: 0, endPos: start, error: 'Expected numeric identifier' };
+    }
+    let pos = start;
+    const firstCode = input.charCodeAt(pos);
+    // Must start with a digit
+    if (!isDigit(firstCode)) {
+        return { success: false, value: 0, endPos: pos, error: 'Expected digit' };
+    }
+    // Check for leading zero (only "0" is valid, not "01", "007", etc.)
+    if (firstCode === 48 && pos + 1 < end && isDigit(input.charCodeAt(pos + 1))) {
+        return { success: false, value: 0, endPos: pos, error: 'Numeric identifier cannot have leading zeros' };
+    }
+    // Consume digits
+    let value = 0;
+    while (pos < end && isDigit(input.charCodeAt(pos))) {
+        value = value * 10 + (input.charCodeAt(pos) - 48);
+        pos++;
+        // Prevent overflow
+        if (value > Number.MAX_SAFE_INTEGER) {
+            return { success: false, value: 0, endPos: pos, error: 'Numeric identifier is too large' };
+        }
+    }
+    return { success: true, value, endPos: pos };
+}
+/**
+ * Parses dot-separated identifiers (for prerelease/build).
+ *
+ * @param input - Input string to parse
+ * @param start - Start position in the input
+ * @param end - End position in the input
+ * @param stopCodes - Character codes that signal end of identifiers
+ * @returns Identifiers parsing result
+ */
+function parseIdentifiers(input, start, end, stopCodes) {
+    const identifiers = [];
+    let pos = start;
+    while (pos < end) {
+        // Check for stop characters
+        if (stopCodes.includes(input.charCodeAt(pos))) {
+            break;
+        }
+        // Parse one identifier
+        const identStart = pos;
+        while (pos < end) {
+            const code = input.charCodeAt(pos);
+            // Stop at dot or stop characters
+            if (code === 46 || stopCodes.includes(code)) {
+                break;
+            }
+            // Must be alphanumeric or hyphen
+            if (!isAlphanumeric(code) && code !== 45) {
+                return { success: false, identifiers: [], endPos: pos, error: `Invalid character in identifier: "${input[pos]}"` };
+            }
+            pos++;
+        }
+        // Empty identifier is not allowed
+        if (pos === identStart) {
+            return { success: false, identifiers: [], endPos: pos, error: 'Empty identifier' };
+        }
+        identifiers.push(input.slice(identStart, pos));
+        // Consume dot separator
+        if (pos < end && input.charCodeAt(pos) === 46) {
+            pos++;
+            // Dot at end is invalid
+            if (pos >= end || stopCodes.includes(input.charCodeAt(pos))) {
+                return { success: false, identifiers: [], endPos: pos, error: 'Identifier expected after dot' };
+            }
+        }
+    }
+    return { success: true, identifiers, endPos: pos };
+}
+/**
+ * Checks if a character code is a digit (0-9).
+ *
+ * @param code - Character code to check
+ * @returns True if the code represents a digit
+ */
+function isDigit(code) {
+    return code >= 48 && code <= 57;
+}
+/**
+ * Checks if a character code is alphanumeric or hyphen.
+ *
+ * @param code - Character code to check
+ * @returns True if the code represents an alphanumeric character
+ */
+function isAlphanumeric(code) {
+    return ((code >= 48 && code <= 57) || // 0-9
+        (code >= 65 && code <= 90) || // A-Z
+        (code >= 97 && code <= 122) // a-z
+    );
+}
+/**
+ * Checks if a character code is whitespace.
+ *
+ * @param code - Character code to check
+ * @returns True if the code represents whitespace
+ */
+function isWhitespace(code) {
+    return code === 32 || code === 9 || code === 10 || code === 13;
+}
+
+/**
+ * Cascade Bump
+ *
+ * Calculates which packages need version bumps when dependencies change.
+ * Implements cascade versioning for monorepos where dependents may need
+ * to be bumped when their dependencies are updated.
+ */
+/**
+ * Default cascade bump options.
+ */
+const DEFAULT_CASCADE_OPTIONS = {
+    cascadeBumpType: 'patch',
+    includeDevDependencies: false,
+    includePeerDependencies: true,
+    prereleaseId: 'alpha',
+};
+/**
+ * Calculates cascade bumps for a workspace given direct bumps.
+ *
+ * When packages are directly bumped (e.g., due to commits), their dependents
+ * may also need version bumps. This function calculates all affected packages.
+ *
+ * @param workspace - Workspace containing projects and dependency graph
+ * @param directBumps - Packages with direct changes
+ * @param options - Configuration for cascade bump calculation
+ * @returns Cascade bump result
+ *
+ * @example
+ * ```typescript
+ * import { calculateCascadeBumps } from '@hyperfrontend/versioning'
+ *
+ * // If lib-utils is getting a minor bump
+ * const result = calculateCascadeBumps(workspace, [
+ *   { name: 'lib-utils', bumpType: 'minor' }
+ * ])
+ *
+ * // result.bumps includes lib-utils and all packages that depend on it
+ * for (const bump of result.bumps) {
+ *   console.log(`${bump.name}: ${bump.currentVersion} -> ${bump.nextVersion}`)
+ * }
+ * ```
+ */
+function calculateCascadeBumps(workspace, directBumps, options = {}) {
+    const opts = { ...DEFAULT_CASCADE_OPTIONS, ...options };
+    const directBumpMap = createMap(directBumps.map((b) => [b.name, b]));
+    const allBumps = createMap();
+    // Process direct bumps first
+    for (const input of directBumps) {
+        const project = workspace.projects.get(input.name);
+        if (!project) {
+            continue;
+        }
+        const planned = createPlannedBump(project, input.bumpType, 'direct', [], opts.prereleaseId);
+        allBumps.set(input.name, planned);
+    }
+    // Calculate cascade bumps
+    const processed = createSet();
+    const queue = [...directBumps.map((b) => b.name)];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === undefined || processed.has(current)) {
+            continue;
+        }
+        processed.add(current);
+        // Get dependents
+        const dependents = getTransitiveDependents(workspace, current);
+        for (const depName of dependents) {
+            // Skip if already has a direct bump
+            if (directBumpMap.has(depName)) {
+                continue;
+            }
+            // Skip if already planned
+            if (allBumps.has(depName)) {
+                // Update triggered by list
+                const existing = allBumps.get(depName);
+                if (existing && !existing.triggeredBy.includes(current)) {
+                    allBumps.set(depName, {
+                        ...existing,
+                        triggeredBy: [...existing.triggeredBy, current],
+                    });
+                }
+                continue;
+            }
+            const project = workspace.projects.get(depName);
+            if (!project) {
+                continue;
+            }
+            // Check if we should include this dependent based on dependency type
+            if (!shouldCascade(workspace, depName, current, opts)) {
+                continue;
+            }
+            const planned = createPlannedBump(project, opts.cascadeBumpType, 'cascade', [current], opts.prereleaseId);
+            allBumps.set(depName, planned);
+            // Continue cascading from this dependent
+            queue.push(depName);
+        }
+    }
+    // Convert to arrays and categorize
+    const bumps = [...allBumps.values()];
+    const directBumpsArray = bumps.filter((b) => b.reason === 'direct');
+    const cascadeBumpsArray = bumps.filter((b) => b.reason === 'cascade');
+    // Sort bumps by name for consistent output
+    bumps.sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        bumps,
+        directBumps: directBumpsArray,
+        cascadeBumps: cascadeBumpsArray,
+        totalAffected: bumps.length,
+    };
+}
+/**
+ * Determines if a cascade should propagate based on dependency type.
+ *
+ * @param workspace - Workspace containing the project
+ * @param dependent - Name of the dependent package
+ * @param dependency - Name of the dependency being bumped
+ * @param opts - Cascade bump options
+ * @returns True if the bump should cascade to this dependent
+ */
+function shouldCascade(workspace, dependent, dependency, opts) {
+    const project = workspace.projects.get(dependent);
+    if (!project) {
+        return false;
+    }
+    const pkg = project.packageJson;
+    // Check production dependencies (always cascades)
+    if (pkg.dependencies?.[dependency]) {
+        return true;
+    }
+    // Check dev dependencies
+    if (opts.includeDevDependencies && pkg.devDependencies?.[dependency]) {
+        return true;
+    }
+    // Check peer dependencies
+    if (opts.includePeerDependencies && pkg.peerDependencies?.[dependency]) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Creates a planned bump for a project.
+ *
+ * @param project - Project to create bump plan for
+ * @param bumpType - Type of version bump to apply
+ * @param reason - Reason for the bump (direct, cascade, or sync)
+ * @param triggeredBy - List of packages that triggered this bump
+ * @param prereleaseId - Optional prerelease identifier
+ * @returns Planned bump object with version information
+ */
+function createPlannedBump(project, bumpType, reason, triggeredBy, prereleaseId) {
+    const parseResult = parseVersion(project.version);
+    if (!parseResult.success || !parseResult.version) {
+        throw createError(`Invalid version for ${project.name}: ${project.version}`);
+    }
+    const next = computeNextVersion(parseResult.version, bumpType, prereleaseId);
+    return {
+        name: project.name,
+        currentVersion: project.version,
+        nextVersion: format(next),
+        bumpType,
+        reason,
+        triggeredBy,
+    };
+}
+/**
+ * Computes the next version based on bump type.
+ *
+ * @param current - Current semantic version
+ * @param bumpType - Type of version bump to apply
+ * @param prereleaseId - Optional prerelease identifier
+ * @returns New semantic version after bump
+ */
+function computeNextVersion(current, bumpType, prereleaseId) {
+    if (bumpType === 'none') {
+        return current;
+    }
+    return increment(current, bumpType, prereleaseId);
+}
+/**
+ * Calculates cascade bumps starting from a single package.
+ *
+ * @param workspace - Workspace containing projects and dependency graph
+ * @param packageName - Package with direct changes
+ * @param bumpType - Type of bump for the direct change
+ * @param options - Configuration for cascade behavior
+ * @returns Cascade bump result
+ */
+function calculateCascadeBumpsFromPackage(workspace, packageName, bumpType, options = {}) {
+    return calculateCascadeBumps(workspace, [{ name: packageName, bumpType }], options);
+}
+/**
+ * Gets a summary of the cascade bump calculation.
+ *
+ * @param result - Result object from cascade bump calculation
+ * @returns Human-readable summary
+ */
+function summarizeCascadeBumps(result) {
+    if (result.totalAffected === 0) {
+        return 'No packages affected';
+    }
+    const lines = [];
+    lines.push(`${result.totalAffected} package(s) affected:`);
+    lines.push(`  - ${result.directBumps.length} direct bump(s)`);
+    lines.push(`  - ${result.cascadeBumps.length} cascade bump(s)`);
+    lines.push('');
+    lines.push('Planned bumps:');
+    for (const bump of result.bumps) {
+        const suffix = bump.reason === 'cascade' ? ` (triggered by ${bump.triggeredBy.join(', ')})` : '';
+        lines.push(`  ${bump.name}: ${bump.currentVersion} -> ${bump.nextVersion} [${bump.bumpType}]${suffix}`);
+    }
+    return lines.join('\n');
+}
+
+/**
+ * Batch Update
+ *
+ * Utilities for updating multiple packages at once.
+ * Supports updating versions, dependencies, and other package.json fields.
+ */
+/**
+ * Default batch update options.
+ */
+const DEFAULT_BATCH_UPDATE_OPTIONS = {
+    dryRun: false,
+    updateDependencyReferences: true,
+};
+/**
+ * Applies planned bumps to the workspace.
+ * Updates package.json version fields for all affected packages.
+ *
+ * @param workspace - Workspace containing projects to update
+ * @param bumps - Planned version bumps
+ * @param options - Update options
+ * @returns Batch update result
+ *
+ * @example
+ * ```typescript
+ * import { applyBumps, calculateCascadeBumps } from '@hyperfrontend/versioning'
+ *
+ * const cascadeResult = calculateCascadeBumps(workspace, directBumps)
+ * const updateResult = applyBumps(workspace, cascadeResult.bumps)
+ *
+ * if (updateResult.success) {
+ *   console.log(`Updated ${updateResult.updated.length} packages`)
+ * } else {
+ *   console.error('Some updates failed:', updateResult.failed)
+ * }
+ * ```
+ */
+function applyBumps(workspace, bumps, options = {}) {
+    const opts = { ...DEFAULT_BATCH_UPDATE_OPTIONS, ...options };
+    const updated = [];
+    const failed = [];
+    // Build a map for dependency reference updates
+    const versionUpdates = createMap();
+    for (const bump of bumps) {
+        versionUpdates.set(bump.name, bump.nextVersion);
+    }
+    for (const bump of bumps) {
+        const project = workspace.projects.get(bump.name);
+        if (!project) {
+            failed.push({
+                name: bump.name,
+                packageJsonPath: '',
+                error: 'Project not found in workspace',
+            });
+            continue;
+        }
+        try {
+            if (!opts.dryRun) {
+                updatePackageVersion(project.packageJsonPath, bump.nextVersion);
+            }
+            updated.push({
+                name: bump.name,
+                packageJsonPath: project.packageJsonPath,
+                previousVersion: bump.currentVersion,
+                newVersion: bump.nextVersion,
+            });
+        }
+        catch (error) {
+            failed.push({
+                name: bump.name,
+                packageJsonPath: project.packageJsonPath,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    // Update dependency references if requested
+    if (opts.updateDependencyReferences && !opts.dryRun) {
+        for (const project of workspace.projectList) {
+            try {
+                updateDependencyReferences(project.packageJsonPath, versionUpdates);
+            }
+            catch {
+                // Dependency reference updates are best-effort
+            }
+        }
+    }
+    return {
+        updated,
+        failed,
+        total: bumps.length,
+        success: failed.length === 0,
+    };
+}
+/**
+ * Updates the version field in a package.json file.
+ *
+ * @param packageJsonPath - Path to package.json
+ * @param newVersion - New version string
+ */
+function updatePackageVersion(packageJsonPath, newVersion) {
+    const content = readFileContent(packageJsonPath);
+    const pkg = parse(content);
+    pkg.version = newVersion;
+    const formatted = stringify(pkg, null, 2) + '\n';
+    writeFileContent(packageJsonPath, formatted);
+}
+/**
+ * Updates dependency version references in a package.json file.
+ *
+ * @param packageJsonPath - Path to package.json
+ * @param versionUpdates - Map of package name to new version
+ */
+function updateDependencyReferences(packageJsonPath, versionUpdates) {
+    const content = readFileContent(packageJsonPath);
+    const pkg = parse(content);
+    let modified = false;
+    const depTypes = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+    for (const depType of depTypes) {
+        const deps = pkg[depType];
+        if (deps) {
+            for (const [name, newVersion] of versionUpdates) {
+                if (deps[name]) {
+                    // Preserve version prefix (^, ~, etc.) or use exact version
+                    const currentRange = deps[name];
+                    const prefix = extractVersionPrefix(currentRange);
+                    deps[name] = prefix + newVersion;
+                    modified = true;
+                }
+            }
+        }
+    }
+    if (modified) {
+        const formatted = stringify(pkg, null, 2) + '\n';
+        writeFileContent(packageJsonPath, formatted);
+    }
+}
+/**
+ * Extracts the version prefix from a version range.
+ *
+ * @param versionRange - Version range string
+ * @returns The prefix (^, ~, >=, etc.) or empty string
+ */
+function extractVersionPrefix(versionRange) {
+    if (versionRange.startsWith('^'))
+        return '^';
+    if (versionRange.startsWith('~'))
+        return '~';
+    if (versionRange.startsWith('>='))
+        return '>=';
+    if (versionRange.startsWith('>'))
+        return '>';
+    if (versionRange.startsWith('<='))
+        return '<=';
+    if (versionRange.startsWith('<'))
+        return '<';
+    if (versionRange.startsWith('='))
+        return '=';
+    return '';
+}
+/**
+ * Updates a package.json file using a VFS Tree.
+ *
+ * @param tree - Virtual file system tree
+ * @param packageJsonPath - Relative path to package.json
+ * @param newVersion - New version string
+ */
+function updatePackageVersionInTree(tree, packageJsonPath, newVersion) {
+    const content = tree.read(packageJsonPath, 'utf-8');
+    if (!content) {
+        throw createError(`Could not read ${packageJsonPath}`);
+    }
+    const pkg = parse(content);
+    pkg.version = newVersion;
+    const formatted = stringify(pkg, null, 2) + '\n';
+    tree.write(packageJsonPath, formatted);
+}
+/**
+ * Creates a summary of the batch update result.
+ *
+ * @param result - Result object from batch update operation
+ * @returns Human-readable summary
+ */
+function summarizeBatchUpdate(result) {
+    const lines = [];
+    if (result.success) {
+        lines.push(`Successfully updated ${result.updated.length} package(s)`);
+    }
+    else {
+        lines.push(`Updated ${result.updated.length}/${result.total} package(s)`);
+        lines.push(`Failed: ${result.failed.length} package(s)`);
+    }
+    if (result.updated.length > 0) {
+        lines.push('');
+        lines.push('Updated packages:');
+        for (const pkg of result.updated) {
+            lines.push(`  ${pkg.name}: ${pkg.previousVersion} -> ${pkg.newVersion}`);
+        }
+    }
+    if (result.failed.length > 0) {
+        lines.push('');
+        lines.push('Failed packages:');
+        for (const pkg of result.failed) {
+            lines.push(`  ${pkg.name}: ${pkg.error}`);
+        }
+    }
+    return lines.join('\n');
+}
+
+/**
+ * Compares two semantic versions.
+ *
+ * @param a - First version
+ * @param b - Second version
+ * @returns -1 if a < b, 0 if a == b, 1 if a > b
+ *
+ * @example
+ * compare(parseVersion('1.0.0'), parseVersion('2.0.0')) // -1
+ * compare(parseVersion('1.0.0'), parseVersion('1.0.0')) // 0
+ * compare(parseVersion('2.0.0'), parseVersion('1.0.0')) // 1
+ */
+function compare(a, b) {
+    // Compare major, minor, patch
+    if (a.major !== b.major) {
+        return a.major < b.major ? -1 : 1;
+    }
+    if (a.minor !== b.minor) {
+        return a.minor < b.minor ? -1 : 1;
+    }
+    if (a.patch !== b.patch) {
+        return a.patch < b.patch ? -1 : 1;
+    }
+    // Compare prerelease
+    // Version with prerelease has lower precedence than release
+    if (a.prerelease.length === 0 && b.prerelease.length > 0) {
+        return 1; // a is release, b is prerelease -> a > b
+    }
+    if (a.prerelease.length > 0 && b.prerelease.length === 0) {
+        return -1; // a is prerelease, b is release -> a < b
+    }
+    // Both have prerelease - compare identifiers
+    const maxLen = max(a.prerelease.length, b.prerelease.length);
+    for (let i = 0; i < maxLen; i++) {
+        const aId = a.prerelease[i];
+        const bId = b.prerelease[i];
+        // Shorter prerelease array has lower precedence
+        if (aId === undefined && bId !== undefined) {
+            return -1;
+        }
+        if (aId !== undefined && bId === undefined) {
+            return 1;
+        }
+        if (aId === undefined || bId === undefined) {
+            continue;
+        }
+        // Compare identifiers
+        const cmp = compareIdentifiers(aId, bId);
+        if (cmp !== 0) {
+            return cmp;
+        }
+    }
+    return 0;
+}
+/**
+ * Checks if a version satisfies a comparator.
+ *
+ * @param version - Version to check
+ * @param comparator - Comparator to test against
+ * @returns True if version satisfies the comparator
+ */
+function satisfiesComparator(version, comparator) {
+    const cmp = compare(version, comparator.version);
+    switch (comparator.operator) {
+        case '=':
+            return cmp === 0;
+        case '>':
+            return cmp === 1;
+        case '>=':
+            return cmp >= 0;
+        case '<':
+            return cmp === -1;
+        case '<=':
+            return cmp <= 0;
+        case '^':
+        case '~':
+            // These should have been expanded during parsing
+            // If we encounter them here, treat as >=
+            return cmp >= 0;
+        default:
+            return false;
+    }
+}
+/**
+ * Checks if a version satisfies a range.
+ *
+ * @param version - Version to check
+ * @param range - Range to test against
+ * @returns True if version satisfies the range
+ *
+ * @example
+ * satisfies(parseVersion('1.2.3'), parseRange('^1.0.0')) // true
+ * satisfies(parseVersion('2.0.0'), parseRange('^1.0.0')) // false
+ */
+function satisfies(version, range) {
+    // Empty range matches any
+    if (range.sets.length === 0) {
+        return true;
+    }
+    // OR logic: at least one set must be satisfied
+    for (const set of range.sets) {
+        // AND logic: all comparators in set must be satisfied
+        let allSatisfied = true;
+        // Empty comparator set matches any
+        if (set.comparators.length === 0) {
+            return true;
+        }
+        for (const comp of set.comparators) {
+            if (!satisfiesComparator(version, comp)) {
+                allSatisfied = false;
+                break;
+            }
+        }
+        if (allSatisfied) {
+            return true;
+        }
+    }
+    return false;
+}
+// ============================================================================
+// Internal helpers
+// ============================================================================
+/**
+ * Compares two prerelease identifiers.
+ * Numeric identifiers have lower precedence than alphanumeric.
+ * Numeric identifiers are compared numerically.
+ * Alphanumeric identifiers are compared lexically.
+ *
+ * @param a - First prerelease identifier
+ * @param b - Second prerelease identifier
+ * @returns -1 if a < b, 0 if equal, 1 if a > b
+ */
+function compareIdentifiers(a, b) {
+    const aIsNumeric = isNumeric(a);
+    const bIsNumeric = isNumeric(b);
+    // Numeric identifiers have lower precedence
+    if (aIsNumeric && !bIsNumeric) {
+        return -1;
+    }
+    if (!aIsNumeric && bIsNumeric) {
+        return 1;
+    }
+    // Both numeric - compare as numbers
+    if (aIsNumeric && bIsNumeric) {
+        const aNum = parseInt(a, 10);
+        const bNum = parseInt(b, 10);
+        if (aNum < bNum)
+            return -1;
+        if (aNum > bNum)
+            return 1;
+        return 0;
+    }
+    // Both alphanumeric - compare lexically
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+}
+/**
+ * Checks if a string consists only of digits.
+ *
+ * @param str - String to check for numeric content
+ * @returns True if string contains only digits
+ */
+function isNumeric(str) {
+    if (str.length === 0)
+        return false;
+    for (let i = 0; i < str.length; i++) {
+        const code = str.charCodeAt(i);
+        if (code < 48 || code > 57) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/**
+ * Creates a new Comparator.
+ *
+ * @param operator - The comparison operator
+ * @param version - The version to compare against
+ * @returns A new Comparator
+ */
+function createComparator(operator, version) {
+    return { operator, version };
+}
+/**
+ * Creates a new ComparatorSet.
+ *
+ * @param comparators - Array of comparators (AND logic)
+ * @returns A new ComparatorSet
+ */
+function createComparatorSet(comparators) {
+    return { comparators };
+}
+/**
+ * Creates a new Range.
+ *
+ * @param sets - Array of comparator sets (OR logic)
+ * @param raw - Original raw string
+ * @returns A new Range
+ */
+function createRange(sets, raw) {
+    return { sets, raw };
+}
+
+/**
+ * Maximum range string length.
+ */
+const MAX_RANGE_LENGTH = 1024;
+/**
+ * Parses a semver range string.
+ *
+ * Supports:
+ * - Exact: 1.2.3, =1.2.3
+ * - Comparators: >1.0.0, >=1.0.0, <2.0.0, <=2.0.0
+ * - Caret: ^1.2.3 (compatible with version)
+ * - Tilde: ~1.2.3 (approximately equivalent)
+ * - X-ranges: 1.x, 1.2.x, *
+ * - Hyphen ranges: 1.0.0 - 2.0.0
+ * - OR: 1.0.0 || 2.0.0
+ * - AND: >=1.0.0 <2.0.0
+ *
+ * @param input - The range string to parse
+ * @returns A ParseRangeResult with the parsed range or error
+ */
+function parseRange(input) {
+    if (!input || typeof input !== 'string') {
+        return { success: false, error: 'Range string is required' };
+    }
+    if (input.length > MAX_RANGE_LENGTH) {
+        return { success: false, error: `Range string exceeds maximum length of ${MAX_RANGE_LENGTH}` };
+    }
+    // Trim whitespace
+    const trimmed = input.trim();
+    // Handle wildcard/any
+    if (trimmed === '' || trimmed === '*' || trimmed.toLowerCase() === 'x') {
+        return { success: true, range: createRange([], input) };
+    }
+    // Split by || for OR logic
+    const orParts = splitByOr(trimmed);
+    const sets = [];
+    for (const part of orParts) {
+        const setResult = parseComparatorSet(part.trim());
+        if (!setResult.success) {
+            return { success: false, error: setResult.error };
+        }
+        if (setResult.set) {
+            sets.push(setResult.set);
+        }
+    }
+    return { success: true, range: createRange(sets, input) };
+}
+/**
+ * Splits a string by || delimiter, respecting nesting.
+ *
+ * @param input - Range string containing OR groups
+ * @returns Array of OR-separated parts
+ */
+function splitByOr(input) {
+    const parts = [];
+    let current = '';
+    let pos = 0;
+    while (pos < input.length) {
+        if (input[pos] === '|' && pos + 1 < input.length && input[pos + 1] === '|') {
+            parts.push(current);
+            current = '';
+            pos += 2;
+        }
+        else {
+            current += input[pos];
+            pos++;
+        }
+    }
+    parts.push(current);
+    return parts;
+}
+/**
+ * Parses a single comparator set (space-separated comparators = AND logic).
+ *
+ * @param input - Comparator set string
+ * @returns Parsed set result
+ */
+function parseComparatorSet(input) {
+    if (!input || input.trim() === '') {
+        return { success: true }; // Empty set matches any
+    }
+    const trimmed = input.trim();
+    // Check for hyphen range: "1.0.0 - 2.0.0"
+    const hyphenMatch = parseHyphenRange(trimmed);
+    if (hyphenMatch.isHyphenRange) {
+        if (!hyphenMatch.success) {
+            return { success: false, error: hyphenMatch.error };
+        }
+        return { success: true, set: hyphenMatch.set };
+    }
+    // Split by whitespace for AND logic
+    const tokens = splitByWhitespace(trimmed);
+    const comparators = [];
+    for (const token of tokens) {
+        const compResult = parseSingleComparator(token);
+        if (!compResult.success) {
+            return { success: false, error: compResult.error };
+        }
+        if (compResult.comparators) {
+            comparators.push(...compResult.comparators);
+        }
+    }
+    if (comparators.length === 0) {
+        return { success: true }; // Empty matches any
+    }
+    return { success: true, set: createComparatorSet(comparators) };
+}
+/**
+ * Checks for and parses hyphen ranges like "1.0.0 - 2.0.0".
+ *
+ * @param input - Potential hyphen range string
+ * @returns Hyphen range parsing result
+ */
+function parseHyphenRange(input) {
+    // Look for " - " (space-hyphen-space)
+    let hyphenPos = -1;
+    for (let i = 0; i < input.length - 2; i++) {
+        if (input[i] === ' ' && input[i + 1] === '-' && input[i + 2] === ' ') {
+            hyphenPos = i;
+            break;
+        }
+    }
+    if (hyphenPos === -1) {
+        return { isHyphenRange: false, success: true };
+    }
+    const leftPart = input.slice(0, hyphenPos).trim();
+    const rightPart = input.slice(hyphenPos + 3).trim();
+    const leftVersion = parseSimpleVersion(leftPart);
+    if (!leftVersion) {
+        return { isHyphenRange: true, success: false, error: `Invalid left side of hyphen range: "${leftPart}"` };
+    }
+    const rightVersion = parseSimpleVersion(rightPart);
+    if (!rightVersion) {
+        return { isHyphenRange: true, success: false, error: `Invalid right side of hyphen range: "${rightPart}"` };
+    }
+    // Hyphen range: >=left <=right
+    const comparators = [createComparator('>=', leftVersion), createComparator('<=', rightVersion)];
+    return {
+        isHyphenRange: true,
+        success: true,
+        set: createComparatorSet(comparators),
+    };
+}
+/**
+ * Splits by whitespace.
+ *
+ * @param input - String to split
+ * @returns Array of whitespace-separated tokens
+ */
+function splitByWhitespace(input) {
+    const tokens = [];
+    let current = '';
+    for (const char of input) {
+        if (char === ' ' || char === '\t') {
+            if (current) {
+                tokens.push(current);
+                current = '';
+            }
+        }
+        else {
+            current += char;
+        }
+    }
+    if (current) {
+        tokens.push(current);
+    }
+    return tokens;
+}
+/**
+ * Parses a single comparator token (e.g., ">=1.0.0", "^1.2.3", "~1.0").
+ *
+ * @param token - Comparator token to parse
+ * @returns Parsed comparator result
+ */
+function parseSingleComparator(token) {
+    let pos = 0;
+    let operator = '=';
+    // Parse operator
+    if (token[pos] === '^') {
+        operator = '^';
+        pos++;
+    }
+    else if (token[pos] === '~') {
+        operator = '~';
+        pos++;
+    }
+    else if (token[pos] === '>') {
+        if (token[pos + 1] === '=') {
+            operator = '>=';
+            pos += 2;
+        }
+        else {
+            operator = '>';
+            pos++;
+        }
+    }
+    else if (token[pos] === '<') {
+        if (token[pos + 1] === '=') {
+            operator = '<=';
+            pos += 2;
+        }
+        else {
+            operator = '<';
+            pos++;
+        }
+    }
+    else if (token[pos] === '=') {
+        operator = '=';
+        pos++;
+    }
+    const versionPart = token.slice(pos);
+    // Handle wildcards: *, x, X
+    if (versionPart === '*' || versionPart.toLowerCase() === 'x') {
+        // Wildcard matches any - return empty (will be handled as match-all)
+        return { success: true, comparators: [] };
+    }
+    // Handle x-ranges: 1.x, 1.2.x
+    if (versionPart.includes('x') || versionPart.includes('X') || versionPart.includes('*')) {
+        return parseXRange(versionPart);
+    }
+    // Parse version
+    const version = parseSimpleVersion(versionPart);
+    if (!version) {
+        return { success: false, error: `Invalid version in comparator: "${versionPart}"` };
+    }
+    // For caret and tilde, expand to range
+    if (operator === '^') {
+        return expandCaretRange(version);
+    }
+    if (operator === '~') {
+        return expandTildeRange(version);
+    }
+    return { success: true, comparators: [createComparator(operator, version)] };
+}
+/**
+ * Parses x-ranges like 1.x, 1.2.x, etc.
+ *
+ * @param input - X-range string to parse
+ * @param _operator - Range operator (unused but kept for interface consistency)
+ * @returns Comparator result
+ */
+function parseXRange(input, _operator) {
+    const parts = input.split('.');
+    const nums = [];
+    for (const part of parts) {
+        const lower = part.toLowerCase();
+        if (lower === 'x' || lower === '*' || lower === '') {
+            break;
+        }
+        const num = parseInt(part, 10);
+        if (globalIsNaN(num) || num < 0) {
+            return { success: false, error: `Invalid x-range: "${input}"` };
+        }
+        nums.push(num);
+    }
+    if (nums.length === 0) {
+        // * or X alone - match any
+        return { success: true, comparators: [] };
+    }
+    if (nums.length === 1) {
+        // 1.x or 1.* -> >=1.0.0 <2.0.0
+        const lower = createSemVer({ major: nums[0], minor: 0, patch: 0 });
+        const upper = createSemVer({ major: nums[0] + 1, minor: 0, patch: 0 });
+        return { success: true, comparators: [createComparator('>=', lower), createComparator('<', upper)] };
+    }
+    // 1.2.x -> >=1.2.0 <1.3.0
+    const lower = createSemVer({ major: nums[0], minor: nums[1], patch: 0 });
+    const upper = createSemVer({ major: nums[0], minor: nums[1] + 1, patch: 0 });
+    return { success: true, comparators: [createComparator('>=', lower), createComparator('<', upper)] };
+}
+/**
+ * Expands caret range: ^1.2.3 -> >=1.2.3 <2.0.0
+ *
+ * @param version - Base version for caret range
+ * @returns Expanded comparator result
+ */
+function expandCaretRange(version) {
+    let upperMajor = version.major;
+    let upperMinor = 0;
+    let upperPatch = 0;
+    if (version.major === 0) {
+        if (version.minor === 0) {
+            // ^0.0.x -> >=0.0.x <0.0.(x+1)
+            upperPatch = version.patch + 1;
+            upperMinor = version.minor;
+        }
+        else {
+            // ^0.x.y -> >=0.x.y <0.(x+1).0
+            upperMinor = version.minor + 1;
+        }
+    }
+    else {
+        // ^x.y.z -> >=x.y.z <(x+1).0.0
+        upperMajor = version.major + 1;
+    }
+    const upper = createSemVer({ major: upperMajor, minor: upperMinor, patch: upperPatch });
+    return { success: true, comparators: [createComparator('>=', version), createComparator('<', upper)] };
+}
+/**
+ * Expands tilde range: ~1.2.3 -> >=1.2.3 <1.3.0
+ *
+ * @param version - Base version for tilde range
+ * @returns Expanded comparator result
+ */
+function expandTildeRange(version) {
+    const upper = createSemVer({
+        major: version.major,
+        minor: version.minor + 1,
+        patch: 0,
+    });
+    return { success: true, comparators: [createComparator('>=', version), createComparator('<', upper)] };
+}
+/**
+ * Parses a simple version string (no range operators).
+ * More lenient - accepts partial versions.
+ *
+ * @param input - Version string to parse
+ * @returns Parsed SemVer or null if invalid
+ */
+function parseSimpleVersion(input) {
+    if (!input)
+        return null;
+    let pos = 0;
+    // Skip leading v
+    if (input[pos] === 'v' || input[pos] === 'V') {
+        pos++;
+    }
+    const parts = input.slice(pos).split('.');
+    if (parts.length === 0)
+        return null;
+    const nums = [];
+    for (const part of parts) {
+        // Stop at prerelease or build
+        const dashIdx = part.indexOf('-');
+        const plusIdx = part.indexOf('+');
+        let numPart = part;
+        if (dashIdx !== -1) {
+            numPart = part.slice(0, dashIdx);
+        }
+        else if (plusIdx !== -1) {
+            numPart = part.slice(0, plusIdx);
+        }
+        if (numPart === '' || numPart.toLowerCase() === 'x' || numPart === '*') {
+            break;
+        }
+        const num = parseInt(numPart, 10);
+        if (globalIsNaN(num) || num < 0)
+            return null;
+        nums.push(num);
+    }
+    if (nums.length === 0)
+        return null;
+    return createSemVer({
+        major: nums[0],
+        minor: nums[1] ?? 0,
+        patch: nums[2] ?? 0,
+        prerelease: [],
+        build: [],
+        raw: input,
+    });
+}
+
+/**
+ * Workspace Validation
+ *
+ * Validation utilities for workspace integrity checks.
+ * Verifies package configurations, dependencies, and workspace structure.
+ */
+/**
+ * Validates a workspace for common issues.
+ *
+ * @param workspace - The workspace to validate
+ * @returns Validation report
+ *
+ * @example
+ * ```typescript
+ * import { validateWorkspace } from '@hyperfrontend/versioning'
+ *
+ * const report = validateWorkspace(workspace)
+ *
+ * if (!report.valid) {
+ *   console.error(`${report.errorCount} error(s) found`)
+ *   for (const result of report.results) {
+ *     if (!result.result.valid) {
+ *       console.error(`  ${result.checkName}: ${result.result.error}`)
+ *     }
+ *   }
+ * }
+ * ```
+ */
+function validateWorkspace(workspace) {
+    const results = [];
+    // Workspace-level checks
+    results.push({
+        checkId: 'workspace-has-projects',
+        checkName: 'Workspace has projects',
+        packageName: null,
+        result: validateHasProjects(workspace),
+    });
+    results.push({
+        checkId: 'no-circular-dependencies',
+        checkName: 'No circular dependencies',
+        packageName: null,
+        result: validateNoCircularDependencies(workspace),
+    });
+    // Package-level checks
+    for (const project of workspace.projectList) {
+        results.push({
+            checkId: 'valid-version',
+            checkName: `Valid semver version`,
+            packageName: project.name,
+            result: validateProjectVersion(project),
+        });
+        results.push({
+            checkId: 'valid-name',
+            checkName: `Valid package name`,
+            packageName: project.name,
+            result: validateProjectName(project),
+        });
+        results.push({
+            checkId: 'dependency-versions',
+            checkName: `Internal dependency versions`,
+            packageName: project.name,
+            result: validateDependencyVersions(workspace, project),
+        });
+    }
+    // Aggregate results
+    const errors = results.filter((r) => !r.result.valid);
+    const warnings = results.filter((r) => r.result.warning !== undefined);
+    const invalidPackageNames = errors
+        .filter((r) => r.packageName !== null)
+        .map((r) => r.packageName)
+        .filter((name) => name !== null);
+    const invalidPackages = createSet(invalidPackageNames);
+    return {
+        results,
+        valid: errors.length === 0,
+        errorCount: errors.length,
+        warningCount: warnings.length,
+        invalidPackages: [...invalidPackages],
+    };
+}
+/**
+ * Validates that the workspace has at least one project.
+ *
+ * @param workspace - Workspace to validate for project existence
+ * @returns Validation result indicating success or failure
+ */
+function validateHasProjects(workspace) {
+    if (workspace.projects.size === 0) {
+        return {
+            valid: false,
+            error: 'Workspace has no projects',
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Validates that there are no circular dependencies.
+ *
+ * @param workspace - Workspace to check for circular dependencies
+ * @returns Validation result indicating success or failure with cycle info
+ */
+function validateNoCircularDependencies(workspace) {
+    // Build adjacency list
+    const visited = createSet();
+    const recursionStack = createSet();
+    /**
+     * Depth-first search to detect cycles in the dependency graph.
+     *
+     * @param node - Current node being visited
+     * @returns True if a cycle was found starting from this node
+     */
+    function hasCycle(node) {
+        visited.add(node);
+        recursionStack.add(node);
+        const deps = workspace.reverseDependencyGraph.get(node) ?? [];
+        for (const dep of deps) {
+            if (!visited.has(dep)) {
+                if (hasCycle(dep)) {
+                    return true;
+                }
+            }
+            else if (recursionStack.has(dep)) {
+                return true;
+            }
+        }
+        recursionStack.delete(node);
+        return false;
+    }
+    for (const name of workspace.projects.keys()) {
+        if (!visited.has(name)) {
+            if (hasCycle(name)) {
+                return {
+                    valid: false,
+                    error: 'Circular dependency detected',
+                };
+            }
+        }
+    }
+    return { valid: true };
+}
+/**
+ * Validates a project's version is valid semver.
+ *
+ * @param project - Project to validate version for
+ * @returns Validation result indicating success or failure
+ */
+function validateProjectVersion(project) {
+    const result = parseVersion(project.version);
+    if (!result.success) {
+        return {
+            valid: false,
+            error: `Invalid semver version: ${project.version}`,
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Validates a project's package name.
+ *
+ * @param project - Project to validate name for
+ * @returns Validation result indicating success or failure
+ */
+function validateProjectName(project) {
+    if (!project.name || project.name.trim() === '') {
+        return {
+            valid: false,
+            error: 'Package name is required',
+        };
+    }
+    // Check for valid npm package name using safe validation without complex regex
+    const nameValidationResult = validatePackageNameFormat(project.name);
+    if (!nameValidationResult.valid) {
+        return {
+            valid: false,
+            error: `Invalid package name format: ${project.name}`,
+        };
+    }
+    // Check length
+    if (project.name.length > 214) {
+        return {
+            valid: false,
+            error: 'Package name exceeds 214 characters',
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Validates that internal dependency versions are satisfiable.
+ *
+ * @param workspace - Workspace containing all projects
+ * @param project - Project to validate dependencies for
+ * @returns Validation result with warnings for unsatisfied versions
+ */
+function validateDependencyVersions(workspace, project) {
+    const warnings = [];
+    for (const depName of project.internalDependencies) {
+        const dep = workspace.projects.get(depName);
+        if (!dep) {
+            continue; // Handled by dependency existence check
+        }
+        // Get the version range from package.json
+        const depTypes = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+        let versionRange;
+        for (const depType of depTypes) {
+            const deps = project.packageJson[depType];
+            if (deps?.[depName]) {
+                versionRange = deps[depName];
+                break;
+            }
+        }
+        if (versionRange) {
+            const depVersionResult = parseVersion(dep.version);
+            if (depVersionResult.success && depVersionResult.version && !isWorkspaceVersion(versionRange)) {
+                // Parse the version range
+                const rangeResult = parseRange(versionRange);
+                if (rangeResult.success && rangeResult.range) {
+                    // Check if the current version satisfies the range
+                    if (!satisfies(depVersionResult.version, rangeResult.range)) {
+                        warnings.push(`${depName}@${dep.version} does not satisfy ${versionRange}`);
+                    }
+                }
+            }
+        }
+    }
+    if (warnings.length > 0) {
+        return {
+            valid: true, // Warning, not error
+            warning: warnings.join('; '),
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Validates npm package name format without using complex regex.
+ * This avoids ReDoS vulnerabilities from backtracking regex patterns.
+ *
+ * @param name - Package name to validate
+ * @returns Validation result
+ */
+function validatePackageNameFormat(name) {
+    // Valid characters for package names: lowercase letters, digits, hyphens, underscores, dots
+    const isValidChar = (char) => {
+        const code = char.charCodeAt(0);
+        return ((code >= 97 && code <= 122) || // a-z
+            (code >= 48 && code <= 57) || // 0-9
+            code === 45 || // -
+            code === 95 || // _
+            code === 46 // .
+        );
+    };
+    // First char must be lowercase letter or digit
+    const isValidFirstChar = (char) => {
+        const code = char.charCodeAt(0);
+        return (code >= 97 && code <= 122) || (code >= 48 && code <= 57);
+    };
+    // Handle scoped packages (@scope/name)
+    if (name.startsWith('@')) {
+        const slashIndex = name.indexOf('/');
+        if (slashIndex === -1 || slashIndex === 1 || slashIndex === name.length - 1) {
+            return { valid: false };
+        }
+        // Validate scope (after @, before /)
+        const scope = name.slice(1, slashIndex);
+        if (!isValidFirstChar(scope[0]))
+            return { valid: false };
+        for (const char of scope) {
+            if (!isValidChar(char))
+                return { valid: false };
+        }
+        // Validate name (after /)
+        const packageName = name.slice(slashIndex + 1);
+        if (!isValidFirstChar(packageName[0]))
+            return { valid: false };
+        for (const char of packageName) {
+            if (!isValidChar(char))
+                return { valid: false };
+        }
+    }
+    else {
+        // Unscoped package
+        if (!isValidFirstChar(name[0]))
+            return { valid: false };
+        for (const char of name) {
+            if (!isValidChar(char))
+                return { valid: false };
+        }
+    }
+    return { valid: true };
+}
+/**
+ * Checks if a version range is a workspace protocol version.
+ *
+ * @param versionRange - Version range string to check
+ * @returns True if the range uses workspace protocol
+ */
+function isWorkspaceVersion(versionRange) {
+    return versionRange.startsWith('workspace:') || versionRange === '*' || versionRange === 'link:';
+}
+/**
+ * Validates a single project.
+ *
+ * @param project - The project to validate
+ * @returns Validation result
+ */
+function validateProject(project) {
+    const versionResult = validateProjectVersion(project);
+    if (!versionResult.valid) {
+        return versionResult;
+    }
+    const nameResult = validateProjectName(project);
+    if (!nameResult.valid) {
+        return nameResult;
+    }
+    return { valid: true };
+}
+/**
+ * Creates a summary of the validation report.
+ *
+ * @param report - Report object from workspace validation
+ * @returns Human-readable summary
+ */
+function summarizeValidation(report) {
+    const lines = [];
+    if (report.valid) {
+        lines.push('Workspace validation passed');
+        if (report.warningCount > 0) {
+            lines.push(`  ${report.warningCount} warning(s)`);
+        }
+    }
+    else {
+        lines.push('Workspace validation failed');
+        lines.push(`  ${report.errorCount} error(s)`);
+        lines.push(`  ${report.warningCount} warning(s)`);
+        lines.push('');
+        lines.push('Errors:');
+        for (const result of report.results) {
+            if (!result.result.valid) {
+                const pkg = result.packageName ? `[${result.packageName}] ` : '';
+                lines.push(`  ${pkg}${result.checkName}: ${result.result.error}`);
+            }
+        }
+        if (report.warningCount > 0) {
+            lines.push('');
+            lines.push('Warnings:');
+            for (const result of report.results) {
+                if (result.result.warning) {
+                    const pkg = result.packageName ? `[${result.packageName}] ` : '';
+                    lines.push(`  ${pkg}${result.checkName}: ${result.result.warning}`);
+                }
+            }
+        }
+    }
+    return lines.join('\n');
+}
+
+/**
+ * Workspace Module
+ *
+ * Package discovery, dependency management, and versioning coordination
+ * for monorepo workspaces. Integrates with project-scope for file operations.
+ *
+ * @example
+ * ```typescript
+ * import { discoverPackages, calculateCascadeBumps, applyBumps } from '@hyperfrontend/versioning'
+ *
+ * // Discover workspace packages
+ * const { projects, projectMap, workspaceRoot } = discoverPackages()
+ *
+ * // Calculate cascade bumps for a package update
+ * const cascadeResult = calculateCascadeBumps(workspace, [
+ *   { name: 'lib-utils', bumpType: 'minor' }
+ * ])
+ *
+ * // Apply the bumps
+ * const updateResult = applyBumps(workspace, cascadeResult.bumps)
+ * ```
+ */
+/**
+ * Detects the workspace type based on configuration markers.
+ *
+ * @param workspaceRoot - Absolute path to workspace root
+ * @returns Detected workspace type (nx, turbo, lerna, pnpm, yarn, npm, rush, or unknown)
+ */
+function detectWorkspaceType(workspaceRoot) {
+    if (exists(node_path.join(workspaceRoot, 'nx.json')))
+        return 'nx';
+    if (exists(node_path.join(workspaceRoot, 'turbo.json')))
+        return 'turbo';
+    if (exists(node_path.join(workspaceRoot, 'lerna.json')))
+        return 'lerna';
+    if (exists(node_path.join(workspaceRoot, 'pnpm-workspace.yaml')))
+        return 'pnpm';
+    if (exists(node_path.join(workspaceRoot, 'rush.json')))
+        return 'rush';
+    // Check for yarn workspaces in package.json
+    const rootPkg = readPackageJsonIfExists(node_path.join(workspaceRoot, 'package.json'));
+    if (rootPkg?.workspaces)
+        return 'yarn';
+    return 'npm';
+}
+/**
+ * Creates a complete workspace object by discovering packages
+ * and building the dependency graph.
+ *
+ * @param options - Discovery configuration options
+ * @returns Complete workspace object with projects and dependency graph
+ *
+ * @example
+ * ```typescript
+ * import { createWorkspaceFromDisk } from '@hyperfrontend/versioning'
+ *
+ * const workspace = createWorkspaceFromDisk()
+ *
+ * // Access projects
+ * for (const project of workspace.projectList) {
+ *   console.log(`${project.name}@${project.version}`)
+ * }
+ *
+ * // Get dependents of a package
+ * const dependents = workspace.dependencyGraph.get('lib-utils')
+ * ```
+ */
+function createWorkspaceFromDisk(options = {}) {
+    const discovery = discoverPackages(options);
+    const analysis = buildDependencyGraph(discovery.projects);
+    const workspaceType = detectWorkspaceType(discovery.workspaceRoot);
+    const projectMap = createMap();
+    for (const project of discovery.projects) {
+        projectMap.set(project.name, project);
+    }
+    return createWorkspace({
+        root: discovery.workspaceRoot,
+        type: workspaceType,
+        projects: projectMap,
+        config: discovery.config,
+        dependencyGraph: analysis.dependencyGraph,
+        reverseDependencyGraph: analysis.reverseDependencyGraph,
+    });
+}
+
+exports.CHANGELOG_NAMES = CHANGELOG_NAMES;
+exports.DEFAULT_BATCH_UPDATE_OPTIONS = DEFAULT_BATCH_UPDATE_OPTIONS;
+exports.DEFAULT_CASCADE_OPTIONS = DEFAULT_CASCADE_OPTIONS;
+exports.DEFAULT_EXCLUDE = DEFAULT_EXCLUDE;
+exports.DEFAULT_PATTERNS = DEFAULT_PATTERNS;
+exports.DEFAULT_WORKSPACE_CONFIG = DEFAULT_WORKSPACE_CONFIG;
+exports.addDependent = addDependent;
+exports.applyBumps = applyBumps;
+exports.buildDependencyGraph = buildDependencyGraph;
+exports.calculateCascadeBumps = calculateCascadeBumps;
+exports.calculateCascadeBumpsFromPackage = calculateCascadeBumpsFromPackage;
+exports.createProject = createProject;
+exports.createWorkspace = createWorkspace;
+exports.createWorkspaceConfig = createWorkspaceConfig;
+exports.createWorkspaceFromDisk = createWorkspaceFromDisk;
+exports.dependsOn = dependsOn;
+exports.discoverAllChangelogs = discoverAllChangelogs;
+exports.discoverPackages = discoverPackages;
+exports.discoverProject = discoverProject;
+exports.discoverProjectByName = discoverProjectByName;
+exports.findChangelogs = findChangelogs;
+exports.findInternalDependencies = findInternalDependencies;
+exports.findInternalDependenciesWithTypes = findInternalDependenciesWithTypes;
+exports.findProjectChangelog = findProjectChangelog;
+exports.getDependencies = getDependencies;
+exports.getDependencyCount = getDependencyCount;
+exports.getDependentCount = getDependentCount;
+exports.getDependents = getDependents;
+exports.getExpectedChangelogPath = getExpectedChangelogPath;
+exports.getProject = getProject;
+exports.getProjectCount = getProjectCount;
+exports.getProjectNames = getProjectNames;
+exports.getTopologicalOrder = getTopologicalOrder;
+exports.getTransitiveDependencies = getTransitiveDependencies;
+exports.getTransitiveDependents = getTransitiveDependents;
+exports.hasChangelog = hasChangelog;
+exports.hasInternalDependencies = hasInternalDependencies;
+exports.hasInternalDependents = hasInternalDependents;
+exports.hasProject = hasProject;
+exports.hasProjectChangelog = hasChangelog$1;
+exports.isPrivate = isPrivate;
+exports.isPublishable = isPublishable;
+exports.summarizeBatchUpdate = summarizeBatchUpdate;
+exports.summarizeCascadeBumps = summarizeCascadeBumps;
+exports.summarizeValidation = summarizeValidation;
+exports.transitivelyDependsOn = transitivelyDependsOn;
+exports.updatePackageVersionInTree = updatePackageVersionInTree;
+exports.validateProject = validateProject;
+exports.validateWorkspace = validateWorkspace;
+exports.withDependents = withDependents;
+//# sourceMappingURL=index.cjs.js.map