@hyperfrontend/project-scope 0.2.0 → 0.2.2

package/project/index.esm.js

@@ -1,412 +1,20 @@
-import { join as join$1, resolve, parse as parse$1, dirname, basename } from 'node:path';
+import { join as join$1, resolve, parse, dirname, basename } from 'node:path';
+import { freeze, entries, keys, defineProperties, values } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.esm.js';
+import { createMap } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/map/index.esm.js';
+import { createSet } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/set/index.esm.js';
 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);
+import { isArray } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.esm.js';
+import { error, warn, log, info, debug } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/console/index.esm.js';
+import { stringify, parse as parse$1 } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.esm.js';
+import { createLogger } from '../_dependencies/@hyperfrontend/logging/index.esm.js';
+import { createError } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.esm.js';
+import { parseInt, parseFloat } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/number/index.esm.js';
+import { isDirectory, exists } from '../_shared/core/fs/stat/index.esm.js';
+import { join } from '../_shared/core/path/join/index.esm.js';
+import { createConfigError } from '../_shared/core/errors/structured-errors/index.esm.js';
+import { createCache } from '../_shared/core/cache/index.esm.js';
+import { matchGlobPattern } from '../_shared/core/patterns/glob/index.esm.js';
+import { CONFIG_PATTERNS, getConfigPatternsByType } from '../_shared/project/config/patterns/index.esm.js';
 
 /**
  * Global log level registry.
@@ -446,6 +54,13 @@ function isSensitiveKey(key) {
  *
  * @param obj - Object to sanitize
  * @returns New object with sensitive values redacted
+ *
+ * @example Sanitizing sensitive data
+ * ```typescript
+ * const config = { apiKey: 'secret123', endpoint: 'https://api.example.com' }
+ * const safe = sanitize(config)
+ * // => { apiKey: '[REDACTED]', endpoint: 'https://api.example.com' }
+ * ```
  */
 function sanitize(obj) {
     if (obj === null || obj === undefined) {
@@ -496,7 +111,7 @@ function formatMessage(namespace, message, meta) {
  * @param options - Logger configuration options
  * @returns A configured scoped logger instance
  *
- * @example
+ * @example Creating a scoped logger
  * ```typescript
  * const logger = createScopedLogger('project-scope')
  * logger.setLogLevel('debug')
@@ -511,14 +126,11 @@ function formatMessage(namespace, message, meta) {
  */
 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),
@@ -529,7 +141,6 @@ function createScopedLogger(namespace, options = {}) {
         setLogLevel: baseLogger.setLogLevel,
         getLogLevel: baseLogger.getLogLevel,
     });
-    // Register logger for global level management
     loggerRegistry.add(scopedLogger);
     return scopedLogger;
 }
@@ -537,7 +148,7 @@ function createScopedLogger(namespace, options = {}) {
  * Default logger instance for the project-scope library.
  * Use this for general logging within the library.
  *
- * @example
+ * @example Using the default logger
  * ```typescript
  * import { logger } from '@hyperfrontend/project-scope/core'
  *
@@ -555,6 +166,15 @@ const fsLogger = createScopedLogger('project-scope:fs');
  * @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
+ *
+ * @example Creating a file system error
+ * ```typescript
+ * throw createFileSystemError(
+ *   'Cannot read file',
+ *   'FS_READ_ERROR',
+ *   { path: './missing.txt', operation: 'read' }
+ * )
+ * ```
  */
 function createFileSystemError(message, code, context) {
     const error = createError(message);
@@ -572,7 +192,7 @@ function createFileSystemError(message, code, context) {
  * @returns File contents as string
  * @throws {Error} If file doesn't exist or can't be read
  *
- * @example
+ * @example Reading file contents
  * ```typescript
  * import { readFileContent } from '@hyperfrontend/project-scope'
  *
@@ -599,6 +219,14 @@ function readFileContent(filePath, encoding = 'utf-8') {
  * @param filePath - Path to file
  * @param encoding - File encoding (default: utf-8)
  * @returns File contents or null if file doesn't exist
+ *
+ * @example Reading file if it exists
+ * ```typescript
+ * const content = readFileIfExists('./optional-config.json')
+ * if (content) {
+ *   // File existed, use content
+ * }
+ * ```
  */
 function readFileIfExists(filePath, encoding = 'utf-8') {
     if (!existsSync(filePath)) {
@@ -612,56 +240,6 @@ function readFileIfExists(filePath, encoding = 'utf-8') {
     }
 }
 
-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.
@@ -670,7 +248,7 @@ const fsDirLogger = createScopedLogger('project-scope:fs:dir');
  * @returns Array of entries with metadata for each file/directory
  * @throws {Error} If directory doesn't exist or isn't a directory
  *
- * @example
+ * @example Listing directory contents
  * ```typescript
  * import { readDirectory } from '@hyperfrontend/project-scope'
  *
@@ -711,17 +289,6 @@ function readDirectory(dirPath) {
     }
 }
 
-/**
- * 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.
@@ -730,11 +297,20 @@ const fsTraversalLogger = createScopedLogger('project-scope:fs:traversal');
  * @param startPath - Starting directory
  * @param predicate - Function to test each directory
  * @returns First matching directory or null
+ *
+ * @example Finding directory containing README
+ * ```typescript
+ * // Find first directory containing a README
+ * const readmeDir = traverseUpward('./src/utils', (dir) =>
+ *   existsSync(join(dir, 'README.md'))
+ * )
+ * // => '/project' or null
+ * ```
  */
 function traverseUpward(startPath, predicate) {
     fsTraversalLogger.debug('Starting upward traversal', { startPath });
     let currentPath = resolve(startPath);
-    const rootPath = parse$1(currentPath).root;
+    const rootPath = parse(currentPath).root;
     while (currentPath !== rootPath) {
         if (predicate(currentPath)) {
             fsTraversalLogger.debug('Upward traversal found match', { startPath, foundPath: currentPath });
@@ -742,7 +318,6 @@ function traverseUpward(startPath, predicate) {
         }
         currentPath = dirname(currentPath);
     }
-    // Check root directory
     if (predicate(rootPath)) {
         fsTraversalLogger.debug('Upward traversal found match at root', { startPath, foundPath: rootPath });
         return rootPath;
@@ -756,6 +331,17 @@ function traverseUpward(startPath, predicate) {
  * @param startPath - Starting directory
  * @param markers - Array of marker file names to search for
  * @returns First directory containing any marker, or null
+ *
+ * @example Finding project root by marker files
+ * ```typescript
+ * // Find project root by looking for common marker files
+ * const projectRoot = locateByMarkers('./src/components', [
+ *   'package.json',
+ *   'nx.json',
+ *   'tsconfig.base.json'
+ * ])
+ * // => '/workspace/my-project'
+ * ```
  */
 function locateByMarkers(startPath, markers) {
     fsTraversalLogger.debug('Locating by markers', { startPath, markers });
@@ -771,217 +357,21 @@ function locateByMarkers(startPath, markers) {
  * @param startPath - Starting directory
  * @param test - Function to test if directory matches criteria
  * @returns Matching directory path or null
+ *
+ * @example Finding directory with specific config
+ * ```typescript
+ * // Find directory with a specific config
+ * const configDir = findUpwardWhere('./deep/nested/path', (dir) =>
+ *   existsSync(join(dir, '.eslintrc.js'))
+ * )
+ * ```
  */
 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;
-}
+createScopedLogger('project-scope:fs:write');
 
 const walkLogger = createScopedLogger('project-scope:project:walk');
 /**
@@ -1048,6 +438,18 @@ function matchPattern(path, pattern) {
  * @param startPath - Root directory to begin traversal
  * @param visitor - Callback function invoked for each file system entry
  * @param options - Configuration for traversal behavior
+ *
+ * @example Walking a directory tree
+ * ```typescript
+ * import { walkDirectory } from '@hyperfrontend/project-scope'
+ *
+ * const tsFiles: string[] = []
+ * walkDirectory('./src', (entry) => {
+ *   if (entry.isFile && entry.name.endsWith('.ts')) {
+ *     tsFiles.push(entry.relativePath)
+ *   }
+ * }, { maxDepth: 5, respectGitignore: true })
+ * ```
  */
 function walkDirectory(startPath, visitor, options) {
     walkLogger.debug('Starting directory walk', {
@@ -1130,6 +532,19 @@ function walkDirectory(startPath, visitor, options) {
  * @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
+ *
+ * @example Walking a virtual tree
+ * ```typescript
+ * import { createTree, walkTree } from '@hyperfrontend/project-scope'
+ *
+ * const tree = createTree('/workspace')
+ * walkTree(tree, 'src', (entry) => {
+ *   if (entry.isDirectory) {
+ *     console.log('Dir:', entry.relativePath)
+ *     return 'skip' // Don't recurse into this directory
+ *   }
+ * })
+ * ```
  */
 function walkTree(tree, startPath, visitor, options) {
     const maxDepth = options?.maxDepth ?? -1;
@@ -1210,7 +625,7 @@ function matchesPatterns(path, patterns) {
  * @param options - Configuration for search behavior
  * @returns List of relative file paths that match the patterns
  *
- * @example
+ * @example Finding files by pattern
  * ```typescript
  * import { findFiles } from '@hyperfrontend/project-scope'
  *
@@ -1255,6 +670,15 @@ function findFiles(startPath, patterns, options) {
  * @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
+ *
+ * @example Finding files in a virtual tree
+ * ```typescript
+ * import { createTree, findFilesInTree } from '@hyperfrontend/project-scope'
+ *
+ * const tree = createTree('/workspace')
+ * const tsFiles = findFilesInTree(tree, '**\/*.ts', { maxDepth: 3 })
+ * // => ['src/index.ts', 'src/utils/helpers.ts']
+ * ```
  */
 function findFilesInTree(tree, patterns, options) {
     const normalizedPatterns = isArray(patterns) ? patterns : [patterns];
@@ -1282,6 +706,14 @@ function findFilesInTree(tree, patterns, options) {
  * @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
+ *
+ * @example Finding directories by pattern
+ * ```typescript
+ * import { findDirectories } from '@hyperfrontend/project-scope'
+ *
+ * const componentDirs = findDirectories('./src', 'components')
+ * // => ['features/auth/components', 'features/dashboard/components']
+ * ```
  */
 function findDirectories(startPath, patterns, options) {
     const normalizedPatterns = isArray(patterns) ? patterns : [patterns];
@@ -1302,324 +734,6 @@ function findDirectories(startPath, patterns, 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.
@@ -1637,7 +751,7 @@ const configDetectionCache = createCache({ ttl: 30000, maxSize: 50 });
  * @param options - Detection options
  * @returns Array of detected configuration files
  *
- * @example
+ * @example Detecting configuration files
  * ```typescript
  * import { detectConfigs } from '@hyperfrontend/project-scope'
  *
@@ -1717,6 +831,14 @@ function detectConfigs(rootPath, types, options) {
  * Clear the config detection cache.
  *
  * Useful for testing or when the project files have changed.
+ *
+ * @example Clearing the config detection cache
+ * ```typescript
+ * import { clearConfigDetectionCache } from '@hyperfrontend/project-scope'
+ *
+ * // Reset cache after modifying config files
+ * clearConfigDetectionCache()
+ * ```
  */
 function clearConfigDetectionCache() {
     configDetectionCache.clear();
@@ -1727,6 +849,17 @@ function clearConfigDetectionCache() {
  * @param rootPath - Project root directory
  * @param type - Config type to find
  * @returns Full path to config file or null if not found
+ *
+ * @example Finding a specific config file
+ * ```typescript
+ * import { findConfigFile } from '@hyperfrontend/project-scope'
+ *
+ * const tsConfig = findConfigFile('/project', 'typescript')
+ * // => '/project/tsconfig.json'
+ *
+ * const eslint = findConfigFile('/project', 'eslint')
+ * // => '/project/.eslintrc.js' or null if not found
+ * ```
  */
 function findConfigFile(rootPath, type) {
     const info = CONFIG_PATTERNS[type];
@@ -1750,76 +883,6 @@ function findConfigFile(rootPath, type) {
     }
     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.
@@ -2032,11 +1095,23 @@ function parseDotenv(content) {
  * @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
+ *
+ * @example Parsing JSON configuration
+ * ```typescript
+ * import { parseJsonConfig } from '@hyperfrontend/project-scope'
+ *
+ * const config = parseJsonConfig(
+ *   'tsconfig.json',
+ *   '{ "extends": "./base.json", "compilerOptions": {} }',
+ *   'typescript'
+ * )
+ * // => { type: 'typescript', path: 'tsconfig.json', data: {...}, extends: ['./base.json'] }
+ * ```
  */
 function parseJsonConfig(filePath, content, type, format = 'json') {
     const cleanContent = format === 'jsonc' ? stripJsonComments(content) : content;
     try {
-        const data = parse(cleanContent);
+        const data = parse$1(cleanContent);
         let extendsPath;
         if (typeof data['extends'] === 'string') {
             extendsPath = [data['extends']];
@@ -2067,6 +1142,14 @@ function parseJsonConfig(filePath, content, type, format = 'json') {
  * @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
+ *
+ * @example Parsing YAML configuration
+ * ```typescript
+ * import { parseYamlConfig } from '@hyperfrontend/project-scope'
+ *
+ * const config = parseYamlConfig('.github/workflows/ci.yml', yamlContent, 'github-actions')
+ * // => { type: 'github-actions', path: '...', format: 'yaml', data: {...} }
+ * ```
  */
 function parseYamlConfig(filePath, content, type) {
     const data = parseSimpleYaml(content);
@@ -2083,6 +1166,14 @@ function parseYamlConfig(filePath, content, type) {
  * @param filePath - Path to config file
  * @param type - Optional config type (auto-detected if not provided)
  * @returns Parsed configuration
+ *
+ * @example Parsing a configuration file
+ * ```typescript
+ * import { parseConfig } from '@hyperfrontend/project-scope'
+ *
+ * const tsConfig = parseConfig('/project/tsconfig.json')
+ * const eslintConfig = parseConfig('/project/.eslintrc.yml', 'eslint')
+ * ```
  */
 function parseConfig(filePath, type) {
     const content = readFileContent(filePath);
@@ -2127,33 +1218,6 @@ function parseConfig(filePath, type) {
             };
     }
 }
-/**
- * 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');
 /**
@@ -2225,13 +1289,21 @@ function validatePackageJson(data) {
  * @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
+ *
+ * @example Reading package.json
+ * ```typescript
+ * import { readPackageJson } from '@hyperfrontend/project-scope'
+ *
+ * const pkg = readPackageJson('/path/to/project')
+ * console.log(pkg.name, pkg.version)
+ * ```
  */
 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 data = parse$1(content);
         const validated = validatePackageJson(data);
         packageLogger.debug('Package.json read successfully', { path: packageJsonPath, name: validated.name });
         return validated;
@@ -2253,6 +1325,16 @@ function readPackageJson(projectPath) {
  *
  * @param projectPath - Project directory path or path to package.json
  * @returns Parsed package.json or null if not found
+ *
+ * @example Reading package.json if it exists
+ * ```typescript
+ * import { readPackageJsonIfExists } from '@hyperfrontend/project-scope'
+ *
+ * const pkg = readPackageJsonIfExists('/path/to/project')
+ * if (pkg) {
+ *   console.log('Found:', pkg.name)
+ * }
+ * ```
  */
 function readPackageJsonIfExists(projectPath) {
     const packageJsonPath = projectPath.endsWith('package.json') ? projectPath : join$1(projectPath, 'package.json');
@@ -2262,7 +1344,7 @@ function readPackageJsonIfExists(projectPath) {
         return null;
     }
     try {
-        const validated = validatePackageJson(parse(content));
+        const validated = validatePackageJson(parse$1(content));
         packageLogger.debug('Package.json loaded', { path: packageJsonPath, name: validated.name });
         return validated;
     }
@@ -2276,6 +1358,14 @@ function readPackageJsonIfExists(projectPath) {
  *
  * @param startPath - Starting path
  * @returns Path to directory containing package.json, or null if not found
+ *
+ * @example Finding nearest package.json
+ * ```typescript
+ * import { findNearestPackageJson } from '@hyperfrontend/project-scope'
+ *
+ * const pkgDir = findNearestPackageJson('./src/deep/nested/file.ts')
+ * // => '/path/to/project'
+ * ```
  */
 function findNearestPackageJson(startPath) {
     return locateByMarkers(startPath, ['package.json']);
@@ -2286,6 +1376,15 @@ function findNearestPackageJson(startPath) {
  *
  * @param packageJson - Parsed package.json
  * @returns All dependencies categorized
+ *
+ * @example Extracting all dependencies
+ * ```typescript
+ * import { getDependencies } from '@hyperfrontend/project-scope'
+ *
+ * const deps = getDependencies(packageJson)
+ * console.log('Runtime:', Object.keys(deps.dependencies))
+ * console.log('Dev:', Object.keys(deps.devDependencies))
+ * ```
  */
 function getDependencies(packageJson) {
     return {
@@ -2300,6 +1399,14 @@ function getDependencies(packageJson) {
  *
  * @param packageJson - Parsed package.json
  * @returns Map of dependency name to version for runtime dependencies
+ *
+ * @example Getting production dependencies
+ * ```typescript
+ * import { getProductionDependencies } from '@hyperfrontend/project-scope'
+ *
+ * const prodDeps = getProductionDependencies(packageJson)
+ * // => { 'express': '^4.18.0', 'lodash': '^4.17.21' }
+ * ```
  */
 function getProductionDependencies(packageJson) {
     return packageJson.dependencies ?? {};
@@ -2309,6 +1416,14 @@ function getProductionDependencies(packageJson) {
  *
  * @param packageJson - Parsed package.json
  * @returns Map of dependency name to version for dev-time dependencies
+ *
+ * @example Getting development dependencies
+ * ```typescript
+ * import { getDevDependencies } from '@hyperfrontend/project-scope'
+ *
+ * const devDeps = getDevDependencies(packageJson)
+ * // => { 'jest': '^29.0.0', 'typescript': '^5.0.0' }
+ * ```
  */
 function getDevDependencies(packageJson) {
     return packageJson.devDependencies ?? {};
@@ -2318,6 +1433,14 @@ function getDevDependencies(packageJson) {
  *
  * @param packageJson - Parsed package.json
  * @returns Map of dependency name to version for peer requirements
+ *
+ * @example Getting peer dependencies
+ * ```typescript
+ * import { getPeerDependencies } from '@hyperfrontend/project-scope'
+ *
+ * const peerDeps = getPeerDependencies(packageJson)
+ * // => { 'react': '^18.0.0', 'react-dom': '^18.0.0' }
+ * ```
  */
 function getPeerDependencies(packageJson) {
     return packageJson.peerDependencies ?? {};
@@ -2327,6 +1450,16 @@ function getPeerDependencies(packageJson) {
  *
  * @param packageJson - Parsed package.json
  * @returns All dependencies merged
+ *
+ * @example Getting all merged dependencies
+ * ```typescript
+ * import { getAllDependencies } from '@hyperfrontend/project-scope'
+ *
+ * const allDeps = getAllDependencies(packageJson)
+ * if ('typescript' in allDeps) {
+ *   console.log('TypeScript version:', allDeps['typescript'])
+ * }
+ * ```
  */
 function getAllDependencies(packageJson) {
     return {
@@ -2343,6 +1476,17 @@ function getAllDependencies(packageJson) {
  * @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
+ *
+ * @example Checking for a dependency
+ * ```typescript
+ * import { hasDependency } from '@hyperfrontend/project-scope'
+ *
+ * // Check any dependency type
+ * hasDependency(packageJson, 'lodash')
+ *
+ * // Check only production dependencies
+ * hasDependency(packageJson, 'lodash', ['dependencies'])
+ * ```
  */
 function hasDependency(packageJson, name, depTypes) {
     const typesToCheck = depTypes ?? ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
@@ -2359,6 +1503,14 @@ function hasDependency(packageJson, name, depTypes) {
  * @param packageJson - Parsed package.json content
  * @param name - Name of the dependency to look up
  * @returns Version string or null if not found
+ *
+ * @example Getting dependency version
+ * ```typescript
+ * import { getDependencyVersion } from '@hyperfrontend/project-scope'
+ *
+ * const version = getDependencyVersion(packageJson, 'react')
+ * // => '^18.2.0' or null
+ * ```
  */
 function getDependencyVersion(packageJson, name) {
     const deps = getDependencies(packageJson);
@@ -2369,6 +1521,14 @@ function getDependencyVersion(packageJson, name) {
  *
  * @param packageJson - Parsed package.json
  * @returns Array of workspace patterns or empty array
+ *
+ * @example Getting workspace patterns
+ * ```typescript
+ * import { getWorkspaces } from '@hyperfrontend/project-scope'
+ *
+ * const patterns = getWorkspaces(packageJson)
+ * // => ['packages/*', 'apps/*']
+ * ```
  */
 function getWorkspaces(packageJson) {
     if (!packageJson.workspaces)
@@ -2386,6 +1546,15 @@ function getWorkspaces(packageJson) {
  *
  * @param packageJson - Parsed package.json
  * @returns True if workspaces are defined
+ *
+ * @example Checking for workspaces
+ * ```typescript
+ * import { hasWorkspaces } from '@hyperfrontend/project-scope'
+ *
+ * if (hasWorkspaces(packageJson)) {
+ *   console.log('This is a monorepo')
+ * }
+ * ```
  */
 function hasWorkspaces(packageJson) {
     return getWorkspaces(packageJson).length > 0;
@@ -2396,22 +1565,20 @@ function hasWorkspaces(packageJson) {
  * @param projectPath - Project root directory
  * @param packageName - Package name to check
  * @returns Boolean indicating whether the package exists in node_modules
+ *
+ * @example Checking installed packages
+ * ```typescript
+ * import { hasInstalledPackage } from '@hyperfrontend/project-scope'
+ *
+ * if (hasInstalledPackage('/project', 'typescript')) {
+ *   console.log('TypeScript is installed')
+ * }
+ * ```
  */
 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');
 /**
@@ -2451,7 +1618,7 @@ function looksLikeProjectDir(dirPath) {
  * @param startPath - Starting path
  * @returns Project root path or null
  *
- * @example
+ * @example Finding project root
  * ```typescript
  * import { findProjectRoot } from '@hyperfrontend/project-scope'
  *
@@ -2491,7 +1658,7 @@ function findProjectRoot(startPath) {
  * @param startPath - Starting path
  * @returns Workspace root path or null
  *
- * @example
+ * @example Finding workspace root
  * ```typescript
  * import { findWorkspaceRoot } from '@hyperfrontend/project-scope'
  *
@@ -2531,6 +1698,15 @@ function findWorkspaceRoot(startPath) {
  * @param startPath - Starting path
  * @param markers - Files to search for
  * @returns Root directory path or null
+ *
+ * @example Finding root by marker files
+ * ```typescript
+ * import { findRootDirectory } from '@hyperfrontend/project-scope'
+ *
+ * // Find monorepo root by looking for nx.json or lerna.json
+ * const root = findRootDirectory('./libs/my-lib', ['nx.json', 'lerna.json'])
+ * // => '/path/to/monorepo'
+ * ```
  */
 function findRootDirectory(startPath, markers) {
     return locateByMarkers(startPath, markers);
@@ -2540,10 +1716,17 @@ function findRootDirectory(startPath, markers) {
  *
  * @param startPath - Starting path
  * @returns Git root path or null
+ *
+ * @example Finding Git repository root
+ * ```typescript
+ * import { findGitRoot } from '@hyperfrontend/project-scope'
+ *
+ * const gitRoot = findGitRoot('./src/deep/nested/file.ts')
+ * // => '/path/to/repository'
+ * ```
  */
 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
+export { CONFIG_PATTERNS, ROOT_MARKERS, WORKSPACE_MARKERS, clearConfigDetectionCache, detectConfigs, findConfigFile, findDirectories, findFiles, findFilesInTree, findGitRoot, findNearestPackageJson, findProjectRoot, findRootDirectory, findWorkspaceRoot, getAllDependencies, getConfigPatternsByType, getDependencies, getDependencyVersion, getDevDependencies, getPeerDependencies, getProductionDependencies, getWorkspaces, hasDependency, hasInstalledPackage, hasWorkspaces, parseConfig, parseJsonConfig, parseYamlConfig, readPackageJson, readPackageJsonIfExists, walkDirectory, walkTree };