@jxsuite/schema 5.6.0 → 6.0.0

package/src/jxn/state-types.ts

@@ -0,0 +1,271 @@
+/**
+ * What a document's `state` says its types are (`spec.md` §23.3), for the two files a checker
+ * reads: one body wrapped alone (`virtual-types.ts`) and a whole `.jxn` document
+ * (`virtual-document.ts`). Both say the same thing about the same entry because both ask here.
+ *
+ * **What `State` says is what the document can prove, and no more.** A literal gives its type, an
+ * object its shape and an array the types of its items. Anything a document does not determine (a
+ * `$prototype` instance, an `$expression`, a template, a `timing: "server"` call, a `null`) is
+ * `any`, because an error about code the author cannot fix teaches them to ignore the checker.
+ */
+import {
+  isBoolean,
+  isExpressionDef,
+  isFunctionDef,
+  isJsonObject,
+  isNumber,
+  isServerFnDef,
+  isString,
+  hasSchemaKeywords,
+} from "../guards";
+import { pointerInto, propertyName, schemaParts, written } from "./schema-types";
+import type { JsonObject, JsonValue, JxElement, ProjectConfig } from "../../types";
+import type { SchemaSite, TypePart } from "./schema-types";
+
+/** The most levels of an object's shape written out before it is `any`. */
+const MAX_NESTING = 4;
+
+/** The most distinct item types an array's type is built from. */
+const MAX_ITEM_TYPES = 6;
+
+/** What a `type` keyword says with nothing beside it, which a value written there says better. */
+const VAGUE = new Set(["any", "any[]", "{ [key: string]: any; }"]);
+
+/** The type a value's shape gives it, widened the way a mutable binding widens. */
+function typeOfValue(value: JsonValue | undefined, depth: number): string {
+  if (isString(value)) {
+    return "string";
+  }
+  if (isNumber(value)) {
+    return "number";
+  }
+  if (isBoolean(value)) {
+    return "boolean";
+  }
+  if (Array.isArray(value)) {
+    const types = [...new Set(value.map((item) => typeOfValue(item, depth + 1)))];
+    if (types.length === 0 || types.length > MAX_ITEM_TYPES || types.includes("any")) {
+      return "any[]";
+    }
+    return types.length === 1 ? `${types[0]}[]` : `(${types.join(" | ")})[]`;
+  }
+  if (isJsonObject(value) && depth < MAX_NESTING) {
+    const members = Object.entries(value).map(
+      ([key, item]) => `${propertyName(key)}: ${typeOfValue(item, depth + 1)}`,
+    );
+    return members.length === 0 ? "Record<string, any>" : `{ ${members.join("; ")} }`;
+  }
+  return "any";
+}
+
+/**
+ * The type a typed entry declares (`spec.md` §5.3): `type` holds its schema, or is the first
+ * keyword of one whose others stand beside it.
+ */
+function declaredParts(entry: JsonObject, site: SchemaSite): TypePart[] {
+  const declared = isJsonObject(entry.type)
+    ? schemaParts(entry.type, { ...site, pointer: pointerInto(site.pointer, "type") })
+    : schemaParts(entry, site);
+  const { default: initial } = entry;
+  // `type: "array"` beside `default: [1, 2]` is a list of numbers, which only the value says.
+  const told = initial !== undefined && initial !== null && VAGUE.has(written(declared));
+  return told ? [typeOfValue(initial, 0)] : declared;
+}
+
+/**
+ * The type of one `state` entry, by the shapes of `spec.md` §5, in parts.
+ *
+ * @param entry The entry.
+ * @param role What its document uses it as, when it is a function.
+ * @param site Where it is, and whether its document has `$defs`.
+ */
+export function entryParts(
+  entry: JsonValue | undefined,
+  role: "computed" | "callable" | undefined,
+  site: SchemaSite,
+): TypePart[] {
+  if (isString(entry)) {
+    // A template is a computed value of a type the document does not give.
+    return [entry.includes("${") ? "any" : "string"];
+  }
+  if (!isJsonObject(entry)) {
+    return [typeOfValue(entry, 0)];
+  }
+  if (isFunctionDef(entry)) {
+    return [role === "computed" ? "any" : "(...args: any[]) => any"];
+  }
+  if (isString(entry.$prototype) || isExpressionDef(entry) || isServerFnDef(entry)) {
+    return ["any"];
+  }
+  return "default" in entry || hasSchemaKeywords(entry)
+    ? declaredParts(entry, site)
+    : [typeOfValue(entry, 0)];
+}
+
+/**
+ * The type of one `state` entry, as text.
+ *
+ * @param entry The entry.
+ * @param role What its document uses it as, when it is a function.
+ * @param defs Whether its document has `$defs`.
+ */
+export function typeOfEntry(
+  entry: JsonValue | undefined,
+  role?: "computed" | "callable",
+  defs = false,
+): string {
+  return written(entryParts(entry, role, { defs, pointer: "" }));
+}
+
+/** The `state` object of an element, when it has one. */
+export function stateOf(node: JsonValue | undefined): Record<string, JsonValue> | null {
+  return isJsonObject(node) && isJsonObject(node.state) ? node.state : null;
+}
+
+/** One parameter a function's body is called with. */
+export interface DeclaredParameter {
+  /** Where the entry writes it in `parameters`, or -1 where it does not. */
+  at: number;
+  name: string;
+  /** The type the entry declares for it, or null where it declares none. */
+  type: TypePart[] | null;
+}
+
+/**
+ * The type a parameter written as an object declares (`spec.md` §23.3): the TypeScript its `text`
+ * holds, as a Custom Elements Manifest has it, or the schema it is, as a typed entry is one.
+ */
+function parameterType(parameter: JsonObject, site: SchemaSite): TypePart[] | null {
+  const { type } = parameter;
+  if (type === undefined) {
+    return null;
+  }
+  const text = isJsonObject(type) && isString(type.text) ? type.text : null;
+  if (text?.trim() === "") {
+    // Nothing is no type, and written as one it would be an error on a line nobody wrote.
+    return null;
+  }
+  const pointer = pointerInto(pointerInto(site.pointer, "type"), "text");
+  const declared: TypePart[] =
+    text === null
+      ? declaredParts(parameter, site)
+      : /* In brackets, so that what follows it is not read into a type that ends in a function's,
+           and closed on a line of its own, so that a comment the text ends in takes nothing. */
+        ["(", { kind: "text", name: text, pointer, written: text }, "\n)"];
+  return parameter.optional === true ? [...declared, " | undefined"] : declared;
+}
+
+/**
+ * The parameters a function's body is called with: `state` first, then the declared ones in their
+ * order (`spec.md` §5.3), each with the type it declares.
+ *
+ * @param definition The function's entry.
+ * @param site Where the entry is, and whether its document has `$defs`.
+ */
+export function declaredParameters(
+  definition: JsonValue | undefined,
+  site: SchemaSite,
+): DeclaredParameter[] {
+  const entry = isJsonObject(definition) ? definition : {};
+  const within = pointerInto(site.pointer, "parameters");
+  const listed: DeclaredParameter[] = Array.isArray(entry.parameters)
+    ? entry.parameters.flatMap((parameter, at) => {
+        if (isString(parameter)) {
+          return [{ at, name: parameter, type: null }];
+        }
+        // What is neither a name nor an object holding one is not a parameter the runtime could bind.
+        return isJsonObject(parameter) && isString(parameter.name)
+          ? [
+              {
+                at,
+                name: parameter.name,
+                type: parameterType(parameter, { ...site, pointer: pointerInto(within, at) }),
+              },
+            ]
+          : [];
+      })
+    : (Array.isArray(entry.arguments) ? entry.arguments : []).flatMap((name) =>
+        isString(name) ? [{ at: -1, name, type: null }] : [],
+      );
+  // A declared `state` is moved to the front, never repeated, as the runtime builds it.
+  const state = listed.find((parameter) => parameter.name === "state");
+  return [
+    { at: state?.at ?? -1, name: "state", type: null },
+    ...listed.filter((parameter) => parameter.name !== "state"),
+  ];
+}
+
+/** What a document is given that it does not say, which only its project knows. */
+export interface OutsideState {
+  /**
+   * The components the project keeps (`imports.md` §1.4), which a document uses without declaring
+   * them: the `.jxn` file each one is, by its tag, as a path from the document.
+   */
+  components?: Readonly<Record<string, string>> | undefined;
+  /** The project names a default layout, which wraps a document that names none. */
+  layout?: boolean | undefined;
+  /** The project has `state` of its own, which every page reads (`site-architecture.md` §3.2). */
+  state?: boolean | undefined;
+  /**
+   * The document is a layout. A page is merged with its layout before anything runs, the page's
+   * state over the layout's, so a layout reads names only a page declares (`spec.md` §23.3).
+   */
+  wraps?: boolean | undefined;
+}
+
+/** What a project gives the documents in it, which its file alone says. */
+export interface ProjectGives {
+  /** It names a default layout. */
+  layout: boolean;
+  /** It has `state` of its own. */
+  state: boolean;
+}
+
+/**
+ * What a project's file says the project gives its documents.
+ *
+ * @param config The project's configuration, as its file holds it.
+ */
+export function givenByProject(config: ProjectConfig): ProjectGives {
+  return {
+    layout: isString(config.defaults?.layout),
+    state: Object.keys(config.state ?? {}).length > 0,
+  };
+}
+
+/**
+ * What a document is given by where its project keeps it.
+ *
+ * A component is a scope of its own, and nothing of the project's is merged into it. A layout is
+ * what wraps a page: the default one does not wrap it, and the state of each page it wraps reaches
+ * it. Every other document is a page, as far as its state goes.
+ *
+ * @param folder The first folder on the document's path from its project: `layouts` for
+ *   `layouts/base.jxn`.
+ * @param gives What the project gives.
+ */
+export function outsideAt(folder: string | undefined, gives: ProjectGives): OutsideState {
+  if (folder === "components") {
+    return {};
+  }
+  return folder === "layouts"
+    ? { state: gives.state, wraps: true }
+    : { layout: gives.layout, state: gives.state };
+}
+
+/**
+ * The index signature that closes `State`.
+ *
+ * A page with a layout inherits state the page does not name, so its `State` is open, and so is one
+ * in a project that has `state` of its own, and so is a layout, which is given the state of every
+ * page it wraps. Otherwise only the `$` members the host adds (`$media`, `$props`) are. `$layout:
+ * false` is a page saying it has no layout, the project's default included.
+ *
+ * @param doc The document.
+ * @param outside What its project gives it. Nothing, when the reader knows of no project.
+ */
+export function stateIndex(doc: JxElement, outside: OutsideState = {}): string {
+  const wrapped = doc.$layout === undefined ? outside.layout === true : doc.$layout !== false;
+  const given = outside.state === true || outside.wraps === true || wrapped;
+  return given ? "[key: string]: any;" : "[key: `$${string}`]: any;";
+}

package/src/jxn/string-pieces.ts

@@ -0,0 +1,240 @@
+/**
+ * Where each character of a string's value was written (`spec.md` §23.3).
+ *
+ * A type error in a function body is found in the body's value, and has to be shown in the file,
+ * where that value is spelled as a KDL string: inside quotes, with escapes, or over several lines
+ * with the indentation of its block taken off each. This reads one string token and answers with
+ * the runs of its value, each beside the source it came from. A run that is the source character
+ * for character can be mapped one to one, so a column in it is exact. A run that is not (an escape,
+ * a line ending the file spells `\r\n`) is one indivisible piece.
+ *
+ * `@bgotink/kdl` decodes a string and does not say where its characters came from, so this reads
+ * the token again. It is checked against the decoder rather than trusted: when the runs do not
+ * spell the value the parser read, the answer is one piece covering the whole token, which places
+ * an error on the right string and never on the wrong character.
+ */
+import type { JxnSpan } from "./errors.ts";
+
+/** A run of a string's value, beside the source it was written as. */
+export interface StringPiece {
+  /** One past the last source character. */
+  end: number;
+  start: number;
+  /** The run of the value. */
+  text: string;
+  /** Whether {@link StringPiece.text} is the source, character for character. */
+  verbatim: boolean;
+}
+
+/** One line of a multi-line string: its text, and where the next line starts. */
+interface Line {
+  end: number;
+  next: number;
+  start: number;
+}
+
+/** What KDL calls whitespace inside a line. */
+const SPACE = String.raw`\t    -   　`;
+
+/** What KDL calls a line ending. */
+const BREAK = String.raw`\n\r\u0085\v\f

`;
+
+const NEWLINE = new RegExp(String.raw`\r\n|[${BREAK}]`, "gu");
+
+/** A line holding nothing but whitespace, which a multi-line string reads as an empty one. */
+const BLANK = new RegExp(`^[${SPACE}]*$`, "u");
+
+/** What a backslash before whitespace discards: all of it, line endings included. */
+const DISCARDED = new RegExp(`[${SPACE}${BREAK}]+`, "uy");
+
+const UNICODE = /u\{([0-9A-Fa-f]{1,6})\}/uy;
+
+/** The escapes that stand for one character each. */
+const ESCAPES: ReadonlyMap<string, string> = new Map([
+  ['"', '"'],
+  ["\\", "\\"],
+  ["b", "\b"],
+  ["f", "\f"],
+  ["n", "\n"],
+  ["r", "\r"],
+  ["s", " "],
+  ["t", "\t"],
+]);
+
+/** The escape whose backslash is at `at`, or null when it is not one this reads. */
+function readEscape(source: string, at: number, to: number): StringPiece | null {
+  const simple = ESCAPES.get(source.charAt(at + 1));
+  if (simple !== undefined) {
+    return { end: at + 2, start: at, text: simple, verbatim: false };
+  }
+  UNICODE.lastIndex = at + 1;
+  const unicode = UNICODE.exec(source);
+  if (unicode) {
+    const point = Number.parseInt(unicode[1] ?? "", 16);
+    // A surrogate is not a character, and KDL refuses one, so the parser never got this far.
+    return point > 0x10_ff_ff || (point >= 0xd8_00 && point <= 0xdf_ff)
+      ? null
+      : { end: UNICODE.lastIndex, start: at, text: String.fromCodePoint(point), verbatim: false };
+  }
+  DISCARDED.lastIndex = at + 1;
+  /* Whitespace cannot run past a closing quote, so the one way this passes `to` is from inside a
+     line of a multi-line string, where it joins two lines and the line structure is not ours. */
+  return DISCARDED.test(source) && DISCARDED.lastIndex <= to
+    ? { end: DISCARDED.lastIndex, start: at, text: "", verbatim: false }
+    : null;
+}
+
+/** The pieces of a stretch that holds no line structure. False when something in it is not read. */
+function readRun(
+  source: string,
+  from: number,
+  to: number,
+  escapes: boolean,
+  out: StringPiece[],
+): boolean {
+  let at = from;
+  while (at < to) {
+    const slash = escapes ? source.indexOf("\\", at) : -1;
+    const stop = slash === -1 || slash >= to ? to : slash;
+    if (stop > at) {
+      out.push({ end: stop, start: at, text: source.slice(at, stop), verbatim: true });
+    }
+    if (stop === to) {
+      break;
+    }
+    const escape = readEscape(source, stop, to);
+    if (!escape) {
+      return false;
+    }
+    out.push(escape);
+    at = escape.end;
+  }
+  return true;
+}
+
+/** The lines of a stretch, each with where the next starts. */
+function linesOf(source: string, from: number, to: number): Line[] {
+  const lines: Line[] = [];
+  let start = from;
+  NEWLINE.lastIndex = from;
+  for (;;) {
+    const match = NEWLINE.exec(source);
+    if (!match || match.index >= to) {
+      lines.push({ end: to, next: to, start });
+      return lines;
+    }
+    const next = match.index + match[0].length;
+    lines.push({ end: match.index, next, start });
+    start = next;
+  }
+}
+
+/**
+ * The pieces of a multi-line string: its lines without the indentation of the closing line, joined
+ * by `\n` whatever the file's line endings are. False when its shape is not the one this reads.
+ */
+function readLines(
+  source: string,
+  from: number,
+  to: number,
+  escapes: boolean,
+  out: StringPiece[],
+): boolean {
+  const lines = linesOf(source, from, to);
+  const [first] = lines;
+  const last = lines.at(-1);
+  if (!first || !last || lines.length < 2 || first.end !== first.start) {
+    return false;
+  }
+  const prefix = source.slice(last.start, last.end);
+  if (!BLANK.test(prefix)) {
+    return false;
+  }
+  const content = lines.slice(1, -1);
+  for (const [index, line] of content.entries()) {
+    const written = source.slice(line.start, line.end);
+    const read =
+      BLANK.test(written) ||
+      (written.startsWith(prefix) &&
+        readRun(source, line.start + prefix.length, line.end, escapes, out));
+    if (!read) {
+      return false;
+    }
+    if (index < content.length - 1) {
+      out.push({
+        end: line.next,
+        start: line.end,
+        text: "\n",
+        verbatim: source.slice(line.end, line.next) === "\n",
+      });
+    }
+  }
+  return true;
+}
+
+/** The pieces of a token as this reads it, unchecked. Null when it is not a string this reads. */
+function scan(source: string, span: JxnSpan): StringPiece[] | null {
+  let open = span.start;
+  while (source.charAt(open) === "#") {
+    open += 1;
+  }
+  const hashes = open - span.start;
+  if (source.charAt(open) !== '"') {
+    // A bare word is its own value. With hashes and no quote it is a keyword, and not a string.
+    return hashes === 0
+      ? [
+          {
+            end: span.end,
+            start: span.start,
+            text: source.slice(span.start, span.end),
+            verbatim: true,
+          },
+        ]
+      : null;
+  }
+  const multiline = source.startsWith('"""', open);
+  const quotes = multiline ? 3 : 1;
+  const from = open + quotes;
+  const to = span.end - quotes - hashes;
+  if (to < from || source.slice(to, span.end) !== '"'.repeat(quotes) + "#".repeat(hashes)) {
+    return null;
+  }
+  const out: StringPiece[] = [];
+  const read = multiline ? readLines : readRun;
+  return read(source, from, to, hashes === 0, out) ? out : null;
+}
+
+/** Join the runs that are one stretch of source, and drop the ones that hold nothing. */
+function joined(pieces: readonly StringPiece[]): StringPiece[] {
+  const out: StringPiece[] = [];
+  for (const piece of pieces) {
+    const before = out.at(-1);
+    if (piece.text === "") {
+      continue;
+    }
+    if (before?.verbatim && piece.verbatim && before.end === piece.start) {
+      before.end = piece.end;
+      before.text += piece.text;
+    } else {
+      out.push({ ...piece });
+    }
+  }
+  return out;
+}
+
+/**
+ * The runs of a string's value, in order, each beside the source it was written as.
+ *
+ * @param source The file.
+ * @param span The string's token: a bare word, or everything from its first `#` or quote to its
+ *   last.
+ * @param value What the parser read the token as.
+ * @returns Runs whose text spells `value`. An empty value has none.
+ */
+export function stringPieces(source: string, span: JxnSpan, value: string): StringPiece[] {
+  const pieces = scan(source, span);
+  if (pieces && pieces.map((piece) => piece.text).join("") === value) {
+    return joined(pieces);
+  }
+  return joined([{ end: span.end, start: span.start, text: value, verbatim: false }]);
+}