@alphafox/cli 0.2.0 → 0.3.2

package/vendor/backtest-runner/lib/coverage.mjs

@@ -0,0 +1,238 @@
+export class TapeDataUnavailableError extends Error {
+  /**
+   * @param {readonly import("../index.d.ts").TapeDataIssue[]} issues
+   */
+  constructor(issues) {
+    super(formatTapeDataIssues(issues));
+    this.name = "TapeDataUnavailableError";
+    this.issues = issues;
+  }
+}
+
+const HARD_ISSUE_CODES = new Set([
+  "market_missing",
+  "ohlcv_missing",
+  "invalid_ohlcv",
+  "non_monotonic",
+  "load_failed",
+]);
+
+export function isHardTapeDataIssue(code) {
+  return HARD_ISSUE_CODES.has(code);
+}
+
+export function isTapeDataUnavailableError(value) {
+  return value instanceof TapeDataUnavailableError;
+}
+
+export function analyzeOhlcvCoverage(input) {
+  const issues = [];
+  const expectedReplayCandles = Math.max(
+    0,
+    Math.floor((input.toMs - input.fromMs) / input.stepMs)
+  );
+
+  if (input.rows.length === 0) {
+    issues.push(issue(input, "ohlcv_missing"));
+    return {
+      symbol: input.symbol,
+      timeframe: input.timeframe,
+      rowCount: 0,
+      warmupCandles: 0,
+      expectedReplayCandles,
+      actualReplayCandles: 0,
+      coverageRatio: 0,
+      issues,
+    };
+  }
+
+  let previousTimestamp;
+  for (const row of input.rows) {
+    const [timestamp, open, high, low, close, volume] = row;
+    if (
+      ![timestamp, open, high, low, close, volume].every(Number.isFinite) ||
+      timestamp <= 0 ||
+      !Number.isInteger(timestamp) ||
+      open <= 0 ||
+      high <= 0 ||
+      low <= 0 ||
+      close <= 0 ||
+      volume < 0 ||
+      high < Math.max(open, close, low) ||
+      low > Math.min(open, close, high)
+    ) {
+      issues.push(issue(input, "invalid_ohlcv", { timestamp }));
+      break;
+    }
+    if (previousTimestamp !== undefined) {
+      const delta = timestamp - previousTimestamp;
+      if (delta <= 0) {
+        issues.push(
+          issue(input, "non_monotonic", {
+            expected: previousTimestamp + input.stepMs,
+            actual: timestamp,
+            timestamp,
+          })
+        );
+        break;
+      }
+      if (delta !== input.stepMs) {
+        issues.push(
+          issue(input, "internal_gap", {
+            expected: previousTimestamp + input.stepMs,
+            actual: timestamp,
+            timestamp,
+          })
+        );
+        break;
+      }
+    }
+    previousTimestamp = timestamp;
+  }
+
+  const warmupCandles = input.rows.filter(
+    (row) => row[0] + input.stepMs <= input.fromMs
+  ).length;
+  if (warmupCandles < input.minWarmupCandles) {
+    issues.push(
+      issue(input, "warmup_insufficient", {
+        expected: input.minWarmupCandles,
+        actual: warmupCandles,
+      })
+    );
+  }
+
+  const replayRows = input.rows.filter(
+    (row) => row[0] >= input.fromMs && row[0] < input.toMs
+  );
+  const actualReplayCandles = replayRows.length;
+  const coverageRatio =
+    expectedReplayCandles > 0
+      ? actualReplayCandles / expectedReplayCandles
+      : actualReplayCandles > 0
+        ? 1
+        : 0;
+
+  if (input.requireFullReplayCoverage) {
+    const alignmentTimestamp = input.rows.find((row) =>
+      Number.isInteger(row?.[0])
+    )?.[0];
+    const expectedStart =
+      alignmentTimestamp === undefined
+        ? input.fromMs
+        : alignmentTimestamp +
+          Math.ceil(
+            (input.fromMs - alignmentTimestamp) / input.stepMs
+          ) *
+            input.stepMs;
+    const firstReplayTimestamp = replayRows[0]?.[0];
+    const lastReplayTimestamp = replayRows.at(-1)?.[0];
+    if (
+      firstReplayTimestamp === undefined ||
+      firstReplayTimestamp > expectedStart
+    ) {
+      issues.push(
+        issue(input, "prefix_gap", {
+          expected: expectedStart,
+          actual: firstReplayTimestamp,
+        })
+      );
+    }
+    if (
+      lastReplayTimestamp === undefined ||
+      lastReplayTimestamp + input.stepMs < input.toMs
+    ) {
+      issues.push(
+        issue(input, "suffix_gap", {
+          expected: input.toMs - input.stepMs,
+          actual: lastReplayTimestamp,
+        })
+      );
+    }
+  } else {
+    const lastTimestamp = input.rows.at(-1)?.[0];
+    if (
+      lastTimestamp === undefined ||
+      lastTimestamp + input.stepMs * 2 <= input.toMs
+    ) {
+      issues.push(
+        issue(input, "suffix_gap", {
+          expected: input.toMs - input.stepMs,
+          actual: lastTimestamp,
+        })
+      );
+    }
+  }
+
+  return {
+    symbol: input.symbol,
+    timeframe: input.timeframe,
+    firstTimestamp: input.rows[0]?.[0],
+    lastTimestamp: input.rows.at(-1)?.[0],
+    rowCount: input.rows.length,
+    warmupCandles,
+    expectedReplayCandles,
+    actualReplayCandles,
+    coverageRatio,
+    issues,
+  };
+}
+
+export function evaluateOhlcvCoverage(input) {
+  const report = analyzeOhlcvCoverage(input);
+
+  if (input.mode === "strict" || report.issues.length === 0) {
+    return {
+      report,
+      accepted: report.issues.length === 0,
+      blockingIssues: report.issues,
+      acceptedSoftIssues: [],
+    };
+  }
+
+  const hardIssues = report.issues.filter((item) =>
+    isHardTapeDataIssue(item.code)
+  );
+  if (hardIssues.length > 0) {
+    return {
+      report,
+      accepted: false,
+      blockingIssues: hardIssues,
+      acceptedSoftIssues: [],
+    };
+  }
+
+  return {
+    report,
+    accepted: true,
+    blockingIssues: [],
+    acceptedSoftIssues: report.issues,
+  };
+}
+
+export function formatCoverageSoftWarning(issues, coverageRatio) {
+  const codes = [...new Set(issues.map((item) => item.code))].join(", ");
+  const sample = issues[0];
+  const symbol = sample?.symbol ?? "unknown";
+  const timeframe = sample?.timeframe ?? "*";
+  return `${symbol} ${timeframe}: accepted soft data issues (${codes}) with ${(coverageRatio * 100).toFixed(1)}% replay coverage`;
+}
+
+function issue(input, code, detail = {}) {
+  return {
+    code,
+    symbol: input.symbol,
+    timeframe: input.timeframe,
+    ...detail,
+  };
+}
+
+function formatTapeDataIssues(issues) {
+  if (issues.length === 0) {
+    return "Backtest market data is unavailable.";
+  }
+  const first = issues[0];
+  const suffix =
+    issues.length > 1 ? ` (+${issues.length - 1} more issues)` : "";
+  return `${first.symbol} ${first.timeframe}: ${first.code}${suffix}`;
+}

package/vendor/backtest-runner/lib/encode.mjs

@@ -0,0 +1,28 @@
+export const TAPE_SERIES_COLUMNS = [
+  "timestamp",
+  "open",
+  "high",
+  "low",
+  "close",
+  "volume",
+];
+
+/**
+ * Encode ascending OHLCV rows ([ts, o, h, l, c, v]) into the columnar
+ * little-endian float64 buffer consumed by the wasm runtime.
+ * Layout matches `@alphafoxai/backtest-wasm` `encodeOhlcvColumns`.
+ *
+ * @param {ReadonlyArray<readonly [number, number, number, number, number, number]>} rows
+ * @returns {ArrayBuffer}
+ */
+export function encodeOhlcvColumns(rows) {
+  const count = rows.length;
+  const view = new Float64Array(TAPE_SERIES_COLUMNS.length * count);
+  for (let i = 0; i < count; i++) {
+    const row = rows[i];
+    for (let column = 0; column < TAPE_SERIES_COLUMNS.length; column++) {
+      view[column * count + i] = row[column];
+    }
+  }
+  return view.buffer;
+}

package/vendor/backtest-runner/lib/exchanges.mjs

@@ -0,0 +1,143 @@
+export const PUBLIC_MARKET_EXCHANGE_BINANCE = "binance_perp_usdt";
+export const PUBLIC_MARKET_EXCHANGE_OKX = "okx_perp_usdt";
+export const PUBLIC_MARKET_EXCHANGE_BYBIT = "bybit_perp_usdt";
+export const PUBLIC_MARKET_EXCHANGE_BITGET = "bitget_perp_usdt";
+export const PUBLIC_MARKET_EXCHANGE_HYPERLIQUID = "hyperliquid_perp_usdc";
+
+/**
+ * HIP-3 builder DEXes the web public-market picker exposes.
+ * The Node runner does not discover the live HIP-3 catalog.
+ */
+export const HYPERLIQUID_PUBLIC_MARKET_DEXES = Object.freeze(["", "xyz"]);
+const HYPERLIQUID_HIP3_DEXES = HYPERLIQUID_PUBLIC_MARKET_DEXES.filter(
+  (dex) => dex !== ""
+);
+
+export const TAPE_EXCHANGES = Object.freeze([
+  Object.freeze({
+    id: PUBLIC_MARKET_EXCHANGE_BINANCE,
+    label: "Binance",
+    ccxtId: "binanceusdm",
+    marketType: "swap",
+    quoteAsset: "USDT",
+  }),
+  Object.freeze({
+    id: PUBLIC_MARKET_EXCHANGE_OKX,
+    label: "OKX",
+    ccxtId: "okx",
+    marketType: "swap",
+    quoteAsset: "USDT",
+  }),
+  Object.freeze({
+    id: PUBLIC_MARKET_EXCHANGE_BYBIT,
+    label: "Bybit",
+    ccxtId: "bybit",
+    marketType: "swap",
+    quoteAsset: "USDT",
+  }),
+  Object.freeze({
+    id: PUBLIC_MARKET_EXCHANGE_BITGET,
+    label: "Bitget",
+    ccxtId: "bitget",
+    marketType: "swap",
+    quoteAsset: "USDT",
+  }),
+  Object.freeze({
+    id: PUBLIC_MARKET_EXCHANGE_HYPERLIQUID,
+    label: "HyperLiquid",
+    ccxtId: "hyperliquid",
+    marketType: "swap",
+    quoteAsset: "USDC",
+  }),
+]);
+
+const TAPE_EXCHANGE_BY_ID = new Map(
+  TAPE_EXCHANGES.map((exchange) => [exchange.id, exchange])
+);
+
+const PLATFORM_ALIASES = Object.freeze({
+  binance: PUBLIC_MARKET_EXCHANGE_BINANCE,
+  binanceusdm: PUBLIC_MARKET_EXCHANGE_BINANCE,
+  [PUBLIC_MARKET_EXCHANGE_BINANCE]: PUBLIC_MARKET_EXCHANGE_BINANCE,
+  okx: PUBLIC_MARKET_EXCHANGE_OKX,
+  [PUBLIC_MARKET_EXCHANGE_OKX]: PUBLIC_MARKET_EXCHANGE_OKX,
+  bybit: PUBLIC_MARKET_EXCHANGE_BYBIT,
+  [PUBLIC_MARKET_EXCHANGE_BYBIT]: PUBLIC_MARKET_EXCHANGE_BYBIT,
+  bitget: PUBLIC_MARKET_EXCHANGE_BITGET,
+  [PUBLIC_MARKET_EXCHANGE_BITGET]: PUBLIC_MARKET_EXCHANGE_BITGET,
+  hyperliquid: PUBLIC_MARKET_EXCHANGE_HYPERLIQUID,
+  [PUBLIC_MARKET_EXCHANGE_HYPERLIQUID]: PUBLIC_MARKET_EXCHANGE_HYPERLIQUID,
+});
+
+export function resolveTapeExchange(exchangeId) {
+  if (exchangeId && typeof exchangeId === "object") {
+    const id = exchangeId.id;
+    if (typeof id === "string" && TAPE_EXCHANGE_BY_ID.has(id)) {
+      return TAPE_EXCHANGE_BY_ID.get(id);
+    }
+    if (exchangeId.ccxtId) {
+      tapeExchangeRuntimeConfig(exchangeId);
+      return exchangeId;
+    }
+    throw new Error(
+      `Unsupported tape exchange: ${id ?? JSON.stringify(exchangeId)}`
+    );
+  }
+  if (typeof exchangeId !== "string" || exchangeId.trim() === "") {
+    throw new Error("Tape exchange id is required");
+  }
+  const normalized = exchangeId.trim().toLowerCase();
+  const id = PLATFORM_ALIASES[normalized];
+  const exchange = id ? TAPE_EXCHANGE_BY_ID.get(id) : undefined;
+  if (!exchange) {
+    throw new Error(`Unsupported tape exchange: ${exchangeId}`);
+  }
+  return exchange;
+}
+
+export function tapeExchangeRuntimeConfig(exchange) {
+  switch (exchange.ccxtId) {
+    case "binanceusdm":
+      return {
+        ohlcvPageLimit: 1500,
+        fundingPageLimit: 1000,
+        requestParams: {},
+      };
+    case "okx":
+      return {
+        ohlcvPageLimit: 100,
+        fundingPageLimit: 100,
+        requestParams: { instType: "SWAP" },
+        constructorOptions: {
+          fetchMarkets: { types: ["swap"] },
+        },
+      };
+    case "bybit":
+      return {
+        ohlcvPageLimit: 1000,
+        fundingPageLimit: 200,
+        requestParams: { category: "linear" },
+      };
+    case "bitget":
+      return {
+        ohlcvPageLimit: 1000,
+        fundingPageLimit: 100,
+        requestParams: { productType: "USDT-FUTURES" },
+      };
+    case "hyperliquid":
+      return {
+        ohlcvPageLimit: 5000,
+        fundingPageLimit: 500,
+        requestParams: {},
+        constructorOptions: {
+          fetchMarkets: {
+            types: ["swap", "hip3"],
+            hip3: { dexes: [...HYPERLIQUID_HIP3_DEXES] },
+          },
+        },
+        unsupportedTimeframes: ["6h"],
+      };
+    default:
+      throw new Error(`Engine Backtest 不支持 ${exchange.label ?? exchange.ccxtId} 数据源`);
+  }
+}

package/vendor/backtest-runner/lib/proxy.mjs

@@ -0,0 +1,78 @@
+const agentCacheIds = new WeakMap();
+let nextAgentCacheId = 1;
+
+/**
+ * Resolve ccxt constructor proxy fields.
+ *
+ * Explicit `httpsProxy` / `httpProxy` / `agent` win. Otherwise read
+ * `HTTPS_PROXY` / `https_proxy` / `HTTP_PROXY` / `http_proxy`.
+ * HTTPS requests fall back to HTTP_PROXY when HTTPS_PROXY is unset.
+ *
+ * These keys are passed through to the ccxt constructor (`httpsProxy`,
+ * `httpProxy`, `agent`). They are never silently dropped.
+ *
+ * @param {import("../index.d.ts").TapeProxyOptions | undefined} options
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function resolveCcxtProxyOptions(options = {}, env = process.env) {
+  const httpsProxy =
+    options.httpsProxy ??
+    env.HTTPS_PROXY ??
+    env.https_proxy ??
+    env.HTTP_PROXY ??
+    env.http_proxy;
+  const httpProxy =
+    options.httpProxy ?? env.HTTP_PROXY ?? env.http_proxy;
+  const agent = options.agent;
+  const resolved = {};
+  if (httpsProxy) {
+    resolved.httpsProxy = httpsProxy;
+  }
+  if (httpProxy) {
+    resolved.httpProxy = httpProxy;
+  }
+  if (agent) {
+    resolved.agent = agent;
+  }
+  return resolved;
+}
+
+export function ccxtExchangeClientCacheKey(exchangeId, options = {}) {
+  const proxy = resolveCcxtProxyOptions(options);
+  return JSON.stringify([
+    exchangeId,
+    proxy.httpsProxy ?? null,
+    proxy.httpProxy ?? null,
+    agentCacheIdentity(proxy.agent),
+  ]);
+}
+
+export function buildCcxtConstructorOptions(exchange, options = {}) {
+  const runtimeConfig = options.runtimeConfig;
+  const proxy = resolveCcxtProxyOptions(options);
+  return {
+    enableRateLimit: true,
+    options: {
+      defaultType: exchange.marketType,
+      ...(runtimeConfig?.constructorOptions ?? {}),
+    },
+    ...proxy,
+  };
+}
+
+function agentCacheIdentity(agent) {
+  if (
+    agent === undefined ||
+    agent === null ||
+    (typeof agent !== "object" && typeof agent !== "function")
+  ) {
+    return agent ?? null;
+  }
+  let id = agentCacheIds.get(agent);
+  if (id === undefined) {
+    id = nextAgentCacheId;
+    nextAgentCacheId += 1;
+    agentCacheIds.set(agent, id);
+  }
+  return id;
+}

package/vendor/backtest-runner/lib/scenario.mjs

@@ -0,0 +1,66 @@
+export const DEFAULT_EXECUTION_MODEL = Object.freeze({
+  pricePath: "ohlc_path_4",
+  makerFeeRate: 0.0002,
+  takerFeeRate: 0.0005,
+  slippageRate: 0.0001,
+});
+
+const PRICE_PATHS = new Set(["ohlc_path_4", "close_only"]);
+
+/**
+ * Assemble an EngineBacktestScenario from a prepared tape.
+ * Does not execute wasm.
+ *
+ * @param {import("../index.d.ts").AssembleScenarioInput} input
+ * @returns {import("../index.d.ts").EngineBacktestScenario}
+ */
+export function assembleScenario(input) {
+  const tape = input?.tape ?? input?.preparedTape?.tape ?? input?.prepared?.tape;
+  if (!tape) {
+    throw new Error("assembleScenario requires a prepared tape");
+  }
+  if (typeof input.runId !== "string" || input.runId.trim() === "") {
+    throw new Error("assembleScenario requires runId");
+  }
+  if (
+    typeof input.definitionId !== "string" ||
+    input.definitionId.trim() === ""
+  ) {
+    throw new Error("assembleScenario requires definitionId");
+  }
+  if (!Number.isFinite(input.initialEquity)) {
+    throw new Error("assembleScenario requires initialEquity");
+  }
+
+  return {
+    version: 1,
+    runId: input.runId,
+    trader: {
+      ...(input.traderId ? { id: input.traderId } : {}),
+      ...(input.traderName ? { name: input.traderName } : {}),
+      strategyDefinitionId: input.definitionId,
+      configSchemaVersion: input.configSchemaVersion,
+      subscriptionTier: input.subscriptionTier,
+      config: structuredClone(input.config),
+    },
+    exchange: {
+      positionSideDual: true,
+      initialEquity: input.initialEquity,
+    },
+    executionModel: resolveExecutionModel(input.executionModel),
+    tape,
+  };
+}
+
+function resolveExecutionModel(override) {
+  const merged = {
+    pricePath: override?.pricePath ?? DEFAULT_EXECUTION_MODEL.pricePath,
+    makerFeeRate: override?.makerFeeRate ?? DEFAULT_EXECUTION_MODEL.makerFeeRate,
+    takerFeeRate: override?.takerFeeRate ?? DEFAULT_EXECUTION_MODEL.takerFeeRate,
+    slippageRate: override?.slippageRate ?? DEFAULT_EXECUTION_MODEL.slippageRate,
+  };
+  if (!PRICE_PATHS.has(merged.pricePath)) {
+    throw new Error(`Unsupported executionModel.pricePath: ${merged.pricePath}`);
+  }
+  return merged;
+}