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

package/src/declaration/semver.ts

@@ -0,0 +1,278 @@
+/**
+ * Minimal semver-range satisfaction used by the declaration resolver.
+ *
+ * Supports the subset the RFC validation needs: exact versions, `^`, `~`,
+ * comparators (`>=`, `>`, `<=`, `<`, `=`), `*`, x-ranges (`1.x`, `1.2.x`,
+ * `1`, `1.2`), space-separated AND clauses and `||` OR clauses. Anything
+ * else (workspace:, file:, link:, npm aliases, hyphen ranges) is reported
+ * as unparsable so callers can skip the gate per RFC §11.
+ */
+export interface SemverVersion {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease: string[];
+}
+
+const VERSION_RE =
+    /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+
+export function parseSemver(input: string): SemverVersion | null {
+    const match = VERSION_RE.exec(input.trim());
+    if (!match) {
+        return null;
+    }
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        prerelease: match[4] ? match[4].split('.') : []
+    };
+}
+
+function comparePrerelease(a: string[], b: string[]): number {
+    if (a.length === 0 && b.length === 0) {
+        return 0;
+    }
+    // A version without prerelease is greater than the same triple with one.
+    if (a.length === 0) {
+        return 1;
+    }
+    if (b.length === 0) {
+        return -1;
+    }
+    const length = Math.max(a.length, b.length);
+    for (let i = 0; i < length; i++) {
+        const idA = a[i];
+        const idB = b[i];
+        if (idA === undefined) {
+            return -1;
+        }
+        if (idB === undefined) {
+            return 1;
+        }
+        const numA = /^\d+$/.test(idA) ? Number(idA) : null;
+        const numB = /^\d+$/.test(idB) ? Number(idB) : null;
+        if (numA !== null && numB !== null) {
+            if (numA !== numB) {
+                return numA < numB ? -1 : 1;
+            }
+        } else if (numA !== null) {
+            // Numeric identifiers sort before alphanumeric ones.
+            return -1;
+        } else if (numB !== null) {
+            return 1;
+        } else if (idA !== idB) {
+            return idA < idB ? -1 : 1;
+        }
+    }
+    return 0;
+}
+
+export function compareSemver(a: SemverVersion, b: SemverVersion): number {
+    if (a.major !== b.major) {
+        return a.major < b.major ? -1 : 1;
+    }
+    if (a.minor !== b.minor) {
+        return a.minor < b.minor ? -1 : 1;
+    }
+    if (a.patch !== b.patch) {
+        return a.patch < b.patch ? -1 : 1;
+    }
+    return comparePrerelease(a.prerelease, b.prerelease);
+}
+
+interface PartialVersion {
+    major: number | null;
+    minor: number | null;
+    patch: number | null;
+    prerelease: string[];
+}
+
+function parsePartial(input: string): PartialVersion | null {
+    const trimmed = input.trim().replace(/^v/, '');
+    if (trimmed === '' || trimmed === '*' || /^x$/i.test(trimmed)) {
+        return { major: null, minor: null, patch: null, prerelease: [] };
+    }
+    const exact = parseSemver(trimmed);
+    if (exact) {
+        return exact;
+    }
+    const segments = trimmed.split('.');
+    if (segments.length > 3) {
+        return null;
+    }
+    const parsed: Array<number | null> = [];
+    for (const segment of segments) {
+        if (segment === '*' || /^x$/i.test(segment)) {
+            parsed.push(null);
+        } else if (/^\d+$/.test(segment)) {
+            parsed.push(Number(segment));
+        } else {
+            return null;
+        }
+    }
+    return {
+        major: parsed[0] ?? null,
+        minor: parsed[1] ?? null,
+        patch: parsed[2] ?? null,
+        prerelease: []
+    };
+}
+
+function lowerBound(partial: PartialVersion): SemverVersion {
+    return {
+        major: partial.major ?? 0,
+        minor: partial.minor ?? 0,
+        patch: partial.patch ?? 0,
+        prerelease: partial.prerelease
+    };
+}
+
+/** Exclusive upper bound for an x-range, or null when unbounded. */
+function xRangeUpperBound(partial: PartialVersion): SemverVersion | null {
+    if (partial.major === null) {
+        return null;
+    }
+    if (partial.minor === null) {
+        return { major: partial.major + 1, minor: 0, patch: 0, prerelease: [] };
+    }
+    if (partial.patch === null) {
+        return {
+            major: partial.major,
+            minor: partial.minor + 1,
+            patch: 0,
+            prerelease: []
+        };
+    }
+    return null;
+}
+
+function caretUpperBound(partial: PartialVersion): SemverVersion | null {
+    if (partial.major === null) {
+        return null;
+    }
+    if (partial.major > 0) {
+        return { major: partial.major + 1, minor: 0, patch: 0, prerelease: [] };
+    }
+    if (partial.minor === null) {
+        return { major: 1, minor: 0, patch: 0, prerelease: [] };
+    }
+    if (partial.minor > 0) {
+        return { major: 0, minor: partial.minor + 1, patch: 0, prerelease: [] };
+    }
+    if (partial.patch === null) {
+        return { major: 0, minor: partial.minor + 1, patch: 0, prerelease: [] };
+    }
+    return { major: 0, minor: 0, patch: partial.patch + 1, prerelease: [] };
+}
+
+function tildeUpperBound(partial: PartialVersion): SemverVersion | null {
+    if (partial.major === null) {
+        return null;
+    }
+    if (partial.minor === null) {
+        return { major: partial.major + 1, minor: 0, patch: 0, prerelease: [] };
+    }
+    return {
+        major: partial.major,
+        minor: partial.minor + 1,
+        patch: 0,
+        prerelease: []
+    };
+}
+
+function satisfiesComparator(
+    version: SemverVersion,
+    comparator: string
+): boolean | null {
+    const match = /^(\^|~|>=|<=|>|<|=)?\s*(.*)$/.exec(comparator.trim());
+    if (!match) {
+        return null;
+    }
+    const operator = match[1] ?? '';
+    const partial = parsePartial(match[2]);
+    if (!partial) {
+        return null;
+    }
+    const lower = lowerBound(partial);
+    switch (operator) {
+        case '>=':
+            return compareSemver(version, lower) >= 0;
+        case '>':
+            return compareSemver(version, lower) > 0;
+        case '<=':
+            return compareSemver(version, lower) <= 0;
+        case '<':
+            return compareSemver(version, lower) < 0;
+        case '^': {
+            if (compareSemver(version, lower) < 0) {
+                return false;
+            }
+            const upper = caretUpperBound(partial);
+            return upper === null || compareSemver(version, upper) < 0;
+        }
+        case '~': {
+            if (compareSemver(version, lower) < 0) {
+                return false;
+            }
+            const upper = tildeUpperBound(partial);
+            return upper === null || compareSemver(version, upper) < 0;
+        }
+        default: {
+            // '=' or bare version / x-range.
+            if (
+                partial.major !== null &&
+                partial.minor !== null &&
+                partial.patch !== null
+            ) {
+                return compareSemver(version, lower) === 0;
+            }
+            if (compareSemver(version, lower) < 0) {
+                return false;
+            }
+            const upper = xRangeUpperBound(partial);
+            return upper === null || compareSemver(version, upper) < 0;
+        }
+    }
+}
+
+/**
+ * Returns true/false when both version and range are understood,
+ * null when either is unparsable (caller skips the gate, RFC §11).
+ */
+export function satisfiesRange(version: string, range: string): boolean | null {
+    const parsedVersion = parseSemver(version);
+    if (!parsedVersion) {
+        return null;
+    }
+    const trimmed = range.trim();
+    if (trimmed === '' || trimmed === '*' || /^x$/i.test(trimmed)) {
+        return true;
+    }
+    for (const clause of trimmed.split('||')) {
+        const comparators = clause.trim().split(/\s+/).filter(Boolean);
+        if (comparators.length === 0) {
+            return null;
+        }
+        let clauseResult: boolean | null = true;
+        for (const comparator of comparators) {
+            const result = satisfiesComparator(parsedVersion, comparator);
+            if (result === null) {
+                clauseResult = null;
+                break;
+            }
+            if (!result) {
+                clauseResult = false;
+                break;
+            }
+        }
+        if (clauseResult === null) {
+            return null;
+        }
+        if (clauseResult) {
+            return true;
+        }
+    }
+    return false;
+}

package/src/declaration/test-fixtures.ts

@@ -0,0 +1,96 @@
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+/** Test-only helpers building fake package trees in temp directories. */
+export interface FixturePackage {
+    /** Directory relative to the fixture root. */
+    dir: string;
+    packageJson: Record<string, unknown>;
+    /** Write a dist/client/manifest.json stub (marks the module as built). */
+    built?: boolean;
+    /** Manifest content for the stub; implies `built`. */
+    manifest?: Record<string, unknown>;
+    /**
+     * Skip auto-creating the empty source files for declared
+     * `esmx.entry`/`esmx.exports` targets — use to trigger E_TARGET_MISSING.
+     */
+    noSources?: boolean;
+}
+
+/** Relative source paths an `esmx` declaration points at (entry + exports). */
+function declaredTargets(esmx: unknown): string[] {
+    if (typeof esmx !== 'object' || esmx === null) {
+        return [];
+    }
+    const out: string[] = [];
+    const decl = esmx as Record<string, unknown>;
+    const entry = decl.entry;
+    if (typeof entry === 'object' && entry !== null) {
+        for (const side of Object.values(entry as Record<string, unknown>)) {
+            if (typeof side === 'string') {
+                out.push(side);
+            }
+        }
+    }
+    const exports = decl.exports;
+    if (typeof exports === 'object' && exports !== null) {
+        for (const value of Object.values(exports as Record<string, unknown>)) {
+            if (typeof value === 'string') {
+                out.push(value);
+            } else if (typeof value === 'object' && value !== null) {
+                for (const side of Object.values(
+                    value as Record<string, unknown>
+                )) {
+                    if (typeof side === 'string') {
+                        out.push(side);
+                    }
+                }
+            }
+        }
+    }
+    return out;
+}
+
+export async function createFixtureRoot(): Promise<string> {
+    const dir = await fsp.mkdtemp(path.join(os.tmpdir(), 'esmx-declaration-'));
+    // realpath once: macOS tmpdirs are symlinked (/var → /private/var).
+    return fs.realpathSync(dir);
+}
+
+export function writeFixturePackage(
+    rootDir: string,
+    pkg: FixturePackage
+): string {
+    const dir = path.join(rootDir, pkg.dir);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(
+        path.join(dir, 'package.json'),
+        JSON.stringify(pkg.packageJson, null, 4)
+    );
+    if (pkg.built || pkg.manifest) {
+        const clientDir = path.join(dir, 'dist/client');
+        fs.mkdirSync(clientDir, { recursive: true });
+        fs.writeFileSync(
+            path.join(clientDir, 'manifest.json'),
+            JSON.stringify(pkg.manifest ?? {})
+        );
+    }
+    // Auto-create empty source files for every declared entry/exports target
+    // so fixtures satisfy the E_TARGET_MISSING existence check by default.
+    if (!pkg.noSources) {
+        for (const target of declaredTargets(pkg.packageJson.esmx)) {
+            const file = path.resolve(dir, target);
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            if (!fs.existsSync(file)) {
+                fs.writeFileSync(file, '');
+            }
+        }
+    }
+    return dir;
+}
+
+export async function removeFixtureRoot(rootDir: string): Promise<void> {
+    await fsp.rm(rootDir, { recursive: true, force: true });
+}

package/src/declaration/types.ts

@@ -0,0 +1,71 @@
+/**
+ * RFC 0001 declaration layer types.
+ *
+ * The `esmx` field of package.json carries strictly local protocol facts:
+ * a module declares only facts about itself (RFC P2).
+ */
+export interface EsmxDeclarationEntry {
+    client?: string;
+    server?: string;
+}
+
+export interface EsmxDeclarationExportFork {
+    client?: string | false;
+    server?: string | false;
+}
+
+export type EsmxDeclarationExportValue = string | EsmxDeclarationExportFork;
+
+export interface EsmxDeclaration {
+    entry?: EsmxDeclarationEntry;
+    exports?: Record<string, EsmxDeclarationExportValue>;
+    provides?: string[];
+    uses?: string[];
+}
+
+/**
+ * Complete diagnostic taxonomy from RFC 0001 §7, plus E_SCHEMA for
+ * declaration shape violations (the RFC ships a JSON Schema but assigns
+ * no code to schema failures; one code is needed so agents can detect them).
+ */
+export const DiagnosticCode = {
+    E_NOT_LINKED: 'E_NOT_LINKED',
+    E_NOT_BUILT: 'E_NOT_BUILT',
+    E_CYCLE: 'E_CYCLE',
+    E_VERSION: 'E_VERSION',
+    E_DUP_PROVIDER: 'E_DUP_PROVIDER',
+    /** A declared entry/exports target file does not exist on disk. */
+    E_TARGET_MISSING: 'E_TARGET_MISSING',
+    // Build-time (phase 3) codes: emitted by the bundler during its
+    // per-specifier traversal, NOT by the build-free `esmx validate` (which
+    // never lexes source). Reserved here so the bundler emits them with the
+    // same envelope; do not wire emit paths into the resolver.
+    E_NOT_USED: 'E_NOT_USED',
+    E_NO_EXPORT: 'E_NO_EXPORT',
+    E_PROTOCOL: 'E_PROTOCOL',
+    E_PROTOCOL_IN_BEHAVIOR: 'E_PROTOCOL_IN_BEHAVIOR',
+    E_SCHEMA: 'E_SCHEMA',
+    W_MULTI_MAJOR: 'W_MULTI_MAJOR',
+    W_NO_RANGE: 'W_NO_RANGE',
+    W_TYPE_DRIFT: 'W_TYPE_DRIFT'
+} as const;
+
+export type DiagnosticCodeValue =
+    (typeof DiagnosticCode)[keyof typeof DiagnosticCode];
+
+export type DiagnosticSeverity = 'error' | 'warning';
+
+export type DiagnosticCheck = 'intent';
+
+/** Structured diagnostic matching the RFC `esmx validate --json` envelope. */
+export interface Diagnostic {
+    code: string;
+    severity: DiagnosticSeverity;
+    module: string;
+    package?: string;
+    check?: DiagnosticCheck;
+    found?: string;
+    required?: string;
+    message: string;
+    fix: string;
+}

package/src/index.ts

@@ -8,12 +8,39 @@ export {
     type ScopesMap,
     type SpecifierMap
 } from './core';
+export type {
+    Diagnostic,
+    DiagnosticCheck,
+    DiagnosticCodeValue,
+    DiagnosticSeverity,
+    EsmxDeclaration,
+    EsmxDeclarationEntry,
+    EsmxDeclarationExportFork,
+    EsmxDeclarationExportValue,
+    ReadDeclarationResult,
+    ResolveDeclarationOptions,
+    ResolveDeclarationResult,
+    SupplyEntry,
+    SupplyGroup
+} from './declaration';
+export {
+    DiagnosticCode,
+    esmxDeclarationSchema,
+    readDeclaration,
+    resolveDeclaration
+} from './declaration';
 export type {
     ManifestJson,
     ManifestJsonChunk,
     ManifestJsonChunks,
     ManifestJsonExport,
-    ManifestJsonExports
+    ManifestJsonExports,
+    ManifestJsonProvide,
+    ManifestProtocolFields
+} from './manifest-json';
+export {
+    buildManifestProtocolFields,
+    MANIFEST_PROTOCOL_VERSION
 } from './manifest-json';
 export type {
     ModuleConfig,