@ecopages/core 0.2.0-alpha.27 → 0.2.0-alpha.28

package/src/watchers/project-watcher.js

@@ -0,0 +1,275 @@
+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.
+   *
+   * Some editors or save pipelines emit two near-identical filesystem change
+   * notifications for the same file. Ecopages should treat those as one logical
+   * update so HMR and route refresh work are not repeated unnecessarily.
+   */
+  static duplicateChangeWindowMs = 150;
+  appConfig;
+  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);
+  }
+  /**
+   * Uncaches modules in the source directory to ensure fresh imports.
+   * This is necessary for hot module replacement to work correctly.
+   * @private
+   */
+  uncacheModules() {
+    if (typeof require === "undefined") return;
+    const { srcDir, rootDir } = this.appConfig;
+    const regex = new RegExp(`${rootDir}/${srcDir}/.*`);
+    for (const key in require.cache) {
+      if (regex.test(key)) {
+        delete require.cache[key];
+      }
+    }
+  }
+  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
+   */
+  async handlePublicDirFileChange(filePath) {
+    try {
+      const relativePath = path.relative(this.appConfig.absolutePaths.publicDir, filePath);
+      const destPath = path.join(this.appConfig.absolutePaths.distDir, relativePath);
+      if (fileSystem.exists(filePath)) {
+        const destDir = path.dirname(destPath);
+        fileSystem.ensureDir(destDir);
+        await fileSystem.copyFileAsync(filePath, destPath);
+      }
+      this.bridge.reload();
+    } catch (error) {
+      appLogger.error(`Failed to copy public file: ${error instanceof Error ? error.message : String(error)}`);
+      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 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, event = "change") {
+    const filePath = path.resolve(rawPath);
+    const now = Date.now();
+    const lastHandledAt = this.lastHandledChange.get(filePath);
+    if (lastHandledAt !== void 0 && now - lastHandledAt < ProjectWatcher.duplicateChangeWindowMs) {
+      return;
+    }
+    this.lastHandledChange.set(filePath, now);
+    try {
+      const plan = this.invalidationService.planFileChange(filePath);
+      if (plan.category === "public-asset") {
+        await this.handlePublicDirFileChange(filePath);
+        return;
+      }
+      this.uncacheModules();
+      if (plan.invalidateServerModules) {
+        this.invalidationService.invalidateServerModules([filePath]);
+      }
+      if (plan.refreshRoutes) {
+        await this.refreshRouterRoutesCallback();
+      }
+      if (plan.category === "additional-watch") {
+        this.bridge.reload();
+        return;
+      }
+      await this.notifyProcessors(filePath, event);
+      if (plan.category === "include-source") {
+        this.bridge.reload();
+        return;
+      }
+      if (plan.processorHandledAsset) {
+        return;
+      }
+      if (plan.delegateToHmr) {
+        await this.hmrManager.handleFileChange(filePath);
+      }
+    } catch (error) {
+      if (error instanceof Error) {
+        this.bridge.error(error.message);
+        this.handleError(error);
+      }
+    }
+  }
+  /**
+   * 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 this.invalidationService.isPublicDirFile(filePath);
+  }
+  /**
+   * Checks if file path matches any additionalWatchPaths patterns.
+   */
+  matchesAdditionalWatchPaths(filePath) {
+    return this.invalidationService.matchesAdditionalWatchPaths(filePath);
+  }
+  /**
+   * Checks if a file is handled by a processor.
+   * Processors that declare asset capabilities own those file types.
+   * Processors without capabilities fall back to checking watch extensions.
+   */
+  isHandledByProcessor(filePath) {
+    return this.invalidationService.isProcessorOwnedAsset(filePath);
+  }
+  /**
+   * Triggers router refresh for page directory changes.
+   * This ensures the router is updated when pages are added or removed.
+   *
+   * @param {string} path - Path of the changed directory
+   */
+  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();
+    }
+  }
+  /**
+   * Handles and logs errors that occur during file watching.
+   *
+   * @param {unknown} error - The error to handle
+   */
+  handleError(error) {
+    if (error instanceof Error) {
+      this.hmrManager.broadcast({ type: "error", message: error.message });
+    }
+    appLogger.error(`Watcher error: ${error}`);
+  }
+  /**
+   * Creates and configures the file system watcher.
+   * This sets up:
+   * 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) {
+      return 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.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);
+      }
+    }
+    return this.watcher;
+  }
+}
+export {
+  ProjectWatcher
+};

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

@@ -0,0 +1,4 @@
+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

@@ -0,0 +1,52 @@
+import { vi } from "vitest";
+const createMockHmrManager = () => ({
+  handleFileChange: vi.fn(async () => {
+  }),
+  broadcast: vi.fn(() => {
+  }),
+  setEnabled: vi.fn(() => {
+  }),
+  setPlugins: vi.fn(() => {
+  }),
+  registerEntrypoint: vi.fn(async () => ""),
+  registerScriptEntrypoint: vi.fn(async () => ""),
+  registerStrategy: vi.fn(() => {
+  }),
+  isEnabled: vi.fn(() => true),
+  getOutputUrl: vi.fn(() => void 0),
+  getWatchedFiles: vi.fn(() => /* @__PURE__ */ new Map()),
+  getDistDir: vi.fn(() => ""),
+  getPlugins: vi.fn(() => []),
+  getDefaultContext: vi.fn(() => ({
+    getWatchedFiles: () => /* @__PURE__ */ new Map(),
+    getDistDir: () => "",
+    getPlugins: () => [],
+    getSrcDir: () => "",
+    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 = () => ({
+  reload: vi.fn(() => {
+  }),
+  error: vi.fn(() => {
+  }),
+  cssUpdate: vi.fn(() => {
+  }),
+  update: vi.fn(() => {
+  }),
+  subscribe: vi.fn(() => {
+  }),
+  unsubscribe: vi.fn(() => {
+  }),
+  broadcast: vi.fn(() => {
+  }),
+  subscriberCount: 0
+});
+export {
+  createMockBridge,
+  createMockHmrManager
+};

package/src/adapters/abstract/application-adapter.test.ts

@@ -1,172 +0,0 @@
-import assert from 'node:assert/strict';
-import { afterEach, describe, it } from 'vitest';
-import {
-	AbstractApplicationAdapter,
-	type ApplicationAdapterOptions,
-	type RouteHandler,
-	type RouteGroupDefinition,
-} from './application-adapter.ts';
-import type { ApiHandlerContext, ViewLoader } from '../../types/public-types.ts';
-import {
-	setHostModuleLoader,
-	clearHostModuleLoader,
-} from '../../services/module-loading/host-module-loader-registry.ts';
-
-class TestApplicationAdapter extends AbstractApplicationAdapter<ApplicationAdapterOptions, unknown, Request> {
-	public getCliArgsSnapshot() {
-		return this.cliArgs;
-	}
-
-	public getAppModuleLoader() {
-		return this.appConfig.runtime?.appModuleLoader;
-	}
-
-	public getHostModuleLoader() {
-		return this.appConfig.runtime?.hostModuleLoader;
-	}
-
-	get<P extends string, TContext extends ApiHandlerContext<Request, unknown>>(
-		_path: P,
-		_handler: RouteHandler<Request, unknown, TContext>,
-	): this {
-		return this;
-	}
-
-	post<P extends string, TContext extends ApiHandlerContext<Request, unknown>>(
-		_path: P,
-		_handler: RouteHandler<Request, unknown, TContext>,
-	): this {
-		return this;
-	}
-
-	put<P extends string, TContext extends ApiHandlerContext<Request, unknown>>(
-		_path: P,
-		_handler: RouteHandler<Request, unknown, TContext>,
-	): this {
-		return this;
-	}
-
-	delete<P extends string, TContext extends ApiHandlerContext<Request, unknown>>(
-		_path: P,
-		_handler: RouteHandler<Request, unknown, TContext>,
-	): this {
-		return this;
-	}
-
-	patch<P extends string, TContext extends ApiHandlerContext<Request, unknown>>(
-		_path: P,
-		_handler: RouteHandler<Request, unknown, TContext>,
-	): this {
-		return this;
-	}
-
-	options<P extends string, TContext extends ApiHandlerContext<Request, unknown>>(
-		_path: P,
-		_handler: RouteHandler<Request, unknown, TContext>,
-	): this {
-		return this;
-	}
-
-	head<P extends string, TContext extends ApiHandlerContext<Request, unknown>>(
-		_path: P,
-		_handler: RouteHandler<Request, unknown, TContext>,
-	): this {
-		return this;
-	}
-
-	route<P extends string>(_path: P, _method: 'GET', _handler: RouteHandler<Request, unknown>): this {
-		return this;
-	}
-
-	add(): this {
-		return this;
-	}
-
-	group(_prefix: string, _callback: (builder: unknown) => void): this;
-	group(_group: RouteGroupDefinition<Request, unknown>): this;
-	group(): this {
-		return this;
-	}
-
-	override static<P>(_path: string, _loader: ViewLoader<P>): this {
-		return this;
-	}
-
-	protected async initializeServerAdapter(): Promise<void> {
-		return;
-	}
-
-	async fetch(_request: Request): Promise<Response> {
-		return new Response(null, { status: 204 });
-	}
-
-	start(): Promise<void> {
-		return Promise.resolve();
-	}
-}
-
-afterEach(() => {
-	clearHostModuleLoader();
-	delete process.env.NODE_ENV;
-});
-
-describe('application adapter runtime bootstrap', () => {
-	it('derives embedded cli args from explicit runtime options', () => {
-		process.env.NODE_ENV = 'development';
-		const adapter = new TestApplicationAdapter({
-			appConfig: {
-				runtime: {},
-			} as ApplicationAdapterOptions['appConfig'],
-			runtime: {
-				embedded: true,
-			},
-		});
-
-		assert.deepEqual(adapter.getCliArgsSnapshot(), {
-			preview: false,
-			build: false,
-			start: false,
-			dev: true,
-			port: undefined,
-			hostname: undefined,
-			reactFastRefresh: undefined,
-		});
-		assert.equal(adapter.getAppModuleLoader()?.owner, 'bun');
-	});
-
-	it('auto-detects the host module loader in embedded mode from registry', async () => {
-		process.env.NODE_ENV = 'development';
-		let importedId: string | undefined;
-		const filePath = import.meta.filename;
-		setHostModuleLoader(async (id) => {
-			importedId = id;
-			return { id };
-		});
-
-		const adapter = new TestApplicationAdapter({
-			appConfig: {
-				runtime: {},
-			} as ApplicationAdapterOptions['appConfig'],
-			runtime: {
-				embedded: true,
-			},
-		});
-
-		const appModuleLoader = adapter.getAppModuleLoader();
-		const hostModuleLoader = adapter.getHostModuleLoader();
-
-		assert.ok(appModuleLoader);
-		assert.ok(hostModuleLoader);
-		assert.equal(appModuleLoader?.owner, 'host');
-		assert.deepEqual(await hostModuleLoader?.('/virtual:entry'), { id: '/virtual:entry' });
-		assert.deepEqual(
-			await appModuleLoader?.importModule({
-				filePath,
-				rootDir: '/app',
-				outdir: '/app/.eco/.server-modules',
-			}),
-			{ id: importedId },
-		);
-		assert.match(importedId ?? '', /application-adapter\.test\.ts\?update=/);
-	});
-});