openalgo-script 0.1.0-alpha.0 → 0.2.0

package/src/core/check/statements.ts

@@ -0,0 +1,465 @@
+/**
+ * Checking a statement: what it declares, what it updates, and what it says
+ * about the bars it runs on.
+ *
+ * The two rules of `language.md` 12.2 are the whole of scoping and they are
+ * both here. A name is declared by its first assignment in a scope, and an
+ * assignment to a name an enclosing scope already holds updates that name
+ * rather than making a second one. Everything else about names follows from
+ * those two: there is no shadowing to allow because there is no syntax that
+ * could ask for it, and a name assigned inside a block and read outside it is
+ * OS2001 rather than an absent value.
+ */
+import type {
+  Assignment,
+  Block,
+  Expression,
+  ForInStatement,
+  ForRangeStatement,
+  IfStatement,
+  Name,
+  Statement,
+  SwitchStatement,
+  TypeAnnotation,
+  VarDeclaration,
+  WhileStatement,
+} from '../ast/index.js';
+import { isObjectTypeName, isValueTypeName, typeAnnotationText, withoutGrouping } from '../ast/index.js';
+import { literalNumber } from './literals.js';
+import type { Checker, Placement } from './checker.js';
+import type { CheckedCall } from './checked.js';
+import { checkCondition, checkExpression } from './expressions.js';
+import { allowHandle } from './handles.js';
+import { isLibraryName } from './surface.js';
+import type { Type } from './types.js';
+import {
+  HANDLE_KINDS,
+  NUMBER,
+  UNKNOWN,
+  arrayOf,
+  canBeArrayElement,
+  compatible,
+  elementOf,
+  isDefinite,
+  join,
+  objectType,
+  sameType,
+  seriesOf,
+  typeText,
+} from './types.js';
+import { BAR_ZERO, earlier } from './warmup.js';
+
+/** Runs a block's statements in a scope of their own, `language.md` 12.1. */
+export function checkBlock(checker: Checker, block: Block, placement: Placement): void {
+  checker.inScope('block', undefined, () => {
+    checkStatements(checker, block.statements, placement);
+  });
+}
+
+/** A run of statements, with the one thing that is about the run: reachability. */
+export function checkStatements(
+  checker: Checker,
+  statements: readonly { readonly kind: string }[],
+  placement: Placement,
+): void {
+  let returned = false;
+  for (const statement of statements) {
+    if (statement.kind === 'functionDeclaration') continue;
+    if (returned) {
+      checker.report('OS8016', (statement as Statement).span, {
+        line: (statement as Statement).span.line,
+      });
+      returned = false;
+    }
+    checkStatement(checker, statement as Statement, placement);
+    if (statement.kind === 'returnStatement') returned = true;
+  }
+}
+
+export function checkStatement(
+  checker: Checker,
+  statement: Statement,
+  placement: Placement,
+): void {
+  switch (statement.kind) {
+    case 'versionLine':
+    case 'scriptDeclaration':
+    case 'limitsLine':
+      // The header is read before anything else runs; see declaration.ts.
+      return;
+    case 'expressionStatement':
+      // A declaration written for its effect, `plot(close, "C")`, is a call
+      // whose result is a handle nobody named (`language.md` 5.4).
+      if (withoutGrouping(statement.expression).kind === 'call') {
+        allowHandle(checker, statement.expression);
+      }
+      checkExpression(checker, statement.expression, placement);
+      return;
+    case 'assignment':
+      checkAssignment(checker, statement, placement);
+      return;
+    case 'varDeclaration':
+      checkVar(checker, statement, placement);
+      return;
+    case 'ifStatement':
+      checkIf(checker, statement, placement);
+      return;
+    case 'forRangeStatement':
+      checkForRange(checker, statement, placement);
+      return;
+    case 'forInStatement':
+      checkForIn(checker, statement, placement);
+      return;
+    case 'whileStatement':
+      checkWhile(checker, statement, placement);
+      return;
+    case 'switchStatement':
+      checkSwitch(checker, statement, placement);
+      return;
+    case 'breakStatement':
+    case 'continueStatement':
+      return;
+    case 'returnStatement': {
+      if (statement.value === undefined) return;
+      const type = checkExpression(checker, statement.value, placement);
+      checker.pendingReturns.push({ type, warmup: checker.warmupOf(statement.value) });
+      return;
+    }
+  }
+}
+
+/** The placement inside a construct, for OS3006's message. */
+function inside(placement: Placement, construct: string, loop = false): Placement {
+  return {
+    topLevel: false,
+    construct,
+    inLoop: placement.inLoop || loop,
+  };
+}
+
+function checkAssignment(checker: Checker, statement: Assignment, placement: Placement): void {
+  const target = statement.target;
+  // `upper = plot(...)` names a declaration, which is the one assignment a
+  // handle may stand in (`language.md` 5.4). A second name for a handle that
+  // already has one is not a declaration and has nothing to store, so only the
+  // call itself is allowed here.
+  if (statement.operator === '=' && withoutGrouping(statement.value).kind === 'call') {
+    allowHandle(checker, statement.value);
+  }
+  const type = checkExpression(checker, statement.value, placement);
+  const warmup = checker.warmupOf(statement.value);
+
+  if (checker.loopVariableNamed(target.text)) {
+    checker.report('OS2006', target.span, { name: target.text });
+    return;
+  }
+
+  const { binding: existing, crossedFunction } = checker.lookupAcross(target.text);
+  if (existing !== undefined) {
+    if (crossedFunction) {
+      checker.report('OS2002', target.span, {
+        name: target.text,
+        line: existing.declaredAt.line,
+      });
+      return;
+    }
+    checker.targets.set(target, existing);
+    updateType(checker, target, existing.type, type, (fixed) => {
+      existing.type = fixed;
+    });
+    existing.warmup = earlier(existing.warmup, warmup);
+    checker.holdsMultiOutput(existing.id, callHeldBy(checker, statement.value));
+    return;
+  }
+
+  // A built-in lives in the global scope, so assigning to one is a shadowing
+  // attempt and is OS2002 (language.md 12.4).
+  if (isLibraryName(target.text)) {
+    checker.report('OS2002', target.span, { name: target.text, line: 'built-in' });
+    return;
+  }
+
+  if (statement.operator !== '=') {
+    checker.report('OS2001', target.span, {
+      name: target.text,
+      suggestion: checker.suggestionFor(target.text),
+    });
+  }
+
+  const kind = checker.scope === checker.fileScope ? 'file' : 'block';
+  const binding = checker.declare(target, kind, type, warmup);
+  const inner = withoutGrouping(statement.value);
+  checker.holdsMultiOutput(binding.id, callHeldBy(checker, statement.value));
+  if (inner.kind === 'call') {
+    const call = checker.callSites.get(inner);
+    if (call?.name === 'input') adoptInput(checker, binding.id, target.text);
+    if (type.kind === 'handle') binding.handle = type.handle;
+  }
+}
+
+/** The library call a name is being given, where it is given one directly. */
+function callHeldBy(checker: Checker, value: Expression): CheckedCall | undefined {
+  const inner = withoutGrouping(value);
+  return inner.kind === 'call' ? checker.callSites.get(inner) : undefined;
+}
+
+/**
+ * Gives the input the name it was assigned to, which is also its default title.
+ *
+ * Called from both spellings that put a name in front of an `input()`, because
+ * the key is what the row is stored under and a `var` does not rename a row.
+ * Whether the name then *is* the input, which decides its slot and whether a
+ * declaration option may fold it, is the separate question `inputHeldBy` asks.
+ */
+function adoptInput(checker: Checker, bindingId: number, name: string): void {
+  const input = checker.inputs[checker.inputs.length - 1];
+  const binding = checker.bindings[bindingId];
+  if (input === undefined || binding === undefined) return;
+  input.name = name;
+  if (input.title === '') input.title = name;
+  binding.input = input.id;
+}
+
+/**
+ * The rule of `language.md` 10.1: the first definite assignment fixes the type.
+ *
+ * `none` is a member of every type, so an assignment of `none` carries nothing
+ * to fix a type with and the name waits for the next one. A name that is never
+ * given a definite type is of type `none`, which is legal wherever `none` is.
+ */
+function updateType(
+  checker: Checker,
+  target: Name,
+  current: Type,
+  given: Type,
+  fix: (type: Type) => void,
+): void {
+  if (!isDefinite(given)) return;
+  if (!isDefinite(current)) {
+    fix(given);
+    return;
+  }
+  if (!sameType(current, given)) {
+    checker.report('OS2003', target.span, {
+      leftType: typeText(current),
+      rightType: typeText(given),
+    });
+    return;
+  }
+  fix(join(current, given));
+}
+
+function checkVar(checker: Checker, statement: VarDeclaration, placement: Placement): void {
+  const initial = checkExpression(checker, statement.initialiser, placement);
+  const annotated =
+    statement.annotation === undefined
+      ? undefined
+      : resolveAnnotation(checker, statement.annotation);
+
+  const name = statement.name;
+  const enclosing = checker.enclosing(name.text);
+  if (enclosing !== undefined) {
+    checker.report('OS2002', name.span, { name: name.text, line: enclosing.declaredAt.line });
+  } else if (isLibraryName(name.text)) {
+    checker.report('OS2002', name.span, { name: name.text, line: 'built-in' });
+  } else if (checker.scope.names.has(name.text)) {
+    const existing = checker.scope.names.get(name.text);
+    checker.report('OS2002', name.span, {
+      name: name.text,
+      line: existing?.declaredAt.line ?? name.span.line,
+    });
+  }
+
+  let type = annotated ?? initial;
+  if (annotated !== undefined && isDefinite(initial) && !sameType(annotated, initial)) {
+    checker.report('OS2003', statement.span, {
+      leftType: typeText(annotated),
+      rightType: typeText(initial),
+    });
+    type = annotated;
+  }
+
+  const kind = checker.scope === checker.fileScope ? 'file' : 'block';
+  const binding = checker.declare(
+    name,
+    kind,
+    type,
+    checker.warmupOf(statement.initialiser),
+    statement.live ? 'live' : 'var',
+  );
+  // `var len = input(14, "Length")` declares one settings row like any other,
+  // and the name it is written under is that row's key and its label
+  // (`host-interface.md` 8.1). What `var` decides is where the value lives, not
+  // what the row is called, so adding or removing the word leaves a user's
+  // stored value on the row they stored it for. The name does not become the
+  // input: `inputHeldBy` is where that half is answered.
+  const written = withoutGrouping(statement.initialiser);
+  if (written.kind === 'call' && checker.callSites.get(written)?.name === 'input') {
+    adoptInput(checker, binding.id, name.text);
+  }
+  if (statement.live) checker.report('OS8011', name.span, { name: name.text });
+}
+
+/** A type as written, `language.md` 5.1 and 14.1. OS2016 and OS2019 live here. */
+export function resolveAnnotation(checker: Checker, annotation: TypeAnnotation): Type {
+  switch (annotation.kind) {
+    case 'namedType': {
+      if (isValueTypeName(annotation.name)) return { kind: annotation.name };
+      if (isObjectTypeName(annotation.name)) return objectType(annotation.name);
+      checker.report('OS2016', annotation.span, { type: typeAnnotationText(annotation) });
+      return UNKNOWN;
+    }
+    case 'seriesType':
+      return seriesOf(resolveAnnotation(checker, annotation.element));
+    case 'arrayType': {
+      // A declaration handle and a series are refused here rather than being
+      // resolved first, because OS2016 would say the word is not a type and it
+      // is: the answer the reader needs is that an array cannot hold one.
+      const written = typeAnnotationText(annotation.element);
+      const handle = (HANDLE_KINDS as readonly string[]).includes(written);
+      if (handle || annotation.element.kind === 'seriesType') {
+        checker.report('OS2019', annotation.span, { type: written });
+        return UNKNOWN;
+      }
+      const element = resolveAnnotation(checker, annotation.element);
+      if (!canBeArrayElement(element)) {
+        checker.report('OS2019', annotation.span, { type: written });
+        return UNKNOWN;
+      }
+      return arrayOf(element);
+    }
+  }
+}
+
+function checkIf(checker: Checker, statement: IfStatement, placement: Placement): void {
+  for (const branch of statement.branches) {
+    checkCondition(checker, branch.condition, placement);
+    reportConstantCondition(checker, branch.condition);
+    checkBlock(checker, branch.body, inside(placement, 'an if block'));
+  }
+  if (statement.elseBranch !== undefined) {
+    checkBlock(checker, statement.elseBranch.body, inside(placement, 'an else block'));
+  }
+}
+
+function reportConstantCondition(checker: Checker, condition: Expression): void {
+  const inner = withoutGrouping(condition);
+  if (inner.kind !== 'booleanLiteral') return;
+  checker.report('OS8017', condition.span, { value: String(inner.value) });
+}
+
+function checkForRange(
+  checker: Checker,
+  statement: ForRangeStatement,
+  placement: Placement,
+): void {
+  checkNumeric(checker, statement.from, placement);
+  checkNumeric(checker, statement.to, placement);
+  if (statement.step !== undefined) checkNumeric(checker, statement.step, placement);
+
+  const from = literalNumber(statement.from);
+  const to = literalNumber(statement.to);
+  const step = statement.step === undefined ? 1 : literalNumber(statement.step);
+
+  if (statement.step !== undefined && step === 0) {
+    checker.report('OS3004', statement.step.span, {
+      name: 'for',
+      argument: 'step',
+      range: 'other than zero',
+      found: 0,
+    });
+  } else if (from !== undefined && to !== undefined && step !== undefined && step !== 0) {
+    const runs = step > 0 ? from <= to : from >= to;
+    if (!runs) {
+      checker.report('OS8015', statement.span, { start: from, end: to, step });
+    }
+  }
+
+  runLoop(checker, statement.variable, NUMBER, statement.body, placement);
+}
+
+function checkForIn(checker: Checker, statement: ForInStatement, placement: Placement): void {
+  const iterable = checkExpression(checker, statement.iterable, placement);
+  const array = elementOf(iterable);
+  if (array.kind !== 'array' && array.kind !== 'unknown') {
+    checker.report('OS2003', statement.iterable.span, {
+      leftType: typeText(arrayOf(UNKNOWN)),
+      rightType: typeText(iterable),
+    });
+  }
+  const element = array.kind === 'array' ? array.element : UNKNOWN;
+  runLoop(checker, statement.variable, element, statement.body, placement);
+}
+
+/** The loop variable's scope is the body's, and assigning to it is OS2006. */
+function runLoop(
+  checker: Checker,
+  variable: Name,
+  type: Type,
+  body: Block,
+  placement: Placement,
+): void {
+  const enclosing = checker.lookup(variable.text);
+  if (enclosing !== undefined) {
+    checker.report('OS2002', variable.span, {
+      name: variable.text,
+      line: enclosing.declaredAt.line,
+    });
+  } else if (isLibraryName(variable.text)) {
+    checker.report('OS2002', variable.span, { name: variable.text, line: 'built-in' });
+  }
+
+  checker.inScope('block', variable.text, () => {
+    checker.declare(variable, 'loop', type, BAR_ZERO);
+    checkStatements(checker, body.statements, inside(placement, 'a loop body', true));
+  });
+}
+
+function checkWhile(checker: Checker, statement: WhileStatement, placement: Placement): void {
+  checkCondition(checker, statement.condition, placement);
+  checkBlock(checker, statement.body, inside(placement, 'a loop body', true));
+}
+
+function checkNumeric(checker: Checker, expression: Expression, placement: Placement): void {
+  const type = checkExpression(checker, expression, placement);
+  if (elementOf(type).kind === 'number' || !isDefinite(type)) return;
+  checker.report('OS2003', expression.span, {
+    leftType: typeText(NUMBER),
+    rightType: typeText(type),
+  });
+}
+
+/**
+ * `switch` in both forms of `language.md` 10.6.
+ *
+ * With a subject, each case value is compared against it and has to be its
+ * type. Without one, each case value is a condition and has to be a bool. The
+ * absent subject is the whole difference between the two forms.
+ */
+function checkSwitch(checker: Checker, statement: SwitchStatement, placement: Placement): void {
+  const subject =
+    statement.subject === undefined
+      ? undefined
+      : checkExpression(checker, statement.subject, placement);
+
+  for (const arm of statement.cases) {
+    for (const value of arm.values) {
+      if (subject === undefined) {
+        checkCondition(checker, value, placement);
+        continue;
+      }
+      const type = checkExpression(checker, value, placement);
+      if (!compatible(subject, type)) {
+        checker.report('OS2003', value.span, {
+          leftType: typeText(subject),
+          rightType: typeText(type),
+        });
+      }
+    }
+    checkBlock(checker, arm.body, inside(placement, 'a case arm'));
+  }
+
+  if (statement.defaultCase !== undefined) {
+    checkBlock(checker, statement.defaultCase.body, inside(placement, 'a default arm'));
+  }
+}

package/src/core/check/suggest.ts

@@ -0,0 +1,63 @@
+/**
+ * The near name a diagnostic offers when something was not found.
+ *
+ * Five codes promise one: OS2001, OS2009, OS2010, OS3002 and OS3008 each carry
+ * a `suggestion` slot documented as the closest candidate by edit distance. So
+ * the answer is the closest one and not the closest one within some threshold:
+ * a threshold would leave the slot with nothing to put in it, and a message
+ * with a hole in it is a defect a reader cannot report.
+ *
+ * The distance is Levenshtein over code units, computed with two rows rather
+ * than a matrix because this runs once per unresolved name against every name
+ * in scope, and an editor asks for it while somebody is still typing.
+ */
+
+/** The edit distance between two names, capped so a hopeless pair costs little. */
+export function editDistance(left: string, right: string): number {
+  if (left === right) return 0;
+  if (left.length === 0) return right.length;
+  if (right.length === 0) return left.length;
+
+  let previous = Array.from({ length: right.length + 1 }, (_unused, index) => index);
+  let current = new Array<number>(right.length + 1).fill(0);
+
+  for (let i = 1; i <= left.length; i += 1) {
+    current[0] = i;
+    for (let j = 1; j <= right.length; j += 1) {
+      const substitution = (previous[j - 1] ?? 0) + (left[i - 1] === right[j - 1] ? 0 : 1);
+      const deletion = (previous[j] ?? 0) + 1;
+      const insertion = (current[j - 1] ?? 0) + 1;
+      current[j] = Math.min(substitution, deletion, insertion);
+    }
+    const swap = previous;
+    previous = current;
+    current = swap;
+  }
+
+  return previous[right.length] ?? Math.max(left.length, right.length);
+}
+
+/**
+ * The closest candidate, or the written name when there are no candidates.
+ *
+ * Returning the written name happens only where a namespace holds nothing,
+ * which the library never does, so it is a floor rather than an outcome. Case
+ * is folded before comparing, because a name written with the wrong capital is
+ * the commonest near miss of all and costs a full edit distance otherwise.
+ */
+export function closestName(written: string, candidates: Iterable<string>): string {
+  const target = written.toLowerCase();
+  let best = written;
+  let bestDistance = Number.POSITIVE_INFINITY;
+
+  for (const candidate of candidates) {
+    if (candidate === written) continue;
+    const distance = editDistance(target, candidate.toLowerCase());
+    if (distance < bestDistance) {
+      best = candidate;
+      bestDistance = distance;
+    }
+  }
+
+  return best;
+}

package/src/core/check/surface.ts

@@ -0,0 +1,115 @@
+/**
+ * The library as one surface, and the questions the checker asks of it.
+ *
+ * The four data files are split by what a call does rather than by anything the
+ * checker cares about, so that each one sits beside the section of `stdlib.md`
+ * it was transcribed from and a reader can check them against each other a
+ * table at a time.
+ *
+ * Two names carry more than one entry on purpose. `close` is a built-in series
+ * read bare and an order function written with brackets (`stdlib.md` 3.2), and
+ * `clear` empties an array or a grid depending on what it is handed (14.3). The
+ * index holds a list per name for exactly this, and a call site picks by arity
+ * and by argument type, at compile time, with no run-time dispatch anywhere.
+ */
+import { BAR_ENTRIES, COLOUR_NAMES } from './library-bars.js';
+import { ORDER_ENTRIES, ORDER_NAMES } from './library-orders.js';
+import { OUTPUT_ENTRIES, REQUEST_NAMES, TOP_LEVEL_NAMES } from './library-output.js';
+import { SERIES_ENTRIES } from './library-series.js';
+import { indexOf } from './library.js';
+import type { LibraryEntry, LibraryIndex } from './library.js';
+
+export { BAR_SERIES, COLOUR_NAMES } from './library-bars.js';
+export { ORDER_NAMES } from './library-orders.js';
+export { REQUEST_NAMES, TOP_LEVEL_NAMES } from './library-output.js';
+
+/**
+ * The closed list of namespaces, `language.md` 15.2.
+ *
+ * A dotted name whose first part is not one of these is not a namespace read at
+ * all: it is a member of a value, and version 1 has no such thing, so the
+ * checker can say so instead of guessing which of the two the writer meant.
+ */
+export const NAMESPACES: readonly string[] = [
+  'bar',
+  'chart',
+  'session',
+  'date',
+  'str',
+  'math',
+  'pos',
+  'order',
+  'leg',
+  'book',
+  'draw',
+  'req',
+];
+
+/** The namespaces that exist only in a `strategy()` file, `language.md` 15.2. */
+export const STRATEGY_NAMESPACES: readonly string[] = ['pos', 'order', 'leg', 'book'];
+
+const ENTRIES: readonly LibraryEntry[] = [
+  ...BAR_ENTRIES,
+  ...SERIES_ENTRIES,
+  ...OUTPUT_ENTRIES,
+  ...ORDER_ENTRIES,
+];
+
+const INDEX: LibraryIndex = indexOf(ENTRIES);
+
+/** Every signature of one name, or nothing when the library has no such name. */
+export function libraryEntries(name: string): readonly LibraryEntry[] {
+  return INDEX.get(name) ?? [];
+}
+
+export function isLibraryName(name: string): boolean {
+  return INDEX.has(name);
+}
+
+/** Every name in the global scope, for the "did you mean" of OS2001 and OS2010. */
+export function libraryNames(): readonly string[] {
+  return [...INDEX.keys()];
+}
+
+/** The members of one namespace, spelled bare, for OS2009's suggestion. */
+export function membersOf(namespace: string): readonly string[] {
+  const prefix = `${namespace}.`;
+  return libraryNames()
+    .filter((name) => name.startsWith(prefix))
+    .map((name) => name.slice(prefix.length));
+}
+
+export function isNamespace(name: string): boolean {
+  return NAMESPACES.includes(name);
+}
+
+export function isColourName(name: string): boolean {
+  return COLOUR_NAMES.includes(name);
+}
+
+/** Whether every entry of a name is only available in a `strategy()` file. */
+export function isStrategyOnly(name: string): boolean {
+  const entries = libraryEntries(name);
+  return entries.length > 0 && entries.every((one) => one.strategyOnly);
+}
+
+/** Whether the name is a bare order function, which `close` is one spelling of. */
+export function isOrderName(name: string): boolean {
+  return ORDER_NAMES.includes(name) || name.startsWith('order.');
+}
+
+/** Whether the call is one of the two higher timeframe reads of stdlib.md 15.1. */
+export function isRequestName(name: string): boolean {
+  return REQUEST_NAMES.includes(name);
+}
+
+/**
+ * Whether the call declares part of the file's fixed shape.
+ *
+ * `input` is deliberately not in this list. Its refusal is OS3007 rather than
+ * OS3006 because the fix is different: a plot has to move out of the branch,
+ * and an input has to move out and be read from inside it.
+ */
+export function isTopLevelOnly(name: string): boolean {
+  return TOP_LEVEL_NAMES.includes(name);
+}