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

package/src/dev/transform-server/dev-transform-import-rewriter.js

@@ -0,0 +1,127 @@
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { cachedParseSync } from '../../cache/module-parse-cache.js';
+import { isBarePackageImportSpecifier, resolveProjectModulePath } from '../../plugins/tsconfig-import-resolver.js';
+import { resolveRuntimeSpecifierPublicPath } from '../../build/browser/browser-runtime-manifest.js';
+import { resolveDevTransformModuleUrl } from './dev-transform-url.js';
+/**
+ * Builds a browser-importable dev-transform URL that changes when the source changes.
+ *
+ * @remarks
+ * Soft HMR reloads cache-bust the active page module, but transitive layout/component
+ * imports keep stable pathnames. A content hash query makes the browser ESM module map
+ * treat the updated dependency as a new module without a full page reload.
+ */
+function resolveVersionedDevTransformModuleUrl(srcDir, resolvedPath) {
+    const baseUrl = resolveDevTransformModuleUrl(srcDir, resolvedPath);
+    if (!fileSystem.exists(resolvedPath)) {
+        return baseUrl;
+    }
+    return `${baseUrl}?v=${fileSystem.hash(resolvedPath)}`;
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object';
+}
+function readStringLiteral(node) {
+    if (!isRecord(node)) {
+        return undefined;
+    }
+    if (node.type !== 'StringLiteral' && node.type !== 'Literal') {
+        return undefined;
+    }
+    if (typeof node.value !== 'string' || typeof node.start !== 'number' || typeof node.end !== 'number') {
+        return undefined;
+    }
+    return { start: node.start, end: node.end, value: node.value };
+}
+/**
+ * Rewrites static and dynamic import specifiers to dev-transform or vendor URLs.
+ */
+export async function rewriteModuleImports(options) {
+    const normalizedSource = path.resolve(options.sourcePath);
+    const dependencies = new Set();
+    const specifierNodes = [];
+    const parseResult = cachedParseSync(normalizedSource, options.code, {
+        sourceType: 'module',
+        lang: path.extname(normalizedSource).endsWith('x') ? 'tsx' : 'ts',
+    });
+    const walk = (node) => {
+        if (!isRecord(node)) {
+            return;
+        }
+        if (node.type === 'ImportDeclaration' ||
+            node.type === 'ExportNamedDeclaration' ||
+            node.type === 'ExportAllDeclaration') {
+            const literal = readStringLiteral(node.source);
+            if (literal) {
+                specifierNodes.push(literal);
+            }
+        }
+        if (node.type === 'ImportExpression') {
+            const literal = readStringLiteral(node.source);
+            if (literal) {
+                specifierNodes.push(literal);
+            }
+        }
+        for (const value of Object.values(node)) {
+            if (Array.isArray(value)) {
+                for (const child of value) {
+                    walk(child);
+                }
+            }
+            else {
+                walk(value);
+            }
+        }
+    };
+    walk(parseResult.program);
+    const edits = [];
+    for (const specifierNode of specifierNodes) {
+        const rewritten = await resolveImportSpecifier({
+            specifier: specifierNode.value,
+            sourcePath: normalizedSource,
+            srcDir: options.srcDir,
+            projectRoot: options.projectRoot,
+            runtimeSpecifierMap: options.runtimeSpecifierMap,
+            resolveVendorUrl: options.resolveVendorUrl,
+            dependencies,
+        });
+        if (!rewritten || rewritten === specifierNode.value) {
+            continue;
+        }
+        const quote = options.code[specifierNode.start] === "'" ? "'" : '"';
+        edits.push({
+            start: specifierNode.start,
+            end: specifierNode.end,
+            replacement: `${quote}${rewritten}${quote}`,
+        });
+    }
+    edits.sort((left, right) => right.start - left.start);
+    let code = options.code;
+    for (const edit of edits) {
+        code = `${code.slice(0, edit.start)}${edit.replacement}${code.slice(edit.end)}`;
+    }
+    return {
+        code,
+        dependencies: [...dependencies],
+    };
+}
+async function resolveImportSpecifier(options) {
+    const runtimeUrl = resolveRuntimeSpecifierPublicPath(options.specifier, options.runtimeSpecifierMap);
+    if (runtimeUrl) {
+        return runtimeUrl;
+    }
+    if (options.specifier.startsWith('node:')) {
+        throw new Error(`[dev-transform] Node builtin "${options.specifier}" imported from client module ${options.sourcePath}. ` +
+            `Check package "browser" exports / client-graph boundary for the importer.`);
+    }
+    if (options.specifier.startsWith('.') || !isBarePackageImportSpecifier(options.specifier, options.projectRoot)) {
+        const resolvedPath = resolveProjectModulePath(options.projectRoot, options.sourcePath, options.specifier);
+        if (!resolvedPath) {
+            return undefined;
+        }
+        options.dependencies.add(resolvedPath);
+        return resolveVersionedDevTransformModuleUrl(options.srcDir, resolvedPath);
+    }
+    return options.resolveVendorUrl(options.specifier);
+}

package/src/dev/transform-server/dev-transform-module-kind.d.ts

@@ -0,0 +1,13 @@
+export type DevTransformModuleKind = 'script' | 'stylesheet';
+/**
+ * Classifies a dev-transform source path for materialization.
+ */
+export declare function resolveDevTransformModuleKind(sourcePath: string): DevTransformModuleKind;
+/**
+ * Emits browser ESM for a stylesheet import (`import styles from './x.css'`).
+ *
+ * @remarks
+ * Parallels the server-side CSS shim: CSS stays in the module graph as a string
+ * export while real stylesheet delivery uses `dependencies.stylesheets`.
+ */
+export declare function materializeDevTransformStylesheet(cssContent: string): string;

package/src/dev/transform-server/dev-transform-module-kind.js

@@ -0,0 +1,17 @@
+import path from 'node:path';
+/**
+ * Classifies a dev-transform source path for materialization.
+ */
+export function resolveDevTransformModuleKind(sourcePath) {
+    return path.extname(sourcePath) === '.css' ? 'stylesheet' : 'script';
+}
+/**
+ * Emits browser ESM for a stylesheet import (`import styles from './x.css'`).
+ *
+ * @remarks
+ * Parallels the server-side CSS shim: CSS stays in the module graph as a string
+ * export while real stylesheet delivery uses `dependencies.stylesheets`.
+ */
+export function materializeDevTransformStylesheet(cssContent) {
+    return `export default ${JSON.stringify(cssContent)};\n`;
+}

package/src/dev/transform-server/dev-transform-runtime-specifiers.d.ts

@@ -0,0 +1,5 @@
+import type { DevTransformBundleContributor } from './types.js';
+/**
+ * Merges runtime manifest specifiers from all dev-transform contributors.
+ */
+export declare function mergeContributorRuntimeSpecifierMaps(contributors: readonly DevTransformBundleContributor[]): Map<string, string>;

package/src/dev/transform-server/dev-transform-runtime-specifiers.js

@@ -0,0 +1,16 @@
+/**
+ * Merges runtime manifest specifiers from all dev-transform contributors.
+ */
+export function mergeContributorRuntimeSpecifierMaps(contributors) {
+    const merged = new Map();
+    for (const contributor of contributors) {
+        const runtimeSpecifierMap = contributor.getRuntimeSpecifierMap?.();
+        if (!runtimeSpecifierMap) {
+            continue;
+        }
+        for (const [specifier, url] of runtimeSpecifierMap) {
+            merged.set(specifier, url);
+        }
+    }
+    return merged;
+}

package/src/dev/transform-server/dev-transform-server.d.ts

@@ -0,0 +1,41 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { DevTransformBundleContributor } from './types.js';
+export type DevTransformServerOptions = {
+    appConfig: EcoPagesAppConfig;
+    contributors?: readonly DevTransformBundleContributor[];
+    onModuleDependencies?: (modulePath: string, dependencies: string[]) => void;
+};
+/**
+ * Serves per-module browser ESM on demand during native CLI dev.
+ *
+ * @remarks
+ * Registration returns a stable URL immediately; the first request (or a cache miss)
+ * transpiles one source file and rewrites imports to dev-transform or vendor URLs.
+ */
+export declare class DevTransformServer {
+    private readonly appConfig;
+    private readonly bundler;
+    private readonly vendorRegistry;
+    private readonly contributors;
+    private readonly runtimeSpecifierMap;
+    private readonly onModuleDependencies?;
+    private readonly urlToSource;
+    private readonly sourceToUrl;
+    private readonly cache;
+    private readonly inFlight;
+    private cacheGeneration;
+    constructor(options: DevTransformServerOptions);
+    registerModule(sourcePath: string): string;
+    getRegisteredSourcePath(moduleUrl: string): string | undefined;
+    addContributor(contributor: DevTransformBundleContributor): void;
+    private rebuildRuntimeSpecifierMap;
+    private resolveVendorBundlePlugins;
+    getWatchedModules(): ReadonlyMap<string, string>;
+    invalidateSource(sourcePath: string): void;
+    invalidateAll(): void;
+    reset(): void;
+    tryHandleRequest(request: Request): Promise<Response | null>;
+    private resolveSourcePathFromModuleUrl;
+    private createJavaScriptResponse;
+    private materialize;
+}

package/src/dev/transform-server/dev-transform-server.js

@@ -0,0 +1,191 @@
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { appLogger } from '../../global/app-logger.js';
+import { startupTrace } from '../../diagnostics/startup-trace.js';
+import { DevTransformBundler } from './dev-transform-bundler.js';
+import { DevTransformVendorRegistry } from './dev-transform-vendor-registry.js';
+import { materializeDevTransformStylesheet, resolveDevTransformModuleKind } from './dev-transform-module-kind.js';
+import { mergeContributorRuntimeSpecifierMaps } from './dev-transform-runtime-specifiers.js';
+import { resolveDevTransformModuleSourcePath, resolveDevTransformModuleUrl } from './dev-transform-url.js';
+/**
+ * Serves per-module browser ESM on demand during native CLI dev.
+ *
+ * @remarks
+ * Registration returns a stable URL immediately; the first request (or a cache miss)
+ * transpiles one source file and rewrites imports to dev-transform or vendor URLs.
+ */
+export class DevTransformServer {
+    appConfig;
+    bundler;
+    vendorRegistry;
+    contributors = [];
+    runtimeSpecifierMap = new Map();
+    onModuleDependencies;
+    urlToSource = new Map();
+    sourceToUrl = new Map();
+    cache = new Map();
+    inFlight = new Map();
+    cacheGeneration = 0;
+    constructor(options) {
+        this.appConfig = options.appConfig;
+        this.onModuleDependencies = options.onModuleDependencies;
+        this.contributors.push(...(options.contributors ?? []));
+        this.rebuildRuntimeSpecifierMap();
+        this.vendorRegistry = new DevTransformVendorRegistry({
+            appConfig: options.appConfig,
+            getRuntimeSpecifierMap: () => this.runtimeSpecifierMap,
+            resolveVendorBundlePlugins: () => this.resolveVendorBundlePlugins(),
+        });
+        this.bundler = new DevTransformBundler({
+            appConfig: options.appConfig,
+            contributors: this.contributors,
+            getRuntimeSpecifierMap: () => this.runtimeSpecifierMap,
+            vendorRegistry: this.vendorRegistry,
+        });
+    }
+    registerModule(sourcePath) {
+        const normalized = path.resolve(sourcePath);
+        const existing = this.sourceToUrl.get(normalized);
+        if (existing) {
+            return existing;
+        }
+        const url = resolveDevTransformModuleUrl(this.appConfig.absolutePaths.srcDir, normalized);
+        this.sourceToUrl.set(normalized, url);
+        this.urlToSource.set(url, normalized);
+        return url;
+    }
+    getRegisteredSourcePath(moduleUrl) {
+        return this.urlToSource.get(moduleUrl);
+    }
+    addContributor(contributor) {
+        this.contributors.push(contributor);
+        this.rebuildRuntimeSpecifierMap();
+        this.bundler.addContributor(contributor);
+    }
+    rebuildRuntimeSpecifierMap() {
+        this.runtimeSpecifierMap.clear();
+        for (const [specifier, url] of mergeContributorRuntimeSpecifierMaps(this.contributors)) {
+            this.runtimeSpecifierMap.set(specifier, url);
+        }
+    }
+    async resolveVendorBundlePlugins() {
+        const plugins = [];
+        for (const contributor of this.contributors) {
+            if (!contributor.getVendorBundlePlugins) {
+                continue;
+            }
+            plugins.push(...(await contributor.getVendorBundlePlugins()));
+        }
+        return plugins;
+    }
+    getWatchedModules() {
+        return this.urlToSource;
+    }
+    invalidateSource(sourcePath) {
+        const normalized = path.resolve(sourcePath);
+        this.cache.delete(normalized);
+    }
+    invalidateAll() {
+        this.cacheGeneration += 1;
+        this.cache.clear();
+        this.inFlight.clear();
+        this.vendorRegistry.invalidateAll();
+    }
+    reset() {
+        this.urlToSource.clear();
+        this.sourceToUrl.clear();
+        this.invalidateAll();
+    }
+    async tryHandleRequest(request) {
+        const url = new URL(request.url);
+        const vendorResponse = this.vendorRegistry.tryHandleVendorRequest(url.pathname);
+        if (vendorResponse) {
+            return vendorResponse;
+        }
+        const sourcePath = this.urlToSource.get(url.pathname) ?? this.resolveSourcePathFromModuleUrl(url.pathname);
+        if (!sourcePath) {
+            return null;
+        }
+        startupTrace.beginDevClientTransform();
+        const startedAt = performance.now();
+        try {
+            const entry = await this.materialize(sourcePath);
+            if (process.env.ECOPAGES_STARTUP_TRACE === 'true') {
+                appLogger.debug(`[dev-transform] materialize path=${url.pathname} bytes=${entry.code.length} durationMs=${Math.round(performance.now() - startedAt)}`);
+            }
+            return this.createJavaScriptResponse(entry.code);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return new Response(message, {
+                status: 500,
+                headers: {
+                    'Content-Type': 'text/plain',
+                    'Cache-Control': 'no-store, must-revalidate',
+                },
+            });
+        }
+        finally {
+            startupTrace.endDevClientTransform();
+        }
+    }
+    resolveSourcePathFromModuleUrl(moduleUrl) {
+        const discoveredSourcePath = resolveDevTransformModuleSourcePath(this.appConfig.absolutePaths.srcDir, moduleUrl);
+        if (!discoveredSourcePath) {
+            return undefined;
+        }
+        this.registerModule(discoveredSourcePath);
+        return path.resolve(discoveredSourcePath);
+    }
+    createJavaScriptResponse(code) {
+        return new Response(code, {
+            headers: {
+                'Content-Type': 'application/javascript',
+                'Cache-Control': 'no-store, must-revalidate',
+            },
+        });
+    }
+    async materialize(sourcePath) {
+        const normalized = path.resolve(sourcePath);
+        if (!fileSystem.exists(normalized)) {
+            throw new Error(`[dev-transform] Missing source module: ${normalized}`);
+        }
+        const sourceHash = fileSystem.hash(normalized);
+        const cached = this.cache.get(normalized);
+        if (cached && cached.sourceHash === sourceHash) {
+            return cached;
+        }
+        const pending = this.inFlight.get(normalized);
+        if (pending) {
+            return pending;
+        }
+        const moduleKind = resolveDevTransformModuleKind(normalized);
+        if (moduleKind === 'stylesheet') {
+            const entry = {
+                code: materializeDevTransformStylesheet(fileSystem.readFileSync(normalized)),
+                sourceHash,
+            };
+            this.cache.set(normalized, entry);
+            return entry;
+        }
+        const generation = this.cacheGeneration;
+        const promise = this.bundler
+            .transpileModule(normalized)
+            .then((result) => {
+            if (generation !== this.cacheGeneration) {
+                throw new Error(`[dev-transform] Stale transpile result for ${normalized}`);
+            }
+            if (result.dependencies) {
+                this.onModuleDependencies?.(normalized, result.dependencies);
+            }
+            const entry = { code: result.code, sourceHash: fileSystem.hash(normalized) };
+            this.cache.set(normalized, entry);
+            return entry;
+        })
+            .finally(() => {
+            this.inFlight.delete(normalized);
+        });
+        this.inFlight.set(normalized, promise);
+        return promise;
+    }
+}

package/src/dev/transform-server/dev-transform-url.d.ts

@@ -0,0 +1,13 @@
+export { DEV_TRANSFORM_URL_PREFIX } from '../../hmr/hmr-asset-paths.js';
+/**
+ * Maps a source entrypoint to the browser URL served by the dev transform server.
+ */
+export declare function resolveDevTransformModuleUrl(srcDir: string, entrypointPath: string): string;
+/**
+ * Resolves a dev-transform browser URL back to an on-disk page entrypoint.
+ *
+ * @remarks
+ * Client-side navigation can request page modules that were not registered during
+ * the current SSR response. Lazy resolution keeps those URLs materializable on demand.
+ */
+export declare function resolveDevTransformModuleSourcePath(srcDir: string, moduleUrl: string): string | undefined;

package/src/dev/transform-server/dev-transform-url.js

@@ -0,0 +1,58 @@
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { DEV_TRANSFORM_URL_PREFIX, stripModuleUrlQuery } from '../../hmr/hmr-asset-paths.js';
+import { decodeHmrDynamicSegments, encodeHmrDynamicSegments } from '../../hmr/hmr-entrypoint-output.js';
+import { resolveDevTransformModuleKind } from './dev-transform-module-kind.js';
+export { DEV_TRANSFORM_URL_PREFIX } from '../../hmr/hmr-asset-paths.js';
+const PAGE_SOURCE_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js', '.mdx', '.md'];
+/**
+ * Maps a source entrypoint to the browser URL served by the dev transform server.
+ */
+export function resolveDevTransformModuleUrl(srcDir, entrypointPath) {
+    const resolvedSrcDir = path.resolve(srcDir);
+    const normalizedEntrypoint = path.resolve(entrypointPath);
+    const relativePath = path.relative(resolvedSrcDir, normalizedEntrypoint);
+    if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+        throw new Error(`[dev-transform] Entrypoint must be under srcDir: ${entrypointPath}`);
+    }
+    const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, '.js');
+    const encodedPathJs = encodeHmrDynamicSegments(relativePathJs);
+    const urlPath = encodedPathJs.split(path.sep).join('/');
+    return `${DEV_TRANSFORM_URL_PREFIX}/${urlPath}`;
+}
+/**
+ * Resolves a dev-transform browser URL back to an on-disk page entrypoint.
+ *
+ * @remarks
+ * Client-side navigation can request page modules that were not registered during
+ * the current SSR response. Lazy resolution keeps those URLs materializable on demand.
+ */
+export function resolveDevTransformModuleSourcePath(srcDir, moduleUrl) {
+    const pathname = stripModuleUrlQuery(moduleUrl);
+    const prefix = `${DEV_TRANSFORM_URL_PREFIX}/`;
+    if (!pathname.startsWith(prefix)) {
+        return undefined;
+    }
+    const resolvedSrcDir = path.resolve(srcDir);
+    const relativeUrlPath = pathname.slice(prefix.length);
+    const relativePathJs = relativeUrlPath.split('/').join(path.sep);
+    const decodedRelativePathJs = decodeHmrDynamicSegments(relativePathJs);
+    if (resolveDevTransformModuleKind(decodedRelativePathJs) === 'stylesheet') {
+        const cssPath = path.resolve(resolvedSrcDir, decodedRelativePathJs);
+        if (cssPath.startsWith(`${resolvedSrcDir}${path.sep}`) && fileSystem.exists(cssPath)) {
+            return cssPath;
+        }
+        return undefined;
+    }
+    const basePath = decodedRelativePathJs.replace(/\.js$/u, '');
+    for (const extension of PAGE_SOURCE_EXTENSIONS) {
+        const candidate = path.resolve(resolvedSrcDir, `${basePath}${extension}`);
+        if (!candidate.startsWith(`${resolvedSrcDir}${path.sep}`)) {
+            continue;
+        }
+        if (fileSystem.exists(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}

package/src/dev/transform-server/dev-transform-vendor-registry.d.ts

@@ -0,0 +1,28 @@
+import type { EcoBuildPlugin } from '../../build/contracts/build-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+export type DevTransformVendorRegistryOptions = {
+    appConfig: EcoPagesAppConfig;
+    getRuntimeSpecifierMap: () => ReadonlyMap<string, string>;
+    resolveVendorBundlePlugins?: () => Promise<readonly EcoBuildPlugin[]>;
+};
+/**
+ * Lazily prebundles bare npm imports into cacheable `/assets/vendors/*` chunks.
+ */
+export declare class DevTransformVendorRegistry {
+    private readonly appConfig;
+    private readonly browserBundleService;
+    private readonly getRuntimeSpecifierMap;
+    private readonly resolveVendorBundlePlugins?;
+    private readonly vendorsDir;
+    private readonly cache;
+    private readonly inFlight;
+    constructor(options: DevTransformVendorRegistryOptions);
+    resolveKnownVendorUrl(specifier: string): string | undefined;
+    resolveVendorUrl(specifier: string): Promise<string>;
+    tryHandleVendorRequest(pathname: string): Response | null;
+    invalidateAll(): void;
+    private createVendorResponse;
+    private resolveExistingVendorPath;
+    private prebundleSpecifier;
+    private resolvePackageEntry;
+}