openalgo-script 0.1.0-alpha.1 → 0.2.0

package/src/core/check/tags.ts

@@ -0,0 +1,94 @@
+/**
+ * A tag that names nothing, read from the file, `stdlib.md` 17.2.
+ *
+ * **A tag argument that defaults to the empty string is a label the destination
+ * carries. A tag argument that is required, or defaults to absence, is a
+ * reference to something that has to exist.** `buy`, `sell`, `exit`,
+ * `order.place`, `order.reverse` and `order.bracket` all default theirs to `""`,
+ * and an empty label is an ordinary order. `cancel` requires one and `close`
+ * defaults to absence, and both name something the strategy already has.
+ *
+ * `cancel` is refused by the engine, with OS7009, because what it asks about is
+ * whether an order is live now and only a run knows that. `close` is refused
+ * here, before any bar runs, because what it asks about is answerable from the
+ * file alone: a tag no order in the file is placed with can never name a part of
+ * a position, so the call sends nothing on every bar and says nothing, and the
+ * script goes on believing it has flattened.
+ *
+ * **The run cannot tell that mistake from an ordinary bar.** A tag naming no
+ * ledger row is also what a working script looks like before its entry has
+ * happened: `close(tag = "runner")` on the bar an exit signal first fires is a
+ * tag that has never named a row yet, and refusing it would refuse a script that
+ * had done exactly what this code's own fix asks. Nothing a script can write
+ * today would guard it either, because every call that reads the ledger
+ * (`stdlib.md` 17.3) is planned. The file, unlike the run, is complete: what it
+ * can place is all of what it will ever place.
+ *
+ * **Only what is written is read.** A tag a script computes could be anything,
+ * so a computed tag on an order that places one leaves this pass silent for the
+ * whole file rather than reporting a close it cannot prove is dead.
+ */
+import type { Argument } from '../ast/index.js';
+import type { Span } from '../span/index.js';
+import type { Checker } from './checker.js';
+import type { CheckedCall } from './checked.js';
+import { literalString } from './literals.js';
+
+/**
+ * The calls that append a ledger row a later `close` can act on.
+ *
+ * `exit`, `order.bracket` and `cancel` are not among them: a bracket is a level
+ * and a cancellation is an instruction about an order, and neither appends a
+ * row (`stdlib.md` 17.7). Nor is `close` itself, which only ever reduces what
+ * one of these opened, so a close that is the only mention of a tag is exactly
+ * the call this pass is about.
+ */
+const PLACING: ReadonlySet<string> = new Set(['buy', 'sell', 'order.place', 'order.reverse']);
+
+/** The `tag` argument a call was given, absent where it was not written. */
+function tagArgument(checked: CheckedCall): Argument | undefined {
+  const index = checked.entry?.parameters.findIndex((one) => one.name === 'tag') ?? -1;
+  return index < 0 ? undefined : checked.arguments[index];
+}
+
+/** One `close` whose tag was written out, and where its tag is written. */
+interface WrittenClose {
+  readonly tag: string;
+  readonly span: Span;
+}
+
+/** OS7016: a `close` naming a tag no order in this file is placed with. */
+export function reportUnplaceableTags(checker: Checker): void {
+  if (checker.declaration?.form !== 'strategy') return;
+
+  const placed = new Set<string>();
+  const closes: WrittenClose[] = [];
+
+  for (const checked of checker.calls) {
+    if (checked.target !== 'library') continue;
+
+    if (PLACING.has(checked.name)) {
+      const argument = tagArgument(checked);
+      // A call that writes no tag takes the empty one its signature states.
+      if (argument === undefined) {
+        placed.add('');
+        continue;
+      }
+      const written = literalString(argument.value);
+      if (written === undefined) return;
+      placed.add(written);
+      continue;
+    }
+
+    if (checked.name !== 'close') continue;
+    const argument = tagArgument(checked);
+    if (argument === undefined) continue;
+    const written = literalString(argument.value);
+    if (written !== undefined) closes.push({ tag: written, span: argument.span });
+  }
+
+  for (const close of closes) {
+    if (placed.has(close.tag)) continue;
+    checker.report('OS7016', close.span, { tag: JSON.stringify(close.tag) });
+  }
+}

package/src/core/check/types.ts

@@ -0,0 +1,260 @@
+/**
+ * The types of language.md section 5, as the checker holds them.
+ *
+ * An annotation is syntax and has a span; this is the checker's answer, it has
+ * no position, and it exists for expressions nobody annotated. The two are
+ * separate for that reason and `ast/annotations.ts` says the same thing from
+ * the other side.
+ *
+ * Three things about this model are worth knowing before reading anything that
+ * uses it.
+ *
+ * `none` is a member of every type (section 6), so it is a type here and it
+ * satisfies every other one. That is why a first assignment of `none` fixes
+ * nothing: there is no information in it to fix a name's type with.
+ *
+ * A series is a wrapper rather than a flag, and broadcast (section 5.2) makes
+ * `T` and `series T` interchangeable at every boundary, so nothing outside this
+ * file compares two types by identity.
+ *
+ * `unknown` is what an expression has after a diagnostic was already reported
+ * about it. It satisfies everything and everything satisfies it, so one mistake
+ * produces one diagnostic instead of one per operator above it.
+ */
+
+/** The scalar types, which are the ones an array may hold and a `var` may take. */
+export const VALUE_KINDS = ['number', 'string', 'bool', 'color'] as const;
+export type ValueKind = (typeof VALUE_KINDS)[number];
+
+/** The runtime object types of language.md 5.4. */
+export const OBJECT_KINDS = ['line', 'label', 'box', 'polyline', 'table'] as const;
+export type ObjectKind = (typeof OBJECT_KINDS)[number];
+
+/** The declaration handle types of language.md 5.4. */
+export const HANDLE_KINDS = ['plot', 'fill', 'level'] as const;
+export type HandleKind = (typeof HANDLE_KINDS)[number];
+
+export type Type =
+  | { readonly kind: ValueKind }
+  | { readonly kind: 'none' }
+  | { readonly kind: 'series'; readonly element: Type }
+  | { readonly kind: 'array'; readonly element: Type }
+  | { readonly kind: 'handle'; readonly handle: HandleKind }
+  | { readonly kind: 'object'; readonly object: ObjectKind }
+  /**
+   * The object kinds one parameter accepts, and nothing else.
+   *
+   * `draw.setFrom` moves the first anchor of a line or of a box, and neither a
+   * single object type nor `any` says that: the first is too narrow to write
+   * and the second takes a label, a number and everything else, which is how a
+   * setter applied to the wrong object came to compile, run on every bar and
+   * draw nothing with nothing reported.
+   *
+   * It is a set of object kinds rather than a union of arbitrary types because
+   * a set is what the eleven signatures that need it mean, and nothing else in
+   * version 1 needs more. A general union would have to answer what it means
+   * for a series, an array element and a name's type, and no entry is asking.
+   * This type therefore appears in a library signature and never as the type of
+   * an expression, so nothing downstream has to hold one.
+   */
+  | { readonly kind: 'objects'; readonly objects: readonly ObjectKind[] }
+  /** The absence of a result. Not a type a name can hold; see language.md 5.1. */
+  | { readonly kind: 'nothing' }
+  /**
+   * A stand-in inside a library signature, and nowhere else.
+   *
+   * `element(arr, i)` returns whatever `arr` holds and `orElse(x, fallback)`
+   * returns whatever it was given. Both are one signature over many types, and
+   * the call site binds the stand-in to a real type before anything downstream
+   * sees it, so no expression is ever left with one of these as its type.
+   */
+  | { readonly kind: 'variable'; readonly name: string }
+  /** Already reported about. Satisfies everything, so mistakes do not cascade. */
+  | { readonly kind: 'unknown' };
+
+export const NUMBER: Type = { kind: 'number' };
+export const STRING: Type = { kind: 'string' };
+export const BOOL: Type = { kind: 'bool' };
+export const COLOR: Type = { kind: 'color' };
+export const NONE: Type = { kind: 'none' };
+export const NOTHING: Type = { kind: 'nothing' };
+export const UNKNOWN: Type = { kind: 'unknown' };
+
+export function seriesOf(element: Type): Type {
+  return element.kind === 'series' ? element : { kind: 'series', element };
+}
+
+export function arrayOf(element: Type): Type {
+  return { kind: 'array', element };
+}
+
+export function handleType(handle: HandleKind): Type {
+  return { kind: 'handle', handle };
+}
+
+export function objectType(object: ObjectKind): Type {
+  return { kind: 'object', object };
+}
+
+/** The set of object kinds a parameter accepts, for a signature that takes two. */
+export function objectsType(objects: readonly ObjectKind[]): Type {
+  return { kind: 'objects', objects };
+}
+
+/** The object kinds a type stands for, or nothing when it stands for none. */
+function objectKindsOf(type: Type): readonly ObjectKind[] | undefined {
+  if (type.kind === 'object') return [type.object];
+  if (type.kind === 'objects') return type.objects;
+  return undefined;
+}
+
+/** The value behind a series, and the type itself when it is not one. */
+export function elementOf(type: Type): Type {
+  return type.kind === 'series' ? type.element : type;
+}
+
+export function isSeries(type: Type): boolean {
+  return type.kind === 'series';
+}
+
+export function isHandle(type: Type): boolean {
+  return type.kind === 'handle';
+}
+
+export function isDefinite(type: Type): boolean {
+  return type.kind !== 'none' && type.kind !== 'unknown';
+}
+
+/**
+ * The type as a reader sees it in a message.
+ *
+ * Every OS2003, OS2012 and OS3011 puts one of these in front of somebody, so
+ * the spelling is the spelling of the specification's own tables rather than an
+ * internal tag: `series number`, not `series(number)`.
+ */
+export function typeText(type: Type): string {
+  switch (type.kind) {
+    case 'series':
+      return `series ${typeText(type.element)}`;
+    case 'array':
+      return `array<${typeText(type.element)}>`;
+    case 'handle':
+      return type.handle;
+    case 'object':
+      return type.object;
+    case 'objects':
+      return kindList(type.objects);
+    case 'nothing':
+      return 'nothing';
+    case 'variable':
+      return type.name;
+    case 'unknown':
+      return 'unknown';
+    default:
+      return type.kind;
+  }
+}
+
+/**
+ * A set of object kinds as a reader sees it: `a line or a box`.
+ *
+ * Written out rather than abbreviated because this is the whole of what OS3011
+ * can tell somebody who passed the wrong object: the sentence has to name what
+ * the setter does take, and a reader who is told `object` learns nothing.
+ */
+function kindList(kinds: readonly ObjectKind[]): string {
+  if (kinds.length === 0) return 'nothing';
+  if (kinds.length === 1) return kinds[0] as string;
+  return `${kinds.slice(0, -1).join(', ')} or ${kinds[kinds.length - 1] as string}`;
+}
+
+/**
+ * Whether two types are the same once broadcast is taken into account.
+ *
+ * Broadcast (language.md 5.2) changes no value, so `number` and `series number`
+ * are the same type to every rule in the language that asks whether two things
+ * mix. The series-ness survives in the result, which is what `join` is for.
+ */
+export function sameType(left: Type, right: Type): boolean {
+  const a = elementOf(left);
+  const b = elementOf(right);
+  if (a.kind === 'unknown' || b.kind === 'unknown') return true;
+  if (a.kind === 'variable' || b.kind === 'variable') return true;
+  // A set of object kinds is compared before the tags are, because an object
+  // and a set the object is in are the same type to every rule that asks. A
+  // kind outside the set is not, which is the whole point of writing the set.
+  if (a.kind === 'objects' || b.kind === 'objects') {
+    const wanted = objectKindsOf(a);
+    const given = objectKindsOf(b);
+    if (wanted === undefined || given === undefined) return false;
+    return given.some((one) => wanted.includes(one));
+  }
+  if (a.kind !== b.kind) return false;
+  if (a.kind === 'array' && b.kind === 'array') return sameType(a.element, b.element);
+  if (a.kind === 'handle' && b.kind === 'handle') return a.handle === b.handle;
+  if (a.kind === 'object' && b.kind === 'object') return a.object === b.object;
+  return true;
+}
+
+/**
+ * Whether a value of `from` may stand where `to` is wanted.
+ *
+ * `none` is accepted everywhere a value is, because it is a member of every
+ * type. `nothing` is accepted nowhere, because a call that draws rather than
+ * computing has no result to stand anywhere: that case is OS2003.
+ */
+export function accepts(to: Type, from: Type): boolean {
+  if (to.kind === 'unknown' || from.kind === 'unknown') return true;
+  if (to.kind === 'variable' || from.kind === 'variable') return true;
+  if (from.kind === 'nothing' || to.kind === 'nothing') return from.kind === to.kind;
+  if (from.kind === 'none') return true;
+  if (to.kind === 'none') return true;
+  return sameType(to, from);
+}
+
+/**
+ * Whether two types may stand beside each other.
+ *
+ * This is `sameType` with the rule of language.md 6 added: `none` is a member
+ * of every type, so an arm of a ternary, a `case` value or an operand of `==`
+ * that is absent mixes with anything. It is the test every rule that compares
+ * two written expressions uses, and `sameType` is the narrower question of
+ * whether two definite types are the same one.
+ */
+export function compatible(left: Type, right: Type): boolean {
+  if (left.kind === 'nothing' || right.kind === 'nothing') return left.kind === right.kind;
+  if (elementOf(left).kind === 'none' || elementOf(right).kind === 'none') return true;
+  return sameType(left, right);
+}
+
+/**
+ * The type of a place that holds both, with series-ness carried across.
+ *
+ * A name assigned a plain number on one line and a series number on another
+ * holds a series number, because a bar where the plain value was written is a
+ * bar of the series. `none` never decides the answer, which is the rule of
+ * language.md 10.1 stated once, here, for every caller.
+ */
+export function join(left: Type, right: Type): Type {
+  if (left.kind === 'unknown') return right;
+  if (right.kind === 'unknown') return left;
+  if (left.kind === 'none') return right;
+  if (right.kind === 'none') return left;
+  const element = elementOf(left);
+  return isSeries(left) || isSeries(right) ? seriesOf(element) : element;
+}
+
+/** Whether this type may be an array element, language.md 14.1. OS2019 otherwise. */
+export function canBeArrayElement(type: Type): boolean {
+  switch (type.kind) {
+    case 'number':
+    case 'string':
+    case 'bool':
+    case 'color':
+    case 'object':
+    case 'unknown':
+      return true;
+    default:
+      return false;
+  }
+}

package/src/core/check/warmup.ts

@@ -0,0 +1,100 @@
+/**
+ * Warmup: the first bar an expression can honestly produce a value for.
+ *
+ * language.md 7.3 makes warmup a promise rather than a hint, and stdlib.md
+ * states a length per function so two engines cannot disagree by a bar. This
+ * module is the arithmetic of composing those lengths, and nothing else.
+ *
+ * Three answers are possible and all three are useful, which is why this is a
+ * small lattice and not a number:
+ *
+ * `at` is an exact first bar. Every length on the path was known while
+ * compiling, so the checker can say "bar 33" and mean it.
+ *
+ * `atLeast` is a floor. A length that comes from `input()` is not known until
+ * the settings are resolved, and a warmup that depends on the data (`vwap`
+ * starts at the session's first bar) is not known even then. Saying "at least
+ * bar 9" is true; saying "bar 9" would not be, and a warning built on a number
+ * that was invented is worse than no warning.
+ *
+ * `never` is a value that is absent on every bar of the run: a name that was
+ * never given a definite type is of type `none` (language.md 10.1), and a plot
+ * of one is OS8009. This is the one case where the compiler can tell a trader
+ * that a line will not appear before they run the study and wonder why.
+ *
+ * There is no warmup field in a compiled program (`compiled-program.md` section
+ * 7) and there is not meant to be one: the line starts on the bar the value
+ * stops being absent. What is here serves the diagnostics and the editor, which
+ * is why it is allowed to be approximate and has to say when it is.
+ */
+export type Warmup =
+  | { readonly kind: 'at'; readonly bar: number }
+  | { readonly kind: 'atLeast'; readonly bar: number }
+  | { readonly kind: 'never' };
+
+/** A value on the very first bar. */
+export const BAR_ZERO: Warmup = { kind: 'at', bar: 0 };
+
+export const NEVER: Warmup = { kind: 'never' };
+
+export function atBar(bar: number): Warmup {
+  return { kind: 'at', bar: Math.max(0, Math.trunc(bar)) };
+}
+
+export function atLeastBar(bar: number): Warmup {
+  return { kind: 'atLeast', bar: Math.max(0, Math.trunc(bar)) };
+}
+
+/** The floor of a warmup, for a rule that can only give a lower bound. */
+export function weaken(warmup: Warmup): Warmup {
+  return warmup.kind === 'at' ? atLeastBar(warmup.bar) : warmup;
+}
+
+/**
+ * The warmup of something that needs both of two values.
+ *
+ * Arithmetic propagates absence (language.md 6.2), so a sum is absent until
+ * both sides are present: the later of the two. An operand that is never
+ * present makes the whole thing never present.
+ */
+export function later(left: Warmup, right: Warmup): Warmup {
+  if (left.kind === 'never' || right.kind === 'never') return NEVER;
+  const bar = Math.max(left.bar, right.bar);
+  return left.kind === 'at' && right.kind === 'at' ? atBar(bar) : atLeastBar(bar);
+}
+
+/**
+ * The warmup of something that needs either of two values.
+ *
+ * `orElse(x, fallback)` and a ternary whose arms warm up at different bars are
+ * both this: present as soon as the earlier one is.
+ */
+export function earlier(left: Warmup, right: Warmup): Warmup {
+  if (left.kind === 'never') return right;
+  if (right.kind === 'never') return left;
+  const bar = Math.min(left.bar, right.bar);
+  return left.kind === 'at' && right.kind === 'at' ? atBar(bar) : atLeastBar(bar);
+}
+
+/** The warmup of every one of these together, or bar 0 when there are none. */
+export function allOf(warmups: readonly Warmup[]): Warmup {
+  return warmups.reduce<Warmup>(later, BAR_ZERO);
+}
+
+/**
+ * The same value, delayed by a stated number of bars.
+ *
+ * This is how a library entry's declared length composes with its source's:
+ * `sma(ema(close, 10), 10)` is absent until bar 18 because each call delays
+ * whatever it was given by its own length, and stdlib.md section 1 says so.
+ */
+export function delayed(warmup: Warmup, bars: number): Warmup {
+  if (warmup.kind === 'never') return NEVER;
+  const bar = warmup.bar + Math.trunc(bars);
+  return warmup.kind === 'at' ? atBar(bar) : atLeastBar(bar);
+}
+
+/** Whether this value is absent on every bar, which is what OS8009 reports. */
+export function isNever(warmup: Warmup): boolean {
+  return warmup.kind === 'never';
+}

package/src/core/diagnostics/collector.ts

@@ -3,6 +3,18 @@ import type { Span } from '../span/index.js';
 import { diagnosticFor, isError } from './diagnostic.js';
 import type { Diagnostic } from './diagnostic.js';
 
+/**
+ * Two codes in code point order, which is the same order everywhere.
+ *
+ * `<` on two strings compares UTF-16 code units and reads no environment
+ * setting, which is exactly what `language.md` 9.3 fixes for the language's own
+ * string comparison. The engine's own output obeys the rule it gives scripts.
+ */
+function byCodePoint(left: string, right: string): number {
+  if (left < right) return -1;
+  return left > right ? 1 : 0;
+}
+
 /**
  * What a stage is handed so it can report.
  *
@@ -77,11 +89,25 @@ export class DiagnosticBag implements DiagnosticSink {
    *
    * Stages report in the order they run, so a checker warning about line 2
    * arrives after a parser error about line 40. A reader reads top to bottom.
+   *
+   * **The order is total, and it depends on nothing outside the program.** Two
+   * engines handed the same diagnostics have to print them in the same order, so
+   * the tie after the offset is the span's length and then the code compared by
+   * code point. It was a locale comparison, which `compiled-program.md` 8.4
+   * forbids by name: the same two codes order differently under different
+   * collation rules, and the machine that is set up differently is the one
+   * nobody is looking at. Length is in the comparison because without it two
+   * diagnostics sharing a code and an offset tie, and a tie leaves the answer to
+   * whether the sort happens to be stable, which is a property of the engine
+   * rather than of the language. With it, nothing can tie: the bag already
+   * refuses a second diagnostic with the same code, offset and length.
    */
   ordered(): readonly Diagnostic[] {
     return [...this.#items].sort(
       (left, right) =>
-        left.span.offset - right.span.offset || left.code.localeCompare(right.code),
+        left.span.offset - right.span.offset ||
+        left.span.length - right.span.length ||
+        byCodePoint(left.code, right.code),
     );
   }
 }