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

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

@@ -1,8 +1,27 @@
 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 { prepareExplicitStaticRender } from "../adapters/shared/http/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/cache/pages-unified-graph-build.js";
+import {
+  clearProductionPageBrowserGraphSession,
+  prebuildProductionPageBrowserGraphs,
+  shouldPrebuildProductionPageBrowserGraphs
+} from "./production-page-browser-graph-prebuild.js";
+import { PageModuleLoaderService } from "../route-renderer/page-loading/page-module-loader.js";
+import { renderSitemap } from "./sitemap.js";
+import { resolveSitemapLocations } from "./sitemap-routes.js";
+import { toEcopagesRouteInfo } from "../utils/ecopages-route-info.js";
+import { normalizePathname } from "../utils/path-pattern.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 +29,53 @@ 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;
+  pageModuleLoader;
   /**
    * 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 pageModule = await routeRendererFactory.getPageRenderer(filePath).loadPageModule(filePath);
+    const Page = pageModule.default;
+    return Page.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.
@@ -73,6 +95,14 @@ class StaticSiteGenerator {
     fileSystem.ensureDir(this.getExportDir());
     fileSystem.write(path.join(this.getExportDir(), "robots.txt"), data);
   }
+  /**
+   * Writes the configured sitemap file to the export directory.
+   */
+  generateSitemap(locations, sitemap) {
+    const fileName = sitemap.fileName ?? "sitemap.xml";
+    fileSystem.ensureDir(this.getExportDir());
+    fileSystem.write(path.join(this.getExportDir(), fileName), renderSitemap(locations));
+  }
   /**
    * Returns whether the input path points at the root directory.
    */
@@ -100,29 +130,126 @@ 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) {
+    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
+    })) {
+      options.activeStaticPathnames?.add(options.pathname);
+      await options.onSuccessfulExport?.();
+      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);
+    options.activeStaticPathnames?.add(options.pathname);
+    if (options.sourceFile) {
+      try {
+        routeModuleBuildCache.recordStaticRender({
+          filePath: options.sourceFile,
+          pathname: options.pathname,
+          sourceHash: fileSystem.hash(options.sourceFile),
+          renderedOutputPath: outputPath,
+          context: this.staticRenderCacheContext
+        });
+      } catch (error) {
+        appLogger.debug(
+          `Failed to record static render cache for ${options.pathname}`,
+          error instanceof Error ? error.message : String(error)
+        );
+      }
+    }
+    await options.onSuccessfulExport?.();
+  }
+  /**
+   * Marks a successfully exported pathname as sitemap-eligible when robots allow indexing.
+   *
+   * @remarks
+   * Fail-closed: metadata resolution errors omit the URL. `robots.index === false`
+   * also omits it. Eligibility is decided during generation, not by reloading modules
+   * after `afterStaticExport`.
+   */
+  async considerSitemapEligibility(input) {
+    if (!input.sitemapEligiblePathnames || !this.appConfig.sitemap?.enabled) {
+      return;
+    }
+    try {
+      const metadata = await input.resolveMetadata();
+      if (metadata.robots?.index === false) {
+        return;
+      }
+      input.sitemapEligiblePathnames.add(normalizePathname(input.pathname));
+    } catch (error) {
+      appLogger.debug(
+        `Sitemap eligibility skipped for ${input.pathname}; metadata resolution failed`,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
   }
-  async createFilesystemStaticContents(route, baseUrl, routeRendererFactory) {
-    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;
+  getPageModuleLoader(baseUrl) {
+    this.pageModuleLoader ??= new PageModuleLoaderService(this.appConfig, baseUrl);
+    return this.pageModuleLoader;
+  }
+  async resolveFilesystemPageMetadata(input) {
+    const loader = this.getPageModuleLoader(input.baseUrl);
+    const pageModule = await loader.resolvePageModule({
+      file: input.filePath,
+      importPageFileFn: (file) => input.routeRendererFactory.getPageRenderer(file).loadPageModule(file)
+    });
+    const { metadata } = await loader.resolvePageData({
+      pageModule,
+      routeOptions: {
+        file: input.filePath,
+        params: input.params
       }
-      return response.text();
+    });
+    return metadata;
+  }
+  async resolveExplicitViewMetadata(input) {
+    if (!input.view.metadata) {
+      return this.appConfig.defaultMetadata;
     }
+    const dynamicMetadata = await input.view.metadata({
+      params: input.params,
+      query: {},
+      props: input.props,
+      appConfig: this.appConfig
+    });
+    return { ...this.appConfig.defaultMetadata, ...dynamicMetadata };
+  }
+  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(input) {
+    const {
+      route: {
+        templateRoute: { filePath },
+        params
+      },
+      routeRendererFactory,
+      skipped
+    } = input;
     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 +270,73 @@ 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(input) {
+    const { router, baseUrl, routeRendererFactory, skipped, activeStaticPathnames, sitemapEligiblePathnames } = input;
+    const routes = input.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,
+          onSuccessfulExport: () => this.considerSitemapEligibility({
+            pathname: route.pathname,
+            sitemapEligiblePathnames,
+            resolveMetadata: () => {
+              if (!routeRendererFactory) {
+                throw new Error(STATIC_SITE_GENERATOR_ERRORS.ROUTE_RENDERER_FACTORY_REQUIRED);
+              }
+              return this.resolveFilesystemPageMetadata({
+                filePath: route.templateRoute.filePath,
+                params: route.params,
+                baseUrl,
+                routeRendererFactory
+              });
+            }
+          }),
+          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,
+      routes: input.routes
+    };
+  }
+  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,31 +345,114 @@ 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();
+    const sitemapEligiblePathnames = this.appConfig.sitemap?.enabled ? /* @__PURE__ */ new Set() : void 0;
+    this.forceFullStaticGeneration = force;
+    this.staticRenderCacheContext = createRouteModuleStaticRenderCacheContext(this.appConfig);
+    this.pageModuleLoader = void 0;
+    if (!force) {
+      this.getRouteModuleBuildCache().ensureIncrementalStaticGenerationContext(this.staticRenderCacheContext);
+    }
+    if (shouldPrebuildProductionPageBrowserGraphs() && force) {
+      clearProductionPageBrowserGraphSession(this.appConfig);
+    }
+    const routes = await router.listStaticGenerationRoutes({ runtimeOrigin: baseUrl });
+    const exportRoutes = routes.map((route) => toEcopagesRouteInfo(route));
+    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,
+      routes: exportRoutes
+    });
+    await this.invokeStaticExportHook("beforeStaticExport", staticExportContext);
+    try {
+      if (shouldPrebuildProductionPageBrowserGraphs() && routeRendererFactory) {
+        await prebuildProductionPageBrowserGraphs(
+          routes.map((route) => route.templateRoute.filePath),
+          routeRendererFactory
+        );
+      }
+      this.generateRobotsTxt();
+      await this.generateStaticPages({
+        router,
+        baseUrl,
+        routeRendererFactory,
+        skipped: skippedDynamicPages,
+        activeStaticPathnames,
+        preloadedRoutes: routes,
+        sitemapEligiblePathnames
+      });
+      if (staticRoutes && staticRoutes.length > 0 && routeRendererFactory) {
+        await this.generateExplicitStaticPages({
+          staticRoutes,
+          routeRendererFactory,
+          skipped: skippedDynamicPages,
+          activeStaticPathnames,
+          sitemapEligiblePathnames
+        });
+      }
+      if (preserveExportDirectory) {
+        this.pruneStaleStaticOutputs(activeStaticPathnames);
+      }
+    } catch (error) {
+      if (shouldPrebuildProductionPageBrowserGraphs()) {
+        clearProductionPageBrowserGraphSession(this.appConfig);
+      }
+      throw error;
+    } finally {
+      await this.invokeStaticExportHook("afterStaticExport", staticExportContext);
+    }
+    if (this.appConfig.sitemap?.enabled && sitemapEligiblePathnames) {
+      const locations = resolveSitemapLocations({
+        eligiblePathnames: [...sitemapEligiblePathnames],
+        sitemap: this.appConfig.sitemap,
+        baseUrl
+      });
+      this.generateSitemap(locations, this.appConfig.sitemap);
+    }
+    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(input) {
     appLogger.debug(
       "Generating explicit static routes",
-      staticRoutes.map((r) => r.path)
+      input.staticRoutes.map((r) => r.path)
     );
-    for (const route of staticRoutes) {
+    for (const route of input.staticRoutes) {
       try {
         const mod = await route.loader();
         const view = mod.default;
         if (this.shouldSkipStaticView(route.path, view)) {
+          input.skipped?.push(route.path);
           continue;
         }
-        await this.generateExplicitStaticRoute(route.path, view, routeRendererFactory);
+        await this.generateExplicitStaticRoute({
+          routePath: route.path,
+          view,
+          routeRendererFactory: input.routeRendererFactory,
+          activeStaticPathnames: input.activeStaticPathnames,
+          sitemapEligiblePathnames: input.sitemapEligiblePathnames
+        });
       } catch (error) {
         appLogger.error(
           `Error generating explicit static page for ${route.path}:`,
@@ -220,46 +461,80 @@ class StaticSiteGenerator {
       }
     }
   }
-  async generateExplicitStaticRoute(routePath, view, routeRendererFactory) {
-    const { renderer, routeEntries } = await this.planExplicitStaticRoute(routePath, view, routeRendererFactory);
-    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}`);
+  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 planExplicitStaticRoute(routePath, view, routeRendererFactory) {
-    const { renderer } = await prepareExplicitStaticRender({
+  async generateExplicitStaticRoute(input) {
+    const { routePath, view, routeRendererFactory, activeStaticPathnames, sitemapEligiblePathnames } = input;
+    const { renderer, routeEntries } = await this.planExplicitStaticRoute({
       routePath,
       view,
+      routeRendererFactory
+    });
+    const sourceFile = this.resolveExplicitViewSourceFile(view);
+    for (const { pathname, params } of routeEntries) {
+      await this.writeStaticPageArtifact({
+        pathname,
+        sourceFile,
+        debugLabel: pathname,
+        activeStaticPathnames,
+        onSuccessfulExport: () => this.considerSitemapEligibility({
+          pathname,
+          sitemapEligiblePathnames,
+          resolveMetadata: async () => {
+            const { props } = await prepareExplicitStaticRender({
+              routePath,
+              view,
+              params,
+              appConfig: this.appConfig,
+              runtimeOrigin: this.appConfig.baseUrl,
+              routeRendererFactory,
+              errors: STATIC_SITE_GENERATOR_ERRORS
+            });
+            return this.resolveExplicitViewMetadata({ view, params, props });
+          }
+        }),
+        createContents: () => this.createExplicitStaticContents({
+          routePath,
+          view,
+          params,
+          routeRendererFactory,
+          renderer
+        })
+      });
+      appLogger.debug(`Generated static page: ${pathname}`);
+    }
+  }
+  async planExplicitStaticRoute(input) {
+    const { renderer } = await prepareExplicitStaticRender({
+      routePath: input.routePath,
+      view: input.view,
       params: {},
       appConfig: this.appConfig,
       runtimeOrigin: this.appConfig.baseUrl,
-      routeRendererFactory,
+      routeRendererFactory: input.routeRendererFactory,
       errors: STATIC_SITE_GENERATOR_ERRORS
     });
     return {
       renderer,
-      routeEntries: await this.listExplicitStaticRouteEntries(routePath, view)
+      routeEntries: await this.listExplicitStaticRouteEntries(input.routePath, input.view)
     };
   }
-  async createExplicitStaticContents(routePath, view, params, routeRendererFactory, renderer) {
+  async createExplicitStaticContents(input) {
     const { props, view: renderableView } = await prepareExplicitStaticRender({
-      routePath,
-      view,
-      params,
+      routePath: input.routePath,
+      view: input.view,
+      params: input.params,
       appConfig: this.appConfig,
       runtimeOrigin: this.appConfig.baseUrl,
-      routeRendererFactory,
+      routeRendererFactory: input.routeRendererFactory,
       errors: STATIC_SITE_GENERATOR_ERRORS
     });
-    const response = await renderer.renderToResponse(renderableView, props, {});
+    const response = await input.renderer.renderToResponse(renderableView, props, {});
     return response.text();
   }
   async listExplicitStaticRouteEntries(routePath, view) {