openalgo-script 0.1.0-alpha.1 → 0.4.0

package/src/adapters/charts/tables.ts

@@ -0,0 +1,243 @@
+/**
+ * Declared grids into the chart's summary grid.
+ *
+ * **A table is written, not plotted.** It is the one output that is not a value
+ * per bar: its cells are written by library calls against a handle, into a
+ * buffer the engine empties at the start of every execution of a bar
+ * (`compiled-program.md` 2.8 and 5.1). What survives is what the last executed
+ * bar wrote, which is what a grid pinned to a corner of a pane shows.
+ *
+ * **So it is read once, after the run, and never per bar.** The obvious way to
+ * get this wrong is to collect a grid for every bar of a long history in order
+ * to display the last one, which costs the length of the history and throws all
+ * of it away. The engine holds one buffer per grid rather than one per bar, and
+ * this reads it exactly once per calculation, so a hundred thousand bars cost
+ * the same as ten.
+ *
+ * A script pays the other half of that bill for itself: `cell()` on every bar of
+ * a long history does the work of writing a grid that only the last bar's copy
+ * is kept from, and the documentation says to guard it with `bar.isLast`. That
+ * is a script's decision and not one this can make for it, because the buffer is
+ * cleared per bar and an engine cannot know which execution is the last one
+ * until it is.
+ *
+ * **The engine's cells are sparse and the chart's grid is dense.** A script
+ * writes the cells it has something to say about; the chart draws rows of cells.
+ * So the declared size is filled with blank cells and the written ones are
+ * 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, so the first declared grid is the one
+ * drawn and any after it are not. That is a gap in the chart's own contract
+ * rather than a choice worth making here: there is no second hook to write to,
+ * and merging two grids into one would put cells somewhere the script never
+ * asked for.
+ *
+ * **What ought to happen is a refusal, and it cannot be written yet.** A study
+ * whose second grid never appears is a study with no explanation, so the second
+ * `table()` should be refused where it is written, naming the limit. Every
+ * diagnostic in this project carries a catalogue code and the catalogue has
+ * none for "the chart cannot draw something this study declares"; inventing one
+ * here is the one thing that is not allowed, so the gap is reported instead, in
+ * `issues/0011-a-second-declared-grid-is-dropped-with-nothing-said.md`, with the
+ * sentence it should carry.
+ *
+ * Until it lands, the drop is at least no longer silent inside this repository:
+ * it is recorded in `spec/chart-narrowings.json` with its reason, and
+ * `scripts/check-chart-surface.mjs` fails the build if this adapter ever drops
+ * anything else a compiled program declares without recording it there.
+ */
+import type { CompiledProgram, Grid as DeclaredGrid } from '../../core/emit/index.js';
+import type { Grid, GridCell } from '../../core/engine/index.js';
+import { cssColour, cssOf } from './colours.js';
+import { colourField, numberField, stringField } from './fields.js';
+import type { InputLookup } from './fields.js';
+import type {
+  ChartCell,
+  ChartCellAlign,
+  ChartGrid,
+  ChartTablePosition,
+} from './surfaces.js';
+
+/** The language's four corners, in the chart's own words. */
+const CORNERS: Readonly<Record<string, ChartTablePosition>> = {
+  topLeft: 'top-left',
+  topRight: 'top-right',
+  bottomLeft: 'bottom-left',
+  bottomRight: 'bottom-right',
+};
+
+const ALIGNMENTS: readonly string[] = ['left', 'center', 'right'];
+
+/**
+ * The grid a chart draws, from the declaration and the engine's buffer.
+ *
+ * The buffer is paired with the 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.
+ */
+export function buildTable(
+  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));
+}
+
+function oneTable(
+  declared: DeclaredGrid,
+  lookup: InputLookup,
+  written: Grid | undefined,
+): ChartGrid {
+  const position = stringField(declared.position, lookup, 'topRight');
+  const textColour = colourField(declared.options.textColor, lookup);
+  const bgColour = colourField(declared.options.bgColor, lookup);
+  const rows = whole(numberField(declared.rows, lookup, 0));
+  const cols = whole(numberField(declared.cols, lookup, 0));
+  const fallback = textColour === undefined ? undefined : cssColour(textColour);
+
+  const grid: ChartCell[][] = [];
+  for (let row = 0; row < rows; row += 1) {
+    grid.push(new Array<ChartCell>(cols).fill({ text: '' }));
+  }
+  for (const cell of written?.cells ?? []) {
+    const built = oneCell(cell, fallback);
+    const line = grid[cell.row];
+    if (built === undefined || line === undefined || cell.col >= cols) continue;
+    line[cell.col] = built;
+  }
+
+  return {
+    rows: grid,
+    options: {
+      position: CORNERS[position] ?? 'top-right',
+      borderWidth: numberField(declared.options.borderWidth, lookup, 0),
+      ...(bgColour === undefined ? {} : { background: cssColour(bgColour) }),
+      ...(cols > 0 ? { cellWidth: columnWidths(grid, cols) } : {}),
+      // The chart measures the text it is about to draw and shrinks it to fit,
+      // which is the half of this that cannot be done from here.
+      fontSize: 'auto',
+    },
+  };
+}
+
+/**
+ * How wide each column has to be, in media pixels.
+ *
+ * The chart's default is one width for every column, chosen without seeing the
+ * text, and a grid whose header says "Moving averages" over cells saying
+ * "RSI: 27.22" has one column bleeding into the next. Nothing downstream can
+ * choose better, because by the time the chart has the grid it has lost which
+ * cells belong together; and nothing upstream can, because the script declares
+ * a size and writes text, not a layout.
+ *
+ * **This is an estimate, and it is allowed to be.** A real width needs the font
+ * the chart will draw with, and only the chart has it. So the width is counted
+ * off the characters and the chart's own `fontSize: 'auto'` corrects whatever
+ * this gets wrong: too narrow and the type shrinks a little, too wide and the
+ * column is a little loose. Either is a table that reads. The failure this
+ * replaces was neither.
+ *
+ * Delete it when the chart can size a column from its own measurements. It
+ * exists because that is not a thing it can be asked to do yet.
+ */
+function columnWidths(grid: readonly (readonly ChartCell[])[], cols: number): number[] {
+  const widths: number[] = [];
+  for (let col = 0; col < cols; col += 1) {
+    let widest = 0;
+    for (const row of grid) {
+      const text = row[col]?.text ?? '';
+      if (text.length > 0) widest = Math.max(widest, textWidth(text));
+    }
+    widths.push(Math.min(MAX_COLUMN, Math.max(MIN_COLUMN, Math.ceil(widest) + CELL_PADDING * 2)));
+  }
+  return widths;
+}
+
+/**
+ * Roughly how wide a string is at the type size the chart starts from.
+ *
+ * Counted rather than measured, and counted in two weights rather than one: a
+ * column of "Histogram: -7.01" is half punctuation and narrow digits, and
+ * treating every character as an em-and-a-bit makes that column half again as
+ * wide as it needs to be while "Moving averages" stays too narrow. Two weights
+ * is not typography, but it is enough to tell those two apart.
+ */
+function textWidth(text: string): number {
+  let width = 0;
+  for (const character of text) {
+    width += NARROW.has(character) ? BASE_SIZE * NARROW_EM : BASE_SIZE * WIDE_EM;
+  }
+  return width;
+}
+
+/** The characters that take noticeably less than an average advance. */
+const NARROW = new Set([...' .,:;!|ijlt1IJfr()[]{}-']);
+
+/**
+ * The type size the widths are counted at.
+ *
+ * The chart's own default row is 18 media pixels and it draws at 62% of the
+ * row, so this is the size a cell gets before anything shrinks it. Counting at
+ * a larger size would reserve room the text never uses.
+ */
+const BASE_SIZE = 11;
+const NARROW_EM = 0.32;
+const WIDE_EM = 0.56;
+
+/** What the chart insets a cell's text by, on each side. */
+const CELL_PADDING = 4;
+
+/**
+ * The narrowest a column is drawn.
+ *
+ * A column of one-character cells sized to its content is a sliver, and a grid
+ * of slivers reads as a rendering fault rather than as a narrow column.
+ */
+const MIN_COLUMN = 56;
+
+/**
+ * The widest a column is drawn.
+ *
+ * A cell holding a sentence would otherwise push the grid past the pane it is
+ * pinned inside, taking the chart with it. Past this the type shrinks instead,
+ * which is the chart's job and it is better at it.
+ */
+const MAX_COLUMN = 220;
+
+/**
+ * One written cell, or none.
+ *
+ * A cell whose text is absent is dropped rather than drawn, which leaves the
+ * blank cell that was already in its place: absence reaching a drawing surface
+ * is a gap, and a blank cell is what a grid draws where nothing was written
+ * (`language.md` 6.7).
+ *
+ * The grid's own text colour is written into each cell that named none, because
+ * the chart carries a text colour per cell and the language declares one for the
+ * whole grid as well.
+ */
+function oneCell(cell: GridCell, fallback: string | undefined): ChartCell | undefined {
+  if (typeof cell.text !== 'string') return undefined;
+  const align = typeof cell.align === 'string' && ALIGNMENTS.includes(cell.align)
+    ? (cell.align as ChartCellAlign)
+    : 'left';
+  const textColour = cssOf(cell.textColor) ?? fallback;
+  const bgColour = cssOf(cell.bgColor);
+  return {
+    text: cell.text,
+    ...(textColour === undefined ? {} : { textColor: textColour }),
+    ...(bgColour === undefined ? {} : { bgColor: bgColour }),
+    align,
+  };
+}
+
+/** A declared size, as a count of rows or columns a grid can be built with. */
+function whole(size: number): number {
+  return size > 0 ? Math.floor(size) : 0;
+}

package/src/adapters/codemirror/commands.ts

@@ -0,0 +1,53 @@
+/**
+ * Laying a script out again, as an editor command.
+ *
+ * `format` is the tier's, and the guarantee it carries is the one that makes a
+ * format button safe to put in front of somebody holding a position: laying a
+ * script out again cannot change what it computes. Every example and every gate
+ * script in the repository is formatted, both texts compiled, and the compiled
+ * programs compared field for field; and every call checks itself against the
+ * lexer, so a rule that is wrong returns the source untouched rather than a
+ * changed program.
+ *
+ * The whole document is replaced rather than a minimal edit computed. It is the
+ * honest version: a diff would have to be trusted to be equivalent to the
+ * replacement, and a formatter that moved a line somewhere unintended would do
+ * it silently. The cursor is kept where it was in the new text, clamped, because
+ * a format that sends the caret to the top of the file is a format nobody
+ * presses twice.
+ *
+ * **A document with two character line endings comes back with one character
+ * ones**, because that is what `language.md` 3.1 normalises a file to before
+ * anything reads it and what every offset in this tier indexes. It is the one
+ * change to a file's bytes that formatting makes without being asked, and it is
+ * recorded in `spec/editor-narrowings.json`.
+ */
+import { format } from '../../editor/index.js';
+import type { EditorView } from './contract.js';
+import { documentOf, normalisedOffset } from './positions.js';
+
+/**
+ * Lays the document out again, and says whether anything changed.
+ *
+ * ```ts
+ * keymap.of([{ key: "Shift-Alt-f", run: formatDocument }])
+ * ```
+ *
+ * False where the document is already laid out, which is what an editor command
+ * returns when it has nothing to do: the key press then falls through to
+ * whatever else is bound to it rather than being swallowed.
+ */
+export function formatDocument(view: EditorView): boolean {
+  const raw = view.state.doc.toString();
+  const held = documentOf(raw);
+  const laid = format(held.text);
+  if (laid === raw) return false;
+
+  const at = normalisedOffset(held, view.state.selection.main.head);
+  view.dispatch({
+    changes: { from: 0, to: view.state.doc.length, insert: laid },
+    selection: { anchor: Math.min(at, laid.length) },
+    scrollIntoView: true,
+  });
+  return true;
+}

package/src/adapters/codemirror/completion.ts

@@ -0,0 +1,74 @@
+/**
+ * Completions, as the editor's completion source.
+ *
+ * The whole of the work is done by `complete`, which reads the standard library
+ * manifest, the checker's bindings and the error catalogue. What is here is the
+ * translation: the editor wants a range to replace, a list of rows, and a note
+ * about whether the list is already filtered.
+ *
+ * **The list is already filtered**, by the word the writer has typed, compared
+ * exactly, because the language's names are case sensitive. So `filter` is false
+ * and the editor is told not to filter it again: its own matcher is fuzzy and
+ * case insensitive, and running it over a list that has already answered the
+ * question would put `EMA` in front of somebody as though it compiled.
+ *
+ * **A planned call is shown and marked.** `complete` carries the catalogue's own
+ * OS2020 sentence on a planned row, so that is what goes in the row's expanded
+ * note, and the row is pushed to the bottom of the list with the editor's own
+ * boost. A host that would rather not show them at all drops them with one
+ * field, which is why they are marked rather than filtered here.
+ */
+import { complete } from '../../editor/index.js';
+import type { Completion } from '../../editor/index.js';
+import type {
+  EditorCompletion,
+  EditorCompletionContext,
+  EditorCompletionResult,
+} from './contract.js';
+import { COMPLETION_TYPES } from './tokens.js';
+
+/** As far down the list as the editor will move a row. */
+const PLANNED_BOOST = -99;
+
+function rowOf(one: Completion): EditorCompletion {
+  const info = one.refusal ?? one.summary;
+  const type = COMPLETION_TYPES[one.kind];
+  return {
+    label: one.label,
+    ...(type === undefined ? {} : { type }),
+    detail: one.detail,
+    ...(info === undefined ? {} : { info }),
+    ...(one.insert === one.label ? {} : { apply: one.insert }),
+    ...(one.planned ? { boost: PLANNED_BOOST } : {}),
+  };
+}
+
+/**
+ * Every completion for the position the editor is asking about.
+ *
+ * ```ts
+ * autocompletion({ override: [openscriptCompletion] })
+ * ```
+ *
+ * Nothing comes back for an empty list rather than an empty list, because the
+ * editor reads the two differently: an empty result closes the panel and null
+ * lets another source answer, and a host with a snippet source of its own should
+ * keep it.
+ */
+export function openscriptCompletion(
+  context: EditorCompletionContext,
+): EditorCompletionResult | null {
+  const rows = complete(context.state.doc.toString(), context.pos);
+  // The first row carries the range every row replaces, so an empty list and a
+  // list whose first row is missing are one answer: nothing. Two guards for that
+  // would be one guard and a line no test can reach.
+  const first = rows[0];
+  if (first === undefined) return null;
+
+  return {
+    from: first.replace.offset,
+    to: first.replace.offset + first.replace.length,
+    options: rows.map(rowOf),
+    filter: false,
+  };
+}

package/src/adapters/codemirror/contract.ts

@@ -0,0 +1,156 @@
+/**
+ * The editor component's own shapes, as this adapter targets them.
+ *
+ * **Why they are declared here rather than imported.** The editor component is a
+ * peer dependency: a host that wants a text area installs it, and a host that
+ * wants only the language must not be made to. This repository therefore does
+ * not install it, cannot type check against it, and would fail its own layering
+ * check the moment a file here imported it. It is the same decision the chart
+ * adapter took, for the same reason, and `src/adapters/charts/contract.ts` says
+ * it at length.
+ *
+ * So the shapes this produces values for are declared below and the host's own
+ * build is where the two meet. Each one is a one line check that costs a host
+ * nothing and fails to compile if this file has drifted:
+ *
+ * ```ts
+ * import type { StreamParser } from "<the editor's language package>";
+ * import type { CompletionSource } from "<the editor's completion package>";
+ * import type { Diagnostic } from "<the editor's lint package>";
+ *
+ * const parser: StreamParser<unknown> = openscriptStream;
+ * const source: CompletionSource = openscriptCompletion;
+ * const linter: (view: EditorView) => Diagnostic[] = openscriptLint;
+ * ```
+ *
+ * **That line catches a value of the wrong shape and not an argument of the
+ * wrong shape.** A method's parameters are compared in both directions, so a
+ * hook declared here as taking something the editor never passes still assigns.
+ * That is the failure the chart adapter has actually made, so every member below
+ * takes the editor's own argument, spelled as the editor spells it, and every
+ * test drives each one with the argument the editor passes rather than with one
+ * of its own.
+ *
+ * **A style name is not checked by any of those lines.** The names this adapter
+ * returns from `token` are looked up by the editor in its own table of
+ * highlighting tags at run time, and an unknown one is a warning on a console
+ * rather than a compile error. That is why the whole mapping is one exported
+ * record a host can replace in a line, and why it is recorded in
+ * `spec/editor-narrowings.json` as the one thing here a type cannot hold.
+ */
+
+/**
+ * One line of the document, as the editor's tokenizer sees it.
+ *
+ * The editor hands a tokenizer a line at a time and expects `pos` to have moved
+ * forward when `token` returns. Only the members this adapter reads are
+ * declared: a narrower shape is still assignable from the editor's wider one.
+ */
+export interface EditorStringStream {
+  /** The line's text, without its line ending. */
+  readonly string: string;
+  /** Where the tokenizer has got to, which this adapter moves. */
+  pos: number;
+  /** Where the current token began. */
+  readonly start: number;
+  /** Whether `pos` is at the end of the line. */
+  eol(): boolean;
+  /** Whether `pos` is at the start of the line. */
+  sol(): boolean;
+}
+
+/**
+ * A tokenizer the editor drives one line at a time.
+ *
+ * `token` returns a style name, or null for text with no style of its own. The
+ * state is the tokenizer's to define, and the editor copies it at line
+ * boundaries so that it can restart mid document, which is why `copyState` is
+ * here.
+ */
+export interface EditorStreamParser<State> {
+  readonly name?: string;
+  startState?(indentUnit: number): State;
+  token(stream: EditorStringStream, state: State): string | null;
+  copyState?(state: State): State;
+  blankLine?(state: State, indentUnit: number): void;
+  readonly languageData?: Readonly<Record<string, unknown>>;
+}
+
+/** The document, which the editor holds as a rope rather than as a string. */
+export interface EditorText {
+  readonly length: number;
+  toString(): string;
+}
+
+/** The part of the editor's state this adapter reads. */
+export interface EditorState {
+  readonly doc: EditorText;
+  readonly selection: {
+    readonly main: { readonly head: number; readonly from: number; readonly to: number };
+  };
+}
+
+/** The part of the editor's view this adapter reads and dispatches to. */
+export interface EditorView {
+  readonly state: EditorState;
+  dispatch(transaction: {
+    readonly changes: { readonly from: number; readonly to: number; readonly insert: string };
+    readonly selection?: { readonly anchor: number };
+    readonly scrollIntoView?: boolean;
+  }): void;
+}
+
+/** What the editor hands a completion source. */
+export interface EditorCompletionContext {
+  readonly state: EditorState;
+  readonly pos: number;
+  /** Whether the writer asked for completions rather than merely typing. */
+  readonly explicit: boolean;
+}
+
+/** One row of the editor's completion list. */
+export interface EditorCompletion {
+  readonly label: string;
+  /** The editor's own name for the icon beside a row. */
+  readonly type?: string;
+  readonly detail?: string;
+  readonly info?: string;
+  /** The text to insert, where it differs from the label. */
+  readonly apply?: string;
+  /** Moves a row up or down the list, from -99 to 99. */
+  readonly boost?: number;
+}
+
+export interface EditorCompletionResult {
+  readonly from: number;
+  readonly to?: number;
+  readonly options: readonly EditorCompletion[];
+  /** False when the list is already filtered, which this adapter's is. */
+  readonly filter?: boolean;
+}
+
+/** One squiggle in the editor's lint panel and gutter. */
+export interface EditorDiagnostic {
+  readonly from: number;
+  readonly to: number;
+  readonly severity: 'hint' | 'info' | 'warning' | 'error';
+  readonly message: string;
+  /** Where the diagnostic came from, shown beside the message. */
+  readonly source?: string;
+  readonly actions?: readonly {
+    readonly name: string;
+    apply(view: EditorView, from: number, to: number): void;
+  }[];
+}
+
+/** What the editor shows over the text, and the element it shows. */
+export interface EditorTooltipView {
+  readonly dom: unknown;
+}
+
+export interface EditorTooltip {
+  readonly pos: number;
+  readonly end?: number;
+  readonly above?: boolean;
+  create(view: EditorView): EditorTooltipView;
+}

package/src/adapters/codemirror/index.ts

@@ -0,0 +1,66 @@
+/**
+ * The editor adapter: the language intelligence, wired into a text component.
+ *
+ * This and the chart adapter are the only modules in the repository allowed to
+ * know two worlds at once, and it is the piece a platform with its own editor
+ * replaces rather than the piece it patches. Everything under `src/editor` stays
+ * ignorant of any component, and the layering check is what keeps it that way.
+ *
+ * **The editor component is a peer dependency, and nothing here imports it.** A
+ * package that pulled a text component into everyone's install would defeat the
+ * point of a language a platform can take on its own, so the shapes this
+ * produces are declared in `contract.ts` and the host's own build is where the
+ * two are compared, in one line per piece. See that file for the lines. The
+ * entry point resolves and every function here runs in an install that holds no
+ * editor at all, which `scripts/check-entry-points.mjs` proves on every build.
+ *
+ * Six functions in, five pieces out:
+ *
+ *     openscriptStream             highlighting, a line at a time
+ *     openscriptCompletion         the completion list
+ *     openscriptLint               errors as you type, with their fixes
+ *     openscriptHoverTooltip       what the thing under the pointer is
+ *     openscriptSignatureTooltip   the call being written
+ *     formatDocument               lay the script out again
+ *
+ * The two tooltips take the markup as a parameter and have no default for it, so
+ * nothing in this package names a browser global at any tier. A host that wants
+ * none of this calls the six functions itself and draws its own. That is not the fallback, it is the supported path: what a host gives up
+ * by taking these instead is recorded in `spec/editor-narrowings.json`, which is
+ * three lines long and worth reading before choosing.
+ */
+export type {
+  EditorCompletion,
+  EditorCompletionContext,
+  EditorCompletionResult,
+  EditorDiagnostic,
+  EditorState,
+  EditorStreamParser,
+  EditorStringStream,
+  EditorText,
+  EditorTooltip,
+  EditorTooltipView,
+  EditorView,
+} from './contract.js';
+
+export { COMPLETION_TYPES, HIGHLIGHT_TOKENS } from './tokens.js';
+
+export type { StreamState } from './stream.js';
+export { openscriptStream } from './stream.js';
+
+export { openscriptCompletion } from './completion.js';
+
+export { diagnosticsFor, openscriptLint } from './lint.js';
+
+export type { Renderer } from './tooltips.js';
+export {
+  hoverLines,
+  openscriptHoverTooltip,
+  openscriptSignatureTooltip,
+  signatureLines,
+} from './tooltips.js';
+
+export { formatDocument } from './commands.js';
+
+export type { Document } from './positions.js';
+export { documentOf, normalisedOffset } from './positions.js';

package/src/adapters/codemirror/lint.ts

@@ -0,0 +1,66 @@
+/**
+ * Errors as you type, as the editor's linter.
+ *
+ * The diagnostics are the compiler's own, whole: `diagnose` runs the lexer, the
+ * parser, the checker and the emitter, so what a writer sees beside their line
+ * is exactly what a compile produces and nothing new can appear when they press
+ * apply. Every message and every fix came from the error catalogue that the
+ * documentation site is generated from.
+ *
+ * Three decisions worth stating, because each one is visible to a trader.
+ *
+ * **The fix is shown.** A `Diagnostic` carries a message saying what is wrong and
+ * a fix saying what to do, and the fix is the half that is worth reading. The
+ * editor's panel shows one string, so the two are joined with a line break
+ * rather than the fix being dropped.
+ *
+ * **The code is the source.** The editor shows a diagnostic's source beside its
+ * message, and a code is the one part of a diagnostic this project promises never
+ * to change, so it is what a trader quotes and what a support page is indexed by.
+ *
+ * **A zero width span is widened by one character.** The compiler points at a
+ * position for a mistake that is an absence, a missing bracket among them, and a
+ * squiggle of no width is a squiggle nobody sees.
+ */
+import { endOffset } from '../../core/index.js';
+import type { Diagnostic } from '../../core/index.js';
+import { diagnose } from '../../editor/index.js';
+import type { EditorDiagnostic, EditorView } from './contract.js';
+import { documentOf } from './positions.js';
+
+/** What the editor prints beside a message, which is the code and nothing else. */
+function sourceOf(one: Diagnostic): string {
+  return one.code;
+}
+
+/** Every diagnostic of a document, in the editor's own shape. */
+export function diagnosticsFor(raw: string): readonly EditorDiagnostic[] {
+  const held = documentOf(raw);
+  return diagnose(held.text).map((one) => {
+    const from = held.at(one.span.offset);
+    const to = held.at(endOffset(one.span));
+    return {
+      from,
+      to: to > from ? to : from + 1,
+      severity: one.severity,
+      message: `${one.message}\n${one.fix}`,
+      source: sourceOf(one),
+    };
+  });
+}
+
+/**
+ * The linter a host wires in one line.
+ *
+ * ```ts
+ * linter(openscriptLint)
+ * ```
+ *
+ * It is synchronous because it is fast enough to be: a finished ninety line
+ * study compiles in a third of a millisecond and the same file with a bracket
+ * left open in about a millisecond, both with a budget in the benchmark suite.
+ * The editor's own linter already debounces, so nothing here does it twice.
+ */
+export function openscriptLint(view: EditorView): readonly EditorDiagnostic[] {
+  return diagnosticsFor(view.state.doc.toString());
+}