@hyperfrontend/project-scope 0.1.0

package/nx/index.cjs.js

@@ -0,0 +1,1302 @@
+'use strict';
+
+var node_path = require('node:path');
+var node_fs = require('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');
+
+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 if exists, return null otherwise.
+ *
+ * @param filePath - Path to file
+ * @param encoding - File encoding (default: utf-8)
+ * @returns File contents or null if file doesn't exist
+ */
+function readFileIfExists(filePath, encoding = 'utf-8') {
+    if (!node_fs.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        return node_fs.readFileSync(filePath, { encoding });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read and parse JSON file if exists, return null otherwise.
+ *
+ * @param filePath - Path to JSON file
+ * @returns Parsed JSON object or null if file doesn't exist or is invalid
+ */
+function readJsonFileIfExists(filePath) {
+    if (!node_fs.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const content = node_fs.readFileSync(filePath, { encoding: 'utf-8' });
+        return parse(content);
+    }
+    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 (!node_fs.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const stat = followSymlinks ? node_fs.statSync(filePath) : node_fs.lstatSync(filePath);
+        return {
+            isFile: stat.isFile(),
+            isDirectory: stat.isDirectory(),
+            isSymlink: stat.isSymbolicLink(),
+            size: stat.size,
+            created: stat.birthtime,
+            modified: stat.mtime,
+            accessed: stat.atime,
+            mode: stat.mode,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if path is a directory.
+ *
+ * @param dirPath - Path to check
+ * @returns True if path is a directory
+ */
+function isDirectory(dirPath) {
+    const stats = getFileStat(dirPath);
+    return stats?.isDirectory ?? false;
+}
+/**
+ * Check if path exists.
+ *
+ * @param filePath - Path to check
+ * @returns True if path exists
+ */
+function exists(filePath) {
+    return node_fs.existsSync(filePath);
+}
+
+const fsDirLogger = createScopedLogger('project-scope:fs:dir');
+/**
+ * List immediate contents of a directory.
+ *
+ * @param dirPath - Absolute or relative path to the directory
+ * @returns Array of entries with metadata for each file/directory
+ * @throws {Error} If directory doesn't exist or isn't a directory
+ *
+ * @example
+ * ```typescript
+ * import { readDirectory } from '@hyperfrontend/project-scope'
+ *
+ * const entries = readDirectory('./src')
+ * for (const entry of entries) {
+ *   console.log(entry.name, entry.isFile ? 'file' : 'directory')
+ * }
+ * ```
+ */
+function readDirectory(dirPath) {
+    fsDirLogger.debug('Reading directory', { path: dirPath });
+    if (!node_fs.existsSync(dirPath)) {
+        fsDirLogger.debug('Directory not found', { path: dirPath });
+        throw createFileSystemError(`Directory not found: ${dirPath}`, 'FS_NOT_FOUND', { path: dirPath, operation: 'readdir' });
+    }
+    if (!isDirectory(dirPath)) {
+        fsDirLogger.debug('Path is not a directory', { path: dirPath });
+        throw createFileSystemError(`Not a directory: ${dirPath}`, 'FS_NOT_A_DIRECTORY', { path: dirPath, operation: 'readdir' });
+    }
+    try {
+        const entries = node_fs.readdirSync(dirPath, { withFileTypes: true });
+        fsDirLogger.debug('Directory read complete', { path: dirPath, entryCount: entries.length });
+        return entries.map((entry) => ({
+            name: entry.name,
+            path: node_path.join(dirPath, entry.name),
+            isFile: entry.isFile(),
+            isDirectory: entry.isDirectory(),
+            isSymlink: entry.isSymbolicLink(),
+        }));
+    }
+    catch (error) {
+        fsDirLogger.warn('Failed to read directory', { path: dirPath, error: error instanceof Error ? error.message : String(error) });
+        throw createFileSystemError(`Failed to read directory: ${dirPath}`, 'FS_READ_ERROR', {
+            path: dirPath,
+            operation: 'readdir',
+            cause: error,
+        });
+    }
+}
+
+/**
+ * Join path segments.
+ * Uses platform-specific separators (e.g., / or \).
+ *
+ * @param paths - Path segments to join
+ * @returns Joined path
+ */
+function join(...paths) {
+    return node_path.join(...paths);
+}
+
+const fsTraversalLogger = createScopedLogger('project-scope:fs:traversal');
+/**
+ * Generic upward directory traversal.
+ * Name avoids similarity to fs.readdir/fs.readdirSync.
+ *
+ * @param startPath - Starting directory
+ * @param predicate - Function to test each directory
+ * @returns First matching directory or null
+ */
+function traverseUpward(startPath, predicate) {
+    fsTraversalLogger.debug('Starting upward traversal', { startPath });
+    let currentPath = node_path.resolve(startPath);
+    const rootPath = node_path.parse(currentPath).root;
+    while (currentPath !== rootPath) {
+        if (predicate(currentPath)) {
+            fsTraversalLogger.debug('Upward traversal found match', { startPath, foundPath: currentPath });
+            return currentPath;
+        }
+        currentPath = node_path.dirname(currentPath);
+    }
+    // Check root directory
+    if (predicate(rootPath)) {
+        fsTraversalLogger.debug('Upward traversal found match at root', { startPath, foundPath: rootPath });
+        return rootPath;
+    }
+    fsTraversalLogger.debug('Upward traversal found no match', { startPath });
+    return null;
+}
+/**
+ * Find directory containing any of the specified marker files.
+ *
+ * @param startPath - Starting directory
+ * @param markers - Array of marker file names to search for
+ * @returns First directory containing any marker, or null
+ */
+function locateByMarkers(startPath, markers) {
+    fsTraversalLogger.debug('Locating by markers', { startPath, markers });
+    const result = traverseUpward(startPath, (dir) => markers.some((marker) => exists(join(dir, marker))));
+    if (result) {
+        fsTraversalLogger.debug('Found directory with marker', { startPath, foundPath: result });
+    }
+    return result;
+}
+
+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,
+    };
+}
+/**
+ * Attempts to read and parse package.json if it exists,
+ * returning null on missing file or parse failure.
+ *
+ * @param projectPath - Project directory path or path to package.json
+ * @returns Parsed package.json or null if not found
+ */
+function readPackageJsonIfExists(projectPath) {
+    const packageJsonPath = projectPath.endsWith('package.json') ? projectPath : node_path.join(projectPath, 'package.json');
+    const content = readFileIfExists(packageJsonPath);
+    if (!content) {
+        packageLogger.debug('Package.json not found', { path: packageJsonPath });
+        return null;
+    }
+    try {
+        const validated = validatePackageJson(parse(content));
+        packageLogger.debug('Package.json loaded', { path: packageJsonPath, name: validated.name });
+        return validated;
+    }
+    catch {
+        packageLogger.debug('Failed to parse package.json, returning null', { path: packageJsonPath });
+        return null;
+    }
+}
+
+createScopedLogger('project-scope:root');
+/**
+ * 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);
+}
+
+const nxLogger = createScopedLogger('project-scope:nx');
+/**
+ * Files indicating NX workspace root.
+ */
+const NX_CONFIG_FILES = ['nx.json', 'workspace.json'];
+/**
+ * NX-specific project file.
+ */
+const NX_PROJECT_FILE = 'project.json';
+/**
+ * Check if directory is an NX workspace root.
+ *
+ * @param path - Directory path to check
+ * @returns True if the directory contains nx.json or workspace.json
+ *
+ * @example
+ * ```typescript
+ * import { isNxWorkspace } from '@hyperfrontend/project-scope'
+ *
+ * if (isNxWorkspace('./my-project')) {
+ *   console.log('This is an NX monorepo')
+ * }
+ * ```
+ */
+function isNxWorkspace(path) {
+    for (const configFile of NX_CONFIG_FILES) {
+        if (exists(node_path.join(path, configFile))) {
+            nxLogger.debug('NX workspace detected', { path, configFile });
+            return true;
+        }
+    }
+    nxLogger.debug('Not an NX workspace', { path });
+    return false;
+}
+/**
+ * Check if directory is an NX project.
+ *
+ * @param path - Directory path to check
+ * @returns True if the directory contains project.json
+ */
+function isNxProject(path) {
+    const isProject = exists(node_path.join(path, NX_PROJECT_FILE));
+    nxLogger.debug('NX project check', { path, isProject });
+    return isProject;
+}
+/**
+ * Find NX workspace root from any path.
+ *
+ * @param startPath - Starting path to search from
+ * @returns Workspace root path or null if not found
+ *
+ * @example
+ * ```typescript
+ * import { findNxWorkspaceRoot } from '@hyperfrontend/project-scope'
+ *
+ * const root = findNxWorkspaceRoot('./libs/my-lib/src')
+ * if (root) {
+ *   console.log('Workspace root:', root) // e.g., '/home/user/my-monorepo'
+ * }
+ * ```
+ */
+function findNxWorkspaceRoot(startPath) {
+    nxLogger.debug('Finding NX workspace root', { startPath });
+    const result = findRootDirectory(startPath, NX_CONFIG_FILES);
+    if (result) {
+        nxLogger.debug('Found NX workspace root', { startPath, root: result });
+    }
+    else {
+        nxLogger.debug('NX workspace root not found', { startPath });
+    }
+    return result;
+}
+/**
+ * Detect NX version from package.json dependencies.
+ *
+ * @param workspacePath - Workspace root path
+ * @returns NX version string (without semver range) or null
+ */
+function detectNxVersion(workspacePath) {
+    const packageJson = readPackageJsonIfExists(workspacePath);
+    if (packageJson) {
+        const nxVersion = packageJson.devDependencies?.['nx'] ?? packageJson.dependencies?.['nx'];
+        if (nxVersion) {
+            // Strip semver range characters (^, ~, >=, etc.)
+            return nxVersion.replace(/^[\^~>=<]+/, '');
+        }
+    }
+    return null;
+}
+/**
+ * Check if workspace is integrated (not standalone).
+ * Integrated repos typically have workspaceLayout, namedInputs, or targetDefaults.
+ *
+ * @param nxJson - Parsed nx.json configuration
+ * @returns True if the workspace is integrated
+ */
+function isIntegratedRepo(nxJson) {
+    return nxJson.workspaceLayout !== undefined || nxJson.namedInputs !== undefined || nxJson.targetDefaults !== undefined;
+}
+/**
+ * Get comprehensive NX workspace information.
+ *
+ * @param workspacePath - Workspace root path
+ * @returns Workspace info or null if not an NX workspace
+ */
+function getNxWorkspaceInfo(workspacePath) {
+    nxLogger.debug('Getting NX workspace info', { workspacePath });
+    if (!isNxWorkspace(workspacePath)) {
+        return null;
+    }
+    const nxJson = readJsonFileIfExists(node_path.join(workspacePath, 'nx.json'));
+    if (!nxJson) {
+        // Check for workspace.json as fallback (older NX)
+        const workspaceJson = readJsonFileIfExists(node_path.join(workspacePath, 'workspace.json'));
+        if (!workspaceJson) {
+            nxLogger.debug('No nx.json or workspace.json found', { workspacePath });
+            return null;
+        }
+        nxLogger.debug('Using legacy workspace.json', { workspacePath });
+        // Create minimal nx.json from workspace.json
+        return {
+            root: workspacePath,
+            version: detectNxVersion(workspacePath),
+            nxJson: {},
+            isIntegrated: true,
+            workspaceLayout: {
+                appsDir: 'apps',
+                libsDir: 'libs',
+            },
+        };
+    }
+    const info = {
+        root: workspacePath,
+        version: detectNxVersion(workspacePath),
+        nxJson,
+        isIntegrated: isIntegratedRepo(nxJson),
+        defaultProject: nxJson.defaultProject,
+        workspaceLayout: {
+            appsDir: nxJson.workspaceLayout?.appsDir ?? 'apps',
+            libsDir: nxJson.workspaceLayout?.libsDir ?? 'libs',
+        },
+    };
+    nxLogger.debug('NX workspace info retrieved', {
+        workspacePath,
+        version: info.version,
+        isIntegrated: info.isIntegrated,
+        defaultProject: info.defaultProject,
+    });
+    return info;
+}
+
+const devkitLogger = createScopedLogger('project-scope:nx:devkit');
+/** Cached load result to avoid repeated require attempts */
+let cachedResult = null;
+/**
+ * Try to load `@nx/devkit` at runtime.
+ * Uses dynamic require to avoid bundling `@nx/devkit` into our output.
+ * Results are cached for subsequent calls.
+ *
+ * @returns DevkitLoadResult with availability status and devkit module or error
+ */
+function tryLoadDevkit() {
+    if (cachedResult !== null) {
+        devkitLogger.debug('Returning cached devkit result', { available: cachedResult.available });
+        return cachedResult;
+    }
+    devkitLogger.debug('Attempting to load @nx/devkit');
+    try {
+        // Dynamic require to avoid bundling
+        const devkit = require('@nx/devkit');
+        devkitLogger.debug('@nx/devkit loaded successfully');
+        cachedResult = { available: true, devkit };
+    }
+    catch (error) {
+        devkitLogger.debug('@nx/devkit not available', { error: error instanceof Error ? error.message : String(error) });
+        cachedResult = {
+            available: false,
+            error: error instanceof Error ? error : createError(String(error)),
+        };
+    }
+    return cachedResult;
+}
+/**
+ * Check if `@nx/devkit` is available.
+ *
+ * @returns true if devkit can be loaded, false otherwise
+ */
+function isDevkitAvailable() {
+    return tryLoadDevkit().available;
+}
+/**
+ * Get `@nx/devkit` module if available.
+ * Throws if not available.
+ *
+ * @returns The `@nx/devkit` module with full type information
+ * @throws {Error} If `@nx/devkit` is not available
+ */
+function getDevkit() {
+    const result = tryLoadDevkit();
+    if (!result.available) {
+        throw createError('@nx/devkit is not available. Install it as a dependency or use standalone mode.');
+    }
+    return result.devkit;
+}
+/**
+ * Execute function with `@nx/devkit` if available, otherwise execute fallback.
+ * This pattern allows graceful degradation when `@nx/devkit` is not installed.
+ *
+ * @param ifAvailable - Function to execute if `@nx/devkit` is available
+ * @param fallback - Function to execute if `@nx/devkit` is not available
+ * @returns Result from whichever function was executed
+ *
+ * @example
+ * ```typescript
+ * const tree = withDevkit(
+ *   (devkit) => devkit.createTree(),
+ *   () => new FsTree(process.cwd())
+ * )
+ * ```
+ */
+function withDevkit(ifAvailable, fallback) {
+    const result = tryLoadDevkit();
+    if (result.available && result.devkit) {
+        return ifAvailable(result.devkit);
+    }
+    return fallback();
+}
+/**
+ * Reset the cached devkit load result.
+ * Primarily useful for testing.
+ *
+ * @internal
+ */
+function resetDevkitCache() {
+    cachedResult = null;
+}
+
+const nxConfigLogger = createScopedLogger('project-scope:nx:config');
+/**
+ * Read project.json for an NX project.
+ *
+ * @param projectPath - Project directory path
+ * @returns Parsed project.json or null if not found
+ */
+function readProjectJson(projectPath) {
+    const projectJsonPath = node_path.join(projectPath, NX_PROJECT_FILE);
+    nxConfigLogger.debug('Reading project.json', { path: projectJsonPath });
+    const result = readJsonFileIfExists(projectJsonPath);
+    if (result) {
+        nxConfigLogger.debug('Project.json loaded', { path: projectJsonPath, name: result.name });
+    }
+    else {
+        nxConfigLogger.debug('Project.json not found', { path: projectJsonPath });
+    }
+    return result;
+}
+/**
+ * Get project configuration from project.json or package.json nx field.
+ *
+ * @param projectPath - Project directory path
+ * @param workspacePath - Workspace root path (for relative path calculation)
+ * @returns Project configuration or null if not found
+ */
+function getProjectConfig(projectPath, workspacePath) {
+    nxConfigLogger.debug('Getting project config', { projectPath, workspacePath });
+    // Try project.json first
+    const projectJson = readProjectJson(projectPath);
+    if (projectJson) {
+        nxConfigLogger.debug('Using project.json config', { projectPath, name: projectJson.name });
+        return {
+            ...projectJson,
+            root: projectJson.root ?? node_path.relative(workspacePath, projectPath),
+        };
+    }
+    // Try to infer from package.json nx field
+    const packageJson = readPackageJsonIfExists(projectPath);
+    if (packageJson && typeof packageJson['nx'] === 'object') {
+        nxConfigLogger.debug('Using package.json nx field', { projectPath, name: packageJson.name });
+        const nxConfig = packageJson['nx'];
+        return {
+            name: packageJson.name,
+            root: node_path.relative(workspacePath, projectPath),
+            ...nxConfig,
+        };
+    }
+    nxConfigLogger.debug('No project config found', { projectPath });
+    return null;
+}
+/**
+ * Recursively scan directory for project.json files.
+ *
+ * @param dirPath - Directory to scan
+ * @param workspacePath - Workspace root path
+ * @param projects - Map to add discovered projects to
+ * @param maxDepth - Maximum recursion depth
+ * @param currentDepth - Current recursion depth
+ */
+function scanForProjects(dirPath, workspacePath, projects, maxDepth, currentDepth = 0) {
+    if (currentDepth > maxDepth)
+        return;
+    try {
+        const entries = readDirectory(dirPath);
+        for (const entry of entries) {
+            // Skip node_modules and hidden directories
+            if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === 'dist') {
+                continue;
+            }
+            const fullPath = node_path.join(dirPath, entry.name);
+            if (entry.isDirectory) {
+                // Check if this directory is an NX project
+                if (isNxProject(fullPath)) {
+                    const config = getProjectConfig(fullPath, workspacePath);
+                    if (config) {
+                        const name = config.name || node_path.relative(workspacePath, fullPath).replace(/[\\/]/g, '-');
+                        projects.set(name, {
+                            ...config,
+                            name,
+                            root: node_path.relative(workspacePath, fullPath),
+                        });
+                    }
+                }
+                // Recursively scan subdirectories
+                scanForProjects(fullPath, workspacePath, projects, maxDepth, currentDepth + 1);
+            }
+        }
+    }
+    catch {
+        // Directory not readable, skip
+    }
+}
+/**
+ * Discover all NX projects in workspace.
+ * Supports both workspace.json (older format) and project.json (newer format).
+ *
+ * @param workspacePath - Workspace root path
+ * @returns Map of project name to configuration
+ */
+function discoverNxProjects(workspacePath) {
+    const projects = createMap();
+    // Check for workspace.json (older NX format)
+    const workspaceJson = readJsonFileIfExists(node_path.join(workspacePath, 'workspace.json'));
+    if (workspaceJson?.projects) {
+        for (const [name, config] of entries(workspaceJson.projects)) {
+            if (typeof config === 'string') {
+                // Path reference to project directory
+                const projectPath = node_path.join(workspacePath, config);
+                const projectConfig = getProjectConfig(projectPath, workspacePath);
+                if (projectConfig) {
+                    projects.set(name, { ...projectConfig, name });
+                }
+            }
+            else if (typeof config === 'object' && config !== null) {
+                // Inline config
+                projects.set(name, { name, ...config });
+            }
+        }
+        return projects;
+    }
+    // Scan for project.json files (newer NX format)
+    const workspaceInfo = getNxWorkspaceInfo(workspacePath);
+    const appsDir = workspaceInfo?.workspaceLayout.appsDir ?? 'apps';
+    const libsDir = workspaceInfo?.workspaceLayout.libsDir ?? 'libs';
+    const searchDirs = [appsDir, libsDir];
+    // Also check packages directory (common in some setups)
+    if (exists(node_path.join(workspacePath, 'packages'))) {
+        searchDirs.push('packages');
+    }
+    for (const dir of searchDirs) {
+        const dirPath = node_path.join(workspacePath, dir);
+        if (exists(dirPath) && isDirectory(dirPath)) {
+            try {
+                scanForProjects(dirPath, workspacePath, projects, 3);
+            }
+            catch {
+                // Directory not accessible
+            }
+        }
+    }
+    // Also check root-level projects (standalone projects in monorepo root)
+    if (isNxProject(workspacePath)) {
+        const config = readProjectJson(workspacePath);
+        if (config) {
+            const name = config.name || node_path.basename(workspacePath);
+            projects.set(name, {
+                ...config,
+                name,
+                root: '.',
+            });
+        }
+    }
+    return projects;
+}
+/**
+ * Build a simple project graph from discovered projects.
+ * For full graph capabilities, use `@nx/devkit`.
+ *
+ * @param workspacePath - Workspace root path
+ * @param projects - Existing configuration map to skip auto-discovery
+ * @returns NxProjectGraph with nodes and dependencies
+ */
+function buildSimpleProjectGraph(workspacePath, projects) {
+    const projectMap = projects ?? discoverNxProjects(workspacePath);
+    const nodes = {};
+    const dependencies = {};
+    for (const [name, config] of projectMap) {
+        nodes[name] = {
+            name,
+            type: config.projectType ?? 'library',
+            data: config,
+        };
+        dependencies[name] = [];
+        // Add implicit dependencies
+        if (config.implicitDependencies) {
+            for (const dep of config.implicitDependencies) {
+                // Skip negative dependencies (those starting with !)
+                if (!dep.startsWith('!')) {
+                    dependencies[name].push({
+                        target: dep,
+                        type: 'implicit',
+                    });
+                }
+            }
+        }
+    }
+    return { nodes, dependencies };
+}
+
+exports.NX_CONFIG_FILES = NX_CONFIG_FILES;
+exports.NX_PROJECT_FILE = NX_PROJECT_FILE;
+exports.buildSimpleProjectGraph = buildSimpleProjectGraph;
+exports.discoverNxProjects = discoverNxProjects;
+exports.findNxWorkspaceRoot = findNxWorkspaceRoot;
+exports.getDevkit = getDevkit;
+exports.getNxWorkspaceInfo = getNxWorkspaceInfo;
+exports.getProjectConfig = getProjectConfig;
+exports.isDevkitAvailable = isDevkitAvailable;
+exports.isNxProject = isNxProject;
+exports.isNxWorkspace = isNxWorkspace;
+exports.readProjectJson = readProjectJson;
+exports.resetDevkitCache = resetDevkitCache;
+exports.tryLoadDevkit = tryLoadDevkit;
+exports.withDevkit = withDevkit;
+//# sourceMappingURL=index.cjs.js.map