@hyperfrontend/project-scope 0.2.1 → 0.2.3

package/project/package/index.cjs.js

@@ -1,428 +1,24 @@
 'use strict';
 
-var node_path = require('node:path');
-var node_fs = require('node:fs');
-
-/**
- * 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
- */
-const _Array = globalThis.Array;
-/**
- * (Safe copy) Determines whether the passed value is an Array.
- */
-const isArray = _Array.isArray;
-
-/**
- * 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
- */
-const _Error = globalThis.Error;
-const _Reflect$1 = 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$1.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
- */
-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
- */
-const _Object = globalThis.Object;
-/**
- * (Safe copy) Prevents modification of existing property attributes and values,
- * and prevents the addition of new properties.
- */
-const freeze = _Object.freeze;
-/**
- * (Safe copy) Returns the names of the enumerable string properties and methods of an object.
- */
-const keys = _Object.keys;
-/**
- * (Safe copy) Returns an array of key/values of the enumerable own properties of an object.
- */
-const entries = _Object.entries;
-/**
- * (Safe copy) Returns an array of values of the enumerable own properties of an object.
- */
-const values = _Object.values;
-/**
- * (Safe copy) Adds one or more properties to an object, and/or modifies attributes of existing properties.
- */
-const defineProperties = _Object.defineProperties;
-
-/**
- * Create a structured error with code and optional context.
- *
- * @param message - The human-readable error message
- * @param code - The machine-readable error code for programmatic handling
- * @param context - Additional contextual information about the error
- * @returns Structured error instance with code and context properties
- *
- * @example
- * ```typescript
- * import { createStructuredError } from '@hyperfrontend/project-scope'
- *
- * throw createStructuredError(
- *   'Configuration file not found',
- *   'CONFIG_NOT_FOUND',
- *   { path: './config.json', searched: ['./config.json', './settings.json'] }
- * )
- * ```
- */
-function createStructuredError(message, code, context) {
-    const error = createError(message);
-    error.code = code;
-    error.context = context ?? {};
-    return error;
-}
-/**
- * Create a configuration-related error.
- *
- * @param message - The human-readable error message
- * @param code - The machine-readable error code for programmatic handling
- * @param context - Additional contextual information (e.g., file path, config key)
- * @returns Structured error instance tagged with type 'config'
- */
-function createConfigError(message, code, context) {
-    return createStructuredError(message, code, { ...context, type: 'config' });
-}
-
-/**
- * Safe copies of Console built-in methods.
- *
- * 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
- */
-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
- */
-const _Set = globalThis.Set;
-const _Reflect = 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.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;
-};
-
-/* 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);
+const node_path = require('node:path');
+const index_cjs_js$5 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.cjs.js');
+const index_cjs_js = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.cjs.js');
+const index_cjs_js$6 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.cjs.js');
+const index_cjs_js$3 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.cjs.js');
+const node_fs = require('node:fs');
+const index_cjs_js$4 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/console/index.cjs.js');
+const index_cjs_js$1 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/set/index.cjs.js');
+const index_cjs_js$2 = require('../../_dependencies/@hyperfrontend/logging/index.cjs.js');
+const { isSafePath } = require('../../_shared/core/fs/guard/index.cjs.js');
+const { exists } = require('../../_shared/core/fs/stat/index.cjs.js');
+const { join } = require('../../_shared/core/path/join/index.cjs.js');
+const { createConfigError } = require('../../_shared/core/errors/structured-errors/index.cjs.js');
 
 /**
  * Global log level registry.
  * Tracks all created scoped loggers to allow global log level changes.
  */
-const loggerRegistry = createSet();
+const loggerRegistry = index_cjs_js$1.createSet();
 /** Redacted placeholder for sensitive values */
 const REDACTED = '[REDACTED]';
 /**
@@ -456,17 +52,24 @@ 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) {
         return obj;
     }
-    if (isArray(obj)) {
+    if (index_cjs_js$5.isArray(obj)) {
         return obj.map((item) => sanitize(item));
     }
     if (typeof obj === 'object') {
         const result = {};
-        for (const [key, value] of entries(obj)) {
+        for (const [key, value] of index_cjs_js$3.entries(obj)) {
             if (isSensitiveKey(key)) {
                 result[key] = REDACTED;
             }
@@ -491,9 +94,9 @@ function sanitize(obj) {
  */
 function formatMessage(namespace, message, meta) {
     const prefix = `[${namespace}]`;
-    if (meta && keys(meta).length > 0) {
+    if (meta && index_cjs_js$3.keys(meta).length > 0) {
         const sanitizedMeta = sanitize(meta);
-        return `${prefix} ${message} ${stringify(sanitizedMeta)}`;
+        return `${prefix} ${message} ${index_cjs_js$6.stringify(sanitizedMeta)}`;
     }
     return `${prefix} ${message}`;
 }
@@ -506,7 +109,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')
@@ -525,9 +128,9 @@ function createScopedLogger(namespace, options = {}) {
         const processedMeta = sanitizeSecrets && meta ? sanitize(meta) : meta;
         baseFn(formatMessage(namespace, message, processedMeta));
     };
-    const baseLogger = createLogger(createLogFn(error), createLogFn(warn), createLogFn(log), createLogFn(info), createLogFn(debug));
+    const baseLogger = index_cjs_js$2.createLogger(createLogFn(index_cjs_js$4.error), createLogFn(index_cjs_js$4.warn), createLogFn(index_cjs_js$4.log), createLogFn(index_cjs_js$4.info), createLogFn(index_cjs_js$4.debug));
     baseLogger.setLogLevel(level);
-    const scopedLogger = freeze({
+    const scopedLogger = index_cjs_js$3.freeze({
         error: (message, meta) => baseLogger.error(message, meta),
         warn: (message, meta) => baseLogger.warn(message, meta),
         log: (message, meta) => baseLogger.log(message, meta),
@@ -543,7 +146,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'
  *
@@ -561,10 +164,19 @@ 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);
-    defineProperties(error, {
+    const error = index_cjs_js.createError(message);
+    index_cjs_js$3.defineProperties(error, {
         code: { value: code, enumerable: true },
         context: { value: context, enumerable: true },
     });
@@ -578,7 +190,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'
  *
@@ -587,6 +199,9 @@ function createFileSystemError(message, code, context) {
  * ```
  */
 function readFileContent(filePath, encoding = 'utf-8') {
+    if (!isSafePath(filePath)) {
+        throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
+    }
     if (!node_fs.existsSync(filePath)) {
         fsLogger.debug('File not found', { path: filePath });
         throw createFileSystemError(`File not found: ${filePath}`, 'FS_NOT_FOUND', { path: filePath, operation: 'read' });
@@ -605,9 +220,17 @@ 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 (!node_fs.existsSync(filePath)) {
+    if (!isSafePath(filePath) || !node_fs.existsSync(filePath)) {
         return null;
     }
     try {
@@ -618,31 +241,8 @@ function readFileIfExists(filePath, encoding = 'utf-8') {
     }
 }
 
-createScopedLogger('project-scope:fs:write');
-
-/**
- * Check if path exists.
- *
- * @param filePath - Path to check
- * @returns True if path exists
- */
-function exists(filePath) {
-    return node_fs.existsSync(filePath);
-}
-
 createScopedLogger('project-scope:fs:dir');
 
-/**
- * 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.
@@ -651,6 +251,15 @@ 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 });
@@ -676,6 +285,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 });
@@ -686,6 +306,8 @@ function locateByMarkers(startPath, markers) {
     return result;
 }
 
+createScopedLogger('project-scope:fs:write');
+
 const packageLogger = createScopedLogger('project-scope:project:package');
 /**
  * Verifies that a value is an object with only string values,
@@ -697,7 +319,7 @@ const packageLogger = createScopedLogger('project-scope:project:package');
 function isStringRecord(value) {
     if (typeof value !== 'object' || value === null)
         return false;
-    return values(value).every((v) => typeof v === 'string');
+    return index_cjs_js$3.values(value).every((v) => typeof v === 'string');
 }
 /**
  * Extracts and normalizes the workspaces field from package.json,
@@ -707,12 +329,12 @@ function isStringRecord(value) {
  * @returns Normalized workspace patterns or undefined if invalid
  */
 function parseWorkspaces(value) {
-    if (isArray(value) && value.every((v) => typeof v === 'string')) {
+    if (index_cjs_js$5.isArray(value) && value.every((v) => typeof v === 'string')) {
         return value;
     }
     if (typeof value === 'object' && value !== null) {
         const obj = value;
-        if (isArray(obj['packages'])) {
+        if (index_cjs_js$5.isArray(obj['packages'])) {
             return { packages: obj['packages'] };
         }
     }
@@ -726,7 +348,7 @@ function parseWorkspaces(value) {
  */
 function validatePackageJson(data) {
     if (typeof data !== 'object' || data === null) {
-        throw createError('package.json must be an object');
+        throw index_cjs_js.createError('package.json must be an object');
     }
     const pkg = data;
     return {
@@ -756,13 +378,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 : node_path.join(projectPath, 'package.json');
     packageLogger.debug('Reading package.json', { path: packageJsonPath });
     const content = readFileContent(packageJsonPath);
     try {
-        const data = parse(content);
+        const data = index_cjs_js$6.parse(content);
         const validated = validatePackageJson(data);
         packageLogger.debug('Package.json read successfully', { path: packageJsonPath, name: validated.name });
         return validated;
@@ -784,6 +414,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 : node_path.join(projectPath, 'package.json');
@@ -793,7 +433,7 @@ function readPackageJsonIfExists(projectPath) {
         return null;
     }
     try {
-        const validated = validatePackageJson(parse(content));
+        const validated = validatePackageJson(index_cjs_js$6.parse(content));
         packageLogger.debug('Package.json loaded', { path: packageJsonPath, name: validated.name });
         return validated;
     }
@@ -807,6 +447,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']);
@@ -817,6 +465,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 {
@@ -831,6 +488,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 ?? {};
@@ -840,6 +505,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 ?? {};
@@ -849,6 +522,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 ?? {};
@@ -858,6 +539,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 {
@@ -874,6 +565,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'];
@@ -890,6 +592,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);
@@ -900,11 +610,19 @@ 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)
         return [];
-    if (isArray(packageJson.workspaces)) {
+    if (index_cjs_js$5.isArray(packageJson.workspaces)) {
         return packageJson.workspaces;
     }
     if (typeof packageJson.workspaces === 'object' && 'packages' in packageJson.workspaces) {
@@ -917,6 +635,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;
@@ -927,29 +654,26 @@ 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 = node_path.join(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(node_path.join(projectPath, 'node_modules', packageName, 'package.json'));
-    return pkg?.version ?? null;
-}
 
 exports.findNearestPackageJson = findNearestPackageJson;
 exports.getAllDependencies = getAllDependencies;
 exports.getDependencies = getDependencies;
 exports.getDependencyVersion = getDependencyVersion;
 exports.getDevDependencies = getDevDependencies;
-exports.getInstalledVersion = getInstalledVersion;
 exports.getPeerDependencies = getPeerDependencies;
 exports.getProductionDependencies = getProductionDependencies;
 exports.getWorkspaces = getWorkspaces;
@@ -958,4 +682,3 @@ exports.hasInstalledPackage = hasInstalledPackage;
 exports.hasWorkspaces = hasWorkspaces;
 exports.readPackageJson = readPackageJson;
 exports.readPackageJsonIfExists = readPackageJsonIfExists;
-//# sourceMappingURL=index.cjs.js.map