openalgo-script 0.1.0-alpha.0 → 0.2.0

package/src/core/index.ts

@@ -1,11 +1,22 @@
 /**
- * OpenScript, the compiler tier.
+ * OpenScript, the compiler and the engine.
  *
- * This is the whole of what a host needs to turn a script into a compiled
- * program, and it knows nothing about a chart, an editor or a broker. It
- * imports no package and touches no browser global, so the same file runs in a
- * worker, on a server and inside somebody else's application under a content
- * security policy that forbids turning text into code.
+ * This is the whole of what a host needs to take a script and produce values,
+ * and it knows nothing about a chart, an editor or a broker. It imports no
+ * package and touches no browser global, so the same file runs in a worker, on
+ * a server and inside somebody else's application under a content security
+ * policy that forbids turning text into code.
+ *
+ * Three things a host does, and the names that do them:
+ *
+ *     sourceFile, parse, check, emit   source text becomes a compiled program
+ *     load                             a program is verified and made runnable
+ *     Engine.run, Engine.append        it runs over bars, and values come out
+ *
+ * Every name below is a promise to somebody who is not in this repository, so
+ * the surface is a decision rather than everything the modules hold: a pass, a
+ * table or an instruction stays behind its module's door, and a host never has
+ * to reach past this file to compile or run a script.
  *
  * The tiers above it are separate entry points, so a host that wants only this
  * one never loads the editor intelligence or an adapter.
@@ -144,3 +155,115 @@ export {
 export { lex } from './lex/index.js';
 
 export { parse, parseTokens } from './parse/index.js';
+
+export type {
+  Binding,
+  BindingKind,
+  CheckedCall,
+  CheckedDeclaration,
+  CheckedFunction,
+  CheckedInput,
+  CheckedOutput,
+  CheckedRequest,
+  CheckedScript,
+  HandleKind,
+  InputKind,
+  LibraryEntry,
+  LibraryParameter,
+  ObjectKind,
+  RequestMode,
+  Storage,
+  Type,
+  ValueKind,
+  WarmupRule,
+  Warmup,
+} from './check/index.js';
+export {
+  BAR_ZERO,
+  HANDLE_KINDS,
+  NAMESPACES,
+  OBJECT_KINDS,
+  STRATEGY_NAMESPACES,
+  VALUE_KINDS,
+  accepts,
+  allOf,
+  arrayOf,
+  atBar,
+  atLeastBar,
+  check,
+  delayed,
+  earlier,
+  elementOf,
+  isLibraryName,
+  isNamespace,
+  isNever,
+  isSeries,
+  join,
+  later,
+  libraryEntries,
+  libraryNames,
+  membersOf,
+  sameType,
+  seriesOf,
+  typeText,
+} from './check/index.js';
+export { REQUEST_NAMES } from './check/index.js';
+export { COMPILED_FORMAT_VERSION, VERSION } from './version/index.js';
+
+/**
+ * The emitter: a checked script becomes the compiled program.
+ *
+ * The program is plain data, so a host may store it, send it, and run it here
+ * or on an engine somebody else wrote from the specification.
+ *
+ * `canonicalise` is the encoding the two hashes are taken over and the bytes
+ * that travel. A host that records the source hash and the program hash beside
+ * a result can later prove an engine upgrade did not change it, which is what
+ * `compiled-program.md` 9.5 promises.
+ */
+export { emit } from './emit/index.js';
+export type { EmitOptions, EmitResult } from './emit/index.js';
+export type { CompiledProgram } from './emit/index.js';
+export { canonicalise, programHash, sourceHash } from './emit/index.js';
+
+/**
+ * The engine: a program in, one bar at a time, values out.
+ *
+ * `load` verifies the program in full before a bar executes and answers with a
+ * diagnostic rather than an exception, because a host runs many scripts in one
+ * process and one failing script must take nothing else down. `verify` is that
+ * same check on its own, for a host that keeps compiled programs and wants to
+ * refuse a bad one when it arrives rather than when it is first drawn.
+ *
+ * `capabilitiesFor` and `LANGUAGE_VERSIONS` are this engine's half of the
+ * compatibility statement in 9.1, beside `COMPILED_FORMAT_VERSION` above.
+ */
+export { load } from './engine/index.js';
+export type { BarResult, Engine, LoadOptions, LoadResult, RunResult } from './engine/index.js';
+export type {
+  BarState,
+  EffectRoute,
+  EngineHost,
+  HostBar,
+  Instrument,
+  PendingEffect,
+  RoutedEffect,
+} from './engine/index.js';
+/**
+ * The order boundary: what a strategy sends, what a host reports back, and the
+ * ledger the two fold into (`host-interface.md` 7, `stdlib.md` 17.7).
+ */
+export type {
+  FrameOutcome,
+  Identity,
+  LedgerRow,
+  OrderFrame,
+  OrderIntent,
+  OrderStatus,
+} from './engine/index.js';
+export { DEFAULT_LIMITS } from './engine/index.js';
+export type { EngineLimits } from './engine/index.js';
+export { isAbsent } from './engine/index.js';
+export type { Value } from './engine/index.js';
+export { LANGUAGE_VERSIONS, capabilitiesFor, verify } from './engine/index.js';
+export type { VerifyOptions, VerifyResult } from './engine/index.js';

package/src/core/parse/expressions.ts

@@ -303,7 +303,7 @@ function parsePrimary(cursor: Cursor): Expression {
       // not read, and the next thing the reader is told is that a bracket they
       // plainly closed was never closed.
       if (isMeantAsAName(token.kind)) {
-        const name = takeName(cursor);
+        const name = takeName(cursor, true);
         return makeNode('nameReference', name.span, { name: name.text });
       }
       return expressionExpected(cursor);

package/src/core/parse/functions.ts

@@ -1,109 +1,109 @@
-import type { Block, Expression, FunctionDeclaration, Name, Parameter } from '../ast/index.js';
-import { makeNode } from '../ast/index.js';
-import { spanning } from '../span/index.js';
-import type { Token } from '../tokens/index.js';
-import { parseTypeAnnotation } from './annotations.js';
-import { parseBlock } from './blocks.js';
-import type { Cursor } from './cursor.js';
-import { parseBracketedList, parseExpression } from './expressions.js';
-import { takeName } from './names.js';
-import { finishStatement } from './statements.js';
-
-/**
- * `fn name(parameters) => body`, language.md 11.1.
- *
- * The body is an expression when it is written after the `=>` on one line, and
- * a block when the `=>` ends the line. Both forms exist because the one line
- * form needs the implicit return and an early exit needs the explicit one.
- *
- * The `=>` is two tokens. Section 3.12 does not list it among the punctuation,
- * so it arrives as an `=` and a `>` that touch, and touching is what tells it
- * from a comparison: the lexer suppresses its continuation rule for that exact
- * pair, and the same adjacency test is what matches it here.
- */
-export function parseFunctionDeclaration(cursor: Cursor): FunctionDeclaration {
-  const keyword = cursor.advance();
-  const name = takeName(cursor);
-
-  const open = cursor.take('(');
-  if (open === undefined) cursor.unexpected(cursor.token);
-  const parameters =
-    open === undefined ? [] : parseBracketedList(cursor, open, parseParameter).items;
-
-  const arrow = takeArrow(cursor);
-  if (arrow === undefined) {
-    return declaration(keyword, name, parameters, headerWithNoArrow(cursor, keyword));
-  }
-
-  if (!cursor.atStatementEnd()) {
-    const body = parseExpression(cursor);
-    finishStatement(cursor);
-    return declaration(keyword, name, parameters, body);
-  }
-
-  finishStatement(cursor);
-  return declaration(keyword, name, parameters, parseBlock(cursor, 'fn', keyword.span));
-}
-
-/**
- * A parameter, which is an ordinary identifier and not a label.
- *
- * `fn f(color = red)` is OS1019, and `plot(v, "V", color = aqua)` is not: the
- * body of a function refers to its parameters, and nothing ever refers to a
- * label (language.md 3.4). `takeName` is the whole of that difference.
- */
-function parseParameter(cursor: Cursor): Parameter {
-  const name = takeName(cursor);
-
-  const annotation = cursor.take(':') !== undefined ? parseTypeAnnotation(cursor) : undefined;
-  const defaultValue = cursor.take('=') !== undefined ? parseExpression(cursor) : undefined;
-
-  const end = defaultValue?.span ?? annotation?.span ?? name.span;
-  return makeNode('parameter', spanning(name.span, end), { name, annotation, defaultValue });
-}
-
-/** The `=>` of 11.1: an `=` and a `>` written against each other. */
-function takeArrow(cursor: Cursor): Token | undefined {
-  const equals = cursor.token;
-  const greater = cursor.peek();
-  if (equals.kind !== '=' || greater.kind !== '>') return undefined;
-  if (equals.span.offset + equals.span.length !== greater.span.offset) return undefined;
-
-  cursor.advance();
-  return cursor.advance();
-}
-
-/**
- * A header with no `=>`, which the catalogue has no code of its own for.
- *
- * What is reported is what is true. A token sitting where the arrow belongs is
- * OS1018, whose fix names the operator that was meant to join the two halves. A
- * header that simply ends is OS1010, because that is what it now is: a header
- * with no body, since without the arrow the lexer opened no block under it.
- */
-function headerWithNoArrow(cursor: Cursor, keyword: Token): Block | Expression {
-  if (!cursor.atStatementEnd()) {
-    cursor.unexpected(cursor.token);
-    const body = parseExpression(cursor);
-    finishStatement(cursor);
-    return body;
-  }
-
-  cursor.report('OS1010', keyword.span, { header: 'fn' });
-  finishStatement(cursor);
-  if (cursor.at('indent')) return parseBlock(cursor, 'fn', keyword.span);
-  return makeNode('block', cursor.holeSpan(), { statements: [] });
-}
-
-function declaration(
-  keyword: Token,
-  name: Name,
-  parameters: readonly Parameter[],
-  body: Block | Expression,
-): FunctionDeclaration {
-  return makeNode('functionDeclaration', spanning(keyword.span, body.span), {
-    name,
-    parameters,
-    body,
-  });
-}
+import type { Block, Expression, FunctionDeclaration, Name, Parameter } from '../ast/index.js';
+import { makeNode } from '../ast/index.js';
+import { spanning } from '../span/index.js';
+import type { Token } from '../tokens/index.js';
+import { parseTypeAnnotation } from './annotations.js';
+import { parseBlock } from './blocks.js';
+import type { Cursor } from './cursor.js';
+import { parseBracketedList, parseExpression } from './expressions.js';
+import { takeName } from './names.js';
+import { finishStatement } from './statements.js';
+
+/**
+ * `fn name(parameters) => body`, language.md 11.1.
+ *
+ * The body is an expression when it is written after the `=>` on one line, and
+ * a block when the `=>` ends the line. Both forms exist because the one line
+ * form needs the implicit return and an early exit needs the explicit one.
+ *
+ * The `=>` is two tokens. Section 3.12 does not list it among the punctuation,
+ * so it arrives as an `=` and a `>` that touch, and touching is what tells it
+ * from a comparison: the lexer suppresses its continuation rule for that exact
+ * pair, and the same adjacency test is what matches it here.
+ */
+export function parseFunctionDeclaration(cursor: Cursor): FunctionDeclaration {
+  const keyword = cursor.advance();
+  const name = takeName(cursor);
+
+  const open = cursor.take('(');
+  if (open === undefined) cursor.unexpected(cursor.token);
+  const parameters =
+    open === undefined ? [] : parseBracketedList(cursor, open, parseParameter).items;
+
+  const arrow = takeArrow(cursor);
+  if (arrow === undefined) {
+    return declaration(keyword, name, parameters, headerWithNoArrow(cursor, keyword));
+  }
+
+  if (!cursor.atStatementEnd()) {
+    const body = parseExpression(cursor);
+    finishStatement(cursor);
+    return declaration(keyword, name, parameters, body);
+  }
+
+  finishStatement(cursor);
+  return declaration(keyword, name, parameters, parseBlock(cursor, 'fn', keyword.span));
+}
+
+/**
+ * A parameter, which is an ordinary identifier and not a label.
+ *
+ * `fn f(color = red)` is OS1019, and `plot(v, "V", color = aqua)` is not: the
+ * body of a function refers to its parameters, and nothing ever refers to a
+ * label (language.md 3.4). `takeName` is the whole of that difference.
+ */
+function parseParameter(cursor: Cursor): Parameter {
+  const name = takeName(cursor);
+
+  const annotation = cursor.take(':') !== undefined ? parseTypeAnnotation(cursor) : undefined;
+  const defaultValue = cursor.take('=') !== undefined ? parseExpression(cursor) : undefined;
+
+  const end = defaultValue?.span ?? annotation?.span ?? name.span;
+  return makeNode('parameter', spanning(name.span, end), { name, annotation, defaultValue });
+}
+
+/** The `=>` of 11.1: an `=` and a `>` written against each other. */
+function takeArrow(cursor: Cursor): Token | undefined {
+  const equals = cursor.token;
+  const greater = cursor.peek();
+  if (equals.kind !== '=' || greater.kind !== '>') return undefined;
+  if (equals.span.offset + equals.span.length !== greater.span.offset) return undefined;
+
+  cursor.advance();
+  return cursor.advance();
+}
+
+/**
+ * A header with no `=>`, which the catalogue has no code of its own for.
+ *
+ * What is reported is what is true. A token sitting where the arrow belongs is
+ * OS1018, whose fix names the operator that was meant to join the two halves. A
+ * header that simply ends is OS1010, because that is what it now is: a header
+ * with no body, since without the arrow the lexer opened no block under it.
+ */
+function headerWithNoArrow(cursor: Cursor, keyword: Token): Block | Expression {
+  if (!cursor.atStatementEnd()) {
+    cursor.unexpected(cursor.token);
+    const body = parseExpression(cursor);
+    finishStatement(cursor);
+    return body;
+  }
+
+  cursor.report('OS1010', keyword.span, { header: 'fn' });
+  finishStatement(cursor);
+  if (cursor.at('indent')) return parseBlock(cursor, 'fn', keyword.span);
+  return makeNode('block', cursor.holeSpan(), { statements: [] });
+}
+
+function declaration(
+  keyword: Token,
+  name: Name,
+  parameters: readonly Parameter[],
+  body: Block | Expression,
+): FunctionDeclaration {
+  return makeNode('functionDeclaration', spanning(keyword.span, body.span), {
+    name,
+    parameters,
+    body,
+  });
+}

package/src/core/parse/names.ts

@@ -76,6 +76,26 @@ function unreservedNear(word: string): string {
   return `${word}Value`;
 }
 
+/**
+ * The library spelling of a reserved word somebody wrote as a call.
+ *
+ * `bool` and `number` name types, and the two conversions to those types have to
+ * be called by a name, which a reserved word is not. For one release the library
+ * published them under the type names anyway: the checker called them functions,
+ * the lexer called the same words reserved, and every spelling a reader could
+ * write was refused with advice to rename a variable they had not declared. The
+ * conversions are `toBool` and `toNumber`, and this is the table that says so to
+ * whoever wrote the natural thing.
+ *
+ * It is two entries because two names collided, not because a rule needs a list:
+ * a library name is never a reserved word, and `tests/unit/library-names.test.ts`
+ * fails the build if one ever is again.
+ */
+const CALLED_INSTEAD: ReadonlyMap<string, string> = new Map([
+  ['bool', 'toBool'],
+  ['number', 'toNumber'],
+]);
+
 /** No word where one was required, which leaves the statement without its subject. */
 function missingWord(cursor: Cursor): Name {
   const hole = cursor.holeSpan();
@@ -91,16 +111,23 @@ function missingWord(cursor: Cursor): Name {
  * The word is taken either way. A script that named something `type` still
  * meant to declare it, and every later diagnostic about that name is more use
  * to the reader than a hole where the declaration should have been.
+ *
+ * `asValue` is set by the one reader that takes a word from where a value
+ * belongs, and it is what lets the fix be true of the program in front of it. A
+ * word with an argument list after it is a call, and a reader who wrote one
+ * wants the name the library really publishes; the same word being declared or
+ * assigned to wants a name of their own, and the library's would collide.
  */
-export function takeName(cursor: Cursor): Name {
+export function takeName(cursor: Cursor, asValue = false): Name {
   const token = cursor.token;
   if (!isWordKind(token.kind)) return missingWord(cursor);
 
   cursor.advance();
   if (token.kind !== 'identifier') {
+    const called = asValue && cursor.kind === '(' ? CALLED_INSTEAD.get(token.text) : undefined;
     cursor.report('OS1019', token.span, {
       word: token.text,
-      suggestion: unreservedNear(token.text),
+      suggestion: called ?? unreservedNear(token.text),
     });
   }
   return makeNode('name', token.span, { text: token.text });

package/src/core/parse/switches.ts

@@ -1,105 +1,105 @@
-import type { Expression, SwitchCase, SwitchDefault, SwitchStatement } from '../ast/index.js';
-import { makeNode } from '../ast/index.js';
-import type { Span } from '../span/index.js';
-import { spanning } from '../span/index.js';
-import { parseBlock } from './blocks.js';
-import type { Cursor } from './cursor.js';
-import { parseCondition } from './expressions.js';
-import { finishStatement } from './statements.js';
-
-/**
- * `switch`, in both forms of language.md 10.6.
- *
- * With a subject each case value is compared against it, and without one each
- * case value is a condition. The difference is the absent subject and needs no
- * flag beside it.
- *
- * The arms are the whole of a switch body. A `default` that is not last would
- * leave the arms after it unreachable, so the arm that follows one is OS1017,
- * and the arm is kept in the tree all the same: a reader who moves the default
- * should not then be told about the arms one at a time.
- */
-export function parseSwitchStatement(cursor: Cursor): SwitchStatement {
-  const keyword = cursor.advance();
-  const subject = cursor.atStatementEnd() ? undefined : parseCondition(cursor);
-  finishStatement(cursor);
-
-  const cases: SwitchCase[] = [];
-  let defaultCase: SwitchDefault | undefined;
-  let end: Span = keyword.span;
-
-  if (!cursor.at('indent')) {
-    if (!cursor.reportedHere) cursor.report('OS1010', keyword.span, { header: 'switch' });
-    return makeNode('switchStatement', spanning(keyword.span, end), {
-      subject,
-      cases,
-      defaultCase,
-    });
-  }
-
-  if (!cursor.openBlock(cursor.token.span)) {
-    cursor.skipBlockBody();
-    return makeNode('switchStatement', spanning(keyword.span, end), {
-      subject,
-      cases,
-      defaultCase,
-    });
-  }
-  cursor.advance();
-
-  while (!cursor.at('dedent') && !cursor.at('endOfFile')) {
-    const before = cursor.position;
-    const word = cursor.token;
-
-    if (cursor.at('case')) {
-      if (defaultCase !== undefined) cursor.report('OS1017', word.span, { word: word.text });
-      const arm = parseCase(cursor);
-      cases.push(arm);
-      end = arm.span;
-    } else if (cursor.at('default')) {
-      const arm = parseDefault(cursor);
-      if (defaultCase === undefined) defaultCase = arm;
-      else cursor.report('OS1017', word.span, { word: word.text });
-      end = arm.span;
-    } else {
-      // A line in a switch body that is not an arm. The catalogue has no code
-      // for it, and OS1017 carries the rule it breaks: the arms are the whole
-      // of the body, so this line belongs inside one of them or above the
-      // switch.
-      cursor.report('OS1017', word.span, { word: 'case' });
-      cursor.skipStatement();
-    }
-
-    if (cursor.position === before) cursor.skipStatement();
-  }
-
-  cursor.closeBlock();
-  cursor.take('dedent');
-
-  return makeNode('switchStatement', spanning(keyword.span, end), { subject, cases, defaultCase });
-}
-
-/** One arm. Several values separated by commas are one arm, not several. */
-function parseCase(cursor: Cursor): SwitchCase {
-  cursor.beginStatement();
-  const keyword = cursor.advance();
-
-  const values: Expression[] = [parseCondition(cursor)];
-  while (cursor.take(',') !== undefined) {
-    const before = cursor.position;
-    values.push(parseCondition(cursor));
-    if (cursor.position === before) break;
-  }
-
-  finishStatement(cursor);
-  const body = parseBlock(cursor, 'case', keyword.span);
-  return makeNode('switchCase', spanning(keyword.span, body.span), { values, body });
-}
-
-function parseDefault(cursor: Cursor): SwitchDefault {
-  cursor.beginStatement();
-  const keyword = cursor.advance();
-  finishStatement(cursor);
-  const body = parseBlock(cursor, 'default', keyword.span);
-  return makeNode('switchDefault', spanning(keyword.span, body.span), { body });
-}
+import type { Expression, SwitchCase, SwitchDefault, SwitchStatement } from '../ast/index.js';
+import { makeNode } from '../ast/index.js';
+import type { Span } from '../span/index.js';
+import { spanning } from '../span/index.js';
+import { parseBlock } from './blocks.js';
+import type { Cursor } from './cursor.js';
+import { parseCondition } from './expressions.js';
+import { finishStatement } from './statements.js';
+
+/**
+ * `switch`, in both forms of language.md 10.6.
+ *
+ * With a subject each case value is compared against it, and without one each
+ * case value is a condition. The difference is the absent subject and needs no
+ * flag beside it.
+ *
+ * The arms are the whole of a switch body. A `default` that is not last would
+ * leave the arms after it unreachable, so the arm that follows one is OS1017,
+ * and the arm is kept in the tree all the same: a reader who moves the default
+ * should not then be told about the arms one at a time.
+ */
+export function parseSwitchStatement(cursor: Cursor): SwitchStatement {
+  const keyword = cursor.advance();
+  const subject = cursor.atStatementEnd() ? undefined : parseCondition(cursor);
+  finishStatement(cursor);
+
+  const cases: SwitchCase[] = [];
+  let defaultCase: SwitchDefault | undefined;
+  let end: Span = keyword.span;
+
+  if (!cursor.at('indent')) {
+    if (!cursor.reportedHere) cursor.report('OS1010', keyword.span, { header: 'switch' });
+    return makeNode('switchStatement', spanning(keyword.span, end), {
+      subject,
+      cases,
+      defaultCase,
+    });
+  }
+
+  if (!cursor.openBlock(cursor.token.span)) {
+    cursor.skipBlockBody();
+    return makeNode('switchStatement', spanning(keyword.span, end), {
+      subject,
+      cases,
+      defaultCase,
+    });
+  }
+  cursor.advance();
+
+  while (!cursor.at('dedent') && !cursor.at('endOfFile')) {
+    const before = cursor.position;
+    const word = cursor.token;
+
+    if (cursor.at('case')) {
+      if (defaultCase !== undefined) cursor.report('OS1017', word.span, { word: word.text });
+      const arm = parseCase(cursor);
+      cases.push(arm);
+      end = arm.span;
+    } else if (cursor.at('default')) {
+      const arm = parseDefault(cursor);
+      if (defaultCase === undefined) defaultCase = arm;
+      else cursor.report('OS1017', word.span, { word: word.text });
+      end = arm.span;
+    } else {
+      // A line in a switch body that is not an arm. The catalogue has no code
+      // for it, and OS1017 carries the rule it breaks: the arms are the whole
+      // of the body, so this line belongs inside one of them or above the
+      // switch.
+      cursor.report('OS1017', word.span, { word: 'case' });
+      cursor.skipStatement();
+    }
+
+    if (cursor.position === before) cursor.skipStatement();
+  }
+
+  cursor.closeBlock();
+  cursor.take('dedent');
+
+  return makeNode('switchStatement', spanning(keyword.span, end), { subject, cases, defaultCase });
+}
+
+/** One arm. Several values separated by commas are one arm, not several. */
+function parseCase(cursor: Cursor): SwitchCase {
+  cursor.beginStatement();
+  const keyword = cursor.advance();
+
+  const values: Expression[] = [parseCondition(cursor)];
+  while (cursor.take(',') !== undefined) {
+    const before = cursor.position;
+    values.push(parseCondition(cursor));
+    if (cursor.position === before) break;
+  }
+
+  finishStatement(cursor);
+  const body = parseBlock(cursor, 'case', keyword.span);
+  return makeNode('switchCase', spanning(keyword.span, body.span), { values, body });
+}
+
+function parseDefault(cursor: Cursor): SwitchDefault {
+  cursor.beginStatement();
+  const keyword = cursor.advance();
+  finishStatement(cursor);
+  const body = parseBlock(cursor, 'default', keyword.span);
+  return makeNode('switchDefault', spanning(keyword.span, body.span), { body });
+}