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

package/dist/core.mjs

@@ -6,6 +6,7 @@ import { cwd } from "node:process";
 import { pathToFileURL } from "node:url";
 import serialize from "serialize-javascript";
 import { createApp } from "./app.mjs";
+import { resolveModuleOptions } from "./declaration/index.mjs";
 import { getManifestList } from "./manifest-json.mjs";
 import {
   parseModuleConfig
@@ -243,13 +244,14 @@ export class Esmx {
     if (this._readied) {
       throw new Error("Cannot be initialized repeatedly");
     }
-    const { name } = await this.readJson(
+    const packageJson = await this.readJson(
       path.resolve(this.root, "package.json")
     );
+    const name = String(packageJson.name);
     const moduleConfig = parseModuleConfig(
       name,
       this.root,
-      this._options.modules
+      resolveModuleOptions(this.root, packageJson, this._options.modules)
     );
     const packConfig = parsePackConfig(this._options.packs);
     this._readied = {
@@ -312,6 +314,67 @@ export class Esmx {
     }
     return true;
   }
+  /**
+   * Atomic generational relink (RFC 0001 §9).
+   *
+   * In-process remotes are not hot-swappable: the server import map and the
+   * module loader are captured once when the app is created. When a mounted
+   * remote republishes (new resolved versions, new wiring), the composer
+   * adopts it by relinking — building a NEW generation (fresh cache,
+   * re-resolved module config, rebuilt app capturing a new import map +
+   * loader) and switching to it atomically.
+   *
+   * The previous generation keeps serving throughout the rebuild; the new
+   * app is installed only once it is fully built, then the previous app's
+   * resources are released. If the rebuild fails, the previous generation
+   * is fully restored (rollback) and the error propagates — a failed relink
+   * never takes the running server down.
+   *
+   * Scope: the production render path (`start`/`preview`). Dev rebuilds its
+   * own app. Cross-compiler dev-watch invalidation remains future work.
+   *
+   * @returns true once the new generation is live.
+   * @throws {NotReadyError} when called before {@link init}.
+   *
+   * @example
+   * ```ts
+   * // After a mounted remote republishes:
+   * await esmx.reinit(); // new generation live, old requests drained
+   * ```
+   */
+  async reinit() {
+    const previous = this.readied;
+    const packageJson = await this.readJson(
+      path.resolve(this.root, "package.json")
+    );
+    const name = String(packageJson.name);
+    const moduleConfig = parseModuleConfig(
+      name,
+      this.root,
+      resolveModuleOptions(this.root, packageJson, this._options.modules)
+    );
+    const packConfig = parsePackConfig(this._options.packs);
+    this._readied = {
+      command: previous.command,
+      app: previous.app,
+      moduleConfig,
+      packConfig,
+      cache: createCache(this.isProd)
+    };
+    try {
+      const command = previous.command;
+      const devApp = this._options.devApp || defaultDevApp;
+      const app = ["dev" /* dev */, "build" /* build */].includes(command) ? await devApp(this) : await createApp(this, command);
+      this.readied.app = app;
+    } catch (error) {
+      this._readied = previous;
+      throw error;
+    }
+    if (previous.app?.destroy) {
+      await previous.app.destroy();
+    }
+    return true;
+  }
   /**
    * Execute the application's build process.
    *
@@ -465,7 +528,7 @@ export class Esmx {
       await this._options.postBuild?.(this);
       return true;
     } catch (e) {
-      console.error(e);
+      console.error("[@esmx/core] postBuild hook failed:", e);
       return false;
     }
   }
@@ -770,6 +833,7 @@ export class Esmx {
       `getImportMap-${mode}`,
       async () => {
         const importmap = await this.getImportMap("client");
+        const { integrity } = importmap;
         const { basePathPlaceholder } = this;
         let filepath = null;
         if (this._importmapHash === null) {
@@ -817,7 +881,8 @@ document.head.appendChild(script);
           return {
             src,
             filepath,
-            code: `<script data-base="${basePathPlaceholder}" src="${src}"><\/script>`
+            code: `<script data-base="${basePathPlaceholder}" src="${src}"><\/script>`,
+            integrity: integrity ?? null
           };
         }
         if (basePathPlaceholder) {
@@ -835,7 +900,8 @@ document.head.appendChild(script);
         return {
           src: null,
           filepath: null,
-          code: `<script type="importmap">${serialize(importmap, { isJSON: true, unsafe: true })}<\/script>`
+          code: `<script type="importmap">${serialize(importmap, { isJSON: true, unsafe: true })}<\/script>`,
+          integrity: integrity ?? null
         };
       }
     );

package/dist/declaration/index.d.ts

@@ -0,0 +1,47 @@
+import type { ModuleConfig } from '../module-config';
+import type { ResolvedMount, ResolverEnvLinks, SupplyEntry } from './resolver';
+import type { Diagnostic } from './types';
+export { lowerDeclaration } from './lower';
+export type { PackageRecord, ReadDeclarationResult } from './reader';
+export { readDeclaration, readPackageRecord } from './reader';
+export type { ResolvedMount, ResolveMountsResult, ResolverEnvLinks, SupplyEntry, SupplyGroup } from './resolver';
+export { resolveMounts, selectSupplyGroup } from './resolver';
+export type { ValidateDeclarationResult } from './schema';
+export { esmxDeclarationSchema, validateDeclaration } from './schema';
+export { parseSemver, satisfiesRange } from './semver';
+export type { Diagnostic, DiagnosticCheck, DiagnosticCodeValue, DiagnosticSeverity, EsmxDeclaration, EsmxDeclarationEntry, EsmxDeclarationExportFork, EsmxDeclarationExportValue } from './types';
+export { DiagnosticCode } from './types';
+export interface ResolveDeclarationOptions {
+    /**
+     * Explicit mount overrides (environment fact): module name → artifact
+     * directory, same semantics as today's `ModuleConfig.links` values,
+     * resolved relative to `rootDir`.
+     */
+    envLinks?: ResolverEnvLinks;
+}
+export interface ResolveDeclarationResult {
+    /** The declaration lowered to today's internal ModuleConfig IR. */
+    config: ModuleConfig;
+    /** Merged supply table: bare package → per-major group winners. */
+    supply: Record<string, SupplyEntry>;
+    /** Resolved mount table: module name → mounted artifact location. */
+    mounts: Record<string, ResolvedMount>;
+    diagnostics: Diagnostic[];
+}
+/**
+ * One-call helper composing reader + resolver + lowering (RFC Phase 1).
+ * Returns null when the package at `rootDir` has no `esmx` declaration.
+ */
+export declare function resolveDeclaration(rootDir: string, options?: ResolveDeclarationOptions): ResolveDeclarationResult | null;
+/**
+ * Integration point for `Esmx.init`: decides between the legacy
+ * `options.modules` path and the declaration path.
+ *
+ * - No `esmx` field in package.json → legacy path, untouched.
+ * - `esmx` field present and `options.modules` carries protocol facts
+ *   (lib/imports/exports) → E_PROTOCOL_IN_BEHAVIOR (protocol facts
+ *   must live in package.json only).
+ * - `links` alone is an environment fact and is passed to the resolver as
+ *   explicit mount overrides.
+ */
+export declare function resolveModuleOptions(rootDir: string, packageJson: Record<string, unknown>, modules?: ModuleConfig): ModuleConfig | undefined;

package/dist/declaration/index.mjs

@@ -0,0 +1,63 @@
+import { lowerDeclaration } from "./lower.mjs";
+import { readDeclaration } from "./reader.mjs";
+import { resolveMounts } from "./resolver.mjs";
+export { lowerDeclaration } from "./lower.mjs";
+export { readDeclaration, readPackageRecord } from "./reader.mjs";
+export { resolveMounts, selectSupplyGroup } from "./resolver.mjs";
+export { esmxDeclarationSchema, validateDeclaration } from "./schema.mjs";
+export { parseSemver, satisfiesRange } from "./semver.mjs";
+export { DiagnosticCode } from "./types.mjs";
+export function resolveDeclaration(rootDir, options = {}) {
+  const pkg = readDeclaration(rootDir);
+  if (!pkg) {
+    return null;
+  }
+  const resolution = resolveMounts(rootDir, pkg, options.envLinks);
+  return {
+    config: lowerDeclaration(pkg, resolution),
+    supply: resolution.supply,
+    mounts: resolution.mounts,
+    diagnostics: resolution.diagnostics
+  };
+}
+const PROTOCOL_MODULE_KEYS = ["lib", "imports", "exports"];
+function formatDiagnostic(diagnostic) {
+  const location = diagnostic.package ? `${diagnostic.module} \u2192 ${diagnostic.package}` : diagnostic.module;
+  return `[${diagnostic.code}] (${location}) ${diagnostic.message} Fix: ${diagnostic.fix}`;
+}
+export function resolveModuleOptions(rootDir, packageJson, modules) {
+  if (packageJson.esmx === void 0) {
+    return modules;
+  }
+  if (modules) {
+    const protocolKeys = PROTOCOL_MODULE_KEYS.filter(
+      (key) => modules[key] !== void 0
+    );
+    if (protocolKeys.length > 0) {
+      throw new Error(
+        `[E_PROTOCOL_IN_BEHAVIOR] package.json declares "esmx" but options.modules contains protocol field(s): ${protocolKeys.join(", ")}. Protocol facts must live in the package.json "esmx" field only; entry.node.ts keeps behavior (devApp, server, postBuild) and environment links. Fix: move ${protocolKeys.join(", ")} into the "esmx" declaration and delete them from options.modules.`
+      );
+    }
+  }
+  const resolved = resolveDeclaration(rootDir, {
+    envLinks: modules?.links
+  });
+  if (!resolved) {
+    return modules;
+  }
+  const errors = resolved.diagnostics.filter(
+    (diagnostic) => diagnostic.severity === "error"
+  );
+  if (errors.length > 0) {
+    throw new Error(
+      `Esmx declaration resolution failed with ${errors.length} error(s):
+` + errors.map((error) => `  ${formatDiagnostic(error)}`).join("\n")
+    );
+  }
+  for (const warning of resolved.diagnostics) {
+    if (warning.severity === "warning") {
+      console.warn(formatDiagnostic(warning));
+    }
+  }
+  return resolved.config;
+}

package/dist/declaration/index.test.d.ts

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

package/dist/declaration/index.test.mjs

@@ -0,0 +1,202 @@
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { resolveDeclaration, resolveModuleOptions } from "./index.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 () => {
+  vi.restoreAllMocks();
+  await Promise.all(fixtureRoots.splice(0).map(removeFixtureRoot));
+});
+describe("resolveDeclaration", () => {
+  it("should return null when the package has no esmx field", async () => {
+    const root = await fixtureRoot();
+    const appDir = writeFixturePackage(root, {
+      dir: "legacy",
+      packageJson: { name: "legacy", version: "1.0.0" }
+    });
+    expect(resolveDeclaration(appDir)).toBeNull();
+  });
+  it("should compose reader, resolver and lowering", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "app/node_modules/shared",
+      packageJson: {
+        name: "shared",
+        version: "1.0.0",
+        esmx: { provides: ["vue"] }
+      },
+      built: true
+    });
+    writeFixturePackage(root, {
+      dir: "app/node_modules/shared/node_modules/vue",
+      packageJson: { name: "vue", version: "3.4.21" }
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        dependencies: { vue: "^3.4.0" },
+        esmx: {
+          entry: {
+            client: "./src/entry.client.ts",
+            server: "./src/entry.server.ts"
+          },
+          uses: ["shared"]
+        }
+      }
+    });
+    const result = resolveDeclaration(appDir);
+    expect(result).not.toBeNull();
+    expect(result?.supply.vue).toEqual({
+      groups: [{ major: 3, provider: "shared", version: "3.4.21" }]
+    });
+    expect(result?.config).toEqual({
+      links: {
+        shared: path.join(appDir, "node_modules/shared/dist")
+      },
+      imports: { vue: "shared/vue" }
+    });
+    expect(
+      result?.diagnostics.filter((d) => d.severity === "error")
+    ).toEqual([]);
+  });
+});
+describe("resolveModuleOptions", () => {
+  it("should keep the legacy path untouched when there is no esmx field", async () => {
+    const root = await fixtureRoot();
+    const appDir = writeFixturePackage(root, {
+      dir: "legacy",
+      packageJson: { name: "legacy", version: "1.0.0" }
+    });
+    const modules = {
+      imports: { vue: "shared/vue" },
+      exports: ["pkg:vue"]
+    };
+    const result = resolveModuleOptions(
+      appDir,
+      { name: "legacy" },
+      modules
+    );
+    expect(result).toBe(modules);
+  });
+  it("should throw E_PROTOCOL_IN_BEHAVIOR when esmx coexists with protocol fields in options.modules", async () => {
+    const root = await fixtureRoot();
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        esmx: { provides: ["vue"] }
+      }
+    });
+    expect(
+      () => resolveModuleOptions(
+        appDir,
+        { name: "app", esmx: { provides: ["vue"] } },
+        { imports: { vue: "shared/vue" } }
+      )
+    ).toThrowError(/E_PROTOCOL_IN_BEHAVIOR/);
+  });
+  it("should allow links-only options.modules as environment overrides", async () => {
+    const root = await fixtureRoot();
+    writeFixturePackage(root, {
+      dir: "shared",
+      packageJson: {
+        name: "shared",
+        version: "1.0.0",
+        esmx: { provides: ["vue"] }
+      },
+      built: true
+    });
+    writeFixturePackage(root, {
+      dir: "shared/node_modules/vue",
+      packageJson: { name: "vue", version: "3.4.21" }
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        dependencies: { vue: "^3.4.0" },
+        esmx: {
+          entry: {
+            client: "./src/entry.client.ts",
+            server: "./src/entry.server.ts"
+          },
+          uses: ["shared"]
+        }
+      }
+    });
+    const result = resolveModuleOptions(
+      appDir,
+      { name: "app", esmx: {} },
+      { links: { shared: "../shared/dist" } }
+    );
+    expect(result).toEqual({
+      links: { shared: path.join(root, "shared/dist") },
+      imports: { vue: "shared/vue" }
+    });
+  });
+  it("should throw a clear error listing error diagnostics", async () => {
+    const root = await fixtureRoot();
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        esmx: {
+          entry: { client: "./src/entry.client.ts" },
+          uses: ["ghost"]
+        }
+      }
+    });
+    expect(
+      () => resolveModuleOptions(appDir, { name: "app", esmx: {} })
+    ).toThrowError(/E_NOT_LINKED[\s\S]*ghost/);
+  });
+  it("should print warnings instead of throwing", async () => {
+    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" }
+    });
+    const appDir = writeFixturePackage(root, {
+      dir: "app",
+      packageJson: {
+        name: "app",
+        version: "1.0.0",
+        esmx: {
+          entry: { client: "./src/entry.client.ts" },
+          uses: ["base"]
+        }
+      }
+    });
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {
+    });
+    const result = resolveModuleOptions(appDir, { name: "app", esmx: {} });
+    expect(result?.imports).toEqual({ vue: "base/vue" });
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining("W_NO_RANGE")
+    );
+  });
+});

package/dist/declaration/lower.d.ts

@@ -0,0 +1,11 @@
+import type { ModuleConfig } from '../module-config';
+import type { ReadDeclarationResult } from './reader';
+import type { ResolveMountsResult } from './resolver';
+/**
+ * Lowers a declaration + resolution result to today's internal
+ * `ModuleConfig` IR (RFC Phase 1+2): default entry paths ride on the
+ * legacy defaults, custom/disabled entries flow through `config.entry`,
+ * `provides` become `pkg:` exports, the merged supply table becomes
+ * `imports`, and mounts become `links`.
+ */
+export declare function lowerDeclaration(pkg: ReadDeclarationResult, resolution: ResolveMountsResult): ModuleConfig;

package/dist/declaration/lower.mjs

@@ -0,0 +1,78 @@
+import { selectSupplyGroup } from "./resolver.mjs";
+const DEFAULT_CLIENT_ENTRY = "./src/entry.client.ts";
+const DEFAULT_SERVER_ENTRY = "./src/entry.server.ts";
+function toRootExport(relativePath) {
+  return `root:${relativePath.slice(2)}`;
+}
+function lowerExportValue(value) {
+  if (typeof value === "string") {
+    return toRootExport(value);
+  }
+  return {
+    client: typeof value.client === "string" ? toRootExport(value.client) : false,
+    server: typeof value.server === "string" ? toRootExport(value.server) : false
+  };
+}
+function lowerEntry(entry) {
+  const lowered = {};
+  if (!entry.client) {
+    lowered.client = false;
+  } else if (entry.client !== DEFAULT_CLIENT_ENTRY) {
+    lowered.client = entry.client;
+  }
+  if (!entry.server) {
+    lowered.server = false;
+  } else if (entry.server !== DEFAULT_SERVER_ENTRY) {
+    lowered.server = entry.server;
+  }
+  return Object.keys(lowered).length > 0 ? lowered : null;
+}
+export function lowerDeclaration(pkg, resolution) {
+  const { declaration } = pkg;
+  const config = {};
+  if (!declaration.entry) {
+    config.lib = true;
+  } else {
+    const entry = lowerEntry(declaration.entry);
+    if (entry) {
+      config.entry = entry;
+    }
+  }
+  const links = {};
+  for (const mount of Object.values(resolution.mounts)) {
+    links[mount.name] = mount.artifactDir;
+  }
+  if (Object.keys(links).length > 0) {
+    config.links = links;
+  }
+  const imports = {};
+  for (const [packageName, entry] of Object.entries(resolution.supply)) {
+    if (entry.groups.some((group2) => group2.provider === pkg.name)) {
+      continue;
+    }
+    const range = pkg.dependencies[packageName] ?? pkg.peerDependencies[packageName];
+    const group = selectSupplyGroup(entry, range);
+    if (!group) {
+      continue;
+    }
+    imports[packageName] = `${group.provider}/${packageName}`;
+  }
+  if (Object.keys(imports).length > 0) {
+    config.imports = imports;
+  }
+  const exports = [];
+  for (const provided of declaration.provides ?? []) {
+    exports.push(`pkg:${provided}`);
+  }
+  const exportObject = {};
+  for (const [subpath, value] of Object.entries(declaration.exports ?? {})) {
+    exportObject[subpath.slice(2)] = lowerExportValue(value);
+  }
+  if (Object.keys(exportObject).length > 0) {
+    exports.push(exportObject);
+  }
+  if (exports.length > 0) {
+    config.exports = exports;
+  }
+  return config;
+}

package/dist/declaration/lower.test.d.ts

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