openalgo-script 0.1.0-alpha.1 → 0.4.0

package/src/core/stdlib/volume/flow.ts

@@ -0,0 +1,173 @@
+/**
+ * The lookback volume readings: `cmf`, `mfi`, `eom`, `forceIndex` and
+ * `relativeVolume`.
+ *
+ * Each is written once, as a step over a state region, and its tail is that
+ * step over a region of its own.
+ */
+import type { Bar, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, fold, held, hl2, hlc3, isPresent, result, tailOf } from '../values/index.js';
+import { emaStep, smaStep } from '../averages/index.js';
+import { changeStep, sumStep } from '../series/index.js';
+
+import { moneyFlow } from './accumulation.js';
+
+/** `cmf(len)`: accumulation over the lookback as a fraction of its volume, from bar `len - 1`. */
+export function cmfStep(
+  state: StateRecord,
+  key: string,
+  bar: Bar,
+  len: number | null,
+): Value {
+  const flow = sumStep(state, `${key}f`, moneyFlow(bar), len);
+  const traded = sumStep(state, `${key}v`, bar.volume, len);
+  if (!isPresent(flow) || !isPresent(traded) || !(traded > 0)) return NONE;
+  return result(flow / traded);
+}
+
+/** `cmf(len)` as a tail. */
+export function cmfTail(len = 20): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => cmfStep(state, '', bar, len));
+}
+
+/** `cmf(len)` over a run of bars. */
+export function cmf(bars: readonly Bar[], len = 20): Value[] {
+  return fold(cmfTail(len), bars);
+}
+
+/**
+ * `mfi(len)`: the strength reading computed on money flow rather than price,
+ * from bar `len`.
+ *
+ * A bar's whole flow counts on one side or the other, by whether the typical
+ * price rose or fell, so the first lookback is bars 1 to `len` and the extra bar
+ * is in the declared warmup.
+ */
+export function mfiStep(
+  state: StateRecord,
+  key: string,
+  bar: Bar,
+  len: number | null,
+): Value {
+  const typicalKey = `${key}p`;
+  const seenKey = `${key}k`;
+  const typical = hlc3(bar);
+  const before = held(state, typicalKey);
+  const started = state[seenKey] === true;
+  state[seenKey] = true;
+  state[typicalKey] = typical;
+
+  let up: Value = NONE;
+  let down: Value = NONE;
+  if (started && isPresent(typical) && isPresent(before) && isPresent(bar.volume)) {
+    const flow = result(typical * bar.volume);
+    up = typical > before ? flow : 0;
+    down = typical < before ? flow : 0;
+  }
+
+  const rise = sumStep(state, `${key}u`, up, len);
+  const fall = sumStep(state, `${key}d`, down, len);
+  if (!isPresent(rise) || !isPresent(fall)) return NONE;
+  // No down bar in the lookback is the top of the scale, as in `rsi`.
+  if (fall === 0) return 100;
+  return result(100 - 100 / (1 + rise / fall));
+}
+
+/** `mfi(len)` as a tail. */
+export function mfiTail(len = 14): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => mfiStep(state, '', bar, len));
+}
+
+/** `mfi(len)` over a run of bars. */
+export function mfi(bars: readonly Bar[], len = 14): Value[] {
+  return fold(mfiTail(len), bars);
+}
+
+/**
+ * `eom(len)`: how far price moved per unit of volume, from bar `len`.
+ *
+ * The midpoint's move, times the bar's range, over the volume traded, then
+ * averaged over the lookback. The midpoint move needs the previous bar, so the
+ * average's lookback starts at bar 1 and the first reading is at bar `len`.
+ *
+ * **No scaling constant.** Implementations of this reading usually multiply by
+ * a large divisor whose only job is to bring the number into a readable range,
+ * and they do not agree on it. `stdlib.md` section 7 declares `eom(len = 14)`
+ * with no such argument, so there is none here and the reading is the quantity
+ * itself. That leaves it very small on a liquid instrument, which is recorded
+ * as a gap in the specification rather than papered over with a constant this
+ * library invented.
+ */
+export function eomStep(
+  state: StateRecord,
+  key: string,
+  bar: Bar,
+  len: number | null,
+): Value {
+  const travelled = changeStep(state, `${key}c`, hl2(bar), 1);
+  let term: Value = NONE;
+  if (
+    isPresent(travelled) &&
+    isPresent(bar.high) &&
+    isPresent(bar.low) &&
+    isPresent(bar.volume) &&
+    bar.volume !== 0
+  ) {
+    term = result((travelled * (bar.high - bar.low)) / bar.volume);
+  }
+  return smaStep(state, `${key}q`, term, len);
+}
+
+/** `eom(len)` as a tail. */
+export function eomTail(len = 14): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => eomStep(state, '', bar, len));
+}
+
+/** `eom(len)` over a run of bars. */
+export function eom(bars: readonly Bar[], len = 14): Value[] {
+  return fold(eomTail(len), bars);
+}
+
+/** `forceIndex(len)`: change times volume, smoothed, from bar `len`. */
+export function forceIndexStep(
+  state: StateRecord,
+  key: string,
+  bar: Bar,
+  len: number | null,
+): Value {
+  const moved = changeStep(state, `${key}c`, bar.close, 1);
+  const force = isPresent(moved) && isPresent(bar.volume) ? result(moved * bar.volume) : NONE;
+  return emaStep(state, `${key}e`, force, len);
+}
+
+/** `forceIndex(len)` as a tail. */
+export function forceIndexTail(len = 13): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => forceIndexStep(state, '', bar, len));
+}
+
+/** `forceIndex(len)` over a run of bars. */
+export function forceIndex(bars: readonly Bar[], len = 13): Value[] {
+  return fold(forceIndexTail(len), bars);
+}
+
+/** `relativeVolume(len)`: this bar's volume over its own recent average, from bar `len - 1`. */
+export function relativeVolumeStep(
+  state: StateRecord,
+  key: string,
+  volume: Value,
+  len: number | null,
+): Value {
+  const mean = smaStep(state, `${key}q`, volume, len);
+  if (!isPresent(mean) || !isPresent(volume) || mean === 0) return NONE;
+  return result(volume / mean);
+}
+
+/** `relativeVolume(len)` as a tail. */
+export function relativeVolumeTail(len = 20): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => relativeVolumeStep(state, '', bar.volume, len));
+}
+
+/** `relativeVolume(len)` over a run of bars. */
+export function relativeVolume(bars: readonly Bar[], len = 20): Value[] {
+  return fold(relativeVolumeTail(len), bars);
+}

package/src/core/stdlib/volume/index.ts

@@ -0,0 +1,43 @@
+export {
+  ad,
+  adOsc,
+  adOscStep,
+  adOscTail,
+  adStep,
+  adTail,
+  moneyFlow,
+  obv,
+  obvStep,
+  obvTail,
+  pvt,
+  pvtStep,
+  pvtTail,
+} from './accumulation.js';
+
+export {
+  cmf,
+  cmfStep,
+  cmfTail,
+  eom,
+  eomStep,
+  eomTail,
+  forceIndex,
+  forceIndexStep,
+  forceIndexTail,
+  mfi,
+  mfiStep,
+  mfiTail,
+  relativeVolume,
+  relativeVolumeStep,
+  relativeVolumeTail,
+} from './flow.js';
+
+export type { Anchored } from './weighted.js';
+export {
+  vwap,
+  vwapAnchor,
+  vwapAnchorStep,
+  vwapAnchorTail,
+  vwapStep,
+  vwapTail,
+} from './weighted.js';

package/src/core/stdlib/volume/weighted.ts

@@ -0,0 +1,101 @@
+/**
+ * `vwap` and `vwapAnchor`: the volume weighted average price since an anchor.
+ *
+ * `stdlib.md` section 7 writes `vwap(src)` and says it resets at the start of
+ * each trading session **as the instrument defines it**, not at midnight,
+ * because the session is what the number means. Where a session starts follows
+ * from the instrument's own trading hours and not from any arithmetic here, so
+ * this library takes the anchor as a flag per bar and an engine derives it.
+ * `vwapAnchor` is therefore the whole of the calculation and `vwap` is that
+ * calculation with the session's first bars passed in.
+ *
+ * The running totals are carried rather than rebuilt, because that is the
+ * definition: a volume weighted average since an anchor is a pair of running
+ * totals, and a lookback over the bars since the anchor would be a different
+ * quantity with a different value.
+ */
+import type { Series, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, flag, fold, isPresent, result, slot, tailOf } from '../values/index.js';
+
+/** A bar's source price, its volume, and whether the average restarts here. */
+export interface Anchored {
+  readonly src: Value;
+  readonly volume: Value;
+  readonly reset: boolean;
+}
+
+/**
+ * `vwapAnchor(src, resetWhen)`: from the first bar `resetWhen` is true.
+ *
+ * The bar the condition holds on is the first bar of the new average, not the
+ * last bar of the old one. Absent before the condition has ever been true,
+ * because there is no anchor to measure from and zero would read as a price.
+ */
+export function vwapAnchorStep(state: StateRecord, key: string, input: Anchored): Value {
+  const flowKey = `${key}f`;
+  const tradedKey = `${key}v`;
+  const anchoredKey = `${key}a`;
+  if (input.reset) {
+    state[flowKey] = 0;
+    state[tradedKey] = 0;
+    state[anchoredKey] = true;
+  }
+  if (!flag(state, anchoredKey)) return NONE;
+  if (!isPresent(input.src) || !isPresent(input.volume)) return NONE;
+  const flow = slot(state, flowKey, 0) + input.src * input.volume;
+  const traded = slot(state, tradedKey, 0) + input.volume;
+  state[flowKey] = flow;
+  state[tradedKey] = traded;
+  if (traded === 0) return NONE;
+  return result(flow / traded);
+}
+
+/** `vwapAnchor(src, resetWhen)` as a tail. */
+export function vwapAnchorTail(): Tail<Anchored, Value> {
+  return tailOf((state, input: Anchored) => vwapAnchorStep(state, '', input));
+}
+
+/** `vwapAnchor(src, resetWhen)` over whole series. */
+export function vwapAnchor(
+  src: Series,
+  volume: Series,
+  resetWhen: readonly boolean[],
+): Value[] {
+  return fold(
+    vwapAnchorTail(),
+    src.map((value, index) => ({
+      src: value,
+      volume: volume[index] ?? NONE,
+      reset: resetWhen[index] === true,
+    })),
+  );
+}
+
+/**
+ * `vwap(src)`: the same average anchored to the session, from the session's
+ * first bar.
+ *
+ * `sessionStart` is the engine's answer to "does a new trading session begin on
+ * this bar", read off the instrument's stated trading hours, which is why it
+ * is an argument rather than something derived from the timestamps here. On a daily or longer interval every bar is its own
+ * session, so every bar is an anchor and the result equals `src`; the compiler
+ * emits warning OS8006 saying so, which is a compile-time matter and not this
+ * library's.
+ */
+export function vwapTail(): Tail<Anchored, Value> {
+  return vwapAnchorTail();
+}
+
+/** `vwap(src)` as a step, which is `vwapAnchor` anchored to the session. */
+export function vwapStep(state: StateRecord, key: string, input: Anchored): Value {
+  return vwapAnchorStep(state, key, input);
+}
+
+/** `vwap(src)` over whole series. */
+export function vwap(
+  src: Series,
+  volume: Series,
+  sessionStart: readonly boolean[],
+): Value[] {
+  return vwapAnchor(src, volume, sessionStart);
+}

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.1.0-alpha.1";
+export const VERSION = "0.4.0";
 
 /**
  * The compiled program format this compiler emits.
@@ -12,4 +12,4 @@ export const VERSION = "0.1.0-alpha.1";
  * Deliberately not the package version. An engine written by somebody else
  * targets this number, and it moves only when the format does.
  */
-export const COMPILED_FORMAT_VERSION = "1.0";
+export const COMPILED_FORMAT_VERSION = "1.1";

package/src/editor/complete.ts

@@ -0,0 +1,266 @@
+/**
+ * `complete`: what may be written at a position.
+ *
+ * Four kinds of answer, and every one of them is read out of something the
+ * compiler already holds:
+ *
+ *     the members of a namespace   `membersOf`, after `draw.`
+ *     the named arguments of the   the manifest's parameters for the call the
+ *     call being written           brackets say the cursor is inside
+ *     the file's own names         the checker's bindings, filtered by the two
+ *                                  scope rules of `scope.ts`
+ *     the library's names          `libraryNames`, the same index the checker
+ *                                  resolves against and the example check reads
+ *                                  its globals from
+ *
+ * **A hand written list of function names is the exact failure this project
+ * keeps removing.** It would be right on the day it was written and wrong at the
+ * next release, and nobody would report it, because a missing completion is
+ * indistinguishable from a completion that has not loaded yet. Nothing below
+ * names a single function of the language.
+ *
+ * ## A planned call is offered, and is marked as one
+ *
+ * `stdlib.md` lists calls that are named and not implemented, so that the gap in
+ * the surface is visible rather than looking like an oversight. Writing one is
+ * OS2020.
+ *
+ * Three answers were possible: leave them out, offer them as though they worked,
+ * or offer them marked. Leaving them out is the worst of the three, because the
+ * writer then types the name from the documentation, gets no completion, and
+ * learns nothing about why; offering them unmarked walks somebody into OS2020
+ * with a plot that will not compile.
+ *
+ * So they are offered, they sort after everything a script may write today, and
+ * each one carries `refusal`, which is **the catalogue's own OS2020 message
+ * filled with that name**. A host greys the row, shows the sentence, or drops
+ * the row with one field, and the sentence it shows is the same sentence the
+ * compiler would produce, because it came from the same catalogue.
+ */
+import {
+  NAMESPACES,
+  entryFor,
+  fillTemplate,
+  isNamespace,
+  libraryEntries,
+  libraryNames,
+  membersOf,
+  proseFor,
+  typeText,
+} from '../core/index.js';
+import type { Binding, LibraryEntry, Span } from '../core/index.js';
+import { entryAt, parametersOf, signatureTextOf } from './manifest.js';
+import { readChecked } from './reading.js';
+import { inScopeAt } from './scope.js';
+import { siteAt } from './site.js';
+
+/**
+ * What a completion is, which decides the icon a host puts beside it.
+ *
+ * `value` is a library name read without brackets, `close` and `aqua` among
+ * them; `function` is one that is called. The two are the manifest's own
+ * `callable`, not a guess from the spelling.
+ */
+export type CompletionKind =
+  | 'function'
+  | 'value'
+  | 'namespace'
+  | 'member'
+  | 'variable'
+  | 'argument';
+
+export interface Completion {
+  /** What the row reads as: the name, or the parameter for a named argument. */
+  readonly label: string;
+  /**
+   * What a host puts into the text, which is not always the label.
+   *
+   * A named argument is written `len = `, so accepting the row leaves the caret
+   * where the value goes rather than beside a label with no equals sign.
+   */
+  readonly insert: string;
+  readonly kind: CompletionKind;
+  /** The signature or the type, spelled by the manifest and the checker. */
+  readonly detail: string;
+  /** The line the specification gives it, where it gives one. */
+  readonly summary: string | undefined;
+  /** Named in the library and not implemented in this version: OS2020. */
+  readonly planned: boolean;
+  /** The catalogue's OS2020 message for this name, on a planned row and no other. */
+  readonly refusal: string | undefined;
+  /** The text the row replaces, which is the word being typed or nothing. */
+  readonly replace: Span;
+}
+
+/** The order a host shows them in, decided here so two hosts agree. */
+const ORDER: Readonly<Record<CompletionKind, number>> = {
+  argument: 0,
+  variable: 1,
+  function: 2,
+  member: 2,
+  value: 3,
+  namespace: 4,
+};
+
+/**
+ * The order, and the two things that decide it.
+ *
+ * Named arguments keep the order the signature states them in, because that is
+ * the order they are written in and an alphabetical list of them would put
+ * `len` before `src` in a call whose first argument is the source. Everything
+ * else is sorted: a planned call after every call a script may write today,
+ * then the kinds above, then the name.
+ *
+ * The name comparison has no locale in it. `compiled-program.md` 8.4 forbids
+ * one, and it is the same rule here for the same reason: two machines set
+ * differently would order a list differently, and the machine set differently is
+ * the one nobody is looking at.
+ */
+function ordered(completions: readonly Completion[]): readonly Completion[] {
+  const written = completions.filter((one) => one.kind === 'argument');
+  const rest = completions.filter((one) => one.kind !== 'argument');
+  rest.sort((a, b) => {
+    if (a.planned !== b.planned) return a.planned ? 1 : -1;
+    const kind = (ORDER[a.kind] ?? 0) - (ORDER[b.kind] ?? 0);
+    if (kind !== 0) return kind;
+    if (a.label === b.label) return 0;
+    return a.label < b.label ? -1 : 1;
+  });
+  return [...written, ...rest];
+}
+
+/** The OS2020 sentence, filled with the name, for a call that is not here yet. */
+function refusalFor(name: string): string {
+  return fillTemplate(entryFor('OS2020').message, { name });
+}
+
+function fromEntry(
+  entry: LibraryEntry,
+  label: string,
+  kind: CompletionKind,
+  replace: Span,
+): Completion {
+  return {
+    label,
+    insert: label,
+    kind,
+    detail: signatureTextOf(entry),
+    summary: proseFor(entry.name)?.summary,
+    planned: entry.planned,
+    refusal: entry.planned ? refusalFor(entry.name) : undefined,
+    replace,
+  };
+}
+
+/**
+ * One row per library name, taking the first signature for the detail.
+ *
+ * A name with several signatures is one row and not several: `clear` is one
+ * thing to write and two things to write it about, and a list that showed it
+ * twice would be a list about the manifest rather than about the language.
+ * `signature` is what tells a writer which one they are in once they have
+ * opened the bracket.
+ */
+function libraryRow(name: string, replace: Span): Completion | undefined {
+  const entries = libraryEntries(name);
+  const entry = entries[0];
+  if (entry === undefined) return undefined;
+  return fromEntry(entry, name, entry.callable ? 'function' : 'value', replace);
+}
+
+/** A name the file declared, with the type and the storage the checker gave it. */
+function declaredRow(binding: Binding, replace: Span): Completion {
+  const kind: CompletionKind = binding.kind === 'function' ? 'function' : 'variable';
+  const persistence = binding.persistence === 'none' ? '' : `${binding.persistence} `;
+  return {
+    label: binding.name,
+    insert: binding.name,
+    kind,
+    detail: `${persistence}${binding.name}: ${typeText(binding.type)}`,
+    summary: undefined,
+    planned: false,
+    refusal: undefined,
+    replace,
+  };
+}
+
+/**
+ * Everything that may be written at an offset, most useful first.
+ *
+ * Rows are filtered by the word already typed, which is compared exactly:
+ * `language.md` makes names case sensitive, so `EM` is not a start of `ema` and
+ * offering it would be offering a name that does not compile.
+ */
+export function complete(source: string, offset: number): readonly Completion[] {
+  const { file, tokens, checked } = readChecked(source);
+  const site = siteAt(file, tokens, offset);
+  const at = site.replace.offset;
+
+  const rows: Completion[] = [];
+
+  // After a dot, the only thing that may be written is a member of the
+  // namespace, and only where the name before the dot is one. A dotted read of
+  // anything else is not a member read at all in version 1 (`language.md` 15.2),
+  // so there is nothing to offer rather than the whole library offered wrongly.
+  if (site.afterDot) {
+    const namespace = site.namespace;
+    if (namespace !== undefined && isNamespace(namespace)) {
+      for (const member of membersOf(namespace)) {
+        const entry = libraryEntries(`${namespace}.${member}`)[0];
+        if (entry !== undefined) rows.push(fromEntry(entry, member, 'member', site.replace));
+      }
+    }
+    return ordered(rows.filter((row) => row.label.startsWith(site.word)));
+  }
+
+  // The named arguments of the call being written, where one is being written
+  // and the label of this argument has not been decided yet.
+  const call = site.call;
+  if (call !== undefined && call.label === undefined) {
+    const entry = entryAt(call.name, call.argument + 1);
+    if (entry !== undefined) {
+      for (const parameter of parametersOf(entry)) {
+        if (call.labels.includes(parameter.name)) continue;
+        rows.push({
+          label: parameter.name,
+          insert: `${parameter.name} = `,
+          kind: 'argument',
+          detail:
+            `${parameter.name}: ${parameter.type}` +
+            (parameter.defaultText === undefined ? '' : ` = ${parameter.defaultText}`),
+          summary: undefined,
+          planned: entry.planned,
+          refusal: entry.planned ? refusalFor(entry.name) : undefined,
+          replace: site.replace,
+        });
+      }
+    }
+  }
+
+  for (const binding of inScopeAt(checked, at)) {
+    rows.push(declaredRow(binding, site.replace));
+  }
+
+  for (const name of libraryNames()) {
+    // A dotted name is reached through its namespace and not written whole from
+    // nothing, so the namespace is the row and `membersOf` is the rest.
+    if (name.includes('.')) continue;
+    const row = libraryRow(name, site.replace);
+    if (row !== undefined) rows.push(row);
+  }
+
+  for (const namespace of NAMESPACES) {
+    rows.push({
+      label: namespace,
+      insert: `${namespace}.`,
+      kind: 'namespace',
+      detail: `${namespace}.`,
+      summary: undefined,
+      planned: false,
+      refusal: undefined,
+      replace: site.replace,
+    });
+  }
+
+  return ordered(rows.filter((row) => row.label.startsWith(site.word)));
+}

package/src/editor/diagnose.ts

@@ -0,0 +1,71 @@
+/**
+ * `diagnose`: source text in, everything the compiler has to say about it out.
+ *
+ * This is the one a trader sees most. It runs on a debounce while somebody
+ * types, so two things about it are decisions rather than details: what it
+ * costs, and what it does with a file that does not parse.
+ *
+ * ## It is the whole compile, on purpose
+ *
+ * Lexer, parser, checker, emitter. Not a subset, and not a faster partial
+ * compiler written for the editor, because a second implementation of the
+ * language is the thing this project refuses to have: the editor is the compiler
+ * wearing a different hat.
+ *
+ * It matters concretely as well as in principle. There are codes a script can
+ * carry that the emitter raises and nothing before it does, so an editor that
+ * stopped after the checker would show a clean file and then refuse it the
+ * moment somebody pressed apply. What a host sees here is exactly what a compile
+ * produces, so nothing new can appear at apply, and a test holds that by taking
+ * a file whose only fault the emitter is the one to find.
+ *
+ * ## What it costs
+ *
+ * A full compile of a ninety line study is a third of a millisecond, and the
+ * same file with a bracket left open mid way through, which is what a file looks
+ * like the moment somebody types one, is about a millisecond. Both are in the
+ * benchmark suite with a budget, as `diagnose-heavy` and `diagnose-typing`, so a
+ * change that makes the editor cost ten times what it costs today fails the
+ * build rather than being felt by a trader.
+ *
+ * That is why there is no partial compiler here. At this price, one is not worth
+ * the second implementation it would cost; if a script ever arrives that makes
+ * it worth one, the number to beat is in the benchmark table rather than in
+ * somebody's impression.
+ *
+ * ## A file that does not parse
+ *
+ * That is the normal state of a file being typed into, so it is the case this
+ * has to be good at rather than the case it survives. Every stage of this
+ * compiler recovers and reports instead of throwing: a lexical error costs its
+ * own character, a statement that will not parse costs its own line, a name that
+ * does not resolve becomes `unknown` and the lines around it are still checked.
+ * So a half typed file produces the diagnostics its finished lines have earned,
+ * plus the one about the line being typed, and nothing here needs a try block to
+ * make that true. `tests/editor/diagnose.test.ts` puts a corpus of malformed
+ * files through it, including text that is not the language at all.
+ */
+import { check, emit } from '../core/index.js';
+import type { Diagnostic } from '../core/index.js';
+import { readTree } from './reading.js';
+
+/**
+ * Every diagnostic a compile of this source produces, in the order a reader
+ * walks the file.
+ *
+ * Each one carries its code, its span, its message and its fix, because that is
+ * what a `Diagnostic` is: the stage that raised it supplied the code and the
+ * span, and everything a person reads came from the error catalogue. There is no
+ * editor-shaped diagnostic type here for the same reason there is no editor
+ * compiler. A host that renders one in a panel and a terminal that renders the
+ * same one under a caret are looking at the same record.
+ *
+ * The order is the bag's own: by offset, then by the span's length, then by code
+ * point of the code. It depends on nothing outside the file, so two machines
+ * list them identically.
+ */
+export function diagnose(source: string): readonly Diagnostic[] {
+  const { file, bag, script } = readTree(source);
+  emit(file, check(file, script, bag), bag, {});
+  return bag.ordered();
+}