@weborigami/language 0.6.9 → 0.6.10

package/src/handlers/js_handler.js

@@ -12,7 +12,7 @@ export default {
     const { key, parent } = options;
     if (!(parent && "import" in parent)) {
       throw new TypeError(
-        "The parent tree must support importing modules to unpack JavaScript files."
+        "The parent tree must support importing modules to unpack JavaScript files.",
       );
     }
 
@@ -35,8 +35,8 @@ export default {
 };
 
 // If the value is a function, bind it to the parent so that the function can,
-// e.g., find local files. Note: evaluate() supports a related but separate
-// mechanism called `containerAsTarget`. We want to use binding here so that, if
+// e.g., find local files. Note: execute() supports a related but separate
+// mechanism called `parentAsTarget`. We want to use binding here so that, if
 // a function is handed to another to be called later, it still has the correct
 // `this`.
 function bindToParent(value, parent) {

package/src/handlers/json_handler.js

@@ -12,9 +12,11 @@ export default {
   unpack(packed) {
     const json = toString(packed);
     if (!json) {
-      throw new Error("Tried to parse something as JSON but it wasn't text.");
+      throw new Error("JSON handler can only unpack text.");
     }
+
     const data = JSON.parse(json);
+
     if (data && typeof data === "object" && Object.isExtensible(data)) {
       Object.defineProperty(data, symbols.deep, {
         enumerable: false,

package/src/handlers/tsv_handler.js

@@ -7,7 +7,7 @@ export default {
     const parent = options.parent ?? null;
     const text = toString(packed);
     if (text === null) {
-      throw new TypeError(".tsv handler can only unpack text");
+      throw new TypeError("TSV handler can only unpack text.");
     }
     const data = tsvParse(text);
     // Define `parent` as non-enumerable property

package/src/handlers/yaml_handler.js

@@ -39,7 +39,7 @@ export default {
   async unpack(packed, options = {}) {
     const yaml = toString(packed);
     if (!yaml) {
-      throw new Error("Tried to parse something as YAML but it wasn't text.");
+      throw new Error("YAML handler can only unpack text.");
     }
     const parent = getParent(packed, options);
     const oriCallTag = await oriCallTagForParent(parent, options, yaml);

package/src/project/jsGlobals.js

@@ -162,7 +162,7 @@ Object.defineProperty(globals, "globalThis", {
 
 async function fetchWrapper(resource, options) {
   console.warn(
-    "Warning: A plain `fetch` reference will eventually call the standard JavaScript fetch() function. For Origami's fetch behavior, update your code to call Origami.fetch()."
+    "Warning: A plain `fetch` reference will eventually call the standard JavaScript fetch() function. For Origami's fetch behavior, update your code to call Origami.fetch().",
   );
   const response = await fetch(resource, options);
   return response.ok ? await response.arrayBuffer() : undefined;
@@ -182,12 +182,12 @@ async function importWrapper(modulePath, options = {}) {
   }
   if (!current) {
     throw new TypeError(
-      "Modules can only be imported from a folder or other object with a path property."
+      "Modules can only be imported from a folder or other object with a path property.",
     );
   }
   const filePath = path.resolve(current.path, modulePath);
   return import(filePath, options);
 }
-importWrapper.containerAsTarget = true;
+importWrapper.parentAsTarget = true;
 
 export default globals;

package/src/protocols/package.js

@@ -27,11 +27,11 @@ export default async function packageProtocol(...args) {
 
   // Identify the main entry point
   const mainPath = await Tree.traverse(packageRoot, "package.json", "main");
-  if (!mainPath) {
+  if (mainPath === undefined) {
     throw new Error(
       `${packageRootPath.join(
-        "/"
-      )} doesn't contain a package.json with a "main" entry.`
+        "/",
+      )} doesn't contain a package.json with a "main" entry.`,
     );
   }
 

package/src/runtime/asyncStorage.js

@@ -0,0 +1,7 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * Storage maintained by the execute() function and accessible to async
+ * functions called during evaluation.
+ */
+export default new AsyncLocalStorage();

package/src/runtime/codeFragment.js

@@ -1,11 +1,12 @@
 export default function codeFragment(location) {
   const { source, start, end } = location;
+  const sourceText = source.text ?? source;
 
   let fragment =
-    start.offset < end.offset
-      ? source.text.slice(start.offset, end.offset)
+    start && end && start.offset < end.offset
+      ? sourceText.slice(start.offset, end.offset)
       : // Use entire source
-        source.text;
+        sourceText;
 
   // Replace newlines and whitespace runs with a single space.
   fragment = fragment.replace(/(\n|\s\s+)+/g, " ");

package/src/runtime/errors.js

@@ -1,148 +1,111 @@
-// Text we look for in an error stack to guess whether a given line represents a
-
-import {
-  box,
-  trailingSlash,
-  TraverseError,
-  Tree,
-} from "@weborigami/async-tree";
+import { TraverseError } from "@weborigami/async-tree";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import codeFragment from "./codeFragment.js";
-import * as symbols from "./symbols.js";
-import { typos } from "./typos.js";
+import explainReferenceError from "./explainReferenceError.js";
+import explainTraverseError from "./explainTraverseError.js";
 
+// Text we look for in an error stack to guess whether a given line represents a
 // function in the Origami source code.
 const origamiSourceSignals = [
   "async-tree/src/",
   "language/src/",
   "origami/src/",
-  "at Scope.evaluate",
+  "at Scope.execute",
 ];
 
-const displayedWarnings = new Set();
-
-export function attachWarning(value, message) {
-  if (value == null) {
-    return value;
-  }
-
-  if (typeof value === "object" && value?.[symbols.warningSymbol]) {
-    // Already has a warning, don't overwrite it
-    return value;
-  }
-
-  const boxed = box(value);
-  boxed[symbols.warningSymbol] = message;
-  return boxed;
-}
-
-export async function builtinReferenceError(tree, builtins, key) {
-  // See if the key is in scope (but not as a builtin)
-  const scope = await Tree.scope(tree);
-  const value = await scope.get(key);
-  let message;
-  if (value === undefined) {
-    const messages = [
-      `"${key}" is being called as if it were a builtin function, but it's not.`,
-    ];
-    const typos = await formatScopeTypos(builtins, key);
-    messages.push(typos);
-    message = messages.join(" ");
-  } else {
-    const messages = [
-      `To call a function like "${key}" that's not a builtin, include a slash: ${key}/( )`,
-      `Details: https://weborigami.org/language/syntax.html#shorthand-for-builtin-functions`,
-    ];
-    message = messages.join("\n");
-  }
-  return new ReferenceError(message);
-}
-
-// Display a warning message in the console, but only once for each unique
-// message and location.
-export function displayWarning(message, location) {
-  const warning = "Warning: " + message + lineInfo(location);
-  if (!displayedWarnings.has(warning)) {
-    displayedWarnings.add(warning);
-    console.warn(warning);
-  }
-}
-
 /**
  * Format an error for display in the console.
  *
  * @param {Error} error
  */
-export function formatError(error) {
-  let message;
-
-  let location = /** @type {any} */ (error).location;
-  const fragment = location ? codeFragment(location) : null;
-  let fragmentInMessage = false;
-
-  if (error.stack) {
-    // Display the stack only until we reach the Origami source code.
-    message = "";
-    let lines = error.stack.split("\n");
-    for (let i = 0; i < lines.length; i++) {
-      let line = lines[i];
-      if (maybeOrigamiSourceCode(line)) {
-        break;
-      }
-      if (
-        error instanceof TraverseError &&
-        error.message === "A null or undefined value can't be traversed"
-      ) {
-        // Provide more meaningful message for TraverseError
-        line = `TraverseError: This part of the path is null or undefined: ${highlightError(
-          fragment
-        )}`;
-        fragmentInMessage = true;
+export async function formatError(error) {
+  // Get the original error message
+  let originalMessage;
+  // If the first line of the stack is just the error message, use that as the message
+  let lines = error.stack?.split("\n") ?? [];
+  if (!lines[0].startsWith("    at")) {
+    originalMessage = lines[0];
+    lines.shift();
+  } else {
+    originalMessage = error.message ?? error.toString();
+  }
+  let message = originalMessage;
+
+  // See if we can identify the Origami location that caused the error
+  let location;
+  const context = /** @type {any} */ (error).context;
+  let code = context?.code;
+  if (code) {
+    // Use the code being evaluated when the error occurred
+    let position = /** @type {any} */ (error).position;
+    const argCode =
+      position !== undefined ? context.code[position] : context.code;
+    if (argCode instanceof Array) {
+      code = argCode;
+      location = /** @type {any} */ (argCode).location;
+    }
+  }
+  const fragment = location ? codeFragment(location) : (code?.source ?? code);
+
+  // See if we can explain the error message
+  try {
+    if (error instanceof ReferenceError && code && context) {
+      const explanation = await explainReferenceError(code, context.state);
+      if (explanation) {
+        message += "\n" + explanation;
       }
-      if (message) {
-        message += "\n";
+    } else if (error instanceof TraverseError) {
+      const explanation = await explainTraverseError(error);
+      if (explanation) {
+        message += "\n" + explanation;
       }
-      message += line;
     }
-  } else {
-    message = error.toString();
+  } catch (internalError) {
+    // Ignore; won't modify the message
+  }
+
+  // If the error's `message` starts with a qualified method name like `Tree.map`
+  // and a colon, extract the method name and link to the docs.
+  const match = error.message?.match(/^(?<namespace>\w+).(?<method>\w+):/);
+  if (match) {
+    /** @type {any} */
+    const { namespace, method } = match.groups;
+    if (["Dev", "Origami", "Tree"].includes(namespace)) {
+      message += `\nFor documentation, see https://weborigami.org/builtins/${namespace}/${method}`;
+    }
   }
 
+  // If the error has a stack trace, only include the portion until we reach
+  // Origami source code.
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (maybeOrigamiSourceCode(line)) {
+      break;
+    }
+    message += "\n" + line;
+  }
+
+  message += `\nevaluating: ${highlightError(fragment)}`;
+
   // Add location
   if (location) {
-    if (!fragmentInMessage) {
-      message += `\nevaluating: ${highlightError(fragment)}`;
+    const lineInformation = lineInfo(location);
+    if (lineInformation) {
+      message += "\n" + lineInformation;
     }
-    message += lineInfo(location);
   }
 
   return message;
 }
 
-export async function formatScopeTypos(scope, key) {
-  const keys = await scopeTypos(scope, key);
-  // Don't match deprecated keys
-  const filtered = keys.filter((key) => !key.startsWith("@"));
-  if (filtered.length === 0) {
-    return "";
-  }
-  const quoted = filtered.map((key) => `"${key}"`);
-  const list = quoted.join(", ");
-  return `Maybe you meant ${list}?`;
-}
-
 export function highlightError(text) {
   // ANSI escape sequence to highlight text in red
   return `\x1b[31m${text}\x1b[0m`;
 }
 
-export function maybeOrigamiSourceCode(text) {
-  return origamiSourceSignals.some((signal) => text.includes(signal));
-}
-
 // Return user-friendly line information for the error location
-function lineInfo(location) {
+export function lineInfo(location) {
   let { source, start } = location;
 
   let line;
@@ -162,7 +125,10 @@ function lineInfo(location) {
   }
 
   if (typeof source === "object" && source.url) {
-    const { url } = source;
+    let { url } = source;
+    if (typeof url === "string") {
+      url = new URL(url);
+    }
     let fileRef;
     // If URL is a file: URL, change to a relative path
     if (url.protocol === "file:") {
@@ -175,28 +141,15 @@ function lineInfo(location) {
       // Not a file: URL, use as is
       fileRef = url.href;
     }
-    return `\n    at ${fileRef}:${line}:${column}`;
+    return `    at ${fileRef}:${line}:${column}`;
   } else if (source.text.includes("\n")) {
     // Don't know the URL, but has multiple lines so add line number
-    return `\n    at line ${line}, column ${column}`;
+    return `    at line ${line}, column ${column}`;
   } else {
-    return "";
+    return null;
   }
 }
 
-export async function scopeReferenceError(scope, key) {
-  const messages = [
-    `"${key}" is not in scope or is undefined.`,
-    await formatScopeTypos(scope, key),
-  ];
-  const message = messages.join(" ");
-  return new ReferenceError(message);
-}
-
-// Return all possible typos for `key` in scope
-async function scopeTypos(scope, key) {
-  const scopeKeys = [...(await scope.keys())];
-  const normalizedScopeKeys = scopeKeys.map((key) => trailingSlash.remove(key));
-  const normalizedKey = trailingSlash.remove(key);
-  return typos(normalizedKey, normalizedScopeKeys);
+export function maybeOrigamiSourceCode(text) {
+  return origamiSourceSignals.some((signal) => text.includes(signal));
 }

package/src/runtime/evaluate.js

@@ -1,83 +1,14 @@
-import { Tree, isUnpackable } from "@weborigami/async-tree";
-import codeFragment from "./codeFragment.js";
-import { displayWarning } from "./errors.js";
-import * as symbols from "./symbols.js";
+import * as compile from "../compiler/compile.js";
 
 /**
- * Evaluate the given code and return the result.
+ * Compile the given source code and evaluate it.
  *
- * `this` should be the tree used as the context for the evaluation.
- *
- * @param {import("../../index.ts").AnnotatedCode} code
- * @param {import("../../index.ts").RuntimeState} [state]
+ * @typedef {import("../../index.ts").Source} Source
+ * @param {Source|string} source
+ * @param {any} [options]
  */
-export default async function evaluate(code, state = {}) {
-  if (!(code instanceof Array)) {
-    // Simple scalar; return as is.
-    return code;
-  }
-
-  let evaluated;
-  if (code[0]?.unevaluatedArgs) {
-    // Don't evaluate instructions, use as is.
-    evaluated = code;
-  } else {
-    // Evaluate each instruction in the code.
-    evaluated = await Promise.all(
-      code.map((instruction) => evaluate(instruction, state)),
-    );
-  }
-
-  // The head of the array is a function or a tree; the rest are args or keys.
-  let [fn, ...args] = evaluated;
-
-  if (!fn) {
-    // The code wants to invoke something that's couldn't be found in scope.
-    const error = ReferenceError(
-      `${codeFragment(code[0].location)} is not defined`,
-    );
-    /** @type {any} */ (error).location = code[0].location;
-    throw error;
-  }
-
-  if (isUnpackable(fn)) {
-    // Unpack the object and use the result as the function or tree.
-    fn = await fn.unpack();
-  }
-
-  if (fn.needsState) {
-    // The function is an op that wants the runtime state
-    args.push(state);
-  } else if (fn.containerAsTarget && state.parent) {
-    // The function wants the code's container as the `this` target
-    fn = fn.bind(state.parent);
-  }
-
-  // Execute the function or traverse the tree.
-  let result;
-  try {
-    result =
-      fn instanceof Function
-        ? await fn(...args) // Invoke the function
-        : await Tree.traverseOrThrow(fn, ...args); // Traverse the tree.
-  } catch (/** @type {any} */ error) {
-    if (!error.location) {
-      // Attach the location of the code we tried to evaluate.
-      error.location =
-        error.position !== undefined && code[error.position + 1]?.location
-          ? // Use location of the argument with the given position (need to
-            // offset by 1 to skip the function).
-            code[error.position + 1]?.location
-          : // Use overall location.
-            code.location;
-    }
-    throw error;
-  }
-
-  if (result?.[symbols.warningSymbol]) {
-    displayWarning(result[symbols.warningSymbol], code.location);
-    delete result[symbols.warningSymbol];
-  }
-
+export default async function evaluate(source, options = {}) {
+  const fn = compile.expression(source, options);
+  const result = await fn();
   return result;
 }

package/src/runtime/execute.js

@@ -0,0 +1,82 @@
+import { isUnpackable, Tree } from "@weborigami/async-tree";
+import asyncStorage from "./asyncStorage.js";
+import "./interop.js";
+
+/**
+ * Execute the given code and return the result.
+ *
+ * `this` should be the map used as the context for the evaluation.
+ *
+ * @typedef {import("../../index.ts").AnnotatedCode} AnnotatedCode
+ * @typedef {import("../../index.ts").RuntimeState} RuntimeState
+ *
+ * @param {AnnotatedCode} code
+ * @param {RuntimeState} [state]
+ */
+export default async function execute(code, state = {}) {
+  if (!(code instanceof Array)) {
+    // Simple scalar; return as is.
+    return code;
+  }
+
+  let evaluated;
+  if (code[0]?.unevaluatedArgs) {
+    // Don't evaluate instructions, use as is.
+    evaluated = code;
+  } else {
+    // Evaluate each instruction in the code.
+    evaluated = await Promise.all(
+      code.map((instruction) => execute(instruction, state)),
+    );
+  }
+
+  // Add the code to the runtime state
+  /** @type {import("../../index.ts").CodeContext} */
+  const context = { state, code };
+
+  // The head of the array is a function or a map; the rest are args or keys.
+  let [fn, ...args] = evaluated;
+
+  if (!fn) {
+    // The code wants to invoke something that's couldn't be found in scope.
+    /** @type {any} */
+    const error = new ReferenceError(
+      "Couldn't find the function or map to execute.",
+    );
+    error.context = context; // For error formatting
+    error.position = 0; // Problem was at function position
+    throw error;
+  }
+
+  if (isUnpackable(fn)) {
+    // Unpack the object and use the result as the function or map.
+    fn = await fn.unpack();
+  }
+
+  if (fn.needsState) {
+    // The function is an op that wants the runtime state
+    args.push(state);
+  } else if (fn.parentAsTarget && state.parent) {
+    // The function wants the code's parent as the `this` target
+    fn = fn.bind(state.parent);
+  }
+
+  // Execute the function or traverse the map.
+  let result;
+  try {
+    result = await asyncStorage.run(
+      context,
+      async () =>
+        fn instanceof Function
+          ? await fn(...args) // Invoke the function
+          : await Tree.traverseOrThrow(fn, ...args), // Traverse the map.
+    );
+  } catch (/** @type {any} */ error) {
+    if (!error.context) {
+      error.context = context; // For error formatting
+    }
+    throw error;
+  }
+
+  return result;
+}