@esmx/core 3.0.0-rc.116 → 3.0.0-rc.118

package/dist/utils/import-map.test.mjs

@@ -1,6 +1,7 @@
 import { assert, describe, test } from "vitest";
 import {
   compressImportMap,
+  createClientImportMap,
   createImportMap,
   createImportsMap,
   createScopesMap,
@@ -1584,3 +1585,230 @@ describe("compressImportMap", () => {
     });
   });
 });
+describe("createClientImportMap integrity", () => {
+  const getFile = (name, file) => `/${name}/${file}`;
+  const getScope = (name, scope) => scope;
+  test("omits integrity when no manifest provides it", () => {
+    const manifests = [
+      {
+        name: "module-a",
+        exports: {
+          index: {
+            name: "index",
+            pkg: false,
+            file: "src/index.mjs",
+            identifier: "module-a"
+          }
+        },
+        scopes: {}
+      }
+    ];
+    const result = createClientImportMap({ manifests, getFile, getScope });
+    assert.isUndefined(result.integrity);
+  });
+  test("converts relative integrity paths to absolute URL paths", () => {
+    const manifests = [
+      {
+        name: "ssr-micro-vue2",
+        exports: {
+          routes: {
+            name: "routes",
+            pkg: false,
+            file: "src/routes.xxx.mjs",
+            identifier: "ssr-micro-vue2/routes"
+          }
+        },
+        scopes: {},
+        integrity: {
+          "src/routes.xxx.mjs": "sha384-abc"
+        }
+      }
+    ];
+    const result = createClientImportMap({ manifests, getFile, getScope });
+    assert.deepEqual(result.integrity, {
+      "/ssr-micro-vue2/src/routes.xxx.mjs": "sha384-abc"
+    });
+  });
+  test("merges integrity across multiple manifests", () => {
+    const manifests = [
+      {
+        name: "module-a",
+        exports: {},
+        scopes: {},
+        integrity: { "src/a.mjs": "sha384-a" }
+      },
+      {
+        name: "module-b",
+        exports: {},
+        scopes: {},
+        integrity: { "src/b.mjs": "sha384-b" }
+      }
+    ];
+    const result = createClientImportMap({ manifests, getFile, getScope });
+    assert.deepEqual(result.integrity, {
+      "/module-a/src/a.mjs": "sha384-a",
+      "/module-b/src/b.mjs": "sha384-b"
+    });
+  });
+});
+describe("createClientImportMap code-split chunk scopes", () => {
+  const getFile = (name, file) => `/${name}/${file}`;
+  const getScope = (name, scope) => `/${name}${scope}`;
+  const makeVueModule = (name, hash) => ({
+    name,
+    exports: {
+      entry: {
+        name: "entry",
+        pkg: false,
+        file: `src/entry.client.${hash}.mjs`,
+        identifier: `${name}/src/entry.client`
+      },
+      vue: {
+        name: "vue",
+        pkg: true,
+        file: `vue.${hash}.mjs`,
+        identifier: `${name}/vue`
+      }
+    },
+    scopes: { "": { vue: `${name}/vue` } },
+    // A Vite-style code-split chunk that is NOT an export.
+    chunks: { routesChunk: { js: `chunks/routes.${hash}.mjs` } }
+  });
+  test("scopes a module code-split chunk to its own externals", () => {
+    const manifests = [
+      makeVueModule("app-a", "aaa"),
+      makeVueModule("app-b", "bbb")
+    ];
+    const result = createClientImportMap({ manifests, getFile, getScope });
+    assert.isUndefined(result.imports?.vue);
+    assert.equal(
+      result.scopes?.["/app-a/chunks/routes.aaa.mjs"]?.vue,
+      "/app-a/vue.aaa.mjs"
+    );
+    assert.equal(
+      result.scopes?.["/app-b/chunks/routes.bbb.mjs"]?.vue,
+      "/app-b/vue.bbb.mjs"
+    );
+  });
+  test("skips a chunk scope when a global import already resolves it", () => {
+    const result = createClientImportMap({
+      manifests: [makeVueModule("solo", "aaa")],
+      getFile,
+      getScope
+    });
+    assert.equal(result.imports?.vue, "/solo/vue.aaa.mjs");
+    assert.isUndefined(result.scopes?.["/solo/chunks/routes.aaa.mjs"]);
+  });
+  test("is a no-op for all-in-one manifests without code-split chunks", () => {
+    const allInOne = {
+      name: "rspack-app",
+      exports: {
+        entry: {
+          name: "entry",
+          pkg: false,
+          file: "src/entry.client.zzz.mjs",
+          identifier: "rspack-app/src/entry.client"
+        },
+        vue: {
+          name: "vue",
+          pkg: true,
+          file: "vue.zzz.mjs",
+          identifier: "rspack-app/vue"
+        }
+      },
+      scopes: { "": { vue: "rspack-app/vue" } }
+      // no `chunks` — rspack all-in-one output
+    };
+    const result = createClientImportMap({
+      manifests: [allInOne, makeVueModule("app-b", "bbb")],
+      getFile,
+      getScope
+    });
+    const invented = Object.keys(result.scopes ?? {}).filter(
+      (k) => k.startsWith("/rspack-app/chunks/")
+    );
+    assert.deepEqual(invented, []);
+  });
+  test("applies all of a module externals to its chunk", () => {
+    const make = (name, hash) => ({
+      name,
+      exports: {
+        vue: {
+          name: "vue",
+          pkg: true,
+          file: `vue.${hash}.mjs`,
+          identifier: `${name}/vue`
+        },
+        pinia: {
+          name: "pinia",
+          pkg: true,
+          file: `pinia.${hash}.mjs`,
+          identifier: `${name}/pinia`
+        }
+      },
+      scopes: { "": { vue: `${name}/vue`, pinia: `${name}/pinia` } },
+      chunks: { storeChunk: { js: `chunks/store.${hash}.mjs` } }
+    });
+    const result = createClientImportMap({
+      manifests: [make("app-a", "aaa"), make("app-b", "bbb")],
+      getFile,
+      getScope
+    });
+    const scope = result.scopes?.["/app-a/chunks/store.aaa.mjs"];
+    assert.equal(scope?.vue, "/app-a/vue.aaa.mjs");
+    assert.equal(scope?.pinia, "/app-a/pinia.aaa.mjs");
+  });
+});
+describe("multi-version coexistence (scope isolation)", () => {
+  const layeredManifests = [
+    {
+      name: "base",
+      exports: {
+        vue: {
+          name: "vue",
+          pkg: true,
+          file: "vue.base.mjs",
+          identifier: "base/vue"
+        }
+      },
+      scopes: { "": { vue: "base/vue" } },
+      chunks: { "base@src/app.ts": { js: "app.base.mjs" } },
+      integrity: {
+        "vue.base.mjs": "sha384-base",
+        "app.base.mjs": "sha384-base-app"
+      }
+    },
+    {
+      name: "vue-base",
+      exports: {
+        vue: {
+          name: "vue",
+          pkg: true,
+          file: "vue.winner.mjs",
+          identifier: "vue-base/vue"
+        }
+      },
+      scopes: { "": { vue: "vue-base/vue" } },
+      integrity: { "vue.winner.mjs": "sha384-winner" }
+    }
+  ];
+  const getFile = (name, file) => `/${name}/${file}`;
+  const getScope = (name, scope) => `/${name}${scope}`;
+  test("each copy stays isolated in its own scope", () => {
+    const result = createImportMap({
+      manifests: layeredManifests,
+      getFile,
+      getScope
+    });
+    assert.equal(result.imports["base/vue"], "/base/vue.base.mjs");
+    assert.equal(
+      result.imports["vue-base/vue"],
+      "/vue-base/vue.winner.mjs"
+    );
+    assert.equal(result.scopes["/base/"]?.vue, "/base/vue.base.mjs");
+    assert.equal(
+      result.scopes["/vue-base/"]?.vue,
+      "/vue-base/vue.winner.mjs"
+    );
+  });
+});

package/package.json

@@ -59,12 +59,12 @@
         "build": "unbuild"
     },
     "dependencies": {
-        "@esmx/import": "workspace:*",
+        "@esmx/import": "3.0.0-rc.118",
         "@types/serialize-javascript": "^5.0.4",
         "es-module-lexer": "^1.7.0",
         "find": "^0.3.0",
         "send": "^1.2.0",
-        "serialize-javascript": "^6.0.2"
+        "serialize-javascript": "^7.0.5"
     },
     "devDependencies": {
         "@biomejs/biome": "2.3.7",
@@ -72,12 +72,12 @@
         "@types/node": "^24.0.0",
         "@types/send": "^1.2.1",
         "@types/write": "^2.0.4",
-        "@vitest/coverage-v8": "3.2.4",
+        "@vitest/coverage-v8": "3.2.6",
         "typescript": "5.9.3",
         "unbuild": "3.6.1",
-        "vitest": "3.2.4"
+        "vitest": "3.2.6"
     },
-    "version": "3.0.0-rc.116",
+    "version": "3.0.0-rc.118",
     "type": "module",
     "private": false,
     "exports": {
@@ -100,5 +100,8 @@
         "template",
         "public"
     ],
-    "gitHead": "2e16b175552400382913b445ae7e112b78c422f5"
+    "gitHead": "2fdbd62470f64e6e45568550941c78cb259e4917",
+    "publishConfig": {
+        "access": "public"
+    }
 }

package/src/app.ts

@@ -1,6 +1,7 @@
 import { pathToFileURL } from 'node:url';
 import { createLoaderImport } from '@esmx/import';
 import type { COMMAND, Esmx } from './core';
+import { DEFAULT_MODULE_ENTRY } from './module-config';
 import {
     RenderContext,
     type RenderContextOptions,
@@ -123,10 +124,12 @@ async function createStartRender(esmx: Esmx) {
     const baseURL = pathToFileURL(esmx.resolvePath('dist/server')) as URL;
     const importMap = await esmx.getImportMap('server');
     const loaderImport = createLoaderImport(baseURL, importMap);
+    const serverEntry =
+        esmx.moduleConfig.entry.server ?? DEFAULT_MODULE_ENTRY.server;
 
     return async (options?: RenderContextOptions): Promise<RenderContext> => {
         const rc = new RenderContext(esmx, options);
-        const result = await loaderImport(`${esmx.name}/src/entry.server`);
+        const result = await loaderImport(`${esmx.name}/${serverEntry.name}`);
         const serverRender: ServerRenderHandle = result[rc.entryName];
         if (typeof serverRender === 'function') {
             await serverRender(rc);
@@ -138,7 +141,7 @@ async function createStartRender(esmx: Esmx) {
 function createErrorRender(esmx: Esmx) {
     return (options?: RenderContextOptions) => {
         throw new Error(
-            `App instance is only available in production and can only execute built artifacts.`
+            `[@esmx/core] esmx.render() is only available in production. The current process is in dev mode and has no built artifacts. Run \`esmx build\` first, then start the server with NODE_ENV=production node dist/index.mjs.`
         );
     };
 }

package/src/cli/cli.ts

@@ -4,6 +4,7 @@ import pkg from '../../package.json' with { type: 'json' };
 
 import { COMMAND, Esmx, type EsmxOptions } from '../core';
 import { resolveImportPath } from '../utils/resolve-path';
+import { runValidate, VALIDATE_HELP } from './validate';
 
 async function getSrcOptions(): Promise<EsmxOptions> {
     return import(resolveImportPath(process.cwd(), './src/entry.node.ts')).then(
@@ -30,6 +31,22 @@ async function getDistOptions(): Promise<EsmxOptions> {
 }
 
 export async function cli(command: string) {
+    if (command === 'validate') {
+        // Handled before the banner: `--json` must keep stdout pure JSON.
+        const flags = process.argv.slice(3);
+        if (flags.includes('--help')) {
+            console.log(VALIDATE_HELP);
+            return;
+        }
+        const result = await runValidate(process.cwd(), {
+            json: flags.includes('--json')
+        });
+        console.log(result.output);
+        if (result.exitCode !== 0) {
+            process.exit(result.exitCode);
+        }
+        return;
+    }
     console.log(`🔥 ${styleText('yellow', 'Esmx')} v${pkg.version}
     `);
     if (
@@ -111,7 +128,7 @@ export function resolve(
     nextResolve: Function
 ) {
     if (
-        context?.parentURL.endsWith('.ts') &&
+        context?.parentURL?.endsWith('.ts') &&
         specifier.startsWith('.') &&
         !specifier.endsWith('.ts')
     ) {
@@ -119,3 +136,29 @@ export function resolve(
     }
     return nextResolve(specifier, context);
 }
+
+/**
+ * Style assets imported via standard `import './x.css'` are part of esmx's
+ * federation contract (manifest's `chunks[*].css[]` — see G section). On the
+ * cli/build path Node's native loader hits these when reading the user's
+ * `entry.node.ts` config (which transitively imports a remote's source). They
+ * have no server-side behaviour — emit a no-op ESM module so the loader chain
+ * continues cleanly. Mirrors `@esmx/import`'s VM-linker hook.
+ */
+const STYLE_ASSET_RE =
+    /\.(?:css|scss|sass|less|stylus|styl|pcss|postcss)(?:\?.*)?$/i;
+
+export async function load(
+    url: string,
+    context: Record<string, any>,
+    nextLoad: Function
+) {
+    if (STYLE_ASSET_RE.test(url)) {
+        return {
+            format: 'module',
+            shortCircuit: true,
+            source: `export default ${JSON.stringify(url)}; export const href = ${JSON.stringify(url)};`
+        };
+    }
+    return nextLoad(url, context);
+}

package/src/cli/validate.test.ts

@@ -0,0 +1,251 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+import util from 'node:util';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+    createFixtureRoot,
+    removeFixtureRoot,
+    writeFixturePackage
+} from '../declaration/test-fixtures';
+import { runValidate } from './validate';
+
+const fixtureRoots: string[] = [];
+
+async function fixtureRoot(): Promise<string> {
+    const root = await createFixtureRoot();
+    fixtureRoots.push(root);
+    return root;
+}
+
+afterEach(async () => {
+    vi.restoreAllMocks();
+    await Promise.all(fixtureRoots.splice(0).map(removeFixtureRoot));
+});
+
+async function legacyFixture(): Promise<string> {
+    const root = await fixtureRoot();
+    return writeFixturePackage(root, {
+        dir: 'legacy',
+        packageJson: { name: 'legacy', version: '1.0.0' }
+    });
+}
+
+/** App using `base`, which provides vue but app declares no range → W_NO_RANGE. */
+async function warningOnlyFixture(): Promise<string> {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+        dir: 'app/node_modules/base',
+        packageJson: {
+            name: 'base',
+            version: '1.0.0',
+            dependencies: { vue: '^3.4.0' },
+            esmx: { provides: ['vue'] }
+        },
+        built: true
+    });
+    writeFixturePackage(root, {
+        dir: 'app/node_modules/base/node_modules/vue',
+        packageJson: { name: 'vue', version: '3.4.21' }
+    });
+    return writeFixturePackage(root, {
+        dir: 'app',
+        packageJson: {
+            name: 'app',
+            version: '1.0.0',
+            esmx: {
+                entry: { client: './src/entry.client.ts' },
+                uses: ['base']
+            }
+        }
+    });
+}
+
+/** Layered merge (Gate 2): vue-base wins over base → one election. */
+async function dupProviderFixture(): Promise<string> {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+        dir: 'node_modules/base',
+        packageJson: {
+            name: 'base',
+            version: '1.0.0',
+            dependencies: { vue: '^3.4.0' },
+            esmx: { provides: ['vue'] }
+        },
+        built: true
+    });
+    writeFixturePackage(root, {
+        dir: 'node_modules/base/node_modules/vue',
+        packageJson: { name: 'vue', version: '3.4.21' }
+    });
+    writeFixturePackage(root, {
+        dir: 'node_modules/vue-base',
+        packageJson: {
+            name: 'vue-base',
+            version: '1.0.0',
+            dependencies: { vue: '^3.4.0' },
+            esmx: { uses: ['base'], provides: ['vue'] }
+        },
+        built: true
+    });
+    writeFixturePackage(root, {
+        dir: 'node_modules/vue-base/node_modules/vue',
+        packageJson: { name: 'vue', version: '3.5.13' }
+    });
+    return writeFixturePackage(root, {
+        dir: 'app',
+        packageJson: {
+            name: 'app',
+            version: '1.0.0',
+            dependencies: { vue: '^3.4.0' },
+            esmx: { uses: ['vue-base'] }
+        }
+    });
+}
+
+async function notLinkedFixture(): Promise<string> {
+    const root = await fixtureRoot();
+    return writeFixturePackage(root, {
+        dir: 'app',
+        packageJson: {
+            name: 'app',
+            version: '1.0.0',
+            esmx: {
+                entry: { client: './src/entry.client.ts' },
+                uses: ['ghost']
+            }
+        }
+    });
+}
+
+describe('runValidate', () => {
+    it('should exit 0 with protocol legacy for a package without esmx field', async () => {
+        const appDir = await legacyFixture();
+
+        const jsonResult = await runValidate(appDir, { json: true });
+        const humanResult = await runValidate(appDir);
+
+        expect(jsonResult.exitCode).toBe(0);
+        expect(JSON.parse(jsonResult.output)).toEqual({
+            protocol: 'legacy',
+            diagnostics: []
+        });
+        expect(humanResult.exitCode).toBe(0);
+        expect(humanResult.output).toContain('entry.node.ts');
+        expect(humanResult.output).toContain('opt-in');
+    });
+
+    it('should exit 0 when the declaration only has warnings', async () => {
+        const appDir = await warningOnlyFixture();
+
+        const result = await runValidate(appDir, { json: true });
+
+        const envelope = JSON.parse(result.output);
+        expect(result.exitCode).toBe(0);
+        expect(envelope.diagnostics).toHaveLength(1);
+        expect(envelope.diagnostics[0].code).toBe('W_NO_RANGE');
+        expect(envelope.supply.vue).toEqual({
+            groups: [{ major: 3, provider: 'base', version: '3.4.21' }]
+        });
+        expect(Object.keys(envelope.mounts)).toEqual(['base']);
+        expect(envelope.mounts.base.built).toBe(true);
+    });
+
+    it('should exit non-zero for E_NOT_LINKED with the exact envelope entry shape', async () => {
+        const appDir = await notLinkedFixture();
+
+        const result = await runValidate(appDir, { json: true });
+
+        const envelope = JSON.parse(result.output);
+        expect(result.exitCode).toBe(1);
+        const entry = envelope.diagnostics.find(
+            (d: { code: string }) => d.code === 'E_NOT_LINKED'
+        );
+        expect(entry).toBeDefined();
+        expect(entry.module).toBe('app');
+        expect(typeof entry.message).toBe('string');
+        expect(typeof entry.fix).toBe('string');
+        expect(entry).not.toHaveProperty('severity');
+    });
+
+    it('should exit non-zero and surface E_DUP_PROVIDER in the JSON envelope', async () => {
+        const appDir = await dupProviderFixture();
+
+        const result = await runValidate(appDir, { json: true });
+
+        const envelope = JSON.parse(result.output);
+        expect(result.exitCode).toBe(1);
+        const entry = envelope.diagnostics.find(
+            (d: { code: string }) => d.code === 'E_DUP_PROVIDER'
+        );
+        expect(entry).toBeDefined();
+        expect(entry.module).toBe('vue-base');
+        expect(entry.package).toBe('vue');
+        expect(entry.found).toBe('base, vue-base');
+        expect(envelope).not.toHaveProperty('elections');
+    });
+
+    it('should print E_DUP_PROVIDER in the human report', async () => {
+        const appDir = await dupProviderFixture();
+
+        const result = await runValidate(appDir);
+
+        const plain = util.stripVTControlCharacters(result.output);
+        expect(plain).toContain('[E_DUP_PROVIDER]');
+        expect(plain).toContain('vue-base → vue');
+        expect(plain).toContain('base, vue-base');
+    });
+
+    it('should report diagnostics, supply and mounts in human mode', async () => {
+        const appDir = await warningOnlyFixture();
+
+        const result = await runValidate(appDir);
+
+        const plain = util.stripVTControlCharacters(result.output);
+        expect(result.exitCode).toBe(0);
+        expect(plain).toContain('[W_NO_RANGE]');
+        expect(plain).toContain('fix:');
+        expect(plain).toContain('vue → base@3.4.21');
+        expect(plain).toMatch(/base → .*dist \(built\)/);
+    });
+
+    it('should produce pure JSON output without writing to the console', async () => {
+        const appDir = await notLinkedFixture();
+        const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+        const result = await runValidate(appDir, { json: true });
+
+        expect(() => JSON.parse(result.output)).not.toThrow();
+        expect(log).not.toHaveBeenCalled();
+        expect(warn).not.toHaveBeenCalled();
+        expect(error).not.toHaveBeenCalled();
+    });
+});
+
+const distCli = path.resolve(
+    path.dirname(url.fileURLToPath(import.meta.url)),
+    '../../dist/cli/index.mjs'
+);
+
+// Spawn-based smoke test: only meaningful against a built CLI; building
+// inside tests is out of scope, so skip when dist is absent.
+describe.skipIf(!fs.existsSync(distCli))('esmx validate (spawned CLI)', () => {
+    it('should emit only the JSON envelope on stdout and exit non-zero on errors', async () => {
+        const childProcess = await import('node:child_process');
+        const appDir = await notLinkedFixture();
+
+        const spawned = childProcess.spawnSync(
+            process.execPath,
+            [distCli, 'validate', '--json'],
+            { cwd: appDir, encoding: 'utf-8' }
+        );
+
+        expect(spawned.status).toBe(1);
+        const envelope = JSON.parse(spawned.stdout);
+        expect(envelope.diagnostics[0].code).toBe('E_NOT_LINKED');
+    });
+});