@weborigami/origami 0.0.35

package/src/builtins/@scope/set.js

@@ -0,0 +1,25 @@
+import { Tree } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import { keySymbol } from "../../common/utilities.js";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Return a copy of the given tree that has the indicated trees as its scope.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @param {Treelike} treelike
+ * @param  {...(Treelike|null)} scopeTrees
+ * @this {AsyncTree|null}
+ */
+export default function setScope(treelike, ...scopeTrees) {
+  assertScopeIsDefined(this);
+  const tree = Tree.from(treelike);
+  const scope = scopeTrees.length === 0 ? this : new Scope(...scopeTrees);
+  const result = Scope.treeWithScope(tree, scope);
+  result[keySymbol] = tree[keySymbol];
+  return result;
+}
+
+setScope.usage = `@scope/set <tree>, <...trees>\tReturns a tree copy with the given scope`;
+setScope.documentation = "https://graphorigami.org/cli/builtins.html#@scope";

package/src/builtins/@serve.js

@@ -0,0 +1,74 @@
+import { Tree } from "@weborigami/async-tree";
+import http from "node:http";
+import { createServer } from "node:net";
+import process from "node:process";
+import ExplorableSiteTransform from "../common/ExplorableSiteTransform.js";
+import { isTransformApplied, transformObject } from "../common/utilities.js";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+import { requestListener } from "../server/server.js";
+import debug from "./@debug.js";
+import watch from "./@watch.js";
+
+const defaultPort = 5000;
+
+/**
+ * Start a local web server for the indicated tree.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ *
+ * @param {Treelike} treelike
+ * @param {number} [port]
+ * @this {AsyncTree|null}
+ */
+export default async function serve(treelike, port) {
+  assertScopeIsDefined(this);
+  let tree;
+  if (treelike) {
+    tree = Tree.from(treelike);
+
+    // TODO: Instead of applying ExplorableSiteTransform, apply a transform
+    // that just maps the empty string to index.html.
+    if (!isTransformApplied(ExplorableSiteTransform, tree)) {
+      tree = transformObject(ExplorableSiteTransform, tree);
+    }
+  } else {
+    // By default, watch the default tree and add default pages.
+    const withDefaults = await debug.call(this);
+    tree = await watch.call(this, withDefaults);
+  }
+
+  if (port === undefined) {
+    if (process.env.PORT) {
+      // Use the port specified in the environment.
+      port = parseInt(process.env.PORT);
+    } else {
+      // Find an open port.
+      port = await findOpenPort(defaultPort);
+    }
+  }
+
+  // @ts-ignore
+  http.createServer(requestListener(tree)).listen(port, undefined, () => {
+    console.log(
+      `Server running at http://localhost:${port}. Press Ctrl+C to stop.`
+    );
+  });
+}
+
+// Return the first open port number on or after the given port number.
+// From https://gist.github.com/mikeal/1840641?permalink_comment_id=2896667#gistcomment-2896667
+function findOpenPort(port) {
+  const server = createServer();
+  return new Promise((resolve, reject) =>
+    server
+      .on("error", (/** @type {any} */ error) =>
+        error.code === "EADDRINUSE" ? server.listen(++port) : reject(error)
+      )
+      .on("listening", () => server.close(() => resolve(port)))
+      .listen(port)
+  );
+}
+
+serve.usage = `@serve <tree>, [port]\tStart a web server for the tree`;
+serve.documentation = "https://graphorigami.org/language/@serve.html";

package/src/builtins/@shell.js

@@ -0,0 +1,16 @@
+import { exec as callbackExec } from "node:child_process";
+import util from "node:util";
+const exec = util.promisify(callbackExec);
+
+export default async function shell(command) {
+  try {
+    const { stdout } = await exec(command);
+    return stdout;
+  } catch (err) {
+    console.error(err);
+    return undefined;
+  }
+}
+
+shell.usage = `@shell <command>\tExecutes the shell command and returns the output`;
+shell.documentation = "https://graphorigami.org/language/@shell.html";

package/src/builtins/@stdin.js

@@ -0,0 +1,26 @@
+import process from "node:process";
+
+export default async function stdin() {
+  return readAll(process.stdin);
+}
+
+function readAll(readable) {
+  return new Promise((resolve) => {
+    const chunks = [];
+
+    readable.on("readable", () => {
+      let chunk;
+      while (null !== (chunk = readable.read())) {
+        chunks.push(chunk);
+      }
+    });
+
+    readable.on("end", () => {
+      const buffer = Buffer.concat(chunks);
+      resolve(buffer);
+    });
+  });
+}
+
+stdin.usage = `@stdin\tReturns the contents of the standard input stream`;
+stdin.documentation = "https://graphorigami.org/language/@stdin.html";

package/src/builtins/@svg.js

@@ -0,0 +1,42 @@
+import { Tree } from "@weborigami/async-tree";
+import graphviz from "graphviz-wasm";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+import dot from "./@tree/dot.js";
+
+let graphvizLoaded = false;
+
+/**
+ * Render a tree visually in SVG format.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("@weborigami/async-tree").PlainObject} PlainObject
+ *
+ * @this {AsyncTree|null}
+ * @param {Treelike} [treelike]
+ * @param {PlainObject} [options]
+ */
+export default async function svg(treelike, options = {}) {
+  assertScopeIsDefined(this);
+  if (!graphvizLoaded) {
+    await graphviz.loadWASM();
+    graphvizLoaded = true;
+  }
+  treelike = treelike ?? (await this?.get("@current"));
+  if (treelike === undefined) {
+    return undefined;
+  }
+  const tree = Tree.from(treelike);
+  const dotText = await dot.call(this, tree, options);
+  if (dotText === undefined) {
+    return undefined;
+  }
+  const svgText = await graphviz.layout(dotText, "svg");
+  /** @type {any} */
+  const result = new String(svgText);
+  result.unpack = () => tree;
+  return result;
+}
+
+svg.usage = `@svg <tree>\tRender a tree visually as in SVG format`;
+svg.documentation = "https://graphorigami.org/language/@svg.html";

package/src/builtins/@tree/concat.js

@@ -0,0 +1,21 @@
+import { Tree } from "@weborigami/async-tree";
+import { ops } from "@weborigami/language";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Concatenate the text content of objects or trees.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @this {AsyncTree|null}
+ * @param {any[]} args
+ */
+export default async function concat(...args) {
+  assertScopeIsDefined(this);
+  const tree =
+    args.length === 0 ? await this?.get("@current") : Tree.from(args);
+  return ops.concat.call(this, tree);
+}
+
+concat.usage = `concat <...objs>\tConcatenate text and/or trees of text`;
+concat.documentation = "https://graphorigami.org/cli/@tree.html#concat";

package/src/builtins/@tree/count.js

@@ -0,0 +1,24 @@
+import { Tree } from "@weborigami/async-tree";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Return the number of keys in the tree.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @this {AsyncTree|null}
+ * @param {Treelike} [treelike]
+ */
+export default async function count(treelike) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  if (treelike === undefined) {
+    return undefined;
+  }
+  const tree = await Tree.from(treelike);
+  const keys = [...(await tree.keys())];
+  return keys.length;
+}
+
+count.usage = `count <treelike>\tReturn the number of keys in the tree`;
+count.documentation = "https://graphorigami.org/cli/@tree.html#count";

package/src/builtins/@tree/defineds.js

@@ -0,0 +1,37 @@
+import { Tree } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Return only the defined (not `undefined`) values in the tree.
+ *
+ * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ *
+ * @this {AsyncTree|null}
+ * @param {Treelike} treelike
+ */
+export default async function defineds(treelike) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  if (treelike === undefined) {
+    throw new TypeError("A treelike argument is required");
+  }
+
+  /** @type {AsyncTree} */
+  let result = await Tree.mapReduce(treelike, null, async (values, keys) => {
+    const result = {};
+    let someValuesExist = false;
+    for (let i = 0; i < keys.length; i++) {
+      const value = values[i];
+      if (value != null) {
+        someValuesExist = true;
+        result[keys[i]] = values[i];
+      }
+    }
+    return someValuesExist ? result : null;
+  });
+
+  result = Scope.treeWithScope(result, this);
+  return result;
+}

package/src/builtins/@tree/dot.js

@@ -0,0 +1,201 @@
+import { Tree, isPlainObject, isStringLike } from "@weborigami/async-tree";
+import { extname } from "@weborigami/language";
+import * as serialize from "../../common/serialize.js";
+import { keySymbol } from "../../common/utilities.js";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Render a tree in DOT format.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("@weborigami/async-tree").PlainObject} PlainObject
+ *
+ * @this {AsyncTree|null}
+ * @param {Treelike} [treelike]
+ * @param {PlainObject} [options]
+ */
+export default async function dot(treelike, options = {}) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  if (treelike === undefined) {
+    return undefined;
+  }
+  const tree = Tree.from(treelike);
+  const rootLabel = tree[keySymbol] ?? "";
+  const treeArcs = await statements(tree, "", rootLabel, options);
+  return `digraph g {
+  bgcolor="transparent";
+  nodesep=1;
+  rankdir=LR;
+  ranksep=1.5;
+  node [color=gray70; fillcolor="white"; fontname="Helvetica"; fontsize="10"; nojustify=true; style="filled"; shape=box];
+  edge [arrowhead=vee; arrowsize=0.75; color=gray60; fontname="Helvetica"; fontsize="10"; labeldistance=5];
+
+${treeArcs.join("\n")}
+}`;
+}
+
+// Return true if the text appears to contain non-printable binary characters.
+function probablyBinary(text) {
+  // https://stackoverflow.com/a/1677660/76472
+  return /[\x00-\x08\x0E-\x1F]/.test(text);
+}
+
+async function statements(tree, nodePath, nodeLabel, options) {
+  let result = [];
+  const createLinks = options.createLinks ?? true;
+
+  // Add a node for the root of this (sub)tree.
+  const rootUrl = nodePath || ".";
+  const url = createLinks ? `; URL="${rootUrl}"` : "";
+  const rootLabel = nodeLabel ? `; xlabel="${nodeLabel}"` : "";
+  result.push(
+    `  "${nodePath}" [shape=circle${rootLabel}; label=""; color=gray40; width=0.15${url}];`
+  );
+
+  // Draw edges and collect labels for the nodes they lead to.
+  let nodes = {};
+  for (const key of await tree.keys()) {
+    const destPath = nodePath ? `${nodePath}/${key}` : key;
+    const arc = `  "${nodePath}" -> "${destPath}" [label="${key}"];`;
+    result.push(arc);
+
+    let isError = false;
+    let value;
+    try {
+      value = await tree.get(key);
+    } catch (/** @type {any} */ error) {
+      isError = true;
+      value =
+        error.name && error.message
+          ? `${error.name}: ${error.message}`
+          : error.name ?? error.message ?? error;
+    }
+
+    // We expand certain types of files known to contain trees.
+    const extension = key ? extname(key).toLowerCase() : "";
+    const expand =
+      {
+        ".json": true,
+        ".yaml": true,
+      }[extension] ?? extension === "";
+
+    const expandable =
+      value instanceof Array || isPlainObject(value) || Tree.isAsyncTree(value);
+    if (expand && expandable) {
+      const subtree = Tree.from(value);
+      const subStatements = await statements(subtree, destPath, null, options);
+      result = result.concat(subStatements);
+    } else {
+      const label = isStringLike(value)
+        ? String(value)
+        : await serialize.toYaml(value);
+      nodes[key] = { label };
+      if (isError) {
+        nodes[key].isError = true;
+      }
+    }
+  }
+
+  // If we have more than one label, we'll focus on the labels' differences.
+  // We'll use the first label as a representative baseline for all labels but
+  // the first (which will use the second label as a baseline).
+  const values = Object.values(nodes);
+  const showLabelDiffs = values.length > 1;
+  const label1 = showLabelDiffs ? String(values[0].label) : undefined;
+  const label2 = showLabelDiffs ? String(values[1].label) : undefined;
+
+  // Trim labels.
+  let i = 0;
+  for (const key of Object.keys(nodes)) {
+    let label = String(nodes[key].label);
+    if (probablyBinary(label)) {
+      nodes[key].label = "[binary data]";
+    } else if (label) {
+      let clippedStart = false;
+      let clippedEnd = false;
+
+      if (showLabelDiffs) {
+        const baseline = i === 0 ? label2 : label1;
+        const diff = stringDiff(baseline, label);
+        if (diff !== label) {
+          label = diff;
+          clippedStart = true;
+        }
+      }
+
+      label = label.trim();
+
+      if (label.length > 40) {
+        // Long text, just use the beginning
+        label = label.slice(0, 40);
+        clippedEnd = true;
+      }
+
+      // Left justify node label using weird Dot escape character
+      // See https://stackoverflow.com/a/13104953/76472
+      const endsWithNewline = label.endsWith("\n");
+      label = label.replace(/\n/g, "\\l");
+
+      label = label.replace(/"/g, '\\"'); // Escape quotes
+      label = label.replace(/[\ \t]+/g, " "); // Collapse spaces and tabs
+
+      // Add ellipses if we clipped the label. We'd prefer to end with a real
+      // ellipsis, but GraphViz warns about "non-ASCII character 226" if we do.
+      // (That's not even the ellipsis character!) We could use a real ellipsis
+      // for the start, but then they might look different.
+      if (clippedStart) {
+        label = "..." + label;
+      }
+      if (clippedEnd) {
+        label += "...";
+      }
+
+      if (!endsWithNewline) {
+        // See note above
+        label += "\\l";
+      }
+
+      nodes[key].label = label;
+    }
+    i++;
+  }
+
+  // Draw labels.
+  for (const key in nodes) {
+    const node = nodes[key];
+    const icon = node.isError ? "⚠️ " : "";
+    const label = `label="${icon}${node.label}"`;
+    const color = node.isError ? `; color="red"` : "";
+    const fill = node.isError ? `; fillcolor="#FFF4F4"` : "";
+    const destPath = nodePath ? `${nodePath}/${key}` : key;
+    const url = createLinks ? `; URL="${destPath}"` : "";
+    result.push(`  "${destPath}" [${label}${color}${fill}${url}];`);
+  }
+
+  return result;
+}
+
+// Return the second string, removing the initial portion it shares with the
+// first string. The returned string will start with the first non-whitespace
+// character of the first line that differs from the first string.
+function stringDiff(first, second) {
+  let i = 0;
+  // Find point of first difference.
+  while (i < first.length && i < second.length && first[i] === second[i]) {
+    i++;
+  }
+  // Back up to start of that line.
+  while (i > 0 && second[i - 1] !== "\n") {
+    i--;
+  }
+  // Move forward to first non-whitespace character.
+  while (i < second.length && /\s/.test(second[i])) {
+    i++;
+  }
+  return second.slice(i);
+}
+
+dot.usage = `dot <tree>\tRender a tree visually in dot language`;
+dot.documentation = "https://graphorigami.org/cli/builtins.html#dot";

package/src/builtins/@tree/exceptions.js

@@ -0,0 +1,50 @@
+import { Tree } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+import defineds from "./defineds.js";
+
+/**
+ * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @this {AsyncTree|null}
+ * @param {Treelike} treelike
+ */
+export default async function exceptions(treelike) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+
+  /** @type {AsyncTree} */
+  let exceptionsTree = new ExceptionsTree(treelike);
+  exceptionsTree = Scope.treeWithScope(exceptionsTree, this);
+  return defineds.call(this, exceptionsTree);
+}
+
+/**
+ * @implements {AsyncTree}
+ */
+class ExceptionsTree {
+  constructor(treelike) {
+    this.tree = Tree.from(treelike);
+  }
+
+  async get(key) {
+    try {
+      const value = await this.tree.get(key);
+      return Tree.isAsyncTree(value)
+        ? Reflect.construct(this.constructor, [value])
+        : undefined;
+    } catch (/** @type {any} */ error) {
+      return error.name && error.message
+        ? `${error.name}: ${error.message}`
+        : error.name ?? error.message ?? error;
+    }
+  }
+
+  async keys() {
+    return this.tree.keys();
+  }
+}
+
+exceptions.usage = `exceptions tree\tReturn a tree of exceptions thrown in the tree`;
+exceptions.documentation =
+  "https://graphorigami.org/cli/builtins.html#exceptions";

package/src/builtins/@tree/first.js

@@ -0,0 +1,28 @@
+import { Tree } from "@weborigami/async-tree";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Return the first value in the tree.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @this {AsyncTree|null}
+ * @param {Treelike} [treelike]
+ */
+export default async function first(treelike) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  if (treelike === undefined) {
+    return undefined;
+  }
+  const tree = Tree.from(treelike);
+  for (const key of await tree.keys()) {
+    // Just return first value immediately.
+    const value = await tree.get(key);
+    return value;
+  }
+  return undefined;
+}
+
+first.usage = `first <tree>\tReturns the first value in the tree.`;
+first.documentation = "https://graphorigami.org/cli/builtins.html#first";

package/src/builtins/@tree/flowSvg.js

@@ -0,0 +1,55 @@
+import graphviz from "graphviz-wasm";
+
+let graphvizLoaded = false;
+
+export default async function flowSvg(flow) {
+  if (!graphvizLoaded) {
+    await graphviz.loadWASM();
+    graphvizLoaded = true;
+  }
+  const dot = flowDot(flow);
+  const svg = await graphviz.layout(dot, "svg");
+  return svg;
+}
+
+function flowDot(flow) {
+  const nodes = [];
+  const edges = [];
+  for (const [key, record] of Object.entries(flow)) {
+    const dependencies = record.dependencies ?? [];
+    let label = record.label ?? key;
+    if (record.undefined) {
+      label += " (?)";
+    }
+    const virtualNode = dependencies.length > 0;
+    const url = record.url ?? key;
+    const nodeLabel = `label="${label}"`;
+    const nodeUrl = `URL=".scope/${url}"`;
+    const nodeShape = record.undefined ? `shape="none"` : "";
+    const nodeStyle = virtualNode ? `style="dashed"` : null;
+    const attributes = [nodeLabel, nodeShape, nodeStyle, nodeUrl].filter(
+      (attribute) => attribute
+    );
+    const nodeDot = `  "${key}" [${attributes.join("; ")}];`;
+    nodes.push(nodeDot);
+
+    for (const dependency of dependencies) {
+      edges.push(`  "${dependency}" -> "${key}";`);
+    }
+  }
+
+  return `digraph dataflow {
+  nodesep=1;
+  rankdir=LR;
+  ranksep=1.5;
+  node [color="gray70"; fillcolor="white"; fontname="Helvetica"; fontsize="10"; nojustify="true"; style="filled"; shape="box"];
+  edge [arrowhead="onormal"; arrowsize="0.75"; color="gray60"; fontname="Helvetica"; fontsize="10"; labeldistance="5"];
+
+${nodes.join("\n")}
+
+${edges.join("\n")}
+}`;
+}
+
+// flowSvg.usage = `flowSvg <dataflow>\tRenders the output of dataflow() as an SVG`;
+// flowSvg.documentation = "https://graphorigami.org/cli/builtins.html#flowSvg";

package/src/builtins/@tree/fn.js

@@ -0,0 +1,34 @@
+import { FunctionTree } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import { toFunction } from "../../common/utilities.js";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Create a tree from a function and a set of keys.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("../../../index.ts").Invocable} Invocable
+ *
+ * @this {AsyncTree|null}
+ * @param {Invocable} [invocable]
+ */
+export default async function fn(invocable, keys = []) {
+  assertScopeIsDefined(this);
+  invocable = invocable ?? (await this?.get("@current"));
+  if (invocable === undefined) {
+    return undefined;
+  }
+  const invocableFn = toFunction(invocable);
+
+  /** @this {AsyncTree|null} */
+  async function extendedFn(key) {
+    const ambientsTree = Scope.treeWithScope({ "@key": key }, this);
+    return invocableFn.call(ambientsTree, key);
+  }
+
+  return new FunctionTree(extendedFn, keys);
+}
+
+fn.usage = `fn <fn>, [<keys>]\tCreate a tree from a function and a set of keys`;
+fn.documentation = "https://graphorigami.org/cli/tree.html#fn";

package/src/builtins/@tree/from.js

@@ -0,0 +1,27 @@
+import { Tree } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Cast the indicated treelike to a tree.
+ *
+ * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @this {AsyncTree|null}
+ * @param {Treelike} [treelike]
+ */
+export default async function tree(treelike) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  if (treelike === undefined) {
+    return undefined;
+  }
+
+  /** @type {AsyncTree} */
+  let result = Tree.from(treelike);
+  result = Scope.treeWithScope(result, this);
+  return result;
+}
+
+tree.usage = `from <treelike>\tConvert JSON, YAML, function, or plain object to a tree`;
+tree.documentation = "https://graphorigami.org/cli/builtins.html#tree";

package/src/builtins/@tree/fromJson.js

@@ -0,0 +1,6 @@
+export default async function fromJson(text) {
+  return text ? JSON.parse(text) : undefined;
+}
+
+fromJson.usage = `fromJson <text>\tParse text as JSON`;
+fromJson.documentation = "https://graphorigami.org/cli/builtins.html#fromJson";