openalgo-script 0.1.0-alpha.0 → 0.2.0

package/src/core/emit/requests.ts

@@ -0,0 +1,258 @@
+/**
+ * Higher timeframe and other instrument reads, `compiled-program.md` 2.16.
+ *
+ * A read is the one thing in the language whose value is not computed from the
+ * bars the program is running on. Everything else an engine needs it can work
+ * out from this chart: a read needs another series entirely, and an expression
+ * evaluated over it.
+ *
+ * So a read compiles to two halves, and the split is the same one a `plot`
+ * makes. The fixed half is an entry here: which instrument, which timeframe,
+ * which of the three readings of `stdlib.md` 15.3, and the expression itself as
+ * a body over the requested bars. The per-bar half is a register, which the
+ * engine fills with the read's value for the bar about to run, exactly as it
+ * fills a bar register from the host's bar.
+ *
+ * **A register rather than a slot**, because a slot belongs to one frame (3.2)
+ * and a read may be written inside a `fn`; and because a register has history,
+ * so `dayHigh[1]` is the previous bar's reading with no further machinery.
+ *
+ * The body gets an emitter of its own. Its registers, cells and state regions
+ * are counted from zero over the requested bars, and a pass that reached into
+ * the parent's would put this chart's history behind another chart's name. What
+ * the two share is the constant pool and the library manifest, because nothing
+ * in either depends on a bar.
+ */
+import type { Call, Expression } from '../ast/index.js';
+import { withoutGrouping } from '../ast/index.js';
+import type { CheckedCall, CheckedRequest } from '../check/index.js';
+import type { Emitter, Frame } from './context.js';
+import { Frame as EmitFrame, argumentAt, declaredNames } from './context.js';
+import { emitExpression } from './expressions.js';
+import { assignRegions } from './functions.js';
+import type { ChartReference, Request, RequestBody, RequestField } from './program.js';
+import { RequestScope } from './request-scope.js';
+import { fieldOf } from './values.js';
+
+/**
+ * The chart facts that can fix part of a request's identity.
+ *
+ * Three of the facts of `stdlib.md` 3.4 name an instrument or an interval, and
+ * one of them is the documented default of `req.symbol`'s `exchange`. The rest
+ * describe the chart rather than identify it, and a request built from one of
+ * those has no meaning to carry.
+ */
+const CHART_IDENTITY: readonly ChartReference['chart'][] = ['symbol', 'exchange', 'interval'];
+
+/** The two reads of `stdlib.md` 15.1, and the two that ask after one. */
+export const REQUEST_CALLS = new Set(['req.timeframe', 'req.symbol']);
+export const REQUEST_STATUS_CALLS = new Set(['req.isReady', 'req.error']);
+
+/**
+ * A read, as a value on this bar: the register the engine filled for it.
+ *
+ * One request per call written in the source, however many call paths reach it.
+ * A body emitted twice, which 2.12 does for a function reached two ways, asks
+ * the host the same question twice otherwise, and the host's ceiling on
+ * outstanding requests counts both.
+ */
+export function emitRequestRead(e: Emitter, f: Frame, call: Call, checked: CheckedCall): void {
+  const register = registerFor(e, call, checked);
+  f.builder.at(call.span);
+  if (register === undefined) {
+    f.builder.push('CONST', e.pool.absent());
+    return;
+  }
+  f.builder.push('SLOAD', register);
+}
+
+/**
+ * The request a status call names, for `req.isReady` and `req.error`.
+ *
+ * Both name a read rather than taking its value, and a value on a bar cannot
+ * say which request produced it, so the compiler resolves the argument to the
+ * request's id and passes that. It is the same resolution `fill` does on a plot
+ * handle (2.8), and the reason is the same: the argument is a compile-time
+ * identity wearing the clothes of a value.
+ *
+ * **A read written inline is registered here and not only resolved**, which is
+ * the whole of the second half of this function. The checker gives every read
+ * in the file an id whether or not anything else in the file uses its value, and
+ * an id on its own names nothing an engine was handed: the compiled program
+ * would carry no request under it, the host would never be asked, and
+ * `req.error` would answer the empty string for a read the host refused. That is
+ * the one answer this pair of calls exists to make impossible, and it held only
+ * for the form written as a name. So the inline form emits its request the same
+ * way the value form does, and asks the host the same question.
+ */
+export function requestIdFor(e: Emitter, expression: Expression): number | undefined {
+  const inner = withoutGrouping(expression);
+  if (inner.kind === 'nameReference') {
+    const binding = e.bindingAt(inner);
+    return binding === undefined ? undefined : e.requestOf.get(binding.id);
+  }
+  if (inner.kind !== 'call') return undefined;
+  const checked = e.callAt(inner);
+  if (checked === undefined || !REQUEST_CALLS.has(checked.name)) return undefined;
+  const found = checkedRequestFor(e, inner);
+  if (found === undefined) return undefined;
+  registerFor(e, inner, checked);
+  return found.id;
+}
+
+/**
+ * Which name holds which read, before a statement is emitted.
+ *
+ * `req.isReady(dayHigh)` is resolved against this, and the call may be written
+ * above the line that declares the name it asks about, so the links are made
+ * before any of them is needed rather than as each declaration is met.
+ */
+export function linkRequestNames(e: Emitter): void {
+  for (const declared of declaredNames(e)) {
+    if (withoutGrouping(declared.value).kind !== 'call') continue;
+    const request = e.checked.requests.find(
+      (one) => one.call === withoutGrouping(declared.value),
+    );
+    const binding = e.checked.targets.get(declared.name);
+    if (request !== undefined && binding !== undefined) e.requestOf.set(binding.id, request.id);
+  }
+}
+
+function checkedRequestFor(e: Emitter, call: Call): CheckedRequest | undefined {
+  return e.checked.requests.find((one) => one.call === call);
+}
+
+function registerFor(e: Emitter, call: Call, checked: CheckedCall): number | undefined {
+  const found = checkedRequestFor(e, call);
+  if (found === undefined) return undefined;
+  const already = e.requestSeries.get(found.id);
+  if (already !== undefined) return already;
+
+  const entry = checked.entry;
+  const argument = (name: string): Expression | undefined => {
+    if (entry === undefined) return undefined;
+    return argumentAt(checked, entry, name)?.value;
+  };
+
+  const expression = argument('expr');
+  const name = nameOf(e, found);
+  const register = e.layout.filled('request', name);
+  e.requestSeries.set(found.id, register);
+
+  const request: Request = {
+    id: found.id,
+    read: found.name === 'req.symbol' ? 'symbol' : 'timeframe',
+    symbol: fieldFrom(e, argument('symbol'), 'symbol'),
+    exchange: fieldFrom(e, argument('exchange'), 'exchange'),
+    timeframe: fieldFrom(e, argument('timeframe'), 'timeframe'),
+    mode: modeOf(e, found),
+    series: register,
+    warmup: warmupOf(e, expression),
+    body: bodyOf(e, expression),
+  };
+  e.requests.push(request);
+  return register;
+}
+
+/** The name the source gave the read, for `debug` and for a reader. */
+function nameOf(e: Emitter, request: CheckedRequest): string {
+  for (const [binding, id] of e.requestOf) {
+    if (id !== request.id) continue;
+    const found = e.checked.bindings.find((one) => one.id === binding);
+    if (found !== undefined) return found.name;
+  }
+  return request.name;
+}
+
+/**
+ * One of the three fields that fix a request's identity.
+ *
+ * All three are settled before bar 0, which is what lets the whole set of
+ * requests be known at load (`host-interface.md` 5.2) and what makes a request
+ * that changed afterwards OS6013. A value this compiler cannot fold is neither
+ * a value nor a reference to one setting, so there is nothing to write, and the
+ * line that wrote it is told so rather than a program being emitted that names
+ * an instrument nobody asked for.
+ */
+function fieldFrom(e: Emitter, written: Expression | undefined, option: string): RequestField {
+  if (written === undefined) return null;
+  const fact = chartFactOf(e, written);
+  if (fact !== undefined) return { chart: fact };
+  const value = e.fold(written);
+  if (value !== undefined) return fieldOf(value);
+  e.sink.report('OS3003', written.span, { option });
+  return null;
+}
+
+/** `chart.symbol`, `chart.exchange` or `chart.interval`, written as a name. */
+function chartFactOf(e: Emitter, written: Expression): ChartReference['chart'] | undefined {
+  const inner = withoutGrouping(written);
+  if (inner.kind !== 'member') return undefined;
+  const object = withoutGrouping(inner.object);
+  if (object.kind !== 'nameReference' || object.name !== 'chart') return undefined;
+  if (e.bindingAt(object) !== undefined) return undefined;
+  return CHART_IDENTITY.find((one) => one === inner.member.text);
+}
+
+function modeOf(e: Emitter, request: CheckedRequest): Request['mode'] {
+  if (request.mode !== 'unknown') return request.mode;
+  // The mode decides whether the study may repaint, so it is read at compile
+  // time or not at all (`stdlib.md` 15.3).
+  e.sink.report('OS3003', request.span, { option: 'mode' });
+  return 'confirmed';
+}
+
+/**
+ * The bars of requested history the body needs, when a number is known.
+ *
+ * A host extends the requested range backwards by it (`host-interface.md` 5.2).
+ * It is a floor rather than a promise, because a length that comes from a
+ * setting is not known until the setting resolves: a host that extends by less
+ * gets a read that is absent for longer, never a wrong number.
+ */
+function warmupOf(e: Emitter, expression: Expression | undefined): number | null {
+  if (expression === undefined) return null;
+  const found = e.checked.warmups.get(expression);
+  if (found === undefined || found.kind === 'never') return null;
+  return found.bar;
+}
+
+function bodyOf(e: Emitter, expression: Expression | undefined): RequestBody {
+  const scope = new RequestScope();
+  const sub = e.forRequest(scope);
+  const top = new EmitFrame(true);
+
+  if (expression === undefined) {
+    top.builder.at(e.checked.script.span);
+    top.builder.push('CONST', sub.pool.absent());
+  } else {
+    emitExpression(sub, top, expression);
+    top.builder.at(expression.span);
+  }
+  // The body ends the way a function body does: the value it leaves is the
+  // read's value for that requested bar, and `RET` is what hands it over
+  // (4.10). Nothing new is asked of an engine's instruction loop.
+  top.builder.push('RET');
+
+  const { cells, states } = assignRegions(sub, top);
+  return {
+    inputs: scope.inputs,
+    series: sub.layout.registers,
+    frame: { slots: top.layout.slotCount },
+    cells,
+    states,
+    functions: sub.functions,
+    callSites: sub.sites.map((site) => ({
+      fn: site.fn,
+      argc: site.argc,
+      cellBase: site.cellBase,
+      stateBase: site.stateBase,
+      series: site.series,
+    })),
+    loops: sub.loops,
+    requests: sub.requests,
+    code: top.builder.code,
+    pos: top.builder.pos,
+    fnPos: sub.functionPos,
+  };
+}

package/src/core/emit/requires.ts

@@ -0,0 +1,91 @@
+/**
+ * `requires`, the capability tags of `compiled-program.md` 2.2.
+ *
+ * Tags are the real compatibility mechanism and the version number is the
+ * coarse one. A version says how new a program is; a tag says what it actually
+ * needs, so an engine that implements everything except order placement runs
+ * every study ever written and refuses exactly the strategies, with a message
+ * naming the capability it lacks rather than "too new".
+ *
+ * That is also why every tag here is derived from what was emitted rather than
+ * from what was written. **A compiler must emit every tag the program needs and
+ * must not emit a tag it does not need**, because a spurious tag turns an engine
+ * that could have run the program into an engine that refuses it.
+ */
+import type { LibraryEntry, Type } from '../check/index.js';
+import type { Emitter } from './context.js';
+import type { Instruction, Request } from './program.js';
+
+/** The tags of format 1.0, in the order 2.2's table gives them. */
+const ORDER: readonly string[] = [
+  'core.1',
+  'arrays',
+  'functions',
+  'loops',
+  'orders',
+  'objects',
+  'tables',
+  'alerts',
+  'req.timeframe',
+  'req.symbol',
+];
+
+const DRAWN_OBJECTS: readonly string[] = ['line', 'label', 'box', 'polyline'];
+
+function mentionsArray(type: Type): boolean {
+  if (type.kind === 'array') return true;
+  if (type.kind === 'series') return mentionsArray(type.element);
+  return false;
+}
+
+function isArrayFunction(entry: LibraryEntry): boolean {
+  return (
+    mentionsArray(entry.returns) || entry.parameters.some((one) => mentionsArray(one.type))
+  );
+}
+
+function createsObject(entry: LibraryEntry): boolean {
+  return entry.returns.kind === 'object' && DRAWN_OBJECTS.includes(entry.returns.object);
+}
+
+function usesArrayInstruction(lists: readonly (readonly Instruction[])[]): boolean {
+  return lists.some((code) => code.some(([opcode]) => opcode === 'ARRAY' || opcode === 'ELEM'));
+}
+
+/**
+ * Every instruction list in the program, the bodies of its reads included.
+ *
+ * A tag says what the program needs, and a read's expression is part of the
+ * program: an engine that cannot run an `ELEM` cannot run one inside a read
+ * either, and a tag derived from the bar's list alone would tell it otherwise.
+ */
+function codeOf(lists: Instruction[][], requests: readonly Request[]): void {
+  for (const request of requests) {
+    lists.push([...request.body.code]);
+    for (const one of request.body.functions) lists.push([...one.code]);
+    codeOf(lists, request.body.requests);
+  }
+}
+
+function loopsIn(requests: readonly Request[]): boolean {
+  return requests.some(
+    (one) => one.body.loops.length > 0 || loopsIn(one.body.requests),
+  );
+}
+
+export function requiresOf(e: Emitter, code: readonly Instruction[]): readonly string[] {
+  const lists: Instruction[][] = [[...code], ...e.functions.map((one) => [...one.code])];
+  codeOf(lists, e.requests);
+  const needed = new Set<string>(['core.1']);
+
+  if (usesArrayInstruction(lists) || e.calledEntries.some(isArrayFunction)) needed.add('arrays');
+  if (e.checked.functions.length > 0) needed.add('functions');
+  if (e.loops.length > 0 || loopsIn(e.requests)) needed.add('loops');
+  if (e.libraryFunctions.some((one) => one.effect === 'order')) needed.add('orders');
+  if (e.calledEntries.some(createsObject)) needed.add('objects');
+  if (e.tables.length > 0) needed.add('tables');
+  if (e.alerts.length > 0) needed.add('alerts');
+  for (const request of e.checked.requests) needed.add(request.name);
+
+  return ORDER.filter((tag) => needed.has(tag));
+}

package/src/core/emit/sha256.ts

@@ -0,0 +1,119 @@
+/**
+ * SHA-256, and the UTF-8 encoding it runs over.
+ *
+ * `compiled-program.md` 2.14 makes `source.hash` the lowercase hexadecimal
+ * SHA-256 of the UTF-8 source text, and a host records it against a chart, a
+ * backtest run and a live process: it is what makes a result reproducible
+ * months later. So it cannot be optional and it cannot come from a package,
+ * because nothing under `src/core` may import one, and it cannot come from a
+ * platform's own crypto either, because the same file has to run in a worker,
+ * on a server and inside somebody else's application.
+ *
+ * Written from FIPS 180-4. It is small, it is exact, and it is tested against
+ * the published vectors rather than against itself.
+ */
+
+const K: readonly number[] = [
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+];
+
+/**
+ * UTF-8 bytes of a string, counting by code point.
+ *
+ * A lone surrogate cannot be encoded and becomes the replacement character,
+ * which is what every other encoder does and what the lexer has already made
+ * unreachable from a source file.
+ */
+export function utf8(text: string): Uint8Array {
+  const bytes: number[] = [];
+  for (const character of text) {
+    let point = character.codePointAt(0) ?? 0xfffd;
+    if (point >= 0xd800 && point <= 0xdfff) point = 0xfffd;
+    if (point < 0x80) {
+      bytes.push(point);
+    } else if (point < 0x800) {
+      bytes.push(0xc0 | (point >> 6), 0x80 | (point & 0x3f));
+    } else if (point < 0x10000) {
+      bytes.push(0xe0 | (point >> 12), 0x80 | ((point >> 6) & 0x3f), 0x80 | (point & 0x3f));
+    } else {
+      bytes.push(
+        0xf0 | (point >> 18),
+        0x80 | ((point >> 12) & 0x3f),
+        0x80 | ((point >> 6) & 0x3f),
+        0x80 | (point & 0x3f),
+      );
+    }
+  }
+  return Uint8Array.from(bytes);
+}
+
+function rotateRight(x: number, n: number): number {
+  return ((x >>> n) | (x << (32 - n))) >>> 0;
+}
+
+export function sha256(text: string): string {
+  const message = utf8(text);
+  const bitLength = message.length * 8;
+
+  // The padding of FIPS 180-4 section 5.1.1: a one bit, zeroes, and the length
+  // as a 64 bit big-endian count of bits.
+  const padded = new Uint8Array(((message.length + 9 + 63) >> 6) << 6);
+  padded.set(message);
+  padded[message.length] = 0x80;
+  const view = new DataView(padded.buffer);
+  view.setUint32(padded.length - 8, Math.floor(bitLength / 0x100000000), false);
+  view.setUint32(padded.length - 4, bitLength >>> 0, false);
+
+  const h = [
+    0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+  ];
+  const w = new Array<number>(64).fill(0);
+
+  for (let block = 0; block < padded.length; block += 64) {
+    for (let i = 0; i < 16; i += 1) w[i] = view.getUint32(block + i * 4, false);
+    for (let i = 16; i < 64; i += 1) {
+      const a = w[i - 15] ?? 0;
+      const b = w[i - 2] ?? 0;
+      const s0 = rotateRight(a, 7) ^ rotateRight(a, 18) ^ (a >>> 3);
+      const s1 = rotateRight(b, 17) ^ rotateRight(b, 19) ^ (b >>> 10);
+      w[i] = (((w[i - 16] ?? 0) + s0 + (w[i - 7] ?? 0) + s1) >>> 0) as number;
+    }
+
+    let [a, b, c, d, f, g, hh, i0] = [h[0] ?? 0, h[1] ?? 0, h[2] ?? 0, h[3] ?? 0, h[4] ?? 0, h[5] ?? 0, h[6] ?? 0, h[7] ?? 0];
+
+    for (let i = 0; i < 64; i += 1) {
+      const s1 = rotateRight(f, 6) ^ rotateRight(f, 11) ^ rotateRight(f, 25);
+      const choose = (f & g) ^ (~f & hh);
+      const temp1 = (i0 + s1 + choose + (K[i] ?? 0) + (w[i] ?? 0)) >>> 0;
+      const s0 = rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22);
+      const majority = (a & b) ^ (a & c) ^ (b & c);
+      const temp2 = (s0 + majority) >>> 0;
+      i0 = hh;
+      hh = g;
+      g = f;
+      f = (d + temp1) >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (temp1 + temp2) >>> 0;
+    }
+
+    h[0] = ((h[0] ?? 0) + a) >>> 0;
+    h[1] = ((h[1] ?? 0) + b) >>> 0;
+    h[2] = ((h[2] ?? 0) + c) >>> 0;
+    h[3] = ((h[3] ?? 0) + d) >>> 0;
+    h[4] = ((h[4] ?? 0) + f) >>> 0;
+    h[5] = ((h[5] ?? 0) + g) >>> 0;
+    h[6] = ((h[6] ?? 0) + hh) >>> 0;
+    h[7] = ((h[7] ?? 0) + i0) >>> 0;
+  }
+
+  return h.map((one) => one.toString(16).padStart(8, '0')).join('');
+}