@ecopages/core 0.2.0-beta.9 → 0.2.0-rc.0

package/src/services/assets/asset-processing-service/asset-processing.service.js

@@ -1,285 +1,352 @@
-import path from "node:path";
-import { RESOLVED_ASSETS_DIR } from "../../../config/constants.js";
-import { appLogger } from "../../../global/app-logger.js";
-import { fileSystem } from "@ecopages/file-system";
-import { deduplicateAssetDependencies, getAssetDependencyKey } from "./asset-dependency-keys.js";
-import {
-  partitionGroupedContentScriptDependencies,
-  processGroupedDependencyBundles
-} from "./grouped-content-bundles.js";
-import { isHmrAware } from "./processor.interface.js";
-import { ProcessorRegistry } from "./processor.registry.js";
-import { processUngroupedDependency } from "./ungrouped-dependency-processing.js";
-import {
-  ContentScriptProcessor,
-  ContentStylesheetProcessor,
-  FileScriptProcessor,
-  FileStylesheetProcessor,
-  NodeModuleScriptProcessor
-} from "./processors/index.js";
-class AssetProcessingService {
-  static RESOLVED_ASSETS_DIR = RESOLVED_ASSETS_DIR;
-  registry = new ProcessorRegistry();
-  hmrManager;
-  cache = /* @__PURE__ */ new Map();
-  config;
-  /**
-   * Creates the asset-processing service bound to one finalized app config.
-   */
-  constructor(config) {
-    this.config = config;
-  }
-  /**
-   * Set the HMR manager for the asset processing service.
-   * @param hmrManager The HMR manager to set.
-   */
-  setHmrManager(hmrManager) {
-    this.hmrManager = hmrManager;
-    for (const processor of this.registry.getAllProcessors().values()) {
-      if (isHmrAware(processor)) {
-        processor.setHmrManager(hmrManager);
-      }
+import path from 'node:path';
+import { RESOLVED_ASSETS_DIR } from '../../../config/constants.js';
+import { appLogger } from '../../../global/app-logger.js';
+import { fileSystem } from '@ecopages/file-system';
+import { deduplicateAssetDependencies, getAssetDependencyKey } from './asset-dependency-keys.js';
+import { ensureGroupedContentScriptsBundle, partitionGroupedContentScriptDependencies, processGroupedDependencyBundles, } from './grouped-content-bundles.js';
+import { resolveIntegrationPluginForProcessingKey } from './resolve-integration-plugin.js';
+import { isHmrAware } from './processor.interface.js';
+import { ProcessorRegistry } from './processor.registry.js';
+import { processUngroupedDependency } from './ungrouped-dependency-processing.js';
+import { materializeContentScriptAsset } from './materialize-content-script-asset.js';
+import { bumpBrowserRuntimeAssetGeneration } from '../browser-runtime-asset-generation.js';
+import { ContentScriptProcessor, ContentStylesheetProcessor, FileScriptProcessor, FileStylesheetProcessor, NodeModuleScriptProcessor, } from './processors/index.js';
+/**
+ * Processes declared component and page asset dependencies for one app instance.
+ *
+ * @remarks
+ * This service is the shared bridge between dependency declarations and emitted
+ * runtime-ready assets. It owns deduplication, processor dispatch, cache reuse,
+ * output URL normalization, and production gzip preparation so route rendering
+ * and HMR flows do not need to understand processor-specific behavior.
+ */
+export class AssetProcessingService {
+    static RESOLVED_ASSETS_DIR = RESOLVED_ASSETS_DIR;
+    registry = new ProcessorRegistry();
+    hmrManager;
+    cache = new Map();
+    config;
+    /**
+     * Creates the asset-processing service bound to one finalized app config.
+     */
+    constructor(config) {
+        this.config = config;
     }
-  }
-  getHmrManager() {
-    return this.hmrManager;
-  }
-  /**
-   * Register a processor for a specific asset kind and source.
-   * @param kind The asset kind.
-   * @param variant The asset source.
-   * @param processor The processor to register.
-   */
-  registerProcessor(kind, variant, processor) {
-    if (this.hmrManager && isHmrAware(processor)) {
-      processor.setHmrManager(this.hmrManager);
+    /**
+     * Set the HMR manager for the asset processing service.
+     * @param hmrManager The HMR manager to set.
+     */
+    setHmrManager(hmrManager) {
+        this.hmrManager = hmrManager;
+        for (const processor of this.registry.getAllProcessors().values()) {
+            if (isHmrAware(processor)) {
+                processor.setHmrManager(hmrManager);
+            }
+        }
+    }
+    getHmrManager() {
+        return this.hmrManager;
     }
-    this.registry.register(kind, variant, processor);
-  }
-  /**
-   * Processes one dependency list into normalized emitted assets.
-   *
-   * @remarks
-   * Dependencies are deduplicated before processor execution so repeated
-   * declarations across the render tree reuse the same emitted outputs and cache
-   * entries.
-   */
-  async processDependencies(deps, key) {
-    const depsDir = path.join(this.config.absolutePaths.distDir, RESOLVED_ASSETS_DIR);
-    fileSystem.ensureDir(depsDir);
-    const dedupedDeps = deduplicateAssetDependencies(deps);
-    const results = await this.processDependenciesParallel(dedupedDeps, key);
-    await this.optimizeDependencies(results);
-    return results;
-  }
-  /**
-   * Processes deduplicated dependencies grouped by processor type.
-   *
-   * @remarks
-   * Grouping keeps cache and processor behavior isolated by asset kind/source
-   * pair, while still allowing the overall dependency set to resolve in
-   * parallel.
-   */
-  async processDependenciesParallel(deps, key) {
-    const grouped = this.groupDependenciesByType(deps);
-    const groupPromises = Object.entries(grouped).map(async ([, typeDeps]) => {
-      const { groupedBundleDeps, ungroupedDeps } = partitionGroupedContentScriptDependencies(typeDeps);
-      const typePromises = ungroupedDeps.map(
-        (dep) => processUngroupedDependency({
-          dep,
-          key,
-          depKey: getAssetDependencyKey(dep),
-          getCachedAsset: (assetDep, depKey) => this.getCachedAsset(assetDep, depKey),
-          getProcessor: (assetDep) => this.registry.getProcessor(assetDep.kind, assetDep.source),
-          resolveProcessedAssetSrcUrl: (processed) => this.resolveProcessedAssetSrcUrl(processed),
-          setCachedAsset: (assetDep, depKey, processed) => this.setCachedAsset(assetDep, depKey, processed),
-          logMissingProcessor: (assetDep) => {
-            appLogger.error(`No processor found for ${assetDep.kind}/${assetDep.source}`);
-          },
-          logMissingFile: (assetDep) => {
-            appLogger.warn(`Skipping missing ${assetDep.kind} file: ${assetDep.filepath}`);
-          },
-          logProcessingError: (assetDep, error) => {
-            appLogger.error(
-              `Failed to process dependency: ${error instanceof Error ? error.message : String(error)} for ${assetDep.kind}/${assetDep.source}`
-            );
-            appLogger.debug(error);
-          }
-        })
-      );
-      const groupedResults = await processGroupedDependencyBundles({
-        bundles: Array.from(groupedBundleDeps.values()),
-        key,
-        getCachedAsset: (dep, depKey) => this.getCachedAsset(dep, depKey),
-        getDependencyKey: getAssetDependencyKey,
-        getGroupedProcessor: () => this.registry.getProcessor("script", "content"),
-        resolveProcessedAssetSrcUrl: (processed) => this.resolveProcessedAssetSrcUrl(processed),
-        setCachedAsset: (dep, depKey, processed) => this.setCachedAsset(dep, depKey, processed),
-        logError: (error) => {
-          appLogger.error(
-            `Failed to process grouped dependency bundle: ${error instanceof Error ? error.message : String(error)}`
-          );
-          appLogger.debug(error);
+    /**
+     * Register a processor for a specific asset kind and source.
+     * @param kind The asset kind.
+     * @param variant The asset source.
+     * @param processor The processor to register.
+     */
+    registerProcessor(kind, variant, processor) {
+        if (this.hmrManager && isHmrAware(processor)) {
+            processor.setHmrManager(this.hmrManager);
         }
-      });
-      const typeResults = await Promise.all(typePromises);
-      const processedTypeResults = typeResults.flatMap((result) => {
-        if (!result) {
-          return [];
+        this.registry.register(kind, variant, processor);
+    }
+    /**
+     * Processes one dependency list into normalized emitted assets.
+     *
+     * @remarks
+     * Dependencies are deduplicated before processor execution so repeated
+     * declarations across the render tree reuse the same emitted outputs and cache
+     * entries. Returned asset order is unspecified — consumers must re-associate
+     * outputs with inputs via dependency metadata such as `groupedBundle`, not by
+     * array index alignment with the input list.
+     */
+    async processDependencies(deps, key) {
+        const depsDir = path.join(this.config.absolutePaths.distDir, RESOLVED_ASSETS_DIR);
+        fileSystem.ensureDir(depsDir);
+        const dedupedDeps = deduplicateAssetDependencies(deps);
+        const preparedDeps = this.prepareDependenciesForProcessing(dedupedDeps, key);
+        ensureGroupedContentScriptsBundle(preparedDeps);
+        const results = await this.processDependenciesParallel(preparedDeps);
+        await this.optimizeDependencies(results);
+        return results;
+    }
+    prepareDependenciesForProcessing(deps, processingKey) {
+        const plugin = resolveIntegrationPluginForProcessingKey(this.config, processingKey);
+        return plugin?.prepareAssetDependencies?.(deps) ?? deps;
+    }
+    /**
+     * Processes deduplicated dependencies grouped by processor type.
+     *
+     * @remarks
+     * Grouping keeps cache and processor behavior isolated by asset kind/source
+     * pair, while still allowing the overall dependency set to resolve in
+     * parallel.
+     */
+    async processDependenciesParallel(deps) {
+        const grouped = this.groupDependenciesByType(deps);
+        const groupPromises = Object.entries(grouped).map(async ([, typeDeps]) => {
+            const { groupedBundleDeps, ungroupedDeps } = partitionGroupedContentScriptDependencies(typeDeps);
+            const typePromises = ungroupedDeps.map((dep) => processUngroupedDependency({
+                dep,
+                depKey: getAssetDependencyKey(dep),
+                getCachedAsset: (assetDep, depKey) => this.getCachedAsset(assetDep, depKey),
+                getProcessor: (assetDep) => this.registry.getProcessor(assetDep.kind, assetDep.source),
+                resolveProcessedAssetSrcUrl: (processed) => this.resolveProcessedAssetSrcUrl(processed),
+                setCachedAsset: (assetDep, depKey, processed) => this.setCachedAsset(assetDep, depKey, processed),
+                logMissingProcessor: (assetDep) => {
+                    appLogger.error(`No processor found for ${assetDep.kind}/${assetDep.source}`);
+                },
+                logMissingFile: (assetDep) => {
+                    appLogger.warn(`Skipping missing ${assetDep.kind} file: ${assetDep.filepath}`);
+                },
+                logProcessingError: (assetDep, error) => {
+                    appLogger.error(`Failed to process dependency: ${error instanceof Error ? error.message : String(error)} for ${assetDep.kind}/${assetDep.source}`);
+                    appLogger.debug(error);
+                },
+            }));
+            const groupedResults = await processGroupedDependencyBundles({
+                bundles: Array.from(groupedBundleDeps.values()),
+                getCachedAsset: (dep, depKey) => this.getCachedAsset(dep, depKey),
+                getDependencyKey: getAssetDependencyKey,
+                getGroupedProcessor: () => this.registry.getProcessor('script', 'content'),
+                resolveProcessedAssetSrcUrl: (processed) => this.resolveProcessedAssetSrcUrl(processed),
+                setCachedAsset: (dep, depKey, processed) => this.setCachedAsset(dep, depKey, processed),
+                logError: (error) => {
+                    appLogger.error(`Failed to process grouped dependency bundle: ${error instanceof Error ? error.message : String(error)}`);
+                    appLogger.debug(error);
+                },
+            });
+            const typeResults = await Promise.all(typePromises);
+            const processedTypeResults = typeResults.flatMap((result) => {
+                if (!result) {
+                    return [];
+                }
+                return Array.isArray(result) ? result : [result];
+            });
+            return [...processedTypeResults, ...groupedResults];
+        });
+        const allTypeResults = await Promise.all(groupPromises);
+        return allTypeResults.flat();
+    }
+    /**
+     * Groups dependencies by processor bucket.
+     */
+    groupDependenciesByType(deps) {
+        return deps.reduce((acc, dep) => {
+            const key = `${dep.kind}_${dep.source}`;
+            if (!acc[key])
+                acc[key] = [];
+            acc[key].push(dep);
+            return acc;
+        }, {});
+    }
+    /**
+     * Converts a dist-local file path into its public URL.
+     */
+    getSrcUrl(filepath) {
+        const distDir = this.config.absolutePaths.distDir;
+        if (!filepath.startsWith(distDir))
+            return undefined;
+        const relativePath = filepath.slice(distDir.length);
+        const urlPath = relativePath.startsWith('/') ? relativePath : `/${relativePath}`;
+        return urlPath.replace(/\\/g, '/');
+    }
+    /**
+     * Normalizes the public source URL for one processed asset.
+     */
+    resolveProcessedAssetSrcUrl(processed) {
+        if (processed.srcUrl) {
+            if (this.isFilesystemPath(processed.srcUrl)) {
+                const srcUrlFromPath = this.getSrcUrl(processed.srcUrl);
+                if (srcUrlFromPath)
+                    return srcUrlFromPath;
+            }
+            else {
+                return processed.srcUrl;
+            }
         }
-        return Array.isArray(result) ? result : [result];
-      });
-      return [...processedTypeResults, ...groupedResults];
-    });
-    const allTypeResults = await Promise.all(groupPromises);
-    return allTypeResults.flat();
-  }
-  /**
-   * Groups dependencies by processor bucket.
-   */
-  groupDependenciesByType(deps) {
-    return deps.reduce(
-      (acc, dep) => {
-        const key = `${dep.kind}_${dep.source}`;
-        if (!acc[key]) acc[key] = [];
-        acc[key].push(dep);
-        return acc;
-      },
-      {}
-    );
-  }
-  /**
-   * Converts a dist-local file path into its public URL.
-   */
-  getSrcUrl(filepath) {
-    const distDir = this.config.absolutePaths.distDir;
-    if (!filepath.startsWith(distDir)) return void 0;
-    const relativePath = filepath.slice(distDir.length);
-    const urlPath = relativePath.startsWith("/") ? relativePath : `/${relativePath}`;
-    return urlPath.replace(/\\/g, "/");
-  }
-  /**
-   * Normalizes the public source URL for one processed asset.
-   */
-  resolveProcessedAssetSrcUrl(processed) {
-    if (processed.srcUrl) {
-      if (this.isFilesystemPath(processed.srcUrl)) {
-        const srcUrlFromPath = this.getSrcUrl(processed.srcUrl);
-        if (srcUrlFromPath) return srcUrlFromPath;
-      } else {
-        return processed.srcUrl;
-      }
+        if (processed.filepath) {
+            return this.getSrcUrl(processed.filepath);
+        }
+        return undefined;
     }
-    if (processed.filepath) {
-      return this.getSrcUrl(processed.filepath);
+    /**
+     * Returns whether a value should be interpreted as a filesystem path instead
+     * of an already-public URL.
+     */
+    isFilesystemPath(value) {
+        if (value.startsWith('http://') || value.startsWith('https://') || value.startsWith('//')) {
+            return false;
+        }
+        if (value.startsWith(this.config.absolutePaths.distDir)) {
+            return true;
+        }
+        const rootDir = this.config.rootDir;
+        if (rootDir && value.startsWith(rootDir)) {
+            return true;
+        }
+        return /^[A-Za-z]:\\/.test(value);
+    }
+    /**
+     * Applies post-processing for emitted production assets.
+     *
+     * @remarks
+     * Current optimization is intentionally conservative: only generated CSS and
+     * JavaScript files inside the app dist directory are gzipped.
+     */
+    async optimizeDependencies(processedAssets) {
+        if (process.env.NODE_ENV !== 'production') {
+            return;
+        }
+        const filesToGzip = new Set();
+        for (const asset of processedAssets) {
+            if (!asset.filepath) {
+                continue;
+            }
+            if (!asset.filepath.startsWith(this.config.absolutePaths.distDir)) {
+                continue;
+            }
+            const extension = path.extname(asset.filepath).slice(1);
+            if (extension === 'css' || extension === 'js') {
+                filesToGzip.add(asset.filepath);
+            }
+        }
+        for (const filePath of filesToGzip) {
+            if (fileSystem.exists(filePath)) {
+                fileSystem.gzipFile(filePath);
+            }
+        }
     }
-    return void 0;
-  }
-  /**
-   * Returns whether a value should be interpreted as a filesystem path instead
-   * of an already-public URL.
-   */
-  isFilesystemPath(value) {
-    if (value.startsWith("http://") || value.startsWith("https://") || value.startsWith("//")) {
-      return false;
+    /**
+     * Returns the cached processed asset for a dependency key when available.
+     */
+    getCachedAsset(dep, depKey) {
+        if (dep.kind === 'script' && dep.source === 'content') {
+            return this.getCachedContentScriptAsset(dep, depKey);
+        }
+        const sourceHash = this.getFileSourceHash(dep);
+        if (dep.source === 'file' && sourceHash === undefined) {
+            this.invalidateCachedAsset(depKey);
+            return null;
+        }
+        const cached = this.cache.get(depKey);
+        if (!cached) {
+            return null;
+        }
+        if (cached.sourceHash !== sourceHash) {
+            this.invalidateCachedAsset(depKey);
+            return null;
+        }
+        if (cached.asset.filepath && !fileSystem.exists(cached.asset.filepath)) {
+            this.invalidateCachedAsset(depKey);
+            return null;
+        }
+        return cached.asset;
     }
-    if (value.startsWith(this.config.absolutePaths.distDir)) {
-      return true;
+    getCachedContentScriptAsset(dep, depKey) {
+        const filepath = this.resolveCachedContentScriptFilepath(depKey);
+        if (!filepath) {
+            return null;
+        }
+        const materialized = materializeContentScriptAsset(dep, filepath);
+        this.cache.set(depKey, { asset: materialized });
+        return materialized;
     }
-    const rootDir = this.config.rootDir;
-    if (rootDir && value.startsWith(rootDir)) {
-      return true;
+    resolveCachedContentScriptFilepath(depKey) {
+        const cached = this.cache.get(depKey);
+        if (!cached?.asset.filepath) {
+            return undefined;
+        }
+        if (!fileSystem.exists(cached.asset.filepath)) {
+            this.cache.delete(depKey);
+            return undefined;
+        }
+        return cached.asset.filepath;
     }
-    return /^[A-Za-z]:\\/.test(value);
-  }
-  /**
-   * Applies post-processing for emitted production assets.
-   *
-   * @remarks
-   * Current optimization is intentionally conservative: only generated CSS and
-   * JavaScript files inside the app dist directory are gzipped.
-   */
-  async optimizeDependencies(processedAssets) {
-    if (process.env.NODE_ENV !== "production") {
-      return;
+    /**
+     * Stores one processed asset in the dependency cache.
+     */
+    setCachedAsset(dep, depKey, asset) {
+        const previous = this.cache.get(depKey)?.asset;
+        const tracksBrowserRuntimeGeneration = dep.packageRole === 'runtime' || dep.packageRole === 'page-script';
+        this.cache.set(depKey, {
+            asset,
+            sourceHash: this.getFileSourceHash(dep),
+        });
+        if (tracksBrowserRuntimeGeneration && previous !== undefined && previous.filepath !== asset.filepath) {
+            void bumpBrowserRuntimeAssetGeneration(this.config);
+        }
     }
-    const filesToGzip = /* @__PURE__ */ new Set();
-    for (const asset of processedAssets) {
-      if (!asset.filepath) {
-        continue;
-      }
-      if (!asset.filepath.startsWith(this.config.absolutePaths.distDir)) {
-        continue;
-      }
-      const extension = path.extname(asset.filepath).slice(1);
-      if (extension === "css" || extension === "js") {
-        filesToGzip.add(asset.filepath);
-      }
+    /**
+     * Removes a cached asset and advances the development HTML cache generation
+     * when the removed asset can determine browser runtime URLs.
+     */
+    invalidateCachedAsset(depKey) {
+        const cached = this.cache.get(depKey);
+        this.cache.delete(depKey);
+        if (cached?.asset.packageRole === 'runtime' || cached?.asset.packageRole === 'page-script') {
+            void bumpBrowserRuntimeAssetGeneration(this.config);
+        }
     }
-    for (const filePath of filesToGzip) {
-      if (fileSystem.exists(filePath)) {
-        fileSystem.gzipFile(filePath);
-      }
+    getFileSourceHash(dep) {
+        if (dep.source !== 'file' || !('filepath' in dep) || !fileSystem.exists(dep.filepath)) {
+            return undefined;
+        }
+        return fileSystem.hash(dep.filepath);
     }
-  }
-  /**
-   * Returns the cached processed asset for a dependency key when available.
-   */
-  getCachedAsset(dep, depKey) {
-    if (process.env.NODE_ENV !== "production" && dep.source === "file" && dep.kind === "stylesheet") {
-      return null;
+    /**
+     * Clears all cached processed assets.
+     */
+    clearCache() {
+        const invalidatesBrowserRuntime = Array.from(this.cache.values()).some(({ asset }) => asset.packageRole === 'runtime' || asset.packageRole === 'page-script');
+        this.cache.clear();
+        if (invalidatesBrowserRuntime) {
+            void bumpBrowserRuntimeAssetGeneration(this.config);
+        }
     }
-    const cached = this.cache.get(depKey);
-    if (!cached) {
-      return null;
+    /**
+     * Removes cached assets that were produced from the given file path.
+     */
+    invalidateCacheForFile(filepath) {
+        let invalidatesBrowserRuntime = false;
+        for (const [key, value] of this.cache.entries()) {
+            if (value.asset.filepath === filepath ||
+                value.asset.sourceFilepath === filepath ||
+                value.asset.bundledSourceFilepaths?.includes(filepath)) {
+                invalidatesBrowserRuntime ||=
+                    value.asset.packageRole === 'runtime' || value.asset.packageRole === 'page-script';
+                this.cache.delete(key);
+            }
+        }
+        if (invalidatesBrowserRuntime) {
+            void bumpBrowserRuntimeAssetGeneration(this.config);
+        }
     }
-    if (cached.asset.filepath && !fileSystem.exists(cached.asset.filepath)) {
-      this.cache.delete(depKey);
-      return null;
+    /**
+     * Creates a service prewired with the default core processors.
+     */
+    static createWithDefaultProcessors(appConfig) {
+        const service = new AssetProcessingService(appConfig);
+        service.registerProcessor('script', 'content', new ContentScriptProcessor({ appConfig }));
+        service.registerProcessor('script', 'file', new FileScriptProcessor({ appConfig }));
+        service.registerProcessor('script', 'node-module', new NodeModuleScriptProcessor({ appConfig }));
+        service.registerProcessor('stylesheet', 'content', new ContentStylesheetProcessor({ appConfig }));
+        service.registerProcessor('stylesheet', 'file', new FileStylesheetProcessor({ appConfig }));
+        return service;
     }
-    return cached.asset;
-  }
-  /**
-   * Stores one processed asset in the dependency cache.
-   */
-  setCachedAsset(dep, depKey, asset) {
-    this.cache.set(depKey, { asset });
-  }
-  /**
-   * Clears all cached processed assets.
-   */
-  clearCache() {
-    this.cache.clear();
-  }
-  /**
-   * Removes cached assets that were produced from the given file path.
-   */
-  invalidateCacheForFile(filepath) {
-    for (const [key, value] of this.cache.entries()) {
-      if (value.asset.filepath === filepath) {
-        this.cache.delete(key);
-      }
+    /**
+     * Returns the processor registry owned by this service.
+     */
+    getRegistry() {
+        return this.registry;
     }
-  }
-  /**
-   * Creates a service prewired with the default core processors.
-   */
-  static createWithDefaultProcessors(appConfig) {
-    const service = new AssetProcessingService(appConfig);
-    service.registerProcessor("script", "content", new ContentScriptProcessor({ appConfig }));
-    service.registerProcessor("script", "file", new FileScriptProcessor({ appConfig }));
-    service.registerProcessor("script", "node-module", new NodeModuleScriptProcessor({ appConfig }));
-    service.registerProcessor("stylesheet", "content", new ContentStylesheetProcessor({ appConfig }));
-    service.registerProcessor("stylesheet", "file", new FileStylesheetProcessor({ appConfig }));
-    return service;
-  }
-  /**
-   * Returns the processor registry owned by this service.
-   */
-  getRegistry() {
-    return this.registry;
-  }
 }
-export {
-  AssetProcessingService
-};