@ecopages/core 0.2.0-beta.4 → 0.2.0-beta.41

package/src/services/invalidation/development-invalidation.service.js

@@ -1,190 +1,254 @@
-import path from "node:path";
-import { getAppServerInvalidationState } from "../runtime-state/server-invalidation-state.service.js";
-class DevelopmentInvalidationService {
-  appConfig;
-  constructor(appConfig) {
-    this.appConfig = appConfig;
-  }
-  /**
-   * Returns the current app-owned server-module invalidation version.
-   */
-  getServerModuleInvalidationVersion() {
-    return getAppServerInvalidationState(this.appConfig).getServerInvalidationVersion();
-  }
-  /**
-   * Invalidates the app-owned server-module graph.
-   */
-  invalidateServerModules(changedFiles) {
-    getAppServerInvalidationState(this.appConfig).invalidateServerModules(changedFiles);
-    this.appConfig.runtime?.appModuleLoader?.invalidateDevelopmentGraph();
-  }
-  /**
-   * Resets runtime-owned graph state and invalidates server modules.
-   */
-  resetRuntimeState(changedFiles) {
-    const serverInvalidationState = getAppServerInvalidationState(this.appConfig);
-    serverInvalidationState.invalidateServerModules(changedFiles);
-    serverInvalidationState.reset();
-  }
-  /**
-   * Classifies one changed file into an explicit framework invalidation plan.
-   */
-  planFileChange(filePath) {
-    if (this.isPublicDirFile(filePath)) {
-      return {
-        category: "public-asset",
-        invalidateServerModules: false,
-        refreshRoutes: false,
-        reloadBrowser: true,
-        delegateToHmr: false,
-        processorHandledAsset: false
-      };
+import path from 'node:path';
+import { getAppServerInvalidationState } from '../runtime-state/server-invalidation-state.service.js';
+import { appLogger } from '../../global/app-logger.js';
+/**
+ * Framework-owned development invalidation service.
+ *
+ * @remarks
+ * This service centralizes two responsibilities:
+ * - file-change classification for watcher behavior
+ * - app-owned server-module invalidation versioning backed by the dev graph
+ *
+ * Hosts and watchers should ask this service what a file change means instead
+ * of deciding invalidation semantics inline.
+ */
+export class DevelopmentInvalidationService {
+    appConfig;
+    constructor(appConfig) {
+        this.appConfig = appConfig;
     }
-    if (this.matchesAdditionalWatchPaths(filePath)) {
-      return {
-        category: "additional-watch",
-        invalidateServerModules: false,
-        refreshRoutes: false,
-        reloadBrowser: true,
-        delegateToHmr: false,
-        processorHandledAsset: false
-      };
+    /**
+     * Returns the current app-owned server-module invalidation version.
+     */
+    getServerModuleInvalidationVersion() {
+        return getAppServerInvalidationState(this.appConfig).getServerInvalidationVersion();
     }
-    if (this.isIncludeSourceFile(filePath)) {
-      return {
-        category: "include-source",
-        invalidateServerModules: true,
-        refreshRoutes: false,
-        reloadBrowser: true,
-        delegateToHmr: false,
-        processorHandledAsset: false
-      };
+    /**
+     * Invalidates the app-owned server-module graph.
+     */
+    invalidateServerModules(changedFiles) {
+        getAppServerInvalidationState(this.appConfig).invalidateServerModules(changedFiles);
+        this.appConfig.runtime?.appModuleLoader?.invalidateDevelopmentGraph();
     }
-    if (this.isRouteSourceFile(filePath)) {
-      return {
-        category: "route-source",
-        invalidateServerModules: true,
-        refreshRoutes: true,
-        reloadBrowser: false,
-        delegateToHmr: true,
-        processorHandledAsset: false
-      };
+    /**
+     * Registers an integration-owned handler for registered script entrypoint edits.
+     */
+    registerRegisteredScriptEntrypointChangeHandler(handler) {
+        const runtime = this.appConfig.runtime ?? {};
+        this.appConfig.runtime = runtime;
+        runtime.registeredScriptEntrypointChangeHandlers ??= [];
+        runtime.registeredScriptEntrypointChangeHandlers.push(handler);
     }
-    if (this.isProcessorOwnedAsset(filePath)) {
-      return {
-        category: "processor-owned-asset",
-        invalidateServerModules: false,
-        refreshRoutes: false,
-        reloadBrowser: false,
-        delegateToHmr: false,
-        processorHandledAsset: true
-      };
+    /**
+     * Notifies integration handlers that a registered script entrypoint changed.
+     */
+    async notifyRegisteredScriptEntrypointChange(filePath) {
+        const handlers = this.appConfig.runtime?.registeredScriptEntrypointChangeHandlers ?? [];
+        for (const handler of handlers) {
+            try {
+                await handler(filePath);
+            }
+            catch (error) {
+                appLogger.error(`Failed to handle registered script entrypoint change for ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
     }
-    if (this.isServerModuleSourceFile(filePath)) {
-      return {
-        category: "server-source",
-        invalidateServerModules: true,
-        refreshRoutes: false,
-        reloadBrowser: false,
-        delegateToHmr: true,
-        processorHandledAsset: false
-      };
+    /**
+     * Resets runtime-owned graph state and invalidates server modules.
+     */
+    resetRuntimeState(changedFiles) {
+        const serverInvalidationState = getAppServerInvalidationState(this.appConfig);
+        serverInvalidationState.invalidateServerModules(changedFiles);
+        serverInvalidationState.reset();
     }
-    return {
-      category: "other",
-      invalidateServerModules: false,
-      refreshRoutes: false,
-      reloadBrowser: false,
-      delegateToHmr: true,
-      processorHandledAsset: false
-    };
-  }
-  /**
-   * Returns whether the file lives under the public directory.
-   */
-  isPublicDirFile(filePath) {
-    return path.resolve(filePath).startsWith(this.appConfig.absolutePaths.publicDir);
-  }
-  /**
-   * Returns whether the file matches `additionalWatchPaths`.
-   */
-  matchesAdditionalWatchPaths(filePath) {
-    const normalizedPath = path.resolve(filePath);
-    const patterns = this.appConfig.additionalWatchPaths;
-    if (!patterns.length) return false;
-    for (const pattern of patterns) {
-      if (pattern.includes("*")) {
-        const ext = pattern.replace(/\*\*?\/\*/, "");
-        if (normalizedPath.endsWith(ext)) return true;
-      } else if (normalizedPath.endsWith(pattern) || normalizedPath === path.resolve(pattern)) {
-        return true;
-      }
+    /**
+     * Classifies one changed file into an explicit framework invalidation plan.
+     */
+    planFileChange(filePath) {
+        if (this.isPublicDirFile(filePath)) {
+            return {
+                category: 'public-asset',
+                invalidateServerModules: false,
+                refreshRoutes: false,
+                reloadBrowser: true,
+                delegateToHmr: false,
+                processorHandledAsset: false,
+            };
+        }
+        if (this.matchesAdditionalWatchPaths(filePath)) {
+            return {
+                category: 'additional-watch',
+                invalidateServerModules: false,
+                refreshRoutes: false,
+                reloadBrowser: true,
+                delegateToHmr: false,
+                processorHandledAsset: false,
+            };
+        }
+        if (this.isIncludeSourceFile(filePath)) {
+            return {
+                category: 'include-source',
+                invalidateServerModules: true,
+                refreshRoutes: false,
+                reloadBrowser: false,
+                delegateToHmr: true,
+                processorHandledAsset: false,
+            };
+        }
+        if (this.isExplicitServerViewFile(filePath)) {
+            return {
+                category: 'explicit-server-view',
+                invalidateServerModules: true,
+                refreshRoutes: false,
+                reloadBrowser: false,
+                delegateToHmr: true,
+                processorHandledAsset: false,
+            };
+        }
+        if (this.isRouteSourceFile(filePath)) {
+            return {
+                category: 'route-source',
+                invalidateServerModules: true,
+                refreshRoutes: true,
+                reloadBrowser: false,
+                delegateToHmr: true,
+                processorHandledAsset: false,
+            };
+        }
+        if (this.isProcessorOwnedAsset(filePath)) {
+            return {
+                category: 'processor-owned-asset',
+                invalidateServerModules: false,
+                refreshRoutes: false,
+                reloadBrowser: false,
+                delegateToHmr: false,
+                processorHandledAsset: true,
+            };
+        }
+        if (this.isServerModuleSourceFile(filePath)) {
+            return {
+                category: 'server-source',
+                invalidateServerModules: true,
+                refreshRoutes: false,
+                reloadBrowser: false,
+                delegateToHmr: true,
+                processorHandledAsset: false,
+            };
+        }
+        return {
+            category: 'other',
+            invalidateServerModules: false,
+            refreshRoutes: false,
+            reloadBrowser: false,
+            delegateToHmr: true,
+            processorHandledAsset: false,
+        };
     }
-    return false;
-  }
-  /**
-   * Returns whether the file is a route source file.
-   */
-  isRouteSourceFile(filePath) {
-    const resolvedPath = path.resolve(filePath);
-    if (!resolvedPath.startsWith(this.appConfig.absolutePaths.pagesDir)) {
-      return false;
+    /**
+     * Returns whether the file lives under the public directory.
+     */
+    isPublicDirFile(filePath) {
+        return path.resolve(filePath).startsWith(this.appConfig.absolutePaths.publicDir);
     }
-    if (this.appConfig.templatesExt.some((extension) => resolvedPath.endsWith(extension))) {
-      return true;
+    /**
+     * Returns whether the file matches `additionalWatchPaths`.
+     */
+    matchesAdditionalWatchPaths(filePath) {
+        const normalizedPath = path.resolve(filePath);
+        const patterns = this.appConfig.additionalWatchPaths;
+        if (!patterns.length)
+            return false;
+        for (const pattern of patterns) {
+            if (pattern.includes('*')) {
+                const ext = pattern.replace(/\*\*?\/\*/, '');
+                if (normalizedPath.endsWith(ext))
+                    return true;
+            }
+            else if (normalizedPath.endsWith(pattern) || normalizedPath === path.resolve(pattern)) {
+                return true;
+            }
+        }
+        return false;
     }
-    return /\.(?:[cm]?ts|[jt]sx?|mdx)$/u.test(resolvedPath);
-  }
-  /**
-   * Returns whether the file is an include/template source file.
-   */
-  isIncludeSourceFile(filePath) {
-    const resolvedPath = path.resolve(filePath);
-    if (!resolvedPath.startsWith(this.appConfig.absolutePaths.includesDir)) {
-      return false;
+    /**
+     * Returns whether the file is a route source file.
+     */
+    isRouteSourceFile(filePath) {
+        const resolvedPath = path.resolve(filePath);
+        if (!resolvedPath.startsWith(this.appConfig.absolutePaths.pagesDir)) {
+            return false;
+        }
+        if (this.appConfig.templatesExt.some((extension) => resolvedPath.endsWith(extension))) {
+            return true;
+        }
+        return /\.(?:[cm]?ts|[jt]sx?|mdx)$/u.test(resolvedPath);
     }
-    if (this.appConfig.templatesExt.some((extension) => resolvedPath.endsWith(extension))) {
-      return true;
+    /**
+     * Returns whether the file is an include/template source file.
+     */
+    isIncludeSourceFile(filePath) {
+        const resolvedPath = path.resolve(filePath);
+        if (!resolvedPath.startsWith(this.appConfig.absolutePaths.includesDir)) {
+            return false;
+        }
+        if (this.appConfig.templatesExt.some((extension) => resolvedPath.endsWith(extension))) {
+            return true;
+        }
+        return /\.(?:[cm]?ts|[jt]sx?|mdx)$/u.test(resolvedPath);
     }
-    return /\.(?:[cm]?ts|[jt]sx?|mdx)$/u.test(resolvedPath);
-  }
-  /**
-   * Returns whether the file is a server-executed source module outside the
-   * special route/include buckets.
-   */
-  isServerModuleSourceFile(filePath) {
-    const resolvedPath = path.resolve(filePath);
-    if (!resolvedPath.startsWith(this.appConfig.absolutePaths.srcDir)) {
-      return false;
+    /**
+     * Returns whether the file is an explicit server-rendered view module.
+     *
+     * @remarks
+     * These modules are typically registered through `renderServerModule` in
+     * `app.ts` rather than the filesystem router. They need a full browser reload
+     * because their HTML is produced on the server, not through client HMR entrypoints.
+     */
+    isExplicitServerViewFile(filePath) {
+        const resolvedPath = path.resolve(filePath);
+        const viewsDir = path.join(this.appConfig.absolutePaths.srcDir, 'views');
+        if (resolvedPath !== viewsDir && !resolvedPath.startsWith(`${viewsDir}${path.sep}`)) {
+            return false;
+        }
+        if (this.appConfig.templatesExt.some((extension) => resolvedPath.endsWith(extension))) {
+            return true;
+        }
+        return /\.(?:[cm]?ts|[jt]sx?|mdx)$/u.test(resolvedPath);
     }
-    if (this.appConfig.templatesExt.some((extension) => resolvedPath.endsWith(extension))) {
-      return true;
+    /**
+     * Returns whether the file is a server-executed source module outside the
+     * special route/include buckets.
+     */
+    isServerModuleSourceFile(filePath) {
+        const resolvedPath = path.resolve(filePath);
+        if (!resolvedPath.startsWith(this.appConfig.absolutePaths.srcDir)) {
+            return false;
+        }
+        if (this.appConfig.templatesExt.some((extension) => resolvedPath.endsWith(extension))) {
+            return true;
+        }
+        return /\.(?:[cm]?ts|[jt]sx?|mdx)$/u.test(resolvedPath);
     }
-    return /\.(?:[cm]?ts|[jt]sx?|mdx)$/u.test(resolvedPath);
-  }
-  /**
-   * Returns whether a processor owns the changed file as an asset input.
-   */
-  isProcessorOwnedAsset(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;
-      }
+    /**
+     * Returns whether a processor owns the changed file as an asset input.
+     *
+     * @remarks
+     * Watch config drives processor notifications only. Asset ownership requires
+     * declared capabilities so dependency-only watches (for example content
+     * collection MDX scans) do not skip server invalidation and HMR.
+     */
+    isProcessorOwnedAsset(filePath) {
+        for (const processor of this.appConfig.processors.values()) {
+            const capabilities = processor.getAssetCapabilities?.() ?? [];
+            if (capabilities.length === 0) {
+                continue;
+            }
+            const matchesConfiguredAsset = typeof processor.matchesFileFilter !== 'function' || processor.matchesFileFilter(filePath);
+            if (matchesConfiguredAsset &&
+                capabilities.some((capability) => processor.canProcessAsset?.(capability.kind, filePath))) {
+                return true;
+            }
+        }
+        return false;
     }
-    return false;
-  }
 }
-export {
-  DevelopmentInvalidationService
-};

package/src/services/module-loading/README.md

@@ -0,0 +1,52 @@
+# Module Loading
+
+Server-side source loading for framework-owned page modules, includes, and related templates.
+
+## Import stack
+
+```
+Call site (route scan, renderer, SSG, API)
+  └─ AppModuleLoader.importModule()          app-server-module-transpiler.service.ts
+       ├─ merges server build plugins + JSX ownership plugins
+       ├─ resolves route-module BuildExecutor
+       └─ PageModuleImportService.importModule()
+            ├─ dev + host loader → host runtime (Node only, when configured)
+            ├─ production disk cache → route-module build cache
+            ├─ unified pages graph → prebuilt chunk import (production only)
+            └─ Rolldown per-page build → dynamic import of transpiled output
+```
+
+`ServerModuleTranspiler` is a thin wrapper that injects `rootDir` and optional default plugins into the same `PageModuleImportService` path. App code should prefer `getAppModuleLoader(appConfig)` or `getAppServerModuleTranspiler(appConfig)`.
+
+## Host vs app ownership
+
+| Path                    | When                                                                                         |
+| ----------------------- | -------------------------------------------------------------------------------------------- |
+| Host loader             | `appConfig.runtime.hostModuleLoader` set (Vite host) and file supports direct source loading |
+| Ecopages build pipeline | Framework-owned template files under `pages/`, `includes/`, etc.                             |
+
+`shouldAppUseHostModuleLoader()` encodes the directory + extension rules. Bun always uses the build pipeline today.
+
+## Caching layers
+
+1. **In-memory promise cache** (`PageModuleImportService.importCache`) — keyed by runtime, file path, content-derived reuse identity (`createRouteModuleReuseIdentity`), and source hash. Cleared by `invalidateDevelopmentGraph()`.
+2. **Disk transpile cache** (`.eco/.server-modules/.build-cache.json`) — production and stable development graphs when dependency hashes match. Manifest field `corePackageVersion` invalidates entries when the framework package changes.
+3. **Unified graph manifest** — production static export fast path only; see build layer docs.
+
+Development `?update=` query params use `sourceHash` plus a per-service import generation counter so Node and Bun bust ESM module cache after `invalidateDevelopmentGraph()` without a process-wide invalidation version in reuse keys.
+
+## Files
+
+| File                                      | Role                                                      |
+| ----------------------------------------- | --------------------------------------------------------- |
+| `page-module-import.service.ts`           | Core import/cache/build orchestration                     |
+| `route-module-build-manifest.ts`          | Content-derived reuse identity and disk cache manifest    |
+| `app-module-loader.service.ts`            | App-facing loader interface                               |
+| `app-server-module-transpiler.service.ts` | Factory for app-scoped loader + transpiler                |
+| `server-module-transpiler.service.ts`     | Injectable transpiler boundary for tests and bootstrap    |
+| `host-module-loader-registry.ts`          | Process-global host loader fallback for embedded runtimes |
+| `source-module-support.ts`                | Extension allowlist for host direct loading               |
+
+## Development invalidation
+
+`DevelopmentInvalidationService.invalidateServerModules()` calls `appModuleLoader.invalidateDevelopmentGraph()`, which clears the in-memory import cache, bumps the per-service dev import generation used only for `?update=` URLs, and clears dependency-hash memoization. Route-module disk reuse stays content-derived: unchanged source and dependency hashes keep their entries until the edited module or its graph changes.

package/src/services/module-loading/app-module-loader.service.js

@@ -0,0 +1 @@
+export {};

package/src/services/module-loading/app-server-module-transpiler.service.d.ts

@@ -5,6 +5,14 @@ import { ServerModuleTranspiler } from './server-module-transpiler.service.js';
 export declare function shouldAppUseHostModuleLoader(appConfig: EcoPagesAppConfig, filePath: string): boolean;
 export declare function getAppHostModuleLoader(appConfig: EcoPagesAppConfig): SourceModuleLoader | undefined;
 export declare function setAppHostModuleLoader(appConfig: EcoPagesAppConfig, hostModuleLoader?: SourceModuleLoader): void;
+/**
+ * Creates the app module loader that imports route modules through the build pipeline.
+ *
+ * @remarks
+ * Caller `plugins` are treated as contributions only.
+ * {@link PageModuleImportService} assembles the complete server request via
+ * {@link createServerBuildRequest}; this loader does not merge app plugins.
+ */
 export declare function createAppModuleLoader(appConfig: EcoPagesAppConfig): AppModuleLoader;
 export declare function getAppModuleLoader(appConfig: EcoPagesAppConfig): AppModuleLoader;
 export declare function setAppModuleLoader(appConfig: EcoPagesAppConfig, appModuleLoader: AppModuleLoader): void;