openalgo-script 0.1.0-alpha.0 → 0.2.0

package/src/core/check/checked.ts

@@ -0,0 +1,228 @@
+/**
+ * The checked tree: what the checker hands the code generator.
+ *
+ * The syntax tree is not rebuilt. Every answer the checker worked out is
+ * recorded against the node it is about, so the generator walks the same tree
+ * the parser produced and looks up what it needs. The alternative, a second
+ * tree of parallel nodes, would double the shapes anyone has to learn and would
+ * put the spans one edit away from disagreeing with the source.
+ *
+ * What is here is chosen so the generator re-derives nothing. It does not have
+ * to work out which declaration a name means, what type an expression has, how
+ * many bars a value needs, whether a name lives in a slot, a cell or a series
+ * register, which call sites need a state region, or which reads repaint. Each
+ * of those is a question the checker already had to answer to report its own
+ * diagnostics, and asking it twice is how two stages come to disagree.
+ *
+ * `compiled-program.md` sections 2.6 to 2.13 name the arrays a program carries.
+ * The lists below are in the same order the program's are, so the generator
+ * writes them out rather than sorting anything.
+ */
+import type {
+  Argument,
+  Call,
+  Expression,
+  FunctionDeclaration,
+  Name,
+  NameReference,
+  Script,
+  ScriptDeclaration,
+} from '../ast/index.js';
+import type { Span } from '../span/index.js';
+import type { LibraryEntry } from './library.js';
+import type { HandleKind, Type } from './types.js';
+import type { Warmup } from './warmup.js';
+
+/** Where a name was introduced, which decides what may be done to it. */
+export type BindingKind = 'file' | 'block' | 'parameter' | 'loop' | 'library' | 'function';
+
+/**
+ * Where the value lives between bars, `compiled-program.md` 2.10 and 2.11.
+ *
+ * A register is allocated only for a top-level name whose history the program
+ * reads, which is the rule that section states; everything else that is not
+ * persistent is a slot, and a `var` is a cell.
+ */
+export type Storage = 'slot' | 'cell' | 'register' | 'none';
+
+export interface Binding {
+  readonly id: number;
+  readonly name: string;
+  readonly kind: BindingKind;
+  /** `var` and `live var` survive the bar; `live` opts out of rollback. */
+  readonly persistence: 'none' | 'var' | 'live';
+  readonly type: Type;
+  readonly warmup: Warmup;
+  readonly storage: Storage;
+  /** The name as it was written, which is what OS2002 and OS8010 point at. */
+  readonly declaredAt: Span;
+  /** Whether any line reads this name's past, which is what allocates a register. */
+  readonly readsHistory: boolean;
+  /** Whether any line reads it at all. False is OS8010. */
+  readonly isRead: boolean;
+  /** The input this name holds, when its value came from `input()`. */
+  readonly input: number | undefined;
+  /** The declaration handle this name holds, when it came from `plot` or `level`. */
+  readonly handle: HandleKind | undefined;
+}
+
+/** The control a host builds for one `input()`, `compiled-program.md` 2.6. */
+export type InputKind =
+  | 'number'
+  | 'bool'
+  | 'string'
+  | 'select'
+  | 'color'
+  | 'source'
+  | 'interval'
+  | 'time';
+
+export interface CheckedInput {
+  readonly id: number;
+  readonly call: Call;
+  /** The name the value was assigned to, or an empty string where it was not. */
+  readonly name: string;
+  readonly title: string;
+  /**
+   * A title was written as a string literal, which an empty one still is.
+   *
+   * `title` cannot carry that on its own: a call with no title argument, a call
+   * whose title is an expression rather than a literal, and a call whose title
+   * is `""` all leave it empty, and the three are three different mistakes with
+   * three different fixes. The first two are OS3021 and the third is OS3024,
+   * whose message and fix have to be true of the program in front of the reader.
+   */
+  readonly titleWritten: boolean;
+  readonly kind: InputKind;
+  readonly type: Type;
+  readonly span: Span;
+}
+
+/** One entry of the study's fixed shape, `compiled-program.md` 2.8. */
+export interface CheckedOutput {
+  readonly id: number;
+  readonly form: 'plot' | 'plotCandles' | 'fill' | 'level' | 'table';
+  readonly title: string;
+  readonly call: Call;
+  /** The first bar this column can draw on, which is what OS8009 reads. */
+  readonly warmup: Warmup;
+  readonly span: Span;
+}
+
+export interface CheckedFunction {
+  readonly id: number;
+  readonly declaration: FunctionDeclaration;
+  readonly parameters: readonly Binding[];
+  readonly returns: Type;
+  readonly warmup: Warmup;
+  /** Holds a `var` or calls something that does, so its call sites need state. */
+  readonly stateful: boolean;
+}
+
+/**
+ * One call site, resolved.
+ *
+ * `arguments` is in the callee's parameter order with a hole where the default
+ * applies, rather than in the order they were written, so the generator emits
+ * them without matching labels a second time. What each default is belongs to
+ * the library manifest (`compiled-program.md` 2.5) and is not copied here.
+ */
+export interface CheckedCall {
+  readonly call: Call;
+  readonly name: string;
+  readonly target: 'library' | 'user' | 'unresolved';
+  readonly entry: LibraryEntry | undefined;
+  /** The index into `functions` when the callee is a user function. */
+  readonly fn: number | undefined;
+  readonly arguments: readonly (Argument | undefined)[];
+  readonly returns: Type;
+  readonly warmup: Warmup;
+  readonly stateful: boolean;
+  /** The per-call-site state region, `compiled-program.md` 2.11. */
+  readonly stateId: number | undefined;
+  /**
+   * The arguments whose per-bar values this call site has to retain.
+   *
+   * A user function that reads `src[1]` reads the history of whatever the
+   * caller passed, so the caller writes that expression to a series register
+   * before the call (`compiled-program.md` 2.10 and 2.12). These are the
+   * parameter positions that need one.
+   */
+  readonly seriesArguments: readonly number[];
+}
+
+/** What a higher timeframe read is allowed to know, `stdlib.md` 15.3. */
+export type RequestMode = 'confirmed' | 'developing' | 'lookahead' | 'unknown';
+
+export interface CheckedRequest {
+  readonly id: number;
+  readonly call: Call;
+  readonly name: string;
+  readonly mode: RequestMode;
+  /** The timeframe as the source writes it: a literal, or the name that holds it. */
+  readonly timeframe: string;
+  readonly repaints: boolean;
+  readonly span: Span;
+}
+
+export interface CheckedDeclaration {
+  readonly node: ScriptDeclaration;
+  readonly form: 'study' | 'strategy';
+  readonly title: string;
+  /** Every option that was given, by name, with the expression it was given. */
+  readonly options: ReadonlyMap<string, Expression>;
+  readonly overlay: boolean;
+  /** Signals and orders may act on a bar that is still moving, language.md 7.5. */
+  readonly onUnconfirmed: boolean;
+}
+
+/**
+ * A file, checked.
+ *
+ * `types` and `warmups` hold an answer for every expression the checker
+ * reached, including the ones it reported a diagnostic about, where the type is
+ * `unknown` so that nothing above them reports a second time.
+ */
+export interface CheckedScript {
+  readonly script: Script;
+  readonly declaration: CheckedDeclaration | undefined;
+  readonly inputs: readonly CheckedInput[];
+  readonly outputs: readonly CheckedOutput[];
+  readonly functions: readonly CheckedFunction[];
+  readonly bindings: readonly Binding[];
+  readonly calls: readonly CheckedCall[];
+  readonly requests: readonly CheckedRequest[];
+  /** Whether any read in the file shows a bar values from the future. */
+  readonly repaints: boolean;
+  /** How many state regions the program needs, `compiled-program.md` 2.11. */
+  readonly stateCount: number;
+  readonly types: ReadonlyMap<Expression, Type>;
+  readonly warmups: ReadonlyMap<Expression, Warmup>;
+  /** Every name used as a value, bound to the declaration it means. */
+  readonly references: ReadonlyMap<NameReference, Binding>;
+  /** Every name that introduces or updates one: a target, a `var`, a loop variable. */
+  readonly targets: ReadonlyMap<Name, Binding>;
+  readonly callSites: ReadonlyMap<Call, CheckedCall>;
+}
+
+/** The checker's own working copy of a record the tree publishes as read-only. */
+export type Mutable<T> = { -readonly [K in keyof T]: T[K] };
+
+/**
+ * The input a name stands for, which is not the input it was given.
+ *
+ * `len = input(14, "Length")` makes the name a second spelling of the setting:
+ * it is the input's own slot, it folds to the input's key where a declaration
+ * option wants a constant, and a read's expression resolves it to the setting
+ * (`compiled-program.md` 2.3, 2.6 and 2.16). `var len = input(14, "Length")`
+ * declares a cell a later assignment may change (`language.md` 8.2), so it
+ * holds the setting on the first bar and whatever it is given after that, and
+ * not one of those three is true of it.
+ *
+ * `input` stays set on both, because the input is the row either spelling
+ * declares and a row nothing reads is OS8018 either way. This is the narrower
+ * question, asked in one place so that three passes cannot answer it twice.
+ */
+export function inputHeldBy(binding: Binding): number | undefined {
+  return binding.persistence === 'none' ? binding.input : undefined;
+}

package/src/core/check/checker.ts

@@ -0,0 +1,393 @@
+/**
+ * The checker's working state: scopes, bindings, and the answers as they are
+ * worked out.
+ *
+ * Everything mutable in the check lives here and nowhere else, so the passes
+ * over the tree are ordinary functions that take this and a node. The state is
+ * handed out as a `CheckedScript` at the end and is not touched again.
+ *
+ * Nothing in this file decides a rule of the language. It holds what the rules
+ * are decided from: which names are in scope here, what the source said, and
+ * where to put an answer once one of the passes has it.
+ */
+import type {
+  Call,
+  Expression,
+  FunctionDeclaration,
+  Name,
+  NameReference,
+  Script,
+} from '../ast/index.js';
+import type { DiagnosticCode, DiagnosticValues } from '../catalogue/index.js';
+import type { DiagnosticSink } from '../diagnostics/index.js';
+import type { SourceFile } from '../source/index.js';
+import type { Span } from '../span/index.js';
+import type {
+  Binding,
+  BindingKind,
+  CheckedCall,
+  CheckedDeclaration,
+  CheckedFunction,
+  CheckedInput,
+  CheckedOutput,
+  CheckedRequest,
+  CheckedScript,
+  Mutable,
+  Storage,
+} from './checked.js';
+import { conditionalCalls } from './conditional.js';
+import { libraryNames } from './surface.js';
+import { closestName } from './suggest.js';
+import type { Type } from './types.js';
+import { UNKNOWN } from './types.js';
+import type { Warmup } from './warmup.js';
+import { BAR_ZERO } from './warmup.js';
+
+/**
+ * One nesting of names, `language.md` 12.1.
+ *
+ * The global scope is not one of these: the library is a lookup of its own,
+ * consulted after every scope has been tried, because it holds three hundred
+ * names that never change and copying them into a map per compile would be the
+ * most expensive thing the checker does.
+ */
+export interface Scope {
+  readonly kind: 'file' | 'block' | 'function';
+  readonly names: Map<string, Mutable<Binding>>;
+  readonly parent: Scope | undefined;
+  /** The loop variable this scope introduced, which OS2006 refuses assignment to. */
+  readonly loopVariable: string | undefined;
+}
+
+/**
+ * What surrounds the statement being checked, for OS3006.
+ *
+ * Whether the thing being checked runs on every bar is deliberately not here.
+ * It is a fact about a node rather than about the path the pass took to reach
+ * it, and half of what makes a call conditional is an operator rather than a
+ * statement, so `conditional.ts` answers it from the tree and this carries only
+ * what a pass can know.
+ */
+export interface Placement {
+  /** True only for a statement written directly in the file, `language.md` 15.3. */
+  readonly topLevel: boolean;
+  /** The enclosing construct, named in OS3006's message. */
+  readonly construct: string | undefined;
+  /** Inside a `for` or `while` body, where `break` and `continue` are legal. */
+  readonly inLoop: boolean;
+}
+
+export const TOP_LEVEL: Placement = {
+  topLevel: true,
+  construct: undefined,
+  inLoop: false,
+};
+
+export class Checker {
+  readonly file: SourceFile;
+  readonly sink: DiagnosticSink;
+  readonly script: Script;
+
+  /** The file scope, which is also where a `fn` puts its name. */
+  readonly fileScope: Scope;
+  scope: Scope;
+
+  declaration: CheckedDeclaration | undefined = undefined;
+  readonly inputs: Mutable<CheckedInput>[] = [];
+  readonly outputs: CheckedOutput[] = [];
+  readonly functions: Mutable<CheckedFunction>[] = [];
+  readonly bindings: Mutable<Binding>[] = [];
+  readonly calls: CheckedCall[] = [];
+  readonly requests: CheckedRequest[] = [];
+
+  readonly types = new Map<Expression, Type>();
+  readonly warmups = new Map<Expression, Warmup>();
+  /**
+   * The expressions a declaration handle is allowed to stand in, 5.4.
+   *
+   * `handles.ts` holds the rule and fills this. It is a set of permissions
+   * rather than a flag on the pass, because the permission belongs to one
+   * written expression: `fill(upper, lower)` may name a handle, and an
+   * expression inside one of those arguments may not.
+   */
+  readonly handleSites = new Set<Expression>();
+  readonly references = new Map<NameReference, Binding>();
+  readonly targets = new Map<Name, Binding>();
+  readonly callSites = new Map<Call, CheckedCall>();
+  /**
+   * The multi-output call a name holds, by binding, for `m[1]`.
+   *
+   * A warmup is recorded against an expression, and an element's warmup is not
+   * a fact about the array expression: it is a fact about the call the name was
+   * given, which `m[1]` has to reach two statements later. Only the calls whose
+   * outputs warm up at different bars are kept, because for every other one the
+   * array's warmup is already the element's.
+   */
+  private readonly multiOutputs = new Map<number, CheckedCall>();
+
+  /** The declarations of every `fn`, collected before any body is checked. */
+  readonly functionsByName = new Map<string, number>();
+  readonly functionNodes = new Map<string, FunctionDeclaration>();
+  /** Bodies already checked, and the ones being checked, so a cycle stops. */
+  readonly checkedFunctions = new Set<number>();
+  readonly checkingFunctions = new Set<number>();
+
+  repaints = false;
+  stateCount = 0;
+  /** How deep inside a `req` expression the pass is, `stdlib.md` 15.4. */
+  requestDepth = 0;
+  /** The function whose body is being checked, for its own statefulness. */
+  currentFunction: Mutable<CheckedFunction> | undefined = undefined;
+  /** What the body being checked returns, gathered as the `return`s are met. */
+  pendingReturns: { readonly type: Type; readonly warmup: Warmup }[] = [];
+
+  /** Every call site a bar can pass without evaluating, `language.md` 11.4. */
+  private readonly conditional: ReadonlySet<Call>;
+
+  constructor(file: SourceFile, script: Script, sink: DiagnosticSink) {
+    this.file = file;
+    this.script = script;
+    this.sink = sink;
+    this.fileScope = { kind: 'file', names: new Map(), parent: undefined, loopVariable: undefined };
+    this.scope = this.fileScope;
+    this.conditional = conditionalCalls(script);
+  }
+
+  /**
+   * Whether this call site can be skipped on a bar, which is what OS8001 asks.
+   *
+   * Asked of the call rather than of the pass that reached it, so the answer is
+   * the same wherever the call was written: inside an `if`, in a ternary arm,
+   * or on the right of an `and` that short-circuited.
+   */
+  isConditional(call: Call): boolean {
+    return this.conditional.has(call);
+  }
+
+  report<Code extends DiagnosticCode>(
+    code: Code,
+    span: Span,
+    values: DiagnosticValues[Code],
+  ): void {
+    this.sink.report(code, span, values);
+  }
+
+  /** The source text a span covers, for the codes that quote what was written. */
+  textOf(span: Span): string {
+    return this.file.text.slice(span.offset, span.offset + span.length).trim();
+  }
+
+  /** Opens a scope, runs the body in it, and closes it however the body ends. */
+  inScope<T>(kind: Scope['kind'], loopVariable: string | undefined, body: () => T): T {
+    const parent = this.scope;
+    this.scope = { kind, names: new Map(), parent, loopVariable };
+    try {
+      return body();
+    } finally {
+      this.scope = parent;
+    }
+  }
+
+  /**
+   * The declaration a name means here, and whether a function body stands
+   * between the two.
+   *
+   * A plain assignment updates an enclosing name (`language.md` 12.2), and a
+   * function body is the one place that does not hold: 12.3's own example makes
+   * an assignment to a file-scope name from inside a `fn` OS2002.
+   */
+  lookupAcross(name: string): {
+    readonly binding: Mutable<Binding> | undefined;
+    readonly crossedFunction: boolean;
+  } {
+    let crossedFunction = false;
+    for (let scope: Scope | undefined = this.scope; scope !== undefined; scope = scope.parent) {
+      const found = scope.names.get(name);
+      if (found !== undefined) return { binding: found, crossedFunction };
+      if (scope.kind === 'function') crossedFunction = true;
+    }
+    return { binding: undefined, crossedFunction };
+  }
+
+  /** The declaration a name means here, or nothing when no scope holds it. */
+  lookup(name: string): Mutable<Binding> | undefined {
+    for (let scope: Scope | undefined = this.scope; scope !== undefined; scope = scope.parent) {
+      const found = scope.names.get(name);
+      if (found !== undefined) return found;
+    }
+    return undefined;
+  }
+
+  /** Whether an enclosing scope already holds the name, which is OS2002. */
+  enclosing(name: string): Mutable<Binding> | undefined {
+    for (
+      let scope: Scope | undefined = this.scope.parent;
+      scope !== undefined;
+      scope = scope.parent
+    ) {
+      const found = scope.names.get(name);
+      if (found !== undefined) return found;
+    }
+    return undefined;
+  }
+
+  /** Whether the name belongs to the loop being executed, `language.md` 10.3. */
+  loopVariableNamed(name: string): boolean {
+    for (let scope: Scope | undefined = this.scope; scope !== undefined; scope = scope.parent) {
+      if (scope.loopVariable === name) return true;
+      if (scope.names.has(name)) return false;
+    }
+    return false;
+  }
+
+  /** Declares a name in the current scope and records it in the checked tree. */
+  declare(
+    name: Name,
+    kind: BindingKind,
+    type: Type,
+    warmup: Warmup,
+    persistence: Binding['persistence'] = 'none',
+  ): Mutable<Binding> {
+    const binding: Mutable<Binding> = {
+      id: this.bindings.length,
+      name: name.text,
+      kind,
+      persistence,
+      type,
+      warmup,
+      storage: storageFor(kind, persistence),
+      declaredAt: name.span,
+      readsHistory: false,
+      isRead: false,
+      input: undefined,
+      handle: undefined,
+    };
+    this.bindings.push(binding);
+    this.scope.names.set(name.text, binding);
+    this.targets.set(name, binding);
+    return binding;
+  }
+
+  /**
+   * Remembers, or forgets, the multi-output call a name was just given.
+   *
+   * Forgetting on a reassignment rather than keeping the first call is what
+   * stops `m[1]` from being answered about a call the name no longer holds:
+   * the array's own warmup is the fallback, and it is a floor for every
+   * element.
+   */
+  holdsMultiOutput(binding: number, call: CheckedCall | undefined): void {
+    if (call === undefined || call.entry === undefined || call.entry.elements.length === 0) {
+      this.multiOutputs.delete(binding);
+      return;
+    }
+    this.multiOutputs.set(binding, call);
+  }
+
+  /** The multi-output call this name holds here, when it holds one. */
+  multiOutputOf(name: string): CheckedCall | undefined {
+    const binding = this.lookup(name);
+    return binding === undefined ? undefined : this.multiOutputs.get(binding.id);
+  }
+
+  record(expression: Expression, type: Type, warmup: Warmup): Type {
+    this.types.set(expression, type);
+    this.warmups.set(expression, warmup);
+    return type;
+  }
+
+  typeOf(expression: Expression): Type {
+    return this.types.get(expression) ?? UNKNOWN;
+  }
+
+  warmupOf(expression: Expression): Warmup {
+    return this.warmups.get(expression) ?? BAR_ZERO;
+  }
+
+  /** Every name a reader could have meant here: the scopes, then the library. */
+  namesInScope(): readonly string[] {
+    const names = new Set<string>();
+    for (let scope: Scope | undefined = this.scope; scope !== undefined; scope = scope.parent) {
+      for (const name of scope.names.keys()) names.add(name);
+    }
+    for (const name of libraryNames()) names.add(name);
+    return [...names];
+  }
+
+  suggestionFor(written: string): string {
+    return closestName(written, this.namesInScope());
+  }
+
+  /** A state region for one call site, `compiled-program.md` 2.11. */
+  takeStateId(): number {
+    const id = this.stateCount;
+    this.stateCount += 1;
+    return id;
+  }
+
+  finish(): CheckedScript {
+    return {
+      script: this.script,
+      declaration: this.declaration,
+      inputs: this.inputs,
+      outputs: this.outputs,
+      functions: this.functions,
+      bindings: this.bindings,
+      calls: this.calls,
+      requests: this.requests,
+      repaints: this.repaints,
+      stateCount: this.stateCount,
+      types: this.types,
+      warmups: this.warmups,
+      references: this.references,
+      targets: this.targets,
+      callSites: this.callSites,
+    };
+  }
+}
+
+/**
+ * OS7001: a name the library gives only to a file declared with `strategy()`.
+ *
+ * The message names the line of the `study()` declaration rather than the call,
+ * because that is the line the reader has to change: the call is what they
+ * meant, and the declaration is what refuses it.
+ */
+export function reportStrategyOnly(
+  checker: Checker,
+  name: string,
+  span: Span,
+  strategyOnly: boolean,
+): void {
+  const declaration = checker.declaration;
+  if (!strategyOnly || declaration === undefined || declaration.form === 'strategy') return;
+  checker.report('OS7001', span, { name, line: declaration.node.span.line });
+}
+
+/**
+ * Where a name's value lives between bars.
+ *
+ * A top-level name starts in a slot and is moved to a register only when the
+ * program turns out to read its history, which the checker knows by the end and
+ * `finaliseStorage` applies. Everything below the top level is a slot, and a
+ * `var` is a cell whatever scope it was written in.
+ */
+function storageFor(kind: BindingKind, persistence: Binding['persistence']): Storage {
+  if (persistence !== 'none') return 'cell';
+  return kind === 'library' || kind === 'function' ? 'none' : 'slot';
+}
+
+/**
+ * Promotes the top-level names whose history is read to series registers.
+ *
+ * `compiled-program.md` 2.10 allocates a register only for a name the program
+ * reads the past of, and this is the one place that decides it, once every read
+ * in the file has been seen.
+ */
+export function finaliseStorage(checker: Checker): void {
+  for (const binding of checker.bindings) {
+    if (binding.readsHistory && binding.kind === 'file' && binding.persistence === 'none') {
+      binding.storage = 'register';
+    }
+  }
+}