@hyperfrontend/project-scope 0.2.1 → 0.2.3

package/vfs/index.esm.js

@@ -1,419 +1,19 @@
-import { existsSync, mkdirSync, statSync, lstatSync, readdirSync, readFileSync, readlinkSync, unlinkSync, rmSync, writeFileSync, chmodSync } from 'node:fs';
+import { existsSync, statSync, lstatSync, readdirSync, mkdirSync, unlinkSync, rmSync, writeFileSync, chmodSync, readFileSync, readlinkSync } from 'node:fs';
 import { join, normalize, sep, isAbsolute as isAbsolute$1, relative, resolve, dirname } from 'node:path';
-
-/**
- * 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$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
- */
-const _JSON = globalThis.JSON;
-/**
- * (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) 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
- */
-const _Array = globalThis.Array;
-/**
- * (Safe copy) Determines whether the passed value is an Array.
- */
-const isArray = _Array.isArray;
-/**
- * (Safe copy) Creates an array from an array-like or iterable object.
- */
-const from = _Array.from;
-
-/**
- * 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$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
- */
-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] : []);
-
-/**
- * Safe copies of Math 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/math
- */
-const _Math = globalThis.Math;
-/**
- * (Safe copy) Returns the larger of zero or more numbers.
- */
-const max = _Math.max;
-/**
- * (Safe copy) Returns the smaller of zero or more numbers.
- */
-const min = _Math.min;
-
-/* eslint-disable @typescript-eslint/no-explicit-any */
-/**
- * Creates a wrapper function that only executes the wrapped function if the condition function returns true.
- *
- * @param func - The function to be conditionally executed.
- * @param conditionFunc - A function that returns a boolean, determining if `func` should be executed.
- * @returns A wrapped version of `func` that executes conditionally.
- */
-function createConditionalExecutionFunction(func, conditionFunc) {
-    return function (...args) {
-        if (conditionFunc()) {
-            return func(...args);
-        }
-    };
-}
-
-/* eslint-disable @typescript-eslint/no-explicit-any */
-/**
- * Creates a wrapper function that silently ignores any errors thrown by the wrapped void function.
- * This function is specifically for wrapping functions that do not return a value (void functions).
- * Exceptions are swallowed without any logging or handling.
- *
- * @param func - The void function to be wrapped.
- * @returns A wrapped version of the input function that ignores errors.
- */
-function createErrorIgnoringFunction(func) {
-    return function (...args) {
-        try {
-            func(...args);
-        }
-        catch {
-            // Deliberately swallowing/ignoring the exception
-        }
-    };
-}
-
-/* eslint-disable @typescript-eslint/no-unused-vars */
-/**
- * A no-operation function (noop) that does nothing regardless of the arguments passed.
- * It is designed to be as permissive as possible in its typing without using the `Function` keyword.
- *
- * @param args - Any arguments passed to the function (ignored)
- */
-const noop = (...args) => {
-    // Intentionally does nothing
-};
-
-const logLevels = ['none', 'error', 'warn', 'log', 'info', 'debug'];
-const priority = {
-    error: 4,
-    warn: 3,
-    log: 2,
-    info: 1,
-    debug: 0,
-};
-/**
- * Validates whether a given string is a valid log level.
- *
- * @param level - The log level to validate
- * @returns True if the level is valid, false otherwise
- */
-function isValidLogLevel(level) {
-    return logLevels.includes(level);
-}
-/**
- * Creates a log level configuration manager for controlling logging behavior.
- * Provides methods to get, set, and evaluate log levels based on priority.
- *
- * @param level - The initial log level (defaults to 'error')
- * @returns A configuration object with log level management methods
- * @throws {Error} When the provided level is not a valid log level
- */
-function createLogLevelConfig(level = 'error') {
-    if (!isValidLogLevel(level)) {
-        throw createError('Cannot create log level configuration with a valid default log level');
-    }
-    const state = { level };
-    const getLogLevel = () => state.level;
-    const setLogLevel = (level) => {
-        if (!isValidLogLevel(level)) {
-            throw createError(`Cannot set value '${level}' level. Expected levels are ${logLevels}.`);
-        }
-        state.level = level;
-    };
-    const shouldLog = (level) => {
-        if (state.level === 'none' || level === 'none' || !isValidLogLevel(level)) {
-            return false;
-        }
-        return priority[level] >= priority[state.level];
-    };
-    return freeze({
-        getLogLevel,
-        setLogLevel,
-        shouldLog,
-    });
-}
-
-/**
- * Creates a logger instance with configurable log level filtering.
- * Each log function is wrapped to respect the current log level setting.
- *
- * @param error - Function to handle error-level logs (required)
- * @param warn - Function to handle warning-level logs (optional, defaults to noop)
- * @param log - Function to handle standard logs (optional, defaults to noop)
- * @param info - Function to handle info-level logs (optional, defaults to noop)
- * @param debug - Function to handle debug-level logs (optional, defaults to noop)
- * @returns A frozen logger object with log methods and level control
- * @throws {ErrorLevelFn} When any provided log function is invalid
- */
-function createLogger(error, warn = noop, log = noop, info = noop, debug = noop) {
-    if (notValidLogFn(error)) {
-        throw createError(notFnMsg('error'));
-    }
-    if (notValidLogFn(warn)) {
-        throw createError(notFnMsg('warn'));
-    }
-    if (notValidLogFn(log)) {
-        throw createError(notFnMsg('log'));
-    }
-    if (notValidLogFn(info)) {
-        throw createError(notFnMsg('info'));
-    }
-    if (notValidLogFn(debug)) {
-        throw createError(notFnMsg('debug'));
-    }
-    const { setLogLevel, getLogLevel, shouldLog } = createLogLevelConfig();
-    const wrapLogFn = (fn, level) => {
-        if (fn === noop)
-            return fn;
-        const condition = () => shouldLog(level);
-        return createConditionalExecutionFunction(createErrorIgnoringFunction(fn), condition);
-    };
-    return freeze({
-        error: wrapLogFn(error, 'error'),
-        warn: wrapLogFn(warn, 'warn'),
-        log: wrapLogFn(log, 'log'),
-        info: wrapLogFn(info, 'info'),
-        debug: wrapLogFn(debug, 'debug'),
-        setLogLevel,
-        getLogLevel,
-    });
-}
-/**
- * Validates whether a given value is a valid log function.
- *
- * @param fn - The value to validate
- * @returns True if the value is not a function (invalid), false if it is valid
- */
-function notValidLogFn(fn) {
-    return getType(fn) !== 'function' && fn !== noop;
-}
-/**
- * Generates an error message for invalid log function parameters.
- *
- * @param label - The name of the log function that failed validation
- * @returns A formatted error message string
- */
-function notFnMsg(label) {
-    return `Cannot create a logger when ${label} is not a function`;
-}
-
-createLogger(error, warn, log, info, debug);
+import { createError } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.esm.js';
+import { isArray, from } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.esm.js';
+import { error, warn, log, info, debug } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/console/index.esm.js';
+import { stringify } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.esm.js';
+import { freeze, entries, keys, defineProperties } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.esm.js';
+import { createSet } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/set/index.esm.js';
+import { createLogger } from '../_dependencies/@hyperfrontend/logging/index.esm.js';
+import { max, min } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/math/index.esm.js';
+import { createMap } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/map/index.esm.js';
+import { isFile, isDirectory, exists } from '../_shared/core/fs/stat/index.esm.js';
+import { normalizePath, removeTrailingSlash } from '../_shared/core/path/normalize/index.esm.js';
+import { resolvePath, relativePath, joinPath, isAbsolute } from '../_shared/core/path/resolve/index.esm.js';
+import { getDirname } from '../_shared/core/path/segments/index.esm.js';
+import { Mode } from '../_shared/vfs/types/index.esm.js';
 
 /**
  * Global log level registry.
@@ -453,6 +53,13 @@ function isSensitiveKey(key) {
  *
  * @param obj - Object to sanitize
  * @returns New object with sensitive values redacted
+ *
+ * @example Sanitizing sensitive data
+ * ```typescript
+ * const config = { apiKey: 'secret123', endpoint: 'https://api.example.com' }
+ * const safe = sanitize(config)
+ * // => { apiKey: '[REDACTED]', endpoint: 'https://api.example.com' }
+ * ```
  */
 function sanitize(obj) {
     if (obj === null || obj === undefined) {
@@ -503,7 +110,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')
@@ -540,7 +147,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'
  *
@@ -558,6 +165,15 @@ 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);
@@ -568,77 +184,6 @@ function createFileSystemError(message, code, context) {
     return error;
 }
 
-const fsWriteLogger = createScopedLogger('project-scope:fs:write');
-/**
- * Ensure directory exists, create recursively if not.
- *
- * @param dirPath - Directory path to ensure exists
- */
-function ensureDir(dirPath) {
-    if (!existsSync(dirPath)) {
-        fsWriteLogger.debug('Creating directory recursively', { path: dirPath });
-        mkdirSync(dirPath, { recursive: true });
-    }
-}
-
-/**
- * Get file stats with error handling.
- *
- * @param filePath - Path to file
- * @param followSymlinks - Whether to follow symlinks (default: true)
- * @returns File stats or null if path doesn't exist
- */
-function getFileStat(filePath, followSymlinks = true) {
-    if (!existsSync(filePath)) {
-        return null;
-    }
-    try {
-        const stat = followSymlinks ? statSync(filePath) : lstatSync(filePath);
-        return {
-            isFile: stat.isFile(),
-            isDirectory: stat.isDirectory(),
-            isSymlink: stat.isSymbolicLink(),
-            size: stat.size,
-            created: stat.birthtime,
-            modified: stat.mtime,
-            accessed: stat.atime,
-            mode: stat.mode,
-        };
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Check if path is a file.
- *
- * @param filePath - Path to check
- * @returns True if path is a file
- */
-function isFile(filePath) {
-    const stats = getFileStat(filePath);
-    return stats?.isFile ?? false;
-}
-/**
- * Check if path is a directory.
- *
- * @param dirPath - Path to check
- * @returns True if path is a directory
- */
-function isDirectory(dirPath) {
-    const stats = getFileStat(dirPath);
-    return stats?.isDirectory ?? false;
-}
-/**
- * Check if path exists.
- *
- * @param filePath - Path to check
- * @returns True if path exists
- */
-function exists(filePath) {
-    return existsSync(filePath);
-}
-
 const fsDirLogger = createScopedLogger('project-scope:fs:dir');
 /**
  * List immediate contents of a directory.
@@ -647,7 +192,7 @@ const fsDirLogger = createScopedLogger('project-scope:fs:dir');
  * @returns Array of entries with metadata for each file/directory
  * @throws {Error} If directory doesn't exist or isn't a directory
  *
- * @example
+ * @example Listing directory contents
  * ```typescript
  * import { readDirectory } from '@hyperfrontend/project-scope'
  *
@@ -688,246 +233,579 @@ function readDirectory(dirPath) {
     }
 }
 
+createScopedLogger('project-scope:fs:traversal');
+
+const fsWriteLogger = createScopedLogger('project-scope:fs:write');
 /**
- * Normalize path separators to forward slashes.
+ * Ensure directory exists, create recursively if not.
  *
- * @param filePath - Path to normalize
- * @returns Normalized path with forward slashes
- */
-function normalizePath(filePath) {
-    if (!filePath)
-        return '';
-    const normalized = normalize(filePath);
-    return sep === '\\' ? normalized.replace(/\\/g, '/') : normalized;
-}
-/**
- * Strip any trailing forward or back slashes from a path.
+ * @param dirPath - Directory path to ensure exists
  *
- * @param filePath - Path that may have trailing slashes
- * @returns Path with trailing slashes removed
+ * @example Ensuring directory exists
+ * ```typescript
+ * ensureDir('./output/reports')
+ * // Directory now exists (created if missing)
+ * ```
  */
-function removeTrailingSlash(filePath) {
-    let i = filePath.length;
-    while (i > 0 && (filePath[i - 1] === '/' || filePath[i - 1] === '\\')) {
-        i--;
+function ensureDir(dirPath) {
+    if (!existsSync(dirPath)) {
+        fsWriteLogger.debug('Creating directory recursively', { path: dirPath });
+        mkdirSync(dirPath, { recursive: true });
     }
-    return filePath.slice(0, i);
 }
 
+const vfsLogger = createScopedLogger('project-scope:vfs');
 /**
- * Resolve path segments to an absolute path.
+ * Commit buffered changes to disk.
  *
- * @param segments - Path segments to resolve
- * @returns Resolved absolute path with normalized separators
- */
-function resolvePath(...segments) {
-    return normalizePath(resolve(...segments));
-}
-/**
- * Compute the normalized path from source directory to target.
+ * @param tree - Virtual file system tree with pending modifications
+ * @param options - Configuration for dry-run and verbosity
+ * @returns Result of the commit operation
  *
- * @param from - Source path (base directory)
- * @param to - Target path to reach
- * @returns Relative path from source to target with forward slashes
- */
-function relativePath(from, to) {
-    return normalizePath(relative(from, to));
-}
-/**
- * Join path segments.
+ * @example Committing changes to disk
+ * ```typescript
+ * import { createTree, commitChanges } from '@hyperfrontend/project-scope'
  *
- * @param segments - Path segments to join
- * @returns Joined path with normalized separators
- */
-function joinPath(...segments) {
-    return normalizePath(join(...segments));
-}
-/**
- * Check if path is absolute.
+ * const tree = createTree('./my-project')
+ * tree.write('src/new-file.ts', 'export const hello = "world"')
  *
- * @param filePath - Path to check
- * @returns True if path is absolute
- */
-function isAbsolute(filePath) {
-    return isAbsolute$1(filePath);
-}
-
-/**
- * Get directory name of path.
+ * // Preview changes without writing
+ * const preview = commitChanges(tree, { dryRun: true })
+ * console.log('Would create:', preview.created, 'files')
  *
- * @param filePath - Path to extract directory from
- * @returns Directory name
+ * // Actually commit changes
+ * const result = commitChanges(tree)
+ * console.log('Created:', result.created, 'Updated:', result.updated)
+ * ```
  */
-function getDirname(filePath) {
-    return normalizePath(dirname(filePath));
+function commitChanges(tree, options) {
+    const changes = tree.listChanges();
+    const appliedChanges = [];
+    if (options?.verbose) {
+        vfsLogger.setLogLevel('debug');
+    }
+    vfsLogger.debug('Committing changes', { changeCount: changes.length, dryRun: options?.dryRun });
+    const result = {
+        created: 0,
+        updated: 0,
+        deleted: 0,
+        changes: [],
+        dryRun: options?.dryRun ?? false,
+    };
+    if (options?.dryRun) {
+        for (const change of changes) {
+            switch (change.type) {
+                case 'CREATE':
+                    result.created++;
+                    break;
+                case 'UPDATE':
+                    result.updated++;
+                    break;
+                case 'DELETE':
+                    result.deleted++;
+                    break;
+            }
+        }
+        result.changes = changes;
+        return result;
+    }
+    const sortedChanges = [...changes].sort((a, b) => {
+        const order = { DELETE: 0, CREATE: 1, UPDATE: 2 };
+        return order[a.type] - order[b.type];
+    });
+    for (const change of sortedChanges) {
+        const absPath = join(tree.root, change.path);
+        try {
+            switch (change.type) {
+                case 'CREATE':
+                case 'UPDATE':
+                    /* istanbul ignore if -- content is always defined for CREATE/UPDATE from tree.write() */
+                    if (change.content !== undefined) {
+                        const dir = dirname(absPath);
+                        ensureDir(dir);
+                        writeFileSync(absPath, change.content);
+                        if (change.mode !== undefined) {
+                            chmodSync(absPath, change.mode);
+                        }
+                        if (change.type === 'CREATE') {
+                            result.created++;
+                        }
+                        else {
+                            result.updated++;
+                        }
+                    }
+                    break;
+                case 'DELETE':
+                    if (exists(absPath)) {
+                        try {
+                            unlinkSync(absPath);
+                        }
+                        catch {
+                            rmSync(absPath, { recursive: true });
+                        }
+                    }
+                    result.deleted++;
+                    break;
+            }
+            appliedChanges.push(change);
+            if (options?.verbose) {
+                const prefix = change.type === 'CREATE' ? '+' : change.type === 'DELETE' ? '-' : '~';
+                vfsLogger.info(`${prefix} ${change.path}`);
+            }
+        }
+        catch (error) {
+            vfsLogger.error('Commit failed', { path: change.path, type: change.type });
+            const message = error instanceof Error
+                ? `Failed to ${change.type.toLowerCase()} ${change.path}: ${error.message}`
+                : `Failed to ${change.type.toLowerCase()} ${change.path}`;
+            throw createError(message);
+        }
+    }
+    result.changes = appliedChanges;
+    tree.clearChanges();
+    return result;
 }
-
-createScopedLogger('project-scope:fs:traversal');
-
 /**
- * Write mode for file operations.
+ * Discard all pending changes.
+ *
+ * @param tree - Virtual file system tree
+ *
+ * @example Rolling back pending changes
+ * ```typescript
+ * import { createTree, rollbackChanges } from '@hyperfrontend/project-scope'
+ *
+ * const tree = createTree('/workspace')
+ * tree.write('new-file.ts', 'content')
+ * // Decide to abort - discard all pending changes
+ * rollbackChanges(tree)
+ * ```
  */
-const Mode = freeze({
-    /** Overwrite existing files */
-    Overwrite: 'overwrite',
-    /** Fail if file exists */
-    ExclusiveCreate: 'exclusive',
-    /** Skip if file exists */
-    SkipIfExists: 'skip',
-});
+function rollbackChanges(tree) {
+    tree.clearChanges();
+}
 
-const fsTreeLogger = createScopedLogger('project-scope:vfs:tree');
+const diffLogger = createScopedLogger('project-scope:vfs:diff');
+const DEFAULT_CONTEXT_LINES = 3;
 /**
- * Create a file system-backed tree implementation.
- *
- * Supports transactional modifications - all changes are buffered
- * in memory and can be committed atomically or rolled back.
+ * Compute the Longest Common Subsequence (LCS) table for two arrays of lines.
+ * Uses dynamic programming for O(n*m) time complexity.
  *
- * @param root - Absolute path to the workspace root directory
- * @param options - Configuration for verbose logging
- * @returns A Tree instance
+ * @param oldLines - Lines from the original file version
+ * @param newLines - Lines from the new file version
+ * @returns Two-dimensional LCS table for backtracking
  */
-function createFsTree(root, options) {
-    const _root = removeTrailingSlash(normalizePath(root));
-    const _changes = createMap();
-    const _isVerbose = options?.verbose ?? false;
-    const _followSymlinks = options?.followSymlinks ?? true;
-    fsTreeLogger.debug('Creating VFS tree', { root: _root, verbose: _isVerbose, followSymlinks: _followSymlinks });
-    /**
-     * Normalize path to be relative from root.
-     *
-     * @param filePath - Path to normalize
-     * @returns Normalized relative path
-     * @throws {Error} if path traverses outside the tree root
-     */
-    function normalizeFilePath(filePath) {
-        const normalized = isAbsolute(filePath) ? relativePath(_root, filePath) : normalizePath(filePath);
-        const absoluteResolved = resolvePath(_root, normalized);
-        if (!absoluteResolved.startsWith(_root + '/') && absoluteResolved !== _root) {
-            throw createError(`Path escapes tree root: ${filePath}`);
+function computeLcsTable(oldLines, newLines) {
+    const m = oldLines.length;
+    const n = newLines.length;
+    const table = from({ length: m + 1 }, () => Array(n + 1).fill(0));
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            if (oldLines[i - 1] === newLines[j - 1]) {
+                table[i][j] = table[i - 1][j - 1] + 1;
+            }
+            else {
+                table[i][j] = max(table[i - 1][j], table[i][j - 1]);
+            }
         }
-        return normalized;
-    }
-    /**
-     * Get absolute path on disk.
-     *
-     * @param filePath - Relative path from root
-     * @returns Absolute path on disk
-     */
-    function absolutePath(filePath) {
-        return joinPath(_root, normalizeFilePath(filePath));
     }
-    /**
-     * Check if a normalized path is a symbolic link.
-     *
-     * @param normalPath - Already normalized path
-     * @returns True if path is a symlink
-     */
-    function isSymlinkNormalizedPath(normalPath) {
-        const absPath = absolutePath(normalPath);
-        try {
-            const stats = lstatSync(absPath);
-            return stats.isSymbolicLink();
+    return table;
+}
+/**
+ * Backtrack through LCS table to produce diff operations.
+ *
+ * @param table - Two-dimensional LCS table from computeLcsTable
+ * @param oldLines - Lines from the original file version
+ * @param newLines - Lines from the new file version
+ * @returns Array of diff operations (unfiltered, includes all lines)
+ */
+function backtrackLcs(table, oldLines, newLines) {
+    const result = [];
+    let i = oldLines.length;
+    let j = newLines.length;
+    while (i > 0 || j > 0) {
+        if (i > 0 && j > 0 && oldLines[i - 1] === newLines[j - 1]) {
+            result.unshift({ type: 'same', oldIdx: i - 1, newIdx: j - 1, content: oldLines[i - 1] });
+            i--;
+            j--;
         }
-        catch {
-            return false;
+        else if (j > 0 && (i === 0 || table[i][j - 1] >= table[i - 1][j])) {
+            result.unshift({ type: 'add', oldIdx: i - 1, newIdx: j - 1, content: newLines[j - 1] });
+            j--;
         }
-    }
-    /**
-     * Validate that a symlink target stays within tree bounds.
-     *
-     * @param normalPath - Already normalized path to symlink
-     * @throws {Error} If symlink target escapes tree root or followSymlinks is disabled
-     */
-    function validateSymlink(normalPath) {
-        const absPath = absolutePath(normalPath);
-        if (!isSymlinkNormalizedPath(normalPath)) {
-            return;
+        else {
+            result.unshift({ type: 'remove', oldIdx: i - 1, newIdx: -1, content: oldLines[i - 1] });
+            i--;
         }
-        if (!_followSymlinks) {
-            throw createError(`Cannot access symlink when followSymlinks is disabled: ${normalPath}`);
+    }
+    return result;
+}
+/**
+ * Convert raw diff operations to DiffLine array with context filtering.
+ *
+ * @param operations - Raw diff operations
+ * @param contextLines - Number of context lines to include
+ * @returns Filtered DiffLine array
+ */
+function operationsToDiffLines(operations, contextLines) {
+    const include = new Array(operations.length).fill(false);
+    for (let i = 0; i < operations.length; i++) {
+        if (operations[i].type !== 'same') {
+            for (let j = max(0, i - contextLines); j <= min(operations.length - 1, i + contextLines); j++) {
+                include[j] = true;
+            }
         }
-        try {
-            const target = readlinkSync(absPath);
-            let targetAbsolute;
-            if (isAbsolute(target)) {
-                targetAbsolute = target;
+    }
+    const lines = [];
+    let oldLineNum = 1;
+    let newLineNum = 1;
+    for (let i = 0; i < operations.length; i++) {
+        const op = operations[i];
+        if (include[i]) {
+            if (op.type === 'same') {
+                lines.push({ type: 'context', line: oldLineNum, content: op.content });
+                oldLineNum++;
+                newLineNum++;
             }
-            else {
-                const symlinkDir = getDirname(absPath);
-                targetAbsolute = resolvePath(symlinkDir, target);
+            else if (op.type === 'remove') {
+                lines.push({ type: 'remove', line: oldLineNum, content: op.content });
+                oldLineNum++;
             }
-            const normalizedTarget = normalizePath(targetAbsolute);
-            if (!normalizedTarget.startsWith(_root + '/') && normalizedTarget !== _root) {
-                throw createError(`Symlink target escapes tree root: ${normalPath} -> ${target}`);
+            else {
+                lines.push({ type: 'add', line: newLineNum, content: op.content });
+                newLineNum++;
             }
         }
-        catch (error) {
-            /* istanbul ignore else -- other errors are rare edge cases (e.g., permission denied) */
-            if (error instanceof Error && error.message.includes('Symlink target escapes')) {
-                throw error;
-            }
-            if (error instanceof Error && error.message.includes('followSymlinks is disabled')) {
-                throw error;
+        else {
+            if (op.type === 'same') {
+                oldLineNum++;
+                newLineNum++;
             }
-            throw createError(`Failed to validate symlink: ${normalPath}`);
+            else if (op.type === 'remove') {
+                /* istanbul ignore next -- unreachable: remove operations always have include=true */
+                oldLineNum++;
+            }
+            else {
+                /* istanbul ignore next -- unreachable: add operations always have include=true */
+                newLineNum++;
+            }
+        }
+    }
+    return lines;
+}
+/**
+ * Split buffer content into lines.
+ *
+ * @param content - File content as Buffer, or undefined for empty
+ * @returns Array of string lines from the buffer
+ */
+function bufferToLines(content) {
+    if (!content)
+        return [];
+    const text = content.toString('utf-8');
+    return text.split('\n');
+}
+/**
+ * Generate a diff for a single file change.
+ *
+ * @example Generating a diff for a file change
+ * ```typescript
+ * const change: FileChange = {
+ *   path: 'src/app.ts',
+ *   type: 'UPDATE',
+ *   originalContent: Buffer.from('const x = 1;\n'),
+ *   content: Buffer.from('const x = 2;\n'),
+ * }
+ * const diff = generateDiff(change)
+ * // { path: 'src/app.ts', additions: 1, deletions: 1, lines: [...] }
+ * ```
+ *
+ * @param change - File change to diff
+ * @param options - Configuration for diff generation including context lines
+ * @returns FileDiff object
+ */
+function generateDiff(change, options = {}) {
+    const contextLines = options.contextLines ?? DEFAULT_CONTEXT_LINES;
+    diffLogger.debug('generateDiff', { path: change.path, type: change.type, contextLines });
+    const oldLines = bufferToLines(change.originalContent);
+    const newLines = bufferToLines(change.content);
+    if (change.type === 'CREATE') {
+        const lines = newLines
+            .filter((line) => line !== '' || newLines.indexOf(line) !== newLines.length - 1 || newLines.length === 1)
+            .map((content, idx) => ({
+            type: 'add',
+            line: idx + 1,
+            content,
+        }));
+        const filteredLines = lines.filter((l, i) => !(i === lines.length - 1 && l.content === '' && lines.length > 1));
+        return {
+            path: change.path,
+            lines: filteredLines,
+            additions: filteredLines.length,
+            deletions: 0,
+        };
+    }
+    if (change.type === 'DELETE') {
+        const lines = oldLines.map((content, idx) => ({
+            type: 'remove',
+            line: idx + 1,
+            content,
+        }));
+        const filteredLines = lines.filter((l, i) => !(i === lines.length - 1 && l.content === '' && lines.length > 1));
+        return {
+            path: change.path,
+            lines: filteredLines,
+            additions: 0,
+            deletions: filteredLines.length,
+        };
+    }
+    const table = computeLcsTable(oldLines, newLines);
+    const operations = backtrackLcs(table, oldLines, newLines);
+    const lines = operationsToDiffLines(operations, contextLines);
+    const additions = lines.filter((l) => l.type === 'add').length;
+    const deletions = lines.filter((l) => l.type === 'remove').length;
+    return {
+        path: change.path,
+        lines,
+        additions,
+        deletions,
+    };
+}
+/**
+ * Format a FileDiff as a unified diff string.
+ *
+ * @example Formatting a unified diff
+ * ```typescript
+ * const formatted = formatUnifiedDiff(diff)
+ * console.log(formatted)
+ * // --- a/src/app.ts
+ * // +++ b/src/app.ts
+ * // @@ -1,3 +1,3 @@
+ * //  const x = 1;
+ * // -const y = 2;
+ * // +const y = 3;
+ * //  const z = 4;
+ * ```
+ *
+ * @param diff - FileDiff to format
+ * @returns Unified diff string
+ */
+function formatUnifiedDiff(diff) {
+    const lines = [];
+    lines.push(`--- a/${diff.path}`);
+    lines.push(`+++ b/${diff.path}`);
+    if (diff.lines.length === 0) {
+        return lines.join('\n');
+    }
+    const hunks = [];
+    const currentHunk = [];
+    for (const line of diff.lines) {
+        currentHunk.push(line);
+    }
+    if (currentHunk.length > 0) {
+        hunks.push(currentHunk);
+    }
+    for (const hunk of hunks) {
+        const contextAndRemove = hunk.filter((l) => l.type === 'context' || l.type === 'remove');
+        const contextAndAdd = hunk.filter((l) => l.type === 'context' || l.type === 'add');
+        const oldStart = hunk.find((l) => l.type === 'context' || l.type === 'remove')?.line ?? 1;
+        const newStart = hunk.find((l) => l.type === 'context' || l.type === 'add')?.line ?? 1;
+        const oldCount = contextAndRemove.length;
+        const newCount = contextAndAdd.length;
+        lines.push(`@@ -${oldStart},${oldCount} +${newStart},${newCount} @@`);
+        for (const line of hunk) {
+            const prefix = line.type === 'add' ? '+' : line.type === 'remove' ? '-' : ' ';
+            lines.push(`${prefix}${line.content}`);
         }
     }
+    return lines.join('\n');
+}
+/**
+ * Generate diffs for all changes in a tree.
+ *
+ * @example Generating diffs for all changes
+ * ```typescript
+ * const tree = createTree('/workspace')
+ * tree.write('new.txt', 'hello')
+ * tree.delete('old.txt')
+ *
+ * const diffs = generateAllDiffs(tree)
+ * for (const diff of diffs) {
+ *   console.log(formatUnifiedDiff(diff))
+ * }
+ * ```
+ *
+ * @param tree - Tree to generate diffs for
+ * @param options - Diff options
+ * @returns Array of FileDiff objects
+ */
+function generateAllDiffs(tree, options = {}) {
+    const changes = tree.listChanges();
+    diffLogger.debug('generateAllDiffs', { changeCount: changes.length });
+    return changes.map((change) => generateDiff(change, options));
+}
+
+const fsTreeLogger = createScopedLogger('project-scope:vfs:tree');
+/**
+ * Create a file system-backed tree implementation.
+ *
+ * Supports transactional modifications - all changes are buffered
+ * in memory and can be committed atomically or rolled back.
+ *
+ * @param root - Absolute path to the workspace root directory
+ * @param options - Configuration for verbose logging
+ * @returns A Tree instance
+ *
+ * @example Creating and using a file system tree
+ * ```typescript
+ * import { createFsTree, commitChanges } from '@hyperfrontend/project-scope'
+ *
+ * const tree = createFsTree('/workspace')
+ * tree.write('src/new-file.ts', 'export const value = 42')
+ * tree.delete('old-file.ts')
+ * commitChanges(tree) // Atomically apply all changes to disk
+ * ```
+ */
+function createFsTree(root, options) {
+    const _root = removeTrailingSlash(normalizePath(root));
+    const _changes = createMap();
+    const _isVerbose = options?.verbose ?? false;
+    const _followSymlinks = options?.followSymlinks ?? true;
+    fsTreeLogger.debug('Creating VFS tree', { root: _root, verbose: _isVerbose, followSymlinks: _followSymlinks });
     /**
-     * Check if path exists on disk (not considering buffered changes).
+     * Normalize path to be relative from root.
      *
-     * @param normalPath - Normalized path to check
-     * @returns True if exists on disk
+     * @param filePath - Path to normalize
+     * @returns Normalized relative path
+     * @throws {Error} if path traverses outside the tree root
      */
-    function existsOnDisk(normalPath) {
-        const absPath = absolutePath(normalPath);
-        return exists(absPath);
+    function normalizeFilePath(filePath) {
+        const normalized = isAbsolute(filePath) ? relativePath(_root, filePath) : normalizePath(filePath);
+        const absoluteResolved = resolvePath(_root, normalized);
+        if (!absoluteResolved.startsWith(_root + '/') && absoluteResolved !== _root) {
+            throw createError(`Path escapes tree root: ${filePath}`);
+        }
+        return normalized;
     }
     /**
-     * Read from disk (not considering buffered changes).
+     * Get absolute path on disk.
      *
-     * @param normalPath - Normalized path to read
-     * @returns File content or null
+     * @param filePath - Relative path from root
+     * @returns Absolute path on disk
      */
-    function readFromDisk(normalPath) {
-        validateSymlink(normalPath);
+    function absolutePath(filePath) {
+        return joinPath(_root, normalizeFilePath(filePath));
+    }
+    /**
+     * Check if a normalized path is a symbolic link.
+     *
+     * @param normalPath - Already normalized path
+     * @returns True if path is a symlink
+     */
+    function isSymlinkNormalizedPath(normalPath) {
         const absPath = absolutePath(normalPath);
-        if (!isFile(absPath)) {
-            return null;
-        }
         try {
-            return readFileSync(absPath);
+            const stats = lstatSync(absPath);
+            return stats.isSymbolicLink();
         }
         catch {
-            return null;
+            return false;
         }
     }
-    const tree = {
-        get root() {
-            return _root;
-        },
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        read(filePath, encoding) {
-            const normalPath = normalizeFilePath(filePath);
-            const change = _changes.get(normalPath);
-            if (change) {
-                if (change.type === 'DELETE') {
-                    return null;
-                }
-                if (change.content !== null) {
-                    return encoding ? change.content.toString(encoding) : change.content;
-                }
-            }
-            validateSymlink(normalPath);
-            const absPath = absolutePath(normalPath);
-            if (!exists(absPath)) {
-                return null;
-            }
-            if (!isFile(absPath)) {
-                return null;
-            }
-            try {
-                const content = readFileSync(absPath);
+    /**
+     * Validate that a symlink target stays within tree bounds.
+     *
+     * @param normalPath - Already normalized path to symlink
+     * @throws {Error} If symlink target escapes tree root or followSymlinks is disabled
+     */
+    function validateSymlink(normalPath) {
+        const absPath = absolutePath(normalPath);
+        if (!isSymlinkNormalizedPath(normalPath)) {
+            return;
+        }
+        if (!_followSymlinks) {
+            throw createError(`Cannot access symlink when followSymlinks is disabled: ${normalPath}`);
+        }
+        try {
+            const target = readlinkSync(absPath);
+            let targetAbsolute;
+            if (isAbsolute(target)) {
+                targetAbsolute = target;
+            }
+            else {
+                const symlinkDir = getDirname(absPath);
+                targetAbsolute = resolvePath(symlinkDir, target);
+            }
+            const normalizedTarget = normalizePath(targetAbsolute);
+            if (!normalizedTarget.startsWith(_root + '/') && normalizedTarget !== _root) {
+                throw createError(`Symlink target escapes tree root: ${normalPath} -> ${target}`);
+            }
+        }
+        catch (error) {
+            /* istanbul ignore else -- other errors are rare edge cases (e.g., permission denied) */
+            if (error instanceof Error && error.message.includes('Symlink target escapes')) {
+                throw error;
+            }
+            if (error instanceof Error && error.message.includes('followSymlinks is disabled')) {
+                throw error;
+            }
+            throw createError(`Failed to validate symlink: ${normalPath}`);
+        }
+    }
+    /**
+     * Check if path exists on disk (not considering buffered changes).
+     *
+     * @param normalPath - Normalized path to check
+     * @returns True if exists on disk
+     */
+    function existsOnDisk(normalPath) {
+        const absPath = absolutePath(normalPath);
+        return exists(absPath);
+    }
+    /**
+     * Read from disk (not considering buffered changes).
+     *
+     * @param normalPath - Normalized path to read
+     * @returns File content or null
+     */
+    function readFromDisk(normalPath) {
+        validateSymlink(normalPath);
+        const absPath = absolutePath(normalPath);
+        if (!isFile(absPath)) {
+            return null;
+        }
+        try {
+            return readFileSync(absPath);
+        }
+        catch {
+            return null;
+        }
+    }
+    const tree = {
+        get root() {
+            return _root;
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        read(filePath, encoding) {
+            const normalPath = normalizeFilePath(filePath);
+            const change = _changes.get(normalPath);
+            if (change) {
+                if (change.type === 'DELETE') {
+                    return null;
+                }
+                if (change.content !== null) {
+                    return encoding ? change.content.toString(encoding) : change.content;
+                }
+            }
+            validateSymlink(normalPath);
+            const absPath = absolutePath(normalPath);
+            if (!exists(absPath)) {
+                return null;
+            }
+            if (!isFile(absPath)) {
+                return null;
+            }
+            try {
+                const content = readFileSync(absPath);
                 return encoding ? content.toString(encoding) : content;
             }
             catch {
@@ -1034,516 +912,143 @@ function createFsTree(root, options) {
                     for (const entry of entries) {
                         childSet.add(entry.name);
                     }
-                }
-            }
-            catch {
-                // Directory doesn't exist on disk
-            }
-            const prefix = normalPath === '.' || normalPath === '' ? '' : normalPath + '/';
-            for (const [changedPath, change] of _changes) {
-                if (prefix === '') {
-                    const childName = changedPath.split('/')[0];
-                    if (change.type === 'DELETE' && !changedPath.includes('/')) {
-                        childSet.delete(childName);
-                    }
-                    else if (change.type !== 'DELETE') {
-                        childSet.add(childName);
-                    }
-                    continue;
-                }
-                if (!changedPath.startsWith(prefix)) {
-                    continue;
-                }
-                const relativePath = changedPath.slice(prefix.length);
-                const childName = relativePath.split('/')[0];
-                if (change.type === 'DELETE') {
-                    if (!relativePath.includes('/')) {
-                        childSet.delete(childName);
-                    }
-                }
-                else {
-                    childSet.add(childName);
-                }
-            }
-            return from(childSet).sort();
-        },
-        listChanges() {
-            const changes = [];
-            for (const [path, record] of _changes) {
-                changes.push({
-                    path,
-                    type: record.type,
-                    content: record.content ?? undefined,
-                    originalContent: record.originalContent ?? undefined,
-                    mode: record.permissions,
-                });
-            }
-            return changes.sort((a, b) => a.path.localeCompare(b.path));
-        },
-        changePermissions(filePath, mode) {
-            const normalPath = normalizeFilePath(filePath);
-            if (!this.exists(normalPath)) {
-                throw createError(`File not found: ${normalPath}`);
-            }
-            const existingChange = _changes.get(normalPath);
-            if (existingChange) {
-                existingChange.permissions = mode;
-            }
-            else {
-                const content = readFromDisk(normalPath);
-                _changes.set(normalPath, {
-                    type: 'UPDATE',
-                    content,
-                    originalContent: content,
-                    permissions: mode,
-                });
-            }
-        },
-        changeFile(filePath, transform) {
-            const content = this.read(filePath);
-            if (content === null) {
-                throw createError(`File not found: ${filePath}`);
-            }
-            const newContent = transform(content);
-            this.write(filePath, newContent);
-        },
-        clearChanges() {
-            _changes.clear();
-        },
-    };
-    return tree;
-}
-
-const factoryLogger = createScopedLogger('project-scope:vfs:factory');
-/**
- * Create a virtual file system tree.
- *
- * @param root - Root directory path
- * @param options - Tree creation options
- * @returns A new Tree instance
- * @throws {Error} If root doesn't exist or isn't a directory
- *
- * @example
- * ```typescript
- * import { createTree } from '@hyperfrontend/project-scope'
- *
- * const tree = createTree('./my-project')
- *
- * // Read files from tree
- * const content = tree.read('src/index.ts', 'utf-8')
- *
- * // Make changes (buffered in memory)
- * tree.write('src/new-file.ts', 'export const x = 1')
- *
- * // List pending changes
- * console.log(tree.listChanges())
- * ```
- */
-function createTree(root, options) {
-    const normalizedRoot = normalizePath(root);
-    factoryLogger.debug('createTree', { root: normalizedRoot });
-    if (!exists(normalizedRoot)) {
-        factoryLogger.warn('createTree failed: root does not exist', { root: normalizedRoot });
-        throw createError(`Root directory does not exist: ${normalizedRoot}`);
-    }
-    if (!isDirectory(normalizedRoot)) {
-        factoryLogger.warn('createTree failed: root is not a directory', { root: normalizedRoot });
-        throw createError(`Root path is not a directory: ${normalizedRoot}`);
-    }
-    return createFsTree(normalizedRoot, options);
-}
-/**
- * Create a tree from disk.
- *
- * Convenience alias for createTree.
- *
- * @param root - Root directory path
- * @param options - Tree creation options
- * @returns A new Tree instance backed by disk
- */
-function createTreeFromDisk(root, options) {
-    return createTree(root, options);
-}
-
-const vfsLogger = createScopedLogger('project-scope:vfs');
-/**
- * Commit buffered changes to disk.
- *
- * @param tree - Virtual file system tree with pending modifications
- * @param options - Configuration for dry-run and verbosity
- * @returns Result of the commit operation
- *
- * @example
- * ```typescript
- * import { createTree, commitChanges } from '@hyperfrontend/project-scope'
- *
- * const tree = createTree('./my-project')
- * tree.write('src/new-file.ts', 'export const hello = "world"')
- *
- * // Preview changes without writing
- * const preview = commitChanges(tree, { dryRun: true })
- * console.log('Would create:', preview.created, 'files')
- *
- * // Actually commit changes
- * const result = commitChanges(tree)
- * console.log('Created:', result.created, 'Updated:', result.updated)
- * ```
- */
-function commitChanges(tree, options) {
-    const changes = tree.listChanges();
-    const appliedChanges = [];
-    if (options?.verbose) {
-        vfsLogger.setLogLevel('debug');
-    }
-    vfsLogger.debug('Committing changes', { changeCount: changes.length, dryRun: options?.dryRun });
-    const result = {
-        created: 0,
-        updated: 0,
-        deleted: 0,
-        changes: [],
-        dryRun: options?.dryRun ?? false,
-    };
-    if (options?.dryRun) {
-        for (const change of changes) {
-            switch (change.type) {
-                case 'CREATE':
-                    result.created++;
-                    break;
-                case 'UPDATE':
-                    result.updated++;
-                    break;
-                case 'DELETE':
-                    result.deleted++;
-                    break;
-            }
-        }
-        result.changes = changes;
-        return result;
-    }
-    const sortedChanges = [...changes].sort((a, b) => {
-        const order = { DELETE: 0, CREATE: 1, UPDATE: 2 };
-        return order[a.type] - order[b.type];
-    });
-    for (const change of sortedChanges) {
-        const absPath = join(tree.root, change.path);
-        try {
-            switch (change.type) {
-                case 'CREATE':
-                case 'UPDATE':
-                    /* istanbul ignore if -- content is always defined for CREATE/UPDATE from tree.write() */
-                    if (change.content !== undefined) {
-                        const dir = dirname(absPath);
-                        ensureDir(dir);
-                        writeFileSync(absPath, change.content);
-                        if (change.mode !== undefined) {
-                            chmodSync(absPath, change.mode);
-                        }
-                        if (change.type === 'CREATE') {
-                            result.created++;
-                        }
-                        else {
-                            result.updated++;
-                        }
-                    }
-                    break;
-                case 'DELETE':
-                    if (exists(absPath)) {
-                        try {
-                            unlinkSync(absPath);
-                        }
-                        catch {
-                            rmSync(absPath, { recursive: true });
-                        }
-                    }
-                    result.deleted++;
-                    break;
-            }
-            appliedChanges.push(change);
-            if (options?.verbose) {
-                const prefix = change.type === 'CREATE' ? '+' : change.type === 'DELETE' ? '-' : '~';
-                vfsLogger.info(`${prefix} ${change.path}`);
-            }
-        }
-        catch (error) {
-            vfsLogger.error('Commit failed', { path: change.path, type: change.type });
-            const message = error instanceof Error
-                ? `Failed to ${change.type.toLowerCase()} ${change.path}: ${error.message}`
-                : `Failed to ${change.type.toLowerCase()} ${change.path}`;
-            throw createError(message);
-        }
-    }
-    result.changes = appliedChanges;
-    tree.clearChanges();
-    return result;
-}
-/**
- * Discard all pending changes.
- *
- * @param tree - Virtual file system tree
- */
-function rollbackChanges(tree) {
-    tree.clearChanges();
-}
-
-const diffLogger = createScopedLogger('project-scope:vfs:diff');
-const DEFAULT_CONTEXT_LINES = 3;
-/**
- * Compute the Longest Common Subsequence (LCS) table for two arrays of lines.
- * Uses dynamic programming for O(n*m) time complexity.
- *
- * @param oldLines - Lines from the original file version
- * @param newLines - Lines from the new file version
- * @returns Two-dimensional LCS table for backtracking
- */
-function computeLcsTable(oldLines, newLines) {
-    const m = oldLines.length;
-    const n = newLines.length;
-    const table = from({ length: m + 1 }, () => Array(n + 1).fill(0));
-    for (let i = 1; i <= m; i++) {
-        for (let j = 1; j <= n; j++) {
-            if (oldLines[i - 1] === newLines[j - 1]) {
-                table[i][j] = table[i - 1][j - 1] + 1;
-            }
-            else {
-                table[i][j] = max(table[i - 1][j], table[i][j - 1]);
-            }
-        }
-    }
-    return table;
-}
-/**
- * Backtrack through LCS table to produce diff operations.
- *
- * @param table - Two-dimensional LCS table from computeLcsTable
- * @param oldLines - Lines from the original file version
- * @param newLines - Lines from the new file version
- * @returns Array of diff operations (unfiltered, includes all lines)
- */
-function backtrackLcs(table, oldLines, newLines) {
-    const result = [];
-    let i = oldLines.length;
-    let j = newLines.length;
-    while (i > 0 || j > 0) {
-        if (i > 0 && j > 0 && oldLines[i - 1] === newLines[j - 1]) {
-            result.unshift({ type: 'same', oldIdx: i - 1, newIdx: j - 1, content: oldLines[i - 1] });
-            i--;
-            j--;
-        }
-        else if (j > 0 && (i === 0 || table[i][j - 1] >= table[i - 1][j])) {
-            result.unshift({ type: 'add', oldIdx: i - 1, newIdx: j - 1, content: newLines[j - 1] });
-            j--;
-        }
-        else {
-            result.unshift({ type: 'remove', oldIdx: i - 1, newIdx: -1, content: oldLines[i - 1] });
-            i--;
-        }
-    }
-    return result;
-}
-/**
- * Convert raw diff operations to DiffLine array with context filtering.
- *
- * @param operations - Raw diff operations
- * @param contextLines - Number of context lines to include
- * @returns Filtered DiffLine array
- */
-function operationsToDiffLines(operations, contextLines) {
-    const include = new Array(operations.length).fill(false);
-    for (let i = 0; i < operations.length; i++) {
-        if (operations[i].type !== 'same') {
-            for (let j = max(0, i - contextLines); j <= min(operations.length - 1, i + contextLines); j++) {
-                include[j] = true;
-            }
-        }
-    }
-    const lines = [];
-    let oldLineNum = 1;
-    let newLineNum = 1;
-    for (let i = 0; i < operations.length; i++) {
-        const op = operations[i];
-        if (include[i]) {
-            if (op.type === 'same') {
-                lines.push({ type: 'context', line: oldLineNum, content: op.content });
-                oldLineNum++;
-                newLineNum++;
+                }
             }
-            else if (op.type === 'remove') {
-                lines.push({ type: 'remove', line: oldLineNum, content: op.content });
-                oldLineNum++;
+            catch {
+                // Directory doesn't exist on disk
             }
-            else {
-                lines.push({ type: 'add', line: newLineNum, content: op.content });
-                newLineNum++;
+            const prefix = normalPath === '.' || normalPath === '' ? '' : normalPath + '/';
+            for (const [changedPath, change] of _changes) {
+                if (prefix === '') {
+                    const childName = changedPath.split('/')[0];
+                    if (change.type === 'DELETE' && !changedPath.includes('/')) {
+                        childSet.delete(childName);
+                    }
+                    else if (change.type !== 'DELETE') {
+                        childSet.add(childName);
+                    }
+                    continue;
+                }
+                if (!changedPath.startsWith(prefix)) {
+                    continue;
+                }
+                const relativePath = changedPath.slice(prefix.length);
+                const childName = relativePath.split('/')[0];
+                if (change.type === 'DELETE') {
+                    if (!relativePath.includes('/')) {
+                        childSet.delete(childName);
+                    }
+                }
+                else {
+                    childSet.add(childName);
+                }
             }
-        }
-        else {
-            if (op.type === 'same') {
-                oldLineNum++;
-                newLineNum++;
+            return from(childSet).sort();
+        },
+        listChanges() {
+            const changes = [];
+            for (const [path, record] of _changes) {
+                changes.push({
+                    path,
+                    type: record.type,
+                    content: record.content ?? undefined,
+                    originalContent: record.originalContent ?? undefined,
+                    mode: record.permissions,
+                });
             }
-            else if (op.type === 'remove') {
-                /* istanbul ignore next -- unreachable: remove operations always have include=true */
-                oldLineNum++;
+            return changes.sort((a, b) => a.path.localeCompare(b.path));
+        },
+        changePermissions(filePath, mode) {
+            const normalPath = normalizeFilePath(filePath);
+            if (!this.exists(normalPath)) {
+                throw createError(`File not found: ${normalPath}`);
+            }
+            const existingChange = _changes.get(normalPath);
+            if (existingChange) {
+                existingChange.permissions = mode;
             }
             else {
-                /* istanbul ignore next -- unreachable: add operations always have include=true */
-                newLineNum++;
+                const content = readFromDisk(normalPath);
+                _changes.set(normalPath, {
+                    type: 'UPDATE',
+                    content,
+                    originalContent: content,
+                    permissions: mode,
+                });
             }
-        }
-    }
-    return lines;
+        },
+        changeFile(filePath, transform) {
+            const content = this.read(filePath);
+            if (content === null) {
+                throw createError(`File not found: ${filePath}`);
+            }
+            const newContent = transform(content);
+            this.write(filePath, newContent);
+        },
+        clearChanges() {
+            _changes.clear();
+        },
+    };
+    return tree;
 }
+
+const factoryLogger = createScopedLogger('project-scope:vfs:factory');
 /**
- * Split buffer content into lines.
+ * Create a virtual file system tree.
  *
- * @param content - File content as Buffer, or undefined for empty
- * @returns Array of string lines from the buffer
- */
-function bufferToLines(content) {
-    if (!content)
-        return [];
-    const text = content.toString('utf-8');
-    return text.split('\n');
-}
-/**
- * Generate a diff for a single file change.
+ * @param root - Root directory path
+ * @param options - Tree creation options
+ * @returns A new Tree instance
+ * @throws {Error} If root doesn't exist or isn't a directory
  *
- * @example
+ * @example Creating a virtual tree
  * ```typescript
- * const change: FileChange = {
- *   path: 'src/app.ts',
- *   type: 'UPDATE',
- *   originalContent: Buffer.from('const x = 1;\n'),
- *   content: Buffer.from('const x = 2;\n'),
- * }
- * const diff = generateDiff(change)
- * // { path: 'src/app.ts', additions: 1, deletions: 1, lines: [...] }
- * ```
+ * import { createTree } from '@hyperfrontend/project-scope'
  *
- * @param change - File change to diff
- * @param options - Configuration for diff generation including context lines
- * @returns FileDiff object
- */
-function generateDiff(change, options = {}) {
-    const contextLines = options.contextLines ?? DEFAULT_CONTEXT_LINES;
-    diffLogger.debug('generateDiff', { path: change.path, type: change.type, contextLines });
-    const oldLines = bufferToLines(change.originalContent);
-    const newLines = bufferToLines(change.content);
-    if (change.type === 'CREATE') {
-        const lines = newLines
-            .filter((line) => line !== '' || newLines.indexOf(line) !== newLines.length - 1 || newLines.length === 1)
-            .map((content, idx) => ({
-            type: 'add',
-            line: idx + 1,
-            content,
-        }));
-        const filteredLines = lines.filter((l, i) => !(i === lines.length - 1 && l.content === '' && lines.length > 1));
-        return {
-            path: change.path,
-            lines: filteredLines,
-            additions: filteredLines.length,
-            deletions: 0,
-        };
-    }
-    if (change.type === 'DELETE') {
-        const lines = oldLines.map((content, idx) => ({
-            type: 'remove',
-            line: idx + 1,
-            content,
-        }));
-        const filteredLines = lines.filter((l, i) => !(i === lines.length - 1 && l.content === '' && lines.length > 1));
-        return {
-            path: change.path,
-            lines: filteredLines,
-            additions: 0,
-            deletions: filteredLines.length,
-        };
-    }
-    const table = computeLcsTable(oldLines, newLines);
-    const operations = backtrackLcs(table, oldLines, newLines);
-    const lines = operationsToDiffLines(operations, contextLines);
-    const additions = lines.filter((l) => l.type === 'add').length;
-    const deletions = lines.filter((l) => l.type === 'remove').length;
-    return {
-        path: change.path,
-        lines,
-        additions,
-        deletions,
-    };
-}
-/**
- * Format a FileDiff as a unified diff string.
+ * const tree = createTree('./my-project')
  *
- * @example
- * ```typescript
- * const formatted = formatUnifiedDiff(diff)
- * console.log(formatted)
- * // --- a/src/app.ts
- * // +++ b/src/app.ts
- * // @@ -1,3 +1,3 @@
- * //  const x = 1;
- * // -const y = 2;
- * // +const y = 3;
- * //  const z = 4;
- * ```
+ * // Read files from tree
+ * const content = tree.read('src/index.ts', 'utf-8')
  *
- * @param diff - FileDiff to format
- * @returns Unified diff string
+ * // Make changes (buffered in memory)
+ * tree.write('src/new-file.ts', 'export const x = 1')
+ *
+ * // List pending changes
+ * console.log(tree.listChanges())
+ * ```
  */
-function formatUnifiedDiff(diff) {
-    const lines = [];
-    lines.push(`--- a/${diff.path}`);
-    lines.push(`+++ b/${diff.path}`);
-    if (diff.lines.length === 0) {
-        return lines.join('\n');
-    }
-    const hunks = [];
-    const currentHunk = [];
-    for (const line of diff.lines) {
-        currentHunk.push(line);
-    }
-    if (currentHunk.length > 0) {
-        hunks.push(currentHunk);
+function createTree(root, options) {
+    const normalizedRoot = normalizePath(root);
+    factoryLogger.debug('createTree', { root: normalizedRoot });
+    if (!exists(normalizedRoot)) {
+        factoryLogger.warn('createTree failed: root does not exist', { root: normalizedRoot });
+        throw createError(`Root directory does not exist: ${normalizedRoot}`);
     }
-    for (const hunk of hunks) {
-        const contextAndRemove = hunk.filter((l) => l.type === 'context' || l.type === 'remove');
-        const contextAndAdd = hunk.filter((l) => l.type === 'context' || l.type === 'add');
-        const oldStart = hunk.find((l) => l.type === 'context' || l.type === 'remove')?.line ?? 1;
-        const newStart = hunk.find((l) => l.type === 'context' || l.type === 'add')?.line ?? 1;
-        const oldCount = contextAndRemove.length;
-        const newCount = contextAndAdd.length;
-        lines.push(`@@ -${oldStart},${oldCount} +${newStart},${newCount} @@`);
-        for (const line of hunk) {
-            const prefix = line.type === 'add' ? '+' : line.type === 'remove' ? '-' : ' ';
-            lines.push(`${prefix}${line.content}`);
-        }
+    if (!isDirectory(normalizedRoot)) {
+        factoryLogger.warn('createTree failed: root is not a directory', { root: normalizedRoot });
+        throw createError(`Root path is not a directory: ${normalizedRoot}`);
     }
-    return lines.join('\n');
+    return createFsTree(normalizedRoot, options);
 }
 /**
- * Generate diffs for all changes in a tree.
+ * Create a tree from disk.
+ *
+ * Convenience alias for createTree.
+ *
+ * @param root - Root directory path
+ * @param options - Tree creation options
+ * @returns A new Tree instance backed by disk
  *
- * @example
+ * @example Creating a tree from disk
  * ```typescript
- * const tree = createTree('/workspace')
- * tree.write('new.txt', 'hello')
- * tree.delete('old.txt')
+ * import { createTreeFromDisk } from '@hyperfrontend/project-scope'
  *
- * const diffs = generateAllDiffs(tree)
- * for (const diff of diffs) {
- *   console.log(formatUnifiedDiff(diff))
- * }
+ * const tree = createTreeFromDisk('/path/to/project', { verbose: true })
+ * const files = tree.children('/src')
  * ```
- *
- * @param tree - Tree to generate diffs for
- * @param options - Diff options
- * @returns Array of FileDiff objects
  */
-function generateAllDiffs(tree, options = {}) {
-    const changes = tree.listChanges();
-    diffLogger.debug('generateAllDiffs', { changeCount: changes.length });
-    return changes.map((change) => generateDiff(change, options));
+function createTreeFromDisk(root, options) {
+    return createTree(root, options);
 }
 
 export { Mode, commitChanges, createFsTree, createTree, createTreeFromDisk, formatUnifiedDiff, generateAllDiffs, generateDiff, rollbackChanges };
-//# sourceMappingURL=index.esm.js.map