oakscriptjs 0.13.2 → 0.14.1

package/skills/oakscript/spec.schema.json

@@ -0,0 +1,199 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "oakscript check spec",
+  "description": "What the user asked for, checked by `oakscript check --spec`: every given entry is checked, an unknown key is an error.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "kind": {
+      "enum": [
+        "indicator",
+        "strategy"
+      ],
+      "description": "indicator() or strategy()"
+    },
+    "title": {
+      "type": "string",
+      "description": "the title of the declaration"
+    },
+    "overlay": {
+      "type": "boolean",
+      "description": "true: price pane, false: own pane"
+    },
+    "inputs": {
+      "type": "object",
+      "description": "inputs that must exist, by id or title",
+      "additionalProperties": {
+        "type": "object",
+        "description": "the expected input",
+        "additionalProperties": false,
+        "properties": {
+          "type": {
+            "enum": [
+              "int",
+              "float",
+              "bool",
+              "string",
+              "text_area",
+              "source",
+              "color",
+              "timeframe",
+              "session",
+              "time",
+              "symbol"
+            ],
+            "description": "input type"
+          },
+          "defval": {
+            "description": "default value"
+          },
+          "title": {
+            "type": "string",
+            "description": "title"
+          },
+          "min": {
+            "type": "number",
+            "description": "minval"
+          },
+          "max": {
+            "type": "number",
+            "description": "maxval"
+          },
+          "options": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "the choices of a string input"
+          }
+        }
+      }
+    },
+    "outputs": {
+      "type": "array",
+      "description": "outputs that must exist: a title, or { title, kind }",
+      "items": {
+        "oneOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "title"
+            ],
+            "properties": {
+              "title": {
+                "type": "string"
+              },
+              "kind": {
+                "enum": [
+                  "plot",
+                  "shape",
+                  "char",
+                  "arrow",
+                  "candle",
+                  "bar",
+                  "hline",
+                  "bgcolor",
+                  "barcolor",
+                  "alertcondition"
+                ]
+              }
+            }
+          }
+        ]
+      }
+    },
+    "plots": {
+      "type": "object",
+      "description": "value checks per plot, by id or title",
+      "additionalProperties": {
+        "type": "object",
+        "description": "the expected values",
+        "additionalProperties": false,
+        "properties": {
+          "min": {
+            "type": "number",
+            "description": "every value is at least this"
+          },
+          "max": {
+            "type": "number",
+            "description": "every value is at most this"
+          },
+          "warmup": {
+            "type": "number",
+            "description": "the first value comes at this bar index or before"
+          }
+        }
+      }
+    },
+    "signals": {
+      "type": "object",
+      "description": "count checks per signal (shape, char, arrow, alertcondition, bgcolor, barcolor), by id or title",
+      "additionalProperties": {
+        "type": "object",
+        "description": "the expected count",
+        "additionalProperties": false,
+        "properties": {
+          "min": {
+            "type": "number",
+            "description": "at least this many bars"
+          },
+          "max": {
+            "type": "number",
+            "description": "at most this many bars"
+          },
+          "minShare": {
+            "type": "number",
+            "description": "at least this share of the bars (0 to 1)"
+          },
+          "maxShare": {
+            "type": "number",
+            "description": "at most this share of the bars (0 to 1)"
+          }
+        }
+      }
+    },
+    "trades": {
+      "type": "object",
+      "description": "closed trades of a strategy",
+      "additionalProperties": false,
+      "properties": {
+        "min": {
+          "type": "number",
+          "description": "at least"
+        },
+        "max": {
+          "type": "number",
+          "description": "at most"
+        }
+      }
+    },
+    "$schema": {
+      "type": "string",
+      "description": "the JSON Schema of the spec (oakscriptjs/skills/oakscript/spec.schema.json)"
+    },
+    "reference": {
+      "type": "string",
+      "description": "CSV of expected values per bar (a time column, one column per plot)"
+    },
+    "export": {
+      "type": "string",
+      "description": "chart export CSV: the bars (time, open, high, low, close, volume) and the expected plot values"
+    },
+    "tolerance": {
+      "type": "number",
+      "description": "relative tolerance of the reference values (default 1e-10)"
+    },
+    "checks": {
+      "type": "string",
+      "description": "JavaScript file of behaviour checks (the body of a function of `t`)"
+    },
+    "scenarios": {
+      "type": "boolean",
+      "description": "also run on the built-in edge-case bars"
+    }
+  }
+}

package/src/check/checks.ts

@@ -0,0 +1,175 @@
+/**
+ * @fileoverview Behaviour checks of a script: the checks a spec cannot write as counts and ranges ("Buy only when the
+ * RSI is below 30", "the signal line stays under the MACD", "the value on bar 100 is X"). A check function gets `t`, the
+ * outputs of the run per bar, and records each check with `t.expect` / `t.everyBar`:
+ *
+ * ```js
+ * const rsi = t.plot("RSI");
+ * t.everyBar("RSI between 0 and 100", (i) => rsi.at(i) === null || (rsi.at(i) >= 0 && rsi.at(i) <= 100));
+ * t.expect("Buy only when the RSI is below 30", t.signal("Buy").bars.every((i) => rsi.at(i) < 30));
+ * ```
+ *
+ * @module check/checks
+ */
+import type { Bar } from '../types/index.js';
+import type { ScriptRunResult, StrategyTrade } from '../script/index.js';
+
+/** The bars of each signal output (shape, char, arrow, alert condition, background or bar colour). */
+export interface SignalBars {
+  kind: 'shape' | 'char' | 'arrow' | 'alertcondition' | 'bgcolor' | 'barcolor';
+  id: string;
+  title: string;
+  /** Bar indexes with the signal, in order. */
+  bars: number[];
+}
+
+const visible = (c: string | undefined): boolean =>
+  !!c && c !== 'transparent' && !/^#[0-9a-f]{6}00$/i.test(c) && !/,\s*0\s*\)$/.test(c);
+
+/** The bars of each signal output of a run. */
+export function signalBars(run: ScriptRunResult, bars: readonly Bar[]): SignalBars[] {
+  const index = new Map(bars.map((b, i) => [b.time, i]));
+  const of = (times: number[]) =>
+    [...new Set(times.map((t) => index.get(t)).filter((i): i is number => i !== undefined))].sort((a, b) => a - b);
+  const r = run.result;
+  const out: SignalBars[] = [];
+  for (const s of run.shapeConfig) {
+    out.push({ kind: s.kind === 'char' ? 'char' : 'shape', id: s.id, title: s.title ?? s.id, bars: of((r.markers ?? []).filter((m) => m.id === s.id).map((m) => m.time)) });
+  }
+  for (const a of run.arrowConfig) {
+    const times = (r.arrows ?? []).filter((x) => x.id === a.id && x.value !== 0 && !Number.isNaN(x.value)).map((x) => x.time as number);
+    out.push({ kind: 'arrow', id: a.id, title: a.title ?? a.id, bars: of(times) });
+  }
+  for (const b of run.barColorConfig) {
+    const list = b.kind === 'bgcolor' ? (r.bgColors ?? []) : (r.barColors ?? []);
+    const times = list.filter((x) => (x.id === undefined || x.id === b.id) && visible(x.color)).map((x) => x.time);
+    out.push({ kind: b.kind, id: b.id, title: b.title ?? b.id, bars: of(times) });
+  }
+  for (const a of r.alerts ?? []) out.push({ kind: 'alertcondition', id: a.id, title: a.title ?? a.id, bars: of(a.times) });
+  return out;
+}
+
+/** A plot of the run, per bar. */
+export interface CheckPlot {
+  id: string;
+  title: string;
+  /** Value per bar (null: na). */
+  values: Array<number | null>;
+  /** Colour per bar when the plot has per-bar colours (undefined otherwise). */
+  colors?: Array<string | null>;
+  /** The value on bar `i` (null: na or no such bar). */
+  at(i: number): number | null;
+}
+
+/** A signal output of the run. */
+export interface CheckSignal {
+  kind: SignalBars['kind'];
+  id: string;
+  title: string;
+  /** Bar indexes with the signal. */
+  bars: number[];
+  /** The signal is on bar `i`. */
+  on(i: number): boolean;
+}
+
+/** What a check function gets. */
+export interface CheckContext {
+  bars: readonly Bar[];
+  /** Number of bars. */
+  n: number;
+  /** A plot by id or title; throws when there is none. */
+  plot(name: string): CheckPlot;
+  /** A signal (shape, char, arrow, alert condition, background or bar colour) by id or title; throws when there is none. */
+  signal(name: string): CheckSignal;
+  /** Closed trades of a strategy (empty for an indicator). */
+  trades: readonly StrategyTrade[];
+  /** The whole result of the run (labels, lines, boxes, tables, markers... as a host gets them). */
+  result: ScriptRunResult['result'];
+  /** The value of an input in the run, by id or title. */
+  input(name: string): unknown;
+  /** Records a check: `ok` false fails it; `detail` is shown when it fails. */
+  expect(check: string, ok: boolean, detail?: unknown): void;
+  /** Records a check true on every bar from `from` (default 0) to `to` (default the last bar); fails on the first bar where `predicate(i)` is false. */
+  everyBar(check: string, predicate: (i: number) => boolean, options?: { from?: number; to?: number }): void;
+}
+
+export interface CheckItem {
+  check: string;
+  ok: boolean;
+  expected?: unknown;
+  actual?: unknown;
+}
+
+const lower = (s: string | undefined): string => (s ?? '').trim().toLowerCase();
+
+/** Runs a check function on a run; returns its items (an exception is a failed item). */
+export function runChecks(
+  fn: (t: CheckContext) => void,
+  run: ScriptRunResult,
+  bars: readonly Bar[],
+  inputs: Record<string, unknown>,
+  trades: readonly StrategyTrade[],
+  label = 'checks'
+): CheckItem[] {
+  const items: CheckItem[] = [];
+  const index = new Map(bars.map((b, i) => [b.time, i]));
+  const signals = signalBars(run, bars);
+  const plots = new Map<string, CheckPlot>();
+  const find = <T extends { id: string; title?: string }>(list: T[], name: string): T | undefined =>
+    list.find((x) => lower(x.id) === lower(name)) ?? list.find((x) => lower(x.title) === lower(name));
+  const t: CheckContext = {
+    bars,
+    n: bars.length,
+    trades,
+    result: run.result,
+    plot(name) {
+      const p = find(run.plotConfig, name);
+      if (!p) throw new Error(`t.plot("${name}"): no plot with this id or title (plots: ${run.plotConfig.map((x) => `"${x.title ?? x.id}"`).join(', ') || 'none'})`);
+      const cached = plots.get(p.id);
+      if (cached) return cached;
+      const values: Array<number | null> = new Array(bars.length).fill(null);
+      let colors: Array<string | null> | undefined;
+      for (const pt of (run.result.plots[p.id] ?? []) as Array<{ time: number; value: number; color?: string }>) {
+        const i = index.get(pt.time);
+        if (i === undefined) continue;
+        values[i] = pt.value;
+        if (pt.color !== undefined) (colors ??= new Array(bars.length).fill(null))[i] = pt.color;
+      }
+      const plot: CheckPlot = { id: p.id, title: p.title ?? p.id, values, ...(colors ? { colors } : {}), at: (i) => values[i] ?? null };
+      plots.set(p.id, plot);
+      return plot;
+    },
+    signal(name) {
+      const s = find(signals, name);
+      if (!s) throw new Error(`t.signal("${name}"): no signal with this id or title (signals: ${signals.map((x) => `"${x.title}"`).join(', ') || 'none'})`);
+      const on = new Set(s.bars);
+      return { kind: s.kind, id: s.id, title: s.title, bars: s.bars, on: (i) => on.has(i) };
+    },
+    input(name) {
+      const i = find(run.inputConfig, name);
+      if (!i) throw new Error(`t.input("${name}"): no input with this id or title`);
+      return i.id in inputs ? inputs[i.id] : i.defval;
+    },
+    expect(check, ok, detail) {
+      items.push({ check, ok: !!ok, ...(ok || detail === undefined ? {} : { actual: detail }) });
+    },
+    everyBar(check, predicate, options = {}) {
+      const from = Math.max(0, options.from ?? 0);
+      const to = Math.min(bars.length - 1, options.to ?? bars.length - 1);
+      for (let i = from; i <= to; i++) {
+        if (!predicate(i)) {
+          items.push({ check, ok: false, expected: 'true on every bar', actual: `false on bar ${i}` });
+          return;
+        }
+      }
+      items.push({ check, ok: true });
+    },
+  };
+  try {
+    fn(t);
+  } catch (e) {
+    const m = e && typeof e === 'object' && 'message' in e ? String((e as Error).message) : String(e);
+    items.push({ check: `${label} (stopped)`, ok: false, actual: m });
+  }
+  return items;
+}

package/src/check/format.ts

@@ -0,0 +1,117 @@
+/**
+ * @fileoverview The check report as text (the output of `oakscript check`) and {@link assertCheck}, which throws it
+ * from a test of any test runner.
+ *
+ * @module check/format
+ */
+import type { CheckReport } from './index.js';
+
+const fmt = (v: number | null | undefined): string =>
+  v === null || v === undefined ? 'na' : Number.isInteger(v) ? String(v) : Number(v.toPrecision(6)).toString();
+
+const shown = (v: unknown): string => (v === undefined ? 'nothing' : JSON.stringify(v));
+
+/** The report as text, for a terminal or an agent. `file` and `typesSkipped` come from the command. */
+export function formatReport(r: CheckReport & { file?: string; typesSkipped?: string }): string {
+  const file = r.file ?? 'script';
+  const out: string[] = [];
+  out.push(`oakscript check ${file}: ${r.bars.count} ${r.bars.synthetic ? 'synthetic ' : ''}bars, timeframe ${r.bars.timeframe}`);
+  const d = r.declaration;
+  if (d) {
+    out.push(`${d.kind} "${d.title}"${d.overlay ? ' (overlay)' : ' (own pane)'}`);
+    if (d.inputs.length) {
+      out.push('inputs:');
+      for (const i of d.inputs) {
+        const extra = [i.options ? `options ${i.options.join(' | ')}` : '', i.min !== undefined ? `min ${i.min}` : '', i.max !== undefined ? `max ${i.max}` : '']
+          .filter(Boolean)
+          .join(', ');
+        out.push(`  ${i.id} (${i.type}) = ${JSON.stringify(i.defval)}${i.title ? `  "${i.title}"` : ''}${extra ? `  ${extra}` : ''}`);
+      }
+    }
+  }
+  if (r.plots.length || r.signals.length) out.push('outputs:');
+  for (const p of r.plots) {
+    out.push(
+      p.values
+        ? `  plot   "${p.title}": ${p.values} values from bar ${p.firstBar}, ${fmt(p.min)} .. ${fmt(p.max)}, last ${p.last.map(fmt).join(' ')}${p.colours ? `, ${p.colours} colours` : ''}`
+        : `  plot   "${p.title}": no value`
+    );
+  }
+  for (const s of r.signals) {
+    out.push(`  ${s.kind.padEnd(6)} "${s.title}": ${s.count} bars (${(s.share * 100).toFixed(1)} %)${s.count ? `, first ${s.firstBar}, last ${s.lastBar}` : ''}`);
+  }
+  const dr = Object.entries(r.drawings).filter(([, n]) => n > 0);
+  if (dr.length) out.push(`drawings: ${dr.map(([k, n]) => `${n} ${k}`).join(', ')}`);
+  if (r.alertCalls) out.push(`alert() calls: ${r.alertCalls}`);
+  if (r.strategy) {
+    const s = r.strategy;
+    out.push(`strategy: ${s.closedTrades} closed trades${s.openTrade ? ' + 1 open' : ''}, ${s.wins} wins, net profit ${fmt(s.netProfit)}`);
+    for (const t of s.first) {
+      out.push(`  ${t.direction} "${t.entry}" bar ${t.entryBar} @ ${fmt(t.entryPrice)} -> bar ${t.exitBar ?? '-'} @ ${fmt(t.exitPrice)}: ${fmt(t.profit)}`);
+    }
+  }
+  if (r.errors.length) {
+    out.push('errors:');
+    for (const e of r.errors) {
+      const at = e.line ? `${file}:${e.line}${e.column ? `:${e.column}` : ''} ` : '';
+      out.push(`  ${at}[${e.stage}${e.code ? ` ${e.code}` : ''}] ${e.message}`);
+    }
+  }
+  if (r.typesSkipped) out.push(`types: not checked (${r.typesSkipped})`);
+  if (r.warnings.length) {
+    out.push('warnings:');
+    for (const w of r.warnings) out.push(`  [${w.code}] ${w.message}`);
+  }
+  if (r.spec) {
+    out.push(`spec and checks: ${r.spec.passed} passed, ${r.spec.failed} failed`);
+    for (const i of r.spec.items.filter((x) => !x.ok)) {
+      out.push(`  FAIL ${i.check}${i.expected !== undefined ? `: expected ${shown(i.expected)}, got ${shown(i.actual)}` : i.actual !== undefined ? `: ${typeof i.actual === 'string' ? i.actual : shown(i.actual)}` : ''}`);
+    }
+  }
+  for (const c of r.reference ?? []) {
+    const m = c.firstMismatch;
+    out.push(
+      c.ignored
+        ? `reference "${c.column}": ignored (no plot with this id or title)`
+        : c.output === undefined
+          ? `reference "${c.column}": FAIL no plot with this id or title`
+          : `reference "${c.column}": ${c.equal} / ${c.total} bars equal${m ? `, first difference on bar ${m.bar}: expected ${fmt(m.expected)}, got ${fmt(m.actual)}` : ''}`
+    );
+  }
+  if (r.scenarios) {
+    out.push('scenarios:');
+    for (const s of r.scenarios) {
+      const notes = [...s.errors.map((e) => `ERROR ${e.message}`), ...s.warnings.map((w) => `[${w.code}] ${w.message}`)];
+      out.push(`  ${s.name} (${s.description}): ${notes.length ? '' : 'ok'}`);
+      for (const n of notes) out.push(`    ${n}`);
+    }
+  }
+  const failed =
+    (r.spec?.failed ?? 0) + (r.reference ?? []).filter((c) => !c.ignored && (c.equal !== c.total || c.output === undefined)).length;
+  out.push(
+    r.ok
+      ? r.warnings.length
+        ? `result: OK with ${r.warnings.length} warning(s)`
+        : 'result: OK'
+      : `result: FAIL (${r.errors.length} error(s), ${failed} failed check(s), ${r.warnings.length} warning(s))`
+  );
+  return out.join('\n');
+}
+
+/**
+ * Throws the report as text when the check failed (an error, a failed spec item, check or reference column), or with
+ * `{ warnings: false }` when it has warnings. For the tests of a project:
+ *
+ * ```ts
+ * it('my indicator follows its spec', () => {
+ *   assertCheck(checkScript(source, { spec, checks: (t) => { ... } }));
+ * });
+ * ```
+ */
+export function assertCheck(report: CheckReport, options: { warnings?: boolean } = {}): void {
+  if (!report.ok || (options.warnings === false && report.warnings.length > 0)) {
+    const error = new Error(formatReport(report));
+    error.name = 'CheckError';
+    throw error;
+  }
+}