@ecopages/core 0.2.0-alpha.4 → 0.2.0-alpha.40

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 = () => ({

package/CHANGELOG.md

@@ -1,91 +0,0 @@
-# Changelog
-
-All notable changes to `@ecopages/core` are documented here.
-
-> **Note:** Changelog tracking begins at version `0.2.0`. Changes prior to this release are not recorded here but are available in the git history.
-
-## [UNRELEASED] — TBD
-
-### Features
-
-#### Node.js Runtime Support
-
-- **Node server adapter** — Full HTTP server adapter for Node.js via `packages/core/src/adapters/node/`, including request bridging, route handling, static content serving, and graceful shutdown.
-- **Node static build pipeline** — Static-site build and preview server for Node.js runtime (`ab22f167`, `a47b4da3`, `435dc250`).
-- **Node API handler pipeline** — `define-api-handler` now works cross-runtime; Node adapter wires API handler execution end-to-end (`73e57d87`, `f46aa528`).
-- **Node client bridge** — `NodeClientBridge` with SSE-based HMR stream and heartbeat mechanism for connection health (`3361445f`).
-- **Node HMR manager** — `NodeHmrManager` that mirrors Bun HMR capabilities on the Node runtime.
-- **`createApp` universal factory** — Top-level `createApp` export that selects the correct adapter (Bun or Node) at runtime (`ce691bdf`, `2f1b1109`).
-
-#### Build System
-
-- **`EsbuildBuildAdapter`** — A new build backend backed by esbuild, replacing the Bun-only transpilation path. Includes module resolution routing, plugin registration, and transpilation defaults (`f503e86e`, `94c37d38`, `e4e124a1`).
-- **Build dependency graph** — `BuildDependencyGraph` interface for tracking entrypoints and their asset dependencies, enabling more accurate HMR invalidation (`e7653c9b`).
-- **Build adapter abstraction** — `build-adapter.ts` and `build-types.ts` decouple build and plugin contracts from Bun-specific types (`11b03bcc`).
-
-#### Rendering & Orchestration
-
-- **Boundary rendering policy** — Cross-integration component boundaries are now explicitly enforced (`ec1e4d66`).
-- **Full orchestration mode** — Legacy rendering mode branches removed; the engine always runs in unified orchestration mode (`f652fa0a`).
-- **Extracted render services** — The render pipeline is decomposed into focused services:
-    - `RenderExecutionService`
-    - `HtmlPostProcessingService`
-    - `RenderPreparationService`
-    - `MarkerGraphResolver`
-    - `FileRouteMiddlewarePipeline`
-    - `PageRequestCacheCoordinator`
-    - `PageModuleImportService`
-- **Component render context** — New `ComponentRenderContext` consolidates component-level state during rendering (`eco/component-render-context.ts`).
-- **Worker-tools HTML rewriter fallback** — `html-transformer` adopts `@worker-tools/html-rewriter` as a fallback for non-Bun environments (`54056d4f`).
-
-#### Dependency & Injection
-
-- **Global injector map** — `GlobalInjectorMap` and `LazyInjectorMap` provide structured, testable dependency injection for global and lazy assets (`c3a25072`).
-- **Lazy dependency resolution** — SSR lazy script resolution now uses dedicated utility functions for dependency entry attributes and content generation (`71ce2f4f`).
-- **Dependency entry type refactor** — Unified types for script and stylesheet dependency entries, with improved error messages (`1e02dba6`).
-- **Module dependencies** — New `module-dependencies.ts` tracks explicit module-level asset relationships.
-- **Eco utils extraction** — Shared utilities moved to `eco.utils.ts` to remove runtime metadata fallbacks (`bdc60d50`).
-
-#### API Handlers
-
-- **Unified typed API handler context** — `defineApiHandler` now exposes a fully typed, runtime-agnostic context object. The Bun-specific adapter is slimmed down to a thin wrapper (`2f1b1109`, `08e194b4`).
-- **Portable root runtime API** — Core exposes a portable API surface that avoids runtime escape hatches (`ce691bdf`, `1ec42c02`).
-
-### Refactoring
-
-- **Bun adapter isolation** — Bun-specific types (`serve` options, file reads, env access, argv/hash helpers) are routed through dedicated helpers, making the remaining adapter code portable (`73668f52`, `0c90ced1`, `73fb904a`, `5eb0957b`, `4bdc74a9`, `e9ce163c`, `22f9de4a`, `f7b3d95e`).
-- **Shared server adapter** — Common server adapter logic extracted to `adapters/shared/application-adapter.ts` and `adapters/shared/server-adapter.ts`, shared between Bun and Node adapters (`5a872eda`).
-- **Route assets isolation** — Route-level assets are now isolated per-request, hardening dependency processing (`3fd76a12`).
-- **Shared matcher error constants** — Matcher error strings are now constants shared across test and source (`ff4db106`).
-- **App registration & fetch pipeline** — App creation and request handling consolidated into a single unified pipeline (`86e20a3d`).
-- **Adapter escape hatch surface** trimmed — Public adapter API is narrowed to reduce surface area (`1ec42c02`).
-
-### Bug Fixes
-
-- Fixed invariant checks for route paths with improved error messaging in `AbstractApplicationAdapter` (`9c2a6242`).
-- Fixed dependency import name extraction in `extractEcopagesVirtualImports` (`39bbc472`).
-- Removed an invalid npm export entry that pointed to a non-existent `utils/ecopages-url-resolver` declaration target.
-- Kept source module HMR active when stylesheet processors also watch TSX and JSX files for Tailwind-driven CSS rebuilds.
-- Triggered HMR current-page refreshes instead of fallback reload suppression for processor-watched TSX and JSX changes that are not client entrypoints.
-
-### Tests
-
-- Added node static content server test coverage (`435dc250`).
-- Strengthened HTML transformer mode matrix coverage (`286c1253`).
-- Aligned integration and dependency processing tests to new orchestration model (`7cc73316`).
-- Added `EsbuildBuildAdapter` test suite with 500+ lines (`build-adapter.test.ts`).
-- Added `file-route-middleware-pipeline` tests.
-
-### Documentation
-
-- Updated rendering graph documentation to cover extracted rendering services (`8bfcfd21`).
-- Refreshed server handler and module dependency guidance (`3494f44d`).
-
----
-
-## Migration Notes
-
-- **`createApp`** is now the recommended entrypoint (previously `EcopagesApp`). Import from `@ecopages/core`.
-- **`defineApiHandler`** signature is unchanged but the handler context object now carries explicit runtime-agnostic types. No breaking changes for existing handlers.
-- Bun adapter still works as before; the new Node adapter is additive.
-- The old explicit `renderingMode` config option has been removed — full orchestration is always active.