openalgo-script 0.2.0 → 0.5.0

package/src/adapters/charts/venue.ts

@@ -0,0 +1,132 @@
+/**
+ * The destination a strategy runs against when a chart draws one.
+ *
+ * **Why a chart needs one at all.** A strategy asks a destination to do things
+ * and folds its position from what comes back. Handed no destination it is
+ * refused at load with OS6006, and handed one that answers nothing it runs but
+ * never learns it is in a position: every `close()` closes nothing, every entry
+ * is allowed again on the next signal, and the study draws a strategy that is
+ * wrong about itself while looking entirely normal. Measured on a stop and
+ * reverse script, that shape produced five buys and no sells.
+ *
+ * **It is the backtest's own venue, not a second one.** `Simulator` is what
+ * `backtest()` runs against, so a chart running a strategy through it fills the
+ * same orders at the same prices as the report the trader ran a moment ago. A
+ * venue written here to be simpler would be a second answer to "what would this
+ * have filled at", and the two would disagree the first time either changed:
+ * the chart would draw one set of trades and the report would list another.
+ *
+ * **What a chart supplies and what it invents.** The bars, the instrument and
+ * the declaration are the chart's own and are passed through. Money is not: a
+ * chart draws a strategy, it does not report one, so the currency, the point
+ * value and the rounding are stated here as the neutral values that make the
+ * accounting a no-op. Nothing a chart draws reads them, and a chart that
+ * guessed a point value would put a wrong profit in front of somebody.
+ *
+ * **Nothing here decides when a fill happens.** The declaration does, through
+ * `fillOn`, and the venue reads it. A market order priced at the next bar's
+ * open is known at that open; one that rested and traded inside a bar is known
+ * once the bar is complete. Both are what a venue could have told anybody at
+ * the time, and that is the whole reason the frames arrive between bars rather
+ * than inside the execution that sent them.
+ */
+
+import { DEFAULT_FILL, Simulator, declarationOf } from '../../core/backtest/index.js';
+import type { RecordedBar } from '../../core/backtest/index.js';
+import type { CompiledProgram } from '../../core/emit/index.js';
+import type { Instrument, OrderFrame, ResolvedInput, RoutedEffect } from '../../core/engine/index.js';
+import type { ChartBar } from './contract.js';
+
+/**
+ * Whether this program needs a destination before it can run at all.
+ *
+ * Read from the program's own declared capabilities rather than from whether
+ * its source said `strategy()`, because `requires` is the same fact the engine
+ * tests at load. A strategy that places no orders needs none, and anything that
+ * does need one is refused without it.
+ */
+export function needsVenue(program: CompiledProgram): boolean {
+  return program.requires.includes('orders');
+}
+
+/** One chart bar as the venue reads it. */
+function recorded(bar: ChartBar): RecordedBar {
+  return {
+    time: bar.time,
+    open: bar.open,
+    high: bar.high,
+    low: bar.low,
+    close: bar.close,
+    volume: bar.volume ?? null,
+    oi: bar.oi ?? null,
+  };
+}
+
+/**
+ * The venue for one chart run, or nothing where the program does not need one.
+ *
+ * `inputs` are the ones the engine resolved at load, because a declaration
+ * field may be written as an `input()`: a script whose `fillOn` comes from a
+ * setting would otherwise be filled the way its source happened to be written
+ * rather than the way the trader is running it.
+ */
+export function venueFor(
+  program: CompiledProgram,
+  bars: readonly ChartBar[],
+  inputs: readonly ResolvedInput[],
+  instrument: Instrument | undefined,
+): Simulator | null {
+  if (!needsVenue(program)) return null;
+
+  const declared = declarationOf(program, inputs);
+
+  return new Simulator({
+    bars: bars.map(recorded),
+    contract: {
+      symbol: instrument?.symbol ?? null,
+      exchange: instrument?.exchange ?? null,
+      // Neutral money. A chart draws a strategy and does not report one, so
+      // nothing it puts on screen reads these; stating a point value a host
+      // never gave would be inventing the size of somebody's position.
+      currency: declared.currency,
+      tickSize: instrument?.tickSize ?? null,
+      lotSize: null,
+      pointValue: 1,
+      digits: 2,
+    },
+    fill: DEFAULT_FILL,
+    // The declaration's own, so slippage is applied the way the backtest
+    // applies it. Ticks, against the instrument's tick size.
+    slippageTicks: declared.slippage,
+    fillOn: declared.fillOn,
+    qtyType: declared.qtyType,
+  });
+}
+
+/**
+ * A venue that can be asked for frames, held across a chart's recomputes.
+ *
+ * The bars a `Simulator` prices against are the ones it was built with, so a
+ * chart that has grown a bar needs a venue that knows about it. `extend` is how
+ * the tail path says so without rebuilding the orders it is already holding.
+ */
+export interface HeldVenue {
+  readonly venue: Simulator;
+  /** Frames the venue answered for a bar, waiting to be delivered before the next. */
+  pending: readonly OrderFrame[];
+}
+
+/** What a venue has to say after one bar, which the next bar's engine reads. */
+export function answersFor(held: HeldVenue, barIndex: number): void {
+  held.pending = held.venue.framesFor(barIndex);
+}
+
+/** The route an engine is loaded with, pointing at a venue built after it. */
+export function routeInto(holder: { current: Simulator | null }): (effect: RoutedEffect, bar: number) => void {
+  // Late bound on purpose. The route is handed to `load`, and the venue cannot
+  // be built until `load` has resolved the inputs the declaration reads. The
+  // route is only ever called from inside an execution, which is after both.
+  return (effect: RoutedEffect, bar: number) => {
+    holder.current?.route(effect, bar);
+  };
+}

package/src/adapters/codemirror/commands.ts

@@ -0,0 +1,53 @@
+/**
+ * Laying a script out again, as an editor command.
+ *
+ * `format` is the tier's, and the guarantee it carries is the one that makes a
+ * format button safe to put in front of somebody holding a position: laying a
+ * script out again cannot change what it computes. Every example and every gate
+ * script in the repository is formatted, both texts compiled, and the compiled
+ * programs compared field for field; and every call checks itself against the
+ * lexer, so a rule that is wrong returns the source untouched rather than a
+ * changed program.
+ *
+ * The whole document is replaced rather than a minimal edit computed. It is the
+ * honest version: a diff would have to be trusted to be equivalent to the
+ * replacement, and a formatter that moved a line somewhere unintended would do
+ * it silently. The cursor is kept where it was in the new text, clamped, because
+ * a format that sends the caret to the top of the file is a format nobody
+ * presses twice.
+ *
+ * **A document with two character line endings comes back with one character
+ * ones**, because that is what `language.md` 3.1 normalises a file to before
+ * anything reads it and what every offset in this tier indexes. It is the one
+ * change to a file's bytes that formatting makes without being asked, and it is
+ * recorded in `spec/editor-narrowings.json`.
+ */
+import { format } from '../../editor/index.js';
+import type { EditorView } from './contract.js';
+import { documentOf, normalisedOffset } from './positions.js';
+
+/**
+ * Lays the document out again, and says whether anything changed.
+ *
+ * ```ts
+ * keymap.of([{ key: "Shift-Alt-f", run: formatDocument }])
+ * ```
+ *
+ * False where the document is already laid out, which is what an editor command
+ * returns when it has nothing to do: the key press then falls through to
+ * whatever else is bound to it rather than being swallowed.
+ */
+export function formatDocument(view: EditorView): boolean {
+  const raw = view.state.doc.toString();
+  const held = documentOf(raw);
+  const laid = format(held.text);
+  if (laid === raw) return false;
+
+  const at = normalisedOffset(held, view.state.selection.main.head);
+  view.dispatch({
+    changes: { from: 0, to: view.state.doc.length, insert: laid },
+    selection: { anchor: Math.min(at, laid.length) },
+    scrollIntoView: true,
+  });
+  return true;
+}

package/src/adapters/codemirror/completion.ts

@@ -0,0 +1,74 @@
+/**
+ * Completions, as the editor's completion source.
+ *
+ * The whole of the work is done by `complete`, which reads the standard library
+ * manifest, the checker's bindings and the error catalogue. What is here is the
+ * translation: the editor wants a range to replace, a list of rows, and a note
+ * about whether the list is already filtered.
+ *
+ * **The list is already filtered**, by the word the writer has typed, compared
+ * exactly, because the language's names are case sensitive. So `filter` is false
+ * and the editor is told not to filter it again: its own matcher is fuzzy and
+ * case insensitive, and running it over a list that has already answered the
+ * question would put `EMA` in front of somebody as though it compiled.
+ *
+ * **A planned call is shown and marked.** `complete` carries the catalogue's own
+ * OS2020 sentence on a planned row, so that is what goes in the row's expanded
+ * note, and the row is pushed to the bottom of the list with the editor's own
+ * boost. A host that would rather not show them at all drops them with one
+ * field, which is why they are marked rather than filtered here.
+ */
+import { complete } from '../../editor/index.js';
+import type { Completion } from '../../editor/index.js';
+import type {
+  EditorCompletion,
+  EditorCompletionContext,
+  EditorCompletionResult,
+} from './contract.js';
+import { COMPLETION_TYPES } from './tokens.js';
+
+/** As far down the list as the editor will move a row. */
+const PLANNED_BOOST = -99;
+
+function rowOf(one: Completion): EditorCompletion {
+  const info = one.refusal ?? one.summary;
+  const type = COMPLETION_TYPES[one.kind];
+  return {
+    label: one.label,
+    ...(type === undefined ? {} : { type }),
+    detail: one.detail,
+    ...(info === undefined ? {} : { info }),
+    ...(one.insert === one.label ? {} : { apply: one.insert }),
+    ...(one.planned ? { boost: PLANNED_BOOST } : {}),
+  };
+}
+
+/**
+ * Every completion for the position the editor is asking about.
+ *
+ * ```ts
+ * autocompletion({ override: [openscriptCompletion] })
+ * ```
+ *
+ * Nothing comes back for an empty list rather than an empty list, because the
+ * editor reads the two differently: an empty result closes the panel and null
+ * lets another source answer, and a host with a snippet source of its own should
+ * keep it.
+ */
+export function openscriptCompletion(
+  context: EditorCompletionContext,
+): EditorCompletionResult | null {
+  const rows = complete(context.state.doc.toString(), context.pos);
+  // The first row carries the range every row replaces, so an empty list and a
+  // list whose first row is missing are one answer: nothing. Two guards for that
+  // would be one guard and a line no test can reach.
+  const first = rows[0];
+  if (first === undefined) return null;
+
+  return {
+    from: first.replace.offset,
+    to: first.replace.offset + first.replace.length,
+    options: rows.map(rowOf),
+    filter: false,
+  };
+}

package/src/adapters/codemirror/contract.ts

@@ -0,0 +1,156 @@
+/**
+ * The editor component's own shapes, as this adapter targets them.
+ *
+ * **Why they are declared here rather than imported.** The editor component is a
+ * peer dependency: a host that wants a text area installs it, and a host that
+ * wants only the language must not be made to. This repository therefore does
+ * not install it, cannot type check against it, and would fail its own layering
+ * check the moment a file here imported it. It is the same decision the chart
+ * adapter took, for the same reason, and `src/adapters/charts/contract.ts` says
+ * it at length.
+ *
+ * So the shapes this produces values for are declared below and the host's own
+ * build is where the two meet. Each one is a one line check that costs a host
+ * nothing and fails to compile if this file has drifted:
+ *
+ * ```ts
+ * import type { StreamParser } from "<the editor's language package>";
+ * import type { CompletionSource } from "<the editor's completion package>";
+ * import type { Diagnostic } from "<the editor's lint package>";
+ *
+ * const parser: StreamParser<unknown> = openscriptStream;
+ * const source: CompletionSource = openscriptCompletion;
+ * const linter: (view: EditorView) => Diagnostic[] = openscriptLint;
+ * ```
+ *
+ * **That line catches a value of the wrong shape and not an argument of the
+ * wrong shape.** A method's parameters are compared in both directions, so a
+ * hook declared here as taking something the editor never passes still assigns.
+ * That is the failure the chart adapter has actually made, so every member below
+ * takes the editor's own argument, spelled as the editor spells it, and every
+ * test drives each one with the argument the editor passes rather than with one
+ * of its own.
+ *
+ * **A style name is not checked by any of those lines.** The names this adapter
+ * returns from `token` are looked up by the editor in its own table of
+ * highlighting tags at run time, and an unknown one is a warning on a console
+ * rather than a compile error. That is why the whole mapping is one exported
+ * record a host can replace in a line, and why it is recorded in
+ * `spec/editor-narrowings.json` as the one thing here a type cannot hold.
+ */
+
+/**
+ * One line of the document, as the editor's tokenizer sees it.
+ *
+ * The editor hands a tokenizer a line at a time and expects `pos` to have moved
+ * forward when `token` returns. Only the members this adapter reads are
+ * declared: a narrower shape is still assignable from the editor's wider one.
+ */
+export interface EditorStringStream {
+  /** The line's text, without its line ending. */
+  readonly string: string;
+  /** Where the tokenizer has got to, which this adapter moves. */
+  pos: number;
+  /** Where the current token began. */
+  readonly start: number;
+  /** Whether `pos` is at the end of the line. */
+  eol(): boolean;
+  /** Whether `pos` is at the start of the line. */
+  sol(): boolean;
+}
+
+/**
+ * A tokenizer the editor drives one line at a time.
+ *
+ * `token` returns a style name, or null for text with no style of its own. The
+ * state is the tokenizer's to define, and the editor copies it at line
+ * boundaries so that it can restart mid document, which is why `copyState` is
+ * here.
+ */
+export interface EditorStreamParser<State> {
+  readonly name?: string;
+  startState?(indentUnit: number): State;
+  token(stream: EditorStringStream, state: State): string | null;
+  copyState?(state: State): State;
+  blankLine?(state: State, indentUnit: number): void;
+  readonly languageData?: Readonly<Record<string, unknown>>;
+}
+
+/** The document, which the editor holds as a rope rather than as a string. */
+export interface EditorText {
+  readonly length: number;
+  toString(): string;
+}
+
+/** The part of the editor's state this adapter reads. */
+export interface EditorState {
+  readonly doc: EditorText;
+  readonly selection: {
+    readonly main: { readonly head: number; readonly from: number; readonly to: number };
+  };
+}
+
+/** The part of the editor's view this adapter reads and dispatches to. */
+export interface EditorView {
+  readonly state: EditorState;
+  dispatch(transaction: {
+    readonly changes: { readonly from: number; readonly to: number; readonly insert: string };
+    readonly selection?: { readonly anchor: number };
+    readonly scrollIntoView?: boolean;
+  }): void;
+}
+
+/** What the editor hands a completion source. */
+export interface EditorCompletionContext {
+  readonly state: EditorState;
+  readonly pos: number;
+  /** Whether the writer asked for completions rather than merely typing. */
+  readonly explicit: boolean;
+}
+
+/** One row of the editor's completion list. */
+export interface EditorCompletion {
+  readonly label: string;
+  /** The editor's own name for the icon beside a row. */
+  readonly type?: string;
+  readonly detail?: string;
+  readonly info?: string;
+  /** The text to insert, where it differs from the label. */
+  readonly apply?: string;
+  /** Moves a row up or down the list, from -99 to 99. */
+  readonly boost?: number;
+}
+
+export interface EditorCompletionResult {
+  readonly from: number;
+  readonly to?: number;
+  readonly options: readonly EditorCompletion[];
+  /** False when the list is already filtered, which this adapter's is. */
+  readonly filter?: boolean;
+}
+
+/** One squiggle in the editor's lint panel and gutter. */
+export interface EditorDiagnostic {
+  readonly from: number;
+  readonly to: number;
+  readonly severity: 'hint' | 'info' | 'warning' | 'error';
+  readonly message: string;
+  /** Where the diagnostic came from, shown beside the message. */
+  readonly source?: string;
+  readonly actions?: readonly {
+    readonly name: string;
+    apply(view: EditorView, from: number, to: number): void;
+  }[];
+}
+
+/** What the editor shows over the text, and the element it shows. */
+export interface EditorTooltipView {
+  readonly dom: unknown;
+}
+
+export interface EditorTooltip {
+  readonly pos: number;
+  readonly end?: number;
+  readonly above?: boolean;
+  create(view: EditorView): EditorTooltipView;
+}

package/src/adapters/codemirror/index.ts

@@ -0,0 +1,66 @@
+/**
+ * The editor adapter: the language intelligence, wired into a text component.
+ *
+ * This and the chart adapter are the only modules in the repository allowed to
+ * know two worlds at once, and it is the piece a platform with its own editor
+ * replaces rather than the piece it patches. Everything under `src/editor` stays
+ * ignorant of any component, and the layering check is what keeps it that way.
+ *
+ * **The editor component is a peer dependency, and nothing here imports it.** A
+ * package that pulled a text component into everyone's install would defeat the
+ * point of a language a platform can take on its own, so the shapes this
+ * produces are declared in `contract.ts` and the host's own build is where the
+ * two are compared, in one line per piece. See that file for the lines. The
+ * entry point resolves and every function here runs in an install that holds no
+ * editor at all, which `scripts/check-entry-points.mjs` proves on every build.
+ *
+ * Six functions in, five pieces out:
+ *
+ *     openscriptStream             highlighting, a line at a time
+ *     openscriptCompletion         the completion list
+ *     openscriptLint               errors as you type, with their fixes
+ *     openscriptHoverTooltip       what the thing under the pointer is
+ *     openscriptSignatureTooltip   the call being written
+ *     formatDocument               lay the script out again
+ *
+ * The two tooltips take the markup as a parameter and have no default for it, so
+ * nothing in this package names a browser global at any tier. A host that wants
+ * none of this calls the six functions itself and draws its own. That is not the fallback, it is the supported path: what a host gives up
+ * by taking these instead is recorded in `spec/editor-narrowings.json`, which is
+ * three lines long and worth reading before choosing.
+ */
+export type {
+  EditorCompletion,
+  EditorCompletionContext,
+  EditorCompletionResult,
+  EditorDiagnostic,
+  EditorState,
+  EditorStreamParser,
+  EditorStringStream,
+  EditorText,
+  EditorTooltip,
+  EditorTooltipView,
+  EditorView,
+} from './contract.js';
+
+export { COMPLETION_TYPES, HIGHLIGHT_TOKENS } from './tokens.js';
+
+export type { StreamState } from './stream.js';
+export { openscriptStream } from './stream.js';
+
+export { openscriptCompletion } from './completion.js';
+
+export { diagnosticsFor, openscriptLint } from './lint.js';
+
+export type { Renderer } from './tooltips.js';
+export {
+  hoverLines,
+  openscriptHoverTooltip,
+  openscriptSignatureTooltip,
+  signatureLines,
+} from './tooltips.js';
+
+export { formatDocument } from './commands.js';
+
+export type { Document } from './positions.js';
+export { documentOf, normalisedOffset } from './positions.js';

package/src/adapters/codemirror/lint.ts

@@ -0,0 +1,66 @@
+/**
+ * Errors as you type, as the editor's linter.
+ *
+ * The diagnostics are the compiler's own, whole: `diagnose` runs the lexer, the
+ * parser, the checker and the emitter, so what a writer sees beside their line
+ * is exactly what a compile produces and nothing new can appear when they press
+ * apply. Every message and every fix came from the error catalogue that the
+ * documentation site is generated from.
+ *
+ * Three decisions worth stating, because each one is visible to a trader.
+ *
+ * **The fix is shown.** A `Diagnostic` carries a message saying what is wrong and
+ * a fix saying what to do, and the fix is the half that is worth reading. The
+ * editor's panel shows one string, so the two are joined with a line break
+ * rather than the fix being dropped.
+ *
+ * **The code is the source.** The editor shows a diagnostic's source beside its
+ * message, and a code is the one part of a diagnostic this project promises never
+ * to change, so it is what a trader quotes and what a support page is indexed by.
+ *
+ * **A zero width span is widened by one character.** The compiler points at a
+ * position for a mistake that is an absence, a missing bracket among them, and a
+ * squiggle of no width is a squiggle nobody sees.
+ */
+import { endOffset } from '../../core/index.js';
+import type { Diagnostic } from '../../core/index.js';
+import { diagnose } from '../../editor/index.js';
+import type { EditorDiagnostic, EditorView } from './contract.js';
+import { documentOf } from './positions.js';
+
+/** What the editor prints beside a message, which is the code and nothing else. */
+function sourceOf(one: Diagnostic): string {
+  return one.code;
+}
+
+/** Every diagnostic of a document, in the editor's own shape. */
+export function diagnosticsFor(raw: string): readonly EditorDiagnostic[] {
+  const held = documentOf(raw);
+  return diagnose(held.text).map((one) => {
+    const from = held.at(one.span.offset);
+    const to = held.at(endOffset(one.span));
+    return {
+      from,
+      to: to > from ? to : from + 1,
+      severity: one.severity,
+      message: `${one.message}\n${one.fix}`,
+      source: sourceOf(one),
+    };
+  });
+}
+
+/**
+ * The linter a host wires in one line.
+ *
+ * ```ts
+ * linter(openscriptLint)
+ * ```
+ *
+ * It is synchronous because it is fast enough to be: a finished ninety line
+ * study compiles in a third of a millisecond and the same file with a bracket
+ * left open in about a millisecond, both with a budget in the benchmark suite.
+ * The editor's own linter already debounces, so nothing here does it twice.
+ */
+export function openscriptLint(view: EditorView): readonly EditorDiagnostic[] {
+  return diagnosticsFor(view.state.doc.toString());
+}

package/src/adapters/codemirror/positions.ts

@@ -0,0 +1,79 @@
+/**
+ * Offsets, translated between the document the editor holds and the text the
+ * compiler read.
+ *
+ * `language.md` 3.1 normalises a file before anything reads it: a byte order
+ * mark is dropped and every CRLF becomes LF. Every span the compiler produces
+ * therefore indexes the normalised text, which `docs/integrating/the-editor-half.md`
+ * tells a host plainly and expects it to handle.
+ *
+ * A drop-in cannot expect it. A document written on a machine that ends its
+ * lines with two characters is an ordinary document, the editor holds it exactly
+ * as it is, and an adapter that handed the editor a span from the normalised
+ * text would put every squiggle on a file's fiftieth line fifty characters to
+ * the left. That is the kind of defect that is reported as "the underline is in
+ * the wrong place" and survives for months.
+ *
+ * So the two are mapped. The map is built only when the document is not already
+ * normalised, which is the common case and costs a comparison; when it is built
+ * it is one walk of the text.
+ */
+import { normaliseSource } from '../../core/index.js';
+
+const BYTE_ORDER_MARK = 0xfeff;
+const CARRIAGE_RETURN = 13;
+const LINE_FEED = 10;
+
+/** The document as the compiler reads it, and where each of its offsets sits. */
+export interface Document {
+  /** The normalised text: what `diagnose`, `complete` and the rest are given. */
+  readonly text: string;
+  /**
+   * The offset in the editor's own document that a normalised offset names.
+   *
+   * The identity where the document is already normalised, which is what a
+   * document written on a machine that ends its lines with one character is.
+   */
+  at(offset: number): number;
+}
+
+export function documentOf(raw: string): Document {
+  const text = normaliseSource(raw);
+  if (text === raw) return { text, at: (offset) => offset };
+
+  // One entry per normalised offset, plus the one past its end, so that the end
+  // of a span at the end of the file maps as readily as its start.
+  const map = new Array<number>(text.length + 1);
+  let normalised = 0;
+  let held = raw.charCodeAt(0) === BYTE_ORDER_MARK ? 1 : 0;
+
+  while (normalised <= text.length) {
+    map[normalised] = held;
+    if (normalised === text.length) break;
+    if (raw.charCodeAt(held) === CARRIAGE_RETURN && raw.charCodeAt(held + 1) === LINE_FEED) {
+      held += 1;
+    }
+    held += 1;
+    normalised += 1;
+  }
+
+  return {
+    text,
+    at: (offset) => map[Math.min(Math.max(offset, 0), text.length)] ?? offset,
+  };
+}
+
+/** The normalised offset an editor offset names, which is the other direction. */
+export function normalisedOffset(held: Document, raw: number): number {
+  // Walked rather than inverted, because the inverse of the map above is only
+  // needed at one position per call and building a second array to answer one
+  // question would cost a file's length for a comparison's worth of work.
+  let low = 0;
+  let high = held.text.length;
+  while (low < high) {
+    const middle = (low + high + 1) >> 1;
+    if (held.at(middle) <= raw) low = middle;
+    else high = middle - 1;
+  }
+  return low;
+}