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

package/dist/manifest-json.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/manifest-json.test.mjs

@@ -0,0 +1,196 @@
+import fs from "node:fs";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  createFixtureRoot,
+  removeFixtureRoot,
+  writeFixturePackage
+} from "./declaration/test-fixtures.mjs";
+import {
+  buildManifestProtocolFields,
+  getManifestList,
+  MANIFEST_PROTOCOL_VERSION
+} from "./manifest-json.mjs";
+const fixtureRoots = [];
+async function fixtureRoot() {
+  const root = await createFixtureRoot();
+  fixtureRoots.push(root);
+  return root;
+}
+afterEach(async () => {
+  await Promise.all(fixtureRoots.splice(0).map(removeFixtureRoot));
+});
+describe("buildManifestProtocolFields", () => {
+  it("should transcribe protocol, version and uses from the module package.json", async () => {
+    const root = await fixtureRoot();
+    const moduleRoot = writeFixturePackage(root, {
+      dir: "shared",
+      packageJson: {
+        name: "shared",
+        version: "1.8.0",
+        esmx: { provides: ["vue"], uses: ["base", "theme"] }
+      }
+    });
+    const fields = buildManifestProtocolFields(moduleRoot, []);
+    expect(fields.protocol).toBe(MANIFEST_PROTOCOL_VERSION);
+    expect(fields.protocol).toBe(2);
+    expect(fields.version).toBe("1.8.0");
+    expect(fields.uses).toEqual(["base", "theme"]);
+    expect(fields.provides).toEqual({});
+  });
+  it("should resolve provided package versions from node_modules of the module root", async () => {
+    const root = await fixtureRoot();
+    const moduleRoot = writeFixturePackage(root, {
+      dir: "shared",
+      packageJson: { name: "shared", version: "1.0.0" }
+    });
+    writeFixturePackage(root, {
+      dir: "shared/node_modules/vue",
+      packageJson: { name: "vue", version: "3.4.21" }
+    });
+    writeFixturePackage(root, {
+      dir: "shared/node_modules/@esmx/router",
+      packageJson: { name: "@esmx/router", version: "0.6.1" }
+    });
+    const fields = buildManifestProtocolFields(moduleRoot, [
+      "vue",
+      "@esmx/router"
+    ]);
+    expect(fields.provides).toEqual({
+      vue: { version: "3.4.21" },
+      "@esmx/router": { version: "0.6.1" }
+    });
+  });
+  it("should resolve subpath specifiers via their parent package", async () => {
+    const root = await fixtureRoot();
+    const moduleRoot = writeFixturePackage(root, {
+      dir: "shared",
+      packageJson: { name: "shared", version: "1.0.0" }
+    });
+    writeFixturePackage(root, {
+      dir: "shared/node_modules/vue",
+      packageJson: { name: "vue", version: "3.4.21" }
+    });
+    writeFixturePackage(root, {
+      dir: "shared/node_modules/@scope/pkg",
+      packageJson: { name: "@scope/pkg", version: "2.1.0" }
+    });
+    const fields = buildManifestProtocolFields(moduleRoot, [
+      "vue/jsx-runtime",
+      "@scope/pkg/client"
+    ]);
+    expect(fields.provides["vue/jsx-runtime"].version).toBe("3.4.21");
+    expect(fields.provides["@scope/pkg/client"].version).toBe("2.1.0");
+  });
+  it("should walk up node_modules for hoisted installs", async () => {
+    const root = await fixtureRoot();
+    const moduleRoot = writeFixturePackage(root, {
+      dir: "packages/shared",
+      packageJson: { name: "shared", version: "1.0.0" }
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/vue",
+      packageJson: { name: "vue", version: "3.5.2" }
+    });
+    const fields = buildManifestProtocolFields(moduleRoot, ["vue"]);
+    expect(fields.provides.vue.version).toBe("3.5.2");
+  });
+  it("should fall back to 0.0.0 for unresolvable packages", async () => {
+    const root = await fixtureRoot();
+    const moduleRoot = writeFixturePackage(root, {
+      dir: "shared",
+      packageJson: { name: "shared", version: "1.0.0" }
+    });
+    const fields = buildManifestProtocolFields(moduleRoot, ["ghost"]);
+    expect(fields.provides.ghost).toEqual({ version: "0.0.0" });
+  });
+  it("should default version and uses when package.json is missing or has no esmx field", async () => {
+    const root = await fixtureRoot();
+    const fields = buildManifestProtocolFields(
+      path.join(root, "does-not-exist"),
+      []
+    );
+    expect(fields).toEqual({
+      protocol: 2,
+      version: "0.0.0",
+      provides: {},
+      uses: []
+    });
+  });
+});
+function writeManifest(root, dir, manifest) {
+  const artifactDir = path.join(root, dir);
+  fs.mkdirSync(artifactDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(artifactDir, "manifest.json"),
+    JSON.stringify(manifest)
+  );
+  return artifactDir;
+}
+function makeModuleConfig(name, dir) {
+  return {
+    links: {
+      [name]: { name, client: dir, server: dir }
+    }
+  };
+}
+const ENV = "client";
+describe("getManifestList \u2014 protocol fields at read time", () => {
+  it("should default pre-v2 manifests to protocol 1 with empty v2 fields", async () => {
+    const root = await fixtureRoot();
+    const dir = writeManifest(root, "legacy/dist/client", {
+      name: "legacy",
+      exports: {},
+      scopes: {},
+      files: [],
+      chunks: {}
+    });
+    const [manifest] = await getManifestList(
+      ENV,
+      makeModuleConfig("legacy", dir)
+    );
+    expect(manifest.protocol).toBe(1);
+    expect(manifest.version).toBe("0.0.0");
+    expect(manifest.provides).toEqual({});
+    expect(manifest.uses).toEqual([]);
+  });
+  it("should keep v2 fields as emitted", async () => {
+    const root = await fixtureRoot();
+    const emitted = {
+      protocol: 2,
+      name: "shared",
+      version: "1.8.0",
+      provides: {
+        vue: { version: "3.4.21" }
+      },
+      uses: ["base"],
+      exports: {},
+      scopes: {},
+      files: [],
+      chunks: {}
+    };
+    const dir = writeManifest(root, "shared/dist/client", emitted);
+    const [manifest] = await getManifestList(
+      ENV,
+      makeModuleConfig("shared", dir)
+    );
+    expect(manifest.protocol).toBe(2);
+    expect(manifest.version).toBe("1.8.0");
+    expect(manifest.provides).toEqual(emitted.provides);
+    expect(manifest.uses).toEqual(["base"]);
+  });
+  it("should reject manifests with a protocol higher than the linker supports", async () => {
+    const root = await fixtureRoot();
+    const dir = writeManifest(root, "future/dist/client", {
+      protocol: MANIFEST_PROTOCOL_VERSION + 1,
+      name: "future",
+      exports: {},
+      scopes: {},
+      files: [],
+      chunks: {}
+    });
+    await expect(
+      getManifestList(ENV, makeModuleConfig("future", dir))
+    ).rejects.toThrow(/E_PROTOCOL/);
+  });
+});

package/dist/module-config.d.ts

@@ -1,11 +1,22 @@
 import type { BuildEnvironment } from './core';
 export interface ModuleConfig {
     lib?: boolean;
+    entry?: ModuleConfigEntry;
     links?: Record<string, string>;
     imports?: ModuleConfigImportMapping;
-    scopes?: Record<string, ModuleConfigImportMapping>;
     exports?: ModuleConfigExportExports;
 }
+/**
+ * Framework entry declaration (RFC 0001 Phase 2).
+ *
+ * Per side: a `./`-relative source file path declares a custom entry,
+ * `false` disables the side, and `undefined` keeps the legacy default
+ * (`./src/entry.client` / `./src/entry.server`).
+ */
+export interface ModuleConfigEntry {
+    client?: string | false;
+    server?: string | false;
+}
 export type ModuleConfigImportMapping = Record<string, string | Record<BuildEnvironment, string>>;
 export type ModuleConfigExportExports = ModuleConfigExportExport[];
 export type ModuleConfigExportExport = string | ModuleConfigExportObject;
@@ -15,12 +26,24 @@ export interface ParsedModuleConfig {
     name: string;
     root: string;
     lib: boolean;
+    entry: ParsedModuleConfigEntry;
     links: Record<string, ParsedModuleConfigLink>;
     environments: {
         client: ParsedModuleConfigEnvironment;
         server: ParsedModuleConfigEnvironment;
     };
 }
+/** A resolved framework entry: export name + source file path. */
+export interface ParsedModuleConfigEntryTarget {
+    /** Export name (import specifier suffix), e.g. 'src/entry.client'. */
+    name: string;
+    /** Source file path, e.g. './src/entry.client' or './custom/main.ts'. */
+    file: string;
+}
+export interface ParsedModuleConfigEntry {
+    client: ParsedModuleConfigEntryTarget | null;
+    server: ParsedModuleConfigEntryTarget | null;
+}
 export type ParsedModuleConfigExports = Record<string, ParsedModuleConfigExport>;
 export interface ParsedModuleConfigExport {
     name: string;
@@ -40,16 +63,33 @@ export interface ParsedModuleConfigLink {
     server: string;
     serverManifestJson: string;
 }
+/**
+ * Single source of truth for the default framework entries, used as the
+ * fallback when a module declares no explicit `entry` (RFC 0001 Phase 2
+ * threads resolved entries through the config instead of hard-coding them).
+ */
+export declare const DEFAULT_MODULE_ENTRY: Record<'client' | 'server', ParsedModuleConfigEntryTarget>;
+export declare function parseEntryConfig(config: ModuleConfig): ParsedModuleConfigEntry;
+/**
+ * Manifest chunk identifier for an entry target: `<module>@<srcRelPath>`
+ * including the file extension (bundlers key chunks by the resolved source
+ * file, so the legacy extensionless default maps to `.ts`).
+ */
+export declare function getEntryChunkId(moduleName: string, target: ParsedModuleConfigEntryTarget): string;
 export declare function parseModuleConfig(name: string, root: string, config?: ModuleConfig): ParsedModuleConfig;
 export declare function getLinks(name: string, root: string, config: ModuleConfig): Record<string, ParsedModuleConfigLink>;
 export declare function getEnvironmentImports(environment: BuildEnvironment, imports?: ModuleConfigImportMapping): Record<string, string>;
-export declare function getEnvironmentScopes(environment: BuildEnvironment, scopes?: Record<string, ModuleConfigImportMapping>): Record<string, Record<string, string>>;
-export declare function getEnvironments(config: ModuleConfig, env: BuildEnvironment, moduleName: string): ParsedModuleConfigEnvironment;
-export declare function createDefaultExports(env: BuildEnvironment): ParsedModuleConfigExports;
+export declare function getEnvironments(config: ModuleConfig, env: BuildEnvironment, moduleName: string, entry?: ParsedModuleConfigEntry): ParsedModuleConfigEnvironment;
+/**
+ * Builds the per-environment exports for the resolved framework entries.
+ * Each entry exports its source file in its own environment and an empty
+ * file on the other side (the inactive side is skipped by adapters).
+ */
+export declare function createEntryExports(entry: ParsedModuleConfigEntry, env: BuildEnvironment): ParsedModuleConfigExports;
 export declare function processStringExport(exportString: string): ParsedModuleConfigExports;
 export declare function processObjectExport(exportObject: ModuleConfigExportObject, env: BuildEnvironment): ParsedModuleConfigExports;
 export declare function resolveExportFile(config: ModuleConfigExportObjectValue, env: BuildEnvironment, name: string): string;
 export declare function processExportArray(exportArray: ModuleConfigExportExports, env: BuildEnvironment): ParsedModuleConfigExports;
-export declare function getEnvironmentExports(config: ModuleConfig, env: BuildEnvironment): ParsedModuleConfigExports;
+export declare function getEnvironmentExports(config: ModuleConfig, env: BuildEnvironment, entry?: ParsedModuleConfigEntry): ParsedModuleConfigExports;
 export declare function addPackageExportsToScopes(exports: ParsedModuleConfigExports, scopes: Record<string, Record<string, string>>, moduleName: string): Record<string, Record<string, string>>;
 export declare function parsedExportValue(value: string): ParsedModuleConfigExport;

package/dist/module-config.mjs

@@ -1,13 +1,51 @@
 import path from "node:path";
+export const DEFAULT_MODULE_ENTRY = {
+  client: { name: "src/entry.client", file: "./src/entry.client" },
+  server: { name: "src/entry.server", file: "./src/entry.server" }
+};
+const FILE_EXT_REGEX = /\.(js|mjs|cjs|jsx|mjsx|cjsx|ts|mts|cts|tsx|mtsx|ctsx)$/i;
+function parseEntryTarget(value, fallback) {
+  if (value === false) {
+    return null;
+  }
+  if (value === void 0) {
+    return { ...fallback };
+  }
+  const relativePath = value.startsWith("./") ? value.slice(2) : value;
+  const parsed = parsedExportValue(`root:${relativePath}`);
+  return { name: parsed.name, file: parsed.file };
+}
+export function parseEntryConfig(config) {
+  if (config.lib) {
+    return { client: null, server: null };
+  }
+  return {
+    client: parseEntryTarget(
+      config.entry?.client,
+      DEFAULT_MODULE_ENTRY.client
+    ),
+    server: parseEntryTarget(
+      config.entry?.server,
+      DEFAULT_MODULE_ENTRY.server
+    )
+  };
+}
+export function getEntryChunkId(moduleName, target) {
+  const relativePath = target.file.startsWith("./") ? target.file.slice(2) : target.file;
+  const withExtension = FILE_EXT_REGEX.test(relativePath) ? relativePath : `${relativePath}.ts`;
+  return `${moduleName}@${withExtension}`;
+}
 export function parseModuleConfig(name, root, config = {}) {
+  const entry = parseEntryConfig(config);
   return {
     name,
     root,
     lib: config.lib ?? false,
+    entry,
     links: getLinks(name, root, config),
     environments: {
-      client: getEnvironments(config, "client", name),
-      server: getEnvironments(config, "server", name)
+      client: getEnvironments(config, "client", name, entry),
+      server: getEnvironments(config, "server", name, entry)
     }
   };
 }
@@ -46,23 +84,12 @@ export function getEnvironmentImports(environment, imports = {}) {
   }
   return result;
 }
-export function getEnvironmentScopes(environment, scopes = {}) {
-  const result = {};
-  for (const [scopeName, scopeImports] of Object.entries(scopes)) {
-    result[scopeName] = getEnvironmentImports(environment, scopeImports);
-  }
-  return result;
-}
-export function getEnvironments(config, env, moduleName) {
+export function getEnvironments(config, env, moduleName, entry = parseEntryConfig(config)) {
   const imports = getEnvironmentImports(env, config.imports);
-  const exports = getEnvironmentExports(config, env);
-  const scopes = getEnvironmentScopes(env, {
-    ...config.scopes,
-    "": {
-      ...config.scopes?.[""],
-      ...imports
-    }
-  });
+  const exports = getEnvironmentExports(config, env, entry);
+  const scopes = {
+    "": { ...imports }
+  };
   addPackageExportsToScopes(exports, scopes, moduleName);
   return {
     imports,
@@ -70,35 +97,20 @@ export function getEnvironments(config, env, moduleName) {
     scopes
   };
 }
-export function createDefaultExports(env) {
-  switch (env) {
-    case "client":
-      return {
-        "src/entry.client": {
-          name: "src/entry.client",
-          file: "./src/entry.client",
-          pkg: false
-        },
-        "src/entry.server": {
-          name: "src/entry.server",
-          file: "",
-          pkg: false
-        }
-      };
-    case "server":
-      return {
-        "src/entry.client": {
-          name: "src/entry.client",
-          file: "",
-          pkg: false
-        },
-        "src/entry.server": {
-          name: "src/entry.server",
-          file: "./src/entry.server",
-          pkg: false
-        }
-      };
+export function createEntryExports(entry, env) {
+  const exports = {};
+  for (const side of ["client", "server"]) {
+    const target = entry[side];
+    if (!target) {
+      continue;
+    }
+    exports[target.name] = {
+      name: target.name,
+      file: side === env ? target.file : "",
+      pkg: false
+    };
   }
+  return exports;
 }
 export function processStringExport(exportString) {
   const parsedValue = parsedExportValue(exportString);
@@ -144,8 +156,8 @@ export function processExportArray(exportArray, env) {
   });
   return exports;
 }
-export function getEnvironmentExports(config, env) {
-  const exports = config.lib ? {} : createDefaultExports(env);
+export function getEnvironmentExports(config, env, entry = parseEntryConfig(config)) {
+  const exports = createEntryExports(entry, env);
   if (config.exports) {
     const userExports = processExportArray(config.exports, env);
     Object.assign(exports, userExports);
@@ -164,7 +176,6 @@ export function addPackageExportsToScopes(exports, scopes, moduleName) {
   return scopes;
 }
 export function parsedExportValue(value) {
-  const FILE_EXT_REGEX = /\.(js|mjs|cjs|jsx|mjsx|cjsx|ts|mts|cts|tsx|mtsx|ctsx)$/i;
   if (value.startsWith("pkg:")) {
     const item = value.substring("pkg:".length);
     return {