@hyperfrontend/project-scope 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -2,7 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
-## [0.2.1](https://github.com/AndrewRedican/hyperfrontend/compare/a9185d9b783d7d8d51cc4ad91eb3178eba3e3930...f358c827dea7ad2a7d8f235673daf5b2bd4257a3) - 2026-04-06
+## [0.2.3](https://github.com/AndrewRedican/hyperfrontend/compare/5f116abb8ba6355dfb283fa03b7481e5eb029480...7fb26b6a30c007cd0392f1fc973265c3d25e16dd) - 2026-06-28
+
+### Bug Fixes
+
+- confine import resolution to the project root
+- reject NUL-byte paths in fs primitives
+
+## [0.2.2](https://github.com/AndrewRedican/hyperfrontend/compare/d96fee4d4d3a70178c8a01e5f2e2ae675fa23f37...466c0388c4cd516b9c704214140b4df1004098e6) - 2026-06-23
+
+### Other
+
+- **@hyperfrontend/workspace:** remove lib-builder and tool-package as implicit dependencies for all lib projects
+
+## [0.2.1](https://github.com/AndrewRedican/hyperfrontend/compare/a9185d9b783d7d8d51cc4ad91eb3178eba3e3930...61a93d778d6b84915c51120f315e81b3a16fd67c) - 2026-04-06
 
 ### Bug Fixes
 

package/README.md

@@ -41,13 +41,13 @@ Comprehensive project analysis, technology stack detection, and transactional vi
 
 @hyperfrontend/project-scope provides intelligent codebase analysis for JavaScript/TypeScript projects. It uses multi-signal heuristics to classify project types, detect frameworks and build tools, discover entry points, and map dependency graphs - all with confidence scoring and explainable evidence. The library also includes a virtual file system (VFS) for safe, atomic file modifications.
 
-Designed for tooling authors building code generators, IDE extensions, CI/CD pipelines, and monorepo tooling. Optional `@nx/devkit` integration enables seamless operation within NX workspaces with graceful fallback for standalone projects.
+Designed for tooling authors building code generators, IDE extensions, CI/CD pipelines, and monorepo tooling. Built-in NX workspace detection reads `nx.json`, `workspace.json`, and `project.json` so tooling can adapt to NX-shaped repos with zero runtime peer dependencies.
 
 ### Key Features
 
 - **Project Classification** - Detect application, library, e2e, tool, or plugin with confidence scoring and evidence tracking
 - **Technology Detection** - Identify 20+ frameworks (React, Vue, Angular, Svelte), build tools (Vite, Webpack, esbuild), and testing frameworks (Jest, Vitest, Cypress)
-- **Virtual File System** - Transaction-aware file operations with atomic commit/rollback, following NX devkit's Tree interface
+- **Virtual File System** - Transaction-aware file operations with atomic commit/rollback
 - **Monorepo Intelligence** - Detect NX, Turborepo, Lerna, pnpm/npm/Yarn workspaces; read project configurations
 - **Dependency Graph** - Build internal import graphs from source code with root/leaf node identification
 - **Entry Point Discovery** - Find application entries from package.json exports, bin fields, and convention patterns
@@ -179,7 +179,6 @@ project-scope tree ./my-project --depth 3
 - **`isNxWorkspace(path): boolean`** - Check if directory is NX workspace
 - **`getNxWorkspaceInfo(path): NxWorkspaceInfo`** - Get workspace details
 - **`findNxProjects(path): NxProjectConfig[]`** - Find all projects
-- **`isDevkitAvailable(): boolean`** - Check if `@nx/devkit` is available
 
 ### Core Utilities
 
@@ -241,4 +240,4 @@ This library is part of the [hyperfrontend](https://github.com/AndrewRedican/hyp
 
 ## License
 
-MIT
+[MIT](https://github.com/AndrewRedican/hyperfrontend/blob/main/LICENSE.md)

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.cjs.js

@@ -0,0 +1,7 @@
+'use strict';
+
+const _Array = globalThis.Array;
+const isArray = _Array.isArray;
+const from = _Array.from;
+exports.from = from;
+exports.isArray = isArray;

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.esm.js

@@ -0,0 +1,5 @@
+const _Array = globalThis.Array;
+const isArray = _Array.isArray;
+const from = _Array.from;
+
+export { from, isArray };

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/console/index.cjs.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const _console = globalThis.console;
+const log = _console.log.bind(_console);
+const warn = _console.warn.bind(_console);
+const error = _console.error.bind(_console);
+const info = _console.info.bind(_console);
+const debug = _console.debug.bind(_console);
+exports.debug = debug;
+exports.error = error;
+exports.info = info;
+exports.log = log;
+exports.warn = warn;

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/console/index.esm.js

@@ -0,0 +1,8 @@
+const _console = globalThis.console;
+const log = _console.log.bind(_console);
+const warn = _console.warn.bind(_console);
+const error = _console.error.bind(_console);
+const info = _console.info.bind(_console);
+const debug = _console.debug.bind(_console);
+
+export { debug, error, info, log, warn };

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/date/index.cjs.js

@@ -0,0 +1,10 @@
+'use strict';
+
+const _Date = globalThis.Date;
+const _Reflect = globalThis.Reflect;
+function createDate(...args) {
+    return _Reflect.construct(_Date, args);
+}
+const dateNow = _Date.now;
+exports.createDate = createDate;
+exports.dateNow = dateNow;

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/date/index.esm.js

@@ -0,0 +1,8 @@
+const _Date = globalThis.Date;
+const _Reflect = globalThis.Reflect;
+function createDate(...args) {
+    return _Reflect.construct(_Date, args);
+}
+const dateNow = _Date.now;
+
+export { createDate, dateNow };

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.cjs.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const _Error = globalThis.Error;
+const _Reflect = globalThis.Reflect;
+const createError = (message, options) => _Reflect.construct(_Error, [message, options]);
+exports.createError = createError;

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.esm.js

@@ -0,0 +1,5 @@
+const _Error = globalThis.Error;
+const _Reflect = globalThis.Reflect;
+const createError = (message, options) => _Reflect.construct(_Error, [message, options]);
+
+export { createError };

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.cjs.js

@@ -0,0 +1,7 @@
+'use strict';
+
+const _JSON = globalThis.JSON;
+const parse = _JSON.parse;
+const stringify = _JSON.stringify;
+exports.parse = parse;
+exports.stringify = stringify;

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.esm.js

@@ -0,0 +1,5 @@
+const _JSON = globalThis.JSON;
+const parse = _JSON.parse;
+const stringify = _JSON.stringify;
+
+export { parse, stringify };

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/map/index.cjs.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const _Map = globalThis.Map;
+const _Reflect = globalThis.Reflect;
+const createMap = (iterable) => _Reflect.construct(_Map, iterable ? [iterable] : []);
+exports.createMap = createMap;

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/map/index.esm.js

@@ -0,0 +1,5 @@
+const _Map = globalThis.Map;
+const _Reflect = globalThis.Reflect;
+const createMap = (iterable) => _Reflect.construct(_Map, iterable ? [iterable] : []);
+
+export { createMap };

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/math/index.cjs.js

@@ -0,0 +1,9 @@
+'use strict';
+
+const _Math = globalThis.Math;
+const round = _Math.round;
+const max = _Math.max;
+const min = _Math.min;
+exports.max = max;
+exports.min = min;
+exports.round = round;

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/math/index.esm.js

@@ -0,0 +1,6 @@
+const _Math = globalThis.Math;
+const round = _Math.round;
+const max = _Math.max;
+const min = _Math.min;
+
+export { max, min, round };

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/number/index.cjs.js

@@ -0,0 +1,7 @@
+'use strict';
+const _parseInt = globalThis.parseInt;
+const _parseFloat = globalThis.parseFloat;
+const parseInt = _parseInt;
+const parseFloat = _parseFloat;
+exports.parseFloat = parseFloat;
+exports.parseInt = parseInt;

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/number/index.esm.js

@@ -0,0 +1,7 @@
+
+const _parseInt = globalThis.parseInt;
+const _parseFloat = globalThis.parseFloat;
+const parseInt = _parseInt;
+const parseFloat = _parseFloat;
+
+export { parseFloat, parseInt };

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.cjs.js

@@ -0,0 +1,15 @@
+'use strict';
+
+const _Object = globalThis.Object;
+const freeze = _Object.freeze;
+const keys = _Object.keys;
+const entries = _Object.entries;
+const values = _Object.values;
+const defineProperty = _Object.defineProperty;
+const defineProperties = _Object.defineProperties;
+exports.defineProperties = defineProperties;
+exports.defineProperty = defineProperty;
+exports.entries = entries;
+exports.freeze = freeze;
+exports.keys = keys;
+exports.values = values;

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.esm.js

@@ -0,0 +1,9 @@
+const _Object = globalThis.Object;
+const freeze = _Object.freeze;
+const keys = _Object.keys;
+const entries = _Object.entries;
+const values = _Object.values;
+const defineProperty = _Object.defineProperty;
+const defineProperties = _Object.defineProperties;
+
+export { defineProperties, defineProperty, entries, freeze, keys, values };

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/set/index.cjs.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const _Set = globalThis.Set;
+const _Reflect = globalThis.Reflect;
+const createSet = (iterable) => _Reflect.construct(_Set, iterable ? [iterable] : []);
+exports.createSet = createSet;

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/set/index.esm.js

@@ -0,0 +1,5 @@
+const _Set = globalThis.Set;
+const _Reflect = globalThis.Reflect;
+const createSet = (iterable) => _Reflect.construct(_Set, iterable ? [iterable] : []);
+
+export { createSet };

package/_dependencies/@hyperfrontend/logging/index.cjs.js

@@ -0,0 +1,191 @@
+'use strict';
+
+const { createError } = require('../immutable-api-utils/built-in-copy/error/index.cjs.js');
+const { freeze } = require('../immutable-api-utils/built-in-copy/object/index.cjs.js');
+const { isArray } = require('../immutable-api-utils/built-in-copy/array/index.cjs.js');
+require('../immutable-api-utils/built-in-copy/map/index.cjs.js');
+const { dateNow } = require('../immutable-api-utils/built-in-copy/date/index.cjs.js');
+require('../immutable-api-utils/built-in-copy/math/index.cjs.js');
+require('../immutable-api-utils/built-in-copy/set/index.cjs.js');
+const { debug: debug$1, error: error$1, info: info$1, log: log$1, warn: warn$1 } = require('../immutable-api-utils/built-in-copy/console/index.cjs.js');
+
+const logLevels = ['none', 'error', 'warn', 'log', 'info', 'debug'];
+const priority = {
+    error: 4,
+    warn: 3,
+    log: 2,
+    info: 1,
+    debug: 0,
+};
+function isValidLogLevel(level) {
+    return logLevels.includes(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,
+    });
+}
+
+const registeredClasses = [];
+
+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;
+};
+
+function createConditionalExecutionFunction(func, conditionFunc) {
+    return function (...args) {
+        if (conditionFunc()) {
+            return func(...args);
+        }
+    };
+}
+
+function createErrorIgnoringFunction(func) {
+    return function (...args) {
+        try {
+            func(...args);
+        }
+        catch {
+        }
+    };
+}
+
+const noop = (...args) => {
+};
+
+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);
+    };
+    const core = {
+        error: wrapLogFn(error, 'error'),
+        warn: wrapLogFn(warn, 'warn'),
+        log: wrapLogFn(log, 'log'),
+        info: wrapLogFn(info, 'info'),
+        debug: wrapLogFn(debug, 'debug'),
+        setLogLevel,
+        getLogLevel,
+    };
+    return createPrefixedLogger(core, '');
+}
+function createPrefixedLogger(core, fullPrefix) {
+    const tag = fullPrefix ? `[${fullPrefix}]` : '';
+    const prefixed = (fn) => {
+        if (!tag)
+            return fn;
+        return (...data) => fn(tag, ...data);
+    };
+    const instance = freeze({
+        error: prefixed(core.error),
+        warn: prefixed(core.warn),
+        log: prefixed(core.log),
+        info: prefixed(core.info),
+        debug: prefixed(core.debug),
+        setLogLevel: core.setLogLevel,
+        getLogLevel: core.getLogLevel,
+        channel: (childPrefix) => createPrefixedLogger(core, fullPrefix ? `${fullPrefix}:${childPrefix}` : childPrefix),
+        timed(label, fn) {
+            return runTimed(instance, label, fn);
+        },
+        timedAsync(label, fn) {
+            return runTimedAsync(instance, label, fn);
+        },
+    });
+    return instance;
+}
+function runTimed(logger, label, fn) {
+    const start = dateNow();
+    try {
+        const result = fn();
+        const elapsed = dateNow() - start;
+        logger.debug(`${label} completed in ${elapsed}ms`);
+        return result;
+    }
+    catch (error) {
+        const elapsed = dateNow() - start;
+        logger.error(`${label} failed after ${elapsed}ms: ${describeError(error)}`);
+        throw error;
+    }
+}
+async function runTimedAsync(logger, label, fn) {
+    const start = dateNow();
+    try {
+        const result = await fn();
+        const elapsed = dateNow() - start;
+        logger.debug(`${label} completed in ${elapsed}ms`);
+        return result;
+    }
+    catch (error) {
+        const elapsed = dateNow() - start;
+        logger.error(`${label} failed after ${elapsed}ms: ${describeError(error)}`);
+        if (error instanceof Error && error.stack) {
+            logger.debug(`Stack trace:\n${error.stack}`);
+        }
+        throw error;
+    }
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function notValidLogFn(fn) {
+    return getType(fn) !== 'function' && fn !== noop;
+}
+function notFnMsg(label) {
+    return `Cannot create a logger when ${label} is not a function`;
+}
+
+const logger = createLogger(error$1, warn$1, log$1, info$1, debug$1);
+
+exports.createLogLevelConfig = createLogLevelConfig;
+exports.createLogger = createLogger;
+exports.isValidLogLevel = isValidLogLevel;
+exports.logger = logger;

package/_dependencies/@hyperfrontend/logging/index.d.ts

@@ -0,0 +1,151 @@
+/** Valid log level values in order of verbosity */
+type LogLevel = 'none' | 'error' | 'warn' | 'log' | 'info' | 'debug';
+/**
+ * Encapsulates the current log level state.
+ */
+interface LogLevelState {
+    /** The active log level */
+    level: LogLevel;
+}
+/** Function to update the log level */
+type SetLogLevel = (level: LogLevel) => void;
+/** Function to retrieve the current log level */
+type GetLogLevel = () => LogLevel;
+/** Predicate to determine if a message should be logged */
+type ShouldLog = (level: LogLevel) => boolean;
+/**
+ * Configuration interface for managing log levels.
+ */
+interface LogLevelConfig {
+    /** Updates the log level */
+    setLogLevel: SetLogLevel;
+    /** Retrieves the current log level */
+    getLogLevel: GetLogLevel;
+    /** Checks if a given level should be logged */
+    shouldLog: ShouldLog;
+}
+/**
+ * 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
+ *
+ * @example Validating log levels
+ * ```typescript
+ * isValidLogLevel('error') // => true
+ * isValidLogLevel('verbose') // => false
+ * ```
+ */
+declare function isValidLogLevel(level: LogLevel): boolean;
+/**
+ * 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
+ *
+ * @example Managing log levels with priority checks
+ * ```typescript
+ * const config = createLogLevelConfig('warn')
+ * config.shouldLog('error') // => true (error >= warn)
+ * config.shouldLog('debug') // => false (debug < warn)
+ * config.setLogLevel('debug')
+ * config.shouldLog('debug') // => true
+ * ```
+ */
+declare function createLogLevelConfig(level?: LogLevel): LogLevelConfig;
+
+/** Function signature for standard log output */
+type LogLevelFn = (...data: any[]) => void;
+/** Function signature for warning output */
+type WarnLevelFn = (...data: any[]) => void;
+/** Function signature for error output */
+type ErrorLevelFn = (...data: any[]) => void;
+/** Function signature for info output */
+type InfoLevelFn = (...data: any[]) => void;
+/** Function signature for debug output */
+type DebugLevelFn = (...data: any[]) => void;
+/** Returns a sub-logger that prepends `[prefix]` to every message. */
+type ChannelFn = (prefix: string) => Logger;
+/** Wraps a sync call with timing. Logs completion or failure with elapsed ms. */
+type TimedFn = <T>(label: string, fn: () => T) => T;
+/** Wraps a promise-returning call with timing. Dumps stack trace on error to debug log. */
+type TimedAsyncFn = <T>(label: string, fn: () => Promise<T>) => Promise<T>;
+/** Logger interface with level-specific methods and level control */
+interface Logger {
+    /** Standard log output */
+    log: LogLevelFn;
+    /** Warning-level output */
+    warn: WarnLevelFn;
+    /** Error-level output */
+    error: ErrorLevelFn;
+    /** Info-level output */
+    info: InfoLevelFn;
+    /** Debug-level output */
+    debug: DebugLevelFn;
+    /** Sets the current log level */
+    setLogLevel: SetLogLevel;
+    /** Gets the current log level */
+    getLogLevel: GetLogLevel;
+    /** Returns a sub-logger that prepends `[prefix]` to every message. */
+    channel: ChannelFn;
+    /** Wraps a sync call with timing. Logs completion or failure with elapsed ms. */
+    timed: TimedFn;
+    /** Wraps a promise-returning call with timing. Dumps stack trace on error to debug log. */
+    timedAsync: TimedAsyncFn;
+}
+/** Keys of Logger that represent log functions */
+type LogFnName = Extract<keyof Logger, 'error' | 'warn' | 'log' | 'info' | 'debug'>;
+/** Union type of all log function signatures */
+type LogFunction = Logger[LogFnName];
+/**
+ * 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, level control, channel, and timing helpers
+ * @throws {ErrorLevelFn} When any provided log function is invalid
+ *
+ * @example Creating a logger with log level filtering
+ * ```typescript
+ * const logger = createLogger(console.error, console.warn, console.log)
+ * logger.setLogLevel('warn')
+ * logger.warn('Connection timeout') // logs
+ * logger.info('Request complete')   // suppressed (below 'warn' level)
+ * ```
+ *
+ * @example Channeling and timing
+ * ```typescript
+ * const logger = createLogger(console.error, console.warn, console.log, console.info, console.debug)
+ * logger.setLogLevel('debug')
+ * const build = logger.channel('build')
+ * await build.timedAsync('bundle', async () => bundle())
+ * ```
+ */
+declare function createLogger(error: ErrorLevelFn, warn?: WarnLevelFn, log?: LogLevelFn, info?: InfoLevelFn, debug?: DebugLevelFn): Logger;
+
+/**
+ * Validates whether an object is a properly structured Logger instance.
+ * Checks for the presence and type of all required logger methods.
+ *
+ * @param logger - The object to validate
+ * @returns True if the object is a valid logger, false otherwise
+ *
+ * @example Validating a logger instance
+ * ```typescript
+ * const logger = createLogger(console.error)
+ * isValidLogger(logger) // => true
+ * isValidLogger({}) // => false
+ * ```
+ */
+declare function isValidLogger(logger: unknown): boolean;
+
+declare const logger: Logger;
+
+export { createLogLevelConfig, createLogger, isValidLogLevel, isValidLogger, logger };
+export type { ChannelFn, DebugLevelFn, ErrorLevelFn, GetLogLevel, InfoLevelFn, LogFnName, LogFunction, LogLevel, LogLevelConfig, LogLevelFn, LogLevelState, Logger, SetLogLevel, ShouldLog, TimedAsyncFn, TimedFn, WarnLevelFn };