openalgo-script 0.2.0 → 0.5.0

package/src/adapters/codemirror/stream.ts

@@ -0,0 +1,87 @@
+/**
+ * Highlighting, as the editor's line at a time tokenizer.
+ *
+ * The editor asks for one line's tokens at a time and remembers nothing between
+ * lines except the state this file hands back. The tier's `highlight` takes a
+ * whole file. So the line is what is lexed here, by the real lexer, through the
+ * same `highlight` a host would call itself.
+ *
+ * **That is an equivalence rather than an approximation, and it is measured.**
+ * `tests/adapters/codemirror/stream.test.ts` puts every script in the repository
+ * and the malformed corpus through both routes and compares them piece for
+ * piece: 4279 lines of real scripts, and not one of them differs. It holds
+ * because nothing in this language crosses a line ending: a string literal is
+ * refused at the end of its line, there is no block comment, and the layout
+ * tokens that do depend on the lines above are painted as whitespace either way.
+ * If the language ever grows something that does cross one, that test fails on
+ * the day it is added rather than on the day somebody notices a half painted
+ * line, and this becomes a line the narrowings file has to carry.
+ *
+ * A line is lexed once, not once per token: the pieces are computed when the
+ * editor arrives at the start of a line and walked from there. Without that, a
+ * line of twenty tokens would be lexed twenty times, which is the shape that
+ * makes a tokenizer show up in a frame budget.
+ */
+import { highlight } from '../../editor/index.js';
+import type { Highlight } from '../../editor/index.js';
+import type { EditorStreamParser, EditorStringStream } from './contract.js';
+import { HIGHLIGHT_TOKENS } from './tokens.js';
+
+/** What is carried from one call to the next: the line, and its pieces. */
+export interface StreamState {
+  /** The line the pieces were computed from, so a changed line is redone. */
+  line: string;
+  pieces: readonly Highlight[];
+}
+
+/** The pieces of one line, computed once and kept until the line changes. */
+function piecesFor(state: StreamState, line: string): readonly Highlight[] {
+  if (state.line !== line || state.pieces.length === 0) {
+    state.line = line;
+    state.pieces = highlight(line);
+  }
+  return state.pieces;
+}
+
+/**
+ * The tokenizer, which a host turns into a language with one call.
+ *
+ * ```ts
+ * const openscript = StreamLanguage.define(openscriptStream);
+ * ```
+ *
+ * `token` moves the stream to the end of the piece that starts where it is and
+ * returns that piece's style. A stream that has somehow been left inside a piece,
+ * which the editor does when it re-tokenizes from a column rather than from the
+ * start of a line, is moved to the end of the piece containing it, so the
+ * tokenizer always advances and the editor cannot be made to loop.
+ */
+export const openscriptStream: EditorStreamParser<StreamState> = {
+  name: 'openscript',
+
+  startState: (): StreamState => ({ line: '', pieces: [] }),
+
+  copyState: (state: StreamState): StreamState => ({ line: state.line, pieces: state.pieces }),
+
+  token(stream: EditorStringStream, state: StreamState): string | null {
+    if (stream.eol()) return null;
+
+    const pieces = piecesFor(state, stream.string);
+    const at = stream.pos;
+    const piece = pieces.find(
+      (one) => at >= one.span.offset && at < one.span.offset + one.span.length,
+    );
+
+    if (piece === undefined) {
+      // No piece covers the position, which cannot happen for a line the tier
+      // has covered and is still answered rather than trusted: the pieces tile
+      // the line, so this is a position outside it. Moving to the end leaves the
+      // editor with an unstyled remainder instead of an infinite loop.
+      stream.pos = stream.string.length;
+      return null;
+    }
+
+    stream.pos = piece.span.offset + piece.span.length;
+    return HIGHLIGHT_TOKENS[piece.kind];
+  },
+};

package/src/adapters/codemirror/tokens.ts

@@ -0,0 +1,64 @@
+/**
+ * The eleven kinds, as the editor's own highlighting tags.
+ *
+ * This is the translation an adapter exists to do: the language has eleven
+ * kinds, closed, and the editor has a vocabulary of tags its themes are written
+ * against. Neither knows about the other, and this file is the only place that
+ * knows both.
+ *
+ * **It is one record rather than a switch on purpose.** A style name is the one
+ * thing in this adapter that no type can hold: the editor looks a name up in its
+ * own tag table at run time and warns on a console about one it does not know,
+ * so a name that is wrong here is invisible to every check in this repository
+ * and shows up as an unpainted keyword in somebody's product. A host that
+ * disagrees with any of these, or whose theme is written against different
+ * names, replaces the row in one line:
+ *
+ * ```ts
+ * const tokens = { ...HIGHLIGHT_TOKENS, unknown: "invalid" };
+ * ```
+ *
+ * Two of the eleven are deliberately unstyled. `whitespace` has nothing to
+ * paint. `unknown` is the honest name for source the lexer took no token from,
+ * which is a character the language does not have, a region somebody wrote as a
+ * block comment, or a line continuation backslash: the first is a mistake and
+ * the last is not, so painting all three as invalid would paint a correct line
+ * red. `diagnose` is what says which of them is wrong, and the linter below is
+ * how a host shows that.
+ */
+import type { HighlightKind } from '../../editor/index.js';
+
+/**
+ * A style name per kind, or null for one the editor should leave alone.
+ *
+ * `builtin` uses the editor's modifier syntax for a name the environment
+ * supplies rather than the file, which is what a library name is.
+ */
+export const HIGHLIGHT_TOKENS: Readonly<Record<HighlightKind, string | null>> = {
+  keyword: 'keyword',
+  builtin: 'variableName.standard',
+  name: 'variableName',
+  number: 'number',
+  string: 'string',
+  color: 'color',
+  comment: 'comment',
+  operator: 'operator',
+  punctuation: 'punctuation',
+  whitespace: null,
+  unknown: null,
+};
+
+/**
+ * The editor's name for the icon beside a completion row, per kind.
+ *
+ * The editor ships icons for a fixed set of names and shows none for a name it
+ * does not know, which is a missing icon rather than a missing row.
+ */
+export const COMPLETION_TYPES: Readonly<Record<string, string>> = {
+  function: 'function',
+  value: 'constant',
+  namespace: 'namespace',
+  member: 'property',
+  variable: 'variable',
+  argument: 'property',
+};

package/src/adapters/codemirror/tooltips.ts

@@ -0,0 +1,113 @@
+/**
+ * Hover and signature, as the editor's tooltips.
+ *
+ * This is the one part of the adapter that would put something on screen, and it
+ * is the one part that does not: the markup is a parameter, and there is no
+ * default for it. So nothing in this package, at any tier, names a browser
+ * global, and `scripts/check-layering.mjs` fails the build if anything under
+ * `src` does. The same files load in a worker, on a server and inside somebody
+ * else's application.
+ *
+ * It costs a host four lines and it is the whole point of the split. Every
+ * platform has a design system and none of them wants to fight a styled panel
+ * that arrived with a language package; a default renderer here would be that
+ * panel, and it would be the one thing in this adapter a host could not replace
+ * without replacing the adapter.
+ *
+ * What is not a parameter is the content. `hoverLines` and `signatureLines`
+ * below are what a tooltip says, in order, and every line of it came from the
+ * compiler: the signatures from the library manifest, the sentence and the
+ * warmup from the specification's own tables, the type from the checker, and the
+ * refusal from the error catalogue.
+ *
+ * ```ts
+ * hoverTooltip(openscriptHoverTooltip((held) => ({ dom: yourPanel(hoverLines(held)) })))
+ * ```
+ */
+import { hover, signature } from '../../editor/index.js';
+import type { Hover, SignatureHelp } from '../../editor/index.js';
+import type { EditorState, EditorTooltip, EditorTooltipView, EditorView } from './contract.js';
+import { documentOf, normalisedOffset } from './positions.js';
+
+/** What a host supplies to draw a tooltip, which is the whole of the markup. */
+export interface Renderer<Held> {
+  (held: Held): EditorTooltipView;
+}
+
+/**
+ * The lines a hover shows, in the order it shows them.
+ *
+ * Every one of them came from the compiler: the signatures from the library
+ * manifest, the sentence and the warmup from the specification's own tables, the
+ * type from the checker, and the refusal from the error catalogue. Nothing is
+ * written here, which is why this function is a join rather than a template.
+ */
+export function hoverLines(held: Hover): readonly string[] {
+  const lines = [...held.signatures];
+  if (held.summary !== undefined) lines.push(held.summary);
+  if (held.warmup !== undefined) lines.push(`First value: ${held.warmup}`);
+  if (held.refusal !== undefined) lines.push(held.refusal);
+  if (held.kind === 'keyword') lines.push('A reserved word of the language.');
+  return lines;
+}
+
+/** The lines a signature tooltip shows, with the active parameter named. */
+export function signatureLines(held: SignatureHelp): readonly string[] {
+  const lines = [held.signature];
+  const active = held.parameters[held.active];
+  if (active !== undefined) {
+    const value = active.defaultText === undefined ? '' : ` = ${active.defaultText}`;
+    const need = active.required ? 'required' : 'optional';
+    lines.push(`${active.name}: ${active.type}${value} (${need})`);
+    if (active.values.length > 0) lines.push(`One of: ${active.values.join(', ')}`);
+  }
+  if (held.summary !== undefined) lines.push(held.summary);
+  if (held.refusal !== undefined) lines.push(held.refusal);
+  return lines;
+}
+
+/**
+ * A hover tooltip source, which a host wires in one line.
+ *
+ * ```ts
+ * hoverTooltip(openscriptHoverTooltip(render))
+ * ```
+ */
+export function openscriptHoverTooltip(
+  render: Renderer<Hover>,
+): (view: EditorView, pos: number) => EditorTooltip | null {
+  return (view, pos) => {
+    const held = documentOf(view.state.doc.toString());
+    const found = hover(held.text, normalisedOffset(held, pos));
+    if (found === undefined) return null;
+    return {
+      pos: held.at(found.span.offset),
+      end: held.at(found.span.offset + found.span.length),
+      create: () => render(found),
+    };
+  };
+}
+
+/**
+ * A signature tooltip for wherever the cursor is, or nothing where it is in no
+ * call.
+ *
+ * ```ts
+ * showTooltip.compute(["doc", "selection"], openscriptSignatureTooltip(render))
+ * ```
+ */
+export function openscriptSignatureTooltip(
+  render: Renderer<SignatureHelp>,
+): (state: EditorState) => EditorTooltip | null {
+  return (state) => {
+    const held = documentOf(state.doc.toString());
+    const at = normalisedOffset(held, state.selection.main.head);
+    const found = signature(held.text, at);
+    if (found === undefined) return null;
+    return {
+      pos: state.selection.main.head,
+      above: true,
+      create: () => render(found),
+    };
+  };
+}

package/src/core/accounting/analysis.ts

@@ -0,0 +1,188 @@
+/**
+ * The trades taken apart: by direction, by extreme, and by run.
+ *
+ * The summary answers what the whole run did. Three questions it cannot answer
+ * are asked here, and each of them is a question about whether the summary
+ * means what it looks like it means.
+ *
+ * **Which side made the money.** A run whose long trades paid for its short
+ * ones reports a healthy net and is two strategies, one of which is losing. The
+ * summary cannot show that, because every figure in it is folded over both
+ * sides at once. Splitting it is not a refinement of the headline number, it is
+ * the first thing that can contradict it.
+ *
+ * **Whether one trade is the result.** A hundred trades and a profit factor of
+ * two reads as an edge until the largest win is the whole of the net. The
+ * expectancy's standard error already says how wide the spread is; the largest
+ * win and the largest loss say where the width came from, which is the part a
+ * reader can act on.
+ *
+ * **What the run of losses was.** The deepest drawdown is a money figure and
+ * the longest one is a bar count, and neither is the number that actually stops
+ * somebody trading a strategy. That number is how many times in a row it was
+ * wrong. It is not derivable from anything in the summary: the same win rate
+ * over the same trades gives a streak of two or a streak of eleven depending on
+ * an ordering the summary folds away.
+ *
+ * ## Every figure here is over closed trades, and that is the whole rule
+ *
+ * An open trade has no net to win or lose by, so it is in none of these counts,
+ * on either side, in no streak and in no extreme. `statistics.ts` has three
+ * different answers to which trades a figure is counted over, because a summary
+ * carries a capital figure and a bar count that are facts about the run rather
+ * than about its trades. Nothing here is a fact about the run, so there is one
+ * answer, and a reader can hold it.
+ *
+ * The consequence worth stating: `longCount + shortCount` is `tradeCount` and
+ * not the length of the list folded. A run holding an open position reports
+ * fewer trades here than it has, and the summary's `openTradeCount` is where
+ * the difference is accounted for.
+ */
+
+import type { Money } from './shapes.js';
+import type { Trade } from './trades.js';
+
+/** One direction's own figures, folded over that side's closed trades. */
+export interface SideAnalysis {
+  readonly count: number;
+  readonly wins: number;
+  readonly losses: number;
+  /** Exactly zero net, counted in neither half, as in the summary. */
+  readonly scratches: number;
+  /** Net after charges, which is the figure the sides are compared on. */
+  readonly netProfit: Money;
+  /** `wins / (wins + losses)`, null where this side decided nothing. */
+  readonly winRate: number | null;
+}
+
+/**
+ * The trades by direction, by extreme and by run.
+ *
+ * `long` and `short` partition the closed trades, so their counts sum to the
+ * summary's `tradeCount` and their nets sum to its `netProfit`. That is
+ * asserted rather than assumed, because a partition that stops partitioning is
+ * the defect this shape exists to make visible and it would otherwise show up
+ * as two panels that quietly disagree.
+ */
+export interface TradeAnalysis {
+  readonly long: SideAnalysis;
+  readonly short: SideAnalysis;
+  /**
+   * The best closed trade's net, zero where none closed and zero where every
+   * closed trade lost.
+   *
+   * Zero rather than null, and it is the one place here that is worth arguing
+   * about. A run whose every trade lost has no winning trade to name, and null
+   * would say so. It reports zero because the figure is read beside
+   * `largestLoss` and against `netProfit`, and a null in a column of money
+   * forces every reader of the report to handle a case that means "nothing
+   * won", which is what zero already means in this column.
+   */
+  readonly largestWin: Money;
+  /** The worst closed trade's net as a positive magnitude, zero where none lost. */
+  readonly largestLoss: Money;
+  /**
+   * The longest run of consecutive winning closed trades, in the order they
+   * closed.
+   *
+   * In the order they closed, and not the order they opened, because that is
+   * the order the account experienced them in and the streak is a fact about
+   * what the account experienced. The two orders differ whenever a trade is
+   * held across another one's whole life, which is every scaling strategy.
+   */
+  readonly maxConsecutiveWins: number;
+  /** The same, for losses. */
+  readonly maxConsecutiveLosses: number;
+}
+
+/** A side's figures under construction, before the rates are taken. */
+interface SideTally {
+  count: number;
+  wins: number;
+  losses: number;
+  scratches: number;
+  netProfit: Money;
+}
+
+function emptySide(): SideTally {
+  return { count: 0, wins: 0, losses: 0, scratches: 0, netProfit: 0 };
+}
+
+function sideOf(tally: SideTally): SideAnalysis {
+  const decided = tally.wins + tally.losses;
+  return {
+    count: tally.count,
+    wins: tally.wins,
+    losses: tally.losses,
+    scratches: tally.scratches,
+    netProfit: tally.netProfit,
+    winRate: decided === 0 ? null : tally.wins / decided,
+  };
+}
+
+/**
+ * One pass over the closed trades, in closing order.
+ *
+ * The list arrives in opening order, which is what the equity fold needs and
+ * what `tradesOf` produces. The streaks need closing order, so the closed
+ * trades are ordered here rather than anywhere else: reordering the list the
+ * caller holds would change the equity curve, and taking a second list in
+ * opening order and calling its streaks correct would be the defect this
+ * function is supposed to have caught.
+ *
+ * A trade whose net is exactly zero is a scratch, which is the summary's rule
+ * and is applied here for the same reason. A scratch **breaks** a streak
+ * without extending either one: a strategy that went right, flat, right was not
+ * right twice running, and counting the flat trade as either would make the
+ * streak a figure that depends on a rounding at the last digit.
+ */
+export function analysisOf(trades: readonly Trade[]): TradeAnalysis {
+  const long = emptySide();
+  const short = emptySide();
+  let largestWin = 0;
+  let largestLoss = 0;
+  let maxConsecutiveWins = 0;
+  let maxConsecutiveLosses = 0;
+  let winStreak = 0;
+  let lossStreak = 0;
+
+  const closed = trades.filter((trade) => !trade.isOpen).slice();
+  // A trade closes on a bar, and two can close on the same one. The opening
+  // order breaks the tie, because it is the order the list arrived in and the
+  // only other fact available: a sort that is not total gives two engines two
+  // different streaks from one list of trades.
+  closed.sort((a, b) => (a.closedOnBar ?? 0) - (b.closedOnBar ?? 0) || a.index - b.index);
+
+  for (const trade of closed) {
+    const side = trade.side === 'long' ? long : short;
+    side.count += 1;
+    side.netProfit += trade.netProfit;
+
+    if (trade.netProfit > 0) {
+      side.wins += 1;
+      if (trade.netProfit > largestWin) largestWin = trade.netProfit;
+      winStreak += 1;
+      lossStreak = 0;
+      if (winStreak > maxConsecutiveWins) maxConsecutiveWins = winStreak;
+    } else if (trade.netProfit < 0) {
+      side.losses += 1;
+      if (-trade.netProfit > largestLoss) largestLoss = -trade.netProfit;
+      lossStreak += 1;
+      winStreak = 0;
+      if (lossStreak > maxConsecutiveLosses) maxConsecutiveLosses = lossStreak;
+    } else {
+      side.scratches += 1;
+      winStreak = 0;
+      lossStreak = 0;
+    }
+  }
+
+  return {
+    long: sideOf(long),
+    short: sideOf(short),
+    largestWin,
+    largestLoss,
+    maxConsecutiveWins,
+    maxConsecutiveLosses,
+  };
+}