@ecopages/core 0.2.0-alpha.3 → 0.2.0-alpha.31

package/src/watchers/project-watcher.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import chokidar, {} from "chokidar";
 import { fileSystem } from "@ecopages/file-system";
 import { appLogger } from "../global/app-logger.js";
+import { DevelopmentInvalidationService } from "../services/invalidation/development-invalidation.service.js";
 class ProjectWatcher {
   /**
    * Duplicate identical watcher events within this window are ignored.
@@ -15,13 +16,16 @@ class ProjectWatcher {
   refreshRouterRoutesCallback;
   hmrManager;
   bridge;
+  invalidationService;
   watcher = null;
   lastHandledChange = /* @__PURE__ */ new Map();
+  changeQueue = Promise.resolve();
   constructor({ config, refreshRouterRoutesCallback, hmrManager, bridge }) {
     this.appConfig = config;
     this.refreshRouterRoutesCallback = refreshRouterRoutesCallback;
     this.hmrManager = hmrManager;
     this.bridge = bridge;
+    this.invalidationService = new DevelopmentInvalidationService(config);
     this.triggerRouterRefresh = this.triggerRouterRefresh.bind(this);
     this.handleError = this.handleError.bind(this);
     this.handleFileChange = this.handleFileChange.bind(this);
@@ -41,6 +45,12 @@ class ProjectWatcher {
       }
     }
   }
+  isRouteSourceFile(filePath) {
+    return this.invalidationService.isRouteSourceFile(filePath);
+  }
+  isIncludeSourceFile(filePath) {
+    return this.invalidationService.isIncludeSourceFile(filePath);
+  }
   /**
    * Handles public directory file changes by copying only the changed file.
    * @param filePath - Absolute path of the changed file
@@ -60,19 +70,33 @@ class ProjectWatcher {
       this.bridge.reload();
     }
   }
+  /**
+   * Serializes file change handling so that concurrent chokidar events are
+   * processed one at a time, preventing overlapping builds and race conditions.
+   */
+  enqueueChange(task) {
+    const queuedTask = this.changeQueue.then(task, task);
+    this.changeQueue = queuedTask.catch(() => void 0);
+  }
   /**
    * Handles file changes by uncaching modules, refreshing routes, and delegating appropriately.
-   * Follows 4-rule priority:
-   * 0. Public directory match? → copy file and reload
-   * 1. additionalWatchPaths match? → reload
-   * 2. Processor extension match? → processor handles (skip HMR)
-   * 3. Otherwise → HMR strategies
+   * Follows 5-rule priority:
+   * 0. Public directory match? -> copy file and reload
+   * 1. additionalWatchPaths match? -> reload
+   * 2. Include template source? -> reload after processor notifications
+   * 3. Processor-owned asset? -> processor already handled it via notification, skip HMR
+   * 4. Otherwise -> HMR strategies
+   *
+   * Processors that watch a file extension as a dependency (e.g. PostCSS watching
+   * .tsx for Tailwind class scanning) are always notified first, but do not
+   * prevent the file from flowing through the normal HMR strategy pipeline.
    *
    * Duplicate identical watcher events for the same file are coalesced within a
    * short window before any of the priority rules run.
    * @param rawPath - Path of the changed file
+   * @param event - The type of file system event
    */
-  async handleFileChange(rawPath) {
+  async handleFileChange(rawPath, event = "change") {
     const filePath = path.resolve(rawPath);
     const now = Date.now();
     const lastHandledAt = this.lastHandledChange.get(filePath);
@@ -81,27 +105,33 @@ class ProjectWatcher {
     }
     this.lastHandledChange.set(filePath, now);
     try {
-      if (this.isPublicDirFile(filePath)) {
+      const plan = this.invalidationService.planFileChange(filePath);
+      if (plan.category === "public-asset") {
         await this.handlePublicDirFileChange(filePath);
         return;
       }
       this.uncacheModules();
-      const isPageFile = filePath.startsWith(this.appConfig.absolutePaths.pagesDir);
-      if (isPageFile) {
-        this.refreshRouterRoutesCallback();
+      if (plan.invalidateServerModules) {
+        this.invalidationService.invalidateServerModules([filePath]);
       }
-      if (this.matchesAdditionalWatchPaths(filePath)) {
+      if (plan.refreshRoutes) {
+        await this.refreshRouterRoutesCallback();
+      }
+      if (plan.category === "additional-watch") {
         this.bridge.reload();
         return;
       }
-      if (this.isHandledByProcessor(filePath)) {
+      await this.notifyProcessors(filePath, event);
+      if (plan.category === "include-source") {
+        this.bridge.reload();
         return;
       }
-      if (this.isWatchedByProcessor(filePath) && !this.hmrManager.canHandleFileChange(filePath)) {
-        this.hmrManager.broadcast({ type: "layout-update" });
+      if (plan.processorHandledAsset) {
         return;
       }
-      await this.hmrManager.handleFileChange(filePath);
+      if (plan.delegateToHmr) {
+        await this.hmrManager.handleFileChange(filePath);
+      }
     } catch (error) {
       if (error instanceof Error) {
         this.bridge.error(error.message);
@@ -109,65 +139,56 @@ class ProjectWatcher {
       }
     }
   }
+  /**
+   * Notifies all processors whose watch config matches the given file extension.
+   * This is called before checking processor ownership so that dependency-only
+   * processors (e.g. PostCSS watching .tsx for class scanning) receive their
+   * notifications regardless of whether they own the file.
+   */
+  async notifyProcessors(filePath, event) {
+    const ctx = { path: filePath, bridge: this.bridge };
+    for (const processor of this.appConfig.processors.values()) {
+      const watchConfig = processor.getWatchConfig();
+      if (!watchConfig) continue;
+      const { extensions = [] } = watchConfig;
+      if (extensions.length && !extensions.some((ext) => filePath.endsWith(ext))) {
+        continue;
+      }
+      const handler = this.getProcessorHandler(watchConfig, event);
+      if (handler) {
+        await handler(ctx);
+      }
+    }
+  }
+  getProcessorHandler(watchConfig, event) {
+    switch (event) {
+      case "change":
+        return watchConfig.onChange;
+      case "add":
+        return watchConfig.onCreate;
+      case "unlink":
+        return watchConfig.onDelete;
+    }
+  }
   /**
    * Checks if a file is in the public directory.
    */
   isPublicDirFile(filePath) {
-    return filePath.startsWith(this.appConfig.absolutePaths.publicDir);
+    return this.invalidationService.isPublicDirFile(filePath);
   }
   /**
    * Checks if file path matches any additionalWatchPaths patterns.
    */
   matchesAdditionalWatchPaths(filePath) {
-    const patterns = this.appConfig.additionalWatchPaths;
-    if (!patterns.length) return false;
-    for (const pattern of patterns) {
-      if (pattern.includes("*")) {
-        const ext = pattern.replace(/\*\*?\/\*/, "");
-        if (filePath.endsWith(ext)) return true;
-      } else {
-        if (filePath.endsWith(pattern) || filePath === path.resolve(pattern)) return true;
-      }
-    }
-    return false;
-  }
-  /**
-   * Checks whether a file is watched by any processor, even if that processor
-   * does not own the file as a primary asset.
-   */
-  isWatchedByProcessor(filePath) {
-    for (const processor of this.appConfig.processors.values()) {
-      const watchConfig = processor.getWatchConfig();
-      if (!watchConfig) continue;
-      const { extensions = [] } = watchConfig;
-      if (extensions.length && extensions.some((ext) => filePath.endsWith(ext))) {
-        return true;
-      }
-    }
-    return false;
+    return this.invalidationService.matchesAdditionalWatchPaths(filePath);
   }
   /**
    * Checks if a file is handled by a processor.
-   * Processors that declare extensions own those file types.
+   * Processors that declare asset capabilities own those file types.
+   * Processors without capabilities fall back to checking watch extensions.
    */
   isHandledByProcessor(filePath) {
-    for (const processor of this.appConfig.processors.values()) {
-      const capabilities = processor.getAssetCapabilities?.() ?? [];
-      if (capabilities.length > 0) {
-        const matchesConfiguredAsset = typeof processor.matchesFileFilter !== "function" || processor.matchesFileFilter(filePath);
-        if (matchesConfiguredAsset && capabilities.some((capability) => processor.canProcessAsset?.(capability.kind, filePath))) {
-          return true;
-        }
-        continue;
-      }
-      const watchConfig = processor.getWatchConfig();
-      if (!watchConfig) continue;
-      const { extensions = [] } = watchConfig;
-      if (extensions.length && extensions.some((ext) => filePath.endsWith(ext))) {
-        return true;
-      }
-    }
-    return false;
+    return this.invalidationService.isProcessorOwnedAsset(filePath);
   }
   /**
    * Triggers router refresh for page directory changes.
@@ -175,10 +196,11 @@ class ProjectWatcher {
    *
    * @param {string} path - Path of the changed directory
    */
-  triggerRouterRefresh(path2) {
-    const isPageDir = path2.startsWith(this.appConfig.absolutePaths.pagesDir);
-    if (isPageDir) {
-      this.refreshRouterRoutesCallback();
+  async triggerRouterRefresh(changedPath) {
+    const resolvedPath = path.resolve(changedPath);
+    const isPageDir = resolvedPath.startsWith(this.appConfig.absolutePaths.pagesDir) && path.extname(resolvedPath) === "";
+    if (isPageDir || this.isRouteSourceFile(resolvedPath)) {
+      await this.refreshRouterRoutesCallback();
     }
   }
   /**
@@ -192,71 +214,59 @@ class ProjectWatcher {
     }
     appLogger.error(`Watcher error: ${error}`);
   }
-  /**
-   * Processes file changes for specific file extensions.
-   * Used by processors to handle their specific file types.
-   *
-   * @private
-   * @param {string} path - Path of the changed file
-   * @param {string[]} extensions - File extensions to process
-   * @param {(ctx: ProcessorWatchContext) => void} handler - Handler function for the file change
-   */
-  shouldProcess(path2, extensions, handler) {
-    if (!extensions.length || extensions.some((ext) => path2.endsWith(ext))) {
-      handler({ path: path2, bridge: this.bridge });
-    }
-  }
   /**
    * Creates and configures the file system watcher.
    * This sets up:
-   * 1. Processor-specific file watching
-   * 2. Page file watching
-   * 3. Directory watching
-   * 4. Error handling
+   * 1. Page file watching
+   * 2. Directory watching
+   * 3. Error handling
+   *
+   * Processor notifications are dispatched inside handleFileChange, ensuring
+   * a single unified event pipeline with no parallel chokidar bindings.
    *
    * Uses chokidar's built-in debouncing through `awaitWriteFinish` to handle
    * rapid file changes efficiently.
    */
   async createWatcherSubscription() {
-    if (!this.watcher) {
-      const processorPaths = [];
-      for (const processor of this.appConfig.processors.values()) {
-        const watchConfig = processor.getWatchConfig();
-        if (!watchConfig) continue;
-        processorPaths.push(...watchConfig.paths);
-      }
-      if (fileSystem.exists(this.appConfig.absolutePaths.pagesDir)) {
-        processorPaths.push(this.appConfig.absolutePaths.pagesDir);
-      }
-      if (fileSystem.exists(this.appConfig.absolutePaths.publicDir)) {
-        processorPaths.push(this.appConfig.absolutePaths.publicDir);
-      }
-      if (this.appConfig.additionalWatchPaths.length) {
-        processorPaths.push(...this.appConfig.additionalWatchPaths);
-      }
-      this.watcher = chokidar.watch(processorPaths, {
-        ignoreInitial: true,
-        ignorePermissionErrors: true,
-        awaitWriteFinish: {
-          stabilityThreshold: 50,
-          pollInterval: 50
-        }
-      });
+    if (this.watcher) {
+      return this.watcher;
     }
+    const processorPaths = [];
     for (const processor of this.appConfig.processors.values()) {
       const watchConfig = processor.getWatchConfig();
       if (!watchConfig) continue;
-      const { extensions = [], onCreate, onChange, onDelete, onError } = watchConfig;
-      if (onCreate) this.watcher.on("add", (path2) => this.shouldProcess(path2, extensions, onCreate));
-      if (onChange) this.watcher.on("change", (path2) => this.shouldProcess(path2, extensions, onChange));
-      if (onDelete) this.watcher.on("unlink", (path2) => this.shouldProcess(path2, extensions, onDelete));
-      if (onError) this.watcher.on("error", onError);
+      processorPaths.push(...watchConfig.paths);
+    }
+    if (fileSystem.exists(this.appConfig.absolutePaths.includesDir)) {
+      processorPaths.push(this.appConfig.absolutePaths.includesDir);
+    }
+    if (fileSystem.exists(this.appConfig.absolutePaths.srcDir)) {
+      processorPaths.push(this.appConfig.absolutePaths.srcDir);
+    }
+    if (fileSystem.exists(this.appConfig.absolutePaths.pagesDir)) {
+      processorPaths.push(this.appConfig.absolutePaths.pagesDir);
+    }
+    if (fileSystem.exists(this.appConfig.absolutePaths.publicDir)) {
+      processorPaths.push(this.appConfig.absolutePaths.publicDir);
+    }
+    if (this.appConfig.additionalWatchPaths.length) {
+      processorPaths.push(...this.appConfig.additionalWatchPaths);
+    }
+    this.watcher = chokidar.watch(processorPaths, {
+      ignoreInitial: true,
+      ignorePermissionErrors: true,
+      awaitWriteFinish: {
+        stabilityThreshold: 50,
+        pollInterval: 50
+      }
+    });
+    this.watcher.on("change", (p) => this.enqueueChange(() => this.handleFileChange(p, "change"))).on("add", (p) => this.enqueueChange(() => this.handleFileChange(p, "add"))).on("addDir", (p) => this.enqueueChange(() => this.triggerRouterRefresh(p))).on("unlink", (p) => this.enqueueChange(() => this.handleFileChange(p, "unlink"))).on("unlinkDir", (p) => this.enqueueChange(() => this.triggerRouterRefresh(p))).on("error", (error) => this.handleError(error));
+    for (const processor of this.appConfig.processors.values()) {
+      const watchConfig = processor.getWatchConfig();
+      if (watchConfig?.onError) {
+        this.watcher.on("error", watchConfig.onError);
+      }
     }
-    this.watcher.add(this.appConfig.absolutePaths.srcDir);
-    this.watcher.on("change", (path2) => this.handleFileChange(path2)).on("add", (path2) => {
-      this.handleFileChange(path2);
-      this.triggerRouterRefresh(path2);
-    }).on("addDir", (path2) => this.triggerRouterRefresh(path2)).on("unlink", (path2) => this.triggerRouterRefresh(path2)).on("unlinkDir", (path2) => this.triggerRouterRefresh(path2)).on("error", (error) => this.handleError(error));
     return this.watcher;
   }
 }

package/src/watchers/project-watcher.test-helpers.d.ts

@@ -1,4 +1,4 @@
-import type { IHmrManager } from '../internal-types';
-import type { ClientBridge } from '../adapters/bun/client-bridge';
+import type { IHmrManager } from '../types/internal-types.js';
+import type { ClientBridge } from '../adapters/bun/client-bridge.js';
 export declare const createMockHmrManager: () => IHmrManager;
 export declare const createMockBridge: () => ClientBridge;

package/src/watchers/project-watcher.test-helpers.js

@@ -9,24 +9,24 @@ const createMockHmrManager = () => ({
   setPlugins: vi.fn(() => {
   }),
   registerEntrypoint: vi.fn(async () => ""),
-  registerSpecifierMap: vi.fn(() => {
-  }),
+  registerScriptEntrypoint: vi.fn(async () => ""),
   registerStrategy: vi.fn(() => {
   }),
   isEnabled: vi.fn(() => true),
-  canHandleFileChange: vi.fn(() => true),
   getOutputUrl: vi.fn(() => void 0),
   getWatchedFiles: vi.fn(() => /* @__PURE__ */ new Map()),
-  getSpecifierMap: vi.fn(() => /* @__PURE__ */ new Map()),
   getDistDir: vi.fn(() => ""),
   getPlugins: vi.fn(() => []),
   getDefaultContext: vi.fn(() => ({
     getWatchedFiles: () => /* @__PURE__ */ new Map(),
-    getSpecifierMap: () => /* @__PURE__ */ new Map(),
     getDistDir: () => "",
     getPlugins: () => [],
     getSrcDir: () => "",
-    getLayoutsDir: () => ""
+    getLayoutsDir: () => "",
+    getPagesDir: () => "",
+    getBuildExecutor: () => ({ build: vi.fn(async () => ({ success: true, logs: [], outputs: [] })) }),
+    getBrowserBundleService: () => ({ bundle: vi.fn(async () => ({ success: true, logs: [], outputs: [] })) }),
+    importServerModule: vi.fn(async () => ({}))
   }))
 });
 const createMockBridge = () => ({