openalgo-script 0.7.2 → 0.8.1

package/src/adapters/charts/produced.ts

@@ -32,7 +32,7 @@
  */
 import type { Value } from '../../core/engine/index.js';
 import type { ChartSettings } from './contract.js';
-import type { ChartDrawing, ChartGrid, ChartMarker } from './surfaces.js';
+import type { ChartDrawing, ChartMarker, ChartTableSpec } from './surfaces.js';
 
 /**
  * One declared alert's message channel, whole, as the run left it.
@@ -47,13 +47,14 @@ export type MessageColumn = readonly Value[];
 /** One run's non-numeric output, as the hooks that follow it read it. */
 export interface Produced {
   readonly markers: readonly ChartMarker[];
-  readonly table: ChartGrid | null;
+  /** Every declared grid, in declaration order; the single hook reads the first. */
+  readonly tables: readonly ChartTableSpec[];
   readonly drawings: readonly ChartDrawing[];
   /** One entry per declared alert, in the order `outputs.alerts` declares them. */
   readonly messages: readonly MessageColumn[];
 }
 
-const NOTHING: Produced = { markers: [], table: null, drawings: [], messages: [] };
+const NOTHING: Produced = { markers: [], tables: [], drawings: [], messages: [] };
 
 const runs = new WeakMap<ChartSettings, Produced>();
 

package/src/adapters/charts/run.ts

@@ -38,6 +38,7 @@ import type { CompiledProgram } from '../../core/emit/index.js';
 import type { SourceFile } from '../../core/index.js';
 import { hostBar, hostNow, stateFor } from './bars.js';
 import type { ChartBar, ChartCalcContext, ChartSettings, ChartStore } from './contract.js';
+import { capabilitiesOf } from './capabilities.js';
 import { refused, stopped } from './errors.js';
 import { undrawable } from './undrawable.js';
 import { stationIn, stationOf } from './requests.js';
@@ -60,6 +61,29 @@ export interface ChartAdapterOptions {
   readonly id?: string;
   /** The category a picker groups the study under, when `meta.group` is empty. */
   readonly category?: string;
+  /**
+   * The chart library's own version: the `VERSION` string it exports, which a
+   * host that imports the chart already holds, passed on as
+   * `descriptorFor(program, { chartVersion: VERSION })`.
+   *
+   * It says which of the descriptor's hooks the chart this descriptor is
+   * registered with will read. Two arrived after the oldest chart the peer
+   * range accepts: a band's per-bar colour and the list of grids. From 2.5.4
+   * on, a band whose colour the script computes is drawn bar by bar and every
+   * declared grid is drawn. Before it, or when nothing is stated, the adapter
+   * cannot tell whether the chart will read either hook, and a chart that
+   * ignores one draws a band in its own default colours or the first grid
+   * alone, with nothing said. So such a program is refused before any bar runs
+   * with OS6024, which is what a host that states nothing got before this
+   * option existed.
+   *
+   * The version rather than a switch per hook, because it is one fact the
+   * host already holds, it moves with the chart the host actually installed,
+   * and a hook the adapter learns to read later needs nothing new from any
+   * host. `capabilities.ts` has the rule, prereleases and unreadable strings
+   * included.
+   */
+  readonly chartVersion?: string;
   /**
    * What the host has stored for this study's inputs, for the declared shape.
    *
@@ -338,7 +362,7 @@ function start(
 
   // What this chart has no room for is refused before the engine is asked,
   // because a study drawn without it is a study that looks broken.
-  const narrower = undrawable(program);
+  const narrower = undrawable(program, capabilitiesOf(options.chartVersion));
   if (narrower !== undefined) throw refused(narrower);
 
   const loaded = load(program, {

package/src/adapters/charts/surfaces.ts

@@ -125,6 +125,18 @@ export interface ChartGrid {
   readonly options?: ChartTableOptions;
 }
 
+/**
+ * One grid of several, under an identity the chart keeps it by.
+ *
+ * The chart reuses the grid a recompute names again and removes one it no
+ * longer names, so the id is the declaration's key: stable across recomputes,
+ * never empty, and unique within a program because the compiler writes one per
+ * declaration.
+ */
+export interface ChartTableSpec extends ChartGrid {
+  readonly id: string;
+}
+
 /** One end of a drawing: a time on the shared axis, a price on the pane's scale. */
 export interface ChartAnchor {
   readonly time: number;

package/src/adapters/charts/tables.ts

@@ -27,13 +27,17 @@
  * placed into it, which is what `language.md` 6.7 asks for from the other
  * direction: a cell nothing was written into is blank, never a zero.
  *
- * **A chart pane holds one grid and the language declares as many as it likes.**
- * The descriptor has one `table` hook, and merging two grids into it would put
- * cells somewhere the script never asked for. So a program declaring a second
- * grid never reaches this file: `undrawable.ts` refuses it before any bar runs,
- * with OS6024, and this reads the one grid a program that runs can have.
- * `spec/chart-narrowings.json` records the refusal and
- * `scripts/check-chart-surface.mjs` proves it with a study that declares two.
+ * **The language declares as many grids as it likes, and a chart with the list
+ * of grids draws them all** (`capabilities.ts` says which chart has it). The
+ * list holds each grid under an id the chart keeps it by, and every declared
+ * grid is built for it here under its declaration's key. The single `table`
+ * hook stays beside the list with the first grid in it, because a chart
+ * without the list reads that one. Merging two grids into the single hook
+ * would put cells somewhere the script never asked for, so on a chart without
+ * the list a program declaring a second grid never reaches this file:
+ * `undrawable.ts` refuses it before any bar runs, with OS6024.
+ * `spec/chart-narrowings.json` records both halves and
+ * `scripts/check-chart-surface.mjs` proves both with a study that declares two.
  */
 import type { CompiledProgram, Grid as DeclaredGrid } from '../../core/emit/index.js';
 import type { Grid, GridCell } from '../../core/engine/index.js';
@@ -45,6 +49,7 @@ import type {
   ChartCellAlign,
   ChartGrid,
   ChartTablePosition,
+  ChartTableSpec,
 } from './surfaces.js';
 
 /** The language's four corners, in the chart's own words. */
@@ -58,22 +63,34 @@ const CORNERS: Readonly<Record<string, ChartTablePosition>> = {
 const ALIGNMENTS: readonly string[] = ['left', 'center', 'right'];
 
 /**
- * The grid a chart draws, from the declaration and the engine's buffer.
+ * Every grid a chart draws, from the declarations and the engine's buffers.
  *
- * The buffer is paired with the declaration by the key both of them carry
+ * Each buffer is paired with its declaration by the key both of them carry
  * rather than by position. The engine reads its grids in declaration order, so
  * the two agree today, and a pairing by position is one reordering away from
  * drawing one grid's cells into another grid's shape, which would be a wrong
  * table that looks like a right one.
+ *
+ * The key is the id as well. The compiler writes one per declaration and never
+ * an empty one, and it does not move between recomputes, which is what lets the
+ * chart keep a grid rather than build it again on every tick.
  */
-export function buildTable(
+export function buildTables(
   program: CompiledProgram,
   lookup: InputLookup,
   written: readonly Grid[],
-): ChartGrid | null {
-  const declared = program.outputs.tables[0];
-  if (declared === undefined) return null;
-  return oneTable(declared, lookup, written.find((one) => one.key === declared.key));
+): readonly ChartTableSpec[] {
+  return program.outputs.tables.map((declared) => ({
+    id: declared.key,
+    ...oneTable(declared, lookup, written.find((one) => one.key === declared.key)),
+  }));
+}
+
+/** The first grid alone, for the single hook a chart without the list reads. */
+export function firstGrid(tables: readonly ChartTableSpec[]): ChartGrid | null {
+  const first = tables[0];
+  if (first === undefined) return null;
+  return { rows: first.rows, ...(first.options === undefined ? {} : { options: first.options }) };
 }
 
 function oneTable(

package/src/adapters/charts/undrawable.ts

@@ -3,17 +3,24 @@
  *
  * `compiled-program.md` section 11: a host draws what its surface has room for,
  * and refuses what it does not with OS6024 rather than drawing part of a study
- * and saying nothing. Two things a version 1 program can declare have no place
- * on this chart's surface, and both used to be dropped in silence.
+ * and saying nothing. Two things a version 1 program can declare have a place
+ * on a newer chart and none on an older one (`capabilities.ts` says which is
+ * which), and on an older one both used to be dropped in silence.
  *
- * - **A second grid.** The descriptor has one `table` hook, so one grid reaches
- *   a pane. Merging two into it would put cells somewhere the script never
- *   asked for, and drawing the first alone is a study whose second panel never
- *   appears and whose cells look broken.
- * - **A band colour computed per bar.** The chart's band takes one colour for
- *   the whole run and has no channel to point at, so a band whose colour the
- *   script computes was drawn in the first plot's colour faded, which is a
- *   colour the script did not choose.
+ * - **A second grid.** An older descriptor has one `table` hook, so one grid
+ *   reaches a pane. Merging two into it would put cells somewhere the script
+ *   never asked for, and drawing the first alone is a study whose second panel
+ *   never appears and whose cells look broken. A newer chart's list of grids
+ *   carries every one (`tables.ts`).
+ * - **A band colour computed per bar.** An older chart's band takes one colour
+ *   for each side for the whole run, and a band whose colour the script
+ *   computes would be drawn in a colour the script did not choose. A newer
+ *   chart's band has a per-bar colour callback (`fills.ts`).
+ *
+ * Which chart the descriptor is registered with is what the host states, and
+ * `capabilities.ts` reads it. A host that states nothing is refused both, as
+ * before, because a chart that ignores a hook it does not know draws the
+ * silent version of each.
  *
  * The compiled program carries no source position for a declaration, so the
  * refusal names the declaration by its title, which is what a reader sees in
@@ -22,23 +29,26 @@
 import { diagnosticFor, makeSpan } from '../../core/index.js';
 import type { Diagnostic } from '../../core/index.js';
 import type { CompiledProgram, Field } from '../../core/emit/index.js';
+import { lacking } from './capabilities.js';
+import type { ChartCapabilities } from './capabilities.js';
 
 /** A load refusal has no line of its own: the program is what was refused. */
 const AT_LOAD = makeSpan(0, 0, 0, 0);
 
-export function undrawable(program: CompiledProgram): Diagnostic | undefined {
+export function undrawable(program: CompiledProgram, chart: ChartCapabilities): Diagnostic | undefined {
   const second = program.outputs.tables[1];
-  if (second !== undefined) {
+  if (second !== undefined && !chart.grids) {
     return diagnosticFor('OS6024', AT_LOAD, {
       what: `the table ${titled(second.title, 'after the first')}, the second grid this study declares`,
-      limit: 'a chart pane draws one grid',
+      limit: lacking(chart, 'grids', 'a chart pane draws one grid'),
     });
   }
+  if (chart.bandColours) return undefined;
   for (const band of program.outputs.fills) {
     if (band.colorUpChannel !== null || band.colorDownChannel !== null) {
       return diagnosticFor('OS6024', AT_LOAD, {
         what: "a band's colour that is computed per bar",
-        limit: "a chart's band takes one colour for the whole run",
+        limit: lacking(chart, 'bandColours', "a chart's band takes one colour for the whole run"),
       });
     }
   }

package/src/core/check/call-sites.ts

@@ -157,7 +157,7 @@ function checkRequest(
     checker.report('OS6001', timeframe?.span ?? call.span, { value: written });
   }
 
-  const mode = modeOf(call);
+  const mode = modeOf(checked);
   if (mode === 'lookahead') {
     checker.report('OS8005', call.span, { mode });
     checker.repaints = true;
@@ -195,14 +195,24 @@ function timeframeArgument(call: Call, name: string): Argument | undefined {
   return positional[name === 'req.symbol' ? 1 : 0];
 }
 
-function modeOf(call: Call): RequestMode {
-  const labelled = call.args.find((one) => one.label?.text === 'mode');
-  const written = labelled === undefined ? undefined : stringLiteral(labelled.value);
+/**
+ * The mode as the signature bound it, written by its label or in its place.
+ *
+ * `language.md` 11.2 fills parameters from the left, so `mode` is the third
+ * argument of `req.timeframe` and the fifth of `req.symbol` whether or not it
+ * carries its label, and the emitter reads every other argument of a read from
+ * the same binding. Looking for the label alone read a positional
+ * `"lookahead"` as the default: the study ran confirmed, with no OS8005 and no
+ * repaint mark, while its source named the mode on the line.
+ */
+function modeOf(checked: CheckedCall): RequestMode {
+  const bound = argumentOf(checked, 'mode');
+  const written = bound === undefined ? undefined : stringLiteral(bound.value);
   if (written === 'confirmed' || written === 'developing' || written === 'lookahead') {
     return written;
   }
   // The default is the one mode that never repaints (stdlib.md 15.3).
-  return labelled === undefined ? 'confirmed' : 'unknown';
+  return bound === undefined ? 'confirmed' : 'unknown';
 }
 
 function stringLiteral(expression: Expression): string | undefined {

package/src/core/version/version.generated.ts

@@ -4,7 +4,7 @@
 // spec/compiled-program.md, so neither can drift from the thing it names.
 
 /** This build's package version. The release refuses to publish unless the tag, the manifest and this agree. */
-export const VERSION = "0.7.2";
+export const VERSION = "0.8.1";
 
 /**
  * The compiled program format this compiler emits.