openalgo-script 0.5.0 → 0.6.0

package/src/core/importer/syntax.ts

@@ -0,0 +1,144 @@
+/**
+ * The tree the importer reads a source script into.
+ *
+ * It holds the subset of the source dialect the importer can say something
+ * about, and one node for everything else: a statement the reader could not
+ * take apart is kept whole as `refused`, carrying the few words that name what
+ * it is, so the translator can report it and keep it as a comment without
+ * having to understand it.
+ */
+import type { Remark } from './lexer.js';
+
+/** A stretch of the input text: where a finding's caret goes. */
+export interface Place {
+  readonly offset: number;
+  readonly length: number;
+}
+
+export type Expr =
+  | { readonly kind: 'number'; readonly text: string; readonly at: Place }
+  | { readonly kind: 'string'; readonly value: string; readonly at: Place }
+  | { readonly kind: 'bool'; readonly value: boolean; readonly at: Place }
+  | { readonly kind: 'color'; readonly text: string; readonly at: Place }
+  | { readonly kind: 'name'; readonly name: string; readonly at: Place }
+  | { readonly kind: 'member'; readonly object: Expr; readonly property: string; readonly at: Place }
+  | { readonly kind: 'call'; readonly callee: Expr; readonly args: readonly Arg[]; readonly at: Place }
+  | { readonly kind: 'index'; readonly target: Expr; readonly index: Expr; readonly at: Place }
+  | { readonly kind: 'unary'; readonly op: string; readonly operand: Expr; readonly at: Place }
+  | {
+      readonly kind: 'binary';
+      readonly op: string;
+      readonly left: Expr;
+      readonly right: Expr;
+      readonly at: Place;
+      readonly opAt: Place;
+    }
+  | {
+      readonly kind: 'ternary';
+      readonly condition: Expr;
+      readonly then: Expr;
+      readonly otherwise: Expr;
+      readonly at: Place;
+    }
+  | { readonly kind: 'group'; readonly inner: Expr; readonly at: Place }
+  | { readonly kind: 'list'; readonly items: readonly Expr[]; readonly at: Place };
+
+export type CallExpr = Extract<Expr, { kind: 'call' }>;
+
+export interface Arg {
+  /** The label of a named argument, or undefined for a positional one. */
+  readonly label: string | undefined;
+  readonly value: Expr;
+  readonly at: Place;
+}
+
+/** The physical lines of the input a statement covers, its block included. */
+export interface Lines {
+  readonly first: number;
+  readonly last: number;
+}
+
+interface Common {
+  /** The statement's head, where a finding about the whole statement points. */
+  readonly at: Place;
+  readonly lines: Lines;
+  readonly remarks: readonly Remark[];
+}
+
+export interface Named {
+  readonly name: string;
+  readonly at: Place;
+}
+
+export interface Param {
+  readonly name: string;
+  readonly at: Place;
+  readonly fallback: Expr | undefined;
+}
+
+export interface Branch {
+  readonly condition: Expr;
+  readonly body: Body;
+}
+
+export interface Arm {
+  /** The value or condition the arm matches, undefined for the default arm. */
+  readonly match: Expr | undefined;
+  readonly body: Body;
+}
+
+export type Stmt =
+  | (Common & {
+      readonly kind: 'declare';
+      readonly mode: 'plain' | 'var' | 'varip';
+      readonly name: Named;
+      readonly value: Expr;
+    })
+  | (Common & { readonly kind: 'tuple'; readonly names: readonly Named[]; readonly value: Expr })
+  | (Common & { readonly kind: 'assign'; readonly op: string; readonly name: Named; readonly value: Expr })
+  | (Common & { readonly kind: 'evaluate'; readonly expr: Expr })
+  | (Common & { readonly kind: 'if'; readonly branches: readonly Branch[]; readonly otherwise: Body | undefined })
+  | (Common & {
+      readonly kind: 'for';
+      readonly variable: Named;
+      readonly from: Expr;
+      readonly to: Expr;
+      readonly by: Expr | undefined;
+      readonly body: Body;
+    })
+  | (Common & { readonly kind: 'while'; readonly condition: Expr; readonly body: Body })
+  | (Common & { readonly kind: 'switch'; readonly subject: Expr | undefined; readonly arms: readonly Arm[] })
+  | (Common & { readonly kind: 'break' | 'continue' })
+  | (Common & {
+      readonly kind: 'function';
+      readonly name: Named;
+      readonly params: readonly Param[];
+      readonly body: Expr | Body;
+    })
+  | (Common & {
+      readonly kind: 'refused';
+      /** A few words naming the form, which fill the finding's placeholder. */
+      readonly construct: string;
+      /** Names the statement would have declared, so what reads them follows it. */
+      readonly declares: readonly Named[];
+    });
+
+export type Entry =
+  | { readonly kind: 'stmt'; readonly stmt: Stmt }
+  | { readonly kind: 'remark'; readonly remark: Remark }
+  | { readonly kind: 'blank'; readonly line: number };
+
+export type Body = readonly Entry[];
+
+/** `ta.sma` for a member chain of plain names, and undefined for anything else. */
+export function pathOf(expr: Expr): string | undefined {
+  if (expr.kind === 'name') return expr.name;
+  if (expr.kind !== 'member') return undefined;
+  const base = pathOf(expr.object);
+  return base === undefined ? undefined : `${base}.${expr.property}`;
+}
+
+/** The place covering two places and everything between them. */
+export function joined(first: Place, last: Place): Place {
+  return { offset: first.offset, length: Math.max(last.offset + last.length - first.offset, 0) };
+}

package/src/core/importer/table.ts

@@ -0,0 +1,191 @@
+/**
+ * Every built-in the importer translates, and what it becomes.
+ *
+ * This table is the one statement of that mapping. The importer reads it, and
+ * the documentation page's table is compared with it row for row by
+ * `tests/importer/table.test.ts`, so the page cannot teach a mapping the
+ * importer does not make. A built-in with no row here is refused with OS9003
+ * rather than guessed at.
+ *
+ * `difference` says how far a translation can be trusted, and it is the reason
+ * a row exists at all rather than a remark about it:
+ *
+ *   - `exact`: the OpenScript call computes the same value on every bar where
+ *     the source's value is finite, absent bars included, or the importer
+ *     writes the expression that does. An OpenScript number is never infinite.
+ *   - `warmup`: the same quantity, whose first bars, seed, arithmetic order and
+ *     handling of an absent value inside its window are OpenScript's own
+ *     (`stdlib.md` 20). The first call of each raises OS9007.
+ *   - `orders`: an order call, placed under OpenScript's order model. The first
+ *     call of each raises OS9010.
+ *
+ * `stateful` marks a call that keeps state at its call site in OpenScript, so
+ * that skipping it on a bar changes what it returns later (`language.md`
+ * 11.4). It decides where the source dialect's evaluation order and
+ * OpenScript's differ, which is what the logic operators' translation is about.
+ */
+
+export type Difference = 'exact' | 'warmup' | 'orders';
+
+export interface Mapping {
+  /** The built-in as the source writes it, namespace included. */
+  readonly source: string;
+  /** What it becomes, as the documentation page prints it. */
+  readonly target: string;
+  /** The source's parameter names, in positional order. Empty for a value. */
+  readonly params: readonly string[];
+  /** The OpenScript parameter names the source's line up with, where they line up one to one. */
+  readonly targets: readonly string[];
+  readonly difference: Difference;
+  readonly stateful: boolean;
+  /** Set where the arguments do not line up one to one, naming the translator that handles it. */
+  readonly special: string | undefined;
+}
+
+type Row = readonly [string, string, string, string, Difference, boolean, string?];
+
+/**
+ * The rows, as source, target, source parameters, target parameters,
+ * difference, stateful and the special translator. Parameters are written as
+ * one space separated string so that a row stays one line.
+ */
+const ROWS: readonly Row[] = [
+  // Bar data and bar facts.
+  ['open', 'open', '', '', 'exact', false],
+  ['high', 'high', '', '', 'exact', false],
+  ['low', 'low', '', '', 'exact', false],
+  ['close', 'close', '', '', 'exact', false],
+  ['volume', 'volume', '', '', 'exact', false],
+  ['hl2', 'hl2', '', '', 'exact', false],
+  ['hlc3', 'hlc3', '', '', 'exact', false],
+  ['ohlc4', 'ohlc4', '', '', 'exact', false],
+  ['hlcc4', 'hlcc4', '', '', 'exact', false],
+  ['time', 'time', '', '', 'exact', false],
+  ['bar_index', 'bar.index', '', '', 'exact', false],
+  ['barstate.isfirst', 'bar.isFirst', '', '', 'exact', false],
+  ['barstate.islast', 'bar.isLast', '', '', 'exact', false],
+  ['barstate.isconfirmed', 'bar.isConfirmed', '', '', 'exact', false],
+  ['barstate.isrealtime', 'bar.isRealtime', '', '', 'exact', false],
+  ['barstate.isnew', 'bar.isNew', '', '', 'exact', false],
+  ['na', 'none', '', '', 'exact', false],
+  ['math.pi', 'math.pi', '', '', 'exact', false],
+  ['math.e', 'math.e', '', '', 'exact', false],
+  ['strategy.position_size', 'pos.size', '', '', 'exact', false],
+  ['strategy.position_avg_price', 'pos.avgPrice', '', '', 'exact', false],
+
+  // Moving averages and trend.
+  ['ta.sma', 'sma', 'source length', 'src len', 'warmup', true],
+  ['ta.ema', 'ema', 'source length', 'src len', 'warmup', true],
+  ['ta.wma', 'wma', 'source length', 'src len', 'warmup', true],
+  ['ta.rma', 'rma', 'source length', 'src len', 'warmup', true],
+  ['ta.hma', 'hma', 'source length', 'src len', 'warmup', true],
+  ['ta.vwma', 'vwma', 'source length', 'src len', 'warmup', true],
+  ['ta.swma', 'swma', 'source', 'src', 'warmup', true],
+  ['ta.linreg', 'linreg', 'source length offset', 'src len offset', 'warmup', true],
+  ['ta.macd', 'macd', 'source fastlen slowlen siglen', 'src fast slow signal', 'warmup', true, 'tuple'],
+  ['ta.supertrend', 'supertrend', 'factor atrPeriod', 'factor atrLen', 'warmup', true, 'tuple'],
+  ['ta.dmi', 'adx', 'diLength adxSmoothing', 'diLen adxLen', 'warmup', true, 'tuple'],
+
+  // Momentum, volatility and the series helpers.
+  ['ta.rsi', 'rsi', 'source length', 'src len', 'warmup', true],
+  ['ta.mom', 'mom', 'source length', 'src len', 'exact', true],
+  ['ta.roc', 'roc', 'source length', 'src len', 'warmup', true],
+  ['ta.change', 'change', 'source length', 'src len', 'exact', true],
+  ['ta.atr', 'atr', 'length', 'len', 'warmup', true],
+  ['ta.tr', 'trueRange', 'handle_na', '', 'exact', false, 'trueRange'],
+  ['ta.stdev', 'stdev', 'source length biased', 'src len sample', 'warmup', true, 'deviation'],
+  ['ta.variance', 'variance', 'source length biased', 'src len sample', 'warmup', true, 'deviation'],
+  ['ta.bb', 'bollinger', 'series length mult', 'src len mult', 'warmup', true, 'tuple'],
+  ['ta.highest', 'highest', 'source length', 'src len', 'warmup', true, 'extreme'],
+  ['ta.lowest', 'lowest', 'source length', 'src len', 'warmup', true, 'extreme'],
+  ['ta.crossover', 'crossUp', 'source1 source2', 'a b', 'exact', true],
+  ['ta.crossunder', 'crossDown', 'source1 source2', 'a b', 'exact', true],
+  ['ta.cross', 'cross', 'source1 source2', 'a b', 'exact', true],
+  ['ta.cum', 'cum', 'source', 'src', 'warmup', true],
+  ['ta.barssince', 'barsSince', 'condition', 'cond', 'warmup', true, 'condition'],
+  ['ta.valuewhen', 'valueWhen', 'condition source occurrence', 'cond src occurrence', 'warmup', true, 'condition'],
+  ['math.sum', 'sum', 'source length', 'src len', 'warmup', true],
+
+  // Maths, absence and conversion.
+  ['math.abs', 'abs', 'number', 'x', 'exact', false],
+  ['math.sign', 'sign', 'number', 'x', 'exact', false],
+  ['math.floor', 'floor', 'number', 'x', 'exact', false],
+  ['math.ceil', 'ceil', 'number', 'x', 'exact', false],
+  ['math.sqrt', 'sqrt', 'number', 'x', 'exact', false],
+  ['math.pow', 'pow', 'base exponent', 'x y', 'exact', false],
+  ['math.exp', 'exp', 'number', 'x', 'exact', false],
+  ['math.log', 'log', 'number', 'x', 'exact', false],
+  ['math.log10', 'log10', 'number', 'x', 'exact', false],
+  ['math.sin', 'math.sin', 'angle', 'x', 'exact', false],
+  ['math.cos', 'math.cos', 'angle', 'x', 'exact', false],
+  ['math.tan', 'math.tan', 'angle', 'x', 'exact', false],
+  ['math.asin', 'math.asin', 'angle', 'x', 'exact', false],
+  ['math.acos', 'math.acos', 'angle', 'x', 'exact', false],
+  ['math.atan', 'math.atan', 'angle', 'x', 'exact', false],
+  ['math.todegrees', 'math.toDegrees', 'radians', 'x', 'exact', false],
+  ['math.toradians', 'math.toRadians', 'degrees', 'x', 'exact', false],
+  ['math.max', 'max', 'number0 number1', 'a b', 'exact', false, 'extremes'],
+  ['math.min', 'min', 'number0 number1', 'a b', 'exact', false, 'extremes'],
+  ['na', 'isNone', 'x', 'x', 'exact', false],
+  ['nz', 'orElse', 'source replacement', 'x fallback', 'exact', false, 'fallback'],
+  ['int', 'trunc', 'x', 'x', 'exact', false],
+  ['float', 'float', 'x', 'x', 'exact', false, 'float'],
+  ['color.new', 'fade', 'color transp', 'color percent', 'exact', false],
+  ['color.rgb', 'rgb', 'red green blue transp', 'r g b', 'exact', false, 'rgb'],
+
+  // Declarations, inputs and what lands on the chart.
+  ['indicator', 'study', 'title', '', 'exact', false, 'declaration'],
+  ['strategy', 'strategy', 'title', '', 'exact', false, 'declaration'],
+  ['input', 'input', 'defval title', '', 'exact', false, 'input'],
+  ['input.int', 'input', 'defval title', '', 'exact', false, 'input'],
+  ['input.float', 'input', 'defval title', '', 'exact', false, 'input'],
+  ['input.bool', 'input', 'defval title', '', 'exact', false, 'input'],
+  ['input.color', 'input', 'defval title', '', 'exact', false, 'input'],
+  ['input.string', 'input', 'defval title', '', 'exact', false, 'input'],
+  ['input.source', 'input', 'defval title', '', 'exact', false, 'input'],
+  ['plot', 'plot', 'series title color', '', 'exact', false, 'plot'],
+  ['hline', 'level', 'price title color', '', 'exact', false, 'hline'],
+  ['fill', 'fill', 'plot1 plot2 color', '', 'exact', false, 'fill'],
+  ['bgcolor', 'background', 'color', '', 'exact', false, 'paint'],
+  ['barcolor', 'barColor', 'color', '', 'exact', false, 'paint'],
+  ['plotshape', 'signal', 'series title style', '', 'exact', false, 'shape'],
+
+  // Orders.
+  ['strategy.entry', 'buy or sell', 'id direction qty', '', 'orders', false, 'entry'],
+  ['strategy.close', 'close', 'id', '', 'orders', false, 'close'],
+  ['strategy.close_all', 'close', '', '', 'orders', false, 'closeAll'],
+  ['strategy.exit', 'exit', 'id from_entry', '', 'orders', false, 'exit'],
+];
+
+const words = (text: string): readonly string[] => (text === '' ? [] : text.split(' '));
+
+export const MAPPINGS: readonly Mapping[] = ROWS.map(
+  ([source, target, params, targets, difference, stateful, special]) => ({
+    source,
+    target,
+    params: words(params),
+    targets: words(targets),
+    difference,
+    stateful,
+    special,
+  }),
+);
+
+/** The rows that are read as a value, keyed by the source spelling. */
+export const VALUES: ReadonlyMap<string, Mapping> = new Map(
+  MAPPINGS.filter((row) => row.params.length === 0 && row.special === undefined).map((row) => [row.source, row]),
+);
+
+/** The rows that are called, keyed by the source spelling. */
+export const CALLS: ReadonlyMap<string, Mapping> = new Map(
+  MAPPINGS.filter((row) => row.params.length > 0 || row.special !== undefined).map((row) => [row.source, row]),
+);
+
+/**
+ * The colour names both languages have, which translate to OpenScript's colour
+ * of the same name. The channel values are OpenScript's (`spec/colours.json`).
+ */
+export const COLOURS: ReadonlySet<string> = new Set([
+  'aqua', 'black', 'blue', 'fuchsia', 'gray', 'green', 'lime', 'maroon', 'navy',
+  'olive', 'orange', 'purple', 'red', 'silver', 'teal', 'white', 'yellow',
+]);

package/src/core/importer/values.ts

@@ -0,0 +1,241 @@
+/**
+ * Expressions, written out as OpenScript text.
+ *
+ * Each translation carries the precedence of its outermost operator, and a
+ * parent wraps a child in brackets only where OpenScript's grammar would
+ * otherwise group it differently, so the output groups exactly as the source
+ * did (`language.md` 9.1). Brackets the source wrote are kept as written.
+ *
+ * Three operators are where the two languages part, and each is translated to
+ * the source dialect's meaning rather than to the nearest spelling:
+ *
+ *   - `not`, which the source dialect applies to a comparison it has already
+ *     answered `false` on an absent side, is written over `orElse(x, false)`.
+ *   - `and` and `or`, whose right operand version 5 always evaluates and
+ *     version 6 evaluates only when its left operand did not decide, where
+ *     OpenScript also evaluates it when the left is absent (`language.md` 9.4).
+ *     That matters only where the right operand holds state, and there version
+ *     5's operand is moved to a line of its own and version 6's left operand is
+ *     written over `orElse`.
+ *   - `==` against `na`, which the source dialect answers `false` on every bar,
+ *     is refused rather than translated to a test for absence.
+ */
+import { diagnosticFor } from '../diagnostics/index.js';
+import { translateCall, trueRangeValue } from './calls.js';
+import type { Context } from './context.js';
+import { quoted } from './context.js';
+import { holdsState, neverAbsent, wholeConstant } from './presence.js';
+import { pathOf } from './syntax.js';
+import type { Expr } from './syntax.js';
+import { COLOURS, VALUES } from './table.js';
+
+export const PREC = {
+  ternary: 1,
+  or: 2,
+  and: 3,
+  equality: 4,
+  comparison: 5,
+  additive: 6,
+  multiplicative: 7,
+  unary: 8,
+  atom: 9,
+} as const;
+
+export interface Out {
+  readonly text: string;
+  readonly prec: number;
+}
+
+export const atom = (text: string): Out => ({ text, prec: PREC.atom });
+
+/** Stands in for a translation that was refused; the statement is not written. */
+export const NOTHING = atom('none');
+
+export function wrap(out: Out, min: number): string {
+  return out.prec >= min ? out.text : `(${out.text})`;
+}
+
+/** The words OS9002 names a strict operand the importer cannot move with. */
+export const STRICT = 'a version 5 and or or whose second operand holds state, in a condition that runs only on some passes';
+
+/** A number as OpenScript writes one: no trailing point, a lower case exponent. */
+export function numberText(text: string): string {
+  const lower = text.toLowerCase();
+  const [mantissa = '', exponent] = lower.split('e');
+  const tidy = mantissa.endsWith('.') ? `${mantissa}0` : mantissa;
+  return exponent === undefined ? tidy : `${tidy}e${exponent}`;
+}
+
+export function translate(ctx: Context, expr: Expr): Out {
+  switch (expr.kind) {
+    case 'number':
+      return atom(numberText(expr.text));
+    case 'string':
+      return atom(quoted(expr.value));
+    case 'bool':
+      return atom(expr.value ? 'true' : 'false');
+    case 'color':
+      return atom(expr.text.toLowerCase());
+    case 'name':
+      return nameOf(ctx, expr);
+    case 'member':
+      return memberOf(ctx, expr);
+    case 'call':
+      return translateCall(ctx, expr);
+    case 'index': {
+      const target = translate(ctx, expr.target);
+      const index = translate(ctx, expr.index);
+      return atom(`${wrap(target, PREC.atom)}[${index.text}]`);
+    }
+    case 'unary':
+      return unaryOf(ctx, expr);
+    case 'binary':
+      return binaryOf(ctx, expr);
+    case 'ternary':
+      return ternaryOf(ctx, expr);
+    case 'group':
+      return atom(`(${translate(ctx, expr.inner).text})`);
+    case 'list':
+      ctx.refuse(diagnosticFor('OS9002', ctx.span(expr.at), { construct: 'an array or tuple literal' }));
+      return NOTHING;
+  }
+}
+
+function nameOf(ctx: Context, expr: Extract<Expr, { kind: 'name' }>): Out {
+  const binding = ctx.lookup(expr.name, expr.at);
+  if (binding !== undefined) {
+    if (binding.kind === 'function') {
+      ctx.refuse(diagnosticFor('OS9002', ctx.span(expr.at), { construct: 'a function used as a value' }));
+      return NOTHING;
+    }
+    return atom(binding.output);
+  }
+  const row = VALUES.get(expr.name);
+  if (row !== undefined) return atom(row.target);
+  ctx.refuse(diagnosticFor('OS9003', ctx.span(expr.at), { name: expr.name }));
+  return NOTHING;
+}
+
+function memberOf(ctx: Context, expr: Extract<Expr, { kind: 'member' }>): Out {
+  const path = pathOf(expr);
+  const root = path?.split('.')[0];
+  if (path === undefined || root === undefined || ctx.lookup(root, expr.at) !== undefined) {
+    ctx.refuse(diagnosticFor('OS9002', ctx.span(expr.at), { construct: 'a field read from a value' }));
+    return NOTHING;
+  }
+  if (path === 'ta.tr') return trueRangeValue();
+  const row = VALUES.get(path);
+  if (row !== undefined) return atom(row.target);
+  if (root === 'color' && COLOURS.has(expr.property)) return atom(expr.property);
+  ctx.refuse(diagnosticFor('OS9003', ctx.span(expr.at), { name: path }));
+  return NOTHING;
+}
+
+/** The expression inside any brackets the source wrapped it in. */
+function unwrapped(expr: Expr): Expr {
+  return expr.kind === 'group' ? unwrapped(expr.inner) : expr;
+}
+
+function unaryOf(ctx: Context, expr: Extract<Expr, { kind: 'unary' }>): Out {
+  if (expr.op === 'not' && !neverAbsent(ctx, expr.operand)) {
+    return { text: `not orElse(${translate(ctx, unwrapped(expr.operand)).text}, false)`, prec: PREC.unary };
+  }
+  const operand = translate(ctx, expr.operand);
+  if (expr.op === 'not') return { text: `not ${wrap(operand, PREC.unary)}`, prec: PREC.unary };
+  const inner = wrap(operand, PREC.unary);
+  const text = inner.startsWith('-') || inner.startsWith('+') ? `${expr.op}(${inner})` : `${expr.op}${inner}`;
+  return { text, prec: PREC.unary };
+}
+
+/** A translation written as an argument, without the one pair of brackets the source put round it. */
+function bare(out: Out): string {
+  const text = out.text;
+  if (!text.startsWith('(') || !text.endsWith(')')) return text;
+  let depth = 0;
+  for (let i = 0; i < text.length; i += 1) {
+    if (text[i] === '(') depth += 1;
+    else if (text[i] === ')') depth -= 1;
+    if (depth === 0 && i < text.length - 1) return text;
+  }
+  return text.slice(1, -1);
+}
+
+function isNa(ctx: Context, expr: Expr): boolean {
+  return expr.kind === 'name' && expr.name === 'na' && ctx.scope.find('na') === undefined;
+}
+
+function equalityOf(ctx: Context, expr: Extract<Expr, { kind: 'binary' }>): Out {
+  if (isNa(ctx, expr.left) || isNa(ctx, expr.right)) {
+    ctx.refuse(diagnosticFor('OS9002', ctx.span(expr.at), { construct: 'a comparison with na' }));
+    return NOTHING;
+  }
+  const left = translate(ctx, expr.left);
+  const right = translate(ctx, expr.right);
+  let leftText = wrap(left, PREC.equality + 1);
+  let rightText = wrap(right, PREC.equality + 1);
+  const leftPresent = neverAbsent(ctx, expr.left);
+  const rightPresent = neverAbsent(ctx, expr.right);
+  if (expr.right.kind === 'bool' && !leftPresent) leftText = `orElse(${bare(left)}, false)`;
+  else if (expr.left.kind === 'bool' && !rightPresent) rightText = `orElse(${bare(right)}, false)`;
+  else if (!leftPresent && !rightPresent) {
+    ctx.note(diagnosticFor('OS9011', ctx.span(expr.opAt), { operator: expr.op }));
+  }
+  return { text: `${leftText} ${expr.op} ${rightText}`, prec: PREC.equality };
+}
+
+function logicOf(ctx: Context, expr: Extract<Expr, { kind: 'binary' }>): Out {
+  const prec = expr.op === 'and' ? PREC.and : PREC.or;
+  const left = translate(ctx, expr.left);
+  let leftText = wrap(left, prec);
+  let right: Out;
+  if (!holdsState(ctx, expr.right)) {
+    right = translate(ctx, expr.right);
+  } else if (ctx.facts.version === 5) {
+    const operand = translate(ctx, expr.right);
+    if (ctx.refused) return NOTHING;
+    const name = ctx.hoist(operand.text);
+    if (name === undefined) {
+      ctx.refuse(diagnosticFor('OS9002', ctx.span(expr.opAt), { construct: STRICT }));
+      return NOTHING;
+    }
+    right = atom(name);
+  } else {
+    right = translate(ctx, expr.right);
+    if (expr.op === 'and' && !neverAbsent(ctx, expr.left)) leftText = `orElse(${left.text}, false)`;
+  }
+  return { text: `${leftText} ${expr.op} ${wrap(right, prec + 1)}`, prec };
+}
+
+function binaryOf(ctx: Context, expr: Extract<Expr, { kind: 'binary' }>): Out {
+  switch (expr.op) {
+    case 'and':
+    case 'or':
+      return logicOf(ctx, expr);
+    case '==':
+    case '!=':
+      return equalityOf(ctx, expr);
+  }
+  const left = translate(ctx, expr.left);
+  const right = translate(ctx, expr.right);
+  let prec: number = PREC.comparison;
+  if (expr.op === '+' || expr.op === '-') prec = PREC.additive;
+  else if (expr.op === '*' || expr.op === '/' || expr.op === '%') prec = PREC.multiplicative;
+  if (expr.op === '/' && ctx.facts.version === 5 && wholeConstant(ctx, expr.left) && wholeConstant(ctx, expr.right)) {
+    ctx.note(diagnosticFor('OS9008', ctx.span(expr.opAt), {}));
+  }
+  // Comparisons do not chain in OpenScript, so both sides are wrapped past them.
+  const leftMin = prec === PREC.comparison ? prec + 1 : prec;
+  return { text: `${wrap(left, leftMin)} ${expr.op} ${wrap(right, prec + 1)}`, prec };
+}
+
+function ternaryOf(ctx: Context, expr: Extract<Expr, { kind: 'ternary' }>): Out {
+  const condition = translate(ctx, expr.condition);
+  ctx.lazy += 1;
+  try {
+    const then = translate(ctx, expr.then);
+    const otherwise = translate(ctx, expr.otherwise);
+    return { text: `${wrap(condition, PREC.or)} ? ${then.text} : ${wrap(otherwise, PREC.ternary)}`, prec: PREC.ternary };
+  } finally {
+    ctx.lazy -= 1;
+  }
+}

package/src/core/index.ts

@@ -288,6 +288,19 @@ export type { Value } from './engine/index.js';
 export { LANGUAGE_VERSIONS, capabilitiesFor, verify } from './engine/index.js';
 export type { VerifyOptions, VerifyResult } from './engine/index.js';
 
+/**
+ * The importer: a script written in another chart language in, OpenScript text
+ * and findings out (`docs/writing/importing-a-script.md`).
+ *
+ * It sits beside the compiler because it is the same kind of thing, a pure
+ * function from text to text with diagnostics, and because it compiles its own
+ * output before returning it so that what it hands back compiles. Every finding
+ * carries a catalogue code in the OS9xxx range and a position in the text that
+ * was imported, not in the text that came out.
+ */
+export { importScript } from './importer/index.js';
+export type { ImportOptions, ImportResult } from './importer/index.js';
+
 /**
  * The money, and the run it is folded from (`stdlib.md` 17.1, 17.7).
  *

package/src/core/stdlib/calendar/civil.ts

@@ -29,7 +29,10 @@ export interface Civil {
 /** Days from 1970-01-01 to this civil date. */
 export function dayNumber(year: number, month: number, day: number): number {
   const shifted = month <= 2 ? year - 1 : year;
-  const era = Math.floor((shifted >= 0 ? shifted : shifted - 399) / 400);
+  // A floor division, and nothing added to it: the published form subtracts 399
+  // from a negative year so that a truncating division floors, and this one
+  // already does. Doing both put every date before about 1 BCE one day early.
+  const era = Math.floor(shifted / 400);
   const yearOfEra = shifted - era * 400;
   const dayOfYear = Math.floor((153 * (month + (month > 2 ? -3 : 9)) + 2) / 5) + day - 1;
   const dayOfEra = yearOfEra * 365 + Math.floor(yearOfEra / 4) - Math.floor(yearOfEra / 100) + dayOfYear;
@@ -39,7 +42,7 @@ export function dayNumber(year: number, month: number, day: number): number {
 /** The civil date a day number names, the exact inverse of `dayNumber`. */
 export function dateOfDay(days: number): { year: number; month: number; day: number } {
   const shifted = days + 719468;
-  const era = Math.floor((shifted >= 0 ? shifted : shifted - 146096) / 146097);
+  const era = Math.floor(shifted / 146097);
   const dayOfEra = shifted - era * 146097;
   const yearOfEra = Math.floor(
     (dayOfEra - Math.floor(dayOfEra / 1460) + Math.floor(dayOfEra / 36524) - Math.floor(dayOfEra / 146096)) / 365,

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.5.0";
+export const VERSION = "0.6.0";
 
 /**
  * The compiled program format this compiler emits.