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

package/src/declaration/schema.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest';
+
+import { esmxDeclarationSchema, validateDeclaration } from './schema';
+import { DiagnosticCode } from './types';
+
+describe('esmxDeclarationSchema', () => {
+    it('should be a draft 2020-12 schema for the esmx field', () => {
+        expect(esmxDeclarationSchema.$schema).toBe(
+            'https://json-schema.org/draft/2020-12/schema'
+        );
+        expect(Object.keys(esmxDeclarationSchema.properties)).toEqual([
+            'entry',
+            'exports',
+            'provides',
+            'uses'
+        ]);
+        expect(esmxDeclarationSchema.additionalProperties).toBe(false);
+    });
+});
+
+describe('validateDeclaration', () => {
+    it('should accept a full valid declaration without diagnostics', () => {
+        const input = {
+            entry: {
+                client: './src/entry.client.ts',
+                server: './src/entry.server.ts'
+            },
+            exports: {
+                './ui': './src/ui/index.ts',
+                './store': {
+                    client: './src/store.client.ts',
+                    server: false
+                }
+            },
+            provides: ['vue', '@esmx/router'],
+            uses: ['shared']
+        };
+
+        const result = validateDeclaration(input, 'cart');
+
+        expect(result.diagnostics).toEqual([]);
+        expect(result.declaration).toEqual(input);
+    });
+
+    it('should reject a non-object esmx field', () => {
+        const result = validateDeclaration('nope', 'cart');
+
+        expect(result.declaration).toBeNull();
+        expect(result.diagnostics).toHaveLength(1);
+        expect(result.diagnostics[0].code).toBe(DiagnosticCode.E_SCHEMA);
+        expect(result.diagnostics[0].severity).toBe('error');
+        expect(result.diagnostics[0].module).toBe('cart');
+    });
+
+    it('should reject export keys without a ./ subpath prefix', () => {
+        const result = validateDeclaration(
+            { exports: { widget: './src/widget.ts' } },
+            'cart'
+        );
+
+        expect(result.diagnostics).toHaveLength(1);
+        expect(result.diagnostics[0].code).toBe(DiagnosticCode.E_SCHEMA);
+        expect(result.diagnostics[0].message).toContain('"widget"');
+        expect(result.declaration?.exports).toEqual({});
+    });
+
+    it('should reject non-relative export file paths', () => {
+        const result = validateDeclaration(
+            { exports: { './widget': 'src/widget.ts' } },
+            'cart'
+        );
+
+        expect(result.diagnostics).toHaveLength(1);
+        expect(result.diagnostics[0].code).toBe(DiagnosticCode.E_SCHEMA);
+        expect(result.diagnostics[0].message).toContain('./');
+    });
+
+    it('should reject wrong types in provides and uses', () => {
+        const result = validateDeclaration(
+            { provides: 'vue', uses: ['shared', '', 42] },
+            'cart'
+        );
+
+        const codes = result.diagnostics.map((d) => d.code);
+        expect(codes).toEqual([
+            DiagnosticCode.E_SCHEMA,
+            DiagnosticCode.E_SCHEMA,
+            DiagnosticCode.E_SCHEMA
+        ]);
+        expect(result.declaration?.provides).toBeUndefined();
+        expect(result.declaration?.uses).toEqual(['shared']);
+    });
+
+    it('should reject non-relative entry paths and unknown keys', () => {
+        const result = validateDeclaration(
+            {
+                entry: { client: 'src/entry.client.ts', node: './x.ts' },
+                bogus: true
+            },
+            'cart'
+        );
+
+        const codes = result.diagnostics.map((d) => d.code);
+        expect(codes).toHaveLength(3);
+        expect(new Set(codes)).toEqual(new Set([DiagnosticCode.E_SCHEMA]));
+    });
+
+    it('should reject invalid env-fork values', () => {
+        const result = validateDeclaration(
+            { exports: { './store': { client: true, server: './s.ts' } } },
+            'cart'
+        );
+
+        expect(result.diagnostics).toHaveLength(1);
+        expect(result.diagnostics[0].code).toBe(DiagnosticCode.E_SCHEMA);
+        expect(result.declaration?.exports).toEqual({});
+    });
+});

package/src/declaration/schema.ts

@@ -0,0 +1,339 @@
+import type {
+    EsmxDeclaration,
+    EsmxDeclarationEntry,
+    EsmxDeclarationExportFork,
+    EsmxDeclarationExportValue
+} from './types';
+import { type Diagnostic, DiagnosticCode } from './types';
+
+/**
+ * JSON Schema (draft 2020-12) for the package.json `esmx` field.
+ * Exported for external tooling and publishing; `validateDeclaration`
+ * enforces the same constraints structurally without a schema-validator
+ * dependency.
+ */
+export const esmxDeclarationSchema = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://esmx.dev/schema/esmx-declaration.json',
+    title: 'Esmx module declaration (package.json "esmx" field)',
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        entry: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                client: { $ref: '#/$defs/relativePath' },
+                server: { $ref: '#/$defs/relativePath' }
+            }
+        },
+        exports: {
+            type: 'object',
+            propertyNames: { pattern: '^\\./.+' },
+            additionalProperties: {
+                anyOf: [
+                    { $ref: '#/$defs/relativePath' },
+                    {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            client: { $ref: '#/$defs/forkValue' },
+                            server: { $ref: '#/$defs/forkValue' }
+                        }
+                    }
+                ]
+            }
+        },
+        provides: {
+            type: 'array',
+            items: { type: 'string', minLength: 1 }
+        },
+        uses: {
+            type: 'array',
+            items: { type: 'string', minLength: 1 }
+        }
+    },
+    $defs: {
+        relativePath: { type: 'string', pattern: '^\\./.+' },
+        forkValue: {
+            anyOf: [{ $ref: '#/$defs/relativePath' }, { const: false }]
+        }
+    }
+} as const;
+
+export interface ValidateDeclarationResult {
+    declaration: EsmxDeclaration | null;
+    diagnostics: Diagnostic[];
+}
+
+function schemaError(
+    moduleName: string,
+    message: string,
+    fix: string
+): Diagnostic {
+    return {
+        code: DiagnosticCode.E_SCHEMA,
+        severity: 'error',
+        module: moduleName,
+        message,
+        fix
+    };
+}
+
+function isRelativePath(value: unknown): value is string {
+    return typeof value === 'string' && /^\.\/.+/.test(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function validateEntry(
+    value: unknown,
+    moduleName: string,
+    diagnostics: Diagnostic[]
+): EsmxDeclarationEntry | undefined {
+    if (!isRecord(value)) {
+        diagnostics.push(
+            schemaError(
+                moduleName,
+                `"esmx.entry" must be an object with optional "client"/"server" keys.`,
+                `Declare entry as { "client": "./src/entry.client.ts", "server": "./src/entry.server.ts" }.`
+            )
+        );
+        return undefined;
+    }
+    const entry: EsmxDeclarationEntry = {};
+    for (const key of Object.keys(value)) {
+        if (key !== 'client' && key !== 'server') {
+            diagnostics.push(
+                schemaError(
+                    moduleName,
+                    `"esmx.entry" has unknown key "${key}".`,
+                    `Only "client" and "server" are allowed in "esmx.entry".`
+                )
+            );
+            continue;
+        }
+        const side = value[key];
+        if (!isRelativePath(side)) {
+            diagnostics.push(
+                schemaError(
+                    moduleName,
+                    `"esmx.entry.${key}" must be a relative "./" path, got ${JSON.stringify(side)}.`,
+                    `Use a relative source path like "./src/entry.${key}.ts".`
+                )
+            );
+            continue;
+        }
+        entry[key] = side;
+    }
+    return entry;
+}
+
+function validateExportFork(
+    key: string,
+    value: Record<string, unknown>,
+    moduleName: string,
+    diagnostics: Diagnostic[]
+): EsmxDeclarationExportFork | null {
+    const fork: EsmxDeclarationExportFork = {};
+    let valid = true;
+    for (const sideKey of Object.keys(value)) {
+        if (sideKey !== 'client' && sideKey !== 'server') {
+            diagnostics.push(
+                schemaError(
+                    moduleName,
+                    `"esmx.exports['${key}']" has unknown key "${sideKey}".`,
+                    `Env-fork export values allow only "client" and "server".`
+                )
+            );
+            valid = false;
+            continue;
+        }
+        const side = value[sideKey];
+        if (side === false || isRelativePath(side)) {
+            fork[sideKey] = side;
+        } else {
+            diagnostics.push(
+                schemaError(
+                    moduleName,
+                    `"esmx.exports['${key}'].${sideKey}" must be a relative "./" path or false, got ${JSON.stringify(side)}.`,
+                    `Point ${sideKey} at a relative source file, or use false to disable that side.`
+                )
+            );
+            valid = false;
+        }
+    }
+    return valid ? fork : null;
+}
+
+function validateExports(
+    value: unknown,
+    moduleName: string,
+    diagnostics: Diagnostic[]
+): Record<string, EsmxDeclarationExportValue> | undefined {
+    if (!isRecord(value)) {
+        diagnostics.push(
+            schemaError(
+                moduleName,
+                `"esmx.exports" must be an object mapping "./<name>" subpaths to source files.`,
+                `Declare exports as { "./widget": "./src/widget.ts" }.`
+            )
+        );
+        return undefined;
+    }
+    const exports: Record<string, EsmxDeclarationExportValue> = {};
+    for (const [key, exportValue] of Object.entries(value)) {
+        if (!/^\.\/.+/.test(key)) {
+            diagnostics.push(
+                schemaError(
+                    moduleName,
+                    `"esmx.exports" key "${key}" must be a "./<name>" subpath.`,
+                    `Rename the key to "./${key.replace(/^\.?\/?/, '')}".`
+                )
+            );
+            continue;
+        }
+        if (isRelativePath(exportValue)) {
+            exports[key] = exportValue;
+            continue;
+        }
+        if (isRecord(exportValue)) {
+            const fork = validateExportFork(
+                key,
+                exportValue,
+                moduleName,
+                diagnostics
+            );
+            if (fork) {
+                exports[key] = fork;
+            }
+            continue;
+        }
+        diagnostics.push(
+            schemaError(
+                moduleName,
+                `"esmx.exports['${key}']" must be a relative "./" path or a { client, server } fork, got ${JSON.stringify(exportValue)}.`,
+                `Point the export at a relative source file like "./src/widget.ts".`
+            )
+        );
+    }
+    return exports;
+}
+
+function validateNameArray(
+    field: 'provides' | 'uses',
+    value: unknown,
+    moduleName: string,
+    diagnostics: Diagnostic[]
+): string[] | undefined {
+    if (!Array.isArray(value)) {
+        diagnostics.push(
+            schemaError(
+                moduleName,
+                `"esmx.${field}" must be an array of non-empty strings.`,
+                `Declare ${field} as a string array, e.g. ["vue"].`
+            )
+        );
+        return undefined;
+    }
+    const names: string[] = [];
+    for (const item of value) {
+        if (typeof item !== 'string' || item.length === 0) {
+            diagnostics.push(
+                schemaError(
+                    moduleName,
+                    `"esmx.${field}" entries must be non-empty strings, got ${JSON.stringify(item)}.`,
+                    `Remove or replace the invalid ${field} entry.`
+                )
+            );
+            continue;
+        }
+        names.push(item);
+    }
+    return names;
+}
+
+/**
+ * Structural validator enforcing `esmxDeclarationSchema`. Invalid pieces
+ * are dropped and reported; the returned declaration keeps the valid rest
+ * so downstream diagnostics stay meaningful. Returns a null declaration
+ * only when the field itself is not an object.
+ */
+export function validateDeclaration(
+    value: unknown,
+    moduleName: string
+): ValidateDeclarationResult {
+    const diagnostics: Diagnostic[] = [];
+    if (!isRecord(value)) {
+        diagnostics.push(
+            schemaError(
+                moduleName,
+                `"esmx" field must be an object, got ${JSON.stringify(value)}.`,
+                `Declare protocol facts as an object: { "entry": ..., "exports": ..., "provides": ..., "uses": ... }.`
+            )
+        );
+        return { declaration: null, diagnostics };
+    }
+    const declaration: EsmxDeclaration = {};
+    for (const key of Object.keys(value)) {
+        switch (key) {
+            case 'entry': {
+                const entry = validateEntry(
+                    value.entry,
+                    moduleName,
+                    diagnostics
+                );
+                if (entry) {
+                    declaration.entry = entry;
+                }
+                break;
+            }
+            case 'exports': {
+                const exports = validateExports(
+                    value.exports,
+                    moduleName,
+                    diagnostics
+                );
+                if (exports) {
+                    declaration.exports = exports;
+                }
+                break;
+            }
+            case 'provides': {
+                const provides = validateNameArray(
+                    'provides',
+                    value.provides,
+                    moduleName,
+                    diagnostics
+                );
+                if (provides) {
+                    declaration.provides = provides;
+                }
+                break;
+            }
+            case 'uses': {
+                const uses = validateNameArray(
+                    'uses',
+                    value.uses,
+                    moduleName,
+                    diagnostics
+                );
+                if (uses) {
+                    declaration.uses = uses;
+                }
+                break;
+            }
+            default:
+                diagnostics.push(
+                    schemaError(
+                        moduleName,
+                        `"esmx" has unknown key "${key}".`,
+                        `Allowed keys are "entry", "exports", "provides", "uses".`
+                    )
+                );
+        }
+    }
+    return { declaration, diagnostics };
+}

package/src/declaration/semver.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest';
+
+import { compareSemver, parseSemver, satisfiesRange } from './semver';
+
+describe('parseSemver', () => {
+    it('should parse a plain version', () => {
+        const result = parseSemver('3.4.21');
+
+        expect(result).toEqual({
+            major: 3,
+            minor: 4,
+            patch: 21,
+            prerelease: []
+        });
+    });
+
+    it('should parse a prerelease version with build metadata', () => {
+        const result = parseSemver('1.2.3-beta.1+build.5');
+
+        expect(result).toEqual({
+            major: 1,
+            minor: 2,
+            patch: 3,
+            prerelease: ['beta', '1']
+        });
+    });
+
+    it('should return null for non-version input', () => {
+        expect(parseSemver('workspace:*')).toBeNull();
+        expect(parseSemver('not-a-version')).toBeNull();
+        expect(parseSemver('1.2')).toBeNull();
+    });
+});
+
+describe('compareSemver', () => {
+    it('should order versions by triple then prerelease', () => {
+        const v340 = parseSemver('3.4.0');
+        const v352 = parseSemver('3.5.2');
+        const v352beta = parseSemver('3.5.2-beta.1');
+        if (!v340 || !v352 || !v352beta) {
+            throw new Error('fixture versions must parse');
+        }
+
+        expect(compareSemver(v340, v352)).toBe(-1);
+        expect(compareSemver(v352, v340)).toBe(1);
+        expect(compareSemver(v352, v352)).toBe(0);
+        expect(compareSemver(v352beta, v352)).toBe(-1);
+    });
+});
+
+describe('satisfiesRange', () => {
+    it('should handle caret ranges', () => {
+        expect(satisfiesRange('3.5.2', '^3.4.0')).toBe(true);
+        expect(satisfiesRange('4.0.0', '^3.4.0')).toBe(false);
+        expect(satisfiesRange('3.3.9', '^3.4.0')).toBe(false);
+        expect(satisfiesRange('0.2.5', '^0.2.3')).toBe(true);
+        expect(satisfiesRange('0.3.0', '^0.2.3')).toBe(false);
+        expect(satisfiesRange('0.0.3', '^0.0.3')).toBe(true);
+        expect(satisfiesRange('0.0.4', '^0.0.3')).toBe(false);
+    });
+
+    it('should handle tilde ranges', () => {
+        expect(satisfiesRange('1.2.9', '~1.2.3')).toBe(true);
+        expect(satisfiesRange('1.3.0', '~1.2.3')).toBe(false);
+        expect(satisfiesRange('1.5.0', '~1')).toBe(true);
+        expect(satisfiesRange('2.0.0', '~1')).toBe(false);
+    });
+
+    it('should handle comparator ranges', () => {
+        expect(satisfiesRange('3.4.0', '>=3.4.0')).toBe(true);
+        expect(satisfiesRange('3.3.9', '>=3.4.0')).toBe(false);
+        expect(satisfiesRange('3.4.0', '>3.4.0')).toBe(false);
+        expect(satisfiesRange('3.4.0', '<=3.4.0')).toBe(true);
+        expect(satisfiesRange('3.4.0', '<3.4.0')).toBe(false);
+        expect(satisfiesRange('3.4.0', '=3.4.0')).toBe(true);
+    });
+
+    it('should handle exact versions, star and x-ranges', () => {
+        expect(satisfiesRange('3.4.21', '3.4.21')).toBe(true);
+        expect(satisfiesRange('3.4.22', '3.4.21')).toBe(false);
+        expect(satisfiesRange('9.9.9', '*')).toBe(true);
+        expect(satisfiesRange('1.7.0', '1.x')).toBe(true);
+        expect(satisfiesRange('2.0.0', '1.x')).toBe(false);
+        expect(satisfiesRange('1.2.9', '1.2.x')).toBe(true);
+        expect(satisfiesRange('1.3.0', '1.2.x')).toBe(false);
+        expect(satisfiesRange('1.5.0', '1')).toBe(true);
+    });
+
+    it('should handle compound AND and OR clauses', () => {
+        expect(satisfiesRange('1.5.0', '>=1.2.0 <2.0.0')).toBe(true);
+        expect(satisfiesRange('2.1.0', '>=1.2.0 <2.0.0')).toBe(false);
+        expect(satisfiesRange('2.1.0', '^1.0.0 || ^2.0.0')).toBe(true);
+        expect(satisfiesRange('3.0.0', '^1.0.0 || ^2.0.0')).toBe(false);
+    });
+
+    it('should return null for unparsable ranges or versions', () => {
+        expect(satisfiesRange('1.0.0', 'workspace:*')).toBeNull();
+        expect(satisfiesRange('1.0.0', 'npm:vue@^3.0.0')).toBeNull();
+        expect(satisfiesRange('not-a-version', '^1.0.0')).toBeNull();
+    });
+});