oakscriptjs 0.13.2 → 0.14.0

package/dist/cjs/check/harness.js

@@ -0,0 +1,302 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var harness_exports = {};
+__export(harness_exports, {
+  LIBRARY_PARAMETER: () => LIBRARY_PARAMETER,
+  SCRIPT_GLOBALS: () => SCRIPT_GLOBALS,
+  SCRIPT_PREFIX: () => SCRIPT_PREFIX,
+  SCRIPT_SUFFIX: () => SCRIPT_SUFFIX,
+  TestEngine: () => TestEngine,
+  compileScript: () => compileScript,
+  inferTimeframe: () => inferTimeframe,
+  rewriteImports: () => rewriteImports,
+  runScript: () => runScript,
+  scriptArguments: () => scriptArguments,
+  syntheticBars: () => syntheticBars,
+  testChart: () => testChart,
+  timeframeSeconds: () => timeframeSeconds,
+  wrapSource: () => wrapSource
+});
+module.exports = __toCommonJS(harness_exports);
+var lib = __toESM(require("../index.js"), 1);
+var api = __toESM(require("../script/index.js"), 1);
+var import_script = require("../script/index.js");
+const SCRIPT_GLOBALS = Object.keys(api).filter(
+  (k) => k !== "default" && k !== "executeScript" && /^[A-Za-z_$][\w$]*$/.test(k)
+);
+const LIBRARY_PARAMETER = "__oakscriptjs";
+function scriptArguments() {
+  return [...SCRIPT_GLOBALS.map((k) => api[k]), lib];
+}
+function rewriteImports(source) {
+  return source.replace(/^([ \t]*)import\s*(\{[^}]*\}|\*\s+as\s+[A-Za-z_$][\w$]*)\s*from\s*(['"])([^'"]+)\3\s*;?/gm, (all, indent, what, _q, from) => {
+    if (from !== "oakscriptjs" && from !== "oakscriptjs/script") {
+      throw new SyntaxError(`A script can only import from "oakscriptjs" (found "${from}").`);
+    }
+    const lines = all.split("\n").length - 1;
+    const binding = what.startsWith("*") ? what.replace(/^\*\s+as\s+/, "") : what.replace(/\s+as\s+/g, ": ").replace(/\s+/g, " ");
+    return `${indent}const ${binding} = ${LIBRARY_PARAMETER};${"\n".repeat(lines)}`;
+  });
+}
+const SCRIPT_PREFIX = '"use strict"; return (function () { ';
+const SCRIPT_SUFFIX = "\n})();";
+function wrapSource(source) {
+  return SCRIPT_PREFIX + rewriteImports(source) + SCRIPT_SUFFIX;
+}
+function compileScript(source) {
+  const fn = new Function(...SCRIPT_GLOBALS, LIBRARY_PARAMETER, wrapSource(source));
+  const values = scriptArguments();
+  return () => fn(...values);
+}
+const HOUR = 3600;
+const START = 1704067200;
+function syntheticBars(count, step = HOUR, seed = 1) {
+  let s = seed >>> 0 || 1;
+  const rand = () => {
+    s = Math.imul(s, 1664525) + 1013904223 >>> 0;
+    return s / 2 ** 32;
+  };
+  const scale = Math.sqrt(step / HOUR);
+  const bars = [];
+  let prev = 100;
+  for (let i = 0; i < count; i++) {
+    const t = i * step / HOUR;
+    const close = 100 + 12 * Math.sin(t / 60) + 4 * Math.sin(t / 11) + t * 4e-3 + (rand() - 0.5) * 1.5 * scale;
+    const open = prev;
+    const high = Math.max(open, close) + rand() * 0.8 * scale;
+    const low = Math.min(open, close) - rand() * 0.8 * scale;
+    bars.push({ time: START + i * step, open, high, low, close, volume: Math.round(1e3 + rand() * 4e3) });
+    prev = close;
+  }
+  return bars;
+}
+function timeframeSeconds(timeframe) {
+  const m = /^(\d*)([SDWM]?)$/.exec(timeframe.trim().toUpperCase());
+  if (!m) return NaN;
+  const n = m[1] ? Number(m[1]) : 1;
+  const unit = { "": 60, S: 1, D: 86400, W: 7 * 86400, M: 30 * 86400 }[m[2]];
+  return n * unit;
+}
+function inferTimeframe(bars) {
+  const counts = /* @__PURE__ */ new Map();
+  for (let i = 1; i < bars.length; i++) {
+    const d = bars[i].time - bars[i - 1].time;
+    if (d > 0) counts.set(d, (counts.get(d) ?? 0) + 1);
+  }
+  let step = 0;
+  let best = 0;
+  for (const [d, c] of counts) if (c > best) [step, best] = [d, c];
+  if (!step) return "60";
+  if (step >= 28 * 86400) return "M";
+  if (step >= 7 * 86400) return "W";
+  if (step >= 86400) return "D";
+  if (step < 60) return `${step}S`;
+  return String(Math.round(step / 60));
+}
+function testChart(bars, options = {}) {
+  const timezone = options.timezone ?? "Etc/UTC";
+  const session = options.session ?? "24x7";
+  const chartStep = timeframeSeconds(options.timeframe ?? "60") || HOUR;
+  const span = bars.length ? bars[bars.length - 1].time - bars[0].time + chartStep : 0;
+  return {
+    tickerid: options.tickerid ?? "TEST:SYN",
+    timeframe: options.timeframe ?? "60",
+    timezone,
+    session,
+    mintick: 0.01,
+    pointvalue: 1,
+    mincontract: 1,
+    currency: "USD",
+    bars: (symbol, timeframe) => {
+      const step = timeframeSeconds(timeframe);
+      if (!step) return [];
+      if (!bars.length) return [{ time: 0, open: 0, high: 0, low: 0, close: 0, volume: 0 }];
+      const first = bars[0].time;
+      return syntheticBars(Math.ceil(span / step), step, symbol.length + 7).map((b) => ({
+        ...b,
+        time: first + (b.time - START)
+      }));
+    },
+    symbolInfo: () => ({ timezone, session, mintick: 0.01, currency: "USD" })
+  };
+}
+class TestEngine {
+  constructor(setup) {
+    this.setup = setup;
+  }
+  setup;
+  closed = [];
+  open = null;
+  pendingEntry = null;
+  pendingClose = false;
+  exits = /* @__PURE__ */ new Map();
+  net = 0;
+  bar = 0;
+  get bars() {
+    return this.setup.bars;
+  }
+  equity(price) {
+    return this.setup.properties.initial_capital + this.net + this.openProfit(price);
+  }
+  openProfit(price) {
+    return this.open ? (price - this.open.entry_price) * this.open.size : 0;
+  }
+  commission(value) {
+    const p = this.setup.properties;
+    return p.commission_type === "percent" ? Math.abs(value) * p.commission_value / 100 : 0;
+  }
+  closeAt(price, exitId) {
+    const t = this.open;
+    if (!t) return;
+    const commission = t.commission + this.commission(price * t.size);
+    const profit = (price - t.entry_price) * t.size - commission;
+    this.net += profit;
+    this.closed.push({
+      ...t,
+      commission,
+      profit,
+      profit_percent: profit / Math.abs(t.entry_price * t.size) * 100,
+      exit_id: exitId,
+      exit_price: price,
+      exit_bar_index: this.bar,
+      exit_time: this.bars[this.bar].time * 1e3
+    });
+    this.open = null;
+    this.exits.clear();
+  }
+  /** The open trade, if any. */
+  get openTradeNow() {
+    return this.open;
+  }
+  processBar(bar) {
+    this.bar = bar;
+    const b = this.bars[bar];
+    if (this.pendingClose) this.closeAt(b.open, "Close");
+    this.pendingClose = false;
+    const e = this.pendingEntry;
+    this.pendingEntry = null;
+    if (e && !(this.open && Math.sign(this.open.size) === (e.direction === "long" ? 1 : -1))) {
+      if (this.open) this.closeAt(b.open, e.id);
+      const p = this.setup.properties;
+      const equity = this.equity(b.open);
+      const qty = e.qty ?? (p.default_qty_type === "fixed" ? p.default_qty_value : p.default_qty_type === "cash" ? p.default_qty_value / b.open : equity * p.default_qty_value / 100 / b.open);
+      const size = e.direction === "long" ? qty : -qty;
+      this.open = {
+        entry_id: e.id,
+        entry_price: b.open,
+        entry_bar_index: bar,
+        entry_time: b.time * 1e3,
+        size,
+        profit: 0,
+        profit_percent: 0,
+        commission: this.commission(b.open * size),
+        max_runup: 0,
+        max_runup_percent: 0,
+        max_drawdown: 0,
+        max_drawdown_percent: 0
+      };
+    }
+    const t = this.open;
+    if (!t) return;
+    for (const [id, x] of this.exits) {
+      if (x.from_entry !== void 0 && x.from_entry !== t.entry_id) continue;
+      const long = t.size > 0;
+      if (x.stop !== void 0 && (long ? b.low <= x.stop : b.high >= x.stop)) {
+        this.closeAt(long ? Math.min(b.open, x.stop) : Math.max(b.open, x.stop), id);
+        return;
+      }
+      if (x.limit !== void 0 && (long ? b.high >= x.limit : b.low <= x.limit)) {
+        this.closeAt(long ? Math.max(b.open, x.limit) : Math.min(b.open, x.limit), id);
+        return;
+      }
+    }
+  }
+  processClose() {
+  }
+  entry(id, direction, options) {
+    this.pendingEntry = { id, direction, qty: options.qty };
+  }
+  order(id, direction, options) {
+    this.entry(id, direction, options);
+  }
+  exit(id, options) {
+    this.exits.set(id, options);
+  }
+  close(id, _options) {
+    if (this.open?.entry_id === id) this.pendingClose = true;
+  }
+  close_all() {
+    if (this.open) this.pendingClose = true;
+  }
+  cancel(id) {
+    this.exits.delete(id);
+    if (this.pendingEntry?.id === id) this.pendingEntry = null;
+  }
+  cancel_all() {
+    this.exits.clear();
+    this.pendingEntry = null;
+  }
+  rules = [];
+  risk(rule) {
+    this.rules.push(rule);
+  }
+  get(variable) {
+    const price = this.bars[this.bar]?.close ?? NaN;
+    const wins = this.closed.filter((t) => t.profit > 0).length;
+    const values = {
+      position_size: this.open?.size ?? 0,
+      position_avg_price: this.open?.entry_price ?? NaN,
+      initial_capital: this.setup.properties.initial_capital,
+      equity: this.equity(price),
+      netprofit: this.net,
+      openprofit: this.openProfit(price),
+      opentrades: this.open ? 1 : 0,
+      closedtrades: this.closed.length,
+      wintrades: wins,
+      losstrades: this.closed.length - wins,
+      account_currency: "USD"
+    };
+    return values[variable];
+  }
+  openTrade(index) {
+    return index === 0 && this.open ? this.open : void 0;
+  }
+  closedTrade(index) {
+    return this.closed[index];
+  }
+}
+function runScript(source, bars, inputs = {}, options = {}) {
+  let engine;
+  const body = (options.compile ?? compileScript)(source);
+  const run = (0, import_script.executeScript)(body, bars, inputs, testChart(bars, options), {
+    strategyEngine: (setup) => engine = new TestEngine(setup)
+  });
+  return { run, engine };
+}
+//# sourceMappingURL=harness.js.map

package/dist/cjs/check/harness.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/check/harness.ts"],
+  "sourcesContent": ["/**\n * @fileoverview Runs a script source the way a host app runs a script written in its editor: the source is the body\n * of the script, with every value export of `oakscriptjs/script` but `executeScript` as an implicit global, on\n * deterministic synthetic bars (or given bars), with a chart context and, for a strategy, a small order engine.\n * Used by {@link checkScript}, the `oakscript check` command and the tests of the agent guide.\n *\n * @module check/harness\n */\nimport * as lib from '../index.js';\nimport * as api from '../script/index.js';\nimport {\n  executeScript,\n  type ChartContext,\n  type ScriptRunResult,\n  type StrategyCloseOptions,\n  type StrategyDirection,\n  type StrategyEngine,\n  type StrategyEntryOptions,\n  type StrategyExitOptions,\n  type StrategyRiskRule,\n  type StrategySetup,\n  type StrategyTrade,\n  type StrategyVariable,\n} from '../script/index.js';\nimport type { Bar } from '../types/index.js';\n\n/** The implicit globals of a script: every value export of the script API but the host entry. */\nexport const SCRIPT_GLOBALS: readonly string[] = Object.keys(api).filter(\n  (k) => k !== 'default' && k !== 'executeScript' && /^[A-Za-z_$][\\w$]*$/.test(k)\n);\n\n/** Name of the parameter that receives the `oakscriptjs` module in a compiled script (its `import` statements). */\nexport const LIBRARY_PARAMETER = '__oakscriptjs';\n\n/** The values of {@link SCRIPT_GLOBALS}, then the `oakscriptjs` module, in the order of the compiled parameters. */\nexport function scriptArguments(): unknown[] {\n  return [...SCRIPT_GLOBALS.map((k) => (api as Record<string, unknown>)[k]), lib];\n}\n\n/**\n * Rewrites the `import { a, b as c } from \"oakscriptjs\"` statements of a script into `const { a, b: c } = ...` on the\n * same lines (the line numbers of the source do not change). Throws on an import of another module: a script runs\n * self-contained.\n */\nexport function rewriteImports(source: string): string {\n  return source.replace(/^([ \\t]*)import\\s*(\\{[^}]*\\}|\\*\\s+as\\s+[A-Za-z_$][\\w$]*)\\s*from\\s*(['\"])([^'\"]+)\\3\\s*;?/gm, (all, indent, what, _q, from) => {\n    if (from !== 'oakscriptjs' && from !== 'oakscriptjs/script') {\n      throw new SyntaxError(`A script can only import from \"oakscriptjs\" (found \"${from}\").`);\n    }\n    const lines = all.split('\\n').length - 1;\n    const binding = what.startsWith('*')\n      ? what.replace(/^\\*\\s+as\\s+/, '')\n      : what.replace(/\\s+as\\s+/g, ': ').replace(/\\s+/g, ' ');\n    return `${indent}const ${binding} = ${LIBRARY_PARAMETER};${'\\n'.repeat(lines)}`;\n  });\n}\n\n/**\n * Start and end of the function the script source is wrapped in. The globals are the parameters of an outer function\n * and the source is the body of an inner one, so a script can declare a name of a global (`const size = 2`), as in an\n * app that imports the globals at the top of a module. The start goes on the first line of the source.\n */\nexport const SCRIPT_PREFIX = '\"use strict\"; return (function () { ';\nexport const SCRIPT_SUFFIX = '\\n})();';\n\n/** The source of the function body of a compiled script (imports rewritten, lines kept). */\nexport function wrapSource(source: string): string {\n  return SCRIPT_PREFIX + rewriteImports(source) + SCRIPT_SUFFIX;\n}\n\n/** Compiles a script source into a body for executeScript(); throws a SyntaxError on invalid code. */\nexport function compileScript(source: string): () => void {\n  const fn = new Function(...SCRIPT_GLOBALS, LIBRARY_PARAMETER, wrapSource(source)) as (...args: unknown[]) => void;\n  const values = scriptArguments();\n  return () => fn(...values);\n}\n\nconst HOUR = 3600;\n/** 2024-01-01 00:00 UTC, in seconds. */\nconst START = 1704067200;\n\n/** Deterministic synthetic bars: two waves, a slow trend and seeded noise. `step`: seconds between bars. */\nexport function syntheticBars(count: number, step = HOUR, seed = 1): Bar[] {\n  let s = seed >>> 0 || 1;\n  const rand = (): number => {\n    s = (Math.imul(s, 1664525) + 1013904223) >>> 0;\n    return s / 2 ** 32;\n  };\n  const scale = Math.sqrt(step / HOUR);\n  const bars: Bar[] = [];\n  let prev = 100;\n  for (let i = 0; i < count; i++) {\n    const t = (i * step) / HOUR;\n    const close = 100 + 12 * Math.sin(t / 60) + 4 * Math.sin(t / 11) + t * 0.004 + (rand() - 0.5) * 1.5 * scale;\n    const open = prev;\n    const high = Math.max(open, close) + rand() * 0.8 * scale;\n    const low = Math.min(open, close) - rand() * 0.8 * scale;\n    bars.push({ time: START + i * step, open, high, low, close, volume: Math.round(1000 + rand() * 4000) });\n    prev = close;\n  }\n  return bars;\n}\n\n/** Seconds of a timeframe string (\"1\", \"60\", \"240\", \"D\", \"1D\", \"W\", \"M\"); NaN when it is not one. */\nexport function timeframeSeconds(timeframe: string): number {\n  const m = /^(\\d*)([SDWM]?)$/.exec(timeframe.trim().toUpperCase());\n  if (!m) return NaN;\n  const n = m[1] ? Number(m[1]) : 1;\n  const unit = { '': 60, S: 1, D: 86400, W: 7 * 86400, M: 30 * 86400 }[m[2] as '' | 'S' | 'D' | 'W' | 'M'];\n  return n * unit;\n}\n\n/** The timeframe of bars from the most common spacing of their times (\"60\", \"D\", \"W\"...); \"60\" for fewer than 2 bars. */\nexport function inferTimeframe(bars: readonly Bar[]): string {\n  const counts = new Map<number, number>();\n  for (let i = 1; i < bars.length; i++) {\n    const d = bars[i]!.time - bars[i - 1]!.time;\n    if (d > 0) counts.set(d, (counts.get(d) ?? 0) + 1);\n  }\n  let step = 0;\n  let best = 0;\n  for (const [d, c] of counts) if (c > best) [step, best] = [d, c];\n  if (!step) return '60';\n  if (step >= 28 * 86400) return 'M';\n  if (step >= 7 * 86400) return 'W';\n  if (step >= 86400) return 'D';\n  if (step < 60) return `${step}S`;\n  return String(Math.round(step / 60));\n}\n\nexport interface TestChartOptions {\n  /** Chart timeframe (default \"60\"). */\n  timeframe?: string;\n  /** Chart ticker id (default \"TEST:SYN\"). */\n  tickerid?: string;\n  /** Time zone of the chart and of the other symbols (default \"Etc/UTC\"). */\n  timezone?: string;\n  /** Session of the chart and of the other symbols (default \"24x7\"). */\n  session?: string;\n}\n\n/**\n * Chart context of the test runs: a 24x7 symbol in UTC. Higher timeframes of the chart symbol are resampled from the\n * chart bars by the library; other symbols get synthetic bars of their own (seeded by the symbol name).\n */\nexport function testChart(bars: Bar[], options: TestChartOptions = {}): ChartContext {\n  const timezone = options.timezone ?? 'Etc/UTC';\n  const session = options.session ?? '24x7';\n  const chartStep = timeframeSeconds(options.timeframe ?? '60') || HOUR;\n  const span = bars.length ? bars[bars.length - 1]!.time - bars[0]!.time + chartStep : 0;\n  return {\n    tickerid: options.tickerid ?? 'TEST:SYN',\n    timeframe: options.timeframe ?? '60',\n    timezone,\n    session,\n    mintick: 0.01,\n    pointvalue: 1,\n    mincontract: 1,\n    currency: 'USD',\n    bars: (symbol, timeframe) => {\n      const step = timeframeSeconds(timeframe);\n      if (!step) return [];\n      // a run on zero bars (the declaration run of a host) gets one empty bar: no bars at all is an invalid symbol\n      if (!bars.length) return [{ time: 0, open: 0, high: 0, low: 0, close: 0, volume: 0 }];\n      const first = bars[0]!.time;\n      return syntheticBars(Math.ceil(span / step), step, symbol.length + 7).map((b) => ({\n        ...b,\n        time: first + (b.time - START),\n      }));\n    },\n    symbolInfo: () => ({ timezone, session, mintick: 0.01, currency: 'USD' }),\n  };\n}\n\n/**\n * A small order engine for checks and tests (the library does not fill orders). Market entries and closes fill at the\n * next bar open; `strategy.exit` stop / limit levels are checked inside each bar (stop first when both are hit).\n * Entry limit / stop prices, pyramiding and process_orders_on_close are not simulated.\n */\nexport class TestEngine implements StrategyEngine {\n  readonly closed: StrategyTrade[] = [];\n  private open: StrategyTrade | null = null;\n  private pendingEntry: { id: string; direction: StrategyDirection; qty?: number } | null = null;\n  private pendingClose = false;\n  private exits = new Map<string, StrategyExitOptions>();\n  private net = 0;\n  private bar = 0;\n\n  constructor(readonly setup: StrategySetup) {}\n\n  private get bars(): readonly Bar[] {\n    return this.setup.bars;\n  }\n\n  private equity(price: number): number {\n    return this.setup.properties.initial_capital + this.net + this.openProfit(price);\n  }\n\n  private openProfit(price: number): number {\n    return this.open ? (price - this.open.entry_price) * this.open.size : 0;\n  }\n\n  private commission(value: number): number {\n    const p = this.setup.properties;\n    return p.commission_type === 'percent' ? (Math.abs(value) * p.commission_value) / 100 : 0;\n  }\n\n  private closeAt(price: number, exitId: string): void {\n    const t = this.open;\n    if (!t) return;\n    const commission = t.commission + this.commission(price * t.size);\n    const profit = (price - t.entry_price) * t.size - commission;\n    this.net += profit;\n    this.closed.push({\n      ...t,\n      commission,\n      profit,\n      profit_percent: (profit / Math.abs(t.entry_price * t.size)) * 100,\n      exit_id: exitId,\n      exit_price: price,\n      exit_bar_index: this.bar,\n      exit_time: this.bars[this.bar]!.time * 1000,\n    });\n    this.open = null;\n    this.exits.clear();\n  }\n\n  /** The open trade, if any. */\n  get openTradeNow(): StrategyTrade | null {\n    return this.open;\n  }\n\n  processBar(bar: number): void {\n    this.bar = bar;\n    const b = this.bars[bar]!;\n    if (this.pendingClose) this.closeAt(b.open, 'Close');\n    this.pendingClose = false;\n    const e = this.pendingEntry;\n    this.pendingEntry = null;\n    if (e && !(this.open && Math.sign(this.open.size) === (e.direction === 'long' ? 1 : -1))) {\n      if (this.open) this.closeAt(b.open, e.id);\n      const p = this.setup.properties;\n      const equity = this.equity(b.open);\n      const qty =\n        e.qty ??\n        (p.default_qty_type === 'fixed'\n          ? p.default_qty_value\n          : p.default_qty_type === 'cash'\n            ? p.default_qty_value / b.open\n            : (equity * p.default_qty_value) / 100 / b.open);\n      const size = e.direction === 'long' ? qty : -qty;\n      this.open = {\n        entry_id: e.id,\n        entry_price: b.open,\n        entry_bar_index: bar,\n        entry_time: b.time * 1000,\n        size,\n        profit: 0,\n        profit_percent: 0,\n        commission: this.commission(b.open * size),\n        max_runup: 0,\n        max_runup_percent: 0,\n        max_drawdown: 0,\n        max_drawdown_percent: 0,\n      };\n    }\n    const t = this.open;\n    if (!t) return;\n    for (const [id, x] of this.exits) {\n      if (x.from_entry !== undefined && x.from_entry !== t.entry_id) continue;\n      const long = t.size > 0;\n      if (x.stop !== undefined && (long ? b.low <= x.stop : b.high >= x.stop)) {\n        this.closeAt(long ? Math.min(b.open, x.stop) : Math.max(b.open, x.stop), id);\n        return;\n      }\n      if (x.limit !== undefined && (long ? b.high >= x.limit : b.low <= x.limit)) {\n        this.closeAt(long ? Math.max(b.open, x.limit) : Math.min(b.open, x.limit), id);\n        return;\n      }\n    }\n  }\n\n  processClose(): void {}\n\n  entry(id: string, direction: StrategyDirection, options: StrategyEntryOptions): void {\n    this.pendingEntry = { id, direction, qty: options.qty };\n  }\n\n  order(id: string, direction: StrategyDirection, options: StrategyEntryOptions): void {\n    this.entry(id, direction, options);\n  }\n\n  exit(id: string, options: StrategyExitOptions): void {\n    this.exits.set(id, options);\n  }\n\n  close(id: string, _options: StrategyCloseOptions): void {\n    if (this.open?.entry_id === id) this.pendingClose = true;\n  }\n\n  close_all(): void {\n    if (this.open) this.pendingClose = true;\n  }\n\n  cancel(id: string): void {\n    this.exits.delete(id);\n    if (this.pendingEntry?.id === id) this.pendingEntry = null;\n  }\n\n  cancel_all(): void {\n    this.exits.clear();\n    this.pendingEntry = null;\n  }\n\n  readonly rules: StrategyRiskRule[] = [];\n\n  risk(rule: StrategyRiskRule): void {\n    this.rules.push(rule);\n  }\n\n  get(variable: StrategyVariable): number | string | undefined {\n    const price = this.bars[this.bar]?.close ?? NaN;\n    const wins = this.closed.filter((t) => t.profit > 0).length;\n    const values: Partial<Record<StrategyVariable, number | string>> = {\n      position_size: this.open?.size ?? 0,\n      position_avg_price: this.open?.entry_price ?? NaN,\n      initial_capital: this.setup.properties.initial_capital,\n      equity: this.equity(price),\n      netprofit: this.net,\n      openprofit: this.openProfit(price),\n      opentrades: this.open ? 1 : 0,\n      closedtrades: this.closed.length,\n      wintrades: wins,\n      losstrades: this.closed.length - wins,\n      account_currency: 'USD',\n    };\n    return values[variable];\n  }\n\n  openTrade(index: number): StrategyTrade | undefined {\n    return index === 0 && this.open ? this.open : undefined;\n  }\n\n  closedTrade(index: number): StrategyTrade | undefined {\n    return this.closed[index];\n  }\n}\n\nexport interface ScriptRun {\n  run: ScriptRunResult;\n  engine?: TestEngine;\n}\n\nexport interface RunScriptOptions extends TestChartOptions {\n  /** Compiles the source (default {@link compileScript}); the CLI compiles with file lines. */\n  compile?: (source: string) => () => void;\n}\n\n/** Runs a script source on `bars` with the test chart context and, for a strategy, the test engine. */\nexport function runScript(\n  source: string,\n  bars: Bar[],\n  inputs: Record<string, unknown> = {},\n  options: RunScriptOptions = {}\n): ScriptRun {\n  let engine: TestEngine | undefined;\n  const body = (options.compile ?? compileScript)(source);\n  const run = executeScript(body, bars, inputs, testChart(bars, options), {\n    strategyEngine: (setup) => (engine = new TestEngine(setup)),\n  });\n  return { run, engine };\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/check/index.d.ts

@@ -0,0 +1,253 @@
+/**
+ * @fileoverview Checks a script source: runs it like a host (a declaration run on zero bars, then a run on bars) and
+ * returns a report an agent or a host can act on: what the script declares (inputs, outputs, strategy), what its outputs
+ * contain (values, warm-up, ranges, signal counts, trades), warnings for the mistakes that give no error (an empty plot,
+ * a signal on every bar or never, an input that changes nothing...), and the result of a spec (the expected inputs,
+ * outputs and signals) and of a reference (expected values per bar). The `oakscript check` command prints it.
+ *
+ * ```ts
+ * import { checkScript } from 'oakscriptjs/check';
+ * const report = checkScript(source, { spec: { overlay: true, outputs: ['Fast', 'Slow'] } });
+ * report.ok; report.errors; report.warnings; report.spec?.items;
+ * ```
+ *
+ * @module check
+ */
+import type { Bar } from '../types/index.js';
+import type { InputConfig } from '../runtime/types.js';
+import { type TestChartOptions } from './harness.js';
+import { type CheckContext, type CheckItem } from './checks.js';
+export { validateSpec, specJsonSchema, SPEC_FIELDS, SPEC_FILE_FIELDS } from './spec.js';
+export { runChecks, signalBars, type CheckContext, type CheckItem, type CheckPlot, type CheckSignal, type SignalBars } from './checks.js';
+export { formatReport, assertCheck } from './format.js';
+export { compileScript, inferTimeframe, rewriteImports, runScript, scriptArguments, syntheticBars, testChart, timeframeSeconds, LIBRARY_PARAMETER, SCRIPT_GLOBALS, SCRIPT_PREFIX, SCRIPT_SUFFIX, TestEngine, wrapSource, type RunScriptOptions, type ScriptRun, type TestChartOptions, } from './harness.js';
+/** Expected count of a signal (a shape, character, arrow, alert condition, background or bar colour) over the bars. */
+export interface SignalSpec {
+    /** At least this many bars with the signal. */
+    min?: number;
+    /** At most this many bars with the signal. */
+    max?: number;
+    /** At least this share of the bars (0 to 1). */
+    minShare?: number;
+    /** At most this share of the bars (0 to 1). */
+    maxShare?: number;
+}
+/** Expected values of a plot. */
+export interface PlotSpec {
+    /** Every value is at least this. */
+    min?: number;
+    /** Every value is at most this. */
+    max?: number;
+    /** The first value comes at this bar index or before (the warm-up). */
+    warmup?: number;
+}
+/** Expected input: the keys are compared when given. */
+export interface InputSpec {
+    type?: InputConfig['type'];
+    defval?: unknown;
+    title?: string;
+    min?: number;
+    max?: number;
+    options?: string[];
+}
+/**
+ * What the user asked for, written before the script: each given entry is checked. Inputs, plots and signals are
+ * found by id or title (case insensitive).
+ */
+export interface CheckSpec {
+    kind?: 'indicator' | 'strategy';
+    title?: string;
+    overlay?: boolean;
+    /** Inputs that must exist, with the expected type, default... */
+    inputs?: Record<string, InputSpec>;
+    /** Outputs that must exist (a title, or a title and a kind: plot, shape, char, arrow, candle, bar, hline, bgcolor, barcolor, alertcondition). */
+    outputs?: Array<string | {
+        title: string;
+        kind?: string;
+    }>;
+    /** Value checks per plot. */
+    plots?: Record<string, PlotSpec>;
+    /** Count checks per signal. */
+    signals?: Record<string, SignalSpec>;
+    /** Number of closed trades of a strategy. */
+    trades?: {
+        min?: number;
+        max?: number;
+    };
+}
+/** Expected values per bar, e.g. the outputs of the Pine script a port follows, on the same bars. */
+export interface CheckReference {
+    /** Bar times (UNIX seconds). */
+    times: number[];
+    /** Expected values per plot id or title, aligned with `times` (NaN or null: na). */
+    columns: Record<string, Array<number | null>>;
+    /** Equal when |a - b| <= tolerance * max(1, |a|, |b|) (default 1e-10), or both na. */
+    tolerance?: number;
+    /** A column without a plot of that id or title is listed as ignored instead of failing (a chart export holds other columns). */
+    ignoreUnknown?: boolean;
+}
+/** A run on edge-case bars (`scenarios: true`): a short history, daily bars, flat prices, no volume, a gap. */
+export interface CheckScenario {
+    name: string;
+    description: string;
+    timeframe: string;
+    bars: () => Bar[];
+}
+export interface CheckOptions extends TestChartOptions {
+    /** Bars of the run (default: 1,500 deterministic synthetic bars of the timeframe). */
+    bars?: Bar[];
+    /** Input values by id (default: the defaults). */
+    inputs?: Record<string, unknown>;
+    spec?: CheckSpec;
+    reference?: CheckReference;
+    /** Compiles the source (default: `new Function`; the CLI compiles with the file name for error lines). */
+    compile?: (source: string) => () => void;
+    /** Wraps each run (the CLI stops a run that takes too long). */
+    run?: <T>(fn: () => T) => T;
+    /** File name of the source, to read the error lines from the stack (`<file>:line:column`). */
+    filename?: string;
+    /** Re-run with each input changed to find inputs that change no output (default true). */
+    inputSweep?: boolean;
+    /** Behaviour checks: called with the outputs of the run per bar (see {@link CheckContext}); their results join the spec items. */
+    checks?: (t: CheckContext) => void;
+    /** Also run on the edge-case bars of {@link SCENARIOS} (or the given ones): their errors fail the check. */
+    scenarios?: boolean | CheckScenario[];
+}
+export type CheckStage = 'syntax' | 'types' | 'declaration' | 'run' | 'timeout' | 'spec' | 'reference' | 'scenario';
+export interface CheckError {
+    stage: CheckStage;
+    message: string;
+    line?: number;
+    column?: number;
+    /** TypeScript error code (stage "types"). */
+    code?: string;
+}
+export interface CheckWarning {
+    code: 'empty-plot' | 'constant-plot' | 'late-start' | 'signal-never' | 'signal-everywhere' | 'one-colour' | 'unused-input' | 'input-error' | 'no-trades' | 'no-output';
+    message: string;
+    /** Output or input title (or id). */
+    target?: string;
+}
+export interface PlotSummary {
+    id: string;
+    title: string;
+    /** Bars with a value (not na). */
+    values: number;
+    /** Bar index of the first value (-1: none). */
+    firstBar: number;
+    min: number | null;
+    max: number | null;
+    /** Values of the last 5 bars (null: na). */
+    last: Array<number | null>;
+    /** Distinct per-bar colours (0: the plot colour is the same on every bar). */
+    colours: number;
+}
+export interface SignalSummary {
+    kind: 'shape' | 'char' | 'arrow' | 'alertcondition' | 'bgcolor' | 'barcolor';
+    id: string;
+    title: string;
+    /** Bars with the signal. */
+    count: number;
+    /** count / number of bars. */
+    share: number;
+    firstBar: number;
+    lastBar: number;
+}
+export interface TradeSummary {
+    entry: string;
+    direction: 'long' | 'short';
+    entryBar: number;
+    entryPrice: number;
+    exitBar: number | null;
+    exitPrice: number | null;
+    profit: number;
+}
+export interface CheckReport {
+    /** No error, no failed spec or reference check. Warnings do not change it. */
+    ok: boolean;
+    bars: {
+        count: number;
+        first: number | null;
+        last: number | null;
+        timeframe: string;
+        synthetic: boolean;
+    };
+    errors: CheckError[];
+    warnings: CheckWarning[];
+    declaration?: {
+        kind: 'indicator' | 'strategy';
+        title: string;
+        shortTitle?: string;
+        overlay: boolean;
+        inputs: Array<Pick<InputConfig, 'id' | 'type' | 'defval' | 'title' | 'min' | 'max' | 'options'>>;
+        outputs: Array<{
+            kind: string;
+            id: string;
+            title: string;
+        }>;
+        strategy?: Record<string, unknown>;
+    };
+    plots: PlotSummary[];
+    signals: SignalSummary[];
+    drawings: {
+        labels: number;
+        lines: number;
+        boxes: number;
+        tables: number;
+        polylines: number;
+        linefills: number;
+    };
+    /** alert() calls of the script (all bars). */
+    alertCalls: number;
+    strategy?: {
+        closedTrades: number;
+        openTrade: boolean;
+        netProfit: number;
+        wins: number;
+        first: TradeSummary[];
+    };
+    /** Spec items and behaviour checks. */
+    spec?: {
+        passed: number;
+        failed: number;
+        items: CheckItem[];
+    };
+    reference?: Array<{
+        column: string;
+        output?: string;
+        /** No plot of this id or title, and `ignoreUnknown` is set. */
+        ignored?: boolean;
+        equal: number;
+        total: number;
+        firstMismatch?: {
+            bar: number;
+            time: number;
+            expected: number | null;
+            actual: number | null;
+        };
+    }>;
+    /** Runs on edge-case bars: their errors (also in `errors`, stage "scenario") and the plots with no value the main run does not have. */
+    scenarios?: Array<{
+        name: string;
+        description: string;
+        bars: number;
+        errors: CheckError[];
+        warnings: CheckWarning[];
+    }>;
+}
+/** Line and column of a script error, from `error.scriptLine` or the `<filename>:line:column` frames of its stack. */
+export declare function errorLocation(error: unknown, filename?: string): {
+    line?: number;
+    column?: number;
+};
+/** Default number of synthetic bars of a check. */
+export declare const CHECK_BARS = 1500;
+/** The edge-case bars of `scenarios: true`. */
+export declare const SCENARIOS: readonly CheckScenario[];
+/**
+ * Checks a script source (the body of a script, as a host runs it): compiles it, runs it on zero bars (the
+ * declarations) and on the bars, and reports its declarations, outputs, warnings and the spec / reference results.
+ * Never throws for a script error: the errors are in the report.
+ */
+export declare function checkScript(source: string, options?: CheckOptions): CheckReport;
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/check/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/check/index.ts"],"names":[],"mappings":"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"}