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

package/src/declaration/reader.ts

@@ -0,0 +1,93 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { validateDeclaration } from './schema';
+
+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;
+}
+
+function readJsonFile(filePath: string): unknown | null {
+    // Boundary adapter: fs/JSON throw; absence or malformed JSON means
+    // "no readable package" for the resolver, which reports E_NOT_LINKED.
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    } catch {
+        return null;
+    }
+}
+
+function toStringRecord(value: unknown): Record<string, string> {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return {};
+    }
+    const result: Record<string, string> = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (typeof entry === 'string') {
+            result[key] = entry;
+        }
+    }
+    return result;
+}
+
+/**
+ * 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 function readPackageRecord(packageDir: string): PackageRecord | null {
+    const json = readJsonFile(path.resolve(packageDir, 'package.json'));
+    if (typeof json !== 'object' || json === null || Array.isArray(json)) {
+        return null;
+    }
+    const pkg = json as Record<string, unknown>;
+    const name = typeof pkg.name === 'string' ? pkg.name : '';
+    const diagnostics: Diagnostic[] = [];
+    let declaration: EsmxDeclaration | null = null;
+    if (pkg.esmx !== undefined) {
+        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
+    };
+}
+
+/**
+ * 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 function readDeclaration(
+    packageDir: string
+): ReadDeclarationResult | null {
+    const record = readPackageRecord(packageDir);
+    if (!record || record.declaration === null) {
+        return null;
+    }
+    return { ...record, declaration: record.declaration };
+}

package/src/declaration/reinit.e2e.test.ts

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { COMMAND, Esmx } from '../core';
+import type { ManifestJson } from '../manifest-json';
+import { MANIFEST_PROTOCOL_VERSION } from '../manifest-json';
+import { createFixtureRoot, removeFixtureRoot } from './test-fixtures';
+
+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));
+});
+
+function writeModule(
+    rootDir: string,
+    dir: string,
+    packageJson: Record<string, unknown>,
+    manifest: Partial<ManifestJson>
+): string {
+    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: ManifestJson = {
+        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'] as const) {
+        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;
+}
+
+/** App mounting `shared`, which exports a module-export `shared/ui`. */
+function buildFixture(root: string, sharedExportFile: string): string {
+    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'] }
+        },
+        {}
+    );
+}
+
+/** Overwrites the shared module's client manifest export file (a new build). */
+function rewriteSharedExport(appDir: string, file: string): void {
+    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 §9)', () => {
+    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');
+
+        // The remote republishes with a new build output; the cached first
+        // generation must NOT see it until a relink.
+        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;
+
+        // Corrupt the app's own package.json so the relink's re-read throws.
+        fs.writeFileSync(path.join(appDir, 'package.json'), '{ not json');
+
+        await expect(esmx.reinit()).rejects.toThrow();
+
+        // The previous generation is intact and still serves.
+        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();
+    });
+});