@jxsuite/schema 5.6.0 → 6.0.0

package/src/jxn/parse.ts

@@ -9,7 +9,7 @@
  * replaced, and its own `toJson` is not used, because it turns `x (ref)"p"` into `"p"`, silently.
  */
 import { InvalidKdlError, getLocation, parse } from "@bgotink/kdl";
-import type { Document, Entry, Node } from "@bgotink/kdl";
+import type { Document, Entry, Identifier, Node, Value } from "@bgotink/kdl";
 import type { JsonObject, JsonValue, JxDocument } from "../../types.ts";
 import { isJsonObject, isNumber, isString } from "../guards.ts";
 import { normalizeObject } from "../parse.ts";
@@ -21,17 +21,48 @@ import { EVENT_HANDLER_NAMES } from "./event-handlers.ts";
 /** Bytes KDL's parser admits that a person should never have in a text file. */
 const RAW_CONTROL = /(?![\t\n\v\f\r])\p{Cc}/u;
 
-/** The annotations the grammar gives meaning to. Any other is a mistake, and not a thing to ignore. */
-const ANNOTATIONS = new Set(["array", "fn", "object", "on", "ref"]);
+/**
+ * The annotations the grammar gives meaning to. Any other is a mistake, and not a thing to ignore.
+ *
+ * Exported for an editor's grammar, which paints the same set and is tested against this one.
+ */
+export const JXN_ANNOTATIONS: ReadonlySet<string> = new Set([
+  "array",
+  "export",
+  "fn",
+  "object",
+  "on",
+  "ref",
+  "server",
+]);
 
 /** A child node name that means something other than an element. */
 const RESERVED_CHILDREN = new Set(["attributes", "script", "state", "style"]);
 
+/**
+ * Where single tokens are, by JSON Pointer (`spec.md` §23.3).
+ *
+ * A span says where a whole node or entry is, which is what a save needs. A type checker needs the
+ * token itself: a string with its quotes, so each character of a body can be put back where it was
+ * written, and a name alone, so renaming it in an editor rewrites the name and nothing beside it.
+ *
+ * A pointer here is built from a key as the file spells it, and a document's keys are NFC. A key
+ * the two disagree about is not found, which costs that name its mapping and never misplaces one.
+ */
+export interface JxnTokens {
+  /** The name of a keyed member: a node's name, or a property's. */
+  names: Map<string, JxnSpan>;
+  /** The one value a pointer holds, as written. */
+  values: Map<string, JxnSpan>;
+}
+
 /** What one read of a file is building. */
 export interface Reader {
   /** Where each thing came from, by JSON Pointer, when that was asked for. */
   spans: Map<string, JxnSpan> | null;
   text: string;
+  /** Where single tokens are, when that was asked for. */
+  tokens?: JxnTokens | undefined;
 }
 
 /** Set a key, refusing a repeat and a key that would be a prototype rather than data. */
@@ -58,8 +89,8 @@ export function failure(reader: Reader, at: Entry | Node, message: string): JxnE
   return new JxnError(message, start === undefined ? null : locate(reader.text, start));
 }
 
-/** Where a node or entry is, from the locations the parser stored. */
-function spanOf(at: Entry | Node): JxnSpan | null {
+/** Where a node, an entry or one token of either is, from the locations the parser stored. */
+function spanOf(at: Entry | Identifier | Node | Value): JxnSpan | null {
   const location = getLocation(at);
   return location ? { end: location.end.offset, start: location.start.offset } : null;
 }
@@ -72,6 +103,35 @@ export function mark(reader: Reader, pointer: string, at: Entry | Node): void {
   }
 }
 
+/** Record where a pointer's name was written. */
+function markName(reader: Reader, pointer: string, at: Identifier | null): void {
+  const span = reader.tokens && at ? spanOf(at) : null;
+  if (span) {
+    reader.tokens?.names.set(pointer, span);
+  }
+}
+
+/**
+ * Record where a pointer's one value was written.
+ *
+ * The parser's location for an argument starts at its annotation, so `(ref)"#/state/a"` would be a
+ * token that begins five characters before the string does. What it kept of how the value was
+ * spelled is the token itself, and the token ends where the location does.
+ */
+function markValue(reader: Reader, pointer: string, at: Entry | undefined): void {
+  const span = reader.tokens && at ? spanOf(at.value) : null;
+  if (span) {
+    const written = at?.value.representation;
+    const start = written === undefined ? span.start : span.end - written.length;
+    reader.tokens?.values.set(pointer, { end: span.end, start });
+  }
+}
+
+/** The entries of a node that carry no name, in order. */
+function positionalEntries(node: Node): Entry[] {
+  return node.entries.filter((entry) => !entry.name);
+}
+
 /** A JSON Pointer token. */
 export function token(key: string): string {
   return key.replaceAll("~", "~0").replaceAll("/", "~1");
@@ -80,7 +140,7 @@ export function token(key: string): string {
 /** A node's annotation, checked. */
 export function annotationOf(reader: Reader, node: Node): string | null {
   const tag = node.getTag();
-  if (tag !== null && !ANNOTATIONS.has(tag)) {
+  if (tag !== null && !JXN_ANNOTATIONS.has(tag)) {
     throw failure(reader, node, `(${tag}) is not an annotation Jx Notation has`);
   }
   if (tag === "ref") {
@@ -140,7 +200,9 @@ function readFunction(reader: Reader, node: Node, pointer: string): JsonObject {
   const kids = childrenOf(node);
   for (const entry of properties(node)) {
     setKey(fn, nameOf(entry), valueOf(reader, entry), reader, entry);
+    markValue(reader, `${pointer}/${token(nameOf(entry))}`, entry);
   }
+  const written = reader.tokens ? positionalEntries(node) : [];
   if (kids.length > 0) {
     if (values.length > 0) {
       setKey(fn, "parameters", values, reader, node);
@@ -153,28 +215,150 @@ function readFunction(reader: Reader, node: Node, pointer: string): JsonObject {
       setKey(fn, "parameters", parameters, reader, node);
     }
     setKey(fn, "body", body, reader, node);
+    markValue(reader, `${pointer}/body`, written.pop());
+  }
+  for (const [index, entry] of written.entries()) {
+    markValue(reader, `${pointer}/parameters/${index}`, entry);
+  }
+  mark(reader, pointer, node);
+  return fn;
+}
+
+/**
+ * An export of the document's client module (`spec.md` §23.2): a Function whose `$src` is
+ * `#client`. The node's name is the export unless `$export` says another.
+ */
+function readExport(reader: Reader, node: Node, pointer: string): JsonObject {
+  const fn: JsonObject = { $prototype: "Function", $src: "#client" };
+  if (positionals(reader, node).length > 0 || childrenOf(node).length > 0) {
+    throw failure(
+      reader,
+      node,
+      "(export) names a function the document's script exports, and holds no body of its own",
+    );
+  }
+  for (const entry of properties(node)) {
+    setKey(fn, nameOf(entry), valueOf(reader, entry), reader, entry);
+    markValue(reader, `${pointer}/${token(nameOf(entry))}`, entry);
+  }
+  if (!Object.hasOwn(fn, "$export")) {
+    fn.$export = node.getName().normalize("NFC");
   }
   mark(reader, pointer, node);
   return fn;
 }
 
-/** The items of a block made of `-` nodes. */
-function readItems(reader: Reader, kids: readonly Node[], pointer: string): JsonValue[] {
+/**
+ * A function of the document's server module (`spec.md` §23.2, §11.4): a `timing: "server"` entry
+ * whose `$src` is `#server`, exported under the node's name, with the node's named values as its
+ * `arguments`.
+ */
+function readServer(reader: Reader, node: Node, pointer: string): JsonObject {
+  if (positionals(reader, node).length > 0 || childrenOf(node).length > 0) {
+    throw failure(
+      reader,
+      node,
+      "(server) names a function the document's server script exports. Its arguments are written name=value",
+    );
+  }
+  const entry: JsonObject = {
+    $export: node.getName().normalize("NFC"),
+    $src: "#server",
+    timing: "server",
+  };
+  const named = properties(node);
+  if (named.length > 0) {
+    const args: JsonObject = {};
+    for (const argument of named) {
+      const key = nameOf(argument);
+      setKey(args, key, valueOf(reader, argument), reader, argument);
+      mark(reader, `${pointer}/arguments/${token(key)}`, argument);
+      markValue(reader, `${pointer}/arguments/${token(key)}`, argument);
+    }
+    entry.arguments = args;
+  }
+  mark(reader, pointer, node);
+  return entry;
+}
+
+/** The `$script` objects made from `script` nodes, which a second `script` node may add a side to. */
+const SCRIPT_BLOCKS = new WeakSet<JsonObject>();
+
+/**
+ * A `script` node of the root element: one of the document's two modules (`spec.md` §23.2).
+ *
+ * @param reader The read.
+ * @param node The `script` node.
+ * @param element The root element, which gains `$script.client` or `$script.server`.
+ */
+function readScript(reader: Reader, node: Node, element: JsonObject): void {
+  const named: JsonObject = {};
+  for (const entry of properties(node)) {
+    const key = nameOf(entry);
+    setKey(named, key, valueOf(reader, entry), reader, entry);
+    if (key !== "timing" || named[key] !== "server") {
+      throw failure(reader, entry, "A script takes timing=server, and nothing else");
+    }
+  }
+  const values = positionals(reader, node);
+  const [text] = values;
+  if (values.length !== 1 || !isString(text) || childrenOf(node).length > 0) {
+    throw failure(reader, node, "A script holds one string, which is the text of its module");
+  }
+  const side = Object.hasOwn(named, "timing") ? "server" : "client";
+  let scripts = element.$script;
+  if (!isJsonObject(scripts) || !SCRIPT_BLOCKS.has(scripts)) {
+    scripts = {};
+    SCRIPT_BLOCKS.add(scripts);
+    setKey(element, "$script", scripts, reader, node);
+  }
+  setKey(scripts, side, text, reader, node);
+  mark(reader, `/$script/${side}`, node);
+  markValue(reader, `/$script/${side}`, positionalEntries(node)[0]);
+}
+
+/** Record where each value of a list written on one line is, under the index it has in the list. */
+function markItems(reader: Reader, pointer: string, node: Node): void {
+  for (const [index, entry] of (reader.tokens ? positionalEntries(node) : []).entries()) {
+    markValue(reader, `${pointer}/${index}`, entry);
+  }
+}
+
+/**
+ * The items of a block made of `-` nodes.
+ *
+ * @param reader The file being read.
+ * @param kids The block.
+ * @param pointer Where the list is.
+ * @param before How many items the list holds ahead of the block, written on the node's own line.
+ */
+function readItems(
+  reader: Reader,
+  kids: readonly Node[],
+  pointer: string,
+  before = 0,
+): JsonValue[] {
   return kids.map((kid, index) => {
     if (kid.getName() !== "-") {
       throw failure(reader, kid, `A list holds only "-" items, and this is "${kid.getName()}"`);
     }
-    return readValue(reader, kid, `${pointer}/${index}`);
+    return readValue(reader, kid, `${pointer}/${before + index}`);
   });
 }
 
-/** A JSON block: JSON-in-KDL, plus `(ref)` and `(fn)`. */
+/** A JSON block: JSON-in-KDL, plus `(ref)`, `(fn)`, `(export)` and `(server)`. */
 export function readValue(reader: Reader, node: Node, pointer: string): JsonValue {
   const tag = annotationOf(reader, node);
   mark(reader, pointer, node);
   if (tag === "fn") {
     return readFunction(reader, node, pointer);
   }
+  if (tag === "export") {
+    return readExport(reader, node, pointer);
+  }
+  if (tag === "server") {
+    return readServer(reader, node, pointer);
+  }
   const values = positionals(reader, node);
   const props = properties(node);
   const kids = childrenOf(node);
@@ -182,19 +366,22 @@ export function readValue(reader: Reader, node: Node, pointer: string): JsonValu
     if (props.length > 0) {
       throw failure(reader, node, "(array) holds items, and these are named");
     }
-    return [...values, ...readItems(reader, kids, pointer)];
+    markItems(reader, pointer, node);
+    return [...values, ...readItems(reader, kids, pointer, values.length)];
   }
   if (tag !== "object") {
     if (values.length > 1) {
       if (props.length > 0 || kids.length > 0) {
         throw failure(reader, node, "A list of values cannot also have names or a block");
       }
+      markItems(reader, pointer, node);
       return values;
     }
     if (values.length === 1) {
       if (props.length > 0 || kids.length > 0) {
         throw failure(reader, node, "A value cannot also have names or a block");
       }
+      markValue(reader, pointer, positionalEntries(node)[0]);
       return values[0] ?? null;
     }
     if (kids.length > 0 && props.length === 0 && kids.every((kid) => kid.getName() === "-")) {
@@ -208,10 +395,13 @@ export function readValue(reader: Reader, node: Node, pointer: string): JsonValu
     const key = nameOf(entry);
     setKey(object, key, valueOf(reader, entry), reader, entry);
     mark(reader, `${pointer}/${token(key)}`, entry);
+    markName(reader, `${pointer}/${token(key)}`, entry.name);
+    markValue(reader, `${pointer}/${token(key)}`, entry);
   }
   for (const kid of kids) {
     const key = kid.getName();
     setKey(object, key, readValue(reader, kid, `${pointer}/${token(key)}`), reader, kid);
+    markName(reader, `${pointer}/${token(key)}`, kid.name);
   }
   return object;
 }
@@ -227,6 +417,7 @@ export function readStyle(reader: Reader, node: Node, pointer: string): JsonObje
     const key = nameOf(entry);
     setKey(style, key, valueOf(reader, entry), reader, entry);
     mark(reader, `${pointer}/${token(key)}`, entry);
+    markValue(reader, `${pointer}/${token(key)}`, entry);
   }
   for (const kid of childrenOf(node)) {
     const key = kid.getName();
@@ -257,6 +448,7 @@ export function readStyle(reader: Reader, node: Node, pointer: string): JsonObje
       }
       setKey(style, key, values[0] ?? null, reader, kid);
       mark(reader, child, kid);
+      markValue(reader, child, positionalEntries(kid)[0]);
     } else {
       setKey(style, key, readStyle(reader, kid, child), reader, kid);
     }
@@ -282,7 +474,9 @@ function readArrayRow(reader: Reader, node: Node, pointer: string): JsonObject {
   }
   for (const entry of properties(node)) {
     const key = nameOf(entry);
-    setKey(row, key.startsWith(".") ? key.slice(1) : key, valueOf(reader, entry), reader, entry);
+    const member = key.startsWith(".") ? key.slice(1) : key;
+    setKey(row, member, valueOf(reader, entry), reader, entry);
+    markValue(reader, `${pointer}/${token(member)}`, entry);
   }
   if (childrenOf(node).length > 0) {
     setKey(row, "map", readOnlyElement(reader, node, `${pointer}/map`), reader, node);
@@ -299,6 +493,7 @@ function readChild(reader: Reader, node: Node, pointer: string): JsonValue {
       throw failure(reader, node, `"-" is one piece of text or one (ref)`);
     }
     mark(reader, pointer, node);
+    markValue(reader, pointer, positionalEntries(node)[0]);
     return values[0] ?? null;
   }
   if (name === "$array") {
@@ -355,6 +550,7 @@ function readElement(reader: Reader, node: Node, pointer: string): JsonObject {
     }
     if (text !== undefined) {
       setKey(element, "textContent", text, reader, node);
+      markValue(reader, `${pointer}/textContent`, positionalEntries(node)[1]);
     }
   } else {
     if (name.startsWith("$")) {
@@ -367,6 +563,7 @@ function readElement(reader: Reader, node: Node, pointer: string): JsonObject {
     if (values[0] !== undefined) {
       setKey(element, "textContent", values[0], reader, node);
       mark(reader, `${pointer}/textContent`, node);
+      markValue(reader, `${pointer}/textContent`, positionalEntries(node)[0]);
     }
   }
   readElementEntries(reader, node, element, pointer);
@@ -409,9 +606,11 @@ function readElementEntries(
       const member = key.startsWith(".") ? key.slice(1) : key;
       setKey(element, member, value, reader, entry);
       mark(reader, `${pointer}/${token(member)}`, entry);
+      markValue(reader, `${pointer}/${token(member)}`, entry);
     } else if (key.startsWith("on") && entryTag === "ref") {
       setKey(element, key, value, reader, entry);
       mark(reader, `${pointer}/${token(key)}`, entry);
+      markValue(reader, `${pointer}/${token(key)}`, entry);
     } else if (key.startsWith("on") && EVENT_HANDLER_NAMES.has(key)) {
       throw failure(
         reader,
@@ -421,6 +620,7 @@ function readElementEntries(
     } else {
       setKey(attributesOf(element), key, value, reader, entry);
       mark(reader, `${pointer}/attributes/${token(key)}`, entry);
+      markValue(reader, `${pointer}/attributes/${token(key)}`, entry);
     }
   }
 }
@@ -447,7 +647,17 @@ function readElementChild(
     // `(on)` has done its job by saying this is a handler, and what it holds is a JSON block.
     setKey(element, name, readValue(reader, kid, member(name)), reader, kid);
   } else if (name === "script") {
-    throw failure(reader, kid, `"script" is reserved. A <script> element is $element "script"`);
+    if (pointer !== "") {
+      throw failure(
+        reader,
+        kid,
+        `"script" is the document's module, and is written in its root element. A <script> element is $element "script"`,
+      );
+    }
+    if (tag !== null) {
+      throw failure(reader, kid, `(${tag}) cannot annotate a script`);
+    }
+    readScript(reader, kid, element);
   } else if (name === "state") {
     setKey(element, "state", readValue(reader, kid, member("state")), reader, kid);
   } else if (name === "style") {
@@ -590,3 +800,14 @@ export function parseJxnWithSpans(text: string) {
   const spans = new Map<string, JxnSpan>();
   return { document: readDocument({ spans, text }), spans };
 }
+
+/**
+ * Read a `.jxn` document, and where the single tokens a type checker reads were written.
+ *
+ * @param text The file.
+ * @throws {JxnError} When it is not one.
+ */
+export function parseJxnWithTokens(text: string) {
+  const tokens: JxnTokens = { names: new Map(), values: new Map() };
+  return { document: readDocument({ spans: null, text, tokens }), tokens };
+}