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

package/src/declaration/index.ts

@@ -0,0 +1,135 @@
+import type { ModuleConfig } from '../module-config';
+import { lowerDeclaration } from './lower';
+import { readDeclaration } from './reader';
+import type { ResolvedMount, ResolverEnvLinks, SupplyEntry } from './resolver';
+import { resolveMounts } 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 function resolveDeclaration(
+    rootDir: string,
+    options: ResolveDeclarationOptions = {}
+): ResolveDeclarationResult | null {
+    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'] as const;
+
+function formatDiagnostic(diagnostic: Diagnostic): string {
+    const location = diagnostic.package
+        ? `${diagnostic.module} → ${diagnostic.package}`
+        : diagnostic.module;
+    return `[${diagnostic.code}] (${location}) ${diagnostic.message} Fix: ${diagnostic.fix}`;
+}
+
+/**
+ * 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 function resolveModuleOptions(
+    rootDir: string,
+    packageJson: Record<string, unknown>,
+    modules?: ModuleConfig
+): ModuleConfig | undefined {
+    if (packageJson.esmx === undefined) {
+        return modules;
+    }
+    if (modules) {
+        const protocolKeys = PROTOCOL_MODULE_KEYS.filter(
+            (key) => modules[key] !== undefined
+        );
+        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):\n` +
+                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/src/declaration/lower.test.ts

@@ -0,0 +1,372 @@
+import path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import type { ModuleConfig } from '../module-config';
+import { parseModuleConfig } from '../module-config';
+import { lowerDeclaration } from './lower';
+import type { ReadDeclarationResult } from './reader';
+import { readDeclaration } from './reader';
+import { resolveMounts } from './resolver';
+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 () => {
+    await Promise.all(fixtureRoots.splice(0).map(removeFixtureRoot));
+});
+
+function readRootDeclaration(appDir: string): ReadDeclarationResult {
+    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: ModuleConfig = {
+            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(): Promise<string> {
+            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: string) {
+            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);
+
+            // Self-provided package: never imported from another module.
+            expect(lowered.imports?.vue).toBeUndefined();
+            expect(
+                resolution.diagnostics.filter((d) => d.severity === 'error')
+            ).toEqual([]);
+        });
+    });
+});

package/src/declaration/lower.ts

@@ -0,0 +1,135 @@
+import type {
+    ModuleConfig,
+    ModuleConfigEntry,
+    ModuleConfigExportExports,
+    ModuleConfigExportObject,
+    ModuleConfigExportObjectValue
+} from '../module-config';
+import type { ReadDeclarationResult } from './reader';
+import type { ResolveMountsResult } from './resolver';
+import { selectSupplyGroup } from './resolver';
+import type { EsmxDeclarationExportValue } from './types';
+
+const DEFAULT_CLIENT_ENTRY = './src/entry.client.ts';
+const DEFAULT_SERVER_ENTRY = './src/entry.server.ts';
+
+/** './src/foo.ts' → 'root:src/foo.ts' */
+function toRootExport(relativePath: string): string {
+    return `root:${relativePath.slice(2)}`;
+}
+
+function lowerExportValue(
+    value: EsmxDeclarationExportValue
+): ModuleConfigExportObjectValue {
+    if (typeof value === 'string') {
+        return toRootExport(value);
+    }
+    // An absent fork side means the side is disabled, same as false.
+    return {
+        client:
+            typeof value.client === 'string'
+                ? toRootExport(value.client)
+                : false,
+        server:
+            typeof value.server === 'string'
+                ? toRootExport(value.server)
+                : false
+    };
+}
+
+/**
+ * Lowers a declared entry to the `ModuleConfig.entry` IR: an absent side
+ * is disabled (`false`), the default path is omitted (rides on the legacy
+ * default, keeping migration parity byte-identical), and a custom path
+ * passes through (its export name is path-derived by `parseEntryConfig`,
+ * RFC 0001 §4.1: no reserved names).
+ */
+function lowerEntry(
+    entry: NonNullable<ReadDeclarationResult['declaration']['entry']>
+): ModuleConfigEntry | null {
+    const lowered: ModuleConfigEntry = {};
+    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;
+}
+
+/**
+ * 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 function lowerDeclaration(
+    pkg: ReadDeclarationResult,
+    resolution: ResolveMountsResult
+): ModuleConfig {
+    const { declaration } = pkg;
+    const config: ModuleConfig = {};
+
+    if (!declaration.entry) {
+        config.lib = true;
+    } else {
+        const entry = lowerEntry(declaration.entry);
+        if (entry) {
+            config.entry = entry;
+        }
+    }
+
+    const links: Record<string, string> = {};
+    for (const mount of Object.values(resolution.mounts)) {
+        links[mount.name] = mount.artifactDir;
+    }
+    if (Object.keys(links).length > 0) {
+        config.links = links;
+    }
+
+    // The static supply table: every merged entry is wired, whether or not
+    // the consumer ever imports it — the externalization predicates treat
+    // it as a pure membership test, so extra entries are harmless. With
+    // per-major groups each module picks its own group locally: a module
+    // that provides the package itself wires to its own copy (self wins
+    // its group in its own merge); otherwise the dependencies ∪
+    // peerDependencies range selects the satisfying major group.
+    const imports: Record<string, string> = {};
+    for (const [packageName, entry] of Object.entries(resolution.supply)) {
+        if (entry.groups.some((group) => group.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: ModuleConfigExportExports = [];
+    for (const provided of declaration.provides ?? []) {
+        exports.push(`pkg:${provided}`);
+    }
+    const exportObject: ModuleConfigExportObject = {};
+    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;
+}