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

package/dist/module-config.test.mjs

@@ -1,14 +1,17 @@
+import fs from "node:fs";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
 import {
   addPackageExportsToScopes,
-  createDefaultExports,
+  createEntryExports,
+  DEFAULT_MODULE_ENTRY,
+  getEntryChunkId,
   getEnvironmentExports,
   getEnvironmentImports,
-  getEnvironmentScopes,
   getEnvironments,
   getLinks,
   parsedExportValue,
+  parseEntryConfig,
   parseModuleConfig,
   processExportArray,
   processObjectExport,
@@ -209,41 +212,17 @@ describe("Module Config Parser", () => {
         expect(Object.keys(result)).toHaveLength(0);
       });
     });
-    describe("getEnvironmentScopes", () => {
-      it("should process scoped imports per environment", () => {
-        const scopes = {
-          utils: {
-            lodash: "lodash",
-            moment: {
-              client: "moment",
-              server: "moment/server"
-            }
-          }
-        };
-        const result = getEnvironmentScopes("client", scopes);
-        expect(result.utils.lodash).toBe("lodash");
-        expect(result.utils.moment).toBe("moment");
-      });
-      it("should handle empty scopes object", () => {
-        const result = getEnvironmentScopes("client", {});
-        expect(Object.keys(result)).toHaveLength(0);
-      });
-    });
     describe("getEnvironments", () => {
-      it("should combine imports, exports and scopes", () => {
+      it("should combine imports and exports into the root scope", () => {
         const config = {
           imports: {
             react: "react"
-          },
-          scopes: {
-            utils: {
-              lodash: "lodash"
-            }
           }
         };
         const result = getEnvironments(config, "client", "test-module");
         expect(result.imports.react).toBe("react");
-        expect(result.scopes.utils.lodash).toBe("lodash");
+        expect(Object.keys(result.scopes)).toEqual([""]);
+        expect(result.scopes[""].react).toBe("react");
         expect(result.exports).toBeDefined();
       });
       it("should preserve import mapping types", () => {
@@ -268,42 +247,19 @@ describe("Module Config Parser", () => {
         expect(emptyScope.react).toBe("test-module/react");
         expect(emptyScope["./src/component"]).toBeUndefined();
       });
-      it("should not override existing empty string scope", () => {
-        const config = {
-          exports: ["pkg:lodash"],
-          scopes: {
-            "": {
-              existing: "existing-value"
-            }
-          }
-        };
-        const result = getEnvironments(config, "client", "test-module");
-        const emptyScope = result.scopes[""];
-        expect(emptyScope).toBeDefined();
-        expect(emptyScope.existing).toBe("existing-value");
-        expect(emptyScope.lodash).toBe("test-module/lodash");
-      });
-      it("should verify the specific scopes merging logic with imports", () => {
+      it("should merge imports and pkg exports into the single root scope", () => {
         const config = {
           imports: {
             react: "react",
             vue: "vue"
           },
-          scopes: {
-            utils: {
-              lodash: "lodash"
-            },
-            "": {
-              existing: "existing-value"
-            }
-          }
+          exports: ["pkg:lodash"]
         };
         const result = getEnvironments(config, "client", "test-module");
-        expect(result.scopes[""]).toBeDefined();
-        expect(result.scopes[""].existing).toBe("existing-value");
+        expect(Object.keys(result.scopes)).toEqual([""]);
         expect(result.scopes[""].react).toBe("react");
         expect(result.scopes[""].vue).toBe("vue");
-        expect(result.scopes.utils.lodash).toBe("lodash");
+        expect(result.scopes[""].lodash).toBe("test-module/lodash");
         expect(result.imports.react).toBe("react");
         expect(result.imports.vue).toBe("vue");
       });
@@ -362,36 +318,6 @@ describe("Module Config Parser", () => {
     });
   });
   describe("Export Processing Functions", () => {
-    describe("createDefaultExports", () => {
-      it("should generate client default exports", () => {
-        const result = createDefaultExports("client");
-        expect(result["src/entry.client"].file).toBe(
-          "./src/entry.client"
-        );
-        expect(result["src/entry.server"].file).toBe("");
-      });
-      it("should generate server default exports", () => {
-        const result = createDefaultExports("server");
-        expect(result["src/entry.client"].file).toBe("");
-        expect(result["src/entry.server"].file).toBe(
-          "./src/entry.server"
-        );
-      });
-      it("should handle client environment switch case", () => {
-        const result = createDefaultExports("client");
-        expect(result["src/entry.client"].file).toBe(
-          "./src/entry.client"
-        );
-        expect(result["src/entry.server"].file).toBe("");
-      });
-      it("should handle server environment switch case", () => {
-        const result = createDefaultExports("server");
-        expect(result["src/entry.client"].file).toBe("");
-        expect(result["src/entry.server"].file).toBe(
-          "./src/entry.server"
-        );
-      });
-    });
     describe("processStringExport", () => {
       it("should parse simple string export", () => {
         const result = processStringExport("./src/component");
@@ -647,11 +573,6 @@ describe("Module Config Parser", () => {
             server: "vue/server"
           }
         },
-        scopes: {
-          utils: {
-            lodash: "lodash"
-          }
-        },
         exports: [
           "./src/component",
           {
@@ -741,3 +662,218 @@ describe("Module Config Parser", () => {
     });
   });
 });
+describe("Framework entry threading (RFC 0001 Phase 2)", () => {
+  describe("parseEntryConfig", () => {
+    it("should default to legacy entries for an empty config", () => {
+      const entry = parseEntryConfig({});
+      expect(entry).toEqual({
+        client: {
+          name: "src/entry.client",
+          file: "./src/entry.client"
+        },
+        server: {
+          name: "src/entry.server",
+          file: "./src/entry.server"
+        }
+      });
+    });
+    it("should resolve both entries to null for lib modules", () => {
+      const entry = parseEntryConfig({ lib: true });
+      expect(entry).toEqual({ client: null, server: null });
+    });
+    it("should derive the export name from a custom entry file path", () => {
+      const entry = parseEntryConfig({
+        entry: { client: "./custom/main.ts" }
+      });
+      expect(entry.client).toEqual({
+        name: "custom/main",
+        file: "./custom/main.ts"
+      });
+      expect(entry.server).toEqual(DEFAULT_MODULE_ENTRY.server);
+    });
+    it("should keep the path-derived default name for a standard declaration path", () => {
+      const entry = parseEntryConfig({
+        entry: { client: "./src/entry.client.ts" }
+      });
+      expect(entry.client).toEqual({
+        name: "src/entry.client",
+        file: "./src/entry.client.ts"
+      });
+    });
+    it("should disable a side declared as false", () => {
+      const entry = parseEntryConfig({ entry: { server: false } });
+      expect(entry.server).toBeNull();
+      expect(entry.client).toEqual(DEFAULT_MODULE_ENTRY.client);
+    });
+  });
+  describe("parseModuleConfig entry population", () => {
+    it("should populate entry for legacy configs", () => {
+      const result = parseModuleConfig("test-module", "/test/root");
+      expect(result.entry.client).toEqual(DEFAULT_MODULE_ENTRY.client);
+      expect(result.entry.server).toEqual(DEFAULT_MODULE_ENTRY.server);
+    });
+    it("should populate null entries for lib configs and omit entry exports", () => {
+      const result = parseModuleConfig("test-module", "/test/root", {
+        lib: true
+      });
+      expect(result.entry).toEqual({ client: null, server: null });
+      expect(result.environments.client.exports).toEqual({});
+      expect(result.environments.server.exports).toEqual({});
+    });
+    it("should thread a custom entry into the environment exports", () => {
+      const result = parseModuleConfig("test-module", "/test/root", {
+        entry: { client: "./custom/main.ts" }
+      });
+      expect(result.environments.client.exports["custom/main"]).toEqual({
+        name: "custom/main",
+        file: "./custom/main.ts",
+        pkg: false
+      });
+      expect(result.environments.server.exports["custom/main"]).toEqual({
+        name: "custom/main",
+        file: "",
+        pkg: false
+      });
+      expect(
+        result.environments.server.exports["src/entry.server"]
+      ).toEqual({
+        name: "src/entry.server",
+        file: "./src/entry.server",
+        pkg: false
+      });
+      expect(
+        result.environments.client.exports["src/entry.client"]
+      ).toBeUndefined();
+    });
+  });
+  describe("default entry exports single source of truth", () => {
+    it("should derive byte-identical defaults from DEFAULT_MODULE_ENTRY", () => {
+      const entry = parseEntryConfig({});
+      expect(createEntryExports(entry, "client")).toEqual({
+        "src/entry.client": {
+          name: "src/entry.client",
+          file: "./src/entry.client",
+          pkg: false
+        },
+        "src/entry.server": {
+          name: "src/entry.server",
+          file: "",
+          pkg: false
+        }
+      });
+      expect(createEntryExports(entry, "server")).toEqual({
+        "src/entry.client": {
+          name: "src/entry.client",
+          file: "",
+          pkg: false
+        },
+        "src/entry.server": {
+          name: "src/entry.server",
+          file: "./src/entry.server",
+          pkg: false
+        }
+      });
+    });
+  });
+  describe("getEntryChunkId", () => {
+    it("should append .ts to the legacy extensionless default", () => {
+      const id = getEntryChunkId(
+        "test-module",
+        DEFAULT_MODULE_ENTRY.client
+      );
+      expect(id).toBe("test-module@src/entry.client.ts");
+    });
+    it("should preserve an explicit extension on custom entries", () => {
+      expect(
+        getEntryChunkId("m", {
+          name: "custom/main",
+          file: "./custom/main.tsx"
+        })
+      ).toBe("m@custom/main.tsx");
+      expect(
+        getEntryChunkId("m", {
+          name: "src/entry.client",
+          file: "./src/entry.client.ts"
+        })
+      ).toBe("m@src/entry.client.ts");
+    });
+  });
+  describe("fleet invariant: built example manifests", () => {
+    const repoRoot = path.resolve(import.meta.dirname, "../../..");
+    const examplesDir = path.join(repoRoot, "examples");
+    const findClientManifests = (dir) => {
+      if (!fs.existsSync(dir)) {
+        return [];
+      }
+      const found = [];
+      for (const item of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (!item.isDirectory() || item.name === "node_modules") {
+          continue;
+        }
+        const child = path.join(dir, item.name);
+        const manifest = path.join(child, "dist/client/manifest.json");
+        if (fs.existsSync(manifest)) {
+          found.push(manifest);
+        }
+        found.push(...findClientManifests(child));
+      }
+      return found;
+    };
+    const manifests = findClientManifests(examplesDir);
+    it.skipIf(manifests.length === 0)(
+      "should compute the exact historical chunk seed for every built example",
+      () => {
+        expect(manifests.length).toBeGreaterThan(0);
+        for (const manifestPath of manifests) {
+          const manifest = JSON.parse(
+            fs.readFileSync(manifestPath, "utf-8")
+          );
+          const parsed = parseModuleConfig(
+            manifest.name,
+            path.resolve(manifestPath, "../../..")
+          );
+          if (!parsed.entry.client) {
+            continue;
+          }
+          const seed = getEntryChunkId(
+            manifest.name,
+            parsed.entry.client
+          );
+          expect(seed).toBe(`${manifest.name}@src/entry.client.ts`);
+          if (manifest.exports["src/entry.client"]) {
+            expect(Object.keys(manifest.chunks)).toContain(seed);
+          }
+        }
+      }
+    );
+    it.skipIf(
+      !fs.existsSync(
+        path.join(
+          examplesDir,
+          "micro-app/ssr-micro-shared/dist/client/manifest.json"
+        )
+      )
+    )(
+      "should match the ssr-micro-shared manifest chunk key exactly",
+      () => {
+        const manifestPath = path.join(
+          examplesDir,
+          "micro-app/ssr-micro-shared/dist/client/manifest.json"
+        );
+        const manifest = JSON.parse(
+          fs.readFileSync(manifestPath, "utf-8")
+        );
+        const parsed = parseModuleConfig(
+          manifest.name,
+          path.resolve(manifestPath, "../../..")
+        );
+        const seed = getEntryChunkId(
+          manifest.name,
+          parsed.entry.client
+        );
+        expect(seed).toBe("ssr-micro-shared@src/entry.client.ts");
+        expect(Object.keys(manifest.chunks)).toContain(seed);
+      }
+    );
+  });
+});

package/dist/pack-config.d.ts

@@ -19,15 +19,8 @@ import type { Esmx } from './core';
  * import type { EsmxOptions } from '@esmx/core';
  *
  * export default {
- *   modules: {
- *     // Configure modules to export
- *     exports: [
- *       'root:src/components/button.vue',
- *       'root:src/utils/format.ts',
- *       'pkg:vue',
- *       'pkg:vue-router'
- *     ]
- *   },
+ *   // Module exports/provides are declared in package.json "esmx"
+ *   // (RFC 0001), not here. entry.node.ts keeps behavior + packaging.
  *   // Packaging configuration
  *   pack: {
  *     // Enable packaging functionality

package/dist/render-context.mjs

@@ -1,5 +1,12 @@
 import path from "node:path";
 import serialize from "serialize-javascript";
+import {
+  DEFAULT_MODULE_ENTRY,
+  getEntryChunkId
+} from "./module-config.mjs";
+function getClientEntry(esmx) {
+  return esmx.moduleConfig.entry.client ?? DEFAULT_MODULE_ENTRY.client;
+}
 export class RenderContext {
   esmx;
   /**
@@ -384,7 +391,8 @@ export class RenderContext {
   };
   _importMap = {
     src: "",
-    code: ""
+    code: "",
+    integrity: null
   };
   /**
    * Define the generation mode for importmap
@@ -702,7 +710,8 @@ export class RenderContext {
    */
   async commit() {
     const { esmx } = this;
-    const chunkSet = /* @__PURE__ */ new Set([`${esmx.name}@src/entry.client.ts`]);
+    const clientEntry = getClientEntry(esmx);
+    const chunkSet = /* @__PURE__ */ new Set([getEntryChunkId(esmx.name, clientEntry)]);
     for (const item of this.importMetaSet) {
       if ("chunkName" in item && typeof item.chunkName === "string") {
         chunkSet.add(item.chunkName);
@@ -729,7 +738,7 @@ export class RenderContext {
     });
     const paths = await esmx.getStaticImportPaths(
       "client",
-      `${esmx.name}/src/entry.client`
+      `${esmx.name}/${clientEntry.name}`
     );
     paths?.forEach(
       (filepath) => files.modulepreload.add(getUrlPath(filepath))
@@ -956,7 +965,8 @@ export class RenderContext {
    * ```
    */
   moduleEntry() {
-    return `<script type="module">import "${this.esmx.name}/src/entry.client";<\/script>`;
+    const clientEntry = getClientEntry(this.esmx);
+    return `<script type="module">import "${this.esmx.name}/${clientEntry.name}";<\/script>`;
   }
   /**
    * Preload module dependencies
@@ -1005,6 +1015,13 @@ export class RenderContext {
    * ```
    */
   modulePreload() {
-    return this.files.modulepreload.map((url) => `<link rel="modulepreload" href="${url}">`).join("");
+    const { integrity } = this._importMap;
+    return this.files.modulepreload.map((url) => {
+      const hash = integrity?.[url];
+      if (hash) {
+        return `<link rel="modulepreload" href="${url}" integrity="${hash}">`;
+      }
+      return `<link rel="modulepreload" href="${url}">`;
+    }).join("");
   }
 }

package/dist/utils/import-map.d.ts

@@ -1,4 +1,9 @@
 import type { ImportMap, ScopesMap, SpecifierMap } from '@esmx/import';
+/**
+ * Import map with `imports` and `scopes` fully resolved. The optional
+ * `integrity` field is layered on later by {@link createClientImportMap}.
+ */
+type ResolvedImportMap = Required<Pick<ImportMap, 'imports' | 'scopes'>>;
 export interface ImportMapManifest {
     name: string;
     exports: Record<string, {
@@ -8,6 +13,20 @@ export interface ImportMapManifest {
         pkg: boolean;
     }>;
     scopes: Record<string, Record<string, string>>;
+    /**
+     * Emitted chunk files (keyed arbitrarily). Each chunk's `js` is a relative
+     * path (e.g. "chunks/routes.xxx.mjs"). Used so a module's scope also covers
+     * its code-split chunks, not just its export files.
+     */
+    chunks?: Record<string, {
+        js: string;
+    }>;
+    /**
+     * Subresource Integrity hashes for this module's build output files.
+     * Keys are relative file paths (e.g. "src/routes.xxx.mjs"), values are
+     * integrity strings (e.g. "sha384-..."). Only present in production builds.
+     */
+    integrity?: Record<string, string>;
 }
 export interface GetImportMapOptions {
     manifests: readonly ImportMapManifest[];
@@ -46,7 +65,8 @@ export declare function createScopesMap(imports: SpecifierMap, manifests: readon
  * @see https://github.com/guybedford/es-module-shims/issues/529
  * @see https://issues.chromium.org/issues/453147451
  */
-export declare function fixImportMapNestedScopes(importMap: Required<ImportMap>): Required<ImportMap>;
-export declare function compressImportMap(importMap: Required<ImportMap>): ImportMap;
-export declare function createImportMap({ manifests, getFile, getScope }: GetImportMapOptions): Required<ImportMap>;
+export declare function fixImportMapNestedScopes(importMap: ResolvedImportMap): ResolvedImportMap;
+export declare function compressImportMap(importMap: ResolvedImportMap): ImportMap;
+export declare function createImportMap({ manifests, getFile, getScope }: GetImportMapOptions): ResolvedImportMap;
 export declare function createClientImportMap(options: GetImportMapOptions): ImportMap;
+export {};

package/dist/utils/import-map.mjs

@@ -48,6 +48,26 @@ export function fixImportMapNestedScopes(importMap) {
   });
   return importMap;
 }
+function addCodeSplitChunkScopes(importMap, base, options) {
+  for (const manifest of options.manifests) {
+    const moduleScope = manifest.scopes?.[""];
+    const chunks = manifest.chunks;
+    if (!moduleScope || !chunks) continue;
+    const resolved = {};
+    for (const [specifier, identifier] of Object.entries(moduleScope)) {
+      const target = base.imports[identifier] ?? identifier;
+      if (importMap.imports?.[specifier] === target) continue;
+      resolved[specifier] = target;
+    }
+    if (Object.keys(resolved).length === 0) continue;
+    for (const chunk of Object.values(chunks)) {
+      if (!chunk.js) continue;
+      const url = options.getFile(manifest.name, chunk.js);
+      importMap.scopes ??= {};
+      importMap.scopes[url] = { ...importMap.scopes[url], ...resolved };
+    }
+  }
+}
 export function compressImportMap(importMap) {
   const compressed = {
     imports: { ...importMap.imports },
@@ -108,5 +128,22 @@ export function createImportMap({
 export function createClientImportMap(options) {
   const base = createImportMap(options);
   const fixed = fixImportMapNestedScopes(base);
-  return compressImportMap(fixed);
+  const compressed = compressImportMap(fixed);
+  addCodeSplitChunkScopes(compressed, base, options);
+  const integrity = {};
+  for (const manifest of options.manifests) {
+    if (manifest.integrity) {
+      for (const [filePath, hash] of Object.entries(manifest.integrity)) {
+        const urlPath = `/${manifest.name}/${filePath}`;
+        integrity[urlPath] = hash;
+      }
+    }
+  }
+  if (Object.keys(integrity).length > 0) {
+    return {
+      ...compressed,
+      integrity
+    };
+  }
+  return compressed;
 }