openalgo-script 0.1.0-alpha.1 → 0.4.0

package/src/core/check/conditional.ts

@@ -0,0 +1,143 @@
+/**
+ * Which call sites do not run on every bar.
+ *
+ * `language.md` 11.4 states its rule about a call site rather than about a
+ * statement: a call site that does not execute on a bar leaves its series
+ * absent for that bar and its state untouched. OS8001 is the warning for a
+ * stateful call written in one, so what the warning needs is a fact about where
+ * a call sits in the tree, and that is the whole of what this file works out.
+ *
+ * It is a file rather than a flag carried down the passes because the passes
+ * are the wrong place to keep it. Two of the constructs that skip an operand
+ * are operators rather than statements: the ternary evaluates only the taken
+ * arm (9.5), and `and` and `or` evaluate the right operand only when it can
+ * change the answer (9.4). A third is inside a statement the pass does walk,
+ * where it walks only the bodies: a branch after the first is reached only when
+ * every condition above it was false, so an `else if` condition and a later
+ * `case` arm's values are skipped as readily as the bodies are (10.2 and 10.6).
+ * What an analysis misses there is silent: a real number computed from a subset
+ * of the bars and drawn as though it came from all of them.
+ *
+ * So the question is asked once, of the tree, through the one traversal in
+ * `childrenOf`. `reachOf` says how a node reaches each of its children and has
+ * no default arm, which means a node kind added to the language stops the build
+ * here, at the one place that has to decide whether it can skip a child.
+ */
+import type { AstNode, Call, Script } from '../ast/index.js';
+import { childrenOf } from '../ast/index.js';
+
+/**
+ * How an evaluation of a node reaches one of its children.
+ *
+ * `apart` is a function declaration and everything under it. A body runs when
+ * the function is called, so whether it runs on a bar is a fact about the call
+ * site and not about the line the `fn` was written on, and 11.4 allocates its
+ * state per call site for the same reason.
+ */
+type Reach = 'always' | 'sometimes' | 'apart';
+
+/**
+ * Every call site in the file that a bar can pass without evaluating.
+ *
+ * Calls rather than nodes, because a call site is what 11.4 is about and what
+ * holds state. Kept as the nodes themselves rather than as spans, so the answer
+ * cannot drift from the tree the checker is walking.
+ */
+export function conditionalCalls(script: Script): ReadonlySet<Call> {
+  const found = new Set<Call>();
+  collect(script, false, found);
+  return found;
+}
+
+function collect(node: AstNode, conditional: boolean, found: Set<Call>): void {
+  if (conditional && node.kind === 'call') found.add(node);
+  for (const child of childrenOf(node)) {
+    const reach = reachOf(node, child);
+    collect(child, reach === 'apart' ? false : conditional || reach === 'sometimes', found);
+  }
+}
+
+function reachOf(node: AstNode, child: AstNode): Reach {
+  switch (node.kind) {
+    // 9.5: only the taken arm is evaluated. Both arms and not only the true
+    // one, because a stateful call in the false arm advances only on the bars
+    // the condition failed, which is the same defect wearing the other sign.
+    case 'ternary':
+      return child === node.condition ? 'always' : 'sometimes';
+
+    // 9.4: `and` and `or` evaluate the right operand only when it can change
+    // the answer. Every other operator evaluates both sides.
+    case 'binary':
+      return child === node.right && (node.operator === 'and' || node.operator === 'or')
+        ? 'sometimes'
+        : 'always';
+
+    // 10.2: the first branch is reached on every bar the `if` is, and a branch
+    // after it only when every condition above it was false. A later condition
+    // is inside that, which is why the whole branch is answered for here and
+    // its body separately below.
+    case 'ifStatement':
+      return child === node.branches[0] ? 'always' : 'sometimes';
+    case 'ifBranch':
+      return child === node.condition ? 'always' : 'sometimes';
+    case 'elseBranch':
+      return 'always';
+
+    // 10.6: the same shape. The subject is evaluated once and the first arm's
+    // values are compared on every bar, but a later arm is reached only when
+    // nothing above it matched. Values within one arm are all evaluated.
+    case 'switchStatement':
+      return child === node.subject || child === node.cases[0] ? 'always' : 'sometimes';
+    case 'switchCase':
+      return child === node.body ? 'sometimes' : 'always';
+    case 'switchDefault':
+      return 'always';
+
+    // 10.3 and 10.4: a loop body may run no times at all, and what decides how
+    // many times it runs is evaluated before it does.
+    case 'forRangeStatement':
+    case 'forInStatement':
+    case 'whileStatement':
+      return child === node.body ? 'sometimes' : 'always';
+
+    // 11.4: state is allocated per call site, so the calls in a body belong to
+    // whoever calls the function.
+    case 'functionDeclaration':
+      return 'apart';
+
+    // Everything else evaluates every child it has, every time it is reached.
+    // A call evaluates each of its arguments, including the expression a `req`
+    // reads, which runs on every bar of the series it is read against.
+    case 'script':
+    case 'parameter':
+    case 'versionLine':
+    case 'scriptDeclaration':
+    case 'limitsLine':
+    case 'block':
+    case 'expressionStatement':
+    case 'assignment':
+    case 'varDeclaration':
+    case 'breakStatement':
+    case 'continueStatement':
+    case 'returnStatement':
+    case 'numberLiteral':
+    case 'stringLiteral':
+    case 'booleanLiteral':
+    case 'colorLiteral':
+    case 'noneLiteral':
+    case 'nameReference':
+    case 'missingExpression':
+    case 'arrayLiteral':
+    case 'grouping':
+    case 'unary':
+    case 'call':
+    case 'argument':
+    case 'index':
+    case 'member':
+    case 'namedType':
+    case 'seriesType':
+    case 'arrayType':
+    case 'name':
+      return 'always';
+  }
+}

package/src/core/check/constant.ts

@@ -0,0 +1,127 @@
+/**
+ * Whether an expression is settled before the first bar runs.
+ *
+ * `language.md` 13.2 states the rule once and every option, declaration field
+ * and marker argument follows it: a literal, arithmetic over literals, or a
+ * call to `input()`. A settings dialog and a legend are built before bar 0, so
+ * a field that depended on a bar could not be filled in at the moment the host
+ * needs it, and that is OS3003.
+ *
+ * An `input()` counts because it is resolved before bar 0 as well. The name a
+ * script assigns an input to counts for the same reason, which is what lets
+ * `table(position = corner)` work with `corner` declared above it.
+ *
+ * So does a colour built out of constants, which is the one call in the library
+ * whose result is settled before bar 0 as surely as a literal is. `fade(red, 50)`
+ * is the same four numbers on every bar, it is what a level and a marker are
+ * normally coloured with, and refusing it would leave a script no way to write a
+ * translucent colour in a field that has to be fixed.
+ */
+import type { Expression } from '../ast/index.js';
+import { withoutGrouping } from '../ast/index.js';
+import { inputHeldBy } from './checked.js';
+import type { Checker } from './checker.js';
+import { BAR_SERIES } from './surface.js';
+
+/** The names `math` holds that are numbers rather than functions. */
+const CONSTANT_MEMBERS = new Set(['math.pi', 'math.e']);
+
+/**
+ * The calls that produce a value before the first bar, `stdlib.md` 11.2.
+ *
+ * A colour built out of constants is a constant: `fade(red, 50)` is the same
+ * four numbers on every bar, and a level or a marker declared with one has a
+ * colour to carry. The list is here, beside the rule, because the compiler folds
+ * exactly these and the two have to be one list rather than two. A call this
+ * accepted and the emitter could not fold would reach a declaration field with
+ * nothing to write in it, and the compiler would have to refuse a script that
+ * the checker had already passed.
+ */
+export const FOLDABLE_CALLS: ReadonlySet<string> = new Set([
+  'rgb',
+  'rgba',
+  'fade',
+  'withAlpha',
+  'alpha',
+  'mix',
+]);
+
+export function isCompileTimeConstant(checker: Checker, expression: Expression): boolean {
+  const inner = withoutGrouping(expression);
+  switch (inner.kind) {
+    case 'numberLiteral':
+    case 'stringLiteral':
+    case 'booleanLiteral':
+    case 'colorLiteral':
+    case 'noneLiteral':
+      return true;
+    case 'arrayLiteral':
+      return inner.elements.every((element) => isCompileTimeConstant(checker, element));
+    case 'unary':
+      return isCompileTimeConstant(checker, inner.operand);
+    case 'binary':
+      return (
+        isCompileTimeConstant(checker, inner.left) && isCompileTimeConstant(checker, inner.right)
+      );
+    case 'ternary':
+      return (
+        isCompileTimeConstant(checker, inner.condition) &&
+        isCompileTimeConstant(checker, inner.whenTrue) &&
+        isCompileTimeConstant(checker, inner.whenFalse)
+      );
+    case 'nameReference': {
+      const binding = checker.lookup(inner.name);
+      // A name that holds a setting is one, and a `var` initialised from one is
+      // not: the cell is the setting's value on the first bar and whatever the
+      // bar puts in it after that, so it is fixed before bar 0 only until
+      // something assigns to it (`language.md` 8.2 and 13.4).
+      if (binding !== undefined) return inputHeldBy(binding) !== undefined;
+      // A colour name is an ordinary global of type `color` and never changes.
+      return checker.typeOf(inner).kind === 'color';
+    }
+    case 'member':
+      return CONSTANT_MEMBERS.has(memberPath(inner.object, inner.member.text));
+    case 'call': {
+      const name = calleeName(inner.callee);
+      if (name === 'input') return true;
+      if (name === undefined || !FOLDABLE_CALLS.has(name)) return false;
+      return inner.args.every((argument) => isCompileTimeConstant(checker, argument.value));
+    }
+    default:
+      return false;
+  }
+}
+
+/**
+ * Whether the expression names one of the price series an `input` may default
+ * to, `stdlib.md` 13.1.
+ *
+ * A source input is the one place a bar series stands where a constant is
+ * otherwise required: `input(close, "Source")` does not read `close`, it names
+ * which column the study is to read, and the host resolves that before bar 0
+ * exactly as it resolves a number.
+ */
+export function isSourceName(expression: Expression): boolean {
+  const inner = withoutGrouping(expression);
+  return inner.kind === 'nameReference' && BAR_SERIES.includes(inner.name);
+}
+
+function memberPath(object: Expression, member: string): string {
+  const inner = withoutGrouping(object);
+  return inner.kind === 'nameReference' ? `${inner.name}.${member}` : member;
+}
+
+function calleeName(callee: Expression): string | undefined {
+  const inner = withoutGrouping(callee);
+  if (inner.kind === 'nameReference') return inner.name;
+  if (inner.kind === 'member') {
+    const object = withoutGrouping(inner.object);
+    if (object.kind === 'nameReference') return `${object.name}.${inner.member.text}`;
+  }
+  return undefined;
+}
+
+/** The dotted name a callee spells, or nothing when it is not a name at all. */
+export function calleeNameOf(callee: Expression): string | undefined {
+  return calleeName(callee);
+}

package/src/core/check/declaration.ts

@@ -0,0 +1,230 @@
+/**
+ * The three lines that describe the file rather than compute anything: the
+ * version line, the `study()` or `strategy()` declaration, and `limits()`.
+ *
+ * Every option of both declarations is written out here once, from
+ * `language.md` 13.2 and 13.3, which are the only place either is defined. They
+ * are written as ordinary library signatures so that the same argument checking
+ * runs over them as over any other call: the option that does not exist, the
+ * one given twice, the one given a bar-dependent value. A second, private way
+ * of checking arguments would be a second set of behaviours to keep in step.
+ */
+import type { Expression, LimitsLine, Script, ScriptDeclaration } from '../ast/index.js';
+import { withoutGrouping } from '../ast/index.js';
+import { bindArguments } from './arguments.js';
+import { validateArguments } from './calls.js';
+import { literalNumber } from './literals.js';
+import type { Checker } from './checker.js';
+import { TOP_LEVEL } from './checker.js';
+import { checkExpression } from './expressions.js';
+import { entry, wholeRange } from './library.js';
+import type { LibraryEntry } from './library.js';
+import { CATALOGUE_LANGUAGE_VERSION } from '../catalogue/index.js';
+
+const STUDY_OPTIONS =
+  'title: string, short?: string, overlay?: bool, precision?: number, format?: string, ' +
+  'range?: array<number>, scale?: string, group?: string, onUnconfirmed?: bool';
+
+const STRATEGY_OPTIONS =
+  'capital?: number, currency?: string, qty?: number, qtyType?: string, product?: string, ' +
+  'fillOn?: string, slippage?: number, commission?: number, commissionType?: string, ' +
+  'pyramiding?: number, closeOnSessionEnd?: bool';
+
+const SHARED = {
+  values: {
+    format: ['price', 'percent', 'volume'],
+    scale: ['right', 'left', 'none'],
+    qtyType: ['units', 'lots', 'cash', 'equityPercent'],
+    product: ['intraday', 'overnight'],
+    fillOn: ['nextOpen', 'close'],
+    commissionType: ['perTrade', 'perUnit', 'percent'],
+  },
+  whole: { precision: wholeRange(0, 10), pyramiding: wholeRange(1) },
+} as const;
+
+/** Every option value is read once, before the first bar, so all are constant. */
+function constantNames(signature: string): readonly string[] {
+  return signature
+    .split(',')
+    .map((part) => part.split(':')[0]?.trim().replace('?', '') ?? '')
+    .filter((name) => name.length > 0);
+}
+
+const STUDY: LibraryEntry = entry(`study(${STUDY_OPTIONS}) -> nothing`, {
+  ...SHARED,
+  constant: constantNames(STUDY_OPTIONS),
+});
+
+const STRATEGY: LibraryEntry = entry(
+  `strategy(${STUDY_OPTIONS}, ${STRATEGY_OPTIONS}) -> nothing`,
+  {
+    ...SHARED,
+    constant: [...constantNames(STUDY_OPTIONS), ...constantNames(STRATEGY_OPTIONS)],
+  },
+);
+
+/** The options of `limits()`, `language.md` 10.7. */
+const LIMITS: LibraryEntry = entry('limits(loops?: number, history?: number) -> nothing');
+
+/**
+ * Finds the file's declaration and reads the two options every later rule needs.
+ *
+ * This runs before anything else is checked, because OS7001 has to know whether
+ * the file is a strategy and OS8002 has to know whether it runs on a bar that
+ * is still moving, and both questions are asked of lines above the declaration
+ * as readily as of lines below it.
+ */
+export function readHeader(checker: Checker, script: Script): void {
+  const declarations = script.items.filter(
+    (item): item is ScriptDeclaration => item.kind === 'scriptDeclaration',
+  );
+  const first = declarations[0];
+
+  if (first === undefined) {
+    checker.report('OS2007', script.span, {});
+  } else {
+    checker.declaration = {
+      node: first,
+      form: first.form,
+      title: stringOption(first, 'title', 0) ?? '',
+      options: optionsOf(first),
+      overlay: booleanOption(first, 'overlay') === true,
+      onUnconfirmed: booleanOption(first, 'onUnconfirmed') === true,
+    };
+  }
+
+  for (const extra of declarations.slice(1)) {
+    checker.report('OS2008', extra.span, {
+      kind: first?.form ?? extra.form,
+      line: first?.span.line ?? extra.span.line,
+    });
+  }
+
+  if (!script.items.some((item) => item.kind === 'versionLine')) {
+    checker.report('OS8003', script.span, { version: CATALOGUE_LANGUAGE_VERSION });
+  }
+}
+
+/** The declaration's own arguments, checked where the declaration is written. */
+export function checkDeclaration(checker: Checker, node: ScriptDeclaration): void {
+  for (const argument of node.args) checkExpression(checker, argument.value, TOP_LEVEL);
+
+  const shape = node.form === 'strategy' ? STRATEGY : STUDY;
+  const parameters = shape.parameters.map((one) => ({
+    name: one.name,
+    optional: one.optional,
+  }));
+  const filled = bindArguments(checker, node.span, node.args, node.form, parameters);
+  validateArguments(checker, shape, filled, new Map());
+  checkRangeOption(checker, shape, filled);
+}
+
+/**
+ * `range = [min, max]`, which is two numbers with the first below the second.
+ *
+ * OS3016 rather than OS3011, because the shape is right and the contents are
+ * not, and a reader given "array<number> was expected" would look at the wrong
+ * thing.
+ */
+function checkRangeOption(
+  checker: Checker,
+  shape: LibraryEntry,
+  filled: readonly ({ readonly value: Expression; readonly span: unknown } | undefined)[],
+): void {
+  const index = shape.parameters.findIndex((one) => one.name === 'range');
+  const argument = index < 0 ? undefined : filled[index];
+  if (argument === undefined) return;
+
+  const literal = withoutGrouping(argument.value);
+  if (literal.kind !== 'arrayLiteral') return;
+
+  const low = literal.elements[0] === undefined ? undefined : literalNumber(literal.elements[0]);
+  const high = literal.elements[1] === undefined ? undefined : literalNumber(literal.elements[1]);
+  const wrong =
+    literal.elements.length !== 2 ||
+    low === undefined ||
+    high === undefined ||
+    low >= high;
+  if (!wrong) return;
+
+  checker.report('OS3016', literal.span, {
+    low: literal.elements[0] === undefined ? '' : checker.textOf(literal.elements[0].span),
+    high: literal.elements[1] === undefined ? '' : checker.textOf(literal.elements[1].span),
+  });
+}
+
+/**
+ * `limits()`, which appears at most once and immediately after the declaration.
+ *
+ * Its values are literal numbers rather than compile-time constants, because
+ * the host is asked whether it will run them before the program is loaded and
+ * an `input()` is not resolved that early.
+ */
+export function checkLimits(
+  checker: Checker,
+  node: LimitsLine,
+  script: Script,
+  seen: boolean,
+): void {
+  for (const argument of node.args) checkExpression(checker, argument.value, TOP_LEVEL);
+
+  const parameters = LIMITS.parameters.map((one) => ({
+    name: one.name,
+    optional: one.optional,
+  }));
+  const filled = bindArguments(checker, node.span, node.args, 'limits', parameters);
+  validateArguments(checker, LIMITS, filled, new Map());
+
+  if (seen || !immediatelyAfterDeclaration(script, node)) {
+    checker.report('OS3014', node.span, { line: node.span.line });
+  }
+
+  for (let i = 0; i < LIMITS.parameters.length; i += 1) {
+    const parameter = LIMITS.parameters[i];
+    const argument = filled[i];
+    if (parameter === undefined || argument === undefined) continue;
+    if (literalNumber(argument.value) === undefined) {
+      checker.report('OS3015', argument.span, { option: parameter.name });
+    }
+  }
+}
+
+function immediatelyAfterDeclaration(script: Script, node: LimitsLine): boolean {
+  const index = script.items.indexOf(node);
+  const before = index <= 0 ? undefined : script.items[index - 1];
+  return before?.kind === 'scriptDeclaration';
+}
+
+function optionsOf(node: ScriptDeclaration): ReadonlyMap<string, Expression> {
+  const options = new Map<string, Expression>();
+  let positional = 0;
+  for (const argument of node.args) {
+    if (argument.label === undefined) {
+      if (positional === 0) options.set('title', argument.value);
+      positional += 1;
+      continue;
+    }
+    options.set(argument.label.text, argument.value);
+  }
+  return options;
+}
+
+function stringOption(
+  node: ScriptDeclaration,
+  name: string,
+  position: number,
+): string | undefined {
+  const labelled = node.args.find((one) => one.label?.text === name);
+  const positional = node.args.filter((one) => one.label === undefined)[position];
+  const chosen = labelled ?? positional;
+  if (chosen === undefined) return undefined;
+  const inner = withoutGrouping(chosen.value);
+  return inner.kind === 'stringLiteral' ? inner.value : undefined;
+}
+
+function booleanOption(node: ScriptDeclaration, name: string): boolean | undefined {
+  const labelled = node.args.find((one) => one.label?.text === name);
+  if (labelled === undefined) return undefined;
+  const inner = withoutGrouping(labelled.value);
+  return inner.kind === 'booleanLiteral' ? inner.value : undefined;
+}