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

package/dist/declaration/schema.d.ts

@@ -0,0 +1,89 @@
+import type { EsmxDeclaration } from './types';
+import { type Diagnostic } 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 declare const esmxDeclarationSchema: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://esmx.dev/schema/esmx-declaration.json";
+    readonly title: "Esmx module declaration (package.json \"esmx\" field)";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly entry: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly client: {
+                    readonly $ref: "#/$defs/relativePath";
+                };
+                readonly server: {
+                    readonly $ref: "#/$defs/relativePath";
+                };
+            };
+        };
+        readonly exports: {
+            readonly type: "object";
+            readonly propertyNames: {
+                readonly pattern: "^\\./.+";
+            };
+            readonly additionalProperties: {
+                readonly anyOf: readonly [{
+                    readonly $ref: "#/$defs/relativePath";
+                }, {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly client: {
+                            readonly $ref: "#/$defs/forkValue";
+                        };
+                        readonly server: {
+                            readonly $ref: "#/$defs/forkValue";
+                        };
+                    };
+                }];
+            };
+        };
+        readonly provides: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+        };
+        readonly uses: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+        };
+    };
+    readonly $defs: {
+        readonly relativePath: {
+            readonly type: "string";
+            readonly pattern: "^\\./.+";
+        };
+        readonly forkValue: {
+            readonly anyOf: readonly [{
+                readonly $ref: "#/$defs/relativePath";
+            }, {
+                readonly const: false;
+            }];
+        };
+    };
+};
+export interface ValidateDeclarationResult {
+    declaration: EsmxDeclaration | null;
+    diagnostics: Diagnostic[];
+}
+/**
+ * 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 declare function validateDeclaration(value: unknown, moduleName: string): ValidateDeclarationResult;

package/dist/declaration/schema.mjs

@@ -0,0 +1,282 @@
+import { DiagnosticCode } from "./types.mjs";
+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 }]
+    }
+  }
+};
+function schemaError(moduleName, message, fix) {
+  return {
+    code: DiagnosticCode.E_SCHEMA,
+    severity: "error",
+    module: moduleName,
+    message,
+    fix
+  };
+}
+function isRelativePath(value) {
+  return typeof value === "string" && /^\.\/.+/.test(value);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateEntry(value, moduleName, diagnostics) {
+  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 void 0;
+  }
+  const entry = {};
+  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, value, moduleName, diagnostics) {
+  const fork = {};
+  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, moduleName, diagnostics) {
+  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 void 0;
+  }
+  const exports = {};
+  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, value, moduleName, diagnostics) {
+  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 void 0;
+  }
+  const names = [];
+  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;
+}
+export function validateDeclaration(value, moduleName) {
+  const diagnostics = [];
+  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 = {};
+  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/dist/declaration/schema.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/declaration/schema.test.mjs

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "vitest";
+import { esmxDeclarationSchema, validateDeclaration } from "./schema.mjs";
+import { DiagnosticCode } from "./types.mjs";
+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(/* @__PURE__ */ 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/dist/declaration/semver.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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[];
+}
+export declare function parseSemver(input: string): SemverVersion | null;
+export declare function compareSemver(a: SemverVersion, b: SemverVersion): number;
+/**
+ * Returns true/false when both version and range are understood,
+ * null when either is unparsable (caller skips the gate, RFC §11).
+ */
+export declare function satisfiesRange(version: string, range: string): boolean | null;