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

package/src/manifest-json.test.ts

@@ -0,0 +1,236 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+import type { BuildEnvironment } from './core';
+import {
+    createFixtureRoot,
+    removeFixtureRoot,
+    writeFixturePackage
+} from './declaration/test-fixtures';
+import type { ManifestJson } from './manifest-json';
+import {
+    buildManifestProtocolFields,
+    getManifestList,
+    MANIFEST_PROTOCOL_VERSION
+} from './manifest-json';
+import type { ParsedModuleConfig } from './module-config';
+
+const fixtureRoots: string[] = [];
+
+async function fixtureRoot(): Promise<string> {
+    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: string,
+    dir: string,
+    manifest: Record<string, unknown>
+): string {
+    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: string, dir: string): ParsedModuleConfig {
+    return {
+        links: {
+            [name]: { name, client: dir, server: dir }
+        }
+    } as unknown as ParsedModuleConfig;
+}
+
+const ENV: BuildEnvironment = 'client';
+
+describe('getManifestList — 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: Partial<ManifestJson> = {
+            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/src/manifest-json.ts

@@ -1,14 +1,42 @@
+import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 
 import type { BuildEnvironment } from './core';
 import type { ParsedModuleConfig } from './module-config';
 
+/**
+ * Manifest protocol version emitted by the bundler plugins (RFC 0001 §5).
+ * The linker rejects manifests whose `protocol` is HIGHER than this value.
+ */
+export const MANIFEST_PROTOCOL_VERSION = 2;
+
 export interface ManifestJson {
+    /**
+     * Manifest protocol version (RFC 0001 §5). Absent in pre-v2 manifests;
+     * readers treat absence as protocol 1 and skip v2-only checks.
+     */
+    protocol: number;
     /**
      * Module name
      */
     name: string;
+    /**
+     * Module version, transcribed from the module's package.json at build
+     * time (RFC 0001 §5). Pre-v2 manifests default to '0.0.0' at read time.
+     */
+    version: string;
+    /**
+     * Resolved versions for every pkg-export (`pkg: true`) package, captured
+     * at build time (RFC 0001 §5).
+     * Type: Record<package specifier, provide record>
+     */
+    provides: Record<string, ManifestJsonProvide>;
+    /**
+     * Consumption edges transcribed from the module's package.json `esmx.uses`
+     * declaration (RFC 0001 §5). Pre-v2 manifests default to [] at read time.
+     */
+    uses: string[];
     /**
      * Scope-specific import mappings
      * Type: Record<scope name, import mappings within that scope>
@@ -28,6 +56,25 @@ export interface ManifestJson {
      * Type: Record<source file, compilation information>
      */
     chunks: ManifestJsonChunks;
+    /**
+     * Subresource Integrity (SRI) hashes for build output files.
+     * Only generated in production builds to avoid development overhead.
+     * Type: Record<file path, integrity hash>
+     */
+    integrity?: Record<string, string>;
+}
+
+/**
+ * Build-time facts about one provided (pkg-export) package (RFC 0001 §5).
+ */
+export interface ManifestJsonProvide {
+    /**
+     * The RESOLVED installed version of the provided package at build time,
+     * read from node_modules/<pkg>/package.json relative to the module root.
+     * Subpath specifiers (e.g. `vue/jsx-runtime`) resolve via their parent
+     * package. '0.0.0' when the package could not be resolved.
+     */
+    version: string;
 }
 
 /**
@@ -78,6 +125,105 @@ export interface ManifestJsonChunk {
     resources: string[];
 }
 
+/**
+ * The RFC 0001 §5 protocol fields shared by every bundler manifest plugin.
+ */
+export interface ManifestProtocolFields {
+    protocol: number;
+    version: string;
+    provides: Record<string, ManifestJsonProvide>;
+    uses: string[];
+}
+
+function readJsonObjectSync(filePath: string): Record<string, unknown> | null {
+    // Boundary adapter: absence or malformed JSON means "no readable
+    // package.json"; callers fall back to protocol defaults.
+    let json: unknown;
+    try {
+        json = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    } catch {
+        return null;
+    }
+    if (typeof json !== 'object' || json === null || Array.isArray(json)) {
+        return null;
+    }
+    return json as Record<string, unknown>;
+}
+
+/**
+ * Parent package name of a bare specifier: `vue/jsx-runtime` → `vue`,
+ * `@esmx/router` → `@esmx/router`.
+ */
+function parentPackageName(specifier: string): string {
+    const segments = specifier.split('/');
+    return specifier.startsWith('@')
+        ? segments.slice(0, 2).join('/')
+        : segments[0];
+}
+
+/** Walks up from `fromDir` through node_modules, Node-resolution style. */
+function resolveInstalledVersionSync(
+    fromDir: string,
+    packageName: string
+): string | null {
+    let dir = path.resolve(fromDir);
+    for (;;) {
+        const candidate = path.join(dir, 'node_modules', packageName);
+        const pkg = readJsonObjectSync(path.join(candidate, 'package.json'));
+        if (pkg) {
+            return typeof pkg.version === 'string' && pkg.version !== ''
+                ? pkg.version
+                : null;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            return null;
+        }
+        dir = parent;
+    }
+}
+
+/**
+ * Builds the RFC 0001 §5 manifest protocol fields (`protocol`, `version`,
+ * `provides`, `uses`) from the module root's package.json plus the list of
+ * pkg-export package specifiers the bundler plugin computed. Shared by the
+ * @esmx/rspack, @esmx/rsbuild and @esmx/vite manifest plugins so their output
+ * cannot drift.
+ */
+export function buildManifestProtocolFields(
+    moduleRoot: string,
+    provides: string[]
+): ManifestProtocolFields {
+    const pkg = readJsonObjectSync(path.resolve(moduleRoot, 'package.json'));
+    const version =
+        pkg && typeof pkg.version === 'string' && pkg.version !== ''
+            ? pkg.version
+            : '0.0.0';
+    const esmx =
+        pkg && typeof pkg.esmx === 'object' && pkg.esmx !== null
+            ? (pkg.esmx as Record<string, unknown>)
+            : null;
+    const uses = Array.isArray(esmx?.uses)
+        ? esmx.uses.filter((item): item is string => typeof item === 'string')
+        : [];
+    const providesField: Record<string, ManifestJsonProvide> = {};
+    for (const name of provides) {
+        const resolvedVersion = resolveInstalledVersionSync(
+            moduleRoot,
+            parentPackageName(name)
+        );
+        providesField[name] = {
+            version: resolvedVersion ?? '0.0.0'
+        };
+    }
+    return {
+        protocol: MANIFEST_PROTOCOL_VERSION,
+        version,
+        provides: providesField,
+        uses
+    };
+}
+
 /**
  * Get service manifest files
  */
@@ -88,17 +234,32 @@ export async function getManifestList(
     return Promise.all(
         Object.values(moduleConfig.links).map(async (item) => {
             const filename = path.resolve(item[env], 'manifest.json');
+            let data: ManifestJson;
             try {
-                const data: ManifestJson = await JSON.parse(
-                    await fsp.readFile(filename, 'utf-8')
-                );
-                data.name = item.name;
-                return data;
+                data = await JSON.parse(await fsp.readFile(filename, 'utf-8'));
             } catch (e) {
                 throw new Error(
                     `'${item.name}' service '${filename}' file read error on environment '${env}': ${e instanceof Error ? e.message : String(e)}`
                 );
             }
+            data.name = item.name;
+            // Pre-v2 manifests carry none of the protocol fields: treat them
+            // as protocol 1 and default the v2 fields so v2-only checks skip.
+            data.protocol =
+                typeof data.protocol === 'number' ? data.protocol : 1;
+            if (data.protocol > MANIFEST_PROTOCOL_VERSION) {
+                throw new Error(
+                    `[E_PROTOCOL] '${item.name}' service '${filename}' declares manifest protocol ${data.protocol}, but this linker supports up to ${MANIFEST_PROTOCOL_VERSION}. Upgrade esmx, or rebuild '${item.name}' with a matching toolchain.`
+                );
+            }
+            data.version =
+                typeof data.version === 'string' ? data.version : '0.0.0';
+            data.provides =
+                typeof data.provides === 'object' && data.provides !== null
+                    ? data.provides
+                    : {};
+            data.uses = Array.isArray(data.uses) ? data.uses : [];
+            return data;
         })
     );
 }