openalgo-script 0.4.0 → 0.6.0

package/src/core/engine/requests.ts

@@ -48,6 +48,8 @@
  */
 import type { Span } from '../span/index.js';
 import type { HostBar } from './bars.js';
+import { sourceOf } from './bar-source.js';
+import type { BarSource } from './bar-source.js';
 import type { Clock, EngineLimits } from './budget.js';
 import type { EngineHost } from './host.js';
 import type { ResolvedInput } from './inputs.js';
@@ -97,7 +99,7 @@ interface Read {
   readonly register: number;
   readonly body: RequestBody;
   /** The host's bars for a `symbol` read, or nothing when the fold is the chart's. */
-  readonly source: readonly HostBar[] | undefined;
+  readonly source: BarSource | undefined;
   readonly ready: boolean;
   readonly reason: string;
   /** How far into the source the fold has read. */
@@ -146,7 +148,7 @@ export class RequestSet {
    * have been revised since the last execution, and the bucket it is inside has
    * to be rebuilt from the revision rather than from the reading it replaced.
    */
-  fill(registers: Registers, bars: readonly HostBar[], index: number, fresh: boolean): void {
+  fill(registers: Registers, bars: BarSource, index: number, fresh: boolean): void {
     const heap = this.parts.heapOf();
     for (const read of this.reads) {
       if (fresh) {
@@ -227,7 +229,7 @@ function build(parts: RequestParts, request: Request, plan: RequestPlan): Read {
     plan,
     register: request.series,
     body,
-    source: answer !== undefined && 'bars' in answer ? answer.bars : undefined,
+    source: answer !== undefined && 'bars' in answer ? sourceOf(answer.bars) : undefined,
     // A fold of the chart's own bars needs nothing from the host, so it is
     // answered the moment it is planned. A read the host is still fetching is
     // not: the read is absent, `req.isReady` is false, and the study keeps
@@ -247,9 +249,9 @@ function build(parts: RequestParts, request: Request, plan: RequestPlan): Read {
 }
 
 /** The read's value for the chart bar at `index`, and the fold that gets there. */
-function valueOf(read: Read, bars: readonly HostBar[], index: number): Value {
+function valueOf(read: Read, bars: BarSource, index: number): Value {
   if (!read.ready) return ABSENT;
-  const bar = bars[index];
+  const bar = bars.at(index);
   const at = bar?.time ?? null;
   if (at === null) return ABSENT;
   const key = keyOf(read, at);
@@ -258,7 +260,7 @@ function valueOf(read: Read, bars: readonly HostBar[], index: number): Value {
   const source = read.source ?? bars;
   const lookahead = read.plan.request.mode === 'lookahead';
   for (;;) {
-    const next = source[read.cursor];
+    const next = source.at(read.cursor);
     if (next === undefined) break;
     const found = next.time === null ? undefined : keyOf(read, next.time);
     if (found === undefined) {
@@ -310,7 +312,7 @@ function feed(read: Read, bar: HostBar, key: number): void {
 }
 
 /** A re-executed bar: the fold as it stood when the bar began. */
-function restore(read: Read, bars: readonly HostBar[]): void {
+function restore(read: Read, bars: BarSource): void {
   read.cursor = read.mark.cursor;
   read.openKey = read.mark.openKey;
   read.openFrom = read.mark.openFrom;
@@ -318,7 +320,7 @@ function restore(read: Read, bars: readonly HostBar[]): void {
   if (read.openKey === undefined) return;
   const source = read.source ?? bars;
   for (let at = read.openFrom; at < read.cursor; at += 1) {
-    const bar = source[at];
+    const bar = source.at(at);
     if (bar === undefined || bar.time === null) continue;
     if (keyOf(read, bar.time) !== read.openKey) continue;
     read.open = read.open === undefined ? start(bar) : extend(read.open, bar);
@@ -380,3 +382,4 @@ function lower(a: number | null, b: number | null | undefined): number | null {
 function both(a: number | null, b: number | null): number | null {
   return a === null || b === null ? null : a + b;
 }
+

package/src/core/engine/series.ts

@@ -1,5 +1,5 @@
 /**
- * The two things the engine checks about the bars it is handed,
+ * The three things the engine checks about the bars it is handed,
  * `host-interface.md` 3.5 and conformance item 1.
  *
  * Everything else about a series the engine takes exactly as stated: it does
@@ -55,6 +55,23 @@ export function noBars(instrument: Instrument | undefined): Diagnostic {
   });
 }
 
+/**
+ * A bar handed over with no time, OS6025.
+ *
+ * `host-interface.md` 3.1 states `time` for every bar with no absent case, and
+ * the order rule is built on it. Reading a missing one as the absent value, as
+ * `barField` would, steps the bar over every calendar fold and makes every
+ * session fact absent on a bar that is on the chart: a study draws a gap where
+ * the host has data, and nothing says why. It is a bar of the wrong shape, not
+ * one out of order, so it has a code and a fix of its own. A time that is not a
+ * finite number is no time either.
+ */
+export function undated(bar: HostBar, index: number): Diagnostic | undefined {
+  const time: unknown = bar.time;
+  if (typeof time === 'number' && Number.isFinite(time)) return undefined;
+  return failure('OS6025', NO_POSITION, { index });
+}
+
 /**
  * A bar whose time does not follow the one before it, OS6011.
  *
@@ -63,11 +80,9 @@ export function noBars(instrument: Instrument | undefined): Diagnostic {
  * only one whose position tells the host where its own ordering went wrong.
  *
  * `previous` is the bar already handed over, or nothing for the first bar of a
- * run, which follows nothing and is therefore always in order. A time the host
- * did not state is not compared: the absent value is what `barField` gives a
- * script for it (3.1), and the catalogue has no code for a bar dated nothing,
- * so inventing this one for it would be a refusal the specification does not
- * describe.
+ * run, which follows nothing and is therefore always in order. A bar with no
+ * time never reaches this comparison: `undated` refuses it first, because a
+ * bar dated nothing is not two instants in the wrong order.
  */
 export function outOfOrder(
   bar: HostBar,
@@ -80,3 +95,12 @@ export function outOfOrder(
   if (time > before) return undefined;
   return failure('OS6011', NO_POSITION, { index, time, previous: index - 1 });
 }
+
+/** Both checks of a bar handed over, in the order they are made: its shape, then its order. */
+export function handOver(
+  bar: HostBar,
+  previous: HostBar | undefined,
+  index: number,
+): Diagnostic | undefined {
+  return undated(bar, index) ?? outOfOrder(bar, previous, index);
+}

package/src/core/engine/session/record.ts

@@ -106,10 +106,10 @@ function hoursOf(stated: SessionHours | undefined): Hours | null {
  *
  * Each of the three is reported at load rather than answered with absence,
  * because absence there is indistinguishable from the honest case and the honest
- * case is the one a reader will assume. This decides nothing about what a bare
- * read of an instrument fact returns, which is issue 0002 and is open: a record
- * the host contradicts itself in is a different question from a fact it did not
- * state.
+ * case is the one a reader will assume. A bare read of an instrument fact the
+ * host did not state is a different question with the opposite answer: it is
+ * absent and never refused (`host-interface.md` 4.5, decision 66), because a
+ * record the host contradicts itself in is not a fact it left out.
  */
 export function recordProblem(
   stated: SessionHours | undefined,

package/src/core/engine/verify-tables.ts

@@ -21,8 +21,51 @@ const META_KINDS = ['study', 'strategy'] as const;
 const CHANNEL_TYPES = ['number', 'string', 'color', 'bool'] as const;
 const EFFECTS = ['none', 'signal', 'order', 'draw', 'log'] as const;
 
+/**
+ * The tables a later minor of this format major added, with the minor that
+ * added each.
+ *
+ * 9.2's rule read from the other side, which 9.4 step 3 states and decision 56
+ * settled: a table a later minor added and an earlier program lacks reads as
+ * empty, never as a refusal, because 9.5's first line is a promise about that
+ * program. A program stamped at this minor or a later one has no such excuse.
+ * Section 2 says an empty table is written as an empty array and never
+ * omitted, so its absence there is the defect check 1 exists for, and the
+ * version is what tells the two apart.
+ *
+ * `spec/format-history.json` records the same additions, one entry per format
+ * version, and `tests/engine/format-minors.test.ts` holds this list to that
+ * file: a table the history says a later minor added has to be one a program
+ * at the earlier minor may lack.
+ */
+const ADDED_AT_MINOR: readonly { readonly table: string; readonly minor: number }[] = [
+  { table: 'requests', minor: 1 },
+];
+
+/** The minor of a `major.minor` the version step has already proved is one. */
+function minorOf(raw: Readonly<Record<string, unknown>>): number {
+  const version = raw['openscript'] as Readonly<Record<string, unknown>>;
+  return Number(String(version['format']).split('.')[1] ?? '0');
+}
+
+/**
+ * Writes the empty table an earlier minor is owed into the program itself.
+ *
+ * Into the object rather than into a local, because every later step reads
+ * the program as its own type and would find the table missing again: the
+ * verifier hands the same object on, and the engine holds it.
+ */
+function supplyAddedTables(raw: Readonly<Record<string, unknown>>): void {
+  const minor = minorOf(raw);
+  for (const added of ADDED_AT_MINOR) {
+    if (raw[added.table] !== undefined || minor >= added.minor) continue;
+    (raw as Record<string, unknown>)[added.table] = [];
+  }
+}
+
 /** Check 1 over every table the machine indexes, and every declaration field. */
 export function checkTables(shape: ShapeCheck, raw: Readonly<Record<string, unknown>>): boolean {
+  supplyAddedTables(raw);
   for (const name of ['requires', 'inputs', 'channels', 'consts', 'series', 'cells', 'states',
     'functions', 'callSites', 'loops', 'code', 'requests']) {
     if (!shape.array(raw[name], name)) return false;

package/src/core/importer/calls.ts

@@ -0,0 +1,274 @@
+/**
+ * Calls, written out as OpenScript text.
+ *
+ * A call to a function the script declares keeps its arguments, with a named
+ * argument's label following the parameter's new spelling where it was renamed.
+ * A call to a built-in is translated from its row in the table, one argument to
+ * one argument where they line up, and by a translator of its own where they do
+ * not: the highest and lowest of a window that default their source, a
+ * deviation whose `biased` flag is the negation of OpenScript's `sample`, a
+ * true range whose absent first bar is a flag, and the handful of conversions
+ * that are an expression rather than a call in OpenScript.
+ *
+ * A call that draws or trades is a statement, not a value, and its translator
+ * lives with the other statements; used as a value it is refused.
+ */
+import { diagnosticFor } from '../diagnostics/index.js';
+import { canonicalNumber } from '../emit/index.js';
+import type { Context } from './context.js';
+import type { Binding } from './names.js';
+import { levelCall, plotCall, translateInput } from './outputs.js';
+import { neverAbsent } from './presence.js';
+import { pathOf } from './syntax.js';
+import type { Arg, CallExpr, Place } from './syntax.js';
+import { CALLS } from './table.js';
+import type { Mapping } from './table.js';
+import { NOTHING, PREC, atom, translate, wrap } from './values.js';
+import type { Out } from './values.js';
+
+/** A call's arguments against a parameter list: by name, and what fitted none. */
+export interface Bound {
+  readonly byName: ReadonlyMap<string, Arg>;
+  /** Arguments past the positional list, named by their position. */
+  readonly stray: readonly { readonly arg: Arg; readonly name: string }[];
+}
+
+export function bind(call: CallExpr, positional: readonly string[]): Bound {
+  const byName = new Map<string, Arg>();
+  const stray: { arg: Arg; name: string }[] = [];
+  let position = 0;
+  for (const arg of call.args) {
+    if (arg.label !== undefined) {
+      byName.set(arg.label, arg);
+      continue;
+    }
+    const name = positional[position];
+    if (name === undefined) stray.push({ arg, name: `argument ${canonicalNumber(position + 1)}` });
+    else byName.set(name, arg);
+    position += 1;
+  }
+  return { byName, stray };
+}
+
+/**
+ * Refuses the first argument that is not one of `known`, with OS9006. Returns
+ * whether the call may go on.
+ */
+export function onlyKnown(ctx: Context, path: string, bound: Bound, known: readonly string[]): boolean {
+  const first = bound.stray[0];
+  if (first !== undefined) {
+    ctx.refuse(diagnosticFor('OS9006', ctx.span(first.arg.at), { argument: first.name, call: path }));
+    return false;
+  }
+  for (const [name, arg] of bound.byName) {
+    if (known.includes(name)) continue;
+    ctx.refuse(diagnosticFor('OS9006', ctx.span(arg.at), { argument: name, call: path }));
+    return false;
+  }
+  return true;
+}
+
+/** OS9007, once per built-in: its first bars follow OpenScript's own rules. */
+export function warmupNote(ctx: Context, at: Place, call: string, target: string): void {
+  ctx.note(diagnosticFor('OS9007', ctx.span(at), { call, target }), `OS9007 ${call}`);
+}
+
+/** The translated text of one argument, or undefined where the call left it out. */
+export function argText(ctx: Context, bound: Bound, name: string): string | undefined {
+  const arg = bound.byName.get(name);
+  return arg === undefined ? undefined : translate(ctx, arg.value).text;
+}
+
+/** Arguments by position up to the first one left out, and by name after it. */
+function written(texts: readonly (string | undefined)[], labels: readonly string[]): string[] | undefined {
+  const parts: string[] = [];
+  let gap = false;
+  for (let i = 0; i < texts.length; i += 1) {
+    const text = texts[i];
+    if (text === undefined) {
+      gap = true;
+      continue;
+    }
+    if (!gap) parts.push(text);
+    else {
+      const label = labels[i];
+      if (label === undefined) return undefined;
+      parts.push(`${label} = ${text}`);
+    }
+  }
+  return parts;
+}
+
+/** A row whose arguments line up one to one, which is most of the table. */
+export function generic(ctx: Context, call: CallExpr, row: Mapping, path: string): Out {
+  const bound = bind(call, row.params);
+  if (!onlyKnown(ctx, path, bound, row.params)) return NOTHING;
+  const parts = written(row.params.map((name) => argText(ctx, bound, name)), row.targets);
+  if (parts === undefined) {
+    ctx.refuse(diagnosticFor('OS9006', ctx.span(call.at), { argument: 'an argument left out before another', call: path }));
+    return NOTHING;
+  }
+  if (row.difference === 'warmup') warmupNote(ctx, call.callee.at, path, row.target);
+  return atom(`${row.target}(${parts.join(', ')})`);
+}
+
+function userCall(ctx: Context, call: CallExpr, binding: Binding): Out {
+  const parts = call.args.map((arg) => {
+    const text = translate(ctx, arg.value).text;
+    if (arg.label === undefined) return text;
+    return `${binding.labels?.get(arg.label) ?? arg.label} = ${text}`;
+  });
+  return atom(`${binding.output}(${parts.join(', ')})`);
+}
+
+/** `ta.tr` read as a value, which is the call with `handle_na` false. */
+export function trueRangeValue(): Out {
+  return { text: 'isNone(close[1]) ? none : trueRange()', prec: PREC.ternary };
+}
+
+function trueRangeCall(ctx: Context, call: CallExpr, path: string): Out {
+  const bound = bind(call, ['handle_na']);
+  if (!onlyKnown(ctx, path, bound, ['handle_na'])) return NOTHING;
+  const flag = bound.byName.get('handle_na')?.value;
+  if (flag === undefined || (flag.kind === 'bool' && !flag.value)) return trueRangeValue();
+  if (flag.kind === 'bool') return atom('trueRange()');
+  const handled = translate(ctx, flag);
+  return { text: `${wrap(handled, PREC.or)} or not isNone(close[1]) ? trueRange() : none`, prec: PREC.ternary };
+}
+
+function extreme(ctx: Context, call: CallExpr, row: Mapping, path: string): Out {
+  const one = call.args.length === 1 && call.args[0]?.label === undefined;
+  const bound = bind(call, one ? ['length'] : ['source', 'length']);
+  if (!onlyKnown(ctx, path, bound, ['source', 'length'])) return NOTHING;
+  const source = argText(ctx, bound, 'source') ?? (row.target === 'highest' ? 'high' : 'low');
+  const length = argText(ctx, bound, 'length');
+  if (length === undefined) {
+    ctx.refuse(diagnosticFor('OS9006', ctx.span(call.at), { argument: 'length', call: path }));
+    return NOTHING;
+  }
+  warmupNote(ctx, call.callee.at, path, row.target);
+  return atom(`${row.target}(${source}, ${length})`);
+}
+
+function deviation(ctx: Context, call: CallExpr, row: Mapping, path: string): Out {
+  const bound = bind(call, row.params);
+  if (!onlyKnown(ctx, path, bound, row.params)) return NOTHING;
+  const source = argText(ctx, bound, 'source');
+  const length = argText(ctx, bound, 'length');
+  if (source === undefined || length === undefined) {
+    ctx.refuse(diagnosticFor('OS9006', ctx.span(call.at), { argument: source === undefined ? 'source' : 'length', call: path }));
+    return NOTHING;
+  }
+  const biased = bound.byName.get('biased')?.value;
+  let sample = '';
+  if (biased !== undefined && !(biased.kind === 'bool' && biased.value)) {
+    sample = biased.kind === 'bool' ? ', sample = true' : `, sample = not ${wrap(translate(ctx, biased), PREC.unary)}`;
+  }
+  warmupNote(ctx, call.callee.at, path, row.target);
+  return atom(`${row.target}(${source}, ${length}${sample})`);
+}
+
+/** A condition handed to a counting built-in, which the source dialect never sees absent. */
+function condition(ctx: Context, call: CallExpr, row: Mapping, path: string): Out {
+  const bound = bind(call, row.params);
+  if (!onlyKnown(ctx, path, bound, row.params)) return NOTHING;
+  const texts = row.params.map((name) => {
+    const arg = bound.byName.get(name);
+    if (arg === undefined) return undefined;
+    const text = translate(ctx, arg.value).text;
+    return name === 'condition' && !neverAbsent(ctx, arg.value) ? `orElse(${text}, false)` : text;
+  });
+  const parts = written(texts, row.targets);
+  if (parts === undefined || texts[0] === undefined) {
+    ctx.refuse(diagnosticFor('OS9006', ctx.span(call.at), { argument: 'condition', call: path }));
+    return NOTHING;
+  }
+  warmupNote(ctx, call.callee.at, path, row.target);
+  return atom(`${row.target}(${parts.join(', ')})`);
+}
+
+/** `math.max` and `math.min` take any number of arguments; OpenScript's take two. */
+function extremes(ctx: Context, call: CallExpr, row: Mapping, path: string): Out {
+  const labelled = call.args.find((arg) => arg.label !== undefined);
+  if (labelled !== undefined || call.args.length < 2) {
+    const at = labelled?.at ?? call.at;
+    ctx.refuse(diagnosticFor('OS9006', ctx.span(at), { argument: labelled?.label ?? 'a single argument', call: path }));
+    return NOTHING;
+  }
+  const texts = call.args.map((arg) => translate(ctx, arg.value).text);
+  let text = texts[0] ?? '';
+  for (const next of texts.slice(1)) text = `${row.target}(${text}, ${next})`;
+  return atom(text);
+}
+
+function fallback(ctx: Context, call: CallExpr, row: Mapping, path: string): Out {
+  const bound = bind(call, row.params);
+  if (!onlyKnown(ctx, path, bound, row.params)) return NOTHING;
+  const source = argText(ctx, bound, 'source');
+  if (source === undefined) {
+    ctx.refuse(diagnosticFor('OS9006', ctx.span(call.at), { argument: 'source', call: path }));
+    return NOTHING;
+  }
+  return atom(`orElse(${source}, ${argText(ctx, bound, 'replacement') ?? '0'})`);
+}
+
+function rgb(ctx: Context, call: CallExpr, row: Mapping, path: string): Out {
+  const bound = bind(call, row.params);
+  if (!onlyKnown(ctx, path, bound, row.params)) return NOTHING;
+  const channels = ['red', 'green', 'blue'].map((name) => argText(ctx, bound, name));
+  if (channels.some((one) => one === undefined)) {
+    ctx.refuse(diagnosticFor('OS9006', ctx.span(call.at), { argument: 'a colour channel', call: path }));
+    return NOTHING;
+  }
+  const colour = `rgb(${channels.join(', ')})`;
+  const transp = argText(ctx, bound, 'transp');
+  return atom(transp === undefined ? colour : `fade(${colour}, ${transp})`);
+}
+
+export function translateCall(ctx: Context, call: CallExpr): Out {
+  const path = pathOf(call.callee);
+  const root = path?.split('.')[0];
+  const binding = root === undefined ? undefined : ctx.lookup(root, call.callee.at);
+  if (path === undefined || (binding !== undefined && (path !== root || binding.kind !== 'function'))) {
+    ctx.refuse(diagnosticFor('OS9002', ctx.span(call.callee.at), { construct: 'a call on a value' }));
+    return NOTHING;
+  }
+  if (binding !== undefined) return userCall(ctx, call, binding);
+  const row = CALLS.get(path);
+  if (row === undefined) {
+    ctx.refuse(diagnosticFor('OS9003', ctx.span(call.callee.at), { name: path }));
+    return NOTHING;
+  }
+  switch (row.special) {
+    case undefined:
+      return generic(ctx, call, row, path);
+    case 'trueRange':
+      return trueRangeCall(ctx, call, path);
+    case 'extreme':
+      return extreme(ctx, call, row, path);
+    case 'deviation':
+      return deviation(ctx, call, row, path);
+    case 'condition':
+      return condition(ctx, call, row, path);
+    case 'extremes':
+      return extremes(ctx, call, row, path);
+    case 'fallback':
+      return fallback(ctx, call, row, path);
+    case 'rgb':
+      return rgb(ctx, call, row, path);
+    case 'float': {
+      const bound = bind(call, row.params);
+      if (!onlyKnown(ctx, path, bound, row.params)) return NOTHING;
+      const arg = bound.byName.get('x');
+      return arg === undefined ? atom('none') : atom(`(${translate(ctx, arg.value).text})`);
+    }
+    case 'input':
+      return translateInput(ctx, call, path, false);
+    case 'plot':
+      return plotCall(ctx, call, path);
+    case 'hline':
+      return levelCall(ctx, call, path);
+  }
+  ctx.refuse(diagnosticFor('OS9002', ctx.span(call.callee.at), { construct: `${path} used as a value` }));
+  return NOTHING;
+}

package/src/core/importer/context.ts

@@ -0,0 +1,197 @@
+/**
+ * What the translators share while they work through one script.
+ *
+ * A translation is kept or refused per top level statement, never per line
+ * inside one: a block with one line missing is a block that means something
+ * the original did not, so the unit that is kept as a comment is the whole
+ * statement at the top level. `Node` is that unit, and everything a refusal or
+ * a warning needs to point at is recorded against it rather than decided on the
+ * spot, because a statement translated now can still be refused later: by the
+ * compiler, or because an earlier statement it reads was refused.
+ */
+import type { Diagnostic } from '../diagnostics/index.js';
+import { canonicalNumber } from '../emit/index.js';
+import type { SourceFile } from '../source/index.js';
+import type { Span } from '../span/index.js';
+import { Namer, Scope } from './names.js';
+import type { Binding } from './names.js';
+import type { Expr, Lines, Named, Place, Stmt } from './syntax.js';
+
+export interface OutLine {
+  readonly depth: number;
+  readonly text: string;
+}
+
+/** A finding on a statement that is kept, and the key that makes it once per script where it is once per built-in. */
+export interface Note {
+  readonly diagnostic: Diagnostic;
+  readonly once: string | undefined;
+}
+
+export interface Node {
+  readonly stmt: Stmt;
+  readonly lines: Lines;
+  /** Top level names the statement declares, so what reads them can follow it. */
+  readonly declares: readonly Named[];
+  /** Top level names it reads, in source order, with where. */
+  readonly reads: Named[];
+  output: OutLine[];
+  /** Why its translation was refused, if it was. */
+  refusal: Diagnostic | undefined;
+  /** Why the compiler refused the translation, if it did. */
+  failed: Diagnostic | undefined;
+  /** Why it reads a name a refused statement declared, recomputed on every pass. */
+  lost: Diagnostic | undefined;
+  readonly notes: Note[];
+  /** The declaration, which is placed first and is never kept as a comment. */
+  readonly declaration: boolean;
+}
+
+export function isKept(node: Node): boolean {
+  return node.refusal === undefined && node.failed === undefined && node.lost === undefined;
+}
+
+/** The first reason a node is not kept, in the order the reasons are found. */
+export function reasonOf(node: Node): Diagnostic | undefined {
+  return node.refusal ?? node.failed ?? node.lost;
+}
+
+export type Version = 5 | 6;
+
+export interface Reassignment {
+  readonly op: string;
+  readonly value: Expr;
+}
+
+/** Everything about the script the translators need before they start. */
+export interface Facts {
+  readonly file: SourceFile;
+  readonly version: Version;
+  /** Every identifier the source writes. */
+  readonly used: ReadonlySet<string>;
+  /**
+   * Every reassignment the source makes, by name, anywhere in the file. A name
+   * with any is never a constant, and is present only if every value it is
+   * given is.
+   */
+  readonly reassigned: ReadonlyMap<string, readonly Reassignment[]>;
+  /**
+   * Every name the file declares at the top level, wherever. OpenScript lets a
+   * block or a function see one declared below it, so an inner declaration of
+   * the same name is renamed, which the source dialect's meaning allows.
+   */
+  readonly globals: ReadonlySet<string>;
+  /** The side each literal entry id opens, from the script's entry calls. */
+  readonly entries: ReadonlyMap<string, 'long' | 'short'>;
+}
+
+export class Context {
+  readonly namer: Namer;
+  readonly fileScope = new Scope(undefined);
+  scope: Scope = this.fileScope;
+  /** The statement being translated. */
+  node: Node | undefined;
+  /** Lines a statement needs evaluated before it, and whether it may have them. */
+  hoisted: OutLine[] = [];
+  mayHoist = false;
+  /** Inside a ternary arm, where the source dialect evaluates lazily as OpenScript does. */
+  lazy = 0;
+  depth = 0;
+  /** The declaration's pyramiding, read as the source dialect reads it: 0 is 1. */
+  pyramiding = 1;
+  /**
+   * Whether the declaration sizes orders in units. The source dialect counts a
+   * quantity written on an entry in contracts whatever the declaration says,
+   * and OpenScript counts it in the declaration's own unit.
+   */
+  qtyInUnits = true;
+  readonly titles = new Map<string, Set<string>>();
+  readonly facts: Facts;
+
+  constructor(facts: Facts) {
+    this.facts = facts;
+    this.namer = new Namer(facts.used);
+  }
+
+  span(at: Place): Span {
+    return this.facts.file.spanAt(at.offset, at.length);
+  }
+
+  /** Records the first reason the current statement cannot be translated. */
+  refuse(diagnostic: Diagnostic): void {
+    if (this.node !== undefined && this.node.refusal === undefined) this.node.refusal = diagnostic;
+  }
+
+  get refused(): boolean {
+    return this.node?.refusal !== undefined;
+  }
+
+  note(diagnostic: Diagnostic, once?: string): void {
+    this.node?.notes.push({ diagnostic, once });
+  }
+
+  /** Whether declaring `name` in the current scope needs a new spelling to keep it apart. */
+  hides(name: string): boolean {
+    return this.scope.find(name) !== undefined || (!this.scope.isGlobal && this.facts.globals.has(name));
+  }
+
+  /** The binding a source name has here, recording a read of a top level one. */
+  lookup(name: string, at: Place): Binding | undefined {
+    const found = this.scope.find(name);
+    if (found !== undefined && found.topLevel) this.node?.reads.push({ name, at });
+    return found;
+  }
+
+  /** Enters a block scope for the length of `work`. */
+  within<T>(work: () => T): T {
+    const outer = this.scope;
+    this.scope = new Scope(outer);
+    try {
+      return work();
+    } finally {
+      this.scope = outer;
+    }
+  }
+
+  /**
+   * Moves an expression to its own line before the current statement, and
+   * returns the name it is read under, or undefined where it cannot be moved.
+   */
+  hoist(text: string): string | undefined {
+    if (!this.mayHoist || this.lazy > 0) return undefined;
+    const name = this.namer.fresh('everyBar');
+    this.hoisted.push({ depth: this.depth, text: `${name} = ${text}` });
+    return name;
+  }
+
+  /** A title for a declared output that no other output of its kind has. */
+  title(kind: string, wanted: string): string {
+    let seen = this.titles.get(kind);
+    if (seen === undefined) {
+      seen = new Set();
+      this.titles.set(kind, seen);
+    }
+    let title = wanted;
+    for (let n = 2; seen.has(title); n += 1) title = `${wanted} ${canonicalNumber(n)}`;
+    seen.add(title);
+    return title;
+  }
+}
+
+const HEX = '0123456789abcdef';
+
+/** A string literal in OpenScript's spelling of it (`language.md` 3.6). */
+export function quoted(value: string): string {
+  let out = '"';
+  for (const c of value) {
+    const code = c.codePointAt(0) ?? 0;
+    if (c === '"') out += '\\"';
+    else if (c === '\\') out += '\\\\';
+    else if (c === '\n') out += '\\n';
+    else if (c === '\t') out += '\\t';
+    else if (c === '\r') out += '\\r';
+    else if (code < 0x20) out += `\\u00${HEX[code >> 4] ?? '0'}${HEX[code & 15] ?? '0'}`;
+    else out += c;
+  }
+  return `${out}"`;
+}