@ecopages/core 0.2.0-beta.6 → 0.2.0-beta.8

package/src/services/module-loading/route-module-build-cache.store.js

@@ -0,0 +1,203 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { RouteModuleDependencyHasher } from "./route-module-dependency-hasher.js";
+import {
+  ROUTE_MODULE_BUILD_CACHE_FILENAME,
+  createEmptyRouteModuleBuildCacheManifest,
+  createPersistedRouteModuleBuildKey,
+  getCorePackageVersion,
+  normalizeRouteModuleCachePath,
+  readRouteModuleBuildCacheManifest,
+  shouldPersistRouteModuleBuildCache,
+  writeRouteModuleBuildCacheManifest
+} from "./route-module-build-manifest.js";
+class RouteModuleBuildCache {
+  manifestPath;
+  dependencies;
+  dependencyHasher;
+  manifest;
+  manifestLoaded = false;
+  constructor(outdir, dependencies) {
+    this.manifestPath = path.join(outdir, ROUTE_MODULE_BUILD_CACHE_FILENAME);
+    this.dependencies = {
+      readManifest: dependencies?.readManifest ?? readRouteModuleBuildCacheManifest,
+      writeManifest: dependencies?.writeManifest ?? writeRouteModuleBuildCacheManifest,
+      exists: dependencies?.exists ?? ((filePath) => fileSystem.exists(filePath)),
+      getCorePackageVersion: dependencies?.getCorePackageVersion ?? getCorePackageVersion,
+      createDependencyHasher: dependencies?.createDependencyHasher ?? (() => new RouteModuleDependencyHasher())
+    };
+    this.dependencyHasher = this.dependencies.createDependencyHasher();
+  }
+  lookup(options) {
+    if (!shouldPersistRouteModuleBuildCache(options)) {
+      return void 0;
+    }
+    const manifest = this.loadManifest();
+    if (manifest.invalidationVersion !== this.dependencies.getCorePackageVersion()) {
+      return void 0;
+    }
+    const buildKey = createPersistedRouteModuleBuildKey(options);
+    const cacheFilePath = normalizeRouteModuleCachePath(options.filePath);
+    const entry = manifest.entries[cacheFilePath];
+    if (!entry || entry.sourceHash !== options.fileHash || entry.buildKey !== buildKey) {
+      return void 0;
+    }
+    if (!this.dependencyHasher.matchesStoredHashes(entry.dependencyHashes, cacheFilePath, options.fileHash)) {
+      return void 0;
+    }
+    const outputPath = path.isAbsolute(entry.outputPath) ? entry.outputPath : path.join(options.outdir, entry.outputPath);
+    if (!this.dependencies.exists(outputPath)) {
+      return void 0;
+    }
+    return { outputPath, entry };
+  }
+  recordBuild(options) {
+    if (!shouldPersistRouteModuleBuildCache(options)) {
+      return;
+    }
+    const cacheFilePath = normalizeRouteModuleCachePath(options.filePath);
+    const dependencyModulePaths = options.dependencyModulePaths && options.dependencyModulePaths.length > 0 ? options.dependencyModulePaths : [cacheFilePath];
+    const dependencyHashes = this.dependencyHasher.createDependencyHashes(dependencyModulePaths);
+    dependencyHashes[cacheFilePath] = options.fileHash;
+    const manifest = this.loadManifest();
+    const existingEntry = manifest.entries[cacheFilePath];
+    manifest.invalidationVersion = this.dependencies.getCorePackageVersion();
+    manifest.entries[cacheFilePath] = {
+      sourceHash: options.fileHash,
+      outputPath: options.outputPath,
+      builtAt: Date.now(),
+      buildKey: createPersistedRouteModuleBuildKey(options),
+      dependencyHashes,
+      renderedOutputs: existingEntry?.renderedOutputs
+    };
+    this.persistManifest(manifest);
+  }
+  isIncrementalStaticGenerationAvailable(context) {
+    if (process.env.NODE_ENV !== "production") {
+      return false;
+    }
+    const manifest = this.loadManifest();
+    if (manifest.invalidationVersion !== this.dependencies.getCorePackageVersion()) {
+      return false;
+    }
+    return manifest.configHash === context.configHash && manifest.buildInputsFingerprint === context.buildInputsFingerprint;
+  }
+  ensureIncrementalStaticGenerationContext(context) {
+    if (process.env.NODE_ENV !== "production") {
+      return;
+    }
+    const manifest = this.loadManifest();
+    manifest.invalidationVersion = this.dependencies.getCorePackageVersion();
+    manifest.configHash = context.configHash;
+    manifest.buildInputsFingerprint = context.buildInputsFingerprint;
+    this.persistManifest(manifest);
+  }
+  canReuseStaticRender(options) {
+    if (options.force) {
+      return false;
+    }
+    if (!fileSystem.exists(options.sourceFile)) {
+      return false;
+    }
+    const sourceHash = fileSystem.hash(options.sourceFile);
+    return this.lookupStaticRender({
+      filePath: options.sourceFile,
+      pathname: options.pathname,
+      sourceHash,
+      renderedOutputPath: options.renderedOutputPath,
+      context: options.context
+    });
+  }
+  lookupStaticRender(options) {
+    if (!this.isIncrementalStaticGenerationAvailable(options.context)) {
+      return false;
+    }
+    const manifest = this.loadManifest();
+    const cacheFilePath = normalizeRouteModuleCachePath(options.filePath);
+    const entry = manifest.entries[cacheFilePath];
+    const renderedOutput = entry?.renderedOutputs?.[options.pathname];
+    if (!entry || !renderedOutput) {
+      return false;
+    }
+    if (entry.sourceHash !== options.sourceHash || renderedOutput.sourceHash !== options.sourceHash) {
+      return false;
+    }
+    if (!this.dependencyHasher.matchesStoredHashes(entry.dependencyHashes, cacheFilePath, options.sourceHash)) {
+      return false;
+    }
+    const cachedOutputPath = path.isAbsolute(renderedOutput.renderedOutputPath) ? renderedOutput.renderedOutputPath : path.resolve(renderedOutput.renderedOutputPath);
+    if (cachedOutputPath !== path.resolve(options.renderedOutputPath)) {
+      return false;
+    }
+    return this.dependencies.exists(cachedOutputPath);
+  }
+  recordStaticRender(options) {
+    if (process.env.NODE_ENV !== "production") {
+      return;
+    }
+    const cacheFilePath = normalizeRouteModuleCachePath(options.filePath);
+    const manifest = this.loadManifest();
+    const existingEntry = manifest.entries[cacheFilePath];
+    manifest.invalidationVersion = this.dependencies.getCorePackageVersion();
+    manifest.configHash = options.context.configHash;
+    manifest.buildInputsFingerprint = options.context.buildInputsFingerprint;
+    manifest.entries[cacheFilePath] = {
+      sourceHash: options.sourceHash,
+      outputPath: existingEntry?.outputPath ?? "",
+      builtAt: existingEntry?.builtAt ?? Date.now(),
+      buildKey: existingEntry?.buildKey ?? "",
+      dependencyHashes: existingEntry?.dependencyHashes,
+      renderedOutputs: {
+        ...existingEntry?.renderedOutputs ?? {},
+        [options.pathname]: {
+          renderedOutputPath: options.renderedOutputPath,
+          renderedAt: Date.now(),
+          sourceHash: options.sourceHash
+        }
+      }
+    };
+    this.persistManifest(manifest);
+  }
+  resetMemory() {
+    this.manifest = void 0;
+    this.manifestLoaded = false;
+  }
+  pruneStaleRenderedOutputs(activePathnames) {
+    if (process.env.NODE_ENV !== "production") {
+      return [];
+    }
+    const manifest = this.loadManifest();
+    const removedOutputPaths = [];
+    for (const entry of Object.values(manifest.entries)) {
+      if (!entry.renderedOutputs) {
+        continue;
+      }
+      for (const [pathname, renderedOutput] of Object.entries(entry.renderedOutputs)) {
+        if (activePathnames.has(pathname)) {
+          continue;
+        }
+        removedOutputPaths.push(renderedOutput.renderedOutputPath);
+        delete entry.renderedOutputs[pathname];
+      }
+    }
+    if (removedOutputPaths.length > 0) {
+      this.persistManifest(manifest);
+    }
+    return removedOutputPaths;
+  }
+  loadManifest() {
+    if (this.manifestLoaded) {
+      return this.manifest ?? createEmptyRouteModuleBuildCacheManifest();
+    }
+    this.manifestLoaded = true;
+    this.manifest = this.dependencies.readManifest(this.manifestPath) ?? createEmptyRouteModuleBuildCacheManifest();
+    return this.manifest;
+  }
+  persistManifest(manifest) {
+    this.manifest = manifest;
+    this.dependencies.writeManifest(this.manifestPath, manifest);
+  }
+}
+export {
+  RouteModuleBuildCache
+};

package/src/services/module-loading/route-module-build-manifest.d.ts

@@ -0,0 +1,61 @@
+import type { EcoBuildPlugin } from '../../build/build-types.js';
+import type { PageModuleBuildImportOptions } from './page-module-import.service.js';
+import type { RouteModuleDependencyHashes } from './route-module-dependency-hasher.js';
+/** Filename written beside transpiled server modules that stores incremental build metadata. */
+export declare const ROUTE_MODULE_BUILD_CACHE_FILENAME = ".build-cache.json";
+/** One persisted route-module build entry in {@link ROUTE_MODULE_BUILD_CACHE_FILENAME}. */
+export interface RouteModuleBuildCacheEntry {
+    sourceHash: string;
+    outputPath: string;
+    builtAt: number;
+    buildKey: string;
+    dependencyHashes?: RouteModuleDependencyHashes;
+    renderedOutputs?: Record<string, RouteModuleStaticRenderCacheEntry>;
+}
+/** Metadata for one rendered static HTML artifact derived from a route module. */
+export interface RouteModuleStaticRenderCacheEntry {
+    renderedOutputPath: string;
+    renderedAt: number;
+    sourceHash: string;
+}
+/** On-disk manifest describing all cached route-module builds for one server outdir. */
+export interface RouteModuleBuildCacheManifest {
+    invalidationVersion: string;
+    configHash?: string;
+    buildInputsFingerprint?: string;
+    entries: Record<string, RouteModuleBuildCacheEntry>;
+}
+/** Successful route-module cache lookup result. */
+export interface RouteModuleBuildCacheLookup {
+    outputPath: string;
+    entry: RouteModuleBuildCacheEntry;
+}
+/** Inputs that must remain stable for incremental static HTML generation. */
+export interface RouteModuleStaticRenderCacheContext {
+    configHash: string;
+    buildInputsFingerprint: string;
+}
+export type RouteModuleBuildCacheManifestReader = (manifestPath: string) => RouteModuleBuildCacheManifest | undefined;
+export type RouteModuleBuildCacheManifestWriter = (manifestPath: string, manifest: RouteModuleBuildCacheManifest) => void;
+/** Returns the installed `@ecopages/core` package version used to invalidate persisted caches. */
+export declare function getCorePackageVersion(): string;
+/** Normalizes filesystem paths used as manifest keys and build-key inputs. */
+export declare function normalizeRouteModuleCachePath(filePath: string): string;
+/** Returns whether route-module disk caching should run for the current import. */
+export declare function shouldPersistRouteModuleBuildCache(options: PageModuleBuildImportOptions): boolean;
+/** Derives the deterministic on-disk filename for one transpiled route module. */
+export declare function resolvePageModuleOutputFileName(options: {
+    filePath: string;
+    fileHash: string;
+    cacheScope?: string;
+    invalidationVersion?: number;
+}): string;
+/** Builds the cache key for persisted production route-module builds. */
+export declare function createPersistedRouteModuleBuildKey(options: PageModuleBuildImportOptions): string;
+export declare function createEmptyRouteModuleBuildCacheManifest(): RouteModuleBuildCacheManifest;
+export declare function readRouteModuleBuildCacheManifest(manifestPath: string): RouteModuleBuildCacheManifest | undefined;
+export declare function writeRouteModuleBuildCacheManifest(manifestPath: string, manifest: RouteModuleBuildCacheManifest): void;
+export declare function createJsxCacheKey(jsx: PageModuleBuildImportOptions['jsx']): string;
+export declare function createPluginCacheKey(plugins?: EcoBuildPlugin[]): string;
+/** Exported for in-process import caches that must match persisted build keys. */
+export declare function hashPluginSetup(setup: EcoBuildPlugin['setup']): string;

package/src/services/module-loading/route-module-build-manifest.js

@@ -0,0 +1,124 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+const ROUTE_MODULE_BUILD_CACHE_FILENAME = ".build-cache.json";
+let cachedCorePackageVersion;
+function getCorePackageVersion() {
+  if (cachedCorePackageVersion) {
+    return cachedCorePackageVersion;
+  }
+  const packageJsonPath = new URL("../../../package.json", import.meta.url);
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+  cachedCorePackageVersion = packageJson.version ?? "0.0.0";
+  return cachedCorePackageVersion;
+}
+function normalizeRouteModuleCachePath(filePath) {
+  return path.resolve(filePath);
+}
+function shouldPersistRouteModuleBuildCache(options) {
+  if (process.env.NODE_ENV !== "production") {
+    return false;
+  }
+  if (options.bypassCache) {
+    return false;
+  }
+  if ((options.invalidationVersion ?? 0) > 0) {
+    return false;
+  }
+  if (options.cacheScope) {
+    return false;
+  }
+  return true;
+}
+function resolvePageModuleOutputFileName(options) {
+  const fileBaseName = path.basename(options.filePath, path.extname(options.filePath));
+  const cacheScopeSuffix = options.cacheScope ? `-${sanitizeCacheScope(options.cacheScope)}` : "";
+  const invalidationSuffix = shouldVersionBuildOutputPath(options.invalidationVersion ?? 0) ? `-v${options.invalidationVersion}` : "";
+  return `${fileBaseName}-${options.fileHash}${cacheScopeSuffix}${invalidationSuffix}.mjs`;
+}
+function createPersistedRouteModuleBuildKey(options) {
+  return [
+    path.resolve(options.rootDir),
+    path.resolve(options.outdir),
+    options.splitting ?? "default",
+    options.externalPackages ?? "default",
+    createJsxCacheKey(options.jsx),
+    createPluginCacheKey(options.plugins)
+  ].join("::");
+}
+function createEmptyRouteModuleBuildCacheManifest() {
+  return {
+    invalidationVersion: getCorePackageVersion(),
+    entries: {}
+  };
+}
+function readRouteModuleBuildCacheManifest(manifestPath) {
+  if (!fileSystem.exists(manifestPath)) {
+    return void 0;
+  }
+  try {
+    const parsed = JSON.parse(fileSystem.readFileSync(manifestPath));
+    if (!parsed || typeof parsed !== "object" || typeof parsed.entries !== "object") {
+      return void 0;
+    }
+    return {
+      invalidationVersion: parsed.invalidationVersion ?? "",
+      configHash: parsed.configHash,
+      buildInputsFingerprint: parsed.buildInputsFingerprint,
+      entries: parsed.entries
+    };
+  } catch {
+    return void 0;
+  }
+}
+function writeRouteModuleBuildCacheManifest(manifestPath, manifest) {
+  fileSystem.write(manifestPath, `${JSON.stringify(manifest, null, "	")}
+`);
+}
+function shouldVersionBuildOutputPath(invalidationVersion) {
+  return typeof Bun !== "undefined" && invalidationVersion > 0;
+}
+function sanitizeCacheScope(cacheScope) {
+  return cacheScope.replace(/[^a-zA-Z0-9_-]+/g, "-");
+}
+function createJsxCacheKey(jsx) {
+  if (!jsx) {
+    return "jsx:default";
+  }
+  return JSON.stringify({
+    development: jsx.development ?? false,
+    factory: jsx.factory ?? null,
+    fragment: jsx.fragment ?? null,
+    importSource: jsx.importSource ?? null,
+    runtime: jsx.runtime ?? null,
+    sideEffects: jsx.sideEffects ?? null
+  });
+}
+function createPluginCacheKey(plugins) {
+  if (!plugins || plugins.length === 0) {
+    return "plugins:default";
+  }
+  return `plugins:${plugins.map((plugin) => `${plugin.name}:${hashPluginSetup(plugin.setup)}`).join(",")}`;
+}
+function hashPluginSetup(setup) {
+  let hash = 0;
+  const source = setup.toString();
+  for (let index = 0; index < source.length; index += 1) {
+    hash = hash * 31 + source.charCodeAt(index) | 0;
+  }
+  return (hash >>> 0).toString(36);
+}
+export {
+  ROUTE_MODULE_BUILD_CACHE_FILENAME,
+  createEmptyRouteModuleBuildCacheManifest,
+  createJsxCacheKey,
+  createPersistedRouteModuleBuildKey,
+  createPluginCacheKey,
+  getCorePackageVersion,
+  hashPluginSetup,
+  normalizeRouteModuleCachePath,
+  readRouteModuleBuildCacheManifest,
+  resolvePageModuleOutputFileName,
+  shouldPersistRouteModuleBuildCache,
+  writeRouteModuleBuildCacheManifest
+};

package/src/services/module-loading/route-module-dependency-hasher.d.ts

@@ -0,0 +1,81 @@
+import type { BuildResult } from '../../build/build-adapter.js';
+/**
+ * Content hashes for every trackable source file in one route module's import graph.
+ *
+ * @remarks
+ * Keys are normalized absolute filesystem paths. Values are opaque content hashes
+ * produced by the active {@link FileSystem} implementation. Only app-owned source
+ * files are tracked; `node:` builtins and `node_modules` paths are excluded
+ * because they are covered by the core package {@link getCorePackageVersion | invalidation version}.
+ */
+export type RouteModuleDependencyHashes = Record<string, string>;
+type HashFileFn = (filePath: string) => string;
+type ExistsFn = (filePath: string) => boolean;
+/**
+ * Lazily hashes route-module dependency files while memoizing results for one build run.
+ *
+ * @remarks
+ * Multiple route modules often share layouts or utilities. Memoizing per path avoids
+ * re-reading the same dependency file while validating or recording many cache entries
+ * during one production build.
+ */
+export declare class RouteModuleDependencyHasher {
+    private readonly memo;
+    private readonly hashFile;
+    private readonly exists;
+    constructor(dependencies?: {
+        hashFile?: HashFileFn;
+        exists?: ExistsFn;
+    });
+    /**
+     * 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: string): string | undefined;
+    /**
+     * 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: readonly string[]): RouteModuleDependencyHashes;
+    /**
+     * 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: RouteModuleDependencyHashes | undefined, entrypointPath?: string, entrypointSourceHash?: string): boolean;
+    /** Clears the per-build memo. Intended for unit tests only. */
+    clearMemoForTests(): void;
+}
+/**
+ * Returns whether a bundler module id should participate in route-module cache invalidation.
+ *
+ * @remarks
+ * Builtins and installed packages are excluded. Their changes are expected to be
+ * reflected through framework-level invalidation instead of per-route file hashing.
+ */
+export declare function isTrackableRouteModuleDependency(modulePath: string): boolean;
+/**
+ * Filters a bundler module list down to trackable app-owned source files.
+ */
+export declare function filterTrackableRouteModuleDependencies(modulePaths: readonly string[]): string[];
+/**
+ * Resolves the dependency module list for one route entrypoint from a build result.
+ *
+ * @param buildResult - Completed route-module build output.
+ * @param entrypointPath - Absolute or root-relative route source path used as the build entry.
+ * @param rootDir - Project root used to normalize relative module ids.
+ * @returns Normalized module paths, falling back to the entrypoint when no graph is available.
+ */
+export declare function resolveRouteModuleDependencyPaths(buildResult: Pick<BuildResult, 'dependencyGraph'>, entrypointPath: string, rootDir: string): string[];
+/**
+ * Convenience helper that combines graph extraction and dependency hashing.
+ */
+export declare function createRouteModuleDependencyHashes(hasher: RouteModuleDependencyHasher, buildResult: Pick<BuildResult, 'dependencyGraph'>, entrypointPath: string, rootDir: string): RouteModuleDependencyHashes;
+export {};

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

@@ -0,0 +1,121 @@
+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) {
+    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. Intended for unit tests only. */
+  clearMemoForTests() {
+    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;