@jxsuite/schema 5.5.0 → 6.0.0

package/src/function-role.ts

@@ -0,0 +1,182 @@
+/**
+ * One verdict per `$prototype: "Function"` entry: is it a **computed** value, read reactively, or a
+ * **callable**, invoked by an event, a call site or the host?
+ *
+ * Every tier reads this one classifier (the interpreter's `buildScope`, both compiled targets and
+ * the build-time scope), so a document means the same thing in Studio and in production. It reads
+ * the document, never an imported function's arity or source: a compiler has only the document, and
+ * `fn.toString()` of a bundled import is not a stable input (spec.md §5.3 4b, 4d).
+ *
+ * @docs framework/concepts/functions
+ */
+import {
+  bodyReturnsValue,
+  hasStructuredBody,
+  isFunctionDef,
+  isJsonObject,
+  isRef,
+  isString,
+  paramNames,
+} from "./guards";
+import type { JsonValue, JxElement, JxFunctionDef } from "../types";
+
+/** What a Function entry is to the tiers that read it. */
+export type FunctionRole = "computed" | "callable";
+
+/** Lifecycle hooks the generated element calls itself, so they are never `$ref`'d (spec.md §16.4). */
+export const LIFECYCLE_KEYS: ReadonlySet<string> = new Set(["onMount", "onUnmount", "onAdopted"]);
+
+/**
+ * The state keys a document uses as a _callable_, at any depth: bound to an `on*` event (a
+ * definition's root-level handlers included, §16.1), invoked by an `$expression` `call` node
+ * (§19.4c), called as `state.key(…)` from a template string or another function's body, or named as
+ * a lifecycle hook (§16.4). `$defs` holds JSON Schema, not usage, and is skipped.
+ *
+ * Anything not used as a callable has its return value read reactively. Defaulting the other way
+ * round would turn a called helper into a value and break its call site.
+ */
+function collectCallableKeys(doc: JxElement): Set<string> {
+  const keys = new Set<string>();
+  const seen = new Set<object>();
+
+  const addStateRef = (ref: string): void => {
+    if (ref.startsWith("#/state/")) {
+      /* SAFETY: `String.prototype.split` always returns at least one element (the whole string
+         when the separator is absent), so index 0 is present. */
+      keys.add(ref.slice("#/state/".length).split("/")[0] as string);
+    }
+  };
+
+  const visit = (node: JsonValue | undefined): void => {
+    if (isString(node)) {
+      // `${state.formatDate(d)}` in a template, or `state.helper(x)` in another function's body.
+      for (const call of node.matchAll(/\bstate\.([A-Za-z_$][\w$]*)\s*\(/gu)) {
+        /* SAFETY: the pattern's one capture group is not optional, so every match fills index 1
+           with the called member's name. */
+        keys.add(call[1] as string);
+      }
+      return;
+    }
+    if (Array.isArray(node)) {
+      if (!seen.has(node)) {
+        seen.add(node);
+        for (const item of node) {
+          visit(item);
+        }
+      }
+      return;
+    }
+    if (!isJsonObject(node) || seen.has(node)) {
+      return;
+    }
+    seen.add(node);
+    // An `$expression` `call` node names its callee in `target` (spec.md §19.4c).
+    if (node.operator === "call" && isRef(node.target)) {
+      addStateRef(node.target.$ref);
+    }
+    for (const [key, value] of Object.entries(node)) {
+      if (key === "$defs") {
+        continue;
+      }
+      if (key.startsWith("on") && isRef(value)) {
+        addStateRef(value.$ref);
+      }
+      visit(value);
+    }
+  };
+
+  // SAFETY: a Jx element is JSON data; its type names what it holds.
+  visit(doc as JsonValue);
+  for (const hook of LIFECYCLE_KEYS) {
+    if (isJsonObject(doc.state) && hook in doc.state) {
+      keys.add(hook);
+    }
+  }
+  return keys;
+}
+
+/**
+ * Does a Function declaration name both a `body` and a `$src`? The two are mutually exclusive
+ * (spec.md §5.3 4d), and the test is presence, as the `FunctionDef` schema's `not` is, so an empty
+ * `body: ""` beside a `$src` is refused too and `jx validate` agrees with every tier.
+ *
+ * @param def A Function declaration, a `state` entry or a handler written inline on an `on*` key.
+ */
+export function declaresBodyAndSrc(def: JxFunctionDef): boolean {
+  return "body" in def && "$src" in def;
+}
+
+/**
+ * Does a Function declaration list any parameter of its own, by `parameters` or the legacy
+ * `arguments`? An inline handler that does not is rewritten to read `state` as the handler's alias,
+ * and one that does is built with {@link handlerParamNames}.
+ *
+ * @param def A Function declaration.
+ */
+export function declaresParameters(def: JxFunctionDef): boolean {
+  return paramNames(def.parameters ?? def.arguments).length > 0;
+}
+
+/**
+ * The formal parameters a string `body` is built with, in every tier (spec.md §5.3 4d): `state`
+ * first, then the other declared names in declared order. Binding is by position, as ECMAScript's
+ * is, so a name that is not `state` receives whatever the call site passes in that position. An
+ * event binding calls a handler `(state, event)`, so the first other name is the event and a later
+ * one is `undefined` from an event (a call with too few arguments), filled by a call site that
+ * passes it. A declared `state` is moved to the front rather than repeated, since a duplicate
+ * parameter is a sloppy-mode quirk in which the later one wins and `state` would be `undefined`.
+ *
+ * @param def A Function declaration, a `state` entry or a handler written inline on an `on*` key.
+ */
+export function handlerParamNames(def: JxFunctionDef): string[] {
+  const list = ["state"];
+  for (const name of paramNames(def.parameters ?? def.arguments)) {
+    if (name !== "state") {
+      list.push(name);
+    }
+  }
+  return list;
+}
+
+/** The rules in order: the first that applies decides. */
+function functionEntryRole(
+  key: string,
+  def: JxFunctionDef,
+  callableKeys: () => Set<string>,
+): FunctionRole {
+  if (hasStructuredBody(def)) {
+    return "callable";
+  }
+  // Declared parameters or arguments make an entry callable wherever it is used (§19.4c).
+  if (paramNames(def.parameters ?? def.arguments).length > 0) {
+    return "callable";
+  }
+  if (isString(def.body)) {
+    return bodyReturnsValue(def.body) ? "computed" : "callable";
+  }
+  if (def.$src) {
+    return callableKeys().has(key) ? "callable" : "computed";
+  }
+  return "callable";
+}
+
+/**
+ * Classify every Function entry in a document's `state`. Other state shapes get no verdict. The
+ * document is the one a tier builds, after the project-state merge, so a project-global entry one
+ * page calls and another only reads is a function on the first and a computed on the second.
+ *
+ * The walk for usage runs at most once, and only when a bodyless `$src` entry reaches it.
+ *
+ * @param doc The document (or just `{ state }`) being built.
+ */
+export function classifyFunctionEntries(doc: JxElement): Map<string, FunctionRole> {
+  const roles = new Map<string, FunctionRole>();
+  let callable: Set<string> | null = null;
+  const callableKeys = (): Set<string> => (callable ??= collectCallableKeys(doc));
+  for (const [key, def] of Object.entries(doc.state ?? {})) {
+    if (isFunctionDef(def)) {
+      roles.set(key, functionEntryRole(key, def, callableKeys));
+    }
+  }
+  return roles;
+}

package/src/guards.ts

@@ -245,6 +245,17 @@ export function bodyReturnsValue(body: string): boolean {
   return /\breturn\b[^\S\n]*(?![;}\s]|$)/.test(maskCode(body));
 }
 
+/**
+ * Whether an object is a function entry, whose `body` is code (`spec.md` §23.1): a `Function`
+ * entry, or a class member, which a `.class.json` names by its `role` alone. A field is a member
+ * with no body. Any other `body` may be data, so it is never read as code.
+ *
+ * @param value An object in a document or class definition.
+ */
+export function isFunctionEntry(value: JsonObject): boolean {
+  return value.$prototype === "Function" || (isString(value.role) && value.role !== "field");
+}
+
 /**
  * A function body with its comments and the contents of its strings blanked, so a pattern reads
  * only code (`spec.md` §23.1). The result is the same length, every newline kept, so an offset in
@@ -282,8 +293,152 @@ export function maskCode(body: string): string {
 const masked = new Map<string, string>();
 const MASKED_LIMIT = 2048;
 
-/** The scan {@link maskCode} caches. */
-function scanCode(body: string): string {
+/**
+ * One `${…}` of a template string: `start` is the offset of its `$`, `end` is one past its closing
+ * `}`, and `expr` is the expression between the braces, exactly as written.
+ */
+export interface TemplateExpression {
+  readonly start: number;
+  readonly end: number;
+  readonly expr: string;
+}
+
+/**
+ * Each top-level `${…}` of a template string (`spec.md` §8.4), in order.
+ *
+ * A template string is the inside of a JavaScript template literal, and its expressions are code,
+ * so where one ends is a question about code: a `}` inside a string, a comment, an object literal
+ * or a nested template literal does not close it. This is the {@link maskCode} scan started inside
+ * a template, so every reader of a template agrees with the engine that evaluates it. A pattern
+ * such as `[^}]+` cuts `${f(x, { a: 1 })}` at the object's brace, and a brace count alone ends `${a
+ * ? "}" : ""}` inside the string.
+ *
+ * Two things this scan does that {@link maskCode} does not, because an expression is short and the
+ * cost of misreading one is a binding shown or stored wrong:
+ *
+ * - A regular expression literal is recognised where an operand may start, so a quote or a brace
+ *   inside `/"/g` is not read as code.
+ * - An expression the scan cannot close (an unterminated string) is closed by brace depth instead,
+ *   and one with no closing brace at all is not reported: its `${` is literal text, and the scan
+ *   goes on after it, so a complete expression later in the string is still found.
+ *
+ * The result is shared and must not be changed.
+ *
+ * @param template The template string, without the backticks of a literal.
+ */
+export function templateExpressions(template: string): readonly TemplateExpression[] {
+  if (!template.includes("${")) {
+    return NO_EXPRESSIONS;
+  }
+  const known = scanned.get(template);
+  if (known !== undefined) {
+    return known;
+  }
+  const found: TemplateExpression[] = [];
+  let from = 0;
+  while (from < template.length) {
+    const spans: number[] = [];
+    scanCode(template.slice(from), spans);
+    let unclosed = -1;
+    for (let i = 0; i < spans.length; i += 2) {
+      const start = from + (spans[i] ?? 0);
+      const end = spans[i + 1] ?? -1;
+      if (end === -1) {
+        unclosed = start;
+        break;
+      }
+      found.push(expressionAt(template, start, from + end));
+    }
+    if (unclosed === -1) {
+      break;
+    }
+    // The scan lost its place (a quote it could not pair): brace depth closes this one expression.
+    const end = closeByBraceDepth(template, unclosed);
+    if (end === -1) {
+      // Never closed, so this `${` is text; a complete expression may still follow it.
+      from = unclosed + 2;
+    } else {
+      found.push(expressionAt(template, unclosed, end));
+      from = end;
+    }
+  }
+  if (scanned.size >= MASKED_LIMIT) {
+    scanned.clear();
+  }
+  scanned.set(template, found);
+  return found;
+}
+
+const NO_EXPRESSIONS: readonly TemplateExpression[] = [];
+
+/** Templates already scanned: a renderer asks about the same template on every evaluation. */
+const scanned = new Map<string, readonly TemplateExpression[]>();
+
+function expressionAt(template: string, start: number, end: number): TemplateExpression {
+  return { end, expr: template.slice(start + 2, end - 1), start };
+}
+
+/** One past the `}` that balances the `${` at `start` by brace depth alone, or -1 for none. */
+function closeByBraceDepth(template: string, start: number): number {
+  let depth = 0;
+  for (let at = start + 1; at < template.length; at += 1) {
+    const char = template.charAt(at);
+    if (char === "{") {
+      depth += 1;
+    } else if (char === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        return at + 1;
+      }
+    }
+  }
+  return -1;
+}
+
+/** The characters after which a `/` starts a regular expression literal, not a division. */
+const BEFORE_OPERAND = new Set("(,=:[!&|?{;+-*%<>~^");
+
+/**
+ * Whether `before`, the operator character read at `at`, is the second half of `++` or `--`. A `/`
+ * after one of those divides (`a++ / 2`): read as a regular expression it ran to the next `/` on
+ * the line, which in `"${a++ / 2} and ${b / 3}"` is in the NEXT expression, and the two were
+ * reported as one.
+ */
+function endsUpdateOperator(body: string, before: string, at: number): boolean {
+  return (before === "+" || before === "-") && body.charAt(at - 1) === before;
+}
+
+/**
+ * One past the end of the regular expression literal opening at `at`, or -1 when the `/` there is
+ * not one: it does not close on its line. A `/` inside a character class does not close it.
+ */
+function regexLiteralEnd(body: string, at: number): number {
+  let inClass = false;
+  for (let i = at + 1; i < body.length; i += 1) {
+    const char = body.charAt(i);
+    if (char === "\n") {
+      return -1;
+    }
+    if (char === "\\") {
+      i += 1;
+    } else if (char === "[") {
+      inClass = true;
+    } else if (char === "]") {
+      inClass = false;
+    } else if (char === "/" && !inClass) {
+      return i + 1;
+    }
+  }
+  return -1;
+}
+
+/**
+ * The scan {@link maskCode} caches. With `spans` it reads `body` as a template string instead of
+ * code (it starts inside the template), recognises regular expression literals, and records each
+ * top-level substitution for {@link templateExpressions} as a pair of offsets: its `$`, then one
+ * past its `}`, which is -1 while it is still open.
+ */
+function scanCode(body: string, spans?: number[]): string {
   /* UTF-16 units, as `at` counts them. Code points (`[...body]`) made an astral character in a
      string one element for two offsets, so the result came back short and every offset after it,
      which is what a caller splices the body at, was off by one. */
@@ -295,7 +450,11 @@ function scanCode(body: string): string {
   };
   /** The brace depth of each template substitution still open, innermost last. */
   const substitutions: number[] = [];
-  let inTemplate = false;
+  let inTemplate = spans !== undefined;
+  /** The last character of code read that is not white space: what a `/` follows. */
+  let before = "";
+  /** Where `before` was read, when it is an operator or part of a name; stale otherwise. */
+  let beforeAt = -1;
   let at = 0;
   while (at < body.length) {
     const char = body.charAt(at);
@@ -304,12 +463,18 @@ function scanCode(body: string): string {
         blank(at);
         blank(at + 1);
         at += 2;
-      } else if (char === "`") {
+      } else if (char === "`" && !(spans && substitutions.length === 0)) {
+        // A template STRING has no closing backtick: one in its own text is text.
         inTemplate = false;
+        before = char;
         at += 1;
       } else if (char === "$" && body.charAt(at + 1) === "{") {
+        if (substitutions.length === 0) {
+          spans?.push(at, -1);
+        }
         substitutions.push(0);
         inTemplate = false;
+        before = "{";
         at += 2;
       } else {
         blank(at);
@@ -336,10 +501,24 @@ function scanCode(body: string): string {
         blank(at);
         at += 1;
       }
+      before = char;
       at += 1;
     } else if (char === "`") {
       inTemplate = true;
       at += 1;
+    } else if (
+      spans &&
+      char === "/" &&
+      BEFORE_OPERAND.has(before) &&
+      !endsUpdateOperator(body, before, beforeAt) &&
+      regexLiteralEnd(body, at) > 0
+    ) {
+      const stop = regexLiteralEnd(body, at);
+      for (at += 1; at < stop - 1; at += 1) {
+        blank(at);
+      }
+      before = "/";
+      at = stop;
     } else {
       const open = substitutions.length - 1;
       if (open >= 0 && char === "{") {
@@ -348,10 +527,17 @@ function scanCode(body: string): string {
         if (substitutions[open] === 0) {
           substitutions.pop();
           inTemplate = true;
+          if (spans && substitutions.length === 0) {
+            spans[spans.length - 1] = at + 1;
+          }
         } else {
           substitutions[open] = (substitutions[open] ?? 1) - 1;
         }
       }
+      if (char.trim() !== "") {
+        before = char;
+        beforeAt = at;
+      }
       at += 1;
     }
   }