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

package/dist/declaration/lower.test.mjs

@@ -0,0 +1,333 @@
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { parseModuleConfig } from "../module-config.mjs";
+import { lowerDeclaration } from "./lower.mjs";
+import { readDeclaration } from "./reader.mjs";
+import { resolveMounts } from "./resolver.mjs";
+import {
+  createFixtureRoot,
+  removeFixtureRoot,
+  writeFixturePackage
+} from "./test-fixtures.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));
+});
+function readRootDeclaration(appDir) {
+  const pkg = readDeclaration(appDir);
+  if (!pkg) {
+    throw new Error(`fixture app at ${appDir} must declare esmx`);
+  }
+  return pkg;
+}
+describe("lowerDeclaration", () => {
+  it("should lower the ssr-micro-react-equivalent declaration to parity with the legacy config", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "shared",
+      packageJson: {
+        name: "ssr-micro-shared",
+        version: "1.0.0",
+        esmx: { provides: ["@esmx/router"] }
+      },
+      built: true
+    });
+    writeFixturePackage(root, {
+      dir: "shared/node_modules/@esmx/router",
+      packageJson: { name: "@esmx/router", version: "1.2.3" }
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "ssr-micro-react",
+        version: "1.0.0",
+        devDependencies: {
+          "@esmx/router": "*",
+          react: "*",
+          "react-dom": "*"
+        },
+        esmx: {
+          entry: {
+            client: "./src/entry.client.ts",
+            server: "./src/entry.server.ts"
+          },
+          exports: { "./src/routes": "./src/routes.ts" },
+          provides: ["react", "react-dom"],
+          uses: ["ssr-micro-shared"]
+        }
+      }
+    });
+    const pkg = readRootDeclaration(appDir);
+    const resolution = resolveMounts(appDir, pkg, {
+      "ssr-micro-shared": "../shared/dist"
+    });
+    const legacy = {
+      links: {
+        "ssr-micro-shared": path.join(root, "shared/dist")
+      },
+      imports: {
+        "@esmx/router": "ssr-micro-shared/@esmx/router"
+      },
+      exports: ["pkg:react", "pkg:react-dom", "root:src/routes.ts"]
+    };
+    const lowered = lowerDeclaration(pkg, resolution);
+    expect(lowered.imports).toEqual({
+      "@esmx/router": "ssr-micro-shared/@esmx/router"
+    });
+    expect(parseModuleConfig("ssr-micro-react", appDir, lowered)).toEqual(
+      parseModuleConfig("ssr-micro-react", appDir, legacy)
+    );
+  });
+  it("should set lib:true when no entry is declared", async () => {
+    const root = await fixtureRoot();
+    const appDir = writeFixturePackage(root, {
+      dir: "lib-module",
+      packageJson: {
+        name: "lib-module",
+        version: "1.0.0",
+        esmx: { exports: { "./widget": "./src/widget.ts" } }
+      }
+    });
+    const pkg = readRootDeclaration(appDir);
+    const resolution = resolveMounts(appDir, pkg);
+    const lowered = lowerDeclaration(pkg, resolution);
+    expect(lowered.lib).toBe(true);
+    expect(lowered.exports).toEqual([{ widget: "root:src/widget.ts" }]);
+    expect(lowered.links).toBeUndefined();
+    expect(lowered.imports).toBeUndefined();
+  });
+  it("should lower custom entries through config.entry with path-derived names", async () => {
+    const root = await fixtureRoot();
+    const appDir = writeFixturePackage(root, {
+      dir: "custom-entry",
+      packageJson: {
+        name: "custom-entry",
+        version: "1.0.0",
+        esmx: {
+          entry: {
+            client: "./src/main.client.ts",
+            server: "./src/entry.server.ts"
+          }
+        }
+      }
+    });
+    const pkg = readRootDeclaration(appDir);
+    const resolution = resolveMounts(appDir, pkg);
+    const lowered = lowerDeclaration(pkg, resolution);
+    expect(lowered.lib).toBeUndefined();
+    expect(lowered.entry).toEqual({ client: "./src/main.client.ts" });
+    expect(lowered.exports).toBeUndefined();
+    const parsed = parseModuleConfig("custom-entry", appDir, lowered);
+    expect(parsed.entry).toEqual({
+      client: { name: "src/main.client", file: "./src/main.client.ts" },
+      server: { name: "src/entry.server", file: "./src/entry.server" }
+    });
+    expect(parsed.environments.client.exports["src/main.client"]).toEqual({
+      name: "src/main.client",
+      file: "./src/main.client.ts",
+      pkg: false
+    });
+    expect(parsed.environments.server.exports["src/entry.server"]).toEqual({
+      name: "src/entry.server",
+      file: "./src/entry.server",
+      pkg: false
+    });
+  });
+  it("should disable an undeclared entry side", async () => {
+    const root = await fixtureRoot();
+    const appDir = writeFixturePackage(root, {
+      dir: "client-only",
+      packageJson: {
+        name: "client-only",
+        version: "1.0.0",
+        esmx: { entry: { client: "./src/entry.client.ts" } }
+      }
+    });
+    const pkg = readRootDeclaration(appDir);
+    const resolution = resolveMounts(appDir, pkg);
+    const lowered = lowerDeclaration(pkg, resolution);
+    expect(lowered.entry).toEqual({ server: false });
+    const parsed = parseModuleConfig("client-only", appDir, lowered);
+    expect(parsed.entry.server).toBeNull();
+    expect(
+      parsed.environments.server.exports["src/entry.server"]
+    ).toBeUndefined();
+    expect(
+      parsed.environments.client.exports["src/entry.client"].file
+    ).toBe("./src/entry.client");
+  });
+  it("should preserve env forks including false in exports", async () => {
+    const root = await fixtureRoot();
+    const appDir = writeFixturePackage(root, {
+      dir: "forked",
+      packageJson: {
+        name: "forked",
+        version: "1.0.0",
+        esmx: {
+          exports: {
+            "./store": {
+              client: "./src/store.client.ts",
+              server: false
+            }
+          }
+        }
+      }
+    });
+    const pkg = readRootDeclaration(appDir);
+    const resolution = resolveMounts(appDir, pkg);
+    const lowered = lowerDeclaration(pkg, resolution);
+    expect(lowered.exports).toEqual([
+      {
+        store: {
+          client: "root:src/store.client.ts",
+          server: false
+        }
+      }
+    ]);
+    const parsed = parseModuleConfig("forked", appDir, lowered);
+    expect(parsed.environments.client.exports.store.file).toBe(
+      "./src/store.client.ts"
+    );
+    expect(parsed.environments.server.exports.store.file).toBe("");
+  });
+  it("should wire a single-owner supply group into config.imports", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "node_modules/shared",
+      packageJson: {
+        name: "shared",
+        version: "1.0.0",
+        dependencies: { vue: "^3.4.0" },
+        esmx: { provides: ["vue"] }
+      },
+      built: true
+    });
+    writeFixturePackage(root, {
+      dir: "node_modules/shared/node_modules/vue",
+      packageJson: { name: "vue", version: "3.5.2" }
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        dependencies: { vue: "^3.4.0" },
+        esmx: { uses: ["shared"] }
+      }
+    });
+    const pkg = readRootDeclaration(appDir);
+    const lowered = lowerDeclaration(pkg, resolveMounts(appDir, pkg));
+    expect(lowered.imports).toEqual({ vue: "shared/vue" });
+  });
+  describe("per-major group wiring", () => {
+    async function multiMajorFixture() {
+      const root = await fixtureRoot();
+      writeFixturePackage(root, {
+        dir: "node_modules/vue2-app",
+        packageJson: {
+          name: "vue2-app",
+          version: "1.0.0",
+          dependencies: { vue: "2.7.16" },
+          esmx: { provides: ["vue"] }
+        },
+        built: true
+      });
+      writeFixturePackage(root, {
+        dir: "node_modules/vue2-app/node_modules/vue",
+        packageJson: { name: "vue", version: "2.7.16" }
+      });
+      writeFixturePackage(root, {
+        dir: "node_modules/vue3-base",
+        packageJson: {
+          name: "vue3-base",
+          version: "1.0.0",
+          dependencies: { vue: "^3.5.0" },
+          esmx: { provides: ["vue"] }
+        },
+        built: true
+      });
+      writeFixturePackage(root, {
+        dir: "node_modules/vue3-base/node_modules/vue",
+        packageJson: { name: "vue", version: "3.5.13" }
+      });
+      return root;
+    }
+    function lowerApp(appDir) {
+      const pkg = readRootDeclaration(appDir);
+      const resolution = resolveMounts(appDir, pkg);
+      return { resolution, lowered: lowerDeclaration(pkg, resolution) };
+    }
+    it("should wire a ^3 consumer to the vue3 group winner", async () => {
+      const root = await multiMajorFixture();
+      const appDir = writeFixturePackage(root, {
+        dir: "app",
+        packageJson: {
+          name: "app",
+          version: "1.0.0",
+          peerDependencies: { vue: "^3.5.0" },
+          esmx: { uses: ["vue2-app", "vue3-base"] }
+        }
+      });
+      const { lowered } = lowerApp(appDir);
+      expect(lowered.imports?.vue).toBe("vue3-base/vue");
+    });
+    it("should wire a ^2 consumer to the vue2 group winner", async () => {
+      const root = await multiMajorFixture();
+      const appDir = writeFixturePackage(root, {
+        dir: "app",
+        packageJson: {
+          name: "app",
+          version: "1.0.0",
+          dependencies: { vue: "^2.7.0" },
+          esmx: { uses: ["vue2-app", "vue3-base"] }
+        }
+      });
+      const { lowered } = lowerApp(appDir);
+      expect(lowered.imports?.vue).toBe("vue2-app/vue");
+    });
+    it("should wire a range-less consumer to the highest major with W_NO_RANGE", async () => {
+      const root = await multiMajorFixture();
+      const appDir = writeFixturePackage(root, {
+        dir: "app",
+        packageJson: {
+          name: "app",
+          version: "1.0.0",
+          esmx: { uses: ["vue2-app", "vue3-base"] }
+        }
+      });
+      const { resolution, lowered } = lowerApp(appDir);
+      expect(lowered.imports?.vue).toBe("vue3-base/vue");
+      expect(
+        resolution.diagnostics.some(
+          (d) => d.code === "W_NO_RANGE" && d.package === "vue"
+        )
+      ).toBe(true);
+    });
+    it("should let a 2.x provider wire to its own copy despite a 3.x group existing", async () => {
+      const root = await multiMajorFixture();
+      const appDir = writeFixturePackage(root, {
+        dir: "app",
+        packageJson: {
+          name: "app",
+          version: "1.0.0",
+          dependencies: { vue: "2.7.16" },
+          esmx: { uses: ["vue3-base"], provides: ["vue"] }
+        }
+      });
+      writeFixturePackage(root, {
+        dir: "app/node_modules/vue",
+        packageJson: { name: "vue", version: "2.7.16" }
+      });
+      const { resolution, lowered } = lowerApp(appDir);
+      expect(lowered.imports?.vue).toBeUndefined();
+      expect(
+        resolution.diagnostics.filter((d) => d.severity === "error")
+      ).toEqual([]);
+    });
+  });
+});

package/dist/declaration/reader.d.ts

@@ -0,0 +1,28 @@
+import type { Diagnostic, EsmxDeclaration } from './types';
+/** Package facts the resolver needs, read from a package root directory. */
+export interface PackageRecord {
+    name: string;
+    version: string;
+    root: string;
+    private: boolean;
+    dependencies: Record<string, string>;
+    peerDependencies: Record<string, string>;
+    devDependencies: Record<string, string>;
+    declaration: EsmxDeclaration | null;
+    diagnostics: Diagnostic[];
+}
+export interface ReadDeclarationResult extends PackageRecord {
+    declaration: EsmxDeclaration;
+}
+/**
+ * Reads a package root's package.json into a PackageRecord, whether or not
+ * it carries an `esmx` declaration. Returns null when no package.json can
+ * be read.
+ */
+export declare function readPackageRecord(packageDir: string): PackageRecord | null;
+/**
+ * Reads a package's `esmx` declaration. Returns null when the package has
+ * no `esmx` field (legacy module) or no readable package.json. Schema
+ * violations are reported in `diagnostics` with the valid remainder kept.
+ */
+export declare function readDeclaration(packageDir: string): ReadDeclarationResult | null;

package/dist/declaration/reader.mjs

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+import path from "node:path";
+import { validateDeclaration } from "./schema.mjs";
+function readJsonFile(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function toStringRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return {};
+  }
+  const result = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (typeof entry === "string") {
+      result[key] = entry;
+    }
+  }
+  return result;
+}
+export function readPackageRecord(packageDir) {
+  const json = readJsonFile(path.resolve(packageDir, "package.json"));
+  if (typeof json !== "object" || json === null || Array.isArray(json)) {
+    return null;
+  }
+  const pkg = json;
+  const name = typeof pkg.name === "string" ? pkg.name : "";
+  const diagnostics = [];
+  let declaration = null;
+  if (pkg.esmx !== void 0) {
+    const validated = validateDeclaration(pkg.esmx, name || packageDir);
+    diagnostics.push(...validated.diagnostics);
+    declaration = validated.declaration ?? {};
+  }
+  return {
+    name,
+    version: typeof pkg.version === "string" ? pkg.version : "",
+    root: packageDir,
+    private: pkg.private === true,
+    dependencies: toStringRecord(pkg.dependencies),
+    peerDependencies: toStringRecord(pkg.peerDependencies),
+    devDependencies: toStringRecord(pkg.devDependencies),
+    declaration,
+    diagnostics
+  };
+}
+export function readDeclaration(packageDir) {
+  const record = readPackageRecord(packageDir);
+  if (!record || record.declaration === null) {
+    return null;
+  }
+  return { ...record, declaration: record.declaration };
+}

package/dist/declaration/reinit.e2e.test.d.ts

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

package/dist/declaration/reinit.e2e.test.mjs

@@ -0,0 +1,117 @@
+import fs from "node:fs";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { COMMAND, Esmx } from "../core.mjs";
+import { MANIFEST_PROTOCOL_VERSION } from "../manifest-json.mjs";
+import { createFixtureRoot, removeFixtureRoot } from "./test-fixtures.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));
+});
+function writeModule(rootDir, dir, packageJson, manifest) {
+  const moduleDir = path.join(rootDir, dir);
+  fs.mkdirSync(moduleDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(moduleDir, "package.json"),
+    JSON.stringify(packageJson, null, 4)
+  );
+  const full = {
+    protocol: MANIFEST_PROTOCOL_VERSION,
+    name: String(packageJson.name),
+    version: String(packageJson.version ?? "0.0.0"),
+    provides: {},
+    uses: [],
+    scopes: {},
+    exports: {},
+    files: [],
+    chunks: {},
+    ...manifest
+  };
+  for (const env of ["client", "server"]) {
+    const envDir = path.join(moduleDir, "dist", env);
+    fs.mkdirSync(envDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(envDir, "manifest.json"),
+      JSON.stringify(full, null, 4)
+    );
+  }
+  return moduleDir;
+}
+function buildFixture(root, sharedExportFile) {
+  writeModule(
+    root,
+    "app/node_modules/shared",
+    {
+      name: "shared",
+      version: "1.0.0",
+      esmx: { exports: { "./ui": "./src/ui.ts" } }
+    },
+    {
+      exports: {
+        ui: {
+          name: "ui",
+          pkg: false,
+          file: sharedExportFile,
+          identifier: "shared/ui"
+        }
+      }
+    }
+  );
+  return writeModule(
+    root,
+    "app",
+    {
+      name: "app",
+      version: "1.0.0",
+      esmx: { uses: ["shared"] }
+    },
+    {}
+  );
+}
+function rewriteSharedExport(appDir, file) {
+  const manifestPath = path.join(
+    appDir,
+    "node_modules/shared/dist/client/manifest.json"
+  );
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+  manifest.exports.ui.file = file;
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 4));
+}
+describe("Esmx.reinit generational relink (RFC 0001 \xA79)", () => {
+  it("adopts a republished remote on a new generation", async () => {
+    const root = await fixtureRoot();
+    const appDir = buildFixture(root, "ui.gen1.mjs");
+    const esmx = new Esmx({ root: appDir, isProd: true });
+    await esmx.init(COMMAND.preview);
+    const before = await esmx.getImportMap("client");
+    expect(before.imports?.["shared/ui"]).toBe("/shared/ui.gen1.mjs");
+    rewriteSharedExport(appDir, "ui.gen2.mjs");
+    const stillCached = await esmx.getImportMap("client");
+    expect(stillCached.imports?.["shared/ui"]).toBe("/shared/ui.gen1.mjs");
+    const ok = await esmx.reinit();
+    expect(ok).toBe(true);
+    const after = await esmx.getImportMap("client");
+    expect(after.imports?.["shared/ui"]).toBe("/shared/ui.gen2.mjs");
+  });
+  it("rolls back to the previous generation when the relink fails", async () => {
+    const root = await fixtureRoot();
+    const appDir = buildFixture(root, "ui.gen1.mjs");
+    const esmx = new Esmx({ root: appDir, isProd: true });
+    await esmx.init(COMMAND.preview);
+    const moduleConfigBefore = esmx.moduleConfig;
+    fs.writeFileSync(path.join(appDir, "package.json"), "{ not json");
+    await expect(esmx.reinit()).rejects.toThrow();
+    expect(esmx.moduleConfig).toBe(moduleConfigBefore);
+    const after = await esmx.getImportMap("client");
+    expect(after.imports?.["shared/ui"]).toBe("/shared/ui.gen1.mjs");
+  });
+  it("throws when called before init", async () => {
+    const esmx = new Esmx({ root: "/nonexistent" });
+    await expect(esmx.reinit()).rejects.toThrow();
+  });
+});

package/dist/declaration/resolver.d.ts

@@ -0,0 +1,59 @@
+import type { ReadDeclarationResult } from './reader';
+import { type Diagnostic } from './types';
+/** A resolved mount-table entry (RFC §6). */
+export interface ResolvedMount {
+    name: string;
+    /** Package root directory (realpath'd for auto-mounts). */
+    root: string;
+    /** Artifact directory, `<root>/dist` for auto-mounts. */
+    artifactDir: string;
+    /** Whether `dist/client/manifest.json` exists. */
+    built: boolean;
+}
+/**
+ * Winner of the recursive supply merge for one (package, major) group
+ * (RFC §7, per-major amendment): elections are keyed by the MAJOR of the
+ * provider's resolved version, so coexisting majors are isolated islands,
+ * each with its own winner.
+ */
+export interface SupplyGroup {
+    /** Major of the group's resolved version; 'unknown' when unresolvable. */
+    major: number | 'unknown';
+    provider: string;
+    /** Provider's resolved installed version, null when unresolvable. */
+    version: string | null;
+}
+/** Per-package election result: one winner per major group. */
+export interface SupplyEntry {
+    /** Group winners, highest major first ('unknown' last). */
+    groups: SupplyGroup[];
+}
+export interface ResolveMountsResult {
+    supply: Record<string, SupplyEntry>;
+    mounts: Record<string, ResolvedMount>;
+    diagnostics: Diagnostic[];
+}
+export interface ResolverEnvLinks {
+    [moduleName: string]: string;
+}
+/**
+ * Consumer-side group selection (RFC §7, per-major amendment): the group
+ * whose winner satisfies `range`; multiple satisfying groups → highest
+ * major; no range (or a workspace placeholder) → highest major group;
+ * range satisfied by no group → highest major group (the caller diagnoses
+ * the violation as E_VERSION). Groups whose version cannot be checked
+ * against the range (unparsable either side) rank after satisfying groups
+ * but before violating ones, per the RFC §11 skip-the-gate rule.
+ */
+export declare function selectSupplyGroup(entry: SupplyEntry, range?: string): SupplyGroup | null;
+/**
+ * Resolves the mount table and the recursive supply merge for a root
+ * module's declaration (RFC §6 + §7 phases 1–2).
+ *
+ * - `envLinks` entries override auto-mounting; their values follow today's
+ *   `ModuleConfig.links` semantics (artifact directory, resolved relative
+ *   to `rootDir`).
+ * - Auto-mounts resolve via Node resolution from the DECLARING module's
+ *   own location and are realpath'd once.
+ */
+export declare function resolveMounts(rootDir: string, rootPackage: ReadDeclarationResult, envLinks?: ResolverEnvLinks): ResolveMountsResult;