@lunatest/core 0.1.0 → 0.1.1

package/dist/browser.d.ts

@@ -0,0 +1,6 @@
+export declare const sdkName = "@lunatest/core/browser";
+export { loadLunaConfig } from "./config/lua-config.js";
+export { createPresetRegistry, getProtocolPreset, getPresetDiagnostics, getWalletPreset, listProtocolPresets, listWalletPresets, validateProtocolPresetSource, validateWalletPresetSource, materializeProtocolPreset, materializeWalletPreset, } from "./presets/registry.js";
+export type { PresetRegistry, PresetRegistryOptions, ProjectPresetSources } from "./presets/registry.js";
+export { applyInterceptState, createScenarioRuntime, LuaConfigSchema, setRouteMocks, type LuaConfig, type RouteMock, type ScenarioRuntime, } from "./runtime/scenario-runtime.js";
+export { executeLuaScenario, type ExecuteLuaScenarioInput, type ExecuteLuaScenarioResult, } from "./runner/execute-scenario.js";

package/dist/browser.js

@@ -0,0 +1,5 @@
+export const sdkName = "@lunatest/core/browser";
+export { loadLunaConfig } from "./config/lua-config.js";
+export { createPresetRegistry, getProtocolPreset, getPresetDiagnostics, getWalletPreset, listProtocolPresets, listWalletPresets, validateProtocolPresetSource, validateWalletPresetSource, materializeProtocolPreset, materializeWalletPreset, } from "./presets/registry.js";
+export { applyInterceptState, createScenarioRuntime, LuaConfigSchema, setRouteMocks, } from "./runtime/scenario-runtime.js";
+export { executeLuaScenario, } from "./runner/execute-scenario.js";

package/dist/config/lua-config.js

@@ -1,50 +1,9 @@
 import { createRuntime } from "../runtime/engine.js";
 import { LuaConfigSchema } from "../runtime/scenario-runtime.js";
 import { isRecord } from "@lunatest/contracts";
-function seemsInlineLua(input) {
-    return input.includes("\n") || input.includes("scenario {") || input.includes("scenario{");
-}
-async function readSource(source) {
-    if (source instanceof URL) {
-        if (source.protocol === "http:" || source.protocol === "https:") {
-            if (typeof fetch !== "function") {
-                throw new Error(`Fetch API is unavailable for URL source: ${source.toString()}`);
-            }
-            const response = await fetch(source);
-            if (!response.ok) {
-                throw new Error(`Failed to load Lua config: ${source.toString()} (${response.status})`);
-            }
-            return response.text();
-        }
-        if (source.protocol !== "file:") {
-            throw new Error(`Unsupported Lua config URL protocol: ${source.protocol}`);
-        }
-        const [{ fileURLToPath }, { readFile }] = await Promise.all([
-            import("node:url"),
-            import("node:fs/promises"),
-        ]);
-        return readFile(fileURLToPath(source), "utf8");
-    }
-    if (seemsInlineLua(source)) {
-        return source;
-    }
-    if (typeof document !== "undefined" && typeof fetch === "function") {
-        const response = await fetch(source);
-        if (!response.ok) {
-            throw new Error(`Failed to load Lua config: ${source} (${response.status})`);
-        }
-        return response.text();
-    }
-    try {
-        const { readFile } = await import("node:fs/promises");
-        return await readFile(source, "utf8");
-    }
-    catch {
-        return source;
-    }
-}
+import { readLuaSource } from "./read-source.js";
 export async function loadLunaConfig(source) {
-    const code = await readSource(source);
+    const code = await readLuaSource(source);
     const runtime = await createRuntime();
     let captured;
     runtime.register("scenario", (table) => {

package/dist/config/read-source.d.ts

@@ -0,0 +1,3 @@
+type LuaSource = string | URL;
+export declare function readLuaSource(source: LuaSource): Promise<string>;
+export {};

package/dist/config/read-source.js

@@ -0,0 +1,56 @@
+function seemsInlineLua(input) {
+    return input.includes("\n") || input.includes("scenario {") || input.includes("scenario{");
+}
+function canUseBrowserFetch() {
+    return typeof document !== "undefined" && typeof fetch === "function";
+}
+function getBuiltinModule(specifier) {
+    if (typeof process === "undefined" ||
+        typeof process.getBuiltinModule !== "function") {
+        return null;
+    }
+    return process.getBuiltinModule(specifier);
+}
+export async function readLuaSource(source) {
+    if (source instanceof URL) {
+        if (source.protocol === "http:" || source.protocol === "https:") {
+            if (typeof fetch !== "function") {
+                throw new Error(`Fetch API is unavailable for URL source: ${source.toString()}`);
+            }
+            const response = await fetch(source);
+            if (!response.ok) {
+                throw new Error(`Failed to load Lua source: ${source.toString()} (${response.status})`);
+            }
+            return response.text();
+        }
+        if (source.protocol !== "file:") {
+            throw new Error(`Unsupported Lua source URL protocol: ${source.protocol}`);
+        }
+        const urlModule = getBuiltinModule("url");
+        const fsModule = getBuiltinModule("fs/promises");
+        if (!urlModule || !fsModule) {
+            throw new Error(`File URL source is unavailable in this runtime: ${source.toString()}`);
+        }
+        return fsModule.readFile(urlModule.fileURLToPath(source), "utf8");
+    }
+    if (seemsInlineLua(source)) {
+        return source;
+    }
+    if (canUseBrowserFetch()) {
+        const response = await fetch(source);
+        if (!response.ok) {
+            throw new Error(`Failed to load Lua source: ${source} (${response.status})`);
+        }
+        return response.text();
+    }
+    const fsModule = getBuiltinModule("fs/promises");
+    if (fsModule) {
+        try {
+            return await fsModule.readFile(source, "utf8");
+        }
+        catch {
+            return source;
+        }
+    }
+    return source;
+}

package/dist/coverage/catalog.d.ts

@@ -0,0 +1,14 @@
+import type { CoverageCatalog, CoverageMetadata, CoverageSnapshot } from "@lunatest/contracts";
+type CoverageCarrier = {
+    when?: Record<string, unknown>;
+    then_ui?: Record<string, unknown>;
+    then_state?: Record<string, unknown>;
+    not_present?: string[];
+    coverage?: CoverageMetadata;
+};
+export declare function resolveCoverageMetadata(input: CoverageCarrier): CoverageCatalog;
+export declare function buildCoverageSnapshot(input: {
+    items: CoverageCarrier[];
+    coverageCatalog?: Partial<CoverageCatalog>;
+}): CoverageSnapshot;
+export {};

package/dist/coverage/catalog.js

@@ -0,0 +1,91 @@
+function normalizeList(values) {
+    if (!values) {
+        return [];
+    }
+    return Array.from(new Set(values
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0))).sort();
+}
+function emptyCatalog() {
+    return {
+        features: [],
+        states: [],
+        components: [],
+    };
+}
+function topLevelKeys(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return [];
+    }
+    return Object.keys(value);
+}
+function inferCoverageMetadata(input) {
+    const inferredStates = new Set([
+        ...topLevelKeys(input.then_ui),
+        ...topLevelKeys(input.then_state),
+        ...(input.not_present ?? []),
+    ]);
+    return {
+        features: input.when && typeof input.when.action === "string"
+            ? [input.when.action]
+            : [],
+        states: Array.from(inferredStates).sort(),
+        components: topLevelKeys(input.then_ui).sort(),
+    };
+}
+export function resolveCoverageMetadata(input) {
+    const inferred = inferCoverageMetadata(input);
+    const declared = input.coverage ?? {};
+    return {
+        features: declared.features !== undefined
+            ? normalizeList(declared.features)
+            : inferred.features,
+        states: declared.states !== undefined
+            ? normalizeList(declared.states)
+            : inferred.states,
+        components: declared.components !== undefined
+            ? normalizeList(declared.components)
+            : inferred.components,
+    };
+}
+function mergeCatalogs(base, next) {
+    return {
+        features: normalizeList([...base.features, ...next.features]),
+        states: normalizeList([...base.states, ...next.states]),
+        components: normalizeList([...base.components, ...next.components]),
+    };
+}
+function subtractCatalog(known, coveredTargets) {
+    const coveredFeatures = new Set(coveredTargets.features);
+    const coveredStates = new Set(coveredTargets.states);
+    const coveredComponents = new Set(coveredTargets.components);
+    return {
+        features: known.features.filter((feature) => !coveredFeatures.has(feature)),
+        states: known.states.filter((state) => !coveredStates.has(state)),
+        components: known.components.filter((component) => !coveredComponents.has(component)),
+    };
+}
+export function buildCoverageSnapshot(input) {
+    const knownFromCatalog = {
+        features: normalizeList(input.coverageCatalog?.features),
+        states: normalizeList(input.coverageCatalog?.states),
+        components: normalizeList(input.coverageCatalog?.components),
+    };
+    const coveredTargets = input.items.reduce((acc, item) => {
+        return mergeCatalogs(acc, resolveCoverageMetadata(item));
+    }, emptyCatalog());
+    const known = mergeCatalogs(knownFromCatalog, coveredTargets);
+    const missing = subtractCatalog(known, coveredTargets);
+    const total = known.features.length + known.states.length + known.components.length;
+    const covered = coveredTargets.features.length +
+        coveredTargets.states.length +
+        coveredTargets.components.length;
+    return {
+        total,
+        covered,
+        ratio: total === 0 ? 1 : Number((covered / total).toFixed(4)),
+        known,
+        coveredTargets,
+        missing,
+    };
+}

package/dist/index.d.ts

@@ -2,5 +2,9 @@ export declare const sdkName = "@lunatest/core";
 export { LunaProvider } from "./provider/luna-provider.js";
 export type { LunaProviderOptions } from "./provider/luna-provider.js";
 export { loadLunaConfig } from "./config/lua-config.js";
+export { buildCoverageSnapshot, resolveCoverageMetadata, } from "./coverage/catalog.js";
+export { createPresetRegistry, getProtocolPreset, getPresetDiagnostics, getWalletPreset, listProtocolPresets, listWalletPresets, validateProtocolPresetSource, validateWalletPresetSource, materializeProtocolPreset, materializeWalletPreset, } from "./presets/registry.js";
+export type { PresetRegistry, PresetRegistryOptions, ProjectPresetSources } from "./presets/registry.js";
+export { loadProjectPresetSources } from "./presets/project-sources.node.js";
 export { applyInterceptState, createScenarioRuntime, LuaConfigSchema, setRouteMocks, type LuaConfig, type RouteMock, type ScenarioRuntime, } from "./runtime/scenario-runtime.js";
 export { executeLuaScenario, type ExecuteLuaScenarioInput, type ExecuteLuaScenarioResult, } from "./runner/execute-scenario.js";

package/dist/index.js

@@ -1,5 +1,8 @@
 export const sdkName = "@lunatest/core";
 export { LunaProvider } from "./provider/luna-provider.js";
 export { loadLunaConfig } from "./config/lua-config.js";
+export { buildCoverageSnapshot, resolveCoverageMetadata, } from "./coverage/catalog.js";
+export { createPresetRegistry, getProtocolPreset, getPresetDiagnostics, getWalletPreset, listProtocolPresets, listWalletPresets, validateProtocolPresetSource, validateWalletPresetSource, materializeProtocolPreset, materializeWalletPreset, } from "./presets/registry.js";
+export { loadProjectPresetSources } from "./presets/project-sources.node.js";
 export { applyInterceptState, createScenarioRuntime, LuaConfigSchema, setRouteMocks, } from "./runtime/scenario-runtime.js";
 export { executeLuaScenario, } from "./runner/execute-scenario.js";

package/dist/mocks/provider.js

@@ -1,3 +1,4 @@
+import { normalizeAddress } from "@lunatest/contracts";
 function parseTokenAmountToWeiHex(value) {
     const [integerPartRaw, fractionalPartRaw = ""] = value.split(".");
     const integerPart = integerPartRaw === "" ? "0" : integerPartRaw;
@@ -6,9 +7,6 @@ function parseTokenAmountToWeiHex(value) {
     const fractionalWei = BigInt(fractionalPart || "0");
     return `0x${(integerWei + fractionalWei).toString(16)}`;
 }
-function normalizeAddress(value) {
-    return value.toLowerCase();
-}
 function cloneState(state) {
     return {
         timeMs: state.timeMs,

package/dist/presets/__tests__/registry.test.ts

@@ -0,0 +1,213 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  createPresetRegistry,
+  getPresetDiagnostics,
+  getProtocolPreset,
+  getWalletPreset,
+  listProtocolPresets,
+  listWalletPresets,
+  materializeProtocolPreset,
+  materializeWalletPreset,
+} from "../registry";
+import { loadProjectPresetSources } from "../project-sources.node";
+import { writeFile, mkdir } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+describe("preset registry", () => {
+  it("lists built-in protocol and wallet presets", async () => {
+    const [protocols, wallets] = await Promise.all([
+      listProtocolPresets(),
+      listWalletPresets(),
+    ]);
+
+    expect(protocols.map((item) => item.qualifiedId)).toEqual(
+      expect.arrayContaining([
+        "builtin/uniswap_v2",
+        "builtin/uniswap_v3",
+        "builtin/curve",
+        "builtin/aave",
+      ]),
+    );
+    expect(wallets.map((item) => item.qualifiedId)).toEqual(
+      expect.arrayContaining(["builtin/empty_wallet", "builtin/demo_sepolia"]),
+    );
+  });
+
+  it("loads protocol and wallet preset metadata by id", async () => {
+    await expect(getProtocolPreset("uniswap_v3")).resolves.toMatchObject({
+      id: "uniswap_v3",
+      qualifiedId: "builtin/uniswap_v3",
+      components: {
+        quoter: "v2",
+      },
+    });
+
+    await expect(getWalletPreset("demo_sepolia")).resolves.toMatchObject({
+      id: "demo_sepolia",
+      qualifiedId: "builtin/demo_sepolia",
+      kind: "wallet",
+    });
+  });
+
+  it("materializes wallet preset deterministically", async () => {
+    const first = await materializeWalletPreset("demo_sepolia", {
+      address: "0x1111111111111111111111111111111111111111",
+      chainId: 11155111,
+    });
+    const second = await materializeWalletPreset("demo_sepolia", {
+      address: "0x1111111111111111111111111111111111111111",
+      chainId: 11155111,
+    });
+
+    expect(first).toEqual(second);
+  });
+
+  it("materializes uniswap v3 with component override", async () => {
+    const v1 = await materializeProtocolPreset("uniswap_v3", {
+      chainId: 11155111,
+      quoter: "v1",
+    });
+    const v2 = await materializeProtocolPreset("uniswap_v3", {
+      chainId: 11155111,
+      quoter: "v2",
+    });
+
+    expect(v1.interceptState).not.toEqual(v2.interceptState);
+    expect(v1.walletPresetId).toBe("builtin/demo_sepolia");
+  });
+
+  it("rejects unsupported protocol chain", async () => {
+    await expect(
+      materializeProtocolPreset("curve", {
+        chainId: 11155111,
+      }),
+    ).rejects.toThrow(/does not support chain/);
+  });
+
+  it("discovers project-local preset sources with namespace separation", async () => {
+    const tempRoot = await fsMkdtemp();
+    await mkdir(path.join(tempRoot, "lunatest/presets/protocol"), { recursive: true });
+    await mkdir(path.join(tempRoot, "lunatest/presets/wallet"), { recursive: true });
+
+    await writeFile(
+      path.join(tempRoot, "lunatest/presets/protocol/team_swap.lua"),
+      `return {
+        manifest = {
+          id = "team_swap",
+          label = "Team Swap",
+          kind = "dex",
+          supportedChains = { 11155111 },
+          protocol = "teamdex",
+          version = "v1",
+          components = { quoter = "local" },
+          defaultWalletPreset = { id = "project/team_wallet" },
+          defaultInterceptState = {},
+          defaultRouteMocks = {},
+          builtinScenarios = {},
+          paramsSchema = {},
+          recommendedControls = {},
+        },
+        materialize = function()
+          return {
+            walletPreset = { id = "project/team_wallet" },
+            interceptState = { protocol = { id = "team_swap" } },
+          }
+        end,
+      }`,
+    );
+
+    await writeFile(
+      path.join(tempRoot, "lunatest/presets/wallet/team_wallet.lua"),
+      `return {
+        manifest = {
+          id = "team_wallet",
+          label = "Team Wallet",
+          kind = "wallet",
+          supportedChains = { 11155111 },
+          defaultSession = {
+            chainId = "0xaa36a7",
+            accounts = { "0x1111111111111111111111111111111111111111" },
+            permissions = {},
+            assets = { nativeBalance = "1", tokens = {} },
+          },
+        },
+        materialize = function()
+          return {}
+        end,
+      }`,
+    );
+
+    const projectSources = await loadProjectPresetSources(tempRoot);
+    const registry = createPresetRegistry({ projectSources });
+    const protocols = await listProtocolPresets(registry);
+    const wallets = await listWalletPresets(registry);
+
+    expect(protocols.map((item) => item.qualifiedId)).toEqual(
+      expect.arrayContaining(["project/team_swap", "builtin/uniswap_v3"]),
+    );
+    expect(wallets.map((item) => item.qualifiedId)).toEqual(
+      expect.arrayContaining(["project/team_wallet", "builtin/demo_sepolia"]),
+    );
+  });
+
+  it("collects diagnostics for malformed local presets and keeps catalog healthy", async () => {
+    const tempRoot = await fsMkdtemp();
+    await mkdir(path.join(tempRoot, "lunatest/presets/protocol"), { recursive: true });
+
+    await writeFile(
+      path.join(tempRoot, "lunatest/presets/protocol/bad_swap.lua"),
+      `return {
+        manifest = {
+          id = "bad_swap",
+          label = "Bad Swap",
+          kind = "dex",
+          supportedChains = { 11155111 },
+          protocol = "teamdex",
+          version = "v1",
+          components = { quoter = "local" },
+          defaultWalletPreset = { id = "missing_wallet" },
+          defaultInterceptState = {},
+          defaultRouteMocks = {},
+          builtinScenarios = {},
+          paramsSchema = {
+            { key = "tokenIn", label = "Token In", type = "address" },
+          },
+          recommendedControls = { "tokenOut" },
+        },
+        materialize = function()
+          return {}
+        end,
+      }`,
+    );
+
+    const registry = createPresetRegistry({
+      projectSources: await loadProjectPresetSources(tempRoot),
+    });
+
+    const protocols = await listProtocolPresets(registry);
+    const diagnostics = await getPresetDiagnostics(registry);
+
+    expect(protocols.map((item) => item.qualifiedId)).not.toContain("project/bad_swap");
+    expect(diagnostics).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: "preset_recommended_control_unknown",
+          qualifiedId: "project/bad_swap",
+          source: "project",
+        }),
+        expect.objectContaining({
+          code: "preset_wallet_reference_missing",
+          qualifiedId: "project/bad_swap",
+          source: "project",
+        }),
+      ]),
+    );
+  });
+});
+
+async function fsMkdtemp(): Promise<string> {
+  const { mkdtemp } = await import("node:fs/promises");
+  return mkdtemp(path.join(os.tmpdir(), "lunatest-preset-registry-"));
+}

package/dist/presets/loader.d.ts

@@ -0,0 +1,6 @@
+type LuaPresetModule = {
+    manifest: unknown;
+    materialize: (params?: Record<string, unknown>) => Promise<unknown>;
+};
+export declare function loadLuaPresetModule(source: string | URL): Promise<LuaPresetModule>;
+export {};

package/dist/presets/loader.js

@@ -0,0 +1,40 @@
+import { asRecord } from "@lunatest/contracts";
+import { readLuaSource } from "../config/read-source.js";
+import { createRuntime } from "../runtime/engine.js";
+function createPresetBootstrap(code) {
+    return `
+local __preset_module = (function()
+${code}
+end)()
+__lunatest_preset_manifest = __preset_module.manifest
+__lunatest_preset_materialize = __preset_module.materialize
+`;
+}
+export async function loadLuaPresetModule(source) {
+    const runtime = await createRuntime();
+    const code = await readLuaSource(source);
+    await runtime.eval(createPresetBootstrap(code));
+    const snapshot = await runtime.getState(["__lunatest_preset_manifest"]);
+    const manifest = snapshot.__lunatest_preset_manifest;
+    if (!asRecord(manifest)) {
+        throw new Error("Lua preset must expose manifest table");
+    }
+    return {
+        manifest,
+        async materialize(params = {}) {
+            const result = await runtime.call("__lunatest_preset_materialize", params);
+            if (!asRecord(result)) {
+                throw new Error("Lua preset materialize() must return a table");
+            }
+            const normalizedResult = result;
+            if (Array.isArray(result.routeMocks)) {
+                const routeMocks = result.routeMocks.filter((route) => asRecord(route) !== null);
+                return {
+                    ...normalizedResult,
+                    routeMocks,
+                };
+            }
+            return normalizedResult;
+        },
+    };
+}

package/dist/presets/loader.ts

@@ -0,0 +1,58 @@
+import { asRecord, type RouteMock } from "@lunatest/contracts";
+
+import { readLuaSource } from "../config/read-source.js";
+import { createRuntime } from "../runtime/engine.js";
+
+type LuaPresetModule = {
+  manifest: unknown;
+  materialize: (params?: Record<string, unknown>) => Promise<unknown>;
+};
+
+function createPresetBootstrap(code: string): string {
+  return `
+local __preset_module = (function()
+${code}
+end)()
+__lunatest_preset_manifest = __preset_module.manifest
+__lunatest_preset_materialize = __preset_module.materialize
+`;
+}
+
+export async function loadLuaPresetModule(source: string | URL): Promise<LuaPresetModule> {
+  const runtime = await createRuntime();
+  const code = await readLuaSource(source);
+
+  await runtime.eval(createPresetBootstrap(code));
+
+  const snapshot = await runtime.getState(["__lunatest_preset_manifest"]);
+  const manifest = snapshot.__lunatest_preset_manifest;
+
+  if (!asRecord(manifest)) {
+    throw new Error("Lua preset must expose manifest table");
+  }
+
+  return {
+    manifest,
+    async materialize(params: Record<string, unknown> = {}) {
+      const result = await runtime.call("__lunatest_preset_materialize", params);
+
+      if (!asRecord(result)) {
+        throw new Error("Lua preset materialize() must return a table");
+      }
+
+      const normalizedResult = result as Record<string, unknown>;
+
+      if (Array.isArray((result as { routeMocks?: unknown }).routeMocks)) {
+        const routeMocks = (result as { routeMocks: unknown[] }).routeMocks.filter(
+          (route): route is RouteMock => asRecord(route) !== null,
+        );
+        return {
+          ...normalizedResult,
+          routeMocks,
+        };
+      }
+
+      return normalizedResult;
+    },
+  };
+}

package/dist/presets/project-sources.node.d.ts

@@ -0,0 +1,2 @@
+import type { ProjectPresetSources } from "./registry.js";
+export declare function loadProjectPresetSources(projectRoot: string): Promise<ProjectPresetSources>;

package/dist/presets/project-sources.node.js

@@ -0,0 +1,44 @@
+async function readPresetDir(root, bucket, baseDir = root) {
+    const { readdir } = await import("node:fs/promises");
+    const path = await import("node:path");
+    const entries = await readdir(root, { withFileTypes: true });
+    for (const entry of entries) {
+        const absolutePath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            await readPresetDir(absolutePath, bucket, baseDir);
+            continue;
+        }
+        if (!entry.isFile() || !entry.name.endsWith(".lua")) {
+            continue;
+        }
+        const relativePath = path.relative(baseDir, absolutePath).replace(/\\/g, "/");
+        const id = relativePath.replace(/\.lua$/u, "");
+        bucket[id] = absolutePath;
+    }
+}
+export async function loadProjectPresetSources(projectRoot) {
+    const path = await import("node:path");
+    const fs = await import("node:fs/promises");
+    const protocolRoot = path.join(projectRoot, "lunatest", "presets", "protocol");
+    const walletRoot = path.join(projectRoot, "lunatest", "presets", "wallet");
+    const protocol = {};
+    const wallet = {};
+    try {
+        await fs.access(protocolRoot);
+        await readPresetDir(protocolRoot, protocol);
+    }
+    catch {
+        // ignore missing local protocol preset directory
+    }
+    try {
+        await fs.access(walletRoot);
+        await readPresetDir(walletRoot, wallet);
+    }
+    catch {
+        // ignore missing local wallet preset directory
+    }
+    return {
+        protocol,
+        wallet,
+    };
+}