@telorun/editor-protocol 0.1.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/editor-protocol",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "The Telo editor protocol: the contract between an editor host and a telo language-server engine — the telo/* requests, the telo/requirements notification and the protocol generation.",
   "keywords": [
     "telo",

package/src/index.ts

@@ -5,7 +5,7 @@
 
 /** The protocol generation this package describes. Additions within a
  *  generation are negotiated by capability; an incompatible change bumps it. */
-export const TELO_EDITOR_PROTOCOL = 1;
+export const TELO_EDITOR_PROTOCOL = 2;
 
 /** What an engine advertises under `ServerCapabilities.experimental`. */
 export interface TeloExperimentalCapabilities {
@@ -15,6 +15,9 @@ export interface TeloExperimentalCapabilities {
 export interface TeloProtocolCapability {
   /** The generation the engine speaks. */
   protocol: number;
+  /** The engine serves `telo/viewModel` and `telo/celCompletion` and sends
+   *  `telo/viewModelChanged`. */
+  viewModel?: boolean;
 }
 
 /** The file a module directory is read as: `telo/read` of a directory answers
@@ -27,8 +30,9 @@ export const TELO_MODULE_FILENAME = "telo.yaml";
  *  pending. */
 export const TELO_SERVER_NAME = "telo";
 
-/** Method names of the requests an engine sends and a host serves, and of the
- *  notification an engine sends. */
+/** Method names of every `telo/*` message: the requests an engine sends and a
+ *  host serves, the requests a host sends and an engine serves, and the
+ *  notifications an engine sends. */
 export const TeloMethod = {
   read: "telo/read",
   exists: "telo/exists",
@@ -36,6 +40,9 @@ export const TeloMethod = {
   hubSearchRefs: "telo/hub/searchRefs",
   hubListVersions: "telo/hub/listVersions",
   requirements: "telo/requirements",
+  viewModel: "telo/viewModel",
+  celCompletion: "telo/celCompletion",
+  viewModelChanged: "telo/viewModelChanged",
 } as const;
 export type TeloMethod = (typeof TeloMethod)[keyof typeof TeloMethod];
 
@@ -145,6 +152,331 @@ export interface RequirementsParams {
   ranges: RequirementsRange[];
 }
 
+/** `telo/viewModelChanged`: the owner's view model moved — sent after each
+ *  analysis of the owner, and when the owner stops being analysed (a
+ *  `telo/viewModel` for it then answers `null`). */
+export interface ViewModelChangedParams {
+  /** Canonical `file:` URI of the owner module's document. */
+  owner: string;
+  /** Increases with every analysis of the owner, and when it is dropped. */
+  revision: number;
+}
+
+// --- Engine-served requests (host → engine) --------------------------------
+
+/** `telo/viewModel`: the structured-view model of one owner module. */
+export interface ViewModelParams {
+  owner: string;
+  /** The assignment to draw the module graph in, keyed by dimension; a
+   *  dimension left out takes its default. */
+  configuration?: Record<string, unknown>;
+}
+/** `null` when the engine is not analysing `owner`. */
+export type ViewModelResult = ViewModel | null;
+
+/** `telo/celCompletion`: completion for a CEL value typed into a structured
+ *  form field, which is not document text yet. */
+export interface CelCompletionParams {
+  owner: string;
+  /** The resource the field belongs to. */
+  resource: { kind: string; name: string };
+  /** Concrete path of the field within the resource (`routes[0].handler.inputs.x`). */
+  path: string;
+  /** The tag the value is written under, without its `!` (`cel`, `interpolate`). */
+  tag: string;
+  /** The field's value without its tag. */
+  text: string;
+  /** Cursor offset into `text`. */
+  offset: number;
+}
+/** LSP `CompletionItem`s; a `textEdit` range is a line/character range in
+ *  `text`. Empty when the engine is not analysing `owner`. */
+export type CelCompletionResult = CompletionItem[];
+
+/** The members of an LSP `CompletionItem` an engine sets. */
+export interface CompletionItem {
+  label: string;
+  /** LSP `CompletionItemKind`. */
+  kind?: number;
+  detail?: string;
+  documentation?: string;
+  insertText?: string;
+  /** LSP `InsertTextFormat`; 2 is a snippet. */
+  insertTextFormat?: number;
+  textEdit?: { range: TextRange; newText: string };
+  preselect?: boolean;
+  sortText?: string;
+  filterText?: string;
+  command?: { title: string; command: string };
+}
+
+export interface TextRange {
+  start: { line: number; character: number };
+  end: { line: number; character: number };
+}
+
+/** Params and result of every engine-served request, by method. */
+export interface TeloEngineRequests {
+  "telo/viewModel": [ViewModelParams, ViewModelResult];
+  "telo/celCompletion": [CelCompletionParams, CelCompletionResult];
+}
+
+// --- The view model ---------------------------------------------------------
+
+/** A JSON Schema, as plain JSON. */
+export type JsonSchema = Record<string, unknown>;
+
+/**
+ * What a structured editor (a module canvas, a schema form, a reference picker)
+ * reads about one owner module, computed by the engine of the module's telo
+ * version over the same analysis its diagnostics come from.
+ */
+export interface ViewModel {
+  owner: string;
+  revision: number;
+  /** The owner module drawn as a graph. */
+  moduleGraph: ModuleGraphData | null;
+  /** The configurations `moduleGraph` can be drawn in. Absent when the module
+   *  writes no `!if` / `!switch` choice. */
+  configurations?: ViewModelConfigurations;
+  /** The schema of the owner's module document kind. */
+  moduleRootSchema: JsonSchema | null;
+  /** Each `kind:` spelling in the closure, and each constraint in
+   *  `refConstraints`, mapped to the canonical kind it resolves to. A spelling
+   *  that resolves to nothing is absent. */
+  kindSpellings: Record<string, string>;
+  /** Per reference-slot constraint: the canonical kinds that satisfy it and the
+   *  spellings a new resource could be created with. A constraint that resolves
+   *  to nothing is absent. */
+  refConstraints: Record<string, RefConstraint>;
+  /** Invocation contracts of every kind declaring one, by canonical kind. */
+  contracts: Record<string, KindContract>;
+  /** Why a resource of the owner module cannot fill a slot, by what it returns:
+   *  one entry per reference slot declaring an `outputType` in the closure's
+   *  kinds. */
+  outputRefusals: OutputRefusals[];
+  /** The body of every templated kind in the closure, by canonical kind. */
+  templates: Record<string, TemplateGraphData>;
+  /** Every reference written in the owner module's resources and its module
+   *  document. */
+  referenceSites: ReferenceSite[];
+  /** Canonical URI → the LSP version of each open document the analysis read.
+   *  A host holding a newer version of one of them holds text this model was
+   *  not computed from. */
+  documents: Record<string, number>;
+}
+
+/** One axis of the configuration picker: the path it is read at, its domain
+ *  and the value a picker starts at (a presence dimension: `absent`). */
+export interface GraphDimension {
+  key: string;
+  values: unknown[];
+  default: unknown;
+}
+
+export interface ViewModelConfigurations {
+  dimensions: GraphDimension[];
+  /** The assignment `moduleGraph` is drawn in, every dimension present. */
+  selected: Record<string, unknown>;
+}
+
+/** One alternative of a choice: `then`, `else`, `default`, a case key, or
+ *  `absent` (an `!if` with no `else:` whose condition is false). At a
+ *  declaration position it carries the kind the branch declares. */
+export interface GraphAlternative {
+  key: string;
+  kind?: string;
+}
+
+/** A `!if` / `!switch` drawn at a box. At a declaration position (`path` is
+ *  `""`) the box is the choice, identified by its name — only its kind follows
+ *  the selected configuration. */
+export interface GraphChoice {
+  path: string;
+  tag: "if" | "switch";
+  alternatives: GraphAlternative[];
+  selected: string | null;
+}
+
+/** A `!for-each` drawn as one box (a family) or one row (a repeat in a list),
+ *  never one per element. */
+export interface GraphRepeat {
+  source: string;
+  as: string;
+}
+
+export interface RefConstraint {
+  accepted: string[];
+  userFacing: string[];
+}
+
+export interface KindContract {
+  inputType?: JsonSchema;
+  outputType?: JsonSchema;
+}
+
+export interface OutputRefusals {
+  /** The canonical kind declaring the slot. */
+  kind: string;
+  /** JSON Pointer of the slot's `x-telo-ref` node within that kind's `schema`. */
+  pointer: string;
+  /** Resource name, in the scope the entry is listed in (the owner module, or
+   *  a template's body), → one line per definite mismatch. A resource absent
+   *  here can fill the slot. */
+  refusals: Record<string, string[]>;
+}
+
+export interface TemplateGraphData {
+  /** Canonical `<module>.<Name>`. */
+  kindId: string;
+  name: string;
+  module?: string;
+  /** The kind's capability, inherited along `extends`. */
+  capability?: string;
+  /** The definition document as analysed; `metadata.source` is a document URI. */
+  definition: Record<string, unknown>;
+  graph: ModuleGraphData;
+  /** Why an entry of the body cannot fill a slot, by what it returns — the
+   *  owner's `outputRefusals`, judged over the body's entries. */
+  outputRefusals: OutputRefusals[];
+}
+
+export interface ReferenceSite {
+  /** The resource writing the reference; the module document as itself. */
+  source: { kind: string; name: string };
+  /** Concrete path of the slot within that resource. */
+  path: string;
+  /** The name the reference holds, as written (`Alias.name` across an import). */
+  target: string;
+}
+
+/** A module drawn as boxes, ordered rows and classed edges — the analyzer's
+ *  module graph as data. */
+export interface ModuleGraphData {
+  root?: GraphNodeData;
+  nodes: GraphNodeData[];
+  edges: GraphEdgeData[];
+  regions: GraphRegionData[];
+  kinds: GraphKindData[];
+}
+
+/** `root` | `named` | `inline` | `scoped` | `imported` | `injected` |
+ *  `enclosing` | `forwarded`. */
+export type NodeOwnership = string;
+/** `flow` | `holds` | `shape` | `data`. */
+export type EdgeClass = string;
+/** `step` | `entry` | `target` | `repeat` | `inline` | `reference` | `export`. */
+export type RowKind = string;
+
+export interface GraphNodeData {
+  id: string;
+  kind: string;
+  name: string;
+  capability?: string;
+  canonicalKind?: string;
+  unknownKind?: boolean;
+  ownership: NodeOwnership;
+  owner?: string;
+  ownerSite?: string;
+  module?: string;
+  external?: boolean;
+  alias?: string;
+  ports: GraphPortData[];
+  rows: GraphRowData[];
+  rowArrays: { field: string; kind: RowKind }[];
+  throws?: { codes: string[]; unbounded: boolean };
+  root?: boolean;
+  choice?: GraphChoice;
+  choices?: GraphChoice[];
+  family?: GraphRepeat;
+}
+
+export interface GraphPortData {
+  slot: string;
+  refs: string[];
+  capabilities: string[];
+  array: boolean;
+  class: EdgeClass;
+  slots: { path: string; target?: string; targetNode?: string; inline?: boolean }[];
+  addPath?: string;
+  rowOwned?: boolean;
+}
+
+export interface GraphRowData {
+  id: string;
+  kind: RowKind;
+  name?: string;
+  path: string;
+  array: string;
+  index: number;
+  depth: number;
+  parent?: string;
+  target?: string;
+  targetNode?: string;
+  inputs?: string;
+  match?: Record<string, unknown>;
+  variant?: string;
+  variantLabel?: string;
+  predicate?: string;
+  catches?: boolean;
+  dispatch?: {
+    path: string;
+    refs: string[];
+    inline?: boolean;
+    alternatives?: { path: string; refs: string[] }[];
+  };
+  declares?: string;
+  unknownKind?: boolean;
+  /** `repeat` rows: the loop the list item is. */
+  repeat?: GraphRepeat;
+  /** A step a template repeat emitted: its identity text, in place of `name`. */
+  emitted?: string;
+}
+
+export interface GraphEdgeData {
+  id: string;
+  from: string;
+  to?: string;
+  toName: string;
+  class: EdgeClass;
+  /** `schema` | `dependency` | `call` | `detached` | `trigger.inbound` |
+   *  `trigger.consumer`. */
+  use: string[];
+  slot: string;
+  path: string;
+  row?: string;
+  inputs?: string;
+  boot?: boolean;
+  scoped?: boolean;
+  read?: string;
+  call?: string;
+}
+
+export interface GraphRegionData {
+  id: string;
+  /** `inline` | `scope` | `zone`. */
+  kind: string;
+  owner: string;
+  site: string;
+  members: string[];
+  attributes?: Record<string, string>;
+  boundaries?: { from: string; toName: string; escaping: string[] }[];
+}
+
+export interface GraphKindData {
+  id: string;
+  name: string;
+  module?: string;
+  abstract: boolean;
+  capability?: string;
+  extendsId?: string;
+  extendsName?: string;
+  instances: string[];
+  template: boolean;
+  own: boolean;
+  exported?: boolean;
+}
+
 // --- Diagnostic.data -------------------------------------------------------
 
 /** The YAML tags a repair may write. A receiver that does not know a tag
@@ -166,6 +498,13 @@ export interface TeloDiagnosticData {
   resource?: { kind: string; name: string };
   /** Dotted path of the offending value within that resource. */
   path?: string;
+  /** Present only on a diagnostic that holds in some configurations of the
+   *  application but not all: partial assignments covering where it holds, each
+   *  `{ "<dimension path>": <JSON value> }` naming only the dimensions it
+   *  narrows (one it leaves out holds every value; the diagnostic holds where
+   *  some entry agrees on every key it names). Empty when it holds in none. The
+   *  label is in `message` only. */
+  configurations?: Array<Record<string, unknown>>;
 }
 
 // --- Commands --------------------------------------------------------------