openalgo-script 0.1.0-alpha.1 → 0.2.0

package/src/core/check/library.ts

@@ -0,0 +1,374 @@
+/**
+ * The shape of the standard library, as the checker needs to see it.
+ *
+ * `stdlib.md` is the specification of what each call does and what it costs in
+ * bars. What the checker needs from it is narrower: a name, the parameters it
+ * takes, the type it gives back, where it may be written and how many bars it
+ * delays its source by. That is what an entry here holds, and nothing here
+ * implements any of it: the numbers are computed under `src/core/stdlib/`.
+ *
+ * Entries are written as signature strings because a signature is what the
+ * specification's tables already show a reader, so the two can be compared by
+ * eye without translating one of them first. A string is parsed once, when this
+ * module loads, into the record below; there is no code built from text
+ * anywhere, and there cannot be, which is the rule the whole design rests on.
+ */
+import type { HandleKind, ObjectKind, Type } from './types.js';
+import {
+  BOOL,
+  COLOR,
+  NONE,
+  NOTHING,
+  NUMBER,
+  STRING,
+  UNKNOWN,
+  arrayOf,
+  handleType,
+  objectType,
+  objectsType,
+  seriesOf,
+} from './types.js';
+
+/**
+ * How a call's own warmup relates to the warmup of what it was given.
+ *
+ * `delay` and `params` both add bars to the source's own warmup, which is what
+ * makes warmups compose: `sma(ema(close, 10), 10)` is absent until bar 18.
+ * `params` reads the added bars off the call's own arguments, so it can only
+ * be exact when those arguments are literal numbers, and `exact` says whether
+ * the formula in `stdlib.md` is reproduced here or only bounded below.
+ */
+export type WarmupRule =
+  | { readonly kind: 'delay'; readonly bars: number }
+  | {
+      readonly kind: 'params';
+      readonly params: readonly string[];
+      readonly scale: number;
+      readonly add: number;
+      readonly exact: boolean;
+    }
+  /** A value on bar 0 however late its arguments are: `isNone` is the example. */
+  | { readonly kind: 'total' }
+  /** The warmup of one named argument, and of nothing else. */
+  | { readonly kind: 'argument'; readonly param: string }
+  /** Present as soon as the earlier of these arguments is: `orElse`. */
+  | { readonly kind: 'either'; readonly params: readonly string[] }
+  /** Decided by the data rather than by a length, so a floor is all there is. */
+  | { readonly kind: 'data' };
+
+/**
+ * A whole number argument and the range it accepts, for OS3004.
+ *
+ * The bounds are numbers and the sentence is derived from them, so the message
+ * a reader sees and the test the checker runs cannot say different things. A
+ * fractional length is refused rather than truncated (`language.md` 5.1): a
+ * length of 14.5 is a bug in the script and rounding it hides the bug.
+ */
+export interface WholeRange {
+  readonly text: string;
+  readonly min: number | undefined;
+  readonly max: number | undefined;
+}
+
+export function wholeRange(min?: number, max?: number): WholeRange {
+  const text =
+    min !== undefined && max !== undefined
+      ? `${min} to ${max}`
+      : min !== undefined
+        ? `${min} or more`
+        : max !== undefined
+          ? `${max} or less`
+          : 'with no fractional part';
+  return { text, min, max };
+}
+
+export interface LibraryParameter {
+  readonly name: string;
+  readonly type: Type;
+  /** Whether the entry gives it a default. A missing required one is OS3012. */
+  readonly optional: boolean;
+  /**
+   * The default, written as `stdlib.md`'s own tables write it, or nothing.
+   *
+   * An omitted argument is filled from this text, so the default is a
+   * compile-time fact and no engine carries a table of them
+   * (`compiled-program.md` 4.10). The text is a literal (`14`, `"ema"`,
+   * `false`, `none`) or a library name the compiler reads at the call
+   * (`hlc3`, `chart.timezone`); the emitter decides which, because a default
+   * is a value and values are the emitter's.
+   *
+   * **Nothing here is not "no default".** It means the specification states no
+   * value for this parameter: either it states words rather than a value, as
+   * `leg = the only leg` does, or it states nothing at all. Both are recorded
+   * with their reason in `spec/default-exceptions.json`, and
+   * `scripts/check-defaults.mjs` refuses any optional parameter that is in
+   * neither that file nor this field. The two together are what stop a default
+   * from being dropped again: an argument omitted from a call used to reach an
+   * engine as absence, every function built on it answered absence on every
+   * bar, and nothing anywhere reported it.
+   */
+  readonly defaultText: string | undefined;
+}
+
+export interface LibraryEntry {
+  /** `ema`, or `draw.line` with its namespace, exactly as a script writes it. */
+  readonly name: string;
+  /** A value such as `close` is read bare; a function is called. */
+  readonly callable: boolean;
+  readonly parameters: readonly LibraryParameter[];
+  readonly returns: Type;
+  readonly warmup: WarmupRule;
+  /**
+   * A rule per output, for an entry whose outputs warm up at different bars.
+   *
+   * `stdlib.md` 2.3 gives each element of a multi-output call its own warmup,
+   * and several of them differ: a signal line is later than the line it
+   * smooths. Empty where the specification states one bar for every element,
+   * because then `warmup` above is already that bar and a second copy of it
+   * would be a fact stated twice.
+   */
+  readonly elements: readonly WarmupRule[];
+  /** Holds per-bar state, so a call inside a branch is OS8001. */
+  readonly stateful: boolean;
+  /** Top level only: OS3006, or OS3007 for `input`. */
+  readonly topLevel: boolean;
+  /** Available only in a `strategy()` file: OS7001. */
+  readonly strategyOnly: boolean;
+  /** Named so the surface is legible, and not in this release: OS2020. */
+  readonly planned: boolean;
+  /** Arguments with a closed set of accepted strings: OS3008. */
+  readonly values: Readonly<Record<string, readonly string[]>>;
+  /**
+   * Arguments that name something the file declares, where this release has no
+   * declaration that could fill the set: OS3023.
+   *
+   * Different from `values` and from `planned`, and the difference is what the
+   * reader is told. `values` holds an argument to a set the language fixes, and
+   * it can only judge a value written out as a literal. `planned` is about the
+   * whole name. This is about an argument whose accepted values are whatever
+   * the file declared, in a release where nothing can declare one: the value
+   * does not come into it, so a computed name is refused exactly as a written
+   * one is, and the message says the file declares none rather than listing an
+   * empty set.
+   */
+  readonly undeclared: readonly string[];
+  /** Arguments that must be a whole number, with the range for OS3004. */
+  readonly whole: Readonly<Record<string, WholeRange>>;
+  /** Arguments read once before bar 0, so a bar-dependent one is OS3003. */
+  readonly constant: readonly string[];
+  /** Pairs that set the same thing two ways, so giving both is OS3010. */
+  readonly conflicts: readonly (readonly [string, string])[];
+}
+
+export interface EntryOptions {
+  readonly warmup?: WarmupRule;
+  readonly elements?: readonly WarmupRule[];
+  readonly stateful?: true;
+  readonly topLevel?: true;
+  readonly strategyOnly?: true;
+  readonly planned?: true;
+  readonly values?: Readonly<Record<string, readonly string[]>>;
+  readonly undeclared?: readonly string[];
+  readonly whole?: Readonly<Record<string, WholeRange>>;
+  readonly constant?: readonly string[];
+  readonly conflicts?: readonly (readonly [string, string])[];
+}
+
+const OBJECT_NAMES: readonly string[] = ['line', 'label', 'box', 'polyline', 'table'];
+const HANDLE_NAMES: readonly string[] = ['plot', 'fill', 'level'];
+
+/**
+ * A type as the signature strings spell it.
+ *
+ * `any` and the single letters are not types of the language. `any` is a
+ * parameter that takes whatever it is given, which is what `isNone` and `text`
+ * want. A single letter is a stand-in carried from one parameter to another, so
+ * that `push(arr, v)` can say that `v` is whatever `arr` holds and `orElse`
+ * can say it gives back what it was given. Both are resolved at the call site
+ * and neither ever reaches a name's type.
+ *
+ * `line | box` is not either of those and is not a general union: it is the set
+ * of object kinds one parameter accepts, which is what a `draw` setter takes,
+ * and it is checked like any other declared type. `any` used to stand there,
+ * and an `any` that means "one of these two" accepts a label and a number as
+ * readily, which is the defect it is written to end.
+ */
+export const ANY: Type = UNKNOWN;
+
+const VARIABLE = /^[A-Z]$/;
+
+function parseType(text: string): Type {
+  const trimmed = text.trim();
+  if (trimmed.startsWith('series ')) return seriesOf(parseType(trimmed.slice(7)));
+  if (trimmed.startsWith('array<') && trimmed.endsWith('>')) {
+    return arrayOf(parseType(trimmed.slice(6, -1)));
+  }
+  if (trimmed.includes('|')) return parseObjectSet(trimmed);
+  switch (trimmed) {
+    case 'number':
+      return NUMBER;
+    case 'string':
+      return STRING;
+    case 'bool':
+      return BOOL;
+    case 'color':
+      return COLOR;
+    case 'none':
+      return NONE;
+    case 'nothing':
+      return NOTHING;
+    case 'any':
+      return ANY;
+    default:
+      if (VARIABLE.test(trimmed)) return { kind: 'variable', name: trimmed };
+      if (OBJECT_NAMES.includes(trimmed)) return objectType(trimmed as ObjectKind);
+      if (HANDLE_NAMES.includes(trimmed)) return handleType(trimmed as HandleKind);
+      throw new Error(`library signature names no such type: ${trimmed}`);
+  }
+}
+
+/**
+ * `line | box`, as a set of object kinds.
+ *
+ * Every member has to be an object kind, there have to be two or more of them,
+ * and no kind may be written twice: each of those is a signature somebody wrote
+ * by hand, and a set that quietly accepted a misspelling would be a parameter
+ * that accepts less than the specification says while reading as though it
+ * accepts it.
+ */
+function parseObjectSet(text: string): Type {
+  const kinds = text.split('|').map((one) => one.trim());
+  const known = kinds.every((one) => OBJECT_NAMES.includes(one));
+  const distinct = new Set(kinds).size === kinds.length;
+  if (!known || !distinct || kinds.length < 2) {
+    throw new Error(`library signature names no such set of object types: ${text}`);
+  }
+  return objectsType(kinds as ObjectKind[]);
+}
+
+/** Split on commas that are not inside angle brackets. */
+function splitParameters(text: string): readonly string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    if (ch === '<') depth += 1;
+    else if (ch === '>') depth -= 1;
+    else if (ch === ',' && depth === 0) {
+      parts.push(text.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(text.slice(start));
+  return parts.map((part) => part.trim()).filter((part) => part.length > 0);
+}
+
+/**
+ * One entry, from `name(param: type, optional?: type) -> result`.
+ *
+ * A name with no bracket is a value a script reads bare, such as `close` or
+ * `bar.index`. A `?` after a parameter name means the library gives it a
+ * default, and `= value` after the type says what that default is, written the
+ * way `stdlib.md`'s tables write it so the two can still be compared by eye.
+ * The text is carried, never interpreted here: the emitter turns it into a
+ * value, because that is where a default belongs (4.10).
+ */
+export function entry(signature: string, options: EntryOptions = {}): LibraryEntry {
+  const arrow = signature.indexOf('->');
+  if (arrow < 0) throw new Error(`library signature has no result type: ${signature}`);
+  const head = signature.slice(0, arrow).trim();
+  const returns = parseType(signature.slice(arrow + 2));
+
+  const open = head.indexOf('(');
+  const callable = open >= 0;
+  const name = callable ? head.slice(0, open).trim() : head;
+  const parameters: LibraryParameter[] = [];
+
+  if (callable) {
+    if (!head.endsWith(')')) throw new Error(`library signature is not closed: ${signature}`);
+    for (const part of splitParameters(head.slice(open + 1, -1))) {
+      const colon = part.indexOf(':');
+      if (colon < 0) throw new Error(`library parameter has no type: ${part}`);
+      const written = part.slice(0, colon).trim();
+      const optional = written.endsWith('?');
+      const rest = part.slice(colon + 1);
+      const equals = rest.indexOf('=');
+      const defaultText = equals < 0 ? undefined : rest.slice(equals + 1).trim();
+      if (defaultText !== undefined && !optional) {
+        throw new Error(`library parameter has a default and no question mark: ${part}`);
+      }
+      // An empty default is a signature that was split somewhere unintended,
+      // and it would reach the emitter as a value nobody wrote.
+      if (defaultText !== undefined && defaultText.length === 0) {
+        throw new Error(`library parameter has an empty default: ${part}`);
+      }
+      parameters.push({
+        name: optional ? written.slice(0, -1) : written,
+        type: parseType(equals < 0 ? rest : rest.slice(0, equals)),
+        optional,
+        defaultText,
+      });
+    }
+  }
+
+  return {
+    name,
+    callable,
+    parameters,
+    returns,
+    warmup: options.warmup ?? { kind: 'delay', bars: 0 },
+    elements: options.elements ?? [],
+    stateful: options.stateful === true,
+    topLevel: options.topLevel === true,
+    strategyOnly: options.strategyOnly === true,
+    planned: options.planned === true,
+    values: options.values ?? {},
+    undeclared: options.undeclared ?? [],
+    whole: options.whole ?? {},
+    constant: options.constant ?? [],
+    conflicts: options.conflicts ?? [],
+  };
+}
+
+/** `bar `len - 1`` and its relatives, the commonest warmup shape in the library. */
+export function fromLength(param: string, add: number, scale = 1): WarmupRule {
+  return { kind: 'params', params: [param], scale, add, exact: true };
+}
+
+/** A sum of lengths, as `bar `len + smoothK - 2`` and its relatives state it. */
+export function fromLengths(params: readonly string[], add: number): WarmupRule {
+  return { kind: 'params', params, scale: 1, add, exact: true };
+}
+
+/** A warmup this module bounds below rather than reproducing the formula for. */
+export function atLeastLength(params: readonly string[], add = 0): WarmupRule {
+  return { kind: 'params', params, scale: 1, add, exact: false };
+}
+
+export const DELAY_ZERO: WarmupRule = { kind: 'delay', bars: 0 };
+export const TOTAL: WarmupRule = { kind: 'total' };
+export const DATA_DRIVEN: WarmupRule = { kind: 'data' };
+
+export function delayBars(bars: number): WarmupRule {
+  return { kind: 'delay', bars };
+}
+
+/**
+ * Every entry of a name, in the order they were declared.
+ *
+ * A bare name may carry more than one signature (stdlib.md 2.2), so a lookup
+ * answers with a list and the call site picks by arity and by argument type.
+ * There is no run-time dispatch anywhere: the choice is made here, once.
+ */
+export type LibraryIndex = ReadonlyMap<string, readonly LibraryEntry[]>;
+
+export function indexOf(entries: readonly LibraryEntry[]): LibraryIndex {
+  const index = new Map<string, LibraryEntry[]>();
+  for (const one of entries) {
+    const existing = index.get(one.name);
+    if (existing === undefined) index.set(one.name, [one]);
+    else existing.push(one);
+  }
+  return index;
+}

package/src/core/check/literals.ts

@@ -0,0 +1,35 @@
+/**
+ * The value behind an expression that was written out.
+ *
+ * Several rules only apply to a value the source states rather than computes: a
+ * length has to be a whole number when it is written as one, a `style` has to
+ * be one of a closed set when it is written as a string, and a warmup is exact
+ * only when every length on the path was a number in the file. Each of those
+ * asks the same two questions, and asking them in one place is what keeps the
+ * answers the same.
+ *
+ * A written negative is a unary minus over a literal rather than a literal, so
+ * it is read through here as well. Without that, `step = -1` would look like
+ * something computed and a loop that counts downwards would lose the one check
+ * that says it terminates.
+ */
+import type { Expression } from '../ast/index.js';
+import { withoutGrouping } from '../ast/index.js';
+
+export function literalNumber(expression: Expression | undefined): number | undefined {
+  if (expression === undefined) return undefined;
+  const inner = withoutGrouping(expression);
+  if (inner.kind === 'numberLiteral') return inner.value;
+  if (inner.kind === 'unary' && (inner.operator === '-' || inner.operator === '+')) {
+    const operand = literalNumber(inner.operand);
+    if (operand === undefined) return undefined;
+    return inner.operator === '-' ? -operand : operand;
+  }
+  return undefined;
+}
+
+export function literalString(expression: Expression | undefined): string | undefined {
+  if (expression === undefined) return undefined;
+  const inner = withoutGrouping(expression);
+  return inner.kind === 'stringLiteral' ? inner.value : undefined;
+}

package/src/core/check/outputs.ts

@@ -0,0 +1,152 @@
+/**
+ * The file's fixed shape, recorded as the calls that declare it are met.
+ *
+ * `plot`, `plotCandles`, `fill`, `level` and `table` each reserve a field of
+ * the chart descriptor (`compiled-program.md` 2.8), and the order they are
+ * written in is the order that descriptor carries and a legend shows. So they
+ * are collected in source order and nothing sorts them afterwards: the script
+ * already decided, and a second decision here would be a second answer.
+ *
+ * The two warnings below belong to one particular call rather than to calls in
+ * general, which is why they are here and not in the argument checking.
+ */
+import type { Argument } from '../ast/index.js';
+import type { Checker } from './checker.js';
+import type { CheckedCall } from './checked.js';
+import type { LibraryEntry } from './library.js';
+import { literalString } from './literals.js';
+
+const OUTPUT_FORMS = new Set(['plot', 'plotCandles', 'fill', 'level', 'table']);
+
+export function recordOutput(
+  checker: Checker,
+  entry: LibraryEntry,
+  checked: CheckedCall,
+): void {
+  if (!OUTPUT_FORMS.has(entry.name)) return;
+  const form = entry.name as 'plot' | 'plotCandles' | 'fill' | 'level' | 'table';
+  const title = literalString(argumentFor(entry, checked, 'title')?.value) ?? '';
+  const value = argumentFor(entry, checked, 'value') ?? argumentFor(entry, checked, 'price');
+  const warmup = value === undefined ? checked.warmup : checker.warmupOf(value.value);
+
+  checker.outputs.push({
+    id: checker.outputs.length,
+    form,
+    title,
+    call: checked.call,
+    warmup,
+    span: checked.call.span,
+  });
+
+  // A column whose value is absent on every bar draws nothing at all, and a
+  // reader deserves to know that before they run the study and wonder why.
+  if ((form === 'plot' || form === 'plotCandles') && warmup.kind === 'never') {
+    checker.report('OS8009', checked.call.span, { title: quoted(title) });
+  }
+}
+
+export function reportCallWarnings(
+  checker: Checker,
+  entry: LibraryEntry,
+  checked: CheckedCall,
+): void {
+  if (entry.name === 'alert') {
+    reportAlertWarnings(checker, entry, checked);
+    return;
+  }
+
+  // precision and format on a plot set the formatting of the price scale the
+  // plot maps to, so setting them over the price pane reformats the
+  // instrument's own axis, which is almost never what was wanted.
+  if (entry.name !== 'plot' || checker.declaration?.overlay !== true) return;
+  const title = quoted(literalString(argumentFor(entry, checked, 'title')?.value) ?? '');
+  for (const option of ['precision', 'format']) {
+    if (argumentFor(entry, checked, option) === undefined) continue;
+    checker.report('OS8007', checked.call.span, { title, option });
+  }
+}
+
+/**
+ * The name one watched condition is known by, `stdlib.md` 16.1.
+ *
+ * It is the `id` the script wrote, and where there is none to write down, one
+ * derived from the line the call sits on. The derivation is here, once, because
+ * the checker reports two alerts that would land under one name and the emitter
+ * writes the name into `outputs.alerts[].key`, and two spellings of it would be
+ * two different answers to "which subscription is this".
+ *
+ * An id is written down only when it is a literal. One taken from an `input()`
+ * is a name that changes when a setting changes, and a subscription keyed on it
+ * would stop matching the moment a user touched the dialog, so it is derived
+ * like an absent one and OS8008 says so.
+ */
+export function alertKey(id: string | undefined, line: number): string {
+  return id === undefined || id === '' ? `alert@${line}` : id;
+}
+
+/** The `id` a call wrote down, or nothing where it wrote none it can keep. */
+function writtenAlertId(entry: LibraryEntry, checked: CheckedCall): string | undefined {
+  const written = literalString(argumentFor(entry, checked, 'id')?.value);
+  return written === '' ? undefined : written;
+}
+
+/**
+ * OS3017 over the watched conditions: two alerts that would share one name.
+ *
+ * A subscription is keyed by the name, so two entries under one name leave the
+ * host with two conditions and one row: whichever it keeps, the other fires
+ * nothing and nothing says which of the two the user subscribed to. The check
+ * runs over the derived name as well as the written one, because an id somebody
+ * writes by hand can collide with a derived one.
+ */
+export function reportRepeatedAlertIds(checker: Checker): void {
+  const seen = new Map<string, number>();
+  for (const checked of checker.calls) {
+    if (checked.name !== 'alert' || checked.entry === undefined) continue;
+    const line = checked.call.span.line;
+    const key = alertKey(writtenAlertId(checked.entry, checked), line);
+    const first = seen.get(key);
+    if (first === undefined) {
+      seen.set(key, line);
+      continue;
+    }
+    checker.report('OS3017', checked.call.span, { kind: 'alert', name: `"${key}"`, line: first });
+  }
+}
+
+function reportAlertWarnings(
+  checker: Checker,
+  entry: LibraryEntry,
+  checked: CheckedCall,
+): void {
+  // With no id of its own the compiler derives one from the call's position,
+  // which changes the moment a line is inserted above it and breaks a
+  // subscription with it.
+  if (writtenAlertId(entry, checked) === undefined) {
+    checker.report('OS8008', checked.call.span, { line: checked.call.span.line });
+  }
+
+  // An alert on every execution of the bar can only fire in a file that acts on
+  // a bar that is still moving (stdlib.md 16.2).
+  const frequency = argumentFor(entry, checked, 'frequency');
+  const written = literalString(frequency?.value);
+  if (written !== 'everyUpdate' || checker.declaration?.onUnconfirmed === true) return;
+  checker.report('OS3009', frequency?.span ?? checked.call.span, {
+    option: 'frequency',
+    value: written,
+    required: 'onUnconfirmed = true',
+  });
+}
+
+function argumentFor(
+  entry: LibraryEntry,
+  checked: CheckedCall,
+  name: string,
+): Argument | undefined {
+  const index = entry.parameters.findIndex((one) => one.name === name);
+  return index < 0 ? undefined : checked.arguments[index];
+}
+
+function quoted(text: string): string {
+  return `"${text}"`;
+}