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

package/src/cli/validate.ts

@@ -0,0 +1,196 @@
+import { styleText } from 'node:util';
+import type { Diagnostic, ResolvedMount, SupplyEntry } from '../declaration';
+import { resolveDeclaration } from '../declaration';
+
+export const VALIDATE_HELP = `Usage: esmx validate [--json]
+
+Build-free dry run of the RFC 0001 module protocol: reads the package.json
+"esmx" declaration in the current directory and runs the resolution layer
+(phases 1-2: consumption graph + supply merge) without building anything.
+
+Exit code is non-zero only when an error-severity diagnostic is found;
+warnings alone exit 0. A package without an "esmx" field uses the legacy
+entry.node.ts config and is not an error.
+
+Options:
+  --json    Emit a machine-readable envelope on stdout and nothing else:
+            {
+              "diagnostics": [ { "code", "check"?, "module", "package"?,
+                                 "found"?, "required"?, "message", "fix" } ],
+              "supply":      { "<package>": { "groups": [ { "major",
+                                              "provider", "version" } ] } },
+              "mounts":      { "<module>":  { "name", "root",
+                                              "artifactDir", "built" } }
+            }
+            Two providers of one (package, major) is an E_DUP_PROVIDER error
+            (a shared dependency must have a single owner).
+            Legacy packages emit { "protocol": "legacy", "diagnostics": [] }.
+  --help    Show this message.`;
+
+export interface RunValidateOptions {
+    json?: boolean;
+}
+
+export interface RunValidateResult {
+    exitCode: number;
+    /** Full stdout payload (JSON envelope or human report). */
+    output: string;
+}
+
+interface ValidateEnvelopeEntry {
+    code: string;
+    check?: string;
+    module: string;
+    package?: string;
+    found?: string;
+    required?: string;
+    message: string;
+    fix: string;
+}
+
+function toEnvelopeEntry(diagnostic: Diagnostic): ValidateEnvelopeEntry {
+    const entry: ValidateEnvelopeEntry = {
+        code: diagnostic.code,
+        module: diagnostic.module,
+        message: diagnostic.message,
+        fix: diagnostic.fix
+    };
+    if (diagnostic.check !== undefined) {
+        entry.check = diagnostic.check;
+    }
+    if (diagnostic.package !== undefined) {
+        entry.package = diagnostic.package;
+    }
+    if (diagnostic.found !== undefined) {
+        entry.found = diagnostic.found;
+    }
+    if (diagnostic.required !== undefined) {
+        entry.required = diagnostic.required;
+    }
+    return entry;
+}
+
+function formatHumanDiagnostic(diagnostic: Diagnostic): string {
+    const color = diagnostic.severity === 'error' ? 'red' : 'yellow';
+    const location = diagnostic.package
+        ? `${diagnostic.module} → ${diagnostic.package}`
+        : diagnostic.module;
+    const lines = [styleText(color, `[${diagnostic.code}]`) + ` ${location}`];
+    if (diagnostic.check) {
+        lines.push(`    check: ${diagnostic.check}`);
+    }
+    if (diagnostic.found !== undefined || diagnostic.required !== undefined) {
+        lines.push(
+            `    found: ${diagnostic.found ?? '—'} / required: ${diagnostic.required ?? '—'}`
+        );
+    }
+    lines.push(`    ${diagnostic.message}`);
+    lines.push(`    fix: ${diagnostic.fix}`);
+    return lines.join('\n');
+}
+
+function formatHumanReport(
+    diagnostics: Diagnostic[],
+    supply: Record<string, SupplyEntry>,
+    mounts: Record<string, ResolvedMount>
+): string {
+    const sections: string[] = [];
+    const errorCount = diagnostics.filter((d) => d.severity === 'error').length;
+    const warningCount = diagnostics.length - errorCount;
+
+    if (diagnostics.length === 0) {
+        sections.push(styleText('green', '✓ Declaration is valid.'));
+    } else {
+        sections.push(diagnostics.map(formatHumanDiagnostic).join('\n'));
+        sections.push(`${errorCount} error(s), ${warningCount} warning(s).`);
+    }
+
+    const supplyEntries = Object.entries(supply);
+    sections.push(
+        supplyEntries.length === 0
+            ? 'Supply: (empty)'
+            : [
+                  'Supply:',
+                  ...supplyEntries.flatMap(([pkg, entry]) =>
+                      entry.groups.map(
+                          (group) =>
+                              `  ${pkg} → ${group.provider}@${group.version ?? 'unresolved'}${
+                                  entry.groups.length > 1
+                                      ? ` (major ${group.major})`
+                                      : ''
+                              }`
+                      )
+                  )
+              ].join('\n')
+    );
+
+    const mountEntries = Object.entries(mounts);
+    sections.push(
+        mountEntries.length === 0
+            ? 'Mounts: (empty)'
+            : [
+                  'Mounts:',
+                  ...mountEntries.map(
+                      ([name, mount]) =>
+                          `  ${name} → ${mount.artifactDir} (${mount.built ? 'built' : 'not built'})`
+                  )
+              ].join('\n')
+    );
+
+    return sections.join('\n\n');
+}
+
+/**
+ * `esmx validate` core (RFC 0001 §10 Phase 5, the agent verification loop).
+ * Pure with respect to process state: never writes to stdout/stderr and
+ * never exits — the CLI case owns printing and the exit code.
+ */
+export async function runValidate(
+    rootDir: string,
+    options: RunValidateOptions = {}
+): Promise<RunValidateResult> {
+    const resolved = resolveDeclaration(rootDir);
+    if (!resolved) {
+        if (options.json) {
+            return {
+                exitCode: 0,
+                output: JSON.stringify(
+                    { protocol: 'legacy', diagnostics: [] },
+                    null,
+                    4
+                )
+            };
+        }
+        return {
+            exitCode: 0,
+            output: [
+                'No "esmx" field in package.json — this module uses the legacy entry.node.ts config.',
+                'That is fine: the new module protocol is opt-in. To adopt it, add an "esmx" field to package.json (see the module protocol docs).'
+            ].join('\n')
+        };
+    }
+
+    const { diagnostics, supply } = resolved;
+    const mounts = resolved.mounts;
+    const hasError = diagnostics.some((d) => d.severity === 'error');
+    const exitCode = hasError ? 1 : 0;
+
+    if (options.json) {
+        return {
+            exitCode,
+            output: JSON.stringify(
+                {
+                    diagnostics: diagnostics.map(toEnvelopeEntry),
+                    supply,
+                    mounts
+                },
+                null,
+                4
+            )
+        };
+    }
+    return {
+        exitCode,
+        output: formatHumanReport(diagnostics, supply, mounts)
+    };
+}

package/src/core.ts

@@ -8,6 +8,7 @@ import type { ImportMap, ScopesMap, SpecifierMap } from '@esmx/import';
 
 import serialize from 'serialize-javascript';
 import { type App, createApp } from './app';
+import { resolveModuleOptions } from './declaration';
 import { getManifestList, type ManifestJson } from './manifest-json';
 import {
     type ModuleConfig,
@@ -396,13 +397,14 @@ export class Esmx {
             throw new Error('Cannot be initialized repeatedly');
         }
 
-        const { name } = await this.readJson(
+        const packageJson = await this.readJson<Record<string, unknown>>(
             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 = {
@@ -472,6 +474,78 @@ 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
+     * ```
+     */
+    public async reinit(): Promise<boolean> {
+        const previous = this.readied;
+
+        const packageJson = await this.readJson<Record<string, unknown>>(
+            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);
+
+        // Install the new generation's config + fresh cache, but keep serving
+        // on the previous app until the new one is built. App-creation reads
+        // `this.readied`, so the rebuilt app captures the new import map.
+        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: App = [COMMAND.dev, COMMAND.build].includes(command)
+                ? await devApp(this)
+                : await createApp(this, command);
+            this.readied.app = app;
+        } catch (error) {
+            // Rollback: restore the previous generation untouched.
+            this._readied = previous;
+            throw error;
+        }
+
+        if (previous.app?.destroy) {
+            await previous.app.destroy();
+        }
+        return true;
+    }
+
     /**
      * Execute the application's build process.
      *
@@ -632,7 +706,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;
         }
     }
@@ -965,17 +1039,20 @@ export class Esmx {
                   src: string;
                   filepath: string;
                   code: string;
+                  integrity: Record<string, string> | null;
               }
             : {
                   src: null;
                   filepath: null;
                   code: string;
+                  integrity: Record<string, string> | null;
               }
     > {
         return this.readied.cache(
             `getImportMap-${mode}`,
             async (): Promise<any> => {
                 const importmap = await this.getImportMap('client');
+                const { integrity } = importmap;
                 const { basePathPlaceholder } = this;
                 let filepath: string | null = null;
                 if (this._importmapHash === null) {
@@ -1023,7 +1100,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) {
@@ -1041,7 +1119,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/src/declaration/index.test.ts

@@ -0,0 +1,223 @@
+import path from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { ModuleConfig } from '../module-config';
+import { resolveDeclaration, resolveModuleOptions } from './index';
+import {
+    createFixtureRoot,
+    removeFixtureRoot,
+    writeFixturePackage
+} from './test-fixtures';
+
+const fixtureRoots: string[] = [];
+
+async function fixtureRoot(): Promise<string> {
+    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: ModuleConfig = {
+            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')
+        );
+    });
+});