@danielsimonjr/mathts-workbook 0.1.8 → 0.3.0

package/dist/chunk-3KTM2DZC.js

@@ -0,0 +1,720 @@
+// src/yaml-safe.ts
+import { parse as parseYaml } from "yaml";
+var POLLUTION_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+function parseYamlHardened(content) {
+  return parseYaml(content, { schema: "core", merge: false, logLevel: "silent" });
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function findPollutionKeys(value, seen = /* @__PURE__ */ new WeakSet(), found = []) {
+  if (!isPlainObject(value) && !Array.isArray(value)) return found;
+  if (seen.has(value)) return found;
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (const item of value) findPollutionKeys(item, seen, found);
+    return found;
+  }
+  for (const key of Object.getOwnPropertyNames(value)) {
+    if (POLLUTION_KEYS.has(key)) {
+      found.push(key);
+      continue;
+    }
+    findPollutionKeys(value[key], seen, found);
+  }
+  return found;
+}
+function assertNoPollution(value) {
+  const keys = findPollutionKeys(value);
+  if (keys.length > 0) {
+    throw new Error(`Disallowed key "${keys[0]}" (prototype pollution)`);
+  }
+}
+
+// src/graph.ts
+function buildDependencyGraph(cells) {
+  const nodes = /* @__PURE__ */ new Map();
+  for (const cell of cells) {
+    nodes.set(cell.id, {
+      id: cell.id,
+      dependencies: cell.dependsOn ?? [],
+      dependents: []
+    });
+  }
+  for (const cell of cells) {
+    for (const depId of cell.dependsOn ?? []) {
+      const depNode = nodes.get(depId);
+      if (depNode) {
+        depNode.dependents.push(cell.id);
+      }
+    }
+  }
+  const executionOrder = topologicalSort(nodes);
+  return { nodes, executionOrder };
+}
+function topologicalSort(nodes) {
+  const visited = /* @__PURE__ */ new Set();
+  const result = [];
+  function visit(id) {
+    if (visited.has(id)) return;
+    visited.add(id);
+    const node = nodes.get(id);
+    if (node) {
+      for (const depId of node.dependencies) {
+        visit(depId);
+      }
+    }
+    result.push(id);
+  }
+  for (const id of nodes.keys()) {
+    visit(id);
+  }
+  return result;
+}
+function getDependents(graph, cellId) {
+  const result = [];
+  const visited = /* @__PURE__ */ new Set();
+  function collect(id) {
+    const node = graph.nodes.get(id);
+    if (!node) return;
+    for (const depId of node.dependents) {
+      if (!visited.has(depId)) {
+        visited.add(depId);
+        result.push(depId);
+        collect(depId);
+      }
+    }
+  }
+  collect(cellId);
+  return result;
+}
+function getAncestors(graph, id) {
+  const result = /* @__PURE__ */ new Set();
+  function visit(nodeId) {
+    if (result.has(nodeId)) return;
+    const node = graph.nodes.get(nodeId);
+    if (!node) return;
+    result.add(nodeId);
+    for (const dep of node.dependencies) visit(dep);
+  }
+  visit(id);
+  return graph.executionOrder.filter((nodeId) => result.has(nodeId));
+}
+function toMermaid(graph) {
+  const lines = ["graph TD"];
+  for (const id of graph.nodes.keys()) {
+    lines.push(`  ${id}["${id}"]`);
+  }
+  for (const [id, node] of graph.nodes) {
+    for (const dep of node.dependencies) {
+      lines.push(`  ${dep} --> ${id}`);
+    }
+  }
+  return lines.join("\n");
+}
+function toDOT(graph) {
+  const lines = ["digraph deps {"];
+  for (const id of graph.nodes.keys()) {
+    lines.push(`  ${id} [label="${id}"];`);
+  }
+  for (const [id, node] of graph.nodes) {
+    for (const dep of node.dependencies) {
+      lines.push(`  ${dep} -> ${id};`);
+    }
+  }
+  lines.push("}");
+  return lines.join("\n");
+}
+function detectCycles(graph) {
+  const cycles = [];
+  const visited = /* @__PURE__ */ new Set();
+  const stack = /* @__PURE__ */ new Set();
+  function dfs(id, path) {
+    if (stack.has(id)) {
+      const cycleStart = path.indexOf(id);
+      cycles.push(path.slice(cycleStart));
+      return true;
+    }
+    if (visited.has(id)) return false;
+    visited.add(id);
+    stack.add(id);
+    const node = graph.nodes.get(id);
+    if (node) {
+      for (const depId of node.dependencies) {
+        dfs(depId, [...path, id]);
+      }
+    }
+    stack.delete(id);
+    return false;
+  }
+  for (const id of graph.nodes.keys()) {
+    if (!visited.has(id)) {
+      dfs(id, []);
+    }
+  }
+  return cycles;
+}
+
+// src/parser.ts
+import { stringify as stringifyYaml } from "yaml";
+var CELL_TYPE_KEYS = [
+  "markdown",
+  "code",
+  "tensor",
+  "equation",
+  "visualization",
+  "data",
+  "test",
+  "export"
+];
+var RESERVED_CELL_KEYS = ["id", "depends_on", "language", "format", "output", "error"];
+var IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function isValidIdentifier(id) {
+  return typeof id === "string" && IDENTIFIER_RE.test(id);
+}
+var SUPPORTED_CELL_TYPES = ["code", "markdown", "data", "test", "equation", "visualization"];
+var EXECUTION_MODES = ["reactive", "sequential", "manual"];
+function detectCellType(cell) {
+  for (const key of CELL_TYPE_KEYS) {
+    if (key in cell) {
+      return key;
+    }
+  }
+  return "code";
+}
+function isPlainObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toContent(raw) {
+  if (raw === null || raw === void 0) return "";
+  if (typeof raw === "string") return raw;
+  return stringifyYaml(raw).trim();
+}
+function normalizeRuntime(raw) {
+  const rt = isPlainObject2(raw) ? raw : {};
+  const runtime = {
+    engine: rt.engine === "custom" ? "custom" : "mathts",
+    execution: typeof rt.execution === "string" && EXECUTION_MODES.includes(rt.execution) ? rt.execution : "reactive"
+  };
+  if (typeof rt.timeout === "number") runtime.timeout = rt.timeout;
+  return runtime;
+}
+function mapCell(raw, index, errors) {
+  if (!isPlainObject2(raw)) {
+    errors.push(`Cell at index ${index}: must be a mapping`);
+    return { id: `#${index}`, type: "code", content: "" };
+  }
+  const rawId = raw.id;
+  let id;
+  if (rawId === void 0 || rawId === null) {
+    errors.push(`Cell at index ${index}: missing "id"`);
+    id = `#${index}`;
+  } else if (typeof rawId !== "string" || !IDENTIFIER_RE.test(rawId)) {
+    errors.push(
+      `Cell "${String(rawId)}": id must be a valid identifier ([A-Za-z_][A-Za-z0-9_]*)`
+    );
+    id = String(rawId);
+  } else {
+    id = rawId;
+  }
+  const presentTypeKeys = CELL_TYPE_KEYS.filter(
+    (k) => Object.prototype.hasOwnProperty.call(raw, k)
+  );
+  if (presentTypeKeys.length === 0) {
+    errors.push(
+      `Cell "${id}": no recognized type key (expected one of ${CELL_TYPE_KEYS.join(", ")})`
+    );
+  } else if (presentTypeKeys.length > 1) {
+    errors.push(`Cell "${id}": multiple type keys (${presentTypeKeys.join(", ")})`);
+  }
+  const type = presentTypeKeys[0] ?? "code";
+  const content = presentTypeKeys[0] ? toContent(raw[presentTypeKeys[0]]) : "";
+  if (presentTypeKeys[0] && !SUPPORTED_CELL_TYPES.includes(type)) {
+    errors.push(
+      `Cell "${id}": type '${type}' is reserved but not yet supported (supported: ${SUPPORTED_CELL_TYPES.join(", ")})`
+    );
+  }
+  let dependsOn;
+  if (raw.depends_on !== void 0) {
+    if (!Array.isArray(raw.depends_on)) {
+      errors.push(`Cell "${id}": depends_on must be a list`);
+    } else {
+      dependsOn = raw.depends_on.map((d) => String(d));
+    }
+  }
+  const metadata = {};
+  for (const key of Object.keys(raw)) {
+    if (RESERVED_CELL_KEYS.includes(key) || CELL_TYPE_KEYS.includes(key)) continue;
+    metadata[key] = raw[key];
+  }
+  const cell = { id, type, content };
+  if (dependsOn) cell.dependsOn = dependsOn;
+  if (Object.keys(metadata).length > 0) cell.metadata = metadata;
+  if (raw.output !== void 0) cell.output = raw.output;
+  if (raw.error !== void 0) cell.error = String(raw.error);
+  return cell;
+}
+function parseWorkbook(content) {
+  try {
+    if (!content.trim()) {
+      return { success: false, errors: ["Empty workbook content"] };
+    }
+    const errors = [];
+    const warnings = [];
+    const doc = parseYamlHardened(content);
+    if (!isPlainObject2(doc)) {
+      return { success: false, errors: ["Workbook must be a YAML mapping"] };
+    }
+    for (const key of findPollutionKeys(doc)) {
+      errors.push(`Disallowed key "${key}" (prototype pollution)`);
+    }
+    const metadata = isPlainObject2(doc.metadata) ? doc.metadata : {};
+    const workbook = {
+      version: doc.version != null ? String(doc.version) : "1.0",
+      metadata,
+      runtime: normalizeRuntime(doc.runtime),
+      cells: []
+    };
+    if (doc.cells === void 0) {
+      warnings.push("Workbook has no cells");
+    } else if (!Array.isArray(doc.cells)) {
+      errors.push('Workbook "cells" must be a list');
+    } else {
+      const idSet = /* @__PURE__ */ new Set();
+      const cells = doc.cells.map((raw, i) => {
+        const cell = mapCell(raw, i, errors);
+        if (IDENTIFIER_RE.test(cell.id)) {
+          if (idSet.has(cell.id)) {
+            errors.push(`Duplicate cell id: "${cell.id}"`);
+          } else {
+            idSet.add(cell.id);
+          }
+        }
+        return cell;
+      });
+      for (const cell of cells) {
+        for (const dep of cell.dependsOn ?? []) {
+          if (!idSet.has(dep)) {
+            errors.push(`Cell "${cell.id}": depends_on references unknown cell "${dep}"`);
+          }
+        }
+      }
+      workbook.cells = cells;
+    }
+    const success = errors.length === 0;
+    return {
+      success,
+      workbook: success ? workbook : void 0,
+      errors: errors.length > 0 ? errors : void 0,
+      warnings: warnings.length > 0 ? warnings : void 0
+    };
+  } catch (error) {
+    return {
+      success: false,
+      errors: [`Parse error: ${error instanceof Error ? error.message : String(error)}`]
+    };
+  }
+}
+function serializeCell(cell) {
+  const out = { [cell.type]: cell.content, id: cell.id };
+  if (cell.dependsOn && cell.dependsOn.length > 0) out.depends_on = cell.dependsOn;
+  if (cell.metadata) {
+    for (const [key, value] of Object.entries(cell.metadata)) {
+      if (CELL_TYPE_KEYS.includes(key) || RESERVED_CELL_KEYS.includes(key)) continue;
+      out[key] = value;
+    }
+  }
+  if (cell.output !== void 0) out.output = cell.output;
+  if (cell.error !== void 0) out.error = String(cell.error);
+  return out;
+}
+function serializeWorkbook(workbook) {
+  if (!workbook || !Array.isArray(workbook.cells)) {
+    throw new Error('serializeWorkbook: invalid workbook (missing "cells" array)');
+  }
+  const runtime = {
+    engine: workbook.runtime?.engine ?? "mathts",
+    execution: workbook.runtime?.execution ?? "reactive"
+  };
+  if (workbook.runtime?.timeout !== void 0) runtime.timeout = workbook.runtime.timeout;
+  const doc = {
+    version: String(workbook.version ?? "1.0"),
+    metadata: workbook.metadata ?? {},
+    runtime,
+    cells: workbook.cells.map(serializeCell)
+  };
+  return stringifyYaml(doc, { lineWidth: 0 });
+}
+function stripOutputs(workbook) {
+  return {
+    ...workbook,
+    cells: workbook.cells.map((cell) => ({
+      ...cell,
+      output: void 0,
+      error: void 0
+    }))
+  };
+}
+function importWorkbook(input) {
+  let obj;
+  try {
+    obj = parseYamlHardened(input);
+  } catch (error) {
+    return { success: false, errors: [`Invalid JSON/YAML: ${error instanceof Error ? error.message : String(error)}`] };
+  }
+  if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
+    return { success: false, errors: ['Input must be an object with a "cells" array'] };
+  }
+  const root = obj;
+  if (!Array.isArray(root.cells)) {
+    return { success: false, errors: ['Input must have a "cells" array'] };
+  }
+  const errors = [];
+  const cells = [];
+  root.cells.forEach((raw, index) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      errors.push(`Cell at index ${index}: must be an object`);
+      return;
+    }
+    const c = raw;
+    const id = typeof c.id === "string" ? c.id : "";
+    const type = typeof c.type === "string" ? c.type : "";
+    const content = typeof c.content === "string" ? c.content : c.content == null ? "" : String(c.content);
+    const depsRaw = Array.isArray(c.dependsOn) ? c.dependsOn : Array.isArray(c.depends_on) ? c.depends_on : void 0;
+    const dependsOn = depsRaw?.map((d) => String(d));
+    const cell = { id, type, content };
+    if (dependsOn && dependsOn.length > 0) cell.dependsOn = dependsOn;
+    cells.push(cell);
+  });
+  if (errors.length > 0) return { success: false, errors };
+  const metadata = root.metadata && typeof root.metadata === "object" && !Array.isArray(root.metadata) ? root.metadata : {};
+  const runtime = root.runtime && typeof root.runtime === "object" && !Array.isArray(root.runtime) ? root.runtime : { engine: "mathts", execution: "reactive" };
+  const version = typeof root.version === "string" ? root.version : "1.0";
+  const workbook = { version, metadata, runtime, cells };
+  const parsed = parseWorkbook(serializeWorkbook(workbook));
+  if (!parsed.success || !parsed.workbook) return parsed;
+  const cycles = detectCycles(buildDependencyGraph(parsed.workbook.cells));
+  if (cycles.length > 0) {
+    return { success: false, errors: cycles.map((c) => `Dependency cycle: ${c.join(" -> ")}`) };
+  }
+  return parsed;
+}
+
+// src/executor.ts
+import { evaluate } from "@danielsimonjr/mathts-functions";
+var WorkbookExecutor = class {
+  workbook;
+  graph;
+  outputs = /* @__PURE__ */ new Map();
+  handlers = [];
+  constructor(workbook) {
+    this.workbook = workbook;
+    this.graph = buildDependencyGraph(workbook.cells);
+  }
+  /**
+   * Subscribe to execution events
+   */
+  on(handler) {
+    this.handlers.push(handler);
+    return () => {
+      const index = this.handlers.indexOf(handler);
+      if (index >= 0) {
+        this.handlers.splice(index, 1);
+      }
+    };
+  }
+  /**
+   * Emit an event to all handlers
+   */
+  emit(event) {
+    for (const handler of this.handlers) {
+      handler(event);
+    }
+  }
+  /**
+   * Run all cells in order
+   */
+  async runAll() {
+    for (const cellId of this.graph.executionOrder) {
+      await this.runCell(cellId);
+    }
+    this.emit({
+      type: "workbook:complete",
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Run a specific cell
+   */
+  async runCell(cellId) {
+    const cell = this.workbook.cells.find((c) => c.id === cellId);
+    if (!cell) {
+      throw new Error(`Cell not found: ${cellId}`);
+    }
+    this.emit({
+      type: "cell:start",
+      cellId,
+      timestamp: Date.now()
+    });
+    try {
+      const output = await this.executeCell(cell);
+      this.outputs.set(cellId, output);
+      this.emit({
+        type: "cell:success",
+        cellId,
+        output,
+        timestamp: Date.now()
+      });
+      if (this.workbook.runtime.execution === "reactive") {
+        const dependents = getDependents(this.graph, cellId);
+        for (const depId of dependents) {
+          this.emit({
+            type: "cell:stale",
+            cellId: depId,
+            timestamp: Date.now()
+          });
+        }
+      }
+      return output;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.emit({
+        type: "cell:error",
+        cellId,
+        error: errorMessage,
+        timestamp: Date.now()
+      });
+      throw error;
+    }
+  }
+  /**
+   * Execute a single cell
+   */
+  async executeCell(cell) {
+    switch (cell.type) {
+      case "code":
+        return this.executeCode(cell);
+      case "test":
+        return this.executeTest(cell);
+      case "markdown":
+      case "equation":
+      case "visualization":
+        return cell.content;
+      // Display-only cells: pass content through, no eval
+      case "data":
+        return this.executeData(cell);
+      default:
+        throw new Error(`Unsupported cell type: ${cell.type}`);
+    }
+  }
+  /**
+   * Build the evaluation scope from a cell's DIRECT dependency outputs.
+   *
+   * Dependency outputs are injected as named variables keyed by the
+   * dependency's cell id, so a cell can reference an earlier cell's result by
+   * that id. Injection is non-transitive: only ids in `cell.dependsOn` are
+   * injected (a dependency's own dependencies are not). An output of
+   * `undefined` (cell never ran) is skipped, so the reference fails loudly.
+   */
+  buildScope(cell) {
+    const scope = {};
+    if (cell.dependsOn) {
+      for (const depId of cell.dependsOn) {
+        if (this.outputs.has(depId)) {
+          scope[depId] = this.outputs.get(depId);
+        }
+      }
+    }
+    return scope;
+  }
+  /**
+   * Execute a code cell by evaluating its content as a MathTS expression.
+   *
+   * Evaluation goes through the MathTS expression engine — property and
+   * method access route through the expression sandbox, so this does not
+   * have the arbitrary-code-execution exposure of the `Function` constructor.
+   */
+  async executeCode(cell) {
+    return evaluate(cell.content, this.buildScope(cell));
+  }
+  /**
+   * Execute a test cell: evaluate its assertion expression in the dependency
+   * scope. The result must be a boolean — `runReport` classifies `true` as a
+   * pass and `false` as a fail. A non-boolean result is a usage error (a test
+   * that doesn't assert), surfaced via throw like any other evaluation error.
+   */
+  async executeTest(cell) {
+    const result = evaluate(cell.content, this.buildScope(cell));
+    if (typeof result !== "boolean") {
+      throw new Error(`test cell must evaluate to a boolean, got ${typeof result}`);
+    }
+    return result;
+  }
+  /**
+   * Execute a data cell — parse its content as YAML (a superset of JSON) using
+   * the same hardened options + prototype-pollution guard as the document
+   * parser, so both YAML entry points are consistent.
+   */
+  async executeData(cell) {
+    const value = parseYamlHardened(cell.content);
+    assertNoPollution(value);
+    return value;
+  }
+  /**
+   * Run every cell in dependency order and return a structured report.
+   *
+   * Unlike {@link runAll} (the event-stream API, which throws on the first cell
+   * error), `runReport` is the headless/report API: it is **continue-on-error**
+   * (one failing cell does not abort the rest) and never throws on a cell
+   * failure. A dependency cycle is refused up front. Test cells are classified
+   * as `pass`/`fail`/`error`; all other cells as `success`/`error`.
+   */
+  /**
+   * Seed the output cache (for incremental session runs): non-stale cells'
+   * outputs are provided so downstream cells can read them as scope without
+   * re-execution. Replaces any existing cached outputs.
+   */
+  seedOutputs(entries) {
+    this.outputs = new Map(entries);
+  }
+  async runReport(options = {}) {
+    const cells = [];
+    const cycles = detectCycles(this.graph);
+    if (cycles.length > 0) {
+      const description = cycles.map((cycle) => cycle.join(" -> ")).join("; ");
+      cells.push({
+        id: "(workbook)",
+        type: "code",
+        status: "error",
+        error: `Dependency cycle detected: ${description}`
+      });
+      return { cells, ok: false };
+    }
+    let order = this.graph.executionOrder;
+    if (options.only !== void 0) {
+      const allowed = new Set(getAncestors(this.graph, options.only));
+      order = order.filter((id) => allowed.has(id));
+    }
+    for (const cellId of order) {
+      if (options.runIds && !options.runIds.has(cellId)) continue;
+      const cell = this.workbook.cells.find((c) => c.id === cellId);
+      if (!cell) continue;
+      try {
+        const output = await this.runCell(cellId);
+        if (cell.type === "test") {
+          const passed = output === true;
+          cells.push({
+            id: cell.id,
+            type: cell.type,
+            status: passed ? "pass" : "fail",
+            output,
+            error: passed ? void 0 : `Assertion failed in cell '${cell.id}'`
+          });
+        } else {
+          cells.push({ id: cell.id, type: cell.type, status: "success", output });
+        }
+      } catch (error) {
+        cells.push({
+          id: cell.id,
+          type: cell.type,
+          status: "error",
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+    const ok = cells.every((c) => c.status === "success" || c.status === "pass");
+    return { cells, ok };
+  }
+  /**
+   * Get output from a previous cell
+   */
+  getOutput(cellId) {
+    return this.outputs.get(cellId);
+  }
+};
+function createExecutor(workbook) {
+  return new WorkbookExecutor(workbook);
+}
+
+// src/formatter.ts
+function bigintReplacer(_key, val) {
+  return typeof val === "bigint" ? `${val}n` : val;
+}
+function safeStringify(value) {
+  try {
+    const json = JSON.stringify(value, bigintReplacer);
+    if (json !== void 0) return json;
+  } catch {
+  }
+  try {
+    const seen = /* @__PURE__ */ new WeakSet();
+    const json = JSON.stringify(value, (_key, val) => {
+      if (typeof val === "bigint") return `${val}n`;
+      if (val !== null && typeof val === "object") {
+        if (seen.has(val)) return "[Circular]";
+        seen.add(val);
+      }
+      return val;
+    });
+    return json ?? "(no result)";
+  } catch {
+    try {
+      return String(value);
+    } catch {
+      return "[unserializable]";
+    }
+  }
+}
+function hasCustomToString(value) {
+  const toString = value.toString;
+  return typeof toString === "function" && toString !== Object.prototype.toString && toString !== Array.prototype.toString;
+}
+function formatResult(value) {
+  if (value === null || value === void 0) return "(no result)";
+  switch (typeof value) {
+    case "string":
+      return value;
+    case "number":
+    case "boolean":
+      return String(value);
+    case "bigint":
+      return `${value}n`;
+    case "function":
+      return "(function)";
+    case "symbol":
+      return value.toString();
+    case "object": {
+      if (!Array.isArray(value) && hasCustomToString(value)) {
+        try {
+          const text = value.toString();
+          if (text && text !== "[object Object]") return text;
+        } catch {
+        }
+      }
+      return safeStringify(value);
+    }
+    default:
+      return safeStringify(value);
+  }
+}
+
+export {
+  parseYamlHardened,
+  buildDependencyGraph,
+  topologicalSort,
+  getDependents,
+  getAncestors,
+  toMermaid,
+  toDOT,
+  detectCycles,
+  isValidIdentifier,
+  SUPPORTED_CELL_TYPES,
+  detectCellType,
+  parseWorkbook,
+  serializeWorkbook,
+  stripOutputs,
+  importWorkbook,
+  WorkbookExecutor,
+  createExecutor,
+  formatResult
+};