openalgo-script 0.1.0-alpha.1 → 0.2.0

package/src/core/check/functions.ts

@@ -0,0 +1,283 @@
+/**
+ * The functions a file declares: collecting them, ordering them and checking
+ * their bodies.
+ *
+ * Two rules shape everything here. A `fn` may be called before its declaration
+ * appears (`language.md` 12.5), so every declaration is collected before any
+ * body is checked. And a function may not call itself, directly or through a
+ * cycle (11.4), because state regions are allocated per call site and recursion
+ * would need a stack of them on every bar of every script; the cycle is
+ * reported as OS2005 and named in full, since a three function cycle is not
+ * something a reader can see from one line.
+ *
+ * Bodies are checked callees first, so a function that calls another already
+ * knows what that one returns rather than treating it as unknown.
+ */
+import type { Block, Expression, FunctionDeclaration, Script } from '../ast/index.js';
+import { walk } from '../ast/index.js';
+import type { Checker, Placement } from './checker.js';
+import { TOP_LEVEL } from './checker.js';
+import type { Binding, Mutable } from './checked.js';
+import { calleeNameOf } from './constant.js';
+import { checkExpression } from './expressions.js';
+import { checkStatements, resolveAnnotation } from './statements.js';
+import { isLibraryName } from './surface.js';
+import type { Type } from './types.js';
+import { UNKNOWN, isDefinite, join, sameType, typeText } from './types.js';
+import type { Warmup } from './warmup.js';
+import { BAR_ZERO, earlier } from './warmup.js';
+
+/** Registers every `fn` in the file, so a call above one still resolves. */
+function collectFunctions(checker: Checker, script: Script): void {
+  for (const item of script.items) {
+    if (item.kind !== 'functionDeclaration') continue;
+    const name = item.name.text;
+
+    const existing = checker.functionNodes.get(name);
+    if (existing !== undefined) {
+      checker.report('OS2017', item.name.span, { name, line: existing.span.line });
+      continue;
+    }
+    if (isLibraryName(name)) {
+      checker.report('OS2002', item.name.span, { name, line: 'built-in' });
+      continue;
+    }
+
+    const id = checker.functions.length;
+    checker.functionNodes.set(name, item);
+    checker.functionsByName.set(name, id);
+    checker.functions.push({
+      id,
+      declaration: item,
+      parameters: [],
+      returns: UNKNOWN,
+      warmup: BAR_ZERO,
+      stateful: false,
+    });
+    checker.declare(item.name, 'function', UNKNOWN, BAR_ZERO);
+  }
+}
+
+/** Every function this one calls, read off its body without checking anything. */
+function calleesOf(declaration: FunctionDeclaration, known: ReadonlySet<string>): Set<string> {
+  const found = new Set<string>();
+  walk(declaration, {
+    enter(node) {
+      if (node.kind !== 'call') return;
+      const name = calleeNameOf(node.callee);
+      if (name !== undefined && known.has(name)) found.add(name);
+    },
+  });
+  return found;
+}
+
+/**
+ * OS2005: a function that reaches itself.
+ *
+ * A depth first walk that meets a name already on its own stack has found a
+ * cycle, and the stack from that name back to itself is the chain the message
+ * quotes, because a three function cycle is not something a reader can see from
+ * one line. The walk runs over every declaration, including the ones nothing
+ * ever calls, so a cycle is reported whether or not the file uses it.
+ */
+function detectRecursion(checker: Checker): void {
+  const known = new Set(checker.functionNodes.keys());
+  const callees = new Map<string, Set<string>>();
+  for (const [name, declaration] of checker.functionNodes) {
+    callees.set(name, calleesOf(declaration, known));
+  }
+
+  const done = new Set<string>();
+  const stack: string[] = [];
+  const reported = new Set<string>();
+
+  const visit = (name: string): void => {
+    const cycle = stack.indexOf(name);
+    if (cycle >= 0) {
+      const chain = [...stack.slice(cycle), name];
+      const start = chain[0] ?? name;
+      if (!reported.has(start)) {
+        reported.add(start);
+        const declaration = checker.functionNodes.get(start);
+        checker.report('OS2005', declaration?.name.span ?? checker.script.span, {
+          name: start,
+          cycle: chain.join(' calls '),
+        });
+      }
+      return;
+    }
+    if (done.has(name)) return;
+
+    stack.push(name);
+    for (const callee of callees.get(name) ?? []) visit(callee);
+    stack.pop();
+    done.add(name);
+  };
+
+  for (const name of checker.functionNodes.keys()) visit(name);
+}
+
+/**
+ * Checks a body once, the first time anything needs to know what it returns.
+ *
+ * A body is checked in the file scope rather than wherever the call was
+ * written, because a function's enclosing scope is the file whatever line calls
+ * it, and it is checked on demand rather than up front because the file-scope
+ * names it can see are the ones declared above the call (`language.md` 12.5).
+ */
+export function ensureChecked(checker: Checker, id: number): void {
+  const fn = checker.functions[id];
+  if (fn === undefined) return;
+  if (checker.checkedFunctions.has(id) || checker.checkingFunctions.has(id)) return;
+
+  checker.checkingFunctions.add(id);
+  const outer = checker.scope;
+  checker.scope = checker.fileScope;
+  try {
+    checkBody(checker, id, fn.declaration);
+  } finally {
+    checker.scope = outer;
+    checker.checkingFunctions.delete(id);
+    checker.checkedFunctions.add(id);
+  }
+}
+
+/** Collects every declaration and reports any cycle among them, before the file runs. */
+export function checkFunctionDeclarations(checker: Checker, script: Script): void {
+  collectFunctions(checker, script);
+  detectRecursion(checker);
+}
+
+/** The bodies nothing called, so an unused helper still gets its diagnostics. */
+export function checkRemainingFunctions(checker: Checker): void {
+  for (const id of checker.functionsByName.values()) ensureChecked(checker, id);
+}
+
+function checkBody(checker: Checker, id: number, declaration: FunctionDeclaration): void {
+  const fn = checker.functions[id];
+  if (fn === undefined) return;
+
+  const firstBinding = checker.bindings.length;
+  const firstCall = checker.calls.length;
+  const outerReturns = checker.pendingReturns;
+  checker.pendingReturns = [];
+
+  const result = checker.inScope('function', undefined, () => {
+    const parameters = declareParameters(checker, declaration);
+    fn.parameters = parameters;
+    return runBody(checker, declaration.body);
+  });
+
+  const returns = checker.pendingReturns;
+  checker.pendingReturns = outerReturns;
+
+  // A function holds state when its body does, whether the body wrote a `var`
+  // or called something that keeps one (language.md 11.4).
+  const heldVar = checker.bindings
+    .slice(firstBinding)
+    .some((one) => one.persistence !== 'none');
+  const heldCall = checker.calls.slice(firstCall).some((one) => one.stateful);
+  fn.stateful = heldVar || heldCall;
+
+  let type = result.type;
+  let warmup = result.warmup;
+  for (const one of returns) {
+    if (isDefinite(one.type) && isDefinite(type) && !sameType(type, one.type)) {
+      checker.report('OS2003', declaration.span, {
+        leftType: typeText(type),
+        rightType: typeText(one.type),
+      });
+      continue;
+    }
+    type = join(type, one.type);
+    warmup = earlier(warmup, one.warmup);
+  }
+
+  fn.returns = type;
+  fn.warmup = warmup;
+}
+
+/** The parameters, in a scope of the body's own, `language.md` 11.2 and 12.3. */
+function declareParameters(
+  checker: Checker,
+  declaration: FunctionDeclaration,
+): readonly Mutable<Binding>[] {
+  const bindings: Mutable<Binding>[] = [];
+  const seen = new Set<string>();
+
+  for (const parameter of declaration.parameters) {
+    const name = parameter.name.text;
+    if (seen.has(name)) {
+      checker.report('OS2018', parameter.name.span, { name });
+      continue;
+    }
+    seen.add(name);
+
+    const enclosing = checker.enclosing(name);
+    if (enclosing !== undefined) {
+      checker.report('OS2002', parameter.name.span, {
+        name,
+        line: enclosing.declaredAt.line,
+      });
+    } else if (isLibraryName(name)) {
+      checker.report('OS2002', parameter.name.span, { name, line: 'built-in' });
+    }
+
+    const annotated =
+      parameter.annotation === undefined
+        ? undefined
+        : resolveAnnotation(checker, parameter.annotation);
+    const fromDefault =
+      parameter.defaultValue === undefined
+        ? undefined
+        : checkExpression(checker, parameter.defaultValue, TOP_LEVEL);
+
+    // Without an annotation the type is inferred from use (language.md 11.2).
+    // Version 1 of this checker infers only from a default value and otherwise
+    // leaves the parameter open, which reports nothing it cannot prove.
+    const type = annotated ?? fromDefault ?? UNKNOWN;
+    bindings.push(checker.declare(parameter.name, 'parameter', type, BAR_ZERO));
+  }
+
+  return bindings;
+}
+
+/**
+ * Inside a function body, which both spellings of one are.
+ *
+ * The single line form used to be checked as though it stood at the top level,
+ * and the placement is what OS3006 and OS3007 read: `fn f(x) => x + input(3,
+ * "K")` declared a settings row from inside a function, which `language.md`
+ * 13.4 forbids in as many words, and nothing said so. The two forms are the
+ * same construct written two ways and a rule that holds for one holds for both.
+ */
+const INSIDE_A_BODY: Placement = {
+  topLevel: false,
+  construct: 'a function body',
+  inLoop: false,
+};
+
+/**
+ * A body and what it gives back.
+ *
+ * The single line form is one expression. The indented form ends in a bare
+ * expression, which is its value, and a body that ends in something else
+ * returns `none` unless a `return` ran (`language.md` 11.3).
+ */
+function runBody(
+  checker: Checker,
+  body: Block | Expression,
+): { readonly type: Type; readonly warmup: Warmup } {
+  if (body.kind !== 'block') {
+    const type = checkExpression(checker, body, INSIDE_A_BODY);
+    return { type, warmup: checker.warmupOf(body) };
+  }
+
+  checkStatements(checker, body.statements, INSIDE_A_BODY);
+
+  const last = body.statements[body.statements.length - 1];
+  if (last === undefined || last.kind !== 'expressionStatement') {
+    return { type: UNKNOWN, warmup: BAR_ZERO };
+  }
+  return { type: checker.typeOf(last.expression), warmup: checker.warmupOf(last.expression) };
+}

package/src/core/check/handles.ts

@@ -0,0 +1,75 @@
+/**
+ * Where a declaration handle may stand, which is `language.md` 5.4's table.
+ *
+ * `plot()`, `plotCandles()`, `fill()` and `level()` hand back the compile-time
+ * half of a declaration. It is not a value. No slot, no cell and no register
+ * ever holds one, and nothing of it is left in the bar loop, so the places one
+ * may be written are a closed list of three:
+ *
+ *     a declaration statement            plot(close, "C", aqua)
+ *     the whole right side of a plain     upper = plot(basis + dev, "U", aqua)
+ *       assignment, where the right side
+ *       is the declaration call itself
+ *     an argument of a call               fill(upper, lower, color = c)
+ *
+ * The third is a permission to be written, not to be accepted: the signature
+ * decides, and `fill` is the one call in version 1 whose parameters take a
+ * handle. Everywhere else a value is required, and 5.4 answers that with
+ * OS2003.
+ *
+ * The rule is a permission rather than a refusal written out at each of the
+ * twenty places a value can appear, because the refusal has to hold for the
+ * position nobody thought of. An expression the checker accepts and the
+ * emitter cannot emit becomes an instruction reading a slot nothing ever
+ * writes, and a study then plots absence on every bar where the script said
+ * plot. Silence of that kind is worse than a refusal, so the default is to
+ * refuse and the permissions are listed.
+ */
+import type { Expression } from '../ast/index.js';
+import type { Checker } from './checker.js';
+import type { Type } from './types.js';
+import { UNKNOWN, typeText } from './types.js';
+
+/**
+ * What a position holds when it requires a value and fixes no type of its own.
+ *
+ * A `var`, a ternary arm, a `return` and an operand of `==` all want one value
+ * per bar and take any type. What they cannot take is the one thing that has no
+ * per-bar value at all, and that is the sentence OS2003 has to say.
+ */
+const PER_BAR_VALUE = 'a per-bar value';
+
+/**
+ * Marks an expression as one of the places 5.4 lets a handle be written.
+ *
+ * Grouping is transparent to every rule in the language, so `(upper)` is
+ * permitted wherever `upper` is and each layer is marked.
+ */
+export function allowHandle(checker: Checker, expression: Expression): void {
+  let node: Expression = expression;
+  for (;;) {
+    checker.handleSites.add(node);
+    if (node.kind !== 'grouping') return;
+    node = node.expression;
+  }
+}
+
+/** Whether a handle written here has been permitted by one of the three rules. */
+export function handleAllowed(checker: Checker, expression: Expression): boolean {
+  return checker.handleSites.has(expression);
+}
+
+/**
+ * OS2003 for a handle in a position that requires a value, `language.md` 5.4.
+ *
+ * The expression is left `unknown` rather than left as a handle, so the rule
+ * above it does not report a second time and the emitter is never handed a
+ * handle to find a register for.
+ */
+export function refuseHandle(checker: Checker, expression: Expression, type: Type): Type {
+  checker.report('OS2003', expression.span, {
+    leftType: PER_BAR_VALUE,
+    rightType: typeText(type),
+  });
+  return checker.record(expression, UNKNOWN, checker.warmupOf(expression));
+}

package/src/core/check/index.ts

@@ -0,0 +1,67 @@
+/**
+ * The checker: a syntax tree in, and the answer to two questions out.
+ *
+ * Is this a program the engine can run, and what does every name in it mean.
+ * Those are one pass rather than two, because the second question is how the
+ * first one is answered: a name resolves or it does not, an expression has a
+ * type or the operator above it cannot be checked, and a value has a first bar
+ * or a line would be drawn before there was anything to draw.
+ *
+ * What comes out is a `CheckedScript`. It is not a second tree: the syntax tree
+ * is still the tree, and every answer is recorded against the node it is about,
+ * so the code generator walks what the parser produced and looks the answers up
+ * rather than working any of them out a second time.
+ *
+ * Nothing here throws. A file with three mistakes in it produces three
+ * diagnostics and a checked tree with `unknown` where the mistakes were,
+ * because a trader fixing three mistakes should see three of them.
+ */
+export { check } from './check.js';
+export { inputHeldBy } from './checked.js';
+export { alertKey } from './outputs.js';
+export { FOLDABLE_CALLS } from './constant.js';
+
+export type {
+  Binding,
+  BindingKind,
+  CheckedCall,
+  CheckedDeclaration,
+  CheckedFunction,
+  CheckedInput,
+  CheckedOutput,
+  CheckedRequest,
+  CheckedScript,
+  InputKind,
+  RequestMode,
+  Storage,
+} from './checked.js';
+
+export type { HandleKind, ObjectKind, Type, ValueKind } from './types.js';
+export {
+  HANDLE_KINDS,
+  OBJECT_KINDS,
+  VALUE_KINDS,
+  accepts,
+  arrayOf,
+  elementOf,
+  isSeries,
+  join,
+  sameType,
+  seriesOf,
+  typeText,
+} from './types.js';
+
+export type { Warmup } from './warmup.js';
+export { BAR_ZERO, allOf, atBar, atLeastBar, delayed, earlier, isNever, later } from './warmup.js';
+
+export type { LibraryEntry, LibraryParameter, WarmupRule } from './library.js';
+export {
+  NAMESPACES,
+  REQUEST_NAMES,
+  STRATEGY_NAMESPACES,
+  isLibraryName,
+  isNamespace,
+  libraryEntries,
+  libraryNames,
+  membersOf,
+} from './surface.js';

package/src/core/check/library-bars.ts

@@ -0,0 +1,194 @@
+/**
+ * The part of the library that reads a bar, an instrument, a clock or a string:
+ * `stdlib.md` sections 3, 8.2, 10 and 12, plus the nineteen colour names of
+ * section 11.1.
+ *
+ * Nothing here computes across bars, so nothing here has a warmup of its own.
+ * The two exceptions state theirs: a session's start and end are known from the
+ * session's first bar, which is a fact about the data rather than a length.
+ */
+import { DATA_DRIVEN, entry } from './library.js';
+import type { LibraryEntry } from './library.js';
+
+/** The colour names of stdlib.md 11.1, each an ordinary global of type `color`. */
+export const COLOUR_NAMES: readonly string[] = [
+  'aqua',
+  'black',
+  'blue',
+  'brown',
+  'fuchsia',
+  'gray',
+  'green',
+  'lime',
+  'maroon',
+  'navy',
+  'olive',
+  'orange',
+  'pink',
+  'purple',
+  'red',
+  'silver',
+  'teal',
+  'white',
+  'yellow',
+];
+
+/** The built-in series of stdlib.md 3.1, the only names with a bar's history. */
+export const BAR_SERIES: readonly string[] = [
+  'open',
+  'high',
+  'low',
+  'close',
+  'volume',
+  'hl2',
+  'hlc3',
+  'ohlc4',
+  'hlcc4',
+  'oi',
+  'time',
+];
+
+const colours: readonly LibraryEntry[] = COLOUR_NAMES.map((name) => entry(`${name} -> color`));
+
+const series: readonly LibraryEntry[] = [
+  ...BAR_SERIES.map((name) => entry(`${name} -> series number`)),
+  entry('timeClose -> series number', { planned: true }),
+];
+
+const bar: readonly LibraryEntry[] = [
+  entry('bar.index -> series number'),
+  entry('bar.count -> series number'),
+  entry('bar.isFirst -> series bool'),
+  entry('bar.isLast -> series bool'),
+  entry('bar.isConfirmed -> series bool'),
+  entry('bar.isRealtime -> series bool'),
+  entry('bar.isNew -> series bool'),
+  entry('bar.updates -> series number'),
+];
+
+const chart: readonly LibraryEntry[] = [
+  entry('chart.symbol -> string'),
+  entry('chart.exchange -> string'),
+  entry('chart.interval -> string'),
+  entry('chart.intervalMinutes -> number'),
+  entry('chart.isIntraday -> bool'),
+  entry('chart.timezone -> string'),
+  entry('chart.tickSize -> number'),
+  entry('chart.lotSize -> number'),
+  entry('chart.pointValue -> number'),
+  entry('chart.currency -> string'),
+  entry('chart.instrumentType -> string'),
+  entry('chart.hasVolume -> bool'),
+  entry('chart.hasOpenInterest -> bool'),
+  entry('chart.now() -> number'),
+  entry('chart.isReplay -> bool', { planned: true }),
+  entry('chart.expiry -> number', { planned: true }),
+  entry('chart.strike -> number', { planned: true }),
+  entry('chart.optionType -> string', { planned: true }),
+];
+
+/**
+ * The session facts, `stdlib.md` 12.4.
+ *
+ * **Three run and the rest are planned**, and the line between them is what an
+ * engine can answer today. `session.isFirstBar` and `session.isLastBar` are
+ * derived from the session hours in the instrument record
+ * (`host-interface.md` 4.3), the bar's time and the instrument's timezone.
+ * `session.isIn` reads the hours the script itself wrote, and the calendar of
+ * section 12.2 turns them into a test. The rest read the same hours and want
+ * an instant or a count off it rather than a boundary, so they are marked
+ * rather than left to be refused at load with a message about a function.
+ */
+const session: readonly LibraryEntry[] = [
+  entry('session.isOpen -> series bool', { planned: true }),
+  entry('session.isFirstBar -> series bool'),
+  entry('session.isLastBar -> series bool'),
+  entry('session.startTime -> series number', { planned: true, warmup: DATA_DRIVEN }),
+  entry('session.endTime -> series number', { planned: true, warmup: DATA_DRIVEN }),
+  entry('session.barIndex -> series number', { planned: true }),
+  entry('session.isIn(spec: string, zone?: string = chart.timezone) -> series bool'),
+  entry('session.isHoliday(t: number) -> bool', { planned: true }),
+  entry('session.nextOpen -> series number', { planned: true }),
+];
+
+/**
+ * The calendar, `stdlib.md` 12.2.
+ *
+ * Every entry reads a timestamp in a named zone, and the zone table is the
+ * runtime's own rather than one copied here: `calendar/zone.ts` gives the
+ * reason. `date.add` stays planned because calendar arithmetic that respects
+ * month lengths has a rule to settle first, which the entry itself says.
+ */
+const date: readonly LibraryEntry[] = [
+  entry('date.year(t: number, zone?: string = chart.timezone) -> number'),
+  entry('date.month(t: number, zone?: string = chart.timezone) -> number'),
+  entry('date.day(t: number, zone?: string = chart.timezone) -> number'),
+  entry('date.dayOfWeek(t: number, zone?: string = chart.timezone) -> number'),
+  entry('date.dayOfYear(t: number, zone?: string = chart.timezone) -> number'),
+  entry('date.hour(t: number, zone?: string = chart.timezone) -> number'),
+  entry('date.minute(t: number, zone?: string = chart.timezone) -> number'),
+  entry('date.second(t: number, zone?: string = chart.timezone) -> number'),
+  entry('date.weekOfYear(t: number, zone?: string = chart.timezone) -> number'),
+  entry(
+    'date.from(year: number, month: number, day: number, hour?: number = 0, minute?: number = 0, second?: number = 0, zone?: string = chart.timezone) -> number',
+  ),
+  entry('date.startOfDay(t: number, zone?: string = chart.timezone) -> number'),
+  entry('date.startOfWeek(t: number, zone?: string = chart.timezone) -> number'),
+  entry('date.startOfMonth(t: number, zone?: string = chart.timezone) -> number'),
+  entry('date.isSameDay(a: number, b: number, zone?: string = chart.timezone) -> bool'),
+  entry('date.format(t: number, pattern: string, zone?: string = chart.timezone) -> string'),
+  entry('date.add(t: number, unit: string, count: number, zone?: string = chart.timezone) -> number', {
+    planned: true,
+  }),
+];
+
+const maths: readonly LibraryEntry[] = [
+  entry('math.pi -> number'),
+  entry('math.e -> number'),
+  entry('math.log2(x: number) -> number'),
+  entry('math.hypot(x: number, y: number) -> number'),
+  entry('math.toDegrees(x: number) -> number'),
+  entry('math.toRadians(x: number) -> number'),
+  entry('math.sin(x: number) -> number'),
+  entry('math.cos(x: number) -> number'),
+  entry('math.tan(x: number) -> number'),
+  entry('math.asin(x: number) -> number'),
+  entry('math.acos(x: number) -> number'),
+  entry('math.atan(x: number) -> number'),
+  entry('math.atan2(y: number, x: number) -> number'),
+  entry('math.sinh(x: number) -> number', { planned: true }),
+  entry('math.cosh(x: number) -> number', { planned: true }),
+  entry('math.tanh(x: number) -> number', { planned: true }),
+];
+
+const strings: readonly LibraryEntry[] = [
+  entry('str.length(s: string) -> number'),
+  entry('str.upper(s: string) -> string'),
+  entry('str.lower(s: string) -> string'),
+  entry('str.trim(s: string) -> string'),
+  entry('str.contains(s: string, part: string) -> bool'),
+  entry('str.startsWith(s: string, part: string) -> bool'),
+  entry('str.endsWith(s: string, part: string) -> bool'),
+  entry('str.indexOf(s: string, part: string) -> number'),
+  entry('str.substring(s: string, from: number, to?: number = none) -> string'),
+  entry('str.replace(s: string, find: string, with: string) -> string'),
+  entry('str.replaceAll(s: string, find: string, with: string) -> string'),
+  entry('str.split(s: string, separator: string) -> array<string>'),
+  entry('str.join(parts: array<string>, separator: string) -> string'),
+  entry('str.padLeft(s: string, width: number, fill?: string = " ") -> string'),
+  entry('str.padRight(s: string, width: number, fill?: string = " ") -> string'),
+  entry('str.repeat(s: string, n: number) -> string'),
+  entry('str.format(template: string, values: array<string>) -> string', { planned: true }),
+  entry('str.match(s: string, pattern: string) -> bool', { planned: true }),
+];
+
+export const BAR_ENTRIES: readonly LibraryEntry[] = [
+  ...colours,
+  ...series,
+  ...bar,
+  ...chart,
+  ...session,
+  ...date,
+  ...maths,
+  ...strings,
+];