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

package/src/route-renderer/orchestration/page-browser-graph/page-browser-graph-session.js

@@ -0,0 +1,542 @@
+import path from 'node:path';
+import { serializeGroupedGraphCacheKey } from './route-instance-key.js';
+import { createHash } from 'node:crypto';
+import { appLogger } from '../../../global/app-logger.js';
+function isSkipCacheGroupedOutcome(outcome) {
+    return 'skipCache' in outcome;
+}
+function serializeGraphKey(key) {
+    return JSON.stringify([
+        'graph',
+        key.policy,
+        key.integrationName,
+        key.routeFile,
+        key.dependencyInstanceKey,
+        key.entryFingerprint,
+    ]);
+}
+function normalizeDependencyPath(filePath) {
+    return path.resolve(filePath);
+}
+function parseSerializedGraphKey(serializedKey) {
+    let parsed;
+    try {
+        parsed = JSON.parse(serializedKey);
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(parsed) ||
+        parsed.length !== 6 ||
+        parsed[0] !== 'graph' ||
+        typeof parsed[1] !== 'string' ||
+        typeof parsed[2] !== 'string' ||
+        typeof parsed[3] !== 'string' ||
+        typeof parsed[4] !== 'string' ||
+        typeof parsed[5] !== 'string') {
+        return undefined;
+    }
+    const [, policy, integrationName, routeFile, dependencyInstanceKey, entryFingerprint] = parsed;
+    if (policy !== 'development' && policy !== 'production') {
+        return undefined;
+    }
+    return {
+        policy,
+        integrationName,
+        routeFile,
+        dependencyInstanceKey,
+        entryFingerprint,
+    };
+}
+/**
+ * Reverse index from dependency paths to graph cache keys.
+ */
+export class GraphDependencyIndex {
+    dependencyToGraphKeys = new Map();
+    bindRecord(record) {
+        const serializedKey = serializeGraphKey(record.key);
+        for (const dependencyPath of record.dependencyPaths) {
+            this.addDependencyBinding(normalizeDependencyPath(dependencyPath), serializedKey);
+        }
+    }
+    unbindRecord(record) {
+        const serializedKey = serializeGraphKey(record.key);
+        for (const dependencyPath of record.dependencyPaths) {
+            this.removeDependencyBinding(normalizeDependencyPath(dependencyPath), serializedKey);
+        }
+    }
+    bindGroupedRecord(cacheKey, record) {
+        for (const dependencyPath of record.dependencyPaths) {
+            this.addDependencyBinding(normalizeDependencyPath(dependencyPath), cacheKey);
+        }
+    }
+    unbindGroupedRecord(cacheKey, record) {
+        for (const dependencyPath of record.dependencyPaths) {
+            this.removeDependencyBinding(normalizeDependencyPath(dependencyPath), cacheKey);
+        }
+    }
+    bindPaths(serializedKey, dependencyPaths) {
+        for (const dependencyPath of dependencyPaths) {
+            this.addDependencyBinding(normalizeDependencyPath(dependencyPath), serializedKey);
+        }
+    }
+    unbindPaths(serializedKey, dependencyPaths) {
+        for (const dependencyPath of dependencyPaths) {
+            this.removeDependencyBinding(normalizeDependencyPath(dependencyPath), serializedKey);
+        }
+    }
+    getAffectedKeys(filePath) {
+        return new Set(this.dependencyToGraphKeys.get(normalizeDependencyPath(filePath)) ?? []);
+    }
+    resetForTests() {
+        this.dependencyToGraphKeys.clear();
+    }
+    addDependencyBinding(dependencyPath, serializedKey) {
+        const graphKeys = this.dependencyToGraphKeys.get(dependencyPath) ?? new Set();
+        graphKeys.add(serializedKey);
+        this.dependencyToGraphKeys.set(dependencyPath, graphKeys);
+    }
+    removeDependencyBinding(dependencyPath, serializedKey) {
+        const graphKeys = this.dependencyToGraphKeys.get(dependencyPath);
+        if (!graphKeys) {
+            return;
+        }
+        graphKeys.delete(serializedKey);
+        if (graphKeys.size === 0) {
+            this.dependencyToGraphKeys.delete(dependencyPath);
+        }
+    }
+}
+/**
+ * Session-local Page Browser Graph cache with precise dependency invalidation.
+ */
+export class SessionPageBrowserGraphCache {
+    records = new Map();
+    inFlight = new Map();
+    inFlightDependencyPaths = new Map();
+    inFlightGenerations = new Map();
+    groupedRecords = new Map();
+    groupedInFlight = new Map();
+    dependencyIndex = new GraphDependencyIndex();
+    graphGenerations = new Map();
+    groupedGenerations = new Map();
+    buildCount = 0;
+    /**
+     * Page Browser Graph compilations in this dev-server session.
+     */
+    getBuildCount() {
+        return this.buildCount;
+    }
+    getGraphByRoute(integrationName, routeFile, policy, dependencyInstanceKey = '') {
+        const normalizedRoute = normalizeDependencyPath(routeFile);
+        for (const record of this.records.values()) {
+            if (record.key.integrationName === integrationName &&
+                record.key.policy === policy &&
+                normalizeDependencyPath(record.key.routeFile) === normalizedRoute &&
+                record.key.dependencyInstanceKey === dependencyInstanceKey) {
+                return record.result;
+            }
+        }
+        return undefined;
+    }
+    getDependencyPathsByRoute(integrationName, routeFile, policy, dependencyInstanceKey = '') {
+        const normalizedRoute = normalizeDependencyPath(routeFile);
+        for (const record of this.records.values()) {
+            if (record.key.integrationName === integrationName &&
+                record.key.policy === policy &&
+                normalizeDependencyPath(record.key.routeFile) === normalizedRoute &&
+                record.key.dependencyInstanceKey === dependencyInstanceKey) {
+                return record.dependencyPaths;
+            }
+        }
+        return undefined;
+    }
+    getAffectedGraphIdentities(filePath) {
+        const identities = [];
+        for (const serializedKey of this.dependencyIndex.getAffectedKeys(filePath)) {
+            const identity = parseSerializedGraphKey(serializedKey);
+            if (identity) {
+                identities.push(identity);
+            }
+        }
+        return identities;
+    }
+    resolveGraph(key, provisionalDependencyPaths, build) {
+        const serializedKey = serializeGraphKey(key);
+        const cached = this.records.get(serializedKey);
+        if (cached) {
+            return Promise.resolve(cached.result);
+        }
+        const pending = this.inFlight.get(serializedKey);
+        if (pending) {
+            return pending;
+        }
+        const buildGeneration = this.bumpGraphGeneration(serializedKey);
+        this.inFlightDependencyPaths.set(serializedKey, provisionalDependencyPaths);
+        this.inFlightGenerations.set(serializedKey, buildGeneration);
+        this.bindDependencyPaths(serializedKey, provisionalDependencyPaths);
+        const buildPromise = this.runGraphBuild(serializedKey, key, buildGeneration, build);
+        this.inFlight.set(serializedKey, buildPromise);
+        return buildPromise;
+    }
+    resolveGroupedGraph(scope, build) {
+        const cacheKey = serializeGroupedGraphCacheKey(scope);
+        const cached = this.groupedRecords.get(cacheKey);
+        if (cached) {
+            return Promise.resolve(cached.assetsByRoute);
+        }
+        const pending = this.groupedInFlight.get(cacheKey);
+        if (pending) {
+            return pending;
+        }
+        const buildGeneration = this.bumpGroupedGeneration(cacheKey);
+        const buildPromise = this.runGroupedBuild(cacheKey, buildGeneration, build);
+        this.groupedInFlight.set(cacheKey, buildPromise);
+        return buildPromise;
+    }
+    peekGroupedGraph(scope) {
+        return this.groupedRecords.get(serializeGroupedGraphCacheKey(scope))?.assetsByRoute;
+    }
+    invalidateByFilePath(filePath) {
+        const normalizedFilePath = normalizeDependencyPath(filePath);
+        const affectedKeys = this.dependencyIndex.getAffectedKeys(normalizedFilePath);
+        let invalidated = 0;
+        for (const serializedKey of affectedKeys) {
+            if (this.groupedRecords.has(serializedKey) || this.groupedInFlight.has(serializedKey)) {
+                invalidated += this.invalidateGroupedRecord(serializedKey);
+                continue;
+            }
+            invalidated += this.invalidateSerializedGraphKey(serializedKey);
+        }
+        for (const serializedKey of this.inFlight.keys()) {
+            const identity = parseSerializedGraphKey(serializedKey);
+            if (!identity) {
+                continue;
+            }
+            if (normalizeDependencyPath(identity.routeFile) !== normalizedFilePath) {
+                continue;
+            }
+            if (affectedKeys.has(serializedKey)) {
+                continue;
+            }
+            invalidated += this.invalidateSerializedGraphKey(serializedKey);
+        }
+        if (invalidated > 0) {
+            appLogger.debug(`[PageBrowserGraphSession] invalidated ${invalidated} graph record(s) for ${normalizedFilePath}`);
+        }
+        return invalidated;
+    }
+    invalidateRoute(integrationName, routeFile) {
+        const normalizedRoute = normalizeDependencyPath(routeFile);
+        for (const [serializedKey, record] of this.records) {
+            if (record.key.integrationName !== integrationName) {
+                continue;
+            }
+            if (normalizeDependencyPath(record.key.routeFile) !== normalizedRoute) {
+                continue;
+            }
+            this.invalidateSerializedGraphKey(serializedKey);
+        }
+    }
+    invalidateByRouteFile(routeFile) {
+        const normalizedRoute = normalizeDependencyPath(routeFile);
+        for (const [serializedKey, record] of this.records) {
+            if (normalizeDependencyPath(record.key.routeFile) !== normalizedRoute) {
+                continue;
+            }
+            this.invalidateSerializedGraphKey(serializedKey);
+        }
+    }
+    resetForTests() {
+        this.records.clear();
+        this.inFlight.clear();
+        this.inFlightDependencyPaths.clear();
+        this.inFlightGenerations.clear();
+        this.groupedRecords.clear();
+        this.groupedInFlight.clear();
+        this.graphGenerations.clear();
+        this.groupedGenerations.clear();
+        this.dependencyIndex.resetForTests();
+        this.buildCount = 0;
+    }
+    exportRecords(policy) {
+        return [...this.records.values()].filter((record) => record.key.policy === policy);
+    }
+    clearPolicyRecords(policy) {
+        for (const [serializedKey, record] of this.records) {
+            if (record.key.policy !== policy) {
+                continue;
+            }
+            this.dependencyIndex.unbindRecord(record);
+            this.records.delete(serializedKey);
+            this.inFlight.delete(serializedKey);
+            const inFlightDependencyPaths = this.inFlightDependencyPaths.get(serializedKey);
+            if (inFlightDependencyPaths) {
+                this.unbindDependencyPaths(serializedKey, inFlightDependencyPaths);
+                this.inFlightDependencyPaths.delete(serializedKey);
+            }
+            this.inFlightGenerations.delete(serializedKey);
+            this.graphGenerations.delete(serializedKey);
+        }
+        if (policy === 'production') {
+            for (const cacheKey of [...this.groupedRecords.keys()]) {
+                const groupedRecord = this.groupedRecords.get(cacheKey);
+                if (groupedRecord) {
+                    this.dependencyIndex.unbindGroupedRecord(cacheKey, groupedRecord);
+                }
+                this.groupedRecords.delete(cacheKey);
+                this.groupedInFlight.delete(cacheKey);
+                this.groupedGenerations.delete(cacheKey);
+            }
+        }
+    }
+    pruneStaleRouteRecords(key) {
+        const normalizedRoute = normalizeDependencyPath(key.routeFile);
+        for (const [serializedKey, record] of this.records) {
+            if (record.key.integrationName !== key.integrationName) {
+                continue;
+            }
+            if (normalizeDependencyPath(record.key.routeFile) !== normalizedRoute) {
+                continue;
+            }
+            if (record.key.dependencyInstanceKey !== key.dependencyInstanceKey) {
+                continue;
+            }
+            if (record.key.entryFingerprint === key.entryFingerprint && record.key.policy === key.policy) {
+                continue;
+            }
+            this.invalidateSerializedGraphKey(serializedKey);
+        }
+    }
+    bumpGraphGeneration(serializedKey) {
+        const next = (this.graphGenerations.get(serializedKey) ?? 0) + 1;
+        this.graphGenerations.set(serializedKey, next);
+        return next;
+    }
+    bumpGroupedGeneration(cacheKey) {
+        const next = (this.groupedGenerations.get(cacheKey) ?? 0) + 1;
+        this.groupedGenerations.set(cacheKey, next);
+        return next;
+    }
+    invalidateSerializedGraphKey(serializedKey) {
+        const record = this.records.get(serializedKey);
+        if (record) {
+            this.dependencyIndex.unbindRecord(record);
+            this.records.delete(serializedKey);
+        }
+        const inFlightDependencyPaths = this.inFlightDependencyPaths.get(serializedKey);
+        if (inFlightDependencyPaths) {
+            this.unbindDependencyPaths(serializedKey, inFlightDependencyPaths);
+            this.inFlightDependencyPaths.delete(serializedKey);
+        }
+        const hadInFlightBuild = this.inFlight.delete(serializedKey);
+        this.inFlightGenerations.delete(serializedKey);
+        this.bumpGraphGeneration(serializedKey);
+        return record || hadInFlightBuild ? 1 : 0;
+    }
+    invalidateGroupedRecord(cacheKey) {
+        const groupedRecord = this.groupedRecords.get(cacheKey);
+        if (groupedRecord) {
+            this.dependencyIndex.unbindGroupedRecord(cacheKey, groupedRecord);
+            this.groupedRecords.delete(cacheKey);
+        }
+        this.bumpGroupedGeneration(cacheKey);
+        this.groupedInFlight.delete(cacheKey);
+        return groupedRecord ? 1 : 0;
+    }
+    async runGraphBuild(serializedKey, key, buildGeneration, build) {
+        try {
+            this.buildCount += 1;
+            const buildResult = await build();
+            if (!buildResult) {
+                return undefined;
+            }
+            if (!this.canCommitGraphBuild(serializedKey, buildGeneration)) {
+                const existing = this.records.get(serializedKey);
+                return existing?.result;
+            }
+            if (buildResult.cacheable === false) {
+                this.releaseInFlightDependencyPaths(serializedKey, buildGeneration);
+                return buildResult.result;
+            }
+            this.releaseInFlightDependencyPaths(serializedKey, buildGeneration);
+            this.pruneStaleRouteRecords(key);
+            const previous = this.records.get(serializedKey);
+            if (previous) {
+                this.dependencyIndex.unbindRecord(previous);
+            }
+            const record = {
+                key,
+                result: buildResult.result,
+                dependencyPaths: buildResult.dependencyPaths,
+                committedAt: Date.now(),
+                generation: buildGeneration,
+            };
+            this.records.set(serializedKey, record);
+            this.dependencyIndex.bindRecord(record);
+            return record.result;
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        finally {
+            this.clearInFlightBuild(serializedKey, buildGeneration);
+        }
+    }
+    async runGroupedBuild(cacheKey, buildGeneration, build) {
+        try {
+            this.buildCount += 1;
+            const buildResult = await build();
+            if (!buildResult) {
+                return new Map();
+            }
+            if (isSkipCacheGroupedOutcome(buildResult)) {
+                return buildResult.assetsByRoute;
+            }
+            if (!this.canCommitGroupedBuild(cacheKey, buildGeneration)) {
+                const existing = this.groupedRecords.get(cacheKey);
+                return existing?.assetsByRoute ?? new Map();
+            }
+            const previous = this.groupedRecords.get(cacheKey);
+            if (previous) {
+                this.dependencyIndex.unbindGroupedRecord(cacheKey, previous);
+            }
+            const record = {
+                assetsByRoute: buildResult.assetsByRoute,
+                dependencyPaths: buildResult.dependencyPaths,
+                generation: buildGeneration,
+            };
+            this.groupedRecords.set(cacheKey, record);
+            this.dependencyIndex.bindGroupedRecord(cacheKey, record);
+            return record.assetsByRoute;
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        finally {
+            this.groupedInFlight.delete(cacheKey);
+        }
+    }
+    canCommitGraphBuild(serializedKey, buildGeneration) {
+        return this.graphGenerations.get(serializedKey) === buildGeneration;
+    }
+    canCommitGroupedBuild(cacheKey, buildGeneration) {
+        return this.groupedGenerations.get(cacheKey) === buildGeneration;
+    }
+    bindDependencyPaths(serializedKey, dependencyPaths) {
+        this.dependencyIndex.bindPaths(serializedKey, dependencyPaths);
+    }
+    unbindDependencyPaths(serializedKey, dependencyPaths) {
+        this.dependencyIndex.unbindPaths(serializedKey, dependencyPaths);
+    }
+    clearInFlightBuild(serializedKey, buildGeneration) {
+        if (this.inFlightGenerations.get(serializedKey) !== buildGeneration) {
+            return;
+        }
+        this.releaseInFlightDependencyPaths(serializedKey, buildGeneration);
+        this.inFlight.delete(serializedKey);
+        this.inFlightGenerations.delete(serializedKey);
+    }
+    releaseInFlightDependencyPaths(serializedKey, buildGeneration) {
+        if (this.inFlightGenerations.get(serializedKey) !== buildGeneration) {
+            return;
+        }
+        const dependencyPaths = this.inFlightDependencyPaths.get(serializedKey);
+        if (!dependencyPaths) {
+            return;
+        }
+        this.unbindDependencyPaths(serializedKey, dependencyPaths);
+        this.inFlightDependencyPaths.delete(serializedKey);
+    }
+}
+const sessionByAppConfig = new WeakMap();
+/**
+ * Returns the session graph cache for one app instance.
+ */
+export function getAppPageBrowserGraphSession(appConfig) {
+    const existing = appConfig.runtime?.pageBrowserGraphSession;
+    if (existing) {
+        return existing;
+    }
+    const cached = sessionByAppConfig.get(appConfig);
+    if (cached) {
+        return cached;
+    }
+    const session = new SessionPageBrowserGraphCache();
+    sessionByAppConfig.set(appConfig, session);
+    appConfig.runtime = {
+        ...(appConfig.runtime ?? {}),
+        pageBrowserGraphSession: session,
+    };
+    return session;
+}
+/**
+ * Invalidates graph records that depend on the changed file path.
+ */
+export function invalidatePageBrowserGraphSession(appConfig, filePath) {
+    return getAppPageBrowserGraphSession(appConfig).invalidateByFilePath(filePath);
+}
+/**
+ * Returns graph identities affected by a source file change.
+ */
+export function getAffectedPageBrowserGraphIdentities(appConfig, filePath) {
+    return getAppPageBrowserGraphSession(appConfig).getAffectedGraphIdentities(filePath);
+}
+/**
+ * Builds a stable fingerprint from declared browser-entry dependencies and assets.
+ */
+export function createPageBrowserGraphEntryFingerprint(contribution) {
+    const descriptors = [
+        ...(contribution.dependencies ?? []).map((dependency) => describeAssetDependency(dependency)),
+        ...(contribution.assets ?? []).map((asset) => describeProcessedAsset(asset)),
+    ].sort((left, right) => left.localeCompare(right));
+    return descriptors.join('|') || 'empty';
+}
+/**
+ * Collects dependency paths used for graph invalidation.
+ */
+export function collectPageBrowserGraphDependencyPaths(routeFile, contribution, processedAssets) {
+    const dependencyPaths = new Set([normalizeDependencyPath(routeFile)]);
+    for (const dependency of contribution.dependencies ?? []) {
+        if (dependency.source === 'file') {
+            dependencyPaths.add(normalizeDependencyPath(dependency.filepath));
+        }
+    }
+    for (const asset of processedAssets) {
+        if (asset.sourceFilepath) {
+            dependencyPaths.add(normalizeDependencyPath(asset.sourceFilepath));
+        }
+        for (const bundledSourceFilepath of asset.bundledSourceFilepaths ?? []) {
+            dependencyPaths.add(normalizeDependencyPath(bundledSourceFilepath));
+        }
+    }
+    for (const watchPath of contribution.watchPaths ?? []) {
+        dependencyPaths.add(normalizeDependencyPath(watchPath));
+    }
+    return dependencyPaths;
+}
+function describeProcessedAsset(asset) {
+    const filepath = asset.filepath ?? '';
+    const sourceFilepath = asset.sourceFilepath ?? '';
+    const content = typeof asset.content === 'string' ? asset.content : '';
+    const contentDigest = content ? createHash('sha1').update(content).digest('hex').slice(0, 12) : '';
+    return `asset:${asset.kind}:${filepath}:${sourceFilepath}:${contentDigest}`;
+}
+function describeAssetDependency(dependency) {
+    switch (dependency.source) {
+        case 'file':
+            return `file:${dependency.filepath}`;
+        case 'node-module':
+            return `module:${dependency.importPath}`;
+        case 'content': {
+            const content = typeof dependency.content === 'string' ? dependency.content : '';
+            const contentDigest = createHash('sha1').update(content).digest('hex').slice(0, 12);
+            const name = 'name' in dependency && typeof dependency.name === 'string' ? dependency.name : '';
+            return `content:${dependency.kind}:${name}:${contentDigest}`;
+        }
+        default: {
+            const exhaustive = dependency;
+            return String(exhaustive);
+        }
+    }
+}

package/src/route-renderer/orchestration/page-browser-graph/page-browser-graph.service.d.ts

@@ -0,0 +1,47 @@
+import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
+import type { PageBrowserGraphContribution, PageBrowserGraphResult } from '../../../types/public-types.js';
+import { type AssetProcessingService } from '../../../services/assets/asset-processing-service/index.js';
+import { type GraphPolicy } from './page-browser-graph-session.js';
+import type { GroupedGraphBuildPlan } from './grouped-graph-build-plan.js';
+export type GroupedPageBrowserGraphContribution = {
+    routeFile: string;
+    dependencyInstanceKey: string;
+    contribution: PageBrowserGraphContribution | undefined;
+};
+export type PageBrowserGraphResolveInput = {
+    routeFile: string;
+    dependencyInstanceKey?: string;
+    integrationName: string;
+    collectContribution: () => Promise<PageBrowserGraphContribution | undefined>;
+    groupedBuildPlan?: GroupedGraphBuildPlan;
+    policy?: GraphPolicy;
+};
+/**
+ * Resolves declarative page browser graph assets for one route and integration.
+ */
+export declare class PageBrowserGraphService {
+    private readonly appConfig;
+    private readonly assetProcessingService;
+    constructor(appConfig: EcoPagesAppConfig, assetProcessingService: AssetProcessingService);
+    resolvePageBrowserGraph(input: PageBrowserGraphResolveInput): Promise<PageBrowserGraphResult | undefined>;
+    /**
+     * Returns dependency paths recorded for one resolved Page Browser Graph.
+     */
+    getDependencyPathsForRoute(input: {
+        integrationName: string;
+        routeFile: string;
+        dependencyInstanceKey?: string;
+        policy?: GraphPolicy;
+    }): ReadonlySet<string> | undefined;
+    /**
+     * Resolves or builds one Page Browser Graph under the given policy.
+     */
+    getOrBuild(input: PageBrowserGraphResolveInput): Promise<PageBrowserGraphResult | undefined>;
+    private resolveGraphPolicy;
+    private isHmrEnabled;
+    private buildPageBrowserGraphRecord;
+    private materializePageBrowserGraph;
+    private resolveGroupedPageBrowserAssets;
+    private buildGroupedPageBrowserAssets;
+    private partitionPageBrowserGraphAssets;
+}