@danielsimonjr/mathts-workbook 0.4.0 → 0.4.2

package/dist/contract.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Machine-contract constants shared by the CLI and the public API.
+ *
+ * `SCHEMA_VERSION` is the version of the `--json` envelope shape. Clients
+ * negotiate with the rule: ignore unknown fields when `major` matches; refuse
+ * on a `major` mismatch. Additive fields bump `minor`; breaking changes bump
+ * `major`.
+ */
+export declare const SCHEMA_VERSION: {
+    readonly major: 1;
+    readonly minor: 0;
+};
+export declare const VERSION: string;
+/** Canonical dispatchable command list (advertised by `capabilities`; a test guards drift). */
+export declare const COMMAND_NAMES: readonly ['run', 'describe', 'validate', 'graph', 'strip', 'new', 'capabilities', 'templates', 'cell', 'serve', 'functions', 'meta', 'import', 'export'];
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc;aAAK,KAAK,EAAE,CAAC;aAAE,KAAK,EAAE,CAAC;CAAW,CAAC;AAO9D,eAAO,MAAM,OAAO,EAAE,MAAwB,CAAC;AAE/C,+FAA+F;AAC/F,eAAO,MAAM,aAAa,YACxB,KAAK,EACL,UAAU,EACV,UAAU,EACV,OAAO,EACP,OAAO,EACP,KAAK,EACL,cAAc,EACd,WAAW,EACX,MAAM,EACN,OAAO,EACP,WAAW,EACX,MAAM,EACN,QAAQ,EACR,QAAQ,CACA,CAAC"}

package/dist/doc.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The structured "describe" document model — shared by the `describe` CLI
+ * command and the serve JSON-RPC router (kept out of cli.ts to avoid a cycle).
+ */
+import type { Workbook } from './types';
+export interface DescribeDoc {
+    version: string;
+    metadata: Workbook['metadata'];
+    runtime: Workbook['runtime'];
+    cells: Array<{
+        id: string;
+        type: string;
+        content: string;
+        dependsOn: string[];
+        metadata: Record<string, unknown>;
+        output: unknown;
+        error: unknown;
+    }>;
+    graph: {
+        edges: Array<{
+            from: string;
+            to: string;
+        }>;
+        cycles: string[][];
+    };
+}
+/** Build the `describe` payload for a (possibly missing) workbook. */
+export declare function describeData(wb: Workbook | undefined): DescribeDoc;
+//# sourceMappingURL=doc.d.ts.map

package/dist/doc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../src/doc.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGxC,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IAC/B,OAAO,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC7B,KAAK,EAAE,KAAK,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,MAAM,EAAE,OAAO,CAAC;QAChB,KAAK,EAAE,OAAO,CAAC;KAChB,CAAC,CAAC;IACH,KAAK,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,EAAE,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAA;KAAE,CAAC;CAC3E;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,CAsBlE"}

package/dist/edit.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pure, immutable cell-mutation operations on a Workbook.
+ *
+ * Every op returns a NEW workbook (the input is never mutated) and enforces the
+ * runnable-valid invariants — unique + identifier-safe ids, supported cell
+ * types, existing `depends_on` references, no self-dependency, and no dependency
+ * cycle. An op that would break an invariant throws; callers must not write the
+ * file on a throw.
+ */
+import type { Workbook, CellType } from './types';
+export interface CellPosition {
+    before?: string;
+    after?: string;
+    at?: number;
+}
+export interface RemoveResult {
+    workbook: Workbook;
+    /** Cells whose `depends_on` was edited to detach the removed cell (force). */
+    changedCells: string[];
+}
+export declare function addCell(wb: Workbook, spec: {
+    id: string;
+    type: CellType;
+    content?: string;
+    dependsOn?: string[];
+}, position?: CellPosition): Workbook;
+export declare function editCell(wb: Workbook, id: string, changes: {
+    content?: string;
+    type?: CellType;
+    dependsOn?: string[];
+}): Workbook;
+export declare function removeCell(wb: Workbook, id: string, options?: {
+    force?: boolean;
+}): RemoveResult;
+export declare function moveCell(wb: Workbook, id: string, position: CellPosition): Workbook;
+export declare function renameCell(wb: Workbook, oldId: string, newId: string): Workbook;
+/** Update workbook-level metadata fields (only the provided ones). */
+export declare function setMetadata(wb: Workbook, changes: {
+    title?: string;
+    author?: string;
+    description?: string;
+    tags?: string[];
+}): Workbook;
+//# sourceMappingURL=edit.d.ts.map

package/dist/edit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit.d.ts","sourceRoot":"","sources":["../src/edit.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAQ,QAAQ,EAAE,MAAM,SAAS,CAAC;AAIxD,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,QAAQ,CAAC;IACnB,8EAA8E;IAC9E,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAkFD,wBAAgB,OAAO,CACrB,EAAE,EAAE,QAAQ,EACZ,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,EAC5E,QAAQ,CAAC,EAAE,YAAY,GACtB,QAAQ,CAiBV;AAED,wBAAgB,QAAQ,CACtB,EAAE,EAAE,QAAQ,EACZ,EAAE,EAAE,MAAM,EACV,OAAO,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GACnE,QAAQ,CAyBV;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,YAAY,CAoBhG;AAED,wBAAgB,QAAQ,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,QAAQ,CASnF;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CA6B/E;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CACzB,EAAE,EAAE,QAAQ,EACZ,OAAO,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAClF,QAAQ,CAOV"}

package/dist/executor.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Workbook executor
+ */
+import type { Workbook, WorkbookEvent, RunResult } from './types';
+/**
+ * Event handler type
+ */
+type EventHandler = (event: WorkbookEvent) => void;
+/**
+ * Workbook executor with reactive execution support
+ */
+export declare class WorkbookExecutor {
+    private workbook;
+    private graph;
+    private outputs;
+    private handlers;
+    constructor(workbook: Workbook);
+    /**
+     * Subscribe to execution events
+     */
+    on(handler: EventHandler): () => void;
+    /**
+     * Emit an event to all handlers
+     */
+    private emit;
+    /**
+     * Run all cells in order
+     */
+    runAll(): Promise<void>;
+    /**
+     * Run a specific cell
+     */
+    runCell(cellId: string): Promise<unknown>;
+    /**
+     * Execute a single cell
+     */
+    private executeCell;
+    /**
+     * 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.
+     */
+    private buildScope;
+    /**
+     * 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.
+     */
+    private executeCode;
+    /**
+     * 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.
+     */
+    private executeTest;
+    /**
+     * 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.
+     */
+    private executeData;
+    /**
+     * 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: Map<string, unknown>): void;
+    runReport(options?: {
+        only?: string;
+        runIds?: Set<string>;
+    }): Promise<RunResult>;
+    /**
+     * Get output from a previous cell
+     */
+    getOutput(cellId: string): unknown;
+}
+/**
+ * Create an executor for a workbook
+ */
+export declare function createExecutor(workbook: Workbook): WorkbookExecutor;
+export {};
+//# sourceMappingURL=executor.d.ts.map

package/dist/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,QAAQ,EAER,aAAa,EAGb,SAAS,EACV,MAAM,SAAS,CAAC;AAKjB;;GAEG;AACH,KAAK,YAAY,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAEnD;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,KAAK,CAAkB;IAC/B,OAAO,CAAC,OAAO,CAAmC;IAClD,OAAO,CAAC,QAAQ,CAAsB;IAEtC,YAAY,QAAQ,EAAE,QAAQ,EAG7B;IAED;;OAEG;IACH,EAAE,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,IAAI,CAQpC;IAED;;OAEG;IACH,OAAO,CAAC,IAAI;IAMZ;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAS5B;IAED;;OAEG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAgD9C;IAED;;OAEG;YACW,WAAW;IAiBzB;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU;IAelB;;;;;;OAMG;YACW,WAAW;IAIzB;;;;;OAKG;YACW,WAAW;IAQzB;;;;OAIG;YACW,WAAW;IAKzB;;;;;;;;OAQG;IACH;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE/C;IAEK,SAAS,CAAC,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;KAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CAwDzF;IAED;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEjC;CACF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,gBAAgB,CAEnE"}

package/dist/formatter.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Human-readable rendering of cell results for terminal output.
+ *
+ * `formatResult` is called inside the executor's continue-on-error loop, so it
+ * MUST NOT throw — circular references, BigInt, and unserializable values all
+ * fall back to safe markers rather than crashing the run.
+ */
+export declare function formatResult(value: unknown): string;
+//# sourceMappingURL=formatter.d.ts.map

package/dist/formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.d.ts","sourceRoot":"","sources":["../src/formatter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAkDH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CA8BnD"}

package/dist/fs-atomic.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Atomic file write shared by the CLI write commands and the serve session.
+ */
+/**
+ * Write `content` to `file` atomically: write a uniquely-named sibling temp
+ * file (exclusive create, so a pre-planted symlink can't be hijacked), then
+ * rename over the target (atomic on the same filesystem; replaces a symlink
+ * rather than writing through it). On any failure the temp file is removed.
+ */
+export declare function writeFileAtomic(file: string, content: string): void;
+//# sourceMappingURL=fs-atomic.d.ts.map

package/dist/fs-atomic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-atomic.d.ts","sourceRoot":"","sources":["../src/fs-atomic.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAanE"}

package/dist/graph.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Dependency graph management
+ */
+import type { Cell, DependencyGraph, DependencyNode } from './types';
+/**
+ * Build dependency graph from cells
+ */
+export declare function buildDependencyGraph(cells: Cell[]): DependencyGraph;
+/**
+ * Topological sort for execution order
+ */
+export declare function topologicalSort(nodes: Map<string, DependencyNode>): string[];
+/**
+ * Get all cells that depend on a given cell
+ */
+export declare function getDependents(graph: DependencyGraph, cellId: string): string[];
+/**
+ * All transitive dependencies of `id` plus `id` itself (its ancestor closure).
+ * Used to run a single cell together with everything it needs. Cycle-safe via
+ * a visited set; returns `[]` if `id` is not in the graph.
+ */
+export declare function getAncestors(graph: DependencyGraph, id: string): string[];
+/**
+ * Render the dependency graph as a Mermaid `graph TD` diagram.
+ *
+ * Cell ids are validated identifiers (`[A-Za-z_][A-Za-z0-9_]*`), so they are
+ * safe to use verbatim as both the node id and its quoted label — Mermaid
+ * syntax injection is impossible and no cell content appears in the output.
+ */
+export declare function toMermaid(graph: DependencyGraph): string;
+/**
+ * Render the dependency graph as Graphviz DOT (the DOT analog of toMermaid).
+ * Cell ids are validated identifiers ([A-Za-z_][A-Za-z0-9_]*), safe verbatim as
+ * both node id and quoted label; no cell content appears in the output.
+ */
+export declare function toDOT(graph: DependencyGraph): string;
+/**
+ * Detect circular dependencies
+ */
+export declare function detectCycles(graph: DependencyGraph): string[][];
+//# sourceMappingURL=graph.d.ts.map

package/dist/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../src/graph.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAErE;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,eAAe,CA0BnE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,MAAM,EAAE,CAuB5E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAmB9E;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAezE;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAcxD;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAepD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,EAAE,EAAE,CAoC/D"}

package/dist/html.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Assemble a generic document structure into one self-contained HTML5 file —
+ * markdown prose, MathML equations, embedded code + outputs, test badges, and
+ * (pre-rendered) charts, with an inlined stylesheet (no external requests).
+ *
+ * Operates on a plain `RenderDoc` (not the workbook's `Workbook` type) to avoid
+ * a dependency inversion. `parse` is injected by the caller (the assembled
+ * `parse` lives in the functions package) to render equation expressions; cell
+ * outputs are pre-formatted strings supplied by the caller. All user content is
+ * HTML-escaped before embedding.
+ */
+export interface RenderCell {
+    type: string;
+    content: string;
+    id?: string;
+    /** Pre-formatted output string (the caller formats values); omitted if none. */
+    output?: string;
+    error?: string;
+    /** For `test` cells: whether the assertion passed. */
+    passed?: boolean;
+    /** For `chart` cells: pre-rendered inline SVG. */
+    chartSvg?: string;
+    /** For `chart` cells in a TeX export: pre-rendered embeddable TikZ. */
+    chartTikz?: string;
+    /** Optional diagnostic note (e.g. a chart whose data didn't resolve). */
+    note?: string;
+}
+export interface RenderDoc {
+    title?: string;
+    author?: string;
+    description?: string;
+    tags?: string[];
+    cells: RenderCell[];
+}
+export interface ToHtmlOptions {
+    /** Parser for equation expressions (e.g. the functions package `parse`). */
+    parse?: (expr: string) => unknown;
+}
+/** A small static stylesheet (explicit colors, system fonts — no external assets). */
+export declare function toCSS(): string;
+/** Render a generic document structure to a self-contained HTML5 string. */
+export declare function toHTML(doc: RenderDoc, options?: ToHtmlOptions): string;
+//# sourceMappingURL=html.d.ts.map

package/dist/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../src/html.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CACnC;AAyED,sFAAsF;AACtF,wBAAgB,KAAK,IAAI,MAAM,CA8B9B;AAED,4EAA4E;AAC5E,wBAAgB,MAAM,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CA6B1E"}