oakscriptjs 0.13.1 → 0.14.0

package/skills/oakscript/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: oakscript
+description: Write, port, review or fix OakScript scripts - indicators and strategies written in JavaScript with the oakscriptjs/script API, a Pine Script v6-style API. Use when asked to create or debug an indicator, oscillator, overlay, signal, alert or backtest strategy for OakScriptJS or for an app that runs OakScript scripts (such as the OpenTrader script editor), or to port a Pine Script v6 script to JavaScript.
+---
+
+# Writing OakScript scripts
+
+An OakScript script is **plain JavaScript** that reads like Pine Script v6. The host (a chart app, a worker,
+a test) runs the whole script body on all the bars at once, and runs it again when the bars or the inputs change.
+
+```js
+indicator("My SMA", { overlay: true });                      // one declaration: indicator() or strategy()
+const length = input.int(20, "Length", { minval: 1 });       // an input: declared AND read here
+const sma = ta.sma(close, length);                           // Series math, all bars at once
+plot(sma, "SMA", { color: color.blue, linewidth: 2 });       // an output
+plotshape(ta.crossover(close, sma), "Cross", { style: shape.triangleup, location: location.belowbar });
+```
+
+## The script format
+
+- The file is the script body: top-level statements, no wrapper function, no `export`.
+- Every export of `oakscriptjs/script` is a global: `indicator`, `strategy`, `input`, `plot`, `ta`, `color`,
+  `close`, `request`, `eachBar`, `label`, `table`... No import is needed.
+- Write JavaScript, not TypeScript: the app editor runs the source without a compile step, so type annotations
+  are syntax errors.
+- Other modules: `import { array, matrix, map, callsite } from "oakscriptjs";` at the top of the script (these
+  are not globals). Use JS arrays and `Map` when you can.
+- Outside an app, a host passes the body as a function: see [Running a script](#running-a-script).
+- A source that exports `calculate(bars, inputs, chart)` is an older format (built-in indicator sources use it).
+  Write new scripts in the format above; a strategy must use it.
+
+## Workflow
+
+0. **Write the spec first** when you can run a command: the user's request as a small JSON file (title, pane,
+   inputs and defaults, outputs, what the signals look like, `"scenarios": true`) and, for the behaviour it cannot
+   count ("Buy only when the RSI is below 30"), a checks file; `oakscript check` checks both (step 6). An unknown spec
+   key is an error. See [check](reference/check.md#the-spec).
+1. **Declare** with `indicator(title, { overlay })` (overlay `true`: on the price pane; `false`, the default: own pane) or
+   `strategy(title, { ...properties })`. Exactly one declaration, at the top.
+2. **Inputs**: `input.int / float / bool / string / color / source / timeframe / session / symbol / time`.
+   They return plain values (a Series for `input.source`). The input id is the title in snake case
+   ("Fast length" is `fast_length`): hosts pass overrides by id.
+3. **Compute with Series** before any loop: `ta.*`, the price builtins and the Series methods
+   (`.add .sub .mul .div .gt .lt .eq .and .or .not .iff .offset`).
+4. **Per-bar state** (Pine `var`, `:=`, `if` on series values, loops): `eachBar((c) => ...)`; for a strategy,
+   `strategy.eachBar((c) => ...)` holds the orders.
+5. **Outputs**: `plot`, `hline`, `fill`, `plotshape`, `plotchar`, `plotarrow`, `bgcolor`, `barcolor`,
+   `plotcandle`, drawings (`label.new`, `line.new`, `box.new`, `table.new`), `alertcondition`, `alert`.
+6. **Check it**: `npx oakscript check script.js --spec spec.json` type-checks the script, runs it on 1,500 bars
+   and reports errors with their line, the inputs and outputs, the values and signal counts, the failed spec items and
+   warnings (an empty plot, a signal on every bar or never, an input that changes nothing). Fix until the exit code is
+   0, or 2 with warnings you have read. For a port, `--export chart-export.csv` compares the values bar by bar. See
+   [check](reference/check.md).
+7. **Without a command**, check by hand: compile errors, runtime errors, then the plot values on the last bars
+   (an empty plot means NaN everywhere). See [errors](reference/errors.md).
+8. Start from the closest [example](#examples) rather than from scratch.
+
+## Rules
+
+1. **No operators on Series.** JavaScript has no operator overloading: `close - open`, `rsi > 50` and
+   `` `${rsi}` `` throw a TypeError, and `if (ta.crossover(a, b))` is always true (an object, no error). Write `close.sub(open)`, `a.gt(b)`, `cond.iff(x, y)`,
+   `x.offset(1)` (Pine `x[1]`), `a.and(b)`, `a.not()`. Conditions are Series of 1 / 0.
+2. **Plain numbers inside the bar loops.** In `eachBar` / `strategy.eachBar`, `c.close`, `c.get(series)`,
+   `c.get(series, 1)` are numbers: JS operators, `if`, `for` work. A condition reads `c.get(cond) === 1`.
+3. **Compute `ta.*` outside the loops.** A `ta.*` call inside a bar callback throws: compute the Series before
+   the loop and read it with `c.get()`.
+4. **Pine constants exist** as in Pine: `shape.*`, `location.*`, `size.*`, `xloc.*`, `yloc.*`, `extend.*`,
+   `display.*`, `format.*`, `font.*`, `scale.*`, `order.*`, `currency.*`, `label.style_*`, `line.style_*`,
+   `dayofweek.*`, `color.*`, `plot.style_*`, `plot.linestyle_*`, `hline.style_*`, `strategy.*`, `barmerge.*`,
+   `position.*`, `text.*`, `alert.freq_*`, `session.*`, `barstate.*`. Their values are strings
+   (`shape.triangleup` is `"triangleup"`), which also work.
+5. **Arguments**: Pine's named arguments are an object after the leading arguments, with Pine's names:
+   `plot(series, title, { color, linewidth, style })`, `input.int(14, { title: "Length", minval: 1 })`,
+   `request.security(sym, "W", () => open, { lookahead: barmerge.lookahead_on })`, `strategy.exit(id, { from_entry, stop })`,
+   `label.new(c.i, c.high, "A", { style: label.style_label_down, textcolor: color.white })`. Drawing functions
+   also take all their arguments by name (`line.new({ x1, y1, x2, y2, extend: extend.right })`); an unknown name
+   throws with the closest names. In a bar loop a Series argument of a drawing is its value on the current bar
+   (`label.new(bar_index, high, "A")`).
+6. **na is NaN.** There is no `na` constant: use `NaN` (`undefined` for a colour). `na(x)` and `nz(x, y)` take
+   numbers (use them in a bar loop); on a Series use `x.iff(x, 0)` for `nz(x)`, `fixnan(x)`, or a bar loop.
+   Plots skip NaN bars. JS comparisons with NaN are false; for the Pine rules (1e-10 tolerance) use
+   `compare.gt(a, b)`, `compare.eq(a, b)`...
+7. **Per-bar colours** are arrays with one colour per bar: `color.when(cond, colorTrue, colorFalse?)`
+   (omitted: na), or an array you fill in a bar loop. `color.new(c, transp)` sets the transparency (0-100).
+8. **Strategies**: order calls (`strategy.entry/exit/close/...`) and per-bar reads (`strategy.position_size`,
+   `strategy.equity`, `strategy.netprofit`...) only inside `strategy.eachBar()`, which runs once per script.
+9. **Other timeframes**: compute the series **inside** the expression:
+   `request.security("", "D", () => ta.ema(close, 20))`, never `() => myEma`.
+10. **No future bars**: offsets are 0 or positive; history reaches at most 5000 bars back.
+11. **Self-contained and fast**: no network, timers or DOM; the same bars give the same output. Hosts stop a
+    run that takes too long (seconds), so avoid nested loops over all bars.
+
+## Pine Script v6 at a glance
+
+| Pine Script v6 | OakScript |
+|---|---|
+| `//@version=6` | nothing |
+| `a + b`, `a > b`, `c ? x : y` (series) | `a.add(b)`, `a.gt(b)`, `c.iff(x, y)` |
+| `close[1]` | `close.offset(1)`; in a loop `c.get(close, 1)` |
+| `var x = 0` / `x := ...` | `let x = 0` before `eachBar`, assigned in the callback |
+| `bar_index`, `last_bar_index` | the Series `bar_index`, `last_bar_index`; in a bar loop `c.i`, `c.n - 1` |
+| `plot(x, "T", color=c, linewidth=2)` | `plot(x, "T", { color: c, linewidth: 2 })` |
+| `[a, b, c] = ta.macd(...)` | `const [a, b, c] = ta.macd(...)` |
+| `if cond` + `strategy.entry(...)` | `strategy.eachBar((c) => { if (c.get(cond) === 1) strategy.entry(...) })` |
+
+Full table, the deviations and the unsupported parts: [reference/pine-differences.md](reference/pine-differences.md).
+
+## Common mistakes
+
+- `if (series)`, `series ? a : b` at the top level: always true, with no error; use Series methods (rule 1).
+- `close - open`, `ma > 50`: a TypeError; use Series methods (rule 1).
+- `ta.sma(...)` inside `eachBar`: an error; compute it before the loop (rule 3).
+- `ta.stoch(close, high, low, 14)` takes all four arguments, as in Pine.
+- A per-bar colour from a JS ternary on a Series (`cond ? green : red`): one colour; use `color.when()`.
+- `strategy.position_size` at the top level: read it inside `strategy.eachBar()`.
+- Two `indicator()` calls, or `indicator()` and `strategy()` in one script: one declaration only.
+- Pine named arguments with `=` (`label.new(x, y, text = "A", style = ...)`): an object, `{ style: ... }`.
+- `strategy.opentrades.entry_price(0)`: `strategy.opentrades` is the count (a number); use
+  `strategy.opentrade(0)?.entry_price` (same for `strategy.closedtrades.*` with `strategy.closedtrade(i)`).
+
+## Reading errors
+
+- **Syntax errors** come with the line and column of your source (the app editor maps them to your lines).
+- **Runtime errors** stop the run: the message names the call and the fix, e.g. `strategy.entry() must be
+  called inside strategy.eachBar().`, `ta.smaa does not exist. Did you mean ta.sma?`, `JavaScript operators
+  (+ - * / ...) do not work on a Series: use its methods...` A host that runs a declaration pass first (zero bars) reports declaration
+  errors when the script is saved.
+- **No error, wrong output**: an empty plot (NaN everywhere: a NaN input to the math, a division by zero),
+  a branch taken on every bar (a Series used as a JS boolean). Check the plot values on the last bars.
+
+The messages and their fixes: [reference/errors.md](reference/errors.md).
+
+## Examples
+
+Complete scripts, run by the package's CI on synthetic bars:
+
+- [examples/ma-cross.js](examples/ma-cross.js): overlay, inputs (incl. a choice list), two MAs, a per-bar
+  coloured fill, cross markers, alert conditions.
+- [examples/macd-oscillator.js](examples/macd-oscillator.js): own pane, tuple from `ta.macd`, four-colour
+  histogram built in a bar loop, zero line, background.
+- [examples/mtf-trend-filter.js](examples/mtf-trend-filter.js): `request.security` on a higher timeframe
+  (tuple), `var`-style state in `eachBar`, signal labels, a label on the last bar.
+- [examples/ma-cross-strategy.js](examples/ma-cross-strategy.js): `strategy()` with sizing and commission,
+  long / short entries, stop loss and take profit with `strategy.exit`, a results table.
+
+## Reference
+
+- [reference/script-structure.md](reference/script-structure.md): declarations, inputs, Series, `eachBar`,
+  builtins (`time`, `barstate`, `timeframe`, `syminfo`), drawings' lifetime.
+- [reference/plotting.md](reference/plotting.md): lines, histograms, shapes, characters, arrows, fills,
+  colours, background and bar colours, candles, labels, lines, boxes, tables, alerts.
+- [reference/timeframes-symbols.md](reference/timeframes-symbols.md): `request.security` (higher and lower
+  timeframes, other symbols, tuples, lookahead), `request.security_lower_tf`, `timeframe.*`.
+- [reference/strategies.md](reference/strategies.md): properties, sizing, orders, exits, reading the results,
+  risk rules, the host's order engine.
+- [reference/pine-differences.md](reference/pine-differences.md): Pine Script v6 to OakScript, what is not
+  supported.
+- [reference/errors.md](reference/errors.md): compiler and runtime errors, silent mistakes.
+- [reference/check.md](reference/check.md): `oakscript check`, its warnings, the spec and reference files.
+
+## Type-checking
+
+`oakscript check` runs this type check itself. On its own: `oakscriptjs/script/globals` types the script globals; a
+`tsconfig.json` next to the scripts, then `npx tsc -p .` (one error per mistake, with its line; no output means no
+type error):
+
+```json
+{
+  "compilerOptions": {
+    "allowJs": true, "checkJs": true, "noEmit": true, "strict": true, "noImplicitAny": false,
+    "target": "ES2022", "module": "ESNext", "moduleResolution": "bundler", "moduleDetection": "force",
+    "lib": ["ES2022"], "types": ["oakscriptjs/script/globals"]
+  },
+  "include": ["*.js"]
+}
+```
+
+It needs `oakscriptjs` and `typescript` installed in the project. The checker does not see a Series used as a
+JavaScript boolean (`if (cond)`, `cond ? a : b` with a Series `cond`): check those by hand (rule 1).
+
+## Running a script
+
+In an app (OpenTrader's script editor) save the script: the app compiles it, then runs it on the chart bars.
+In your own code, wrap the body in a function and pass it to `executeScript` (imports needed there):
+
+```ts
+import { executeScript, indicator, input, plot, ta, close } from 'oakscriptjs/script';
+
+const run = executeScript(() => {
+  indicator('My SMA', { overlay: true });
+  plot(ta.sma(close, input.int(20, 'Length')), 'SMA');
+}, bars, { length: 50 }, { timeframe: '60', timezone: 'Etc/UTC', session: '24x7' });
+// run.result.plots.plot0 -> [{ time, value }, ...]; run.inputConfig, run.plotConfig, run.strategyConfig...
+```
+
+Bars are `{ time, open, high, low, close, volume }`, oldest first, `time` in UNIX seconds. The chart context
+(4th argument) gives the timeframe, time zone and session that `request.security`, `time()` and
+`timeframe.*` need. A strategy also needs an order engine: see [strategies](reference/strategies.md#the-host-side).

package/skills/oakscript/examples/ma-cross-strategy.js

@@ -0,0 +1,57 @@
+// Moving-average cross strategy: long and short entries on the crosses, a stop loss
+// and a take profit from the entry price, and a results table on the last bar.
+strategy("MA Cross Strategy", {
+  shorttitle: "MA X Strat",
+  overlay: true,
+  initial_capital: 10000,
+  default_qty_type: strategy.percent_of_equity,
+  default_qty_value: 50,
+  commission_type: strategy.commission.percent,
+  commission_value: 0.05,
+});
+
+const fastLength = input.int(10, "Fast length", { minval: 1 });
+const slowLength = input.int(30, "Slow length", { minval: 1 });
+const stopPercent = input.float(2, "Stop loss %", { minval: 0.1, step: 0.1 });
+const takePercent = input.float(4, "Take profit %", { minval: 0.1, step: 0.1 });
+
+// Series math happens before the bar loop, on all bars at once.
+const fast = ta.sma(close, fastLength);
+const slow = ta.sma(close, slowLength);
+const longSignal = ta.crossover(fast, slow);
+const shortSignal = ta.crossunder(fast, slow);
+
+plot(fast, "Fast", { color: color.teal });
+plot(slow, "Slow", { color: color.orange });
+
+// Orders and strategy.* reads only work inside strategy.eachBar(): the callback runs at the
+// close of each bar; market orders fill at the open of the next bar.
+strategy.eachBar((c) => {
+  if (c.get(longSignal) === 1) strategy.entry("Long", strategy.long);
+  if (c.get(shortSignal) === 1) strategy.entry("Short", strategy.short);
+
+  const size = strategy.position_size;
+  const entryPrice = strategy.position_avg_price;
+  if (size > 0) {
+    strategy.exit("Long exit", {
+      from_entry: "Long",
+      stop: entryPrice * (1 - stopPercent / 100),
+      limit: entryPrice * (1 + takePercent / 100),
+    });
+  } else if (size < 0) {
+    strategy.exit("Short exit", {
+      from_entry: "Short",
+      stop: entryPrice * (1 + stopPercent / 100),
+      limit: entryPrice * (1 - takePercent / 100),
+    });
+  }
+
+  // Results so far, read from the order engine.
+  if (c.i === c.n - 1) {
+    const t = table.new(position.top_right, 2, 2, color.new(color.black, 20));
+    table.cell(t, 0, 0, "Net profit", 0, 0, color.white);
+    table.cell(t, 1, 0, str.tostring(strategy.netprofit, "#.##"), 0, 0, color.white);
+    table.cell(t, 0, 1, "Closed trades", 0, 0, color.white);
+    table.cell(t, 1, 1, str.tostring(strategy.closedtrades), 0, 0, color.white);
+  }
+});

package/skills/oakscript/examples/ma-cross.js

@@ -0,0 +1,34 @@
+// Moving-average cross on the price pane: two averages, a fill between them,
+// markers on the crosses and two alert conditions.
+indicator("MA Cross", { shorttitle: "MA X", overlay: true });
+
+const src = input.source("close", "Source");
+const fastLength = input.int(9, "Fast length", { minval: 1 });
+const slowLength = input.int(21, "Slow length", { minval: 1 });
+const maType = input.string("EMA", "MA type", { options: ["SMA", "EMA", "WMA"] });
+
+// Inputs are plain values: a JS `if` on them is fine.
+function ma(source, length) {
+  if (maType === "SMA") return ta.sma(source, length);
+  if (maType === "WMA") return ta.wma(source, length);
+  return ta.ema(source, length);
+}
+
+const fast = ma(src, fastLength);
+const slow = ma(src, slowLength);
+const bullish = fast.gt(slow); // Series of 1 / 0: fast > slow
+
+const fastPlot = plot(fast, "Fast", { color: color.teal, linewidth: 2 });
+const slowPlot = plot(slow, "Slow", { color: color.orange, linewidth: 2 });
+fill(fastPlot, slowPlot, {
+  color: color.when(bullish, color.new(color.teal, 85), color.new(color.red, 85)),
+  title: "Trend fill",
+});
+
+const crossUp = ta.crossover(fast, slow);
+const crossDown = ta.crossunder(fast, slow);
+plotshape(crossUp, "Cross up", { style: shape.triangleup, location: location.belowbar, color: color.teal, size: size.small });
+plotshape(crossDown, "Cross down", { style: shape.triangledown, location: location.abovebar, color: color.red, size: size.small });
+
+alertcondition(crossUp, "Cross up", "Fast MA crossed above the slow MA");
+alertcondition(crossDown, "Cross down", "Fast MA crossed below the slow MA");

package/skills/oakscript/examples/macd-oscillator.js

@@ -0,0 +1,29 @@
+// MACD in its own pane: a four-colour histogram, the MACD and signal lines,
+// a zero level and a background on the signal crosses.
+indicator("MACD Oscillator", { shorttitle: "MACD", overlay: false, precision: 4 });
+
+const src = input.source("close", "Source");
+const fastLength = input.int(12, "Fast length", { minval: 1 });
+const slowLength = input.int(26, "Slow length", { minval: 1 });
+const signalLength = input.int(9, "Signal smoothing", { minval: 1, maxval: 50 });
+
+// A tuple comes back as an array: destructure it.
+const [macdLine, signalLine, hist] = ta.macd(src, fastLength, slowLength, signalLength);
+
+// Four colours: above / below zero, growing / falling. color.when() takes two colours,
+// so build the per-bar array in a bar loop (one entry per bar, undefined = na).
+const histColors = [];
+eachBar((c) => {
+  const h = c.get(hist);
+  const previous = c.get(hist, 1);
+  if (Number.isNaN(h)) histColors.push(undefined);
+  else if (h >= 0) histColors.push(h > previous ? "#26A69A" : "#B2DFDB");
+  else histColors.push(h < previous ? "#FF5252" : "#FFCDD2");
+});
+
+plot(hist, "Histogram", { style: plot.style_columns, color: histColors });
+plot(macdLine, "MACD", { color: color.blue, linewidth: 2 });
+plot(signalLine, "Signal", { color: color.orange });
+hline(0, "Zero", { color: color.gray, linestyle: hline.style_dotted });
+
+bgcolor(color.when(ta.cross(macdLine, signalLine), color.new(color.gray, 85)), { title: "Signal cross" });

package/skills/oakscript/examples/mtf-trend-filter.js

@@ -0,0 +1,46 @@
+// Multi-timeframe filter: a higher-timeframe EMA decides the trend, and a cross of the
+// chart EMA gives a signal only when it agrees with that trend, once per trend.
+indicator("MTF Trend Filter", { shorttitle: "MTF", overlay: true });
+
+const filterTf = input.timeframe("D", "Filter timeframe");
+const filterLength = input.int(20, "Filter EMA length", { minval: 1 });
+const signalLength = input.int(10, "Signal EMA length", { minval: 1 });
+
+// The expression runs on the higher-timeframe bars: compute every series INSIDE it.
+// Returning an array gives one series per element (a PineScript tuple).
+const [htfEma, htfClose] = request.security("", filterTf, () => [ta.ema(close, filterLength), close]);
+const upTrend = htfClose.gt(htfEma);
+
+const signalEma = ta.ema(close, signalLength);
+plot(htfEma, "Filter EMA", { color: color.gray, linewidth: 2, style: plot.style_stepline });
+plot(signalEma, "Signal EMA", { color: color.when(upTrend, color.teal, color.red) });
+
+const crossUp = ta.crossover(close, signalEma);
+const crossDown = ta.crossunder(close, signalEma);
+
+// Stateful logic (PineScript `var` + `:=`): a closure variable in a bar loop.
+let lastSignal = 0; // var int lastSignal = 0
+const signal = eachBar((c) => {
+  const up = c.get(upTrend) === 1;
+  if (c.get(crossUp) === 1 && up && lastSignal !== 1) {
+    lastSignal = 1;
+    return 1;
+  }
+  if (c.get(crossDown) === 1 && !up && lastSignal !== -1) {
+    lastSignal = -1;
+    return -1;
+  }
+  return 0;
+});
+
+plotshape(signal.eq(1), "Long", { style: shape.labelup, location: location.belowbar, color: color.teal, text: "L", textcolor: color.white });
+plotshape(signal.eq(-1), "Short", { style: shape.labeldown, location: location.abovebar, color: color.red, text: "S", textcolor: color.white });
+bgcolor(color.when(upTrend, color.new(color.teal, 92), color.new(color.red, 92)), { title: "Trend" });
+
+// One label on the last bar with the filter state.
+eachBar((c) => {
+  if (c.i === c.n - 1) {
+    const text = (c.get(upTrend) === 1 ? "Uptrend " : "Downtrend ") + filterTf;
+    label.new(c.i, c.high, text, { color: color.gray, style: label.style_label_down, textcolor: color.white });
+  }
+});

package/skills/oakscript/reference/check.md

@@ -0,0 +1,150 @@
+# Checking a script: `oakscript check`
+
+`oakscript check` runs a script the way an app runs it (the declarations on zero bars, then a run on bars) and
+prints what it declares and what it outputs, the errors with their line, warnings for the mistakes that give no error,
+and the result of a spec: the inputs, outputs and signals the user asked for.
+
+```sh
+npx oakscript check my-indicator.js                       # synthetic bars (1,500, hourly)
+npx oakscript check my-indicator.js --spec spec.json      # + the user's spec (and its checks file)
+npx oakscript check my-indicator.js --scenarios           # + edge-case bars
+npx oakscript check my-port.js --export chart-export.csv  # + bars and expected values of a chart export
+```
+
+Exit code: `0` clean, `2` warnings only, `1` an error or a failed spec / reference check. Run it after each change
+until it gives `0` (or `2` with warnings you have read and explained).
+
+## Workflow
+
+1. Write the spec from the user's request **before** the script (below): title, pane, inputs with their defaults,
+   outputs, what the signals should look like; and a checks file for the behaviour the spec cannot count ("Buy only
+   when the RSI is below 30"). Add `"scenarios": true`.
+2. Write the script.
+3. `npx oakscript check script.js --spec spec.json`; fix the errors, then the failed spec items and checks, then
+   read the warnings.
+4. For a port of a Pine script with known values, add `--export` (or `--bars` and `--reference`).
+
+## What it checks
+
+| Stage | Reports |
+|---|---|
+| types | TypeScript errors of the script with the script globals (`TS2362` operator on a Series, `TS2551` unknown name...), when `typescript` is installed in the project; `--no-types` skips it |
+| syntax | the JavaScript syntax error and its line |
+| declaration | errors of the top-level code (the declaration run of an app), e.g. `close - open` |
+| run | errors on the bars (inside `eachBar`), with the line |
+| timeout | a run longer than `--timeout` (default 10 s) |
+| spec | an unknown key or a wrong value in the spec (`"signal"` for `"signals"`): a misspelt spec would check nothing |
+| scenario | an error on the edge-case bars of `--scenarios` |
+
+Then, on a clean run: the inputs (id, type, default, options), each plot (number of values, first bar, min / max,
+last 5 values, colours), each signal (shapes, characters, arrows, alert conditions, background and bar colours: bars,
+share, first and last bar), drawings, `alert()` calls, and for a strategy the trades (count, wins, net profit, the
+first trades) on a small built-in order engine (next-bar-open fills, stop / limit exits).
+
+## Warnings
+
+| Code | Meaning |
+|---|---|
+| `empty-plot` | a plot with no value (na on every bar) |
+| `constant-plot` | the same value on every bar (a level is an `hline()`) |
+| `late-start` | the first value after half of the bars |
+| `signal-never` | a signal that is never true |
+| `signal-everywhere` | a signal on more than half of the bars: often a Series used as a JavaScript boolean |
+| `one-colour` | per-bar colours that are the same on every bar |
+| `unused-input` | changing the input changes no output (the check runs again with each input changed) |
+| `input-error` | another valid value of the input stops the script |
+| `no-trades` | a strategy without any trade |
+| `no-output` | nothing is drawn |
+
+A warning is not always a mistake (a rare signal on 1,500 bars): read it and keep it when it is what the user wants.
+
+## The spec
+
+A JSON file; every entry is optional and only the given ones are checked. Inputs, plots and signals are found by id
+or title (case insensitive). An unknown key or a wrong value is an error (with the closest key), so a misspelt entry
+does not pass unchecked. Its JSON Schema is `node_modules/oakscriptjs/skills/oakscript/spec.schema.json`: point
+`$schema` at it to get the keys in an editor.
+
+```json
+{
+  "$schema": "./node_modules/oakscriptjs/skills/oakscript/spec.schema.json",
+  "kind": "indicator",
+  "title": "MACD Histogram",
+  "overlay": false,
+  "inputs": {
+    "fast_length": { "type": "int", "defval": 12 },
+    "Source": { "type": "source", "defval": "close" },
+    "MA type": { "options": ["SMA", "EMA"] }
+  },
+  "outputs": ["MACD", "Signal", { "title": "Zero", "kind": "hline" }],
+  "plots": { "MACD": { "warmup": 40 }, "RSI": { "min": 0, "max": 100 } },
+  "signals": { "Buy": { "min": 1, "maxShare": 0.1 } },
+  "trades": { "min": 1 },
+  "checks": "checks.js",
+  "scenarios": true,
+  "reference": "expected.csv",
+  "tolerance": 1e-10
+}
+```
+
+- `outputs`: titles that must exist; `kind` is one of `plot`, `shape`, `char`, `arrow`, `candle`, `bar`, `hline`,
+  `bgcolor`, `barcolor`, `alertcondition`.
+- `plots`: `min` / `max` bound every value, `warmup` is the latest bar of the first value.
+- `signals`: `min` / `max` count bars, `minShare` / `maxShare` the share of the bars (0 to 1).
+- `checks`, `scenarios`, `reference`, `export`, `tolerance`: as `--checks`, `--scenarios`, `--reference`, `--export`,
+  `--tolerance` (paths relative to the spec file).
+
+## Behaviour checks
+
+What a spec cannot write as counts and ranges goes in a checks file: plain JavaScript, the body of a function of `t`
+(no import or export). `t.plot(name)` gives a plot per bar (`values`, `at(i)`, `colors`), `t.signal(name)` the bars of
+a signal (`bars`, `on(i)`), `t.trades` the closed trades of a strategy, `t.input(name)` the value of an input, `t.bars`
+and `t.n` the bars. Record each check with `t.expect(name, ok, detail?)` or `t.everyBar(name, (i) => ..., { from, to })`
+(it fails on the first bar where the function is false).
+
+```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));
+t.expect("Buy right after the RSI was at or above 30", t.signal("Buy").bars.every((i) => rsi.at(i - 1) >= 30));
+```
+
+The checks run on the main run; their results come after the spec items. An error in the file (an unknown plot, a
+typo) fails the checks with its line.
+
+## Scenarios
+
+`--scenarios` (or `"scenarios": true`) runs the script again on edge-case bars: 30 bars (a short history), 800 daily
+bars, 1,000 one-minute bars, 200 flat bars (zero ranges, no volume), 500 bars without volume, and a 3-day gap. An
+error there fails the check; a plot with no value that the main run does not have is listed per scenario (on 30
+bars it is often expected, a division by a zero range is not).
+
+## Bars and reference files
+
+- `--bars`: CSV with the columns `time` (UNIX seconds or milliseconds, or a date), `open`, `high`, `low`, `close`,
+  optional `volume`; or a JSON array of `{ time, open, high, low, close, volume }`. The timeframe comes from the bar
+  spacing unless `--timeframe` gives it. Other symbols of `request.security` get synthetic bars.
+- `--reference`: CSV with a `time` column and one column per plot (id or title); empty or `na` is na. A value is
+  equal when `|a - b| <= tolerance * max(1, |a|, |b|)` (default `1e-10`) or both are na. Use the bars the reference
+  was computed on. The bar columns (`open`, `high`, `low`, `close`, `volume`) are skipped.
+- `--export`: one CSV with both: the chart data exported with the original script on the chart (a `time` column,
+  the bars, then one column per plot title, as charting apps export them). The bars are the bars of the run, the
+  other columns the expected values; a column with no plot of that title (another script on the chart) is ignored.
+
+## Other options
+
+`--inputs '{"length": 50}'` (input values by id), `--count 3000` (synthetic bars), `--timeframe D`, `--no-sweep`
+(no reruns for unused inputs), `--json` (the whole report as JSON).
+
+## From code
+
+```ts
+import { assertCheck, checkScript } from 'oakscriptjs/check';
+const report = checkScript(source, { spec, bars, scenarios: true, checks: (t) => { /* as a checks file */ } });
+// report.ok, errors, warnings, plots, signals, spec, reference, scenarios
+
+// in a test of any runner: throws the report as text when the check fails ({ warnings: false }: also on warnings)
+assertCheck(checkScript(source, { spec }));
+```
+
+`checkScript` runs anywhere (no Node API); the command adds the file lines, the time limit and the type check.

package/skills/oakscript/reference/errors.md

@@ -0,0 +1,92 @@
+# Errors and how to read them
+
+A script fails in one of three ways: it does not compile, it stops with a runtime error, or it runs and gives a
+wrong output. Fix them in that order, then check the values. `npx oakscript check script.js` ([check](check.md))
+reports all three, with the lines, and warns about the silent mistakes of the last table.
+
+## Type-check errors
+
+| Error | Cause | Fix |
+|---|---|---|
+| `TS2362` / `TS2363` `The left-hand (right-hand) side of an arithmetic operation must be of type...` | `close - open`, `rsi * 2` | Series methods: `close.sub(open)`, `rsi.mul(2)` |
+| `TS2365` `Operator '>' cannot be applied to types 'Series' and 'number'` | `rsi > 50`, `c.close > ta.sma(close, 5)` in a loop | `rsi.gt(50)`; in a loop `c.close > c.get(sma)` with `sma` computed before |
+| `TS2339` / `TS2551` `Property 'smaa' does not exist on type...` | a misspelt or Pine-only name | the name it suggests, [pine-differences.md](pine-differences.md) |
+| `TS2322` `Type '"triangel"' is not assignable to type 'ShapeStyle'` | a bad constant string | one of the strings it lists |
+| `TS2561` / `TS2353` `Object literal may only specify known properties` | a misspelt option (`colour`) | the option it suggests |
+| `TS2554` `Expected 4 arguments, but got 3` | a missing argument (`ta.stoch(close, high, low)`) | pass it: `ta.stoch(close, high, low, 14)` |
+| `TS2339` `Property 'entry_price' does not exist on type 'number'` | `strategy.opentrades.entry_price(0)` (`strategy.opentrades` is the count) | `strategy.opentrade(0)?.entry_price`, `strategy.closedtrade(i)?.profit` |
+| `TS2769` `No overload matches this call` on a drawing | a misspelt named argument (`{ textcolour: ... }`) | the Pine name (`textcolor`) |
+| `TS8010` `Type annotations can only be used in TypeScript files` | TypeScript syntax | remove the types |
+
+## Compile errors (syntax)
+
+The source is loaded as JavaScript: a syntax error comes with a line and a column of your source.
+
+| Message | Cause | Fix |
+|---|---|---|
+| `Missing initializer in const declaration`, `Unexpected token ':'` | a TypeScript annotation (`const a: number = 5`) | remove the types: the script is JavaScript |
+| `Unexpected identifier`, `Unexpected token '='` | Pine syntax: `x := 1`, `var x = 0`, `a = b ? c : d` on one line without `const`, `=>` functions, named arguments `f(a, length = 5)` | JS syntax: `x = 1`, `let x = 0`, `const a = ...`, `function f() {}`, options objects |
+| `Unexpected token 'export'` / `'import'` at a wrong place | an import below other code, an export | imports first, no exports |
+
+A host that compiles a script also runs it once on zero bars (a declaration pass: title, inputs, plots,
+strategy properties). Errors in the declarations or in top-level code show up there, with the line.
+
+## Runtime errors
+
+The run stops at the first error; the message names the call. The ones you will meet:
+
+| Message | Cause | Fix |
+|---|---|---|
+| `TypeError: JavaScript operators (+ - * / % ** < > <= >= ==) do not work on a Series: use its methods...` | an operator on a Series: `close - open`, `rsi > 50`, `fast > slow ? a : b` | the method it lists: `close.sub(open)`, `rsi.gt(50)`, `fast.gt(slow).iff(a, b)`; a colour: `color.when(fast.gt(slow), a, b)` |
+| `TypeError: A Series is not a text...` | a Series in a text: `` `RSI ${rsi}` ``, `"RSI " + rsi` | in a loop: `str.tostring(c.get(rsi))` |
+| `ta.sma() was called inside eachBar(): a ta.* call computes the whole Series at once...` | a `ta.*` function in a bar callback | compute it before the loop, read it with `c.get(x)`; a Pine call in an `if` block: `callsite.*` |
+| `TypeError: ta.smaa does not exist. Did you mean ta.sma?` (also `math.`, `str.`, `color.`, `input.`, `request.`) | a misspelt or Pine-only member | a suggested name, [pine-differences.md](pine-differences.md) |
+| `TypeError: series.toArray is not a function` | a number or NaN passed where a Series is expected: `plot(5)`, `ta.sma(c.close, 10)` | a Series; a constant level: `hline(5)` |
+| `xyz is not defined` | a global that does not exist (Pine-only name such as `shape`, `location`, `size`, `xloc`, `bar_index`) | [pine-differences.md](pine-differences.md): strings for the constants, `c.i` for `bar_index` |
+| `TypeError: Cannot read properties of undefined (reading 'toArray')` | a missing Series argument, e.g. `ta.stoch(close, high, low)` | pass it: `ta.stoch(close, high, low, 14)` |
+| `TypeError: label.new(): unknown argument "textcolour". Did you mean textcolor?` | a misspelt named argument of a drawing | the name it suggests |
+| `TypeError: input.int(): unknown argument "min". Did you mean minval?` | an input option that is not Pine's (`min`, `max`, `choices`) | Pine's name: `minval`, `maxval`, `options` |
+| `TypeError: request.security(): unknown argument "lookahed"...` | a misspelt named argument of `request.security` | `gaps`, `lookahead`, `ignore_invalid_symbol` |
+| `TypeError: label.new(): argument 1 is a Series, a drawing takes one value: call label.new() inside eachBar()...` | a drawing created at the top level with a Series (`label.new(bar_index, high)`) | create it in a bar loop |
+| `TypeError: strategy.opentrades.entry_price is not a function` | `strategy.opentrades` is the count | `strategy.opentrade(0)?.entry_price` |
+| `Error on bar N: Invalid value of the 'length' argument (0.0) in the 'sma' function. It must be > 0.` | a length of 0, negative or NaN (often an input) | `minval: 1` on the input, or guard the value |
+| `Error on bar N: The 'sma' function references too many historical candles (6000), the limit is 5000.` | a window longer than 5000 bars | a shorter length |
+| `Error on bar N: The script attempts to reference historical data that is too far from the current bar (K bars back)...` | `x.offset(k)` / `c.get(x, k)` with k above 5000, or a history that keeps growing (`c.get(x, c.i)`) | bounded offsets |
+| `c.get(): the offset cannot be negative` / `Series.offset(-1)...` | reading a future bar | offsets >= 0; for a left shift of a marker use `offset` of `plotshape` |
+| `indicator(): the script already declared indicator(); a script has one declaration.` | two declarations | one `indicator()` or `strategy()` |
+| `strategy.entry() must be called inside strategy.eachBar().` | an order at the top level | move it into `strategy.eachBar((c) => ...)` |
+| `strategy.position_size must be read inside strategy.eachBar().` | a per-bar strategy value at the top level | read it in the loop; return it from the loop to plot it |
+| `strategy.eachBar(): declare the script with strategy() first.` | `strategy.*` in an `indicator()` script | declare `strategy(...)` |
+| `strategy.eachBar() runs once per script run.` | two strategy loops | one loop with all the logic |
+| `strategy.X is not provided by the strategy engine.` | the host's engine lacks a variable or a risk rule | use another value, or ask the host |
+| `request.security(): the expression returned a series computed on the chart bars...` | `request.security("", "D", () => myEma)` | compute inside: `() => ta.ema(close, 20)` |
+| `request.security needs the bars of X (D): pass them with ChartContext.bars.` (`MissingSymbolDataError`) | another symbol whose bars the host has not loaded | an app loads them and runs again; in your own host give `bars()` |
+| `Invalid symbol: X` | a symbol without bars | check the ticker id, or `ignore_invalid_symbol = true` |
+| `Invalid timeframe "XYZ"` | a bad timeframe string | `"1"`, `"60"`, `"240"`, `"D"`, `"W"`, `"M"`... |
+| `request.security_lower_tf: timeframe "D" is higher than the chart timeframe "60".` | `security_lower_tf` on a higher timeframe | `request.security` for higher timeframes |
+| `The chart timeframe is not known: pass it as executeScript(body, bars, inputs, { timeframe }).` (also time zone, session, `syminfo.*`) | a direct `executeScript` call without the chart context | pass `{ timeframe, timezone, session, ... }`; an app gives them |
+| `chart.point.now() needs a current bar: call it inside eachBar().` | a per-bar call at the top level | call it in a bar loop |
+| `oakscriptjs/script functions can only run inside executeScript()` | a script API call outside a run (e.g. from a timer, or a Node module that calls `plot` at import) | only the host runs the body |
+| `Script did not finish within Ns and was stopped.` (app) | an endless or very slow loop | bound the loops, compute Series outside the bar loops |
+
+## Silent mistakes (no error, wrong output)
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| a branch taken on every bar | `if (ta.crossover(a, b))`, `cond ? x : y`, `!cond`, `cond && x` with a Series `cond`: an object is always true | `cond.iff(x, y)`, `cond.not()`, `cond.and(x)`, or `c.get(cond) === 1` in a loop |
+| one colour on every bar | `color: cond ? color.green : color.red` with a Series `cond` | `color.when(cond, color.green, color.red)` |
+| an empty plot | NaN on every bar: a division by zero, a NaN input | guard divisions (`range.gt(0).iff(x.div(range), 0)`) |
+| a plot that starts late | the warm-up of long lengths, or of a higher timeframe (20 daily bars on an hourly chart is 480 bars) | expected; shorter lengths or more bars |
+| values that look like the future (backtests too good) | `barmerge.lookahead_on` on a series that is not offset | lookahead off, or `.offset(1)` inside the expression |
+| a strategy without trades | conditions read as `c.get(cond)` on NaN-only Series, orders placed outside the conditions you expect, `pyramiding: 0` blocking a second entry in the same direction | plot the conditions (`plotshape`) and check them first |
+| `na(series)` / `nz(series)` has no effect | they take numbers | in a loop on `c.get(x)`, or `x.iff(x, 0)` |
+| an input never changes the output | the input value is not used, or its title changed (new id) | use the returned value; keep titles stable |
+
+## Checking the output
+
+After a clean run, read the values instead of trusting the code:
+
+- the last values of each plot (`run.result.plots.plot0.slice(-5)` in a direct call; the app shows them in the
+  data window and the legend);
+- the number of markers / labels (a signal on every bar, or none, is a bug);
+- for a strategy, the trade count and a few trades (entry and exit bars and prices).