openalgo-script 0.1.0-alpha.1 → 0.2.0

package/src/core/check/calls.ts

@@ -0,0 +1,412 @@
+/**
+ * Resolving a call: which signature it means, whether what was written fits it,
+ * and what comes back.
+ *
+ * The arguments have already been checked as expressions by the time this runs,
+ * so everything here reads their recorded types and warmups. That is what keeps
+ * this file out of a cycle with the expression pass, and it is also the order
+ * a reader expects: the inner expressions are wrong or they are not, before
+ * anything asks whether they fit the call.
+ *
+ * Overload resolution is by arity and then by argument type, which is the whole
+ * of `stdlib.md` 2.2. It happens once, here, and there is no run-time dispatch.
+ */
+import type { Argument, Call } from '../ast/index.js';
+import { withoutGrouping } from '../ast/index.js';
+import { bindArguments, arityText, signatureText } from './arguments.js';
+import { warmupOfCall } from './call-warmup.js';
+import type { ParameterShape } from './arguments.js';
+import type { Checker, Placement } from './checker.js';
+import { reportStrategyOnly } from './checker.js';
+import type { CheckedCall } from './checked.js';
+import { isCompileTimeConstant } from './constant.js';
+import { refuseHandle } from './handles.js';
+import type { LibraryEntry } from './library.js';
+import { literalNumber, literalString } from './literals.js';
+import { recordOutput, reportCallWarnings } from './outputs.js';
+import { isTopLevelOnly, libraryEntries } from './surface.js';
+import { closestName } from './suggest.js';
+import type { Type } from './types.js';
+import { NOTHING, UNKNOWN, accepts, elementOf, isHandle, typeText } from './types.js';
+import { BAR_ZERO } from './warmup.js';
+
+/** The calls whose first argument is an array that an empty literal may fill. */
+const INSERTERS = new Set(['push', 'unshift', 'insert', 'set']);
+
+function shapesOf(entry: LibraryEntry): readonly ParameterShape[] {
+  return entry.parameters.map((one) => ({ name: one.name, optional: one.optional }));
+}
+
+/**
+ * The signature a call means.
+ *
+ * With one candidate there is nothing to choose. With several, arity decides
+ * first because it is the cheaper test and it separates most of the library's
+ * overloads on its own; where two signatures take the same count, the written
+ * positional arguments decide, which is `stdlib.md` 2.2's second rule.
+ */
+function selectOverload(
+  checker: Checker,
+  call: Call,
+  entries: readonly LibraryEntry[],
+): LibraryEntry | undefined {
+  const callable = entries.filter((one) => one.callable);
+  const first = callable[0];
+  if (first === undefined || callable.length === 1) return first;
+
+  const given = call.args.length;
+  const byArity = callable.filter((one) => {
+    const required = one.parameters.filter((p) => !p.optional).length;
+    return given >= required && given <= one.parameters.length;
+  });
+  const narrowed = byArity.length === 0 ? callable : byArity;
+  const only = narrowed[0];
+  if (only === undefined || narrowed.length === 1) return only;
+
+  const byType = narrowed.find((one) =>
+    call.args.every((argument, index) => {
+      if (argument.label !== undefined) return true;
+      const parameter = one.parameters[index];
+      return parameter === undefined || accepts(parameter.type, checker.typeOf(argument.value));
+    }),
+  );
+  return byType ?? only;
+}
+
+/** Binds the stand-ins of a signature to the types the call actually supplied. */
+function bindVariables(
+  checker: Checker,
+  entry: LibraryEntry,
+  filled: readonly (Argument | undefined)[],
+): Map<string, Type> {
+  const bound = new Map<string, Type>();
+
+  const remember = (name: string, type: Type): void => {
+    const existing = bound.get(name);
+    if (existing === undefined || existing.kind === 'none' || existing.kind === 'unknown') {
+      bound.set(name, type);
+    }
+  };
+
+  for (let i = 0; i < entry.parameters.length; i += 1) {
+    const parameter = entry.parameters[i];
+    const argument = filled[i];
+    if (parameter === undefined || argument === undefined) continue;
+    // A stand-in binds to the type it was given, and a declaration handle is
+    // the one type it must not carry: a signature that returned one would hand
+    // a name a handle the emitter has no declaration for (`language.md` 5.4).
+    // `validateArguments` reports it; this keeps the result out of the tree.
+    const supplied = checker.typeOf(argument.value);
+    const given = supplied.kind === 'handle' ? UNKNOWN : supplied;
+    const wanted = parameter.type;
+    if (wanted.kind === 'variable') remember(wanted.name, given);
+    else if (wanted.kind === 'array' && wanted.element.kind === 'variable') {
+      const element = elementOf(given);
+      if (element.kind === 'array') remember(wanted.element.name, element.element);
+    }
+  }
+
+  return bound;
+}
+
+/**
+ * Whether a parameter is written to take whatever it is given.
+ *
+ * A stand-in (`orElse(x: T, fallback: T)`) and `any` (`text(x: any)`) both name
+ * no type, so a handle in one of them has no declared type to be named against
+ * and OS3011 would have nothing to put in its sentence. What is true of both is
+ * that they take a value, which is the answer OS2003 gives.
+ */
+function takesAnyValue(type: Type): boolean {
+  switch (type.kind) {
+    case 'variable':
+    case 'unknown':
+      return true;
+    case 'array':
+    case 'series':
+      return takesAnyValue(type.element);
+    default:
+      return false;
+  }
+}
+
+function substitute(type: Type, bound: ReadonlyMap<string, Type>): Type {
+  switch (type.kind) {
+    case 'variable':
+      return bound.get(type.name) ?? UNKNOWN;
+    case 'array':
+      return { kind: 'array', element: substitute(type.element, bound) };
+    case 'series':
+      return { kind: 'series', element: substitute(type.element, bound) };
+    default:
+      return type;
+  }
+}
+
+/** Every argument against the parameter it filled: type, value set, range, constancy. */
+export function validateArguments(
+  checker: Checker,
+  entry: LibraryEntry,
+  filled: readonly (Argument | undefined)[],
+  bound: ReadonlyMap<string, Type>,
+): void {
+  for (let i = 0; i < entry.parameters.length; i += 1) {
+    const parameter = entry.parameters[i];
+    const argument = filled[i];
+    if (parameter === undefined || argument === undefined) continue;
+
+    const expected = substitute(parameter.type, bound);
+    const given = checker.typeOf(argument.value);
+    const span = argument.span;
+
+    if (given.kind === 'nothing') {
+      checker.report('OS2003', span, {
+        leftType: typeText(expected),
+        rightType: typeText(NOTHING),
+      });
+    } else if (entry.name === 'fill' && (i === 0 || i === 1)) {
+      // `unknown` is what an expression already reported about carries, and it
+      // satisfies everything, so a band drawn to a name whose own line was
+      // refused does not collect a second diagnostic about the same mistake.
+      if (given.kind !== 'unknown' && (given.kind !== 'handle' || given.handle !== 'plot')) {
+        checker.report('OS3020', span, {
+          argument: parameter.name,
+          found: typeText(given),
+        });
+      }
+    } else if (isHandle(given) && parameter.type.kind !== 'handle') {
+      // `fill` is the one signature in version 1 that declares a handle
+      // parameter, and it is answered above. Every other parameter takes a
+      // value, including a stand-in, which binds to whatever it is given and
+      // would otherwise carry a handle into a call that has no way to hold one.
+      if (takesAnyValue(parameter.type)) {
+        refuseHandle(checker, argument.value, given);
+      } else if (expected.kind === 'object' || expected.kind === 'objects') {
+        // A setter that takes a set of object kinds is the same case as one
+        // that takes a single kind: the argument wanted a runtime object and a
+        // declaration handle has no value on a bar. OS3019's own example is a
+        // plot handle given to `draw.setColor`, which reached OS2003 while that
+        // parameter was written `any`.
+        checker.report('OS3019', span, {
+          name: entry.name,
+          argument: parameter.name,
+          expected: typeText(expected),
+          found: typeText(given),
+        });
+      } else {
+        checker.report('OS3011', span, {
+          name: entry.name,
+          argument: parameter.name,
+          expected: typeText(expected),
+          found: typeText(given),
+        });
+      }
+    } else if (!accepts(expected, given)) {
+      checker.report('OS3011', span, {
+        name: entry.name,
+        argument: parameter.name,
+        expected: typeText(expected),
+        found: typeText(given),
+      });
+    }
+
+    // OS3023. An argument that names something the file declares, in a release
+    // where nothing can declare one. The value is not read and no suggestion is
+    // offered, because there is no name that would have been right: what the
+    // reader has to do is take the argument out. Refused whether the name was
+    // written or computed, which is the whole difference from the set check
+    // below: a computed leg was ignored exactly as quietly as a misspelt one,
+    // and a script that named one leg and closed another traded the leg it did
+    // not name.
+    if (entry.undeclared.includes(parameter.name)) {
+      checker.report('OS3023', span, { name: entry.name, argument: parameter.name });
+    }
+
+    const allowed = entry.values[parameter.name];
+    const written = literalString(argument.value);
+    if (allowed !== undefined && written !== undefined && !allowed.includes(written)) {
+      checker.report('OS3008', span, {
+        argument: parameter.name,
+        values: allowed.join(', '),
+        found: written,
+        suggestion: closestName(written, allowed),
+      });
+    }
+
+    const range = entry.whole[parameter.name];
+    const value = range === undefined ? undefined : literalNumber(argument.value);
+    if (range !== undefined && value !== undefined && !inRange(value, range.min, range.max)) {
+      checker.report('OS3004', span, {
+        name: entry.name,
+        argument: parameter.name,
+        range: range.text,
+        found: value,
+      });
+    }
+
+    if (entry.constant.includes(parameter.name) && !isCompileTimeConstant(checker, argument.value)) {
+      checker.report('OS3003', span, { option: parameter.name });
+    }
+  }
+
+  reportConflicts(checker, entry, filled);
+}
+
+/**
+ * OS3010: two arguments that state one thing two ways.
+ *
+ * Reconciling them would need a rule, and every rule anybody has proposed for
+ * it surprises somebody, so both are refused and the script says which it
+ * meant. The caret goes under the second of the two, which is the one the
+ * reader is most likely to have added.
+ */
+function reportConflicts(
+  checker: Checker,
+  entry: LibraryEntry,
+  filled: readonly (Argument | undefined)[],
+): void {
+  for (const [first, second] of entry.conflicts) {
+    const a = filled[entry.parameters.findIndex((one) => one.name === first)];
+    const b = filled[entry.parameters.findIndex((one) => one.name === second)];
+    if (a === undefined || b === undefined) continue;
+    checker.report('OS3010', b.span, { first, second });
+  }
+}
+
+function inRange(value: number, min: number | undefined, max: number | undefined): boolean {
+  if (!Number.isInteger(value)) return false;
+  if (min !== undefined && value < min) return false;
+  return max === undefined || value <= max;
+}
+
+/**
+ * An empty array literal taking its element type from the first insertion.
+ *
+ * `language.md` 14.1 gives an unannotated `[]` its type from the first `push`,
+ * `unshift`, `insert` or `set` in source order, and this is that moment: the
+ * checker is looking at the call, it knows which name the array came from, and
+ * it knows what is being put in.
+ */
+function fixElementType(
+  checker: Checker,
+  entry: LibraryEntry,
+  filled: readonly (Argument | undefined)[],
+): void {
+  if (!INSERTERS.has(entry.name)) return;
+  const target = filled[0];
+  const value = filled[filled.length - 1];
+  if (target === undefined || value === undefined) return;
+
+  const reference = withoutGrouping(target.value);
+  if (reference.kind !== 'nameReference') return;
+  const binding = checker.lookup(reference.name);
+  if (binding === undefined) return;
+
+  const current = elementOf(binding.type);
+  if (current.kind !== 'array' || current.element.kind !== 'unknown') return;
+
+  const element = elementOf(checker.typeOf(value.value));
+  if (element.kind === 'unknown' || element.kind === 'none') return;
+  binding.type = { kind: 'array', element };
+}
+
+/**
+ * A call to a name the library holds.
+ *
+ * The result is recorded whether or not anything was reported about it, because
+ * every stage above this one asks the same two questions of a call site, and a
+ * hole in the map would make each of them invent an answer of its own.
+ */
+export function resolveLibraryCall(
+  checker: Checker,
+  call: Call,
+  name: string,
+  placement: Placement,
+): CheckedCall {
+  const entries = libraryEntries(name);
+  const entry = selectOverload(checker, call, entries);
+
+  if (entry === undefined) {
+    const held = entries[0];
+    checker.report('OS2010', call.span, {
+      name,
+      type: held === undefined ? typeText(UNKNOWN) : typeText(held.returns),
+      suggestion: checker.suggestionFor(name),
+    });
+    return unresolved(call, name);
+  }
+
+  if (entry.planned) {
+    checker.report('OS2020', call.span, { name });
+  }
+
+  reportStrategyOnly(checker, name, call.span, entry.strategyOnly);
+  checkPlacement(checker, call, entry, placement);
+
+  const shapes = shapesOf(entry);
+  const filled = bindArguments(checker, call.span, call.args, name, shapes);
+  const bound = bindVariables(checker, entry, filled);
+  validateArguments(checker, entry, filled, bound);
+  fixElementType(checker, entry, filled);
+
+  const stateful = entry.stateful;
+  if (stateful && checker.isConditional(call)) {
+    checker.report('OS8001', call.span, { name });
+  }
+
+  const checked: CheckedCall = {
+    call,
+    name,
+    target: 'library',
+    entry,
+    fn: undefined,
+    arguments: filled,
+    returns: substitute(entry.returns, bound),
+    warmup: warmupOfCall(checker, entry, filled),
+    stateful,
+    stateId: stateful ? checker.takeStateId() : undefined,
+    seriesArguments: [],
+  };
+  remember(checker, checked);
+  recordOutput(checker, entry, checked);
+  reportCallWarnings(checker, entry, checked);
+  return checked;
+}
+
+/** OS3006 and OS3007: a call that describes the file's shape, written inside it. */
+function checkPlacement(
+  checker: Checker,
+  call: Call,
+  entry: LibraryEntry,
+  placement: Placement,
+): void {
+  if (!entry.topLevel || placement.topLevel) return;
+  const construct = placement.construct ?? 'a block';
+  if (entry.name === 'input') checker.report('OS3007', call.span, {});
+  else if (isTopLevelOnly(entry.name)) {
+    checker.report('OS3006', call.span, { name: entry.name, construct });
+  }
+}
+
+export function unresolved(call: Call, name: string): CheckedCall {
+  return {
+    call,
+    name,
+    target: 'unresolved',
+    entry: undefined,
+    fn: undefined,
+    arguments: [],
+    returns: UNKNOWN,
+    warmup: BAR_ZERO,
+    stateful: false,
+    stateId: undefined,
+    seriesArguments: [],
+  };
+}
+
+export function remember(checker: Checker, checked: CheckedCall): void {
+  checker.calls.push(checked);
+  checker.callSites.set(checked.call, checked);
+}
+
+export { arityText, signatureText };

package/src/core/check/check.ts

@@ -0,0 +1,183 @@
+/**
+ * The checker, from a syntax tree to a checked one.
+ *
+ * The order the passes run in is the order the language asks for. The header is
+ * read first, because whether a file is a strategy and whether it acts on a
+ * moving bar are facts every later rule consults, including about lines above
+ * the declaration. Declarations of `fn` are collected next, because a function
+ * may be called before the line it is written on. Then the file runs top to
+ * bottom, which is the order a bar runs in and the order a name has to be
+ * assigned before it is read.
+ *
+ * What is left over is the small set of things that can only be known once
+ * everything has been seen: whether a name was ever read, whether an empty
+ * array literal ever received an element, whether two columns were given one
+ * title, whether a tag a `close` names is one this file can place, and which
+ * names need a series register rather than a slot.
+ */
+import type { Script } from '../ast/index.js';
+import type { DiagnosticSink } from '../diagnostics/index.js';
+import type { SourceFile } from '../source/index.js';
+import { Checker, TOP_LEVEL, finaliseStorage } from './checker.js';
+import type { CheckedScript } from './checked.js';
+import { checkDeclaration, checkLimits, readHeader } from './declaration.js';
+import { checkFunctionDeclarations, checkRemainingFunctions } from './functions.js';
+import { reportRepeatedAlertIds } from './outputs.js';
+import { checkStatement } from './statements.js';
+import { reportUnplaceableTags } from './tags.js';
+import { elementOf } from './types.js';
+
+export function check(file: SourceFile, script: Script, sink: DiagnosticSink): CheckedScript {
+  const checker = new Checker(file, script, sink);
+
+  readHeader(checker, script);
+  checkFunctionDeclarations(checker, script);
+
+  let limits = false;
+  for (const item of script.items) {
+    switch (item.kind) {
+      case 'functionDeclaration':
+        continue;
+      case 'scriptDeclaration':
+        checkDeclaration(checker, item);
+        continue;
+      case 'limitsLine':
+        checkLimits(checker, item, script, limits);
+        limits = true;
+        continue;
+      default:
+        checkStatement(checker, item, TOP_LEVEL);
+    }
+  }
+
+  checkRemainingFunctions(checker);
+  finaliseStorage(checker);
+  reportUnknownElementTypes(checker);
+  reportNamesNeverRead(checker);
+  reportRepeatedTitles(checker);
+  reportInputKeys(checker);
+  reportRepeatedAlertIds(checker);
+  reportUnplaceableTags(checker);
+
+  return checker.finish();
+}
+
+/**
+ * OS2015: an empty array literal that never learned what it holds.
+ *
+ * `language.md` 14.1 gives one its element type from an annotation or from the
+ * first `push`, `unshift`, `insert` or `set` in the file. With neither, there
+ * is no type, and the moment to say so is now rather than at the literal, where
+ * the insertion three lines below had not been read yet.
+ */
+function reportUnknownElementTypes(checker: Checker): void {
+  for (const binding of checker.bindings) {
+    const type = elementOf(binding.type);
+    if (type.kind !== 'array' || type.element.kind !== 'unknown') continue;
+    checker.report('OS2015', binding.declaredAt, {});
+  }
+}
+
+/** OS8010 and OS8018: a name, or an input, that nothing in the file reads. */
+function reportNamesNeverRead(checker: Checker): void {
+  for (const binding of checker.bindings) {
+    if (binding.isRead) continue;
+    if (binding.kind === 'library' || binding.kind === 'function') continue;
+    if (binding.kind === 'parameter' || binding.kind === 'loop') continue;
+
+    if (binding.input !== undefined) {
+      const input = checker.inputs[binding.input];
+      checker.report('OS8018', binding.declaredAt, {
+        title: `"${input?.title ?? binding.name}"`,
+        line: binding.declaredAt.line,
+      });
+      continue;
+    }
+    checker.report('OS8010', binding.declaredAt, {
+      name: binding.name,
+      line: binding.declaredAt.line,
+    });
+  }
+}
+
+/**
+ * OS3017: two things in one file given the same name.
+ *
+ * A title is what every later stage keys on, from a legend entry to a saved
+ * alert subscription, so two of them is not a cosmetic problem: one of the two
+ * would have to lose, and nothing anywhere decides which.
+ */
+function reportRepeatedTitles(checker: Checker): void {
+  const seen = new Map<string, number>();
+
+  for (const output of checker.outputs) {
+    if (output.form === 'fill' || output.title === '') continue;
+    const key = `${output.form}:${output.title}`;
+    const first = seen.get(key);
+    if (first === undefined) seen.set(key, output.span.line);
+    else {
+      checker.report('OS3017', output.span, {
+        kind: output.form,
+        name: `"${output.title}"`,
+        line: first,
+      });
+    }
+  }
+
+  const inputs = new Map<string, number>();
+  for (const input of checker.inputs) {
+    if (input.title === '') continue;
+    const first = inputs.get(input.title);
+    if (first === undefined) inputs.set(input.title, input.span.line);
+    else {
+      checker.report('OS3017', input.span, {
+        kind: 'input',
+        name: `"${input.title}"`,
+        line: first,
+      });
+    }
+  }
+}
+
+/**
+ * OS3021, OS3024 and OS3022: an input whose settings key is missing, or is
+ * another's.
+ *
+ * `host-interface.md` 8.1 keys a stored value by the name the input was
+ * assigned to, and an input written where a value belongs is assigned to none.
+ * Its key is its title instead: the one thing about the row a user sees, and
+ * therefore the one thing whose change is a rename rather than an edit. That
+ * holds only while every input lands on a key of its own, and there are exactly
+ * two ways it does not. A title spelling another input's name puts two rows on
+ * one key, and one user value would serve both. A title that is not there at
+ * all is no key and no label either.
+ *
+ * **No title and an empty title are two programs and take two codes.** Both end
+ * with nothing to be keyed by, and a reader who wrote `input(14, "")` did write
+ * a title as a string literal, so OS3021's message and its fix are both untrue
+ * of their file: they tell them to do the thing they have just done. OS3024 is
+ * the same refusal with a sentence that is true of it, and it refines OS3021
+ * rather than widening it, because the two fixes are different edits.
+ *
+ * Two inputs carrying one title is the third way and is OS3017 above, which is
+ * why this runs after it: the case is already reported and reporting it twice
+ * would be two codes for one edit.
+ */
+function reportInputKeys(checker: Checker): void {
+  const names = new Map<string, number>();
+  for (const input of checker.inputs) {
+    if (input.name !== '') names.set(input.name, input.span.line);
+  }
+
+  for (const input of checker.inputs) {
+    if (input.name !== '') continue;
+    if (input.title === '') {
+      if (input.titleWritten) checker.report('OS3024', input.span, {});
+      else checker.report('OS3021', input.span, {});
+      continue;
+    }
+    const taken = names.get(input.title);
+    if (taken === undefined) continue;
+    checker.report('OS3022', input.span, { name: `"${input.title}"`, line: taken });
+  }
+}