@ecopages/core 0.2.0-beta.2 → 0.2.0-beta.21

package/src/static-site-generator/static-site-generator.js

@@ -1,8 +1,14 @@
 import path from "node:path";
+import { availableParallelism } from "node:os";
 import { appLogger } from "../global/app-logger.js";
 import { fileSystem } from "@ecopages/file-system";
-import { PathUtils } from "../utils/path-utils.module.js";
 import { prepareExplicitStaticRender } from "../adapters/shared/explicit-static-render-preparation.js";
+import { createRouteModuleStaticRenderCacheContext } from "./static-build-invalidation.js";
+import {
+  getServerModuleBuildCacheOutdir,
+  getSharedRouteModuleBuildCache
+} from "../services/module-loading/route-module-build-cache-registry.js";
+import { ensurePagesUnifiedGraphBuilt, shouldBuildPagesUnifiedGraph } from "../build/pages-unified-graph-build.js";
 const STATIC_SITE_GENERATOR_ERRORS = {
   ROUTE_RENDERER_FACTORY_REQUIRED: "RouteRendererFactory is required for render strategy",
   unsupportedBodyType: (bodyType) => `Unsupported body type for static generation: ${bodyType}`,
@@ -10,50 +16,51 @@ const STATIC_SITE_GENERATOR_ERRORS = {
   noRendererForIntegration: (integrationName) => `No renderer found for integration: ${integrationName}`,
   dynamicRouteRequiresStaticPaths: (routePath) => `Dynamic route ${routePath} requires staticPaths to be defined on the view.`
 };
+function resolveStaticPageConcurrency() {
+  return Math.max(1, availableParallelism() - 1);
+}
+async function runWithConcurrency(items, concurrency, worker) {
+  if (items.length === 0) {
+    return;
+  }
+  const limit = Math.max(1, concurrency);
+  let nextIndex = 0;
+  const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (nextIndex < items.length) {
+      const currentIndex = nextIndex++;
+      await worker(items[currentIndex]);
+    }
+  });
+  await Promise.all(runners);
+}
 class StaticSiteGenerator {
   appConfig;
+  routeModuleBuildCacheOverride;
+  staticRenderCacheContext;
+  forceFullStaticGeneration = false;
   /**
    * Creates the static-site generator for one app config.
    */
-  constructor({ appConfig }) {
+  constructor({
+    appConfig,
+    routeModuleBuildCache
+  }) {
     this.appConfig = appConfig;
+    this.routeModuleBuildCacheOverride = routeModuleBuildCache;
+    this.staticRenderCacheContext = createRouteModuleStaticRenderCacheContext(appConfig);
+  }
+  getRouteModuleBuildCache() {
+    return this.routeModuleBuildCacheOverride ?? getSharedRouteModuleBuildCache(getServerModuleBuildCacheOutdir(this.appConfig), this.appConfig);
   }
   getExportDir() {
     return this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, this.appConfig.distDir);
   }
-  /**
-   * Logs the standardized warning emitted when a dynamic-cache page is skipped.
-   */
-  warnDynamicPageSkipped(filePath) {
-    appLogger.warn(
-      "Pages with cache: 'dynamic' are not supported in static generation or preview, so they will be skipped\n",
-      `\u27A4 ${filePath}`
-    );
-  }
-  /**
-   * Determines whether one filesystem-discovered page should be excluded from
-   * static generation.
-   */
   async shouldSkipStaticPageFile(filePath, routeRendererFactory) {
-    const module = await routeRendererFactory.getPageRenderer(filePath).loadPageModule(filePath, {
-      cacheScope: "static-page-probe"
-    });
-    if (module.default?.cache !== "dynamic") {
-      return false;
-    }
-    this.warnDynamicPageSkipped(filePath);
-    return true;
+    const module = await routeRendererFactory.getPageRenderer(filePath).loadPageModule(filePath);
+    return module.default?.cache === "dynamic";
   }
-  /**
-   * Determines whether one explicit static route view should be excluded from
-   * static generation.
-   */
-  shouldSkipStaticView(routePath, view) {
-    if (view.cache !== "dynamic") {
-      return false;
-    }
-    this.warnDynamicPageSkipped(routePath);
-    return true;
+  shouldSkipStaticView(_routePath, view) {
+    return view.cache === "dynamic";
   }
   /**
    * Writes the robots.txt file declared by the app config.
@@ -100,29 +107,56 @@ class StaticSiteGenerator {
     fileSystem.write(outputPath, contents);
     return outputPath;
   }
-  getStaticBuildStrategy(filePath) {
-    const ext = PathUtils.getEcoTemplateExtension(filePath);
-    const integration = this.appConfig.integrations.find((plugin) => plugin.extensions.includes(ext));
-    return integration?.staticBuildStep || "render";
+  async writeStaticPageArtifact(options) {
+    options.activeStaticPathnames?.add(options.pathname);
+    const directories = options.directories ?? this.getDirectories([options.pathname]);
+    const renderedOutputPath = this.getOutputPath(options.pathname, directories);
+    const routeModuleBuildCache = this.getRouteModuleBuildCache();
+    if (options.reuseRenderedOutput !== false && options.sourceFile && routeModuleBuildCache.canReuseStaticRender({
+      sourceFile: options.sourceFile,
+      pathname: options.pathname,
+      renderedOutputPath,
+      context: this.staticRenderCacheContext,
+      force: this.forceFullStaticGeneration
+    })) {
+      appLogger.debug(`Skipped unchanged static page: ${options.debugLabel ?? options.pathname}`);
+      return;
+    }
+    const contents = await options.createContents();
+    if (contents === null) {
+      return;
+    }
+    const outputPath = this.writeStaticOutput(options.pathname, contents, directories);
+    if (options.sourceFile) {
+      routeModuleBuildCache.recordStaticRender({
+        filePath: options.sourceFile,
+        pathname: options.pathname,
+        sourceHash: fileSystem.hash(options.sourceFile),
+        renderedOutputPath: outputPath,
+        context: this.staticRenderCacheContext
+      });
+    }
   }
-  async createFilesystemStaticContents(route, baseUrl, routeRendererFactory) {
+  pruneStaleStaticOutputs(activeStaticPathnames) {
+    const removedOutputPaths = this.getRouteModuleBuildCache().pruneStaleRenderedOutputs(activeStaticPathnames);
+    for (const outputPath of removedOutputPaths) {
+      const resolvedOutputPath = path.isAbsolute(outputPath) ? outputPath : path.resolve(outputPath);
+      if (fileSystem.exists(resolvedOutputPath)) {
+        fileSystem.remove(resolvedOutputPath);
+        appLogger.debug(`Removed stale static output: ${resolvedOutputPath}`);
+      }
+    }
+  }
+  async createFilesystemStaticContents(route, _baseUrl, routeRendererFactory, skipped) {
     const {
       templateRoute: { filePath },
       params
     } = route;
-    if (this.getStaticBuildStrategy(filePath) === "fetch") {
-      const fetchUrl = this.resolveStaticFetchUrl(route.requestUrl, baseUrl);
-      const response = await fetch(fetchUrl);
-      if (!response.ok) {
-        appLogger.error(`Failed to fetch ${fetchUrl}. Status: ${response.status}`);
-        return null;
-      }
-      return response.text();
-    }
     if (!routeRendererFactory) {
       throw new Error(STATIC_SITE_GENERATOR_ERRORS.ROUTE_RENDERER_FACTORY_REQUIRED);
     }
     if (await this.shouldSkipStaticPageFile(filePath, routeRendererFactory)) {
+      skipped?.push(filePath);
       return null;
     }
     const renderer = routeRendererFactory.getPageRenderer(filePath);
@@ -143,42 +177,51 @@ class StaticSiteGenerator {
    * Generates static output for all filesystem-discovered routes.
    *
    * @remarks
-   * Routes whose integrations opt into fetch-based static builds are rendered by
-   * issuing a request against the running server origin. Render-strategy routes
-   * go through the normal route renderer directly.
+   * Routes are rendered through the normal route renderer directly.
    */
-  async generateStaticPages(router, baseUrl, routeRendererFactory) {
-    const routes = await router.listStaticGenerationRoutes({ runtimeOrigin: baseUrl });
+  async generateStaticPages(router, baseUrl, routeRendererFactory, skipped, activeStaticPathnames, preloadedRoutes) {
+    const routes = preloadedRoutes ?? await router.listStaticGenerationRoutes({ runtimeOrigin: baseUrl });
     appLogger.debug(
       "Static Pages",
       routes.map((route) => route.requestUrl)
     );
     const directories = this.getDirectories(routes.map((route) => route.requestUrl));
-    for (const route of routes) {
+    await runWithConcurrency(routes, resolveStaticPageConcurrency(), async (route) => {
       try {
-        const contents = await this.createFilesystemStaticContents(route, baseUrl, routeRendererFactory);
-        if (contents === null) {
-          continue;
-        }
-        this.writeStaticOutput(route.pathname, contents, directories);
+        await this.writeStaticPageArtifact({
+          pathname: route.pathname,
+          sourceFile: route.templateRoute.filePath,
+          directories,
+          debugLabel: route.requestUrl,
+          activeStaticPathnames,
+          createContents: () => this.createFilesystemStaticContents(route, baseUrl, routeRendererFactory, skipped)
+        });
       } catch (error) {
         appLogger.error(
           `Error generating static page for ${route.requestUrl}:`,
           error instanceof Error ? error : String(error)
         );
       }
-    }
+    });
   }
-  resolveStaticFetchUrl(route, baseUrl) {
-    if (!route.startsWith("http://") && !route.startsWith("https://")) {
-      return `${baseUrl}${route}`;
+  createStaticExportContext(input) {
+    return {
+      appConfig: this.appConfig,
+      router: input.router,
+      baseUrl: input.baseUrl,
+      routeRendererFactory: input.routeRendererFactory,
+      staticRoutes: input.staticRoutes,
+      force: input.force,
+      preserveExportDirectory: input.preserveExportDirectory
+    };
+  }
+  async invokeStaticExportHook(hook, context) {
+    for (const integration of this.appConfig.integrations) {
+      const handler = integration[hook];
+      if (typeof handler === "function") {
+        await handler.call(integration, context);
+      }
     }
-    const targetUrl = new URL(route);
-    const buildUrl = new URL(baseUrl);
-    buildUrl.pathname = targetUrl.pathname;
-    buildUrl.search = targetUrl.search;
-    buildUrl.hash = targetUrl.hash;
-    return buildUrl.href;
   }
   /**
    * Executes the full static-generation workflow for one app run.
@@ -187,19 +230,71 @@ class StaticSiteGenerator {
     router,
     baseUrl,
     routeRendererFactory,
-    staticRoutes
+    staticRoutes,
+    force = false,
+    preserveExportDirectory = false
   }) {
-    this.generateRobotsTxt();
-    await this.generateStaticPages(router, baseUrl, routeRendererFactory);
-    if (staticRoutes && staticRoutes.length > 0 && routeRendererFactory) {
-      await this.generateExplicitStaticPages(staticRoutes, routeRendererFactory);
+    const skippedDynamicPages = [];
+    const activeStaticPathnames = /* @__PURE__ */ new Set();
+    this.forceFullStaticGeneration = force;
+    this.staticRenderCacheContext = createRouteModuleStaticRenderCacheContext(this.appConfig);
+    if (!force) {
+      this.getRouteModuleBuildCache().ensureIncrementalStaticGenerationContext(this.staticRenderCacheContext);
+    }
+    const routes = await router.listStaticGenerationRoutes({ runtimeOrigin: baseUrl });
+    if (shouldBuildPagesUnifiedGraph()) {
+      await ensurePagesUnifiedGraphBuilt({
+        appConfig: this.appConfig,
+        entryPaths: routes.map((route) => route.templateRoute.filePath),
+        outdir: getServerModuleBuildCacheOutdir(this.appConfig),
+        force
+      });
+    }
+    const staticExportContext = this.createStaticExportContext({
+      router,
+      baseUrl,
+      routeRendererFactory,
+      staticRoutes,
+      force,
+      preserveExportDirectory
+    });
+    await this.invokeStaticExportHook("beforeStaticExport", staticExportContext);
+    try {
+      this.generateRobotsTxt();
+      await this.generateStaticPages(
+        router,
+        baseUrl,
+        routeRendererFactory,
+        skippedDynamicPages,
+        activeStaticPathnames,
+        routes
+      );
+      if (staticRoutes && staticRoutes.length > 0 && routeRendererFactory) {
+        await this.generateExplicitStaticPages(
+          staticRoutes,
+          routeRendererFactory,
+          skippedDynamicPages,
+          activeStaticPathnames
+        );
+      }
+      if (preserveExportDirectory) {
+        this.pruneStaleStaticOutputs(activeStaticPathnames);
+      }
+    } finally {
+      await this.invokeStaticExportHook("afterStaticExport", staticExportContext);
+    }
+    if (skippedDynamicPages.length > 0) {
+      appLogger.debug(
+        `Skipped ${skippedDynamicPages.length} page(s) with cache: 'dynamic' (not supported in static generation)`,
+        skippedDynamicPages
+      );
     }
   }
   /**
    * Generates static pages from explicit static routes registered via app.static().
    * These routes use eco.page views via loader functions for HMR support.
    */
-  async generateExplicitStaticPages(staticRoutes, routeRendererFactory) {
+  async generateExplicitStaticPages(staticRoutes, routeRendererFactory, skipped, activeStaticPathnames) {
     appLogger.debug(
       "Generating explicit static routes",
       staticRoutes.map((r) => r.path)
@@ -209,9 +304,10 @@ class StaticSiteGenerator {
         const mod = await route.loader();
         const view = mod.default;
         if (this.shouldSkipStaticView(route.path, view)) {
+          skipped?.push(route.path);
           continue;
         }
-        await this.generateExplicitStaticRoute(route.path, view, routeRendererFactory);
+        await this.generateExplicitStaticRoute(route.path, view, routeRendererFactory, activeStaticPathnames);
       } catch (error) {
         appLogger.error(
           `Error generating explicit static page for ${route.path}:`,
@@ -220,18 +316,25 @@ class StaticSiteGenerator {
       }
     }
   }
-  async generateExplicitStaticRoute(routePath, view, routeRendererFactory) {
+  resolveExplicitViewSourceFile(view) {
+    const sourceFile = view.config?.__eco?.file;
+    if (!sourceFile) {
+      return void 0;
+    }
+    return path.isAbsolute(sourceFile) ? sourceFile : path.join(this.appConfig.rootDir, sourceFile);
+  }
+  async generateExplicitStaticRoute(routePath, view, routeRendererFactory, activeStaticPathnames) {
     const { renderer, routeEntries } = await this.planExplicitStaticRoute(routePath, view, routeRendererFactory);
+    const sourceFile = this.resolveExplicitViewSourceFile(view);
     for (const { pathname, params } of routeEntries) {
-      const contents = await this.createExplicitStaticContents(
-        routePath,
-        view,
-        params,
-        routeRendererFactory,
-        renderer
-      );
-      const outputPath = this.writeStaticOutput(pathname, contents);
-      appLogger.debug(`Generated static page: ${pathname} -> ${outputPath}`);
+      await this.writeStaticPageArtifact({
+        pathname,
+        sourceFile,
+        debugLabel: pathname,
+        activeStaticPathnames,
+        createContents: () => this.createExplicitStaticContents(routePath, view, params, routeRendererFactory, renderer)
+      });
+      appLogger.debug(`Generated static page: ${pathname}`);
     }
   }
   async planExplicitStaticRoute(routePath, view, routeRendererFactory) {

package/src/types/internal-types.d.ts

@@ -1,6 +1,7 @@
 import type { EcoBuildPlugin } from '../build/build-types.js';
 import type { AppBuildManifest } from '../build/build-manifest.js';
-import type { BuildAdapter, BuildExecutor, BuildOwnership } from '../build/build-adapter.js';
+import type { BuildAdapter, BuildOwnership } from '../build/build-adapter.js';
+import type { BuildRuntime } from '../build/build-runtime.js';
 import type { AnyIntegrationPlugin } from '../plugins/integration-plugin.js';
 import type { Processor } from '../plugins/processor.js';
 import type { EcoSourceTransform } from '../plugins/source-transform.js';
@@ -13,6 +14,9 @@ import type { SourceModuleLoader } from '../services/module-loading/module-loadi
 import type { EntrypointDependencyGraph } from '../services/runtime-state/entrypoint-dependency-graph.service.js';
 import type { ServerInvalidationState } from '../services/runtime-state/server-invalidation-state.service.js';
 import type { ServerModuleTranspiler } from '../services/module-loading/server-module-transpiler.service.js';
+import type { RouteModuleBuildCache } from '../services/module-loading/route-module-build-cache.store.js';
+/** Integration hook for registered `dependencies.scripts` entrypoint changes in dev. */
+export type RegisteredScriptEntrypointChangeHandler = (filePath: string) => void | Promise<void>;
 export interface RobotsPreference {
     /**
      * The user agent
@@ -149,13 +153,23 @@ export type EcoPagesAppConfig = {
         buildOwnership?: BuildOwnership;
         buildAdapter?: BuildAdapter;
         buildManifest?: AppBuildManifest;
-        buildExecutor?: BuildExecutor;
         devGraphService?: DevGraphService;
         entrypointDependencyGraph?: EntrypointDependencyGraph;
         hostModuleLoader?: SourceModuleLoader;
         rendererModuleContext?: unknown;
         serverInvalidationState?: ServerInvalidationState;
         serverModuleTranspiler?: ServerModuleTranspiler;
+        routeModuleBuildCaches?: Map<string, RouteModuleBuildCache>;
+        /** Profile-based build runtime installed by {@link installBuildRuntime}. */
+        buildRuntime?: BuildRuntime;
+        /** Set after {@link setupAppRuntimePlugins} runs processor/integration setup once per process. */
+        runtimeAssetsPrepared?: boolean;
+        /** When `'host'`, the embedded dev server owns browser dev-client bootstrap. */
+        devClientOwner?: 'core' | 'host';
+        /** Integration hooks run when a registered `dependencies.scripts` entrypoint changes. */
+        registeredScriptEntrypointChangeHandlers?: RegisteredScriptEntrypointChangeHandler[];
+        /** @deprecated Prefer {@link devClientOwner}: `'host'`. */
+        delegateBrowserReloadToHost?: boolean;
     };
     /**
      * Experimental features.
@@ -222,11 +236,4 @@ export interface EcoPagesFileSystemServerAdapter<ServerInstanceOptions = unknown
         server: unknown;
     }>;
 }
-export interface ProcessorPlugin {
-    name: string;
-    description?: string;
-    setup(): Promise<void>;
-    process<T = unknown>(input: T): Promise<T>;
-    teardown?(): Promise<void>;
-}
 export type { ClientBridgeEvent, DefaultHmrContext, IHmrManager, IClientBridge } from './public-types.js';