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

package/src/services/module-loading/route-module-dependency-hasher.js

@@ -0,0 +1,122 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+class RouteModuleDependencyHasher {
+  memo = /* @__PURE__ */ new Map();
+  hashFile;
+  exists;
+  constructor(dependencies) {
+    this.hashFile = dependencies?.hashFile ?? ((filePath) => fileSystem.hash(filePath));
+    this.exists = dependencies?.exists ?? ((filePath) => fileSystem.exists(filePath));
+  }
+  /**
+   * Returns a memoized content hash for one trackable dependency path.
+   *
+   * @param filePath - Absolute or project-relative source path.
+   * @returns The content hash, or `undefined` when the path is not trackable or missing.
+   */
+  hashDependency(filePath) {
+    const normalizedPath = path.normalize(filePath);
+    if (!isTrackableRouteModuleDependency(normalizedPath)) {
+      return void 0;
+    }
+    if (!this.exists(normalizedPath)) {
+      return void 0;
+    }
+    const cachedHash = this.memo.get(normalizedPath);
+    if (cachedHash) {
+      return cachedHash;
+    }
+    const nextHash = this.hashFile(normalizedPath);
+    this.memo.set(normalizedPath, nextHash);
+    return nextHash;
+  }
+  /**
+   * Builds the dependency-hash map for one route entrypoint graph.
+   *
+   * @param modulePaths - Raw module ids from the bundler dependency graph.
+   * @returns Hashes for every trackable, existing source file in the graph.
+   */
+  createDependencyHashes(modulePaths) {
+    const dependencyHashes = {};
+    for (const modulePath of filterTrackableRouteModuleDependencies(modulePaths)) {
+      const dependencyHash = this.hashDependency(modulePath);
+      if (dependencyHash) {
+        dependencyHashes[modulePath] = dependencyHash;
+      }
+    }
+    return dependencyHashes;
+  }
+  /**
+   * Returns whether every stored dependency hash still matches the current file contents.
+   *
+   * @param storedHashes - Dependency hashes previously persisted for one route module.
+   * @param entrypointPath - Route entry file whose hash is validated separately.
+   * @param entrypointSourceHash - Already-validated content hash for {@link entrypointPath}.
+   * @returns `true` when all stored hashes are present and still valid.
+   */
+  matchesStoredHashes(storedHashes, entrypointPath, entrypointSourceHash) {
+    this.clearMemo();
+    if (!storedHashes || Object.keys(storedHashes).length === 0) {
+      return false;
+    }
+    const normalizedEntrypoint = entrypointPath ? path.normalize(entrypointPath) : void 0;
+    for (const [dependencyPath, storedHash] of Object.entries(storedHashes)) {
+      if (normalizedEntrypoint && path.normalize(dependencyPath) === normalizedEntrypoint) {
+        if (entrypointSourceHash && storedHash !== entrypointSourceHash) {
+          return false;
+        }
+        continue;
+      }
+      const currentHash = this.hashDependency(dependencyPath);
+      if (!currentHash || currentHash !== storedHash) {
+        return false;
+      }
+    }
+    return true;
+  }
+  /** Clears the per-build memo so subsequent reads reflect current file contents. */
+  clearMemo() {
+    this.memo.clear();
+  }
+}
+function isTrackableRouteModuleDependency(modulePath) {
+  const normalizedPath = path.normalize(modulePath);
+  if (normalizedPath.startsWith("node:")) {
+    return false;
+  }
+  if (normalizedPath.includes(`${path.sep}node_modules${path.sep}`)) {
+    return false;
+  }
+  return /\.(?:[cm]?[jt]sx?|mdx)$/iu.test(normalizedPath) || normalizedPath.endsWith(".json");
+}
+function filterTrackableRouteModuleDependencies(modulePaths) {
+  const uniquePaths = /* @__PURE__ */ new Set();
+  for (const modulePath of modulePaths) {
+    const normalizedPath = path.normalize(modulePath);
+    if (isTrackableRouteModuleDependency(normalizedPath)) {
+      uniquePaths.add(normalizedPath);
+    }
+  }
+  return Array.from(uniquePaths).sort();
+}
+function resolveRouteModuleDependencyPaths(buildResult, entrypointPath, rootDir) {
+  const normalizedEntrypoint = path.isAbsolute(entrypointPath) ? path.normalize(entrypointPath) : path.normalize(path.resolve(rootDir, entrypointPath));
+  const graphEntrypoints = buildResult.dependencyGraph?.entrypoints ?? {};
+  const dependencyPaths = graphEntrypoints[normalizedEntrypoint] ?? graphEntrypoints[entrypointPath] ?? Object.entries(graphEntrypoints).find(([candidate]) => path.normalize(candidate) === normalizedEntrypoint)?.[1];
+  if (!dependencyPaths || dependencyPaths.length === 0) {
+    return [normalizedEntrypoint];
+  }
+  return dependencyPaths.map(
+    (dependencyPath) => path.isAbsolute(dependencyPath) ? path.normalize(dependencyPath) : path.normalize(path.resolve(rootDir, dependencyPath))
+  );
+}
+function createRouteModuleDependencyHashes(hasher, buildResult, entrypointPath, rootDir) {
+  return hasher.createDependencyHashes(resolveRouteModuleDependencyPaths(buildResult, entrypointPath, rootDir));
+}
+export {
+  RouteModuleDependencyHasher,
+  createRouteModuleDependencyHashes,
+  filterTrackableRouteModuleDependencies,
+  isTrackableRouteModuleDependency,
+  resolveRouteModuleDependencyPaths
+};

package/src/services/module-loading/server-module-transpiler.service.js

@@ -11,7 +11,7 @@ class ServerModuleTranspiler {
    * context.
    */
   constructor(args) {
-    this.pageModuleImportService = args.pageModuleImportService ?? new PageModuleImportService({
+    this.pageModuleImportService = args.pageModuleImportService ?? new PageModuleImportService(void 0, {
       canLoadSourceModuleFromHost: args.canLoadSourceModuleFromHost,
       getHostModuleLoader: args.getHostModuleLoader
     });

package/src/static-site-generator/README.md

@@ -24,3 +24,36 @@ That means it should reuse:
 - asset processing
 
 It should not invent a parallel rendering stack just for build mode.
+
+## Files
+
+| File                           | Role                                                                         |
+| ------------------------------ | ---------------------------------------------------------------------------- |
+| `static-site-generator.ts`     | Route enumeration, HTML artifact writes, integration export hooks            |
+| `static-export-context.ts`     | Hook context type for `beforeStaticExport` / `afterStaticExport`             |
+| `static-build-invalidation.ts` | `dist/` reset policy, production cache clearing, static-render cache context |
+
+Build-input fingerprinting (`hashAppConfigFile`, `createBuildInputsFingerprint`) lives in `packages/core/src/build/build-input-fingerprint.ts` and is shared with server-entry and unified-graph caches.
+
+## Incremental static export
+
+`ServerStaticBuilder.prepareExportDirectory()` decides whether to wipe `dist/`:
+
+1. `force: true` → always reset
+2. Any processor/integration reports `didChange()` → reset
+3. Route-module manifest lacks matching `configHash` + `buildInputsFingerprint` → reset
+
+When `dist/` is preserved (`preserveExportDirectory: true`), `StaticSiteGenerator.run()` prunes HTML files no longer in the active route set.
+
+Rendered HTML reuse is tracked in `.eco/.server-modules/.build-cache.json` under each route module's `renderedOutputs`. `canReuseStaticRender()` skips re-rendering when the source file, dependency hashes, and output path are unchanged.
+
+`clearProductionBuildCaches()` runs on `force` builds and removes all persisted `.eco` build manifests (route modules, server entry, unified pages graph).
+
+## Integration hooks
+
+Integrations may implement:
+
+- `beforeStaticExport(context)` — runs after unified-graph prebuild, before page rendering
+- `afterStaticExport(context)` — runs in a `finally` block after generation completes
+
+See `StaticExportContext` in `static-export-context.ts`.

package/src/static-site-generator/static-build-invalidation.d.ts

@@ -0,0 +1,10 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import { type RouteModuleStaticRenderCacheContext } from '../services/module-loading/route-module-build-manifest.js';
+export type { BuildInputChangeContributor, IntegrationPlugin, Processor } from '../build/build-input-fingerprint.js';
+export { collectBuildInputContributors, createBuildInputsFingerprint, didBuildInputContributorChange, hashAppConfigFile, haveBuildInputsChanged, } from '../build/build-input-fingerprint.js';
+/** Builds the static-render invalidation context for one app config. */
+export declare function createRouteModuleStaticRenderCacheContext(appConfig: EcoPagesAppConfig): RouteModuleStaticRenderCacheContext;
+/** Returns whether `dist/` should be wiped before the next static export. */
+export declare function shouldResetStaticExportDirectory(appConfig: EcoPagesAppConfig, force?: boolean): boolean;
+/** Removes persisted production build caches so the next build recomputes everything. */
+export declare function clearProductionBuildCaches(appConfig: EcoPagesAppConfig): void;

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

@@ -0,0 +1,59 @@
+import {
+  createBuildInputsFingerprint,
+  hashAppConfigFile,
+  haveBuildInputsChanged
+} from "../build/build-input-fingerprint.js";
+import { clearPersistedProductionBuildCacheManifests } from "../build/production-build-cache.js";
+import {} from "../services/module-loading/route-module-build-manifest.js";
+import {
+  getSharedRouteModuleBuildCache,
+  getServerModuleBuildCacheOutdir
+} from "../services/module-loading/route-module-build-cache-registry.js";
+import {
+  collectBuildInputContributors,
+  createBuildInputsFingerprint as createBuildInputsFingerprint2,
+  didBuildInputContributorChange,
+  hashAppConfigFile as hashAppConfigFile2,
+  haveBuildInputsChanged as haveBuildInputsChanged2
+} from "../build/build-input-fingerprint.js";
+function createRouteModuleStaticRenderCacheContext(appConfig) {
+  return {
+    configHash: hashAppConfigFile(appConfig),
+    buildInputsFingerprint: createBuildInputsFingerprint(appConfig)
+  };
+}
+function shouldResetStaticExportDirectory(appConfig, force = false) {
+  if (force) {
+    return true;
+  }
+  if (haveBuildInputsChanged(appConfig)) {
+    return true;
+  }
+  const routeModuleCache = getSharedRouteModuleBuildCache(getServerModuleBuildCacheOutdir(appConfig), appConfig);
+  return !routeModuleCache.isIncrementalStaticGenerationAvailable(
+    createRouteModuleStaticRenderCacheContext(appConfig)
+  );
+}
+function clearProductionBuildCaches(appConfig) {
+  if (process.env.NODE_ENV !== "production") {
+    return;
+  }
+  clearPersistedProductionBuildCacheManifests(appConfig);
+  for (const cache of appConfig.runtime?.routeModuleBuildCaches?.values() ?? []) {
+    cache.resetMemory();
+  }
+  appConfig.runtime?.routeModuleBuildCaches?.clear();
+  if (appConfig.runtime) {
+    appConfig.runtime.buildRuntime = void 0;
+  }
+}
+export {
+  clearProductionBuildCaches,
+  collectBuildInputContributors,
+  createBuildInputsFingerprint2 as createBuildInputsFingerprint,
+  createRouteModuleStaticRenderCacheContext,
+  didBuildInputContributorChange,
+  hashAppConfigFile2 as hashAppConfigFile,
+  haveBuildInputsChanged2 as haveBuildInputsChanged,
+  shouldResetStaticExportDirectory
+};

package/src/static-site-generator/static-export-context.d.ts

@@ -0,0 +1,22 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { StaticRoute } from '../types/public-types.js';
+import type { StaticGenerationRendererResolver } from '../route-renderer/route-renderer.js';
+import type { StaticGenerationRoute } from '../router/server/route-registry.js';
+type StaticGenerationRouteSource = {
+    listStaticGenerationRoutes(input: {
+        runtimeOrigin: string;
+    }): Promise<readonly StaticGenerationRoute[]>;
+};
+/**
+ * Context passed to integration plugins during static export lifecycle hooks.
+ */
+export interface StaticExportContext {
+    appConfig: EcoPagesAppConfig;
+    router: StaticGenerationRouteSource;
+    baseUrl: string;
+    routeRendererFactory?: StaticGenerationRendererResolver;
+    staticRoutes?: StaticRoute[];
+    force: boolean;
+    preserveExportDirectory: boolean;
+}
+export {};

package/src/static-site-generator/static-site-generator.d.ts

@@ -2,6 +2,7 @@ import type { EcoPagesAppConfig } from '../types/internal-types.js';
 import type { StaticRoute } from '../types/public-types.js';
 import type { PageRendererResolver, StaticGenerationRendererResolver } from '../route-renderer/route-renderer.js';
 import type { StaticGenerationRoute } from '../router/server/route-registry.js';
+import type { RouteModuleBuildCache } from '../services/module-loading/route-module-build-cache.store.js';
 type StaticGenerationRouteSource = {
     listStaticGenerationRoutes(input: {
         runtimeOrigin: string;
@@ -27,26 +28,19 @@ export declare const STATIC_SITE_GENERATOR_ERRORS: {
  */
 export declare class StaticSiteGenerator {
     appConfig: EcoPagesAppConfig;
+    private readonly routeModuleBuildCacheOverride?;
+    private staticRenderCacheContext;
+    private forceFullStaticGeneration;
     /**
      * Creates the static-site generator for one app config.
      */
-    constructor({ appConfig }: {
+    constructor({ appConfig, routeModuleBuildCache, }: {
         appConfig: EcoPagesAppConfig;
+        routeModuleBuildCache?: RouteModuleBuildCache;
     });
+    private getRouteModuleBuildCache;
     private getExportDir;
-    /**
-     * Logs the standardized warning emitted when a dynamic-cache page is skipped.
-     */
-    private warnDynamicPageSkipped;
-    /**
-     * Determines whether one filesystem-discovered page should be excluded from
-     * static generation.
-     */
     private shouldSkipStaticPageFile;
-    /**
-     * Determines whether one explicit static route view should be excluded from
-     * static generation.
-     */
     private shouldSkipStaticView;
     /**
      * Writes the robots.txt file declared by the app config.
@@ -61,32 +55,35 @@ export declare class StaticSiteGenerator {
      */
     getDirectories(routes: string[]): string[];
     private writeStaticOutput;
-    private getStaticBuildStrategy;
+    private writeStaticPageArtifact;
+    private pruneStaleStaticOutputs;
     private createFilesystemStaticContents;
     /**
      * 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.
      */
-    generateStaticPages(router: StaticGenerationRouteSource, baseUrl: string, routeRendererFactory?: StaticPageRouteRendererFactory): Promise<void>;
-    private resolveStaticFetchUrl;
+    generateStaticPages(router: StaticGenerationRouteSource, baseUrl: string, routeRendererFactory?: StaticPageRouteRendererFactory, skipped?: string[], activeStaticPathnames?: Set<string>, preloadedRoutes?: readonly StaticGenerationRoute[]): Promise<void>;
+    private createStaticExportContext;
+    private invokeStaticExportHook;
     /**
      * Executes the full static-generation workflow for one app run.
      */
-    run({ router, baseUrl, routeRendererFactory, staticRoutes, }: {
+    run({ router, baseUrl, routeRendererFactory, staticRoutes, force, preserveExportDirectory, }: {
         router: StaticGenerationRouteSource;
         baseUrl: string;
         routeRendererFactory?: StaticGenerationRendererFactory;
         staticRoutes?: StaticRoute[];
+        force?: boolean;
+        preserveExportDirectory?: boolean;
     }): Promise<void>;
     /**
      * Generates static pages from explicit static routes registered via app.static().
      * These routes use eco.page views via loader functions for HMR support.
      */
     private generateExplicitStaticPages;
+    private resolveExplicitViewSourceFile;
     private generateExplicitStaticRoute;
     private planExplicitStaticRoute;
     private createExplicitStaticContents;