@hyperfrontend/project-scope 0.1.0

package/project/index.esm.js

@@ -0,0 +1,2549 @@
+import { join as join$1, resolve, parse as parse$1, dirname, basename } from 'node:path';
+import { existsSync, readFileSync, statSync, lstatSync, readdirSync } from 'node:fs';
+
+/**
+ * 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$2 = 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$2.construct(_Error, [message, options]);
+
+/**
+ * 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 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 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 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 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 = 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.construct(_Map, iterable ? [iterable] : []);
+
+/* 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 (!existsSync(filePath)) {
+        fsLogger.debug('File not found', { path: filePath });
+        throw createFileSystemError(`File not found: ${filePath}`, 'FS_NOT_FOUND', { path: filePath, operation: 'read' });
+    }
+    try {
+        return 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 (!existsSync(filePath)) {
+        return null;
+    }
+    try {
+        return readFileSync(filePath, { encoding });
+    }
+    catch {
+        return null;
+    }
+}
+
+createScopedLogger('project-scope:fs:write');
+
+/**
+ * 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 (!existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const stat = followSymlinks ? statSync(filePath) : 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 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 (!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 = readdirSync(dirPath, { withFileTypes: true });
+        fsDirLogger.debug('Directory read complete', { path: dirPath, entryCount: entries.length });
+        return entries.map((entry) => ({
+            name: entry.name,
+            path: join$1(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 join$1(...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 = resolve(startPath);
+    const rootPath = parse$1(currentPath).root;
+    while (currentPath !== rootPath) {
+        if (predicate(currentPath)) {
+            fsTraversalLogger.debug('Upward traversal found match', { startPath, foundPath: currentPath });
+            return currentPath;
+        }
+        currentPath = 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);
+}
+
+/**
+ * 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 = join$1(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 });
+}
+/**
+ * Traverses a virtual file system tree, calling a visitor function
+ * for each file and directory. Operates on in-memory tree structure
+ * without disk I/O.
+ *
+ * @param tree - In-memory virtual file system representation
+ * @param startPath - Root path within the tree to begin traversal
+ * @param visitor - Callback function invoked for each tree entry
+ * @param options - Configuration for traversal behavior
+ */
+function walkTree(tree, startPath, visitor, options) {
+    const maxDepth = options?.maxDepth ?? -1;
+    const includeHidden = options?.includeHidden ?? false;
+    /**
+     * Recursively walks tree entries, applying visitor to each.
+     *
+     * @param currentPath - Current path within the tree
+     * @param relativePath - Path relative to the starting path
+     * @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 children;
+        try {
+            children = tree.children(currentPath);
+        }
+        catch {
+            return true;
+        }
+        for (const name of children) {
+            if (!includeHidden && name.startsWith('.')) {
+                continue;
+            }
+            const childPath = currentPath ? `${currentPath}/${name}` : name;
+            const entryRelativePath = relativePath ? `${relativePath}/${name}` : name;
+            const isFileEntry = tree.isFile(childPath);
+            const walkEntry = {
+                name,
+                path: childPath,
+                relativePath: entryRelativePath,
+                isFile: isFileEntry,
+                isDirectory: !isFileEntry,
+                isSymlink: false,
+                depth,
+            };
+            const result = visitor(walkEntry);
+            if (result === 'stop') {
+                return false;
+            }
+            if (result === 'skip') {
+                continue;
+            }
+            if (!isFileEntry) {
+                const shouldContinue = walk(childPath, entryRelativePath, depth + 1);
+                if (!shouldContinue) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+    walk(startPath, '', 0);
+}
+
+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;
+}
+/**
+ * Searches a virtual file system tree for files matching glob patterns,
+ * useful for analyzing project structure without disk I/O.
+ *
+ * @param tree - In-memory virtual file system representation
+ * @param patterns - Glob patterns (e.g., '*.ts', '**\/*.json') to filter files
+ * @param options - Configuration for search behavior
+ * @returns List of virtual file paths that match the patterns
+ */
+function findFilesInTree(tree, patterns, options) {
+    const normalizedPatterns = isArray(patterns) ? patterns : [patterns];
+    const results = [];
+    const maxResults = options?.maxResults ?? Infinity;
+    walkTree(tree, tree.root || '', (entry) => {
+        if (results.length >= maxResults) {
+            return 'stop';
+        }
+        if (!entry.isFile) {
+            return undefined;
+        }
+        if (matchesPatterns(entry.relativePath, normalizedPatterns)) {
+            results.push(entry.relativePath);
+        }
+        return undefined;
+    }, options);
+    return results;
+}
+/**
+ * Searches a directory tree for directories 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 to filter directories (supports wildcards)
+ * @param options - Configuration for search behavior
+ * @returns List of relative directory paths that match the patterns
+ */
+function findDirectories(startPath, patterns, options) {
+    const normalizedPatterns = isArray(patterns) ? patterns : [patterns];
+    const results = [];
+    const maxResults = options?.maxResults ?? Infinity;
+    walkDirectory(startPath, (entry) => {
+        if (results.length >= maxResults) {
+            return 'stop';
+        }
+        if (!entry.isDirectory) {
+            return undefined;
+        }
+        if (matchesPatterns(entry.relativePath, normalizedPatterns)) {
+            results.push(options?.absolutePaths ? entry.path : entry.relativePath);
+        }
+        return undefined;
+    }, options);
+    return results;
+}
+
+/**
+ * Known configuration file patterns organized by type.
+ */
+const CONFIG_PATTERNS = {
+    // Package Management
+    'package.json': {
+        patterns: ['package.json'],
+        format: 'json',
+        description: 'NPM package manifest',
+    },
+    'package-lock.json': {
+        patterns: ['package-lock.json'],
+        format: 'json',
+        description: 'NPM lockfile',
+    },
+    'pnpm-lock.yaml': {
+        patterns: ['pnpm-lock.yaml'],
+        format: 'yaml',
+        description: 'PNPM lockfile',
+    },
+    'yarn.lock': {
+        patterns: ['yarn.lock'],
+        format: 'text',
+        description: 'Yarn lockfile',
+    },
+    '.npmrc': {
+        patterns: ['.npmrc'],
+        format: 'ini',
+        description: 'NPM configuration',
+        sensitive: true,
+    },
+    // TypeScript
+    tsconfig: {
+        patterns: ['tsconfig.json', 'tsconfig.*.json'],
+        format: 'jsonc',
+        description: 'TypeScript configuration',
+        canExtend: true,
+    },
+    // Monorepo
+    nx: {
+        patterns: ['nx.json'],
+        format: 'json',
+        description: 'NX workspace configuration',
+    },
+    'project.json': {
+        patterns: ['project.json', '**/project.json'],
+        format: 'json',
+        description: 'NX project configuration',
+    },
+    'workspace.json': {
+        patterns: ['workspace.json'],
+        format: 'json',
+        description: 'NX workspace projects (deprecated)',
+    },
+    turbo: {
+        patterns: ['turbo.json'],
+        format: 'jsonc',
+        description: 'TurboRepo configuration',
+    },
+    lerna: {
+        patterns: ['lerna.json'],
+        format: 'json',
+        description: 'Lerna configuration',
+    },
+    // Build Tools
+    webpack: {
+        patterns: ['webpack.config.js', 'webpack.config.ts', 'webpack.config.cjs', 'webpack.config.mjs'],
+        format: 'js',
+        description: 'Webpack configuration',
+    },
+    rollup: {
+        patterns: ['rollup.config.js', 'rollup.config.ts', 'rollup.config.mjs'],
+        format: 'js',
+        description: 'Rollup configuration',
+    },
+    vite: {
+        patterns: ['vite.config.js', 'vite.config.ts', 'vite.config.mjs'],
+        format: 'js',
+        description: 'Vite configuration',
+    },
+    esbuild: {
+        patterns: ['esbuild.config.js', 'esbuild.config.ts', 'esbuild.config.mjs'],
+        format: 'js',
+        description: 'esbuild configuration',
+    },
+    babel: {
+        patterns: ['babel.config.js', 'babel.config.json', '.babelrc', '.babelrc.js', '.babelrc.json'],
+        format: 'json',
+        description: 'Babel configuration',
+    },
+    swc: {
+        patterns: ['.swcrc'],
+        format: 'json',
+        description: 'SWC configuration',
+    },
+    // Testing
+    jest: {
+        patterns: ['jest.config.js', 'jest.config.ts', 'jest.config.mjs'],
+        description: 'Jest configuration',
+    },
+    vitest: {
+        patterns: ['vitest.config.js', 'vitest.config.ts'],
+        description: 'Vitest configuration',
+    },
+    cypress: {
+        patterns: ['cypress.config.js', 'cypress.config.ts'],
+        description: 'Cypress configuration',
+    },
+    playwright: {
+        patterns: ['playwright.config.js', 'playwright.config.ts'],
+        description: 'Playwright configuration',
+    },
+    // Framework configs
+    next: {
+        patterns: ['next.config.js', 'next.config.mjs', 'next.config.ts'],
+        format: 'js',
+        description: 'Next.js configuration',
+    },
+    angular: {
+        patterns: ['angular.json'],
+        format: 'json',
+        description: 'Angular CLI configuration',
+    },
+    nuxt: {
+        patterns: ['nuxt.config.js', 'nuxt.config.ts'],
+        format: 'js',
+        description: 'Nuxt.js configuration',
+    },
+    svelte: {
+        patterns: ['svelte.config.js', 'svelte.config.ts'],
+        format: 'js',
+        description: 'SvelteKit configuration',
+    },
+    astro: {
+        patterns: ['astro.config.js', 'astro.config.ts', 'astro.config.mjs'],
+        format: 'js',
+        description: 'Astro configuration',
+    },
+    // Linting & Formatting
+    eslint: {
+        patterns: [
+            'eslint.config.js',
+            'eslint.config.cjs',
+            'eslint.config.mjs',
+            '.eslintrc',
+            '.eslintrc.js',
+            '.eslintrc.json',
+            '.eslintrc.yml',
+        ],
+        format: 'js',
+        description: 'ESLint configuration',
+    },
+    prettier: {
+        patterns: ['prettier.config.js', 'prettier.config.cjs', '.prettierrc', '.prettierrc.js', '.prettierrc.json', '.prettierrc.yml'],
+        format: 'json',
+        description: 'Prettier configuration',
+    },
+    // Environment (sensitive)
+    env: {
+        patterns: ['.env', '.env.*', '*.env'],
+        format: 'dotenv',
+        description: 'Environment variables',
+        sensitive: true,
+    },
+    // Git
+    '.gitignore': {
+        patterns: ['.gitignore'],
+        format: 'text',
+        description: 'Git ignore patterns',
+    },
+    '.gitattributes': {
+        patterns: ['.gitattributes'],
+        format: 'text',
+        description: 'Git attributes',
+    },
+};
+/**
+ * Get patterns for specific config types.
+ *
+ * @param types - Array of config types to get patterns for
+ * @returns Array of file patterns
+ */
+function getConfigPatternsByType(types) {
+    return types.flatMap((type) => CONFIG_PATTERNS[type]?.patterns ?? []);
+}
+
+/**
+ * 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);
+}
+
+const configLogger = createScopedLogger('project-scope:config');
+/**
+ * Cache for config detection results.
+ * TTL: 30 seconds (configs can change frequently during setup)
+ */
+const configDetectionCache = createCache({ ttl: 30000, maxSize: 50 });
+/**
+ * Detect all configuration files in a directory.
+ *
+ * Results are cached for 30 seconds per project path and options
+ * to avoid redundant file system operations on repeated calls.
+ *
+ * @param rootPath - Project root directory
+ * @param types - Optional array of config types to check (defaults to all)
+ * @param options - Detection options
+ * @returns Array of detected configuration files
+ *
+ * @example
+ * ```typescript
+ * import { detectConfigs } from '@hyperfrontend/project-scope'
+ *
+ * // Detect all config files
+ * const configs = detectConfigs('./my-project')
+ * for (const config of configs) {
+ *   console.log(`${config.type}: ${config.path}`)
+ * }
+ * // Output:
+ * // typescript: tsconfig.json
+ * // eslint: eslint.config.js
+ * // jest: jest.config.ts
+ *
+ * // Detect specific config types only
+ * const tsConfigs = detectConfigs('./my-project', ['typescript', 'eslint'])
+ * ```
+ */
+function detectConfigs(rootPath, types, options) {
+    const typesToCheck = types ?? keys(CONFIG_PATTERNS);
+    const results = [];
+    const maxDepth = options?.maxDepth ?? 10;
+    const includeHidden = options?.includeHidden ?? true;
+    const typeKey = types ? types.sort().join(',') : 'all';
+    const cacheKey = `${rootPath}:${typeKey}:${maxDepth}:${includeHidden}`;
+    if (!options?.skipCache) {
+        const cached = configDetectionCache.get(cacheKey);
+        if (cached) {
+            configLogger.debug('Returning cached config detection results', { rootPath });
+            return cached;
+        }
+    }
+    configLogger.debug('Detecting config files', { rootPath, types: typesToCheck.length });
+    for (const type of typesToCheck) {
+        const info = CONFIG_PATTERNS[type];
+        if (!info)
+            continue;
+        for (const pattern of info.patterns) {
+            const isRecursive = pattern.includes('**');
+            if (isRecursive) {
+                const files = findFiles(rootPath, pattern, {
+                    maxDepth,
+                    includeHidden: options?.includeHidden ?? true,
+                });
+                for (const file of files) {
+                    if (!results.some((r) => r.path === file && r.type === type)) {
+                        configLogger.debug('Found config file', { type, path: file });
+                        results.push({
+                            type,
+                            path: file,
+                            matchedPattern: pattern,
+                            info,
+                        });
+                    }
+                }
+            }
+            else {
+                const fullPath = join$1(rootPath, pattern);
+                if (exists(fullPath)) {
+                    if (!results.some((r) => r.path === pattern && r.type === type)) {
+                        configLogger.debug('Found config file', { type, path: pattern });
+                        results.push({
+                            type,
+                            path: pattern,
+                            matchedPattern: pattern,
+                            info,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    configLogger.debug('Config detection complete', { found: results.length });
+    configDetectionCache.set(cacheKey, results);
+    return results;
+}
+/**
+ * Clear the config detection cache.
+ *
+ * Useful for testing or when the project files have changed.
+ */
+function clearConfigDetectionCache() {
+    configDetectionCache.clear();
+}
+/**
+ * Find a specific configuration file.
+ *
+ * @param rootPath - Project root directory
+ * @param type - Config type to find
+ * @returns Full path to config file or null if not found
+ */
+function findConfigFile(rootPath, type) {
+    const info = CONFIG_PATTERNS[type];
+    if (!info)
+        return null;
+    for (const pattern of info.patterns) {
+        if (!pattern.includes('*')) {
+            const fullPath = join$1(rootPath, pattern);
+            if (exists(fullPath)) {
+                return fullPath;
+            }
+        }
+    }
+    for (const pattern of info.patterns) {
+        if (pattern.includes('*') && !pattern.includes('**')) {
+            const files = findFiles(rootPath, pattern, { maxDepth: 0 });
+            if (files.length > 0) {
+                return join$1(rootPath, files[0]);
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Get all known config file patterns for a given configuration type.
+ *
+ * @param type - Configuration type identifier
+ * @returns Array of glob patterns for matching config files
+ */
+function getConfigPaths(type) {
+    const info = CONFIG_PATTERNS[type];
+    return info?.patterns ?? [];
+}
+
+/**
+ * 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 _parseFloat = globalThis.parseFloat;
+// ============================================================================
+// Parsing
+// ============================================================================
+/**
+ * (Safe copy) Parses a string and returns an integer.
+ */
+const parseInt = _parseInt;
+/**
+ * (Safe copy) Parses a string and returns a floating point number.
+ */
+const parseFloat = _parseFloat;
+
+/**
+ * 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' });
+}
+
+/**
+ * Detect config type from file name.
+ * Uses safe character-by-character matching to prevent ReDoS attacks.
+ *
+ * @param filePath - Path to config file
+ * @returns Detected config type or undefined
+ */
+function detectConfigType(filePath) {
+    const fileName = basename(filePath);
+    for (const [type, info] of entries(CONFIG_PATTERNS)) {
+        for (const pattern of info.patterns) {
+            if (matchGlobPattern(fileName, pattern)) {
+                return type;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Detect format from file path.
+ *
+ * @param filePath - Path to config file
+ * @returns Detected format
+ */
+function detectFormat(filePath) {
+    const ext = filePath.split('.').pop()?.toLowerCase();
+    switch (ext) {
+        case 'json':
+            return 'json';
+        case 'yaml':
+        case 'yml':
+            return 'yaml';
+        case 'js':
+        case 'cjs':
+        case 'mjs':
+            return 'js';
+        case 'ts':
+            return 'ts';
+        case 'toml':
+            return 'toml';
+        case 'ini':
+            return 'ini';
+        default:
+            return 'text';
+    }
+}
+/**
+ * Strip JSON comments (// and /* *\/).
+ *
+ * @param content - JSONC content
+ * @returns JSON content without comments
+ */
+function stripJsonComments(content) {
+    let result = '';
+    let inString = false;
+    let inLineComment = false;
+    let inBlockComment = false;
+    let stringChar = '';
+    for (let i = 0; i < content.length; i++) {
+        const char = content[i];
+        const nextChar = content[i + 1];
+        if (inLineComment) {
+            if (char === '\n') {
+                inLineComment = false;
+                result += char;
+            }
+            continue;
+        }
+        if (inBlockComment) {
+            if (char === '*' && nextChar === '/') {
+                inBlockComment = false;
+                i++;
+            }
+            continue;
+        }
+        if (inString) {
+            result += char;
+            if (char === stringChar && content[i - 1] !== '\\') {
+                inString = false;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            inString = true;
+            stringChar = char;
+            result += char;
+            continue;
+        }
+        if (char === '/' && nextChar === '/') {
+            inLineComment = true;
+            i++;
+            continue;
+        }
+        if (char === '/' && nextChar === '*') {
+            inBlockComment = true;
+            i++;
+            continue;
+        }
+        result += char;
+    }
+    return result;
+}
+/**
+ * Parse simple YAML key-value pairs into an object.
+ * Note: This is a simplified parser for basic config structures.
+ *
+ * @param content - Raw YAML file content to parse
+ * @returns Object representation of the YAML key-value pairs
+ */
+function parseSimpleYaml(content) {
+    const lines = content.split('\n');
+    const result = {};
+    for (const line of lines) {
+        if (line.trim().startsWith('#') || !line.includes(':')) {
+            continue;
+        }
+        const colonIndex = line.indexOf(':');
+        const key = line.substring(0, colonIndex).trim();
+        const value = line.substring(colonIndex + 1).trim();
+        if (key && value) {
+            if (value === 'true') {
+                result[key] = true;
+            }
+            else if (value === 'false') {
+                result[key] = false;
+            }
+            else if (value === 'null') {
+                result[key] = null;
+            }
+            else if (/^-?\d+$/.test(value)) {
+                result[key] = parseInt(value, 10);
+            }
+            else if (/^-?\d+\.\d+$/.test(value)) {
+                result[key] = parseFloat(value);
+            }
+            else {
+                result[key] = value.replace(/^["']|["']$/g, '');
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Parse INI-style configuration format into an object.
+ * Supports sections and key-value pairs.
+ *
+ * @param content - Raw INI file content to parse
+ * @returns Object with sections as keys and their key-value pairs
+ */
+function parseIniConfig(content) {
+    const result = {};
+    let currentSection = '';
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith(';')) {
+            continue;
+        }
+        const sectionMatch = trimmed.match(/^\[([^\]]+)\]$/);
+        if (sectionMatch) {
+            currentSection = sectionMatch[1];
+            result[currentSection] = {};
+            continue;
+        }
+        const keyValueMatch = trimmed.match(/^([^=]+)=(.*)$/);
+        if (keyValueMatch) {
+            const key = keyValueMatch[1].trim();
+            const value = keyValueMatch[2].trim();
+            if (currentSection) {
+                result[currentSection][key] = value;
+            }
+            else {
+                result[key] = value;
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Parse dotenv-style environment variable format.
+ * Handles quoted values and comments.
+ *
+ * @param content - Raw dotenv file content to parse
+ * @returns Object mapping variable names to their values
+ */
+function parseDotenv(content) {
+    const result = {};
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) {
+            continue;
+        }
+        const match = trimmed.match(/^([^=]+)=(.*)$/);
+        if (match) {
+            const key = match[1].trim();
+            let value = match[2].trim();
+            if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+                value = value.slice(1, -1);
+            }
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Parse JSON configuration file.
+ *
+ * @param filePath - Path to the JSON configuration file
+ * @param content - Raw file content to parse
+ * @param type - Category of configuration (e.g., typescript, eslint)
+ * @param format - Whether to strip comments (jsonc) or parse strictly (json)
+ * @returns Configuration object with parsed data and extends references
+ */
+function parseJsonConfig(filePath, content, type, format = 'json') {
+    const cleanContent = format === 'jsonc' ? stripJsonComments(content) : content;
+    try {
+        const data = parse(cleanContent);
+        let extendsPath;
+        if (typeof data['extends'] === 'string') {
+            extendsPath = [data['extends']];
+        }
+        else if (isArray(data['extends'])) {
+            extendsPath = data['extends'];
+        }
+        return {
+            type: type ?? 'unknown',
+            path: filePath,
+            format,
+            data,
+            extends: extendsPath,
+        };
+    }
+    catch (error) {
+        throw createConfigError(`Failed to parse JSON config: ${filePath}`, 'CONFIG_PARSE_ERROR', {
+            filePath,
+            format,
+            cause: error,
+        });
+    }
+}
+/**
+ * Parse YAML configuration file.
+ *
+ * @param filePath - Path to the YAML configuration file
+ * @param content - Raw file content to parse
+ * @param type - Category of configuration (e.g., github-actions, docker-compose)
+ * @returns Configuration object with parsed YAML data
+ */
+function parseYamlConfig(filePath, content, type) {
+    const data = parseSimpleYaml(content);
+    return {
+        type: type ?? 'unknown',
+        path: filePath,
+        format: 'yaml',
+        data,
+    };
+}
+/**
+ * Parse configuration file.
+ *
+ * @param filePath - Path to config file
+ * @param type - Optional config type (auto-detected if not provided)
+ * @returns Parsed configuration
+ */
+function parseConfig(filePath, type) {
+    const content = readFileContent(filePath);
+    const detectedType = type ?? detectConfigType(filePath);
+    const info = detectedType ? CONFIG_PATTERNS[detectedType] : null;
+    const format = info?.format ?? detectFormat(filePath);
+    switch (format) {
+        case 'json':
+            return parseJsonConfig(filePath, content, detectedType, 'json');
+        case 'jsonc':
+            return parseJsonConfig(filePath, content, detectedType, 'jsonc');
+        case 'yaml':
+            return parseYamlConfig(filePath, content, detectedType);
+        case 'ini':
+            return {
+                type: detectedType ?? 'unknown',
+                path: filePath,
+                format: 'ini',
+                data: parseIniConfig(content),
+            };
+        case 'dotenv':
+            return {
+                type: detectedType ?? 'unknown',
+                path: filePath,
+                format: 'dotenv',
+                data: parseDotenv(content),
+            };
+        case 'js':
+        case 'ts':
+            return {
+                type: detectedType ?? 'unknown',
+                path: filePath,
+                format,
+                raw: content,
+            };
+        default:
+            return {
+                type: detectedType ?? 'unknown',
+                path: filePath,
+                format: 'text',
+                raw: content,
+            };
+    }
+}
+/**
+ * Read and parse config file if it exists.
+ *
+ * @param configPath - Path to config file
+ * @returns Parsed config or null if file doesn't exist
+ */
+function readConfigIfExists(configPath) {
+    const content = readFileIfExists(configPath);
+    if (!content)
+        return null;
+    try {
+        const format = detectFormat(configPath);
+        switch (format) {
+            case 'json':
+                return parse(content);
+            case 'jsonc':
+                return parse(stripJsonComments(content));
+            case 'yaml':
+                return parseSimpleYaml(content);
+            default:
+                return null;
+        }
+    }
+    catch {
+        return null;
+    }
+}
+
+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 : join$1(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 : join$1(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']);
+}
+
+/**
+ * Extract all dependencies from package.json.
+ *
+ * @param packageJson - Parsed package.json
+ * @returns All dependencies categorized
+ */
+function getDependencies(packageJson) {
+    return {
+        dependencies: packageJson.dependencies ?? {},
+        devDependencies: packageJson.devDependencies ?? {},
+        peerDependencies: packageJson.peerDependencies ?? {},
+        optionalDependencies: packageJson.optionalDependencies ?? {},
+    };
+}
+/**
+ * Get production dependencies only.
+ *
+ * @param packageJson - Parsed package.json
+ * @returns Map of dependency name to version for runtime dependencies
+ */
+function getProductionDependencies(packageJson) {
+    return packageJson.dependencies ?? {};
+}
+/**
+ * Get development dependencies only.
+ *
+ * @param packageJson - Parsed package.json
+ * @returns Map of dependency name to version for dev-time dependencies
+ */
+function getDevDependencies(packageJson) {
+    return packageJson.devDependencies ?? {};
+}
+/**
+ * Get peer dependencies only.
+ *
+ * @param packageJson - Parsed package.json
+ * @returns Map of dependency name to version for peer requirements
+ */
+function getPeerDependencies(packageJson) {
+    return packageJson.peerDependencies ?? {};
+}
+/**
+ * Get all dependencies merged into a single map.
+ *
+ * @param packageJson - Parsed package.json
+ * @returns All dependencies merged
+ */
+function getAllDependencies(packageJson) {
+    return {
+        ...packageJson.dependencies,
+        ...packageJson.devDependencies,
+        ...packageJson.peerDependencies,
+        ...packageJson.optionalDependencies,
+    };
+}
+/**
+ * Check if package has a dependency of any type.
+ *
+ * @param packageJson - Parsed package.json content
+ * @param name - Name of the dependency to check
+ * @param depTypes - Optional array of dependency types to check (defaults to all)
+ * @returns True if dependency exists in specified categories
+ */
+function hasDependency(packageJson, name, depTypes) {
+    const typesToCheck = depTypes ?? ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+    for (const depType of typesToCheck) {
+        if (packageJson[depType] && name in packageJson[depType]) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Get version string of a specific dependency.
+ *
+ * @param packageJson - Parsed package.json content
+ * @param name - Name of the dependency to look up
+ * @returns Version string or null if not found
+ */
+function getDependencyVersion(packageJson, name) {
+    const deps = getDependencies(packageJson);
+    return deps.dependencies[name] ?? deps.devDependencies[name] ?? deps.peerDependencies[name] ?? deps.optionalDependencies[name] ?? null;
+}
+/**
+ * Get workspace patterns from package.json.
+ *
+ * @param packageJson - Parsed package.json
+ * @returns Array of workspace patterns or empty array
+ */
+function getWorkspaces(packageJson) {
+    if (!packageJson.workspaces)
+        return [];
+    if (isArray(packageJson.workspaces)) {
+        return packageJson.workspaces;
+    }
+    if (typeof packageJson.workspaces === 'object' && 'packages' in packageJson.workspaces) {
+        return packageJson.workspaces.packages;
+    }
+    return [];
+}
+/**
+ * Check if package has workspaces configured (monorepo).
+ *
+ * @param packageJson - Parsed package.json
+ * @returns True if workspaces are defined
+ */
+function hasWorkspaces(packageJson) {
+    return getWorkspaces(packageJson).length > 0;
+}
+/**
+ * Check if a package is installed in node_modules.
+ *
+ * @param projectPath - Project root directory
+ * @param packageName - Package name to check
+ * @returns Boolean indicating whether the package exists in node_modules
+ */
+function hasInstalledPackage(projectPath, packageName) {
+    const pkgPath = join$1(projectPath, 'node_modules', packageName, 'package.json');
+    return readPackageJsonIfExists(pkgPath) !== null;
+}
+/**
+ * Get installed package version from node_modules.
+ *
+ * @param projectPath - Project root directory
+ * @param packageName - Name of the npm package to look up
+ * @returns Installed version or null if not found
+ */
+function getInstalledVersion(projectPath, packageName) {
+    const pkg = readPackageJsonIfExists(join$1(projectPath, 'node_modules', packageName, 'package.json'));
+    return pkg?.version ?? null;
+}
+
+const rootLogger = createScopedLogger('project-scope:root');
+/**
+ * Files indicating project root.
+ */
+const ROOT_MARKERS = ['package.json', '.git'];
+/**
+ * Files indicating workspace/monorepo root.
+ */
+const WORKSPACE_MARKERS = ['nx.json', 'turbo.json', 'lerna.json', 'pnpm-workspace.yaml', 'rush.json'];
+/**
+ * Check if directory looks like a project directory.
+ *
+ * @param dirPath - Directory path to check
+ * @returns True if directory appears to be a project
+ */
+function looksLikeProjectDir(dirPath) {
+    if (exists(join$1(dirPath, 'src'))) {
+        return true;
+    }
+    const entryPoints = ['index.ts', 'index.js', 'index.tsx', 'index.jsx', 'main.ts', 'main.js'];
+    for (const entry of entryPoints) {
+        if (exists(join$1(dirPath, entry))) {
+            return true;
+        }
+    }
+    if (exists(join$1(dirPath, 'project.json'))) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Find the project root from a starting path.
+ * Project root is the nearest directory containing package.json
+ * with source files.
+ *
+ * @param startPath - Starting path
+ * @returns Project root path or null
+ *
+ * @example
+ * ```typescript
+ * import { findProjectRoot } from '@hyperfrontend/project-scope'
+ *
+ * // Find project root from current directory
+ * const root = findProjectRoot(process.cwd())
+ * if (root) {
+ *   console.log('Project root:', root)
+ * }
+ *
+ * // Find root from a deeply nested file
+ * const root2 = findProjectRoot('./libs/my-lib/src/utils/helper.ts')
+ * ```
+ */
+function findProjectRoot(startPath) {
+    rootLogger.debug('Finding project root', { startPath });
+    const result = findUpwardWhere(startPath, (dir) => {
+        if (exists(join$1(dir, 'package.json')) && looksLikeProjectDir(dir)) {
+            return true;
+        }
+        if (exists(join$1(dir, 'project.json'))) {
+            return true;
+        }
+        return false;
+    });
+    if (result) {
+        rootLogger.debug('Found project root', { root: result });
+    }
+    else {
+        rootLogger.debug('Project root not found');
+    }
+    return result;
+}
+/**
+ * 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;
+}
+/**
+ * Generic root finder - walk up looking for any marker file.
+ *
+ * @param startPath - Starting path
+ * @param markers - Files to search for
+ * @returns Root directory path or null
+ */
+function findRootDirectory(startPath, markers) {
+    return locateByMarkers(startPath, markers);
+}
+/**
+ * Find nearest .git directory (repo root).
+ *
+ * @param startPath - Starting path
+ * @returns Git root path or null
+ */
+function findGitRoot(startPath) {
+    return locateByMarkers(startPath, ['.git']);
+}
+
+export { CONFIG_PATTERNS, ROOT_MARKERS, WORKSPACE_MARKERS, clearConfigDetectionCache, detectConfigs, findConfigFile, findDirectories, findFiles, findFilesInTree, findGitRoot, findNearestPackageJson, findProjectRoot, findRootDirectory, findWorkspaceRoot, getAllDependencies, getConfigPaths, getConfigPatternsByType, getDependencies, getDependencyVersion, getDevDependencies, getInstalledVersion, getPeerDependencies, getProductionDependencies, getWorkspaces, hasDependency, hasInstalledPackage, hasWorkspaces, parseConfig, parseJsonConfig, parseYamlConfig, readConfigIfExists, readPackageJson, readPackageJsonIfExists, walkDirectory, walkTree };
+//# sourceMappingURL=index.esm.js.map