@warlock.js/core 4.0.48 → 4.0.59

package/esm/dev2-server/file-event-handler.js

@@ -0,0 +1,300 @@
+import events from'@mongez/events';import {debounce}from'@mongez/reinforcements';import {devLogSuccess}from'./dev-logger.js';import {FILE_PROCESSING_BATCH_SIZE}from'./flags.js';import {clearFileExistsCache}from'./parse-imports.js';import {Path}from'./path.js';/**
+ * FileEventHandler - Handles runtime file system events
+ *
+ * This class receives file system events (add, change, delete) from the
+ * FilesWatcher and processes them in batches for optimal performance.
+ *
+ * ## Batching Strategy
+ *
+ * Events are collected and processed after a debounce period (150ms).
+ * This batching is crucial when:
+ * - Multiple files are created at once (e.g., VSCode extension creating a module)
+ * - A file save triggers multiple filesystem events
+ * - Large refactoring operations affect many files
+ *
+ * ## Processing Order
+ *
+ * 1. **Added files** - Processed first so they're available for imports
+ * 2. **Changed files** - Can reference newly added files
+ * 3. **Deleted files** - Processed last, dependents are notified
+ *
+ * ## Batch Add Strategy
+ *
+ * When multiple files are added (e.g., creating a Warlock module), they're
+ * processed using a two-phase approach with topological sorting:
+ *
+ * 1. **Parse Phase**: All files are parsed to discover dependencies
+ * 2. **Sort Phase**: Files are topologically sorted by dependencies
+ * 3. **Complete Phase**: Files are finalized in dependency order
+ *
+ * This ensures that when file A imports file B, file B is processed first.
+ *
+ * @class FileEventHandler
+ */
+class FileEventHandler {
+    fileOperations;
+    manifest;
+    dependencyGraph;
+    files;
+    /**
+     * Pending file change events (relative paths)
+     */
+    pendingChanges = new Set();
+    /**
+     * Pending file add events (relative paths)
+     */
+    pendingAdds = new Set();
+    /**
+     * Pending file delete events (relative paths)
+     */
+    pendingDeletes = new Set();
+    /**
+     * Debounced batch processor
+     * Waits 150ms after the last event before processing
+     */
+    processPendingEvents = debounce(async () => {
+        await this.processBatch();
+    }, 150);
+    /**
+     * Creates a new FileEventHandler
+     *
+     * @param fileOperations - FileOperations instance for file lifecycle management
+     * @param manifest - ManifestManager for persisting file metadata
+     * @param dependencyGraph - DependencyGraph for tracking dependencies
+     * @param files - Map of all tracked FileManager instances
+     */
+    constructor(fileOperations, manifest, dependencyGraph, files) {
+        this.fileOperations = fileOperations;
+        this.manifest = manifest;
+        this.dependencyGraph = dependencyGraph;
+        this.files = files;
+    }
+    /**
+     * Handle a file change event from the file watcher
+     *
+     * The event is queued and will be processed in the next batch.
+     *
+     * @param absolutePath - Absolute path to the changed file
+     */
+    handleFileChange(absolutePath) {
+        const relativePath = Path.toRelative(absolutePath);
+        this.pendingChanges.add(relativePath);
+        this.processPendingEvents();
+    }
+    /**
+     * Handle a file add event from the file watcher
+     *
+     * The event is queued and will be processed in the next batch.
+     *
+     * @param absolutePath - Absolute path to the new file
+     */
+    handleFileAdd(absolutePath) {
+        const relativePath = Path.toRelative(absolutePath);
+        this.pendingAdds.add(relativePath);
+        this.processPendingEvents();
+    }
+    /**
+     * Handle a file delete event from the file watcher
+     *
+     * The event is queued and will be processed in the next batch.
+     *
+     * @param absolutePath - Absolute path to the deleted file
+     */
+    handleFileDelete(absolutePath) {
+        const relativePath = Path.toRelative(absolutePath);
+        this.pendingDeletes.add(relativePath);
+        this.processPendingEvents();
+    }
+    /**
+     * Process all pending events in a batch
+     *
+     * Events are processed in order: adds → changes → deletes
+     * After processing, the dependency graph and manifest are updated.
+     *
+     * @internal
+     */
+    async processBatch() {
+        // Snapshot pending events
+        const changes = Array.from(this.pendingChanges);
+        const adds = Array.from(this.pendingAdds);
+        const deletes = Array.from(this.pendingDeletes);
+        // Clear pending sets
+        this.pendingChanges.clear();
+        this.pendingAdds.clear();
+        this.pendingDeletes.clear();
+        // Skip if nothing to process
+        if (changes.length === 0 && adds.length === 0 && deletes.length === 0) {
+            return;
+        }
+        // For batch operations, add extra delay to let filesystem settle
+        const totalFiles = adds.length + changes.length;
+        if (totalFiles > 1) {
+            await new Promise((resolve) => setTimeout(resolve, 500));
+            clearFileExistsCache();
+        }
+        // Process in order: adds first, then changes, then deletes
+        await this.processBatchAdds(adds);
+        await this.processBatchChanges(changes);
+        await this.processBatchDeletes(deletes);
+        // Update dependency graph and manifest once
+        this.fileOperations.updateFileDependents();
+        this.fileOperations.syncFilesToManifest();
+        await this.manifest.save();
+        // Trigger batch completion event (for HMR/reload execution)
+        events.trigger("dev-server:batch-complete", {
+            added: adds,
+            changed: changes,
+            deleted: deletes,
+        });
+    }
+    /**
+     * Process a batch of changed files
+     *
+     * Each file is updated (reprocessed if content changed).
+     * Processing is done in parallel batches for performance.
+     *
+     * @param relativePaths - Array of relative paths to changed files
+     * @internal
+     */
+    async processBatchChanges(relativePaths) {
+        if (relativePaths.length === 0)
+            return;
+        const BATCH_SIZE = FILE_PROCESSING_BATCH_SIZE;
+        for (let i = 0; i < relativePaths.length; i += BATCH_SIZE) {
+            const batch = relativePaths.slice(i, i + BATCH_SIZE);
+            await Promise.all(batch.map(async (relativePath) => {
+                await this.fileOperations.updateFile(relativePath);
+            }));
+        }
+    }
+    /**
+     * Process a batch of added files using topological sort
+     *
+     * This method uses a two-phase approach:
+     * 1. Parse all files to discover dependencies
+     * 2. Complete files in topological order (dependencies first)
+     *
+     * This ensures that when file A imports file B (both in the batch),
+     * file B is fully processed before file A tries to resolve the import.
+     *
+     * @param relativePaths - Array of relative paths to new files
+     * @internal
+     */
+    async processBatchAdds(relativePaths) {
+        if (relativePaths.length === 0)
+            return;
+        const batchSet = new Set(relativePaths);
+        // PHASE 1: Parse all files in parallel to discover dependencies
+        const parsedFiles = await Promise.all(relativePaths.map(async (relativePath) => {
+            try {
+                return await this.fileOperations.parseNewFile(relativePath);
+            }
+            catch (error) {
+                return null;
+            }
+        }));
+        // Filter out nulls (files that couldn't be parsed)
+        const validFiles = parsedFiles.filter((f) => f !== null);
+        // PHASE 2: Topological sort for proper dependency order
+        const orderedFiles = this.topologicalSort(validFiles, batchSet);
+        // PHASE 3: Complete processing in dependency order
+        for (const file of orderedFiles) {
+            try {
+                await this.fileOperations.finalizeNewFile(file);
+                devLogSuccess(`Added file: ${file.relativePath}`);
+            }
+            catch (error) {
+                // File may have issues, but we continue with others
+                console.error(`Failed to add file ${file.relativePath}:`, error);
+            }
+        }
+    }
+    /**
+     * Topologically sort files by their dependencies
+     *
+     * Uses Kahn's algorithm to produce an ordering where files with
+     * no batch dependencies come first, and files that depend on other
+     * batch files come after their dependencies.
+     *
+     * @param files - Array of FileManager instances to sort
+     * @param batchSet - Set of relative paths in this batch (for filtering deps)
+     * @returns Files in topological order (dependencies first)
+     *
+     * @example
+     * ```typescript
+     * // If A imports B, and B imports C, result will be: [C, B, A]
+     * const ordered = this.topologicalSort([fileA, fileB, fileC], batchSet);
+     * ```
+     *
+     * @internal
+     */
+    topologicalSort(files, batchSet) {
+        const fileMap = new Map();
+        const inDegree = new Map();
+        const graph = new Map();
+        // Initialize data structures
+        for (const file of files) {
+            fileMap.set(file.relativePath, file);
+            inDegree.set(file.relativePath, 0);
+            graph.set(file.relativePath, []);
+        }
+        // Build graph: for each file, record which files depend on it
+        for (const file of files) {
+            for (const dep of file.dependencies) {
+                // Only consider dependencies that are in this batch
+                if (batchSet.has(dep) && fileMap.has(dep)) {
+                    // dep → file (file depends on dep)
+                    graph.get(dep).push(file.relativePath);
+                    inDegree.set(file.relativePath, (inDegree.get(file.relativePath) || 0) + 1);
+                }
+            }
+        }
+        // Kahn's algorithm: start with files that have no batch dependencies
+        const queue = [];
+        for (const file of files) {
+            if (inDegree.get(file.relativePath) === 0) {
+                queue.push(file);
+            }
+        }
+        const result = [];
+        while (queue.length > 0) {
+            const file = queue.shift();
+            result.push(file);
+            // For each file that depends on this one, reduce its in-degree
+            for (const dependentPath of graph.get(file.relativePath) || []) {
+                const newDegree = (inDegree.get(dependentPath) || 0) - 1;
+                inDegree.set(dependentPath, newDegree);
+                if (newDegree === 0) {
+                    const dependentFile = fileMap.get(dependentPath);
+                    if (dependentFile) {
+                        queue.push(dependentFile);
+                    }
+                }
+            }
+        }
+        // Handle any remaining files (cycles or isolated)
+        // These are added at the end to ensure all files are processed
+        for (const file of files) {
+            if (!result.includes(file)) {
+                result.push(file);
+            }
+        }
+        return result;
+    }
+    /**
+     * Process a batch of deleted files
+     *
+     * Each file is removed from the system and its dependents are notified.
+     *
+     * @param relativePaths - Array of relative paths to deleted files
+     * @internal
+     */
+    async processBatchDeletes(relativePaths) {
+        if (relativePaths.length === 0)
+            return;
+        for (const relativePath of relativePaths) {
+            await this.fileOperations.deleteFile(relativePath);
+            devLogSuccess(`Deleted file: ${relativePath}`);
+        }
+    }
+}export{FileEventHandler};//# sourceMappingURL=file-event-handler.js.map

package/esm/dev2-server/file-event-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-event-handler.js","sources":["../../src/dev2-server/file-event-handler.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/esm/dev2-server/file-manager.d.ts

@@ -0,0 +1,385 @@
+import { type FileOperations } from "./file-operations";
+import type { FileManifest, FileState, FileType, LayerType } from "./types";
+/**
+ * Options for the process() method
+ */
+export interface ProcessOptions {
+    /**
+     * Force reprocessing even if file hasn't changed
+     * @default false
+     */
+    force?: boolean;
+    /**
+     * Whether to transform imports to cache paths
+     * Set to false during batch operations where imports are transformed later
+     * @default true
+     */
+    transformImports?: boolean;
+    /**
+     * Whether to save to cache after processing
+     * Set to false if you need to do additional transformations before saving
+     * @default true
+     */
+    saveToCache?: boolean;
+}
+/**
+ * FileManager - Manages the lifecycle of a single source file
+ *
+ * ## Lifecycle States
+ *
+ * ```
+ * idle → loading → parsed → transpiled → ready
+ *   ↑                                      │
+ *   └──────────── (file changed) ──────────┘
+ * ```
+ *
+ * ## Processing Pipeline
+ *
+ * All file processing flows through a unified pipeline:
+ * 1. **Load** - Read source from disk
+ * 2. **Hash** - Calculate content hash for change detection
+ * 3. **Parse** - Discover imports and dependencies
+ * 4. **Transpile** - Convert TypeScript to JavaScript
+ * 5. **Transform** - Rewrite import paths to cache locations
+ * 6. **Save** - Write transformed code to cache (ONCE)
+ *
+ * ## Usage Examples
+ *
+ * ```typescript
+ * // Standard processing (full pipeline)
+ * const file = new FileManager(absolutePath, filesMap, fileOps);
+ * await file.process();
+ *
+ * // Batch processing (parse first, complete later)
+ * await file.parse();
+ * // ... after dependencies are ready ...
+ * await file.complete();
+ *
+ * // Check for changes and reprocess if needed
+ * const changed = await file.process(); // returns false if unchanged
+ *
+ * // Force reprocessing
+ * await file.process({ force: true });
+ * ```
+ *
+ * @class FileManager
+ */
+export declare class FileManager {
+    readonly absolutePath: string;
+    files: Map<string, FileManager>;
+    fileOperations: FileOperations;
+    /**
+     * Relative path from the project root directory
+     * Used as the primary identifier for files throughout the system
+     * @example "src/app/users/controllers/get-user.controller.ts"
+     */
+    relativePath: string;
+    /**
+     * Unix timestamp of the last modification time
+     * Used with hash for change detection
+     */
+    lastModified: number;
+    /**
+     * SHA-256 hash of the source content
+     * Primary mechanism for detecting file changes
+     */
+    hash: string;
+    /**
+     * Original TypeScript/JavaScript source code
+     * Loaded from disk during processing
+     */
+    source: string;
+    /**
+     * Transpiled JavaScript code with transformed imports
+     * This is the final output that gets saved to cache and loaded at runtime
+     */
+    transpiled: string;
+    /**
+     * Set of relative paths that this file depends on (imports)
+     * Used to build the dependency graph for HMR invalidation
+     * @example Set(["src/app/users/models/user.model.ts", "src/config/database.ts"])
+     */
+    dependencies: Set<string>;
+    /**
+     * Map of original import specifiers to resolved absolute paths
+     * Key: the exact import string from source (e.g., "./user.model")
+     * Value: resolved absolute path (e.g., "D:/project/src/app/users/models/user.model.ts")
+     *
+     * Used during import transformation to rewrite paths to cache locations
+     */
+    importMap: Map<string, string>;
+    /**
+     * Set of relative paths that depend on this file
+     * Populated from the dependency graph after initial processing
+     * Used to determine what needs reloading when this file changes
+     */
+    dependents: Set<string>;
+    /**
+     * Version number incremented on each change
+     * Used for cache busting in dynamic imports
+     */
+    version: number;
+    /**
+     * Semantic type of the file based on its path/content
+     * Used to determine reload behavior and special handling
+     */
+    type: FileType | undefined;
+    /**
+     * Reload layer: HMR (hot module replacement) or FSR (full server restart)
+     * Determines how changes to this file are applied at runtime
+     */
+    layer: LayerType | undefined;
+    /**
+     * Path to the cached transpiled file (relative to .warlock/cache/)
+     * @example "src-app-users-controllers-get-user.controller.js"
+     */
+    cachePath: string;
+    /**
+     * Cleanup function called before the file is unloaded
+     * Set by module loader for files that export cleanup handlers
+     */
+    cleanup?: (() => void)[] | (() => void);
+    /**
+     * Whether imports have been transformed to cache paths
+     * Prevents double transformation and tracks processing state
+     */
+    importsTransformed: boolean;
+    /**
+     * Whether this file contains only type definitions (no runtime code)
+     * Type-only files are excluded from circular dependency detection
+     */
+    isTypeOnlyFile: boolean;
+    /**
+     * Current processing state of the file
+     *
+     * - `idle`: Initial state, no processing started
+     * - `loading`: Reading source from disk
+     * - `parsed`: Source loaded and imports discovered
+     * - `transpiled`: TypeScript compiled to JavaScript
+     * - `ready`: Fully processed and available for use
+     * - `updating`: Being reprocessed after a change
+     * - `deleted`: File has been removed from disk
+     */
+    state: FileState;
+    /**
+     * Creates a new FileManager instance
+     *
+     * @param absolutePath - Full filesystem path to the source file
+     * @param files - Map of all tracked files (for import resolution)
+     * @param fileOperations - FileOperations instance (for adding missing dependencies)
+     *
+     * @example
+     * ```typescript
+     * const fileManager = new FileManager(
+     *   "D:/project/src/app/users/controllers/get-user.controller.ts",
+     *   filesMap,
+     *   fileOperations
+     * );
+     * ```
+     */
+    constructor(absolutePath: string, files: Map<string, FileManager>, fileOperations: FileOperations);
+    /**
+     * Initialize the file manager from disk or manifest cache
+     *
+     * This is the primary entry point for file initialization.
+     * If manifest data is provided, it will attempt to use cached data
+     * and only reprocess if the file has changed.
+     *
+     * @param fileManifest - Optional cached manifest data from previous build
+     *
+     * @example
+     * ```typescript
+     * // Fresh initialization (no cache)
+     * await fileManager.init();
+     *
+     * // Initialize with cached manifest data
+     * await fileManager.init(manifestEntry);
+     * ```
+     */
+    init(fileManifest?: Partial<FileManifest>): Promise<void>;
+    /**
+     * Get the cache path as a file:// URL for dynamic import
+     * Includes cache busting query parameter based on version
+     *
+     * @returns File URL ready for dynamic import, or empty string if no cache
+     *
+     * @example
+     * ```typescript
+     * const module = await import(fileManager.cachePathUrl);
+     * ```
+     */
+    get cachePathUrl(): string;
+    /**
+     * Process the file through the unified pipeline
+     *
+     * This is the core method that handles all file processing.
+     * It implements a single-pass pipeline that:
+     * 1. Loads source from disk
+     * 2. Checks if content changed (skip if unchanged)
+     * 3. Parses imports to discover dependencies
+     * 4. Ensures all dependencies exist
+     * 5. Transpiles TypeScript to JavaScript
+     * 6. Transforms imports to cache paths
+     * 7. Saves to cache (ONCE - no duplicate writes)
+     *
+     * @param options - Processing options
+     * @param options.force - Force reprocessing even if unchanged
+     * @param options.transformImports - Whether to transform import paths (default: true)
+     * @param options.saveToCache - Whether to save to cache file (default: true)
+     *
+     * @returns True if file was processed, false if unchanged and skipped
+     *
+     * @example
+     * ```typescript
+     * // Normal processing
+     * const changed = await fileManager.process();
+     *
+     * // Force reprocess
+     * await fileManager.process({ force: true });
+     *
+     * // Batch mode: transform imports later
+     * await fileManager.process({ transformImports: false });
+     * ```
+     */
+    process(options?: ProcessOptions): Promise<boolean>;
+    /**
+     * Parse the file to discover dependencies (Phase 1 of batch processing)
+     *
+     * This method only performs the first half of processing:
+     * - Loads source from disk
+     * - Calculates hash
+     * - Parses imports to discover dependencies
+     * - Sets up file metadata
+     *
+     * Use this for batch file operations where you need to know
+     * dependencies before deciding processing order.
+     *
+     * **Important**: After calling parse(), you must call complete()
+     * to finish processing and make the file usable.
+     *
+     * @example
+     * ```typescript
+     * // Batch processing pattern
+     * const files = await Promise.all(
+     *   paths.map(async (path) => {
+     *     const file = new FileManager(path, filesMap, fileOps);
+     *     await file.parse();
+     *     return file;
+     *   })
+     * );
+     *
+     * // Order by dependencies, then complete
+     * for (const file of orderedFiles) {
+     *   await file.complete();
+     * }
+     * ```
+     */
+    parse(): Promise<void>;
+    /**
+     * Complete file processing after parse() (Phase 2 of batch processing)
+     *
+     * This method completes the processing pipeline:
+     * - Ensures dependencies exist
+     * - Transpiles TypeScript to JavaScript
+     * - Transforms imports to cache paths
+     * - Saves to cache
+     *
+     * **Important**: This must be called after parse() to finish processing.
+     * The file is not usable until complete() has been called.
+     *
+     * @example
+     * ```typescript
+     * await file.parse();
+     * // ... after dependencies are ready ...
+     * await file.complete();
+     * // File is now ready for use
+     * ```
+     */
+    complete(): Promise<void>;
+    /**
+     * Update the file after a change during development
+     *
+     * This is a convenience method that delegates to process().
+     * It checks if the file has actually changed and only reprocesses if needed.
+     *
+     * @returns True if file was reprocessed, false if unchanged
+     *
+     * @example
+     * ```typescript
+     * // Called by file watcher
+     * const changed = await fileManager.update();
+     * if (changed) {
+     *   console.log("File was updated");
+     * }
+     * ```
+     */
+    update(): Promise<boolean>;
+    /**
+     * Force reprocess the file regardless of hash match
+     *
+     * Use this when:
+     * - A dependency that was previously missing is now available
+     * - Import transformation needs to be redone
+     * - Cache is corrupted or missing
+     *
+     * @example
+     * ```typescript
+     * // After a missing dependency is added
+     * await fileManager.forceReprocess();
+     * ```
+     */
+    forceReprocess(): Promise<void>;
+    /**
+     * Initialize from cached manifest data
+     *
+     * Attempts to use cached data from a previous build.
+     * If the file has changed (hash mismatch) or cache is missing,
+     * falls back to full processing.
+     *
+     * @param fileManifest - Cached manifest entry
+     * @internal
+     */
+    protected initFromManifest(fileManifest: Partial<FileManifest>): Promise<void>;
+    /**
+     * Detect the file type and reload layer based on path patterns
+     *
+     * File types determine special handling:
+     * - `main`: Application entry point
+     * - `config`: Configuration files
+     * - `route`: Route definitions
+     * - `controller`: HTTP controllers
+     * - `service`: Business logic services
+     * - `model`: Database models
+     * - `event`: Event handlers
+     * - `other`: Everything else
+     *
+     * Layers determine reload behavior:
+     * - `HMR`: Hot module replacement (instant reload)
+     * - `FSR`: Full server restart (required for some changes)
+     *
+     * @internal
+     */
+    protected detectFileTypeAndLayer(): void;
+    /**
+     * Export file data as a manifest entry for caching
+     *
+     * The manifest stores metadata about each file to enable:
+     * - Fast startup by skipping unchanged files
+     * - Dependency tracking across restarts
+     * - Cache validation via hash comparison
+     *
+     * Note: Source code and transpiled output are NOT stored in manifest.
+     * - Source is always read from disk
+     * - Transpiled code is stored in .warlock/cache/
+     *
+     * @returns Manifest entry for this file
+     *
+     * @example
+     * ```typescript
+     * const entry = fileManager.toManifest();
+     * manifest.setFile(fileManager.relativePath, entry);
+     * ```
+     */
+    toManifest(): FileManifest;
+}
+//# sourceMappingURL=file-manager.d.ts.map