@weborigami/language 0.6.9 → 0.6.11

package/src/runtime/explainReferenceError.js

@@ -0,0 +1,248 @@
+import {
+  pathFromKeys,
+  scope,
+  trailingSlash,
+  Tree,
+} from "@weborigami/async-tree";
+import { ops } from "./internal.js";
+import { typos } from "./typos.js";
+
+// Doesn't include `/` because that would have been handled as a path separator
+const binaryOperatorRegex =
+  /!==|!=|%|&&|&|\*\*|\*|\+|-|\/|<<|<|<=|===|==|>>>|>>|>=|>|\^|\|\||\|/g;
+
+/**
+ * Try to provide a more helpful message for a ReferenceError by analyzing the
+ * code and suggesting possible typos.
+ *
+ * @param {import("../../index.ts").AnnotatedCode} code
+ * @param {import("../../index.ts").RuntimeState} state
+ */
+export default async function explainReferenceError(code, state) {
+  if (!state) {
+    return null;
+  }
+
+  const stateKeys = await getStateKeys(state);
+
+  if (code[0] === ops.property) {
+    // An inner property access returned undefined.
+    // Might be a global+extension or local+extension.
+    const explanation = await accidentalReferenceExplainer(
+      code.source,
+      stateKeys,
+    );
+    return explanation;
+  }
+
+  // See if the code looks like an external scope reference that failed
+  let key;
+  if (code[0] === ops.cache) {
+    // External scope reference
+    const scopeCall = code[3].slice(1); // drop the ops.scope
+    const keys = scopeCall.map((part) => part[1]);
+    const path = pathFromKeys(keys);
+
+    if (keys.length > 1) {
+      return `This path returned undefined: ${path}`;
+    }
+    key = keys[0];
+  } else if (code[0]?.[0] === ops.scope) {
+    // Simple scope reference
+    key = code[1][1];
+  } else {
+    // Generic reference error, can't offer help
+    return null;
+  }
+
+  key = trailingSlash.remove(key);
+  if (typeof key !== "string") {
+    return null;
+  }
+
+  // Common case of a single key
+  let message = `"${key}" is not in scope.`;
+
+  const explainers = [
+    mathExplainer,
+    qualifiedReferenceExplainer,
+    typoExplainer,
+  ];
+  let explanation;
+  for (const explainer of explainers) {
+    explanation = await explainer(key, stateKeys);
+    if (explanation) {
+      message += "\n" + explanation;
+      break;
+    }
+  }
+
+  return message;
+}
+
+/**
+ * Handle a reference that worked but maybe shouldn't have:
+ *
+ * - a global + extension like `performance.html` (`performance` is a global)
+ * - a local + extension like `posts.md` (where `posts` is a local variable)
+ *
+ * In either case, suggest using angle brackets.
+ */
+async function accidentalReferenceExplainer(key, stateKeys) {
+  const parts = key.split(".");
+  if (parts.length !== 2) {
+    return null;
+  }
+
+  const extensionHandlers = stateKeys.global.filter((globalKey) =>
+    globalKey.endsWith("_handler"),
+  );
+  const extensions = extensionHandlers.map((handler) => handler.slice(0, -8));
+  if (!extensions.includes(parts[1])) {
+    return null;
+  }
+
+  if (stateKeys.global.includes(parts[0])) {
+    return `"${parts[0]}" is a global, but "${parts[1]}" looks like a file extension.
+If you intended to reference a file, use angle brackets: <${key}>`;
+  }
+
+  if (stateKeys.object.includes(parts[0])) {
+    return `"${key}" looks like a file reference, but is matching the local object property "${parts[0]}".
+If you intended to reference a file, use angle brackets: <${key}>`;
+  }
+
+  if (stateKeys.stack.includes(parts[0])) {
+    return `"${key}" looks like a file reference, but is matching the local parameter "${parts[0]}".
+If you intended to reference a file, use angle brackets: <${key}>`;
+  }
+
+  return null;
+}
+
+// Return global, local, and object keys in scope for the given state
+async function getStateKeys(state) {
+  const { globals, parent, object, stack } = state;
+  const objectScope = object ? await scope(object) : null;
+  const parentScope = parent ? await scope(parent) : null;
+
+  const globalKeys = globals ? Object.keys(globals) : [];
+  const objectKeys = objectScope ? await Tree.keys(objectScope) : [];
+  const scopeKeys = parentScope ? await Tree.keys(parentScope) : [];
+  const stackKeys = stack?.map((frame) => Object.keys(frame)).flat() ?? [];
+
+  const qualifiedGlobal = [];
+  for (const globalKey of globalKeys) {
+    // Heuristic namespace test: name starts with capital, prototype is null (an
+    // exotic `Module` instance)
+    let global = globals[globalKey];
+    if (
+      /^[A-Z]/.test(globalKey) &&
+      global &&
+      Object.getPrototypeOf(global) === null
+    ) {
+      for (const [key, value] of Object.entries(global)) {
+        if (typeof value === "function") {
+          qualifiedGlobal.push(`${globalKey}.${key}`);
+        }
+      }
+    }
+  }
+
+  const normalizedGlobalKeys = globalKeys.map((key) =>
+    trailingSlash.remove(key),
+  );
+  const normalizedObjectKeys = objectKeys.map((key) =>
+    trailingSlash.remove(key),
+  );
+  const normalizedScopeKeys = scopeKeys.map((key) => trailingSlash.remove(key));
+  const normalizedStackKeys = stackKeys.map((key) => trailingSlash.remove(key));
+
+  return {
+    global: normalizedGlobalKeys,
+    object: normalizedObjectKeys,
+    qualifiedGlobal,
+    scope: normalizedScopeKeys,
+    stack: normalizedStackKeys,
+  };
+}
+
+/**
+ * If it looks like a math operation, suggest adding spaces around the operator.
+ */
+function mathExplainer(key, stateKeys) {
+  if (!binaryOperatorRegex.test(key)) {
+    return null;
+  }
+
+  // Create a global version of the regex for replacing all operators
+  const withSpaces = key.replace(binaryOperatorRegex, " $& ");
+  return `If you intended a math operation, Origami requires spaces around the operator: "${withSpaces}"`;
+}
+
+/**
+ * If the key is an unqualified reference (`repeat`), but there's a qualified
+ * version in scope (`Origami.repeat`), suggest that.
+ */
+async function qualifiedReferenceExplainer(key, stateKeys) {
+  if (key.includes(".")) {
+    return null;
+  }
+
+  const qualifiedKeys = stateKeys.qualifiedGlobal.filter((k) =>
+    k.endsWith("." + key),
+  );
+
+  if (qualifiedKeys.length === 0) {
+    return null;
+  }
+
+  let message = `Perhaps you intended`;
+  const list = qualifiedKeys.join(", ");
+  if (qualifiedKeys.length > 1) {
+    message += " one of these";
+  }
+  message += `: ${list}`;
+
+  return message;
+}
+
+/**
+ * Suggest possible typos for the given key based on the keys in scope.
+ */
+async function typoExplainer(key, stateKeys) {
+  const allKeys = [
+    ...new Set([
+      ...stateKeys.global,
+      ...stateKeys.object,
+      ...stateKeys.scope,
+      ...stateKeys.stack,
+    ]),
+  ];
+
+  let firstPartTypos;
+  if (key.includes(".")) {
+    // Split off first part
+    const [firstPart] = key.split(".");
+    firstPartTypos = typos(firstPart, allKeys);
+  } else {
+    firstPartTypos = [];
+  }
+
+  const fullTypos = typos(key, allKeys);
+  const allTypos = [...new Set([...firstPartTypos, ...fullTypos])];
+  allTypos.sort();
+
+  if (allTypos.length === 0) {
+    return null;
+  }
+
+  let message = `Perhaps you intended`;
+  const list = allTypos.join(", ");
+  if (allTypos.length > 1) {
+    message += " one of these";
+  }
+  message += `: ${list}`;
+
+  return message;
+}

package/src/runtime/explainTraverseError.js

@@ -0,0 +1,77 @@
+import {
+  extension,
+  isPacked,
+  pathFromKeys,
+  trailingSlash,
+  TraverseError,
+  Tree,
+} from "@weborigami/async-tree";
+import { typos } from "./typos.js";
+
+/**
+ * Try to provide a more helpful message for a TraverseError by analyzing the
+ * code and suggesting possible typos.
+ *
+ * @param {TraverseError} error
+ */
+export default async function explainTraverseError(error) {
+  const { lastValue, keys, position } = error;
+  if (lastValue === undefined || keys === undefined || position === undefined) {
+    // Don't have sufficient information; shouldn't happen
+    return null;
+  }
+
+  if (position === 0) {
+    // Shouldn't happen; should have been a ReferenceError
+    return null;
+  }
+
+  // The key that caused the error is the one before the current position
+  const path = pathFromKeys(keys.slice(0, position));
+  let message = `The path traversal ended unexpectedly at: ${path}`;
+
+  const key = trailingSlash.remove(keys[position - 1]);
+
+  if (
+    error.message === "A path tried to unpack data that's already unpacked."
+  ) {
+    // Key ends in a slash but value isn't packed
+    message += `\nYou can drop the trailing slash and just use: ${key}`;
+  } else if (isPacked(lastValue) && typeof lastValue.unpack !== "function") {
+    // Missing an extension handler
+    const ext = extension.extname(key);
+    if (ext) {
+      message += `\nThe value couldn't be unpacked because no file extension handler is registered for "${ext}".`;
+    }
+  } else {
+    // Compare the requested key with the available keys
+    const lastValueKeys = await Tree.keys(lastValue);
+    const normalizedKeys = lastValueKeys.map(trailingSlash.remove);
+
+    const keyAsNumber = Number(key);
+    if (!isNaN(keyAsNumber)) {
+      // See if the string version of the key is present
+      if (lastValueKeys.includes(keyAsNumber)) {
+        const suggestedPath = `${pathFromKeys(keys.slice(0, position - 1))}(${keyAsNumber})`;
+        message += `\nSlash-separated keys are searched as strings. Here there's no string "${key}" key, but there is a number ${keyAsNumber} key.
+To get the value for that number key, use parentheses: ${suggestedPath}`;
+      }
+    } else {
+      // Suggest typos
+      const possibleTypos = typos(key, normalizedKeys);
+      if (possibleTypos.length > 0) {
+        message += "\nPerhaps you intended";
+        if (possibleTypos.length > 1) {
+          message += " one of these";
+        }
+        message += ": ";
+
+        const withLeadingSlashes =
+          position > 1 ? possibleTypos.map(trailingSlash.add) : possibleTypos;
+        message += withLeadingSlashes.join(", ");
+      }
+    }
+  }
+
+  return message;
+}

package/src/runtime/expressionFunction.js

@@ -1,16 +1,17 @@
-import { evaluate } from "./internal.js";
+import execute from "./execute.js";
 
 /**
  * Given parsed Origami code, return a function that executes that code.
  *
- * @typedef {import("@weborigami/async-tree").SyncOrAsyncMap} SyncOrAsyncMap
+ * @typedef {import("../../index.ts").RuntimeState} RuntimeState
+ * @typedef {import("../../index.js").AnnotatedCode} AnnotatedCode
  *
- * @param {import("../../index.js").AnnotatedCode} code - parsed Origami expression
- * @param {SyncOrAsyncMap} parent - the parent tree in which the code is running
+ * @param {AnnotatedCode} code - parsed Origami expression
+ * @param {RuntimeState} [state] - runtime state
  */
-export function createExpressionFunction(code, parent) {
+export function createExpressionFunction(code, state) {
   async function fn() {
-    return evaluate(code, { parent });
+    return execute(code, state);
   }
   fn.code = code;
   fn.toString = () => code.location.source.text;
@@ -22,7 +23,7 @@ export function createExpressionFunction(code, parent) {
  * expression.
  *
  * @param {any} obj
- * @returns {obj is { code: Array }}
+ * @returns {obj is AnnotatedCode}
  */
 export function isExpressionFunction(obj) {
   return typeof obj === "function" && obj.code;

package/src/runtime/expressionObject.js

@@ -6,8 +6,9 @@ import {
   trailingSlash,
   Tree,
 } from "@weborigami/async-tree";
+import execute from "./execute.js";
 import handleExtension from "./handleExtension.js";
-import { evaluate, ops } from "./internal.js";
+import { ops } from "./internal.js";
 
 export const KEY_TYPE = {
   STRING: 0, // Simple string key: `a: 1`
@@ -65,7 +66,7 @@ export default async function expressionObject(entries, state = {}) {
   for (const info of infos) {
     if (info.keyType === KEY_TYPE.COMPUTED) {
       const newState = Object.assign({}, state, { object: map });
-      const key = await evaluate(/** @type {any} */ (info.key), newState);
+      const key = await execute(/** @type {any} */ (info.key), newState);
       // Destructively update the property info with the computed key
       info.key = key;
       defineProperty(object, info, state, map);
@@ -127,7 +128,7 @@ function defineProperty(object, propertyInfo, state, map) {
       enumerable,
       get: async () => {
         const newState = Object.assign({}, state, { object: map });
-        const result = await evaluate(value, newState);
+        const result = await execute(value, newState);
         return hasExtension ? handleExtension(result, key, map) : result;
       },
     });

package/src/runtime/handleExtension.js

@@ -7,6 +7,7 @@ import {
   setParent,
   trailingSlash,
 } from "@weborigami/async-tree";
+import getPackedPath from "../handlers/getPackedPath.js";
 import projectGlobals from "../project/projectGlobals.js";
 
 /**
@@ -50,17 +51,30 @@ export default async function handleExtension(value, key, parent = null) {
           setParent(value, parent);
         }
 
-        const unpack = handler.unpack;
-        if (unpack) {
-          // Wrap the unpack function so its only called once per value.
-          let loadPromise;
-          value.unpack = async () => {
-            loadPromise ??= unpack(value, { key, parent });
-            return loadPromise;
-          };
+        if (handler.unpack) {
+          value.unpack = wrapUnpack(handler.unpack, value, key, parent);
         }
       }
     }
   }
+  value;
   return value;
 }
+
+// Wrap the unpack function so it's only called once per value, and so we can
+// add the file path to any errors it throws.
+function wrapUnpack(unpack, value, key, parent) {
+  let result;
+  return async () => {
+    if (!result) {
+      try {
+        result = await unpack(value, { key, parent });
+      } catch (/** @type {any} */ error) {
+        const filePath = getPackedPath(value, { key, parent });
+        const message = `Can't unpack ${filePath}\n${error.message}`;
+        throw new error.constructor(message, { cause: error });
+      }
+    }
+    return result;
+  };
+}

package/src/runtime/internal.js

@@ -10,6 +10,6 @@
 
 export * as ops from "./ops.js";
 
-export { default as evaluate } from "./evaluate.js";
+export { default as evaluate } from "./execute.js";
 
 export * as expressionFunction from "./expressionFunction.js";

package/src/runtime/interop.js

@@ -0,0 +1,15 @@
+import { interop } from "@weborigami/async-tree";
+import asyncStorage from "./asyncStorage.js";
+import { lineInfo } from "./errors.js";
+
+/**
+ * Inject our warning function into async-tree calls
+ */
+interop.warn = function warn(...args) {
+  console.warn(...args);
+  const context = asyncStorage.getStore();
+  const location = context?.code?.location;
+  if (location) {
+    console.warn(lineInfo(location));
+  }
+};

package/src/runtime/ops.js

@@ -8,8 +8,8 @@
 
 import { getParent, isUnpackable, Tree } from "@weborigami/async-tree";
 import os from "node:os";
+import execute from "./execute.js";
 import expressionObject from "./expressionObject.js";
-import { evaluate } from "./internal.js";
 import mergeTrees from "./mergeTrees.js";
 import OrigamiFileMap from "./OrigamiFileMap.js";
 import { codeSymbol } from "./symbols.js";
@@ -26,6 +26,28 @@ export function addition(a, b) {
 }
 addOpLabel(addition, "«ops.addition»");
 
+/**
+ * Flatten the arguments and then apply the function.
+ * This is used to handle spreads in function calls.
+ */
+export async function apply(fn, args, state) {
+  // TODO: This is starting to recapitulate much of execute()
+  if (isUnpackable(fn)) {
+    fn = await fn.unpack();
+  }
+  if (fn.needsState) {
+    // The function is an op that wants the runtime state
+    args.push(state);
+  }
+  const result =
+    fn instanceof Function
+      ? await fn(...args) // Invoke the function
+      : await Tree.traverseOrThrow(fn, ...args); // Traverse the map.
+  return result;
+}
+addOpLabel(apply, "«ops.apply»");
+apply.needsState = true;
+
 /**
  * Construct an array.
  *
@@ -70,7 +92,7 @@ export async function cache(cache, path, code) {
   }
 
   // Don't await: might get another request for this before promise resolves
-  const promise = await evaluate(code);
+  const promise = await execute(code);
 
   // Save promise so another request will get the same promise
   cache[path] = promise;
@@ -94,23 +116,13 @@ cache.unevaluatedArgs = true;
 export async function comma(...args) {
   let result;
   for (const arg of args) {
-    result = await evaluate(arg);
+    result = await execute(arg);
   }
   return result;
 }
 addOpLabel(comma, "«ops.comma»");
 comma.unevaluatedArgs = true;
 
-/**
- * Concatenate the given arguments.
- *
- * @param {any[]} args
- */
-export async function concat(...args) {
-  return Tree.deepText(args);
-}
-addOpLabel(concat, "«ops.concat»");
-
 export async function conditional(condition, truthy, falsy) {
   const value = condition ? truthy : falsy;
   return value instanceof Function ? await value() : value;
@@ -123,6 +135,16 @@ export async function construct(constructor, ...args) {
   return Reflect.construct(constructor, args);
 }
 
+/**
+ * Return the deep text of the arguments
+ *
+ * @param {any[]} args
+ */
+export async function deepText(...args) {
+  return Tree.deepText(args);
+}
+addOpLabel(deepText, "«ops.deepText");
+
 /**
  * Default value for a parameter: if the value is defined, return that;
  * otherwise, return the result of invoking the initializer.
@@ -157,11 +179,14 @@ addOpLabel(exponentiation, "«ops.exponentiation»");
  */
 export async function flat(...args) {
   const arrays = await Promise.all(
-    args.map(async (arg) =>
-      arg instanceof Array || typeof arg !== "object"
+    args.map(async (arg) => {
+      if (isUnpackable(arg)) {
+        arg = await arg.unpack();
+      }
+      return arg instanceof Array || typeof arg !== "object"
         ? arg
-        : await Tree.values(arg)
-    )
+        : await Tree.values(arg);
+    }),
   );
 
   return arrays.flat();
@@ -210,7 +235,7 @@ export async function inherited(depth, state) {
   for (let i = 0; i < depth; i++) {
     if (!current) {
       throw new ReferenceError(
-        `Origami internal error: Can't find context object`
+        `Origami internal error: Can't find context object`,
       );
     }
     current = getParent(current);
@@ -255,7 +280,7 @@ export function lambda(length, parameters, code, state = {}) {
       newState = Object.assign({}, state, { stack: newStack });
     }
 
-    const result = await evaluate(code, newState);
+    const result = await execute(code, newState);
     return result;
   }
 
@@ -460,7 +485,12 @@ addOpLabel(optional, "«ops.optional»");
  */
 export async function property(object, key) {
   if (object == null) {
-    throw new ReferenceError();
+    /** @type {any} */
+    const error = new ReferenceError(
+      "Tried to get a property of something that doesn't exist.",
+    );
+    error.position = 1; // position of the bad argument
+    throw error;
   }
 
   if (isUnpackable(object)) {
@@ -511,7 +541,7 @@ addOpLabel(rootDirectory, "«ops.rootDirectory»");
 export async function scope(parent) {
   if (!parent) {
     throw new ReferenceError(
-      "Tried to find a value in scope, but no container was provided as the parent."
+      "Tried to find a value in scope, but no container was provided as the parent.",
     );
   }
   return Tree.scope(parent);

package/src/runtime/symbols.js

@@ -2,4 +2,3 @@ export const codeSymbol = Symbol("code");
 export const configSymbol = Symbol("config");
 export const scopeSymbol = Symbol("scope");
 export const sourceSymbol = Symbol("source");
-export const warningSymbol = Symbol("warning");

package/src/runtime/typos.js

@@ -1,7 +1,12 @@
 /**
- * Returns true if the two strings have a Damerau-Levenshtein distance of 1.
- * This will be true if the strings differ by a single insertion, deletion,
- * substitution, or transposition.
+ * Returns true if one string could be a typo of the other.
+ *
+ * We generally define a typo as two strings with a Damerau-Levenshtein distance
+ * of 1. This will be true if the strings differ by a single insertion,
+ * deletion, substitution, or transposition.
+ *
+ * Additionally, we consider two strings that differ only in case to be typos,
+ * as well as two strings that differ only by accents.
  *
  * @param {string} s1
  * @param {string} s2
@@ -15,6 +20,16 @@ export function isTypo(s1, s2) {
     return false;
   }
 
+  // If the strings are the same ignoring case, consider them typos
+  if (s1.toLowerCase() === s2.toLowerCase()) {
+    return true;
+  }
+
+  // If the strings are the same ignoring accents, consider them typos
+  if (normalize(s1) === normalize(s2)) {
+    return true;
+  }
+
   // If strings are both a single character, we don't want to consider them
   // typos.
   if (length1 === 1 && length2 === 1) {
@@ -66,6 +81,10 @@ export function isTypo(s1, s2) {
   return shorter === longer.slice(0, shorter.length);
 }
 
+function normalize(str) {
+  return str.normalize("NFD").replace(/[\u0300-\u036f]/g, "");
+}
+
 /**
  * Return any strings that could be a typo of s
  *