@tinta-lang/engine 0.0.0-stage → 0.1.0-dev.0

package/dist/analysis.d.ts

@@ -0,0 +1,8 @@
+import type { Program } from "@tinta-lang/types";
+import type { EditorType } from "@tinta-lang/types/editor";
+export interface AnalyzedBinding {
+    readonly name: string;
+    readonly type: EditorType;
+}
+/** Read-only compiler facts; never expose the private binding maps or alter IR. */
+export declare function analyzeProgram(program: Program): readonly AnalyzedBinding[];

package/dist/analysis.js

@@ -0,0 +1,19 @@
+import { freeze } from "./common.js";
+import { programs } from "./programs.js";
+/** Read-only compiler facts; never expose the private binding maps or alter IR. */
+export function analyzeProgram(program) {
+    const bound = programs.get(program);
+    if (!bound)
+        throw new TypeError("Expected a compiled or decoded program.");
+    return freeze(program.declarations.map(({ name }) => {
+        const type = bound.types.get(name);
+        return {
+            name,
+            type: typeof type !== "string"
+                ? { kind: "table", columns: type.map((column) => ({ ...column })) }
+                : type.startsWith("list:")
+                    ? { kind: "list", scalar: type.slice(5) }
+                    : { kind: "scalar", scalar: type },
+        };
+    }));
+}

package/dist/binding.d.ts

@@ -0,0 +1,15 @@
+import type { ControlDefinition, Declaration, DocNode, Expr, ProgramIR, Span } from "@tinta-lang/types";
+import { Budget } from "./common.js";
+import { type RuntimeValue, type Type } from "./expression.js";
+export interface Bound {
+    readonly types: ReadonlyMap<string, Type>;
+    readonly compileOperations: number;
+    readonly locations: ReadonlyMap<string, Span>;
+    readonly order: readonly Declaration[];
+    readonly controls: ReadonlyMap<string, ControlDefinition>;
+    readonly constants: ReadonlyMap<string, RuntimeValue>;
+    readonly limits: Readonly<Record<string, number>>;
+}
+export declare function walkFlow(nodes: readonly DocNode[], visit: (node: DocNode) => void): void;
+export declare function references(expr: Expr): Expr[];
+export declare function bind(ir: ProgramIR, budget: Budget, locations: ReadonlyMap<string, Span>): Bound;

package/dist/binding.js

@@ -0,0 +1,292 @@
+import { Budget, Failure, fail } from "./common.js";
+import { evaluate, infer } from "./expression.js";
+export function walkFlow(nodes, visit) {
+    for (const node of nodes) {
+        visit(node);
+        if ("children" in node)
+            walkFlow(node.children, visit);
+        if (node.kind === "list")
+            node.items.forEach((item) => walkFlow(item.children, visit));
+        if (node.kind === "markdown-table")
+            [...node.header, ...node.rows.flat()].forEach((cell) => walkFlow(cell, visit));
+    }
+}
+export function references(expr) {
+    if (expr.kind === "name")
+        return [expr];
+    if (expr.kind === "binary")
+        return [...references(expr.left), ...references(expr.right)];
+    if (expr.kind === "unary")
+        return references(expr.operand);
+    if (expr.kind === "call")
+        return expr.arguments.flatMap(references);
+    if (expr.kind === "list")
+        return expr.items.flatMap(references);
+    return [];
+}
+export function bind(ir, budget, locations) {
+    const symbols = new Map();
+    const controls = new Map();
+    const order = [];
+    const types = new Map();
+    const diagnostics = [];
+    const nameSpan = (d) => {
+        const offset = ir.source
+            .slice(d.span.start.offset, d.span.end.offset)
+            .indexOf(d.name, d.kind.length + 1);
+        const start = {
+            ...d.span.start,
+            offset: d.span.start.offset + offset,
+            column: d.span.start.column + offset,
+        };
+        return {
+            uri: d.span.uri,
+            start,
+            end: {
+                ...start,
+                offset: start.offset + d.name.length,
+                column: start.column + d.name.length,
+            },
+        };
+    };
+    const report = (code, span, related = []) => {
+        diagnostics.push({
+            code,
+            severity: "error",
+            phase: "bind",
+            message: code === "E_CYCLE"
+                ? "A dependency cycle prevents evaluation."
+                : code === "E_NAME_DUPLICATE"
+                    ? "A name is declared more than once."
+                    : "A global reference cannot be resolved.",
+            span,
+            related,
+        });
+    };
+    const finish = () => {
+        if (!diagnostics.length)
+            return;
+        diagnostics.sort((a, b) => a.span.start.offset - b.span.start.offset ||
+            a.code.localeCompare(b.code, "en"));
+        const maximum = budget.limits.diagnostics;
+        if (diagnostics.length > maximum) {
+            const observed = diagnostics.length;
+            diagnostics.splice(maximum - 1);
+            diagnostics.push({
+                code: "E_LIMIT",
+                severity: "error",
+                phase: "bind",
+                message: "The diagnostic limit was exceeded.",
+                span: budget.span,
+                details: { limitName: "diagnostics", observed, maximum },
+            });
+        }
+        throw new Failure(diagnostics);
+    };
+    budget.limit("declarations", ir.declarations.length);
+    for (const d of ir.declarations) {
+        const previous = symbols.get(d.name);
+        if (previous) {
+            report("E_NAME_DUPLICATE", nameSpan(d), [
+                { message: "First declaration.", span: nameSpan(previous) },
+            ]);
+            continue;
+        }
+        symbols.set(d.name, d);
+        if (d.kind === "slider" || d.kind === "choice" || d.kind === "toggle")
+            controls.set(d.name, d);
+    }
+    budget.limit("controls", controls.size);
+    budget.limit("tableCount", ir.declarations.filter((d) => d.kind === "data" || d.kind === "view")
+        .length);
+    const graph = new Map();
+    for (const d of symbols.values()) {
+        const refs = [];
+        if (d.kind === "view")
+            refs.push({ name: d.source, span: d.span });
+        const expr = "expression" in d
+            ? d.expression
+            : d.kind === "view"
+                ? d.where
+                : undefined;
+        if (expr)
+            for (const ref of references(expr))
+                if (ref.kind === "name")
+                    refs.push(ref);
+        const edges = [];
+        for (const ref of refs) {
+            budget.charge(ref.span);
+            if (!symbols.has(ref.name))
+                report("E_NAME_UNKNOWN", ref.span);
+            else
+                edges.push(ref.name);
+        }
+        graph.set(d.name, edges);
+    }
+    // Tarjan's stack identifies every component, including inactive branches.
+    const indices = new Map(), low = new Map();
+    const stack = [], onStack = new Set();
+    function component(name) {
+        const index = indices.size;
+        indices.set(name, index);
+        low.set(name, index);
+        stack.push(name);
+        onStack.add(name);
+        for (const edge of graph.get(name)) {
+            if (!indices.has(edge)) {
+                component(edge);
+                low.set(name, Math.min(low.get(name), low.get(edge)));
+            }
+            else if (onStack.has(edge))
+                low.set(name, Math.min(low.get(name), indices.get(edge)));
+        }
+        if (low.get(name) !== index)
+            return;
+        const members = [];
+        let popped;
+        do {
+            popped = stack.pop();
+            onStack.delete(popped);
+            members.push(symbols.get(popped));
+        } while (popped !== name);
+        if (members.length > 1 || graph.get(name).includes(name)) {
+            members.sort((a, b) => a.span.start.offset - b.span.start.offset);
+            report("E_CYCLE", nameSpan(members[0]), members.map((d) => ({
+                message: "Participating declaration.",
+                span: nameSpan(d),
+            })));
+        }
+    }
+    for (const name of symbols.keys())
+        if (!indices.has(name))
+            component(name);
+    finish();
+    function declaration(name, span) {
+        budget.charge(span);
+        const d = symbols.get(name);
+        if (!d)
+            fail("E_NAME_UNKNOWN", span, "bind");
+        return d;
+    }
+    function visit(d) {
+        if (types.has(d.name))
+            return;
+        const deps = [];
+        if (d.kind === "view")
+            deps.push({ name: d.source, span: d.span });
+        const expr = "expression" in d
+            ? d.expression
+            : d.kind === "view"
+                ? d.where
+                : undefined;
+        if (expr)
+            for (const ref of references(expr))
+                if (ref.kind === "name")
+                    deps.push(ref);
+        for (const ref of deps) {
+            const target = declaration(ref.name, ref.span);
+            if (d.kind === "let" && target.kind !== "let")
+                fail("E_CONST_DEPENDENCY", ref.span, "bind");
+            visit(target);
+        }
+        const get = (name, expr) => {
+            declaration(name, expr.span);
+            return types.get(name);
+        };
+        let type;
+        if (d.kind === "slider")
+            type = "number";
+        else if (d.kind === "toggle")
+            type = "boolean";
+        else if (d.kind === "choice")
+            type = "text";
+        else if (d.kind === "data")
+            type = d.table.columns;
+        else if (d.kind === "view") {
+            type = types.get(d.source);
+            if (typeof type === "string")
+                fail("E_TYPE", d.span);
+            if (d.where && infer(d.where, get, budget, type) !== "boolean")
+                fail("E_TYPE", d.where.span);
+            if (d.sort && !type.some((c) => c.name === d.sort))
+                fail("E_COLUMN_UNKNOWN", d.span);
+        }
+        else {
+            type = infer(d.expression, get, budget);
+            if (typeof type !== "string")
+                fail("E_TYPE", d.expression.span);
+        }
+        types.set(d.name, type);
+        order.push(d);
+    }
+    ir.declarations.forEach(visit);
+    const get = (name, expr) => {
+        declaration(name, expr.span);
+        return types.get(name);
+    };
+    const schema = (name, span) => {
+        declaration(name, span);
+        const type = types.get(name);
+        if (typeof type === "string")
+            fail("E_TYPE", span);
+        return type;
+    };
+    let charts = 0;
+    walkFlow(ir.flow, (node) => {
+        budget.charge(node.span);
+        if (node.kind === "interpolation") {
+            const type = infer(node.expression, get, budget);
+            if (type !== "number" && type !== "text" && type !== "boolean")
+                fail("E_TYPE", node.expression.span);
+        }
+        if (node.kind === "when" &&
+            infer(node.condition, get, budget) !== "boolean")
+            fail("E_TYPE", node.condition.span);
+        if (node.kind === "data-table")
+            schema(node.source, node.span);
+        if (node.kind !== "chart")
+            return;
+        budget.limit("chartCount", ++charts, node.span);
+        const c = node.chart, columns = schema(c.source, c.span);
+        const x = columns.find((col) => col.name === c.x);
+        if (!x)
+            fail("E_COLUMN_UNKNOWN", locations.get(`${c.id}:option:x`));
+        if (x.type === "boolean" ||
+            ((c.kind === "scatter" || c.kind === "histogram") && x.type !== "number"))
+            fail("E_TYPE", c.span);
+        if (c.y?.kind === "columns") {
+            budget.limit("chartSeries", c.y.columns.length, c.span);
+            for (const name of c.y.columns) {
+                const col = columns.find((col) => col.name === name);
+                if (!col)
+                    fail("E_COLUMN_UNKNOWN", locations.get(`${c.id}:option:y`));
+                if (col.type !== "number")
+                    fail("E_TYPE", c.span);
+            }
+        }
+        else if (c.y && infer(c.y.expression, get, budget, columns) !== "number")
+            fail("E_TYPE", c.y.expression.span);
+        if (c.select) {
+            const target = controls.get(c.select);
+            if (!target || target.kind !== (x.type === "text" ? "choice" : "slider"))
+                fail("E_SELECTION_TARGET", c.span);
+        }
+    });
+    const constants = new Map();
+    for (const d of order)
+        if (d.kind === "let")
+            constants.set(d.name, evaluate(d.expression, {
+                get: (name) => constants.get(name),
+                metadata: ir.metadata,
+                budget,
+            }));
+    return {
+        types,
+        order,
+        controls,
+        constants,
+        limits: budget.limits,
+        locations,
+        compileOperations: budget.used,
+    };
+}

package/dist/chart-presentation.d.ts

@@ -0,0 +1,11 @@
+import type { PreparedChart } from "@tinta-lang/types";
+/** Viewport-independent presentation derivation; never changes document state. */
+export declare function numericDomain(values: readonly number[], zero?: boolean): [number, number];
+export declare function legendKey(chart: PreparedChart, index: number): string;
+export declare function chartPresentation(chart: PreparedChart, hidden?: ReadonlySet<string>): {
+    points: import("@tinta-lang/types").ChartPoint[];
+    total: number;
+    message: string;
+    xDomain: [number, number] | undefined;
+    yDomain: [number, number] | undefined;
+};

package/dist/chart-presentation.js

@@ -0,0 +1,61 @@
+/** Viewport-independent presentation derivation; never changes document state. */
+export function numericDomain(values, zero = false) {
+    let lo = Math.min(...values);
+    let hi = Math.max(...values);
+    if (zero) {
+        lo = Math.min(0, lo);
+        hi = Math.max(0, hi);
+    }
+    if (lo === hi) {
+        const delta = Math.max(1, Math.abs(lo) * 0.05);
+        lo -= delta;
+        hi += delta;
+    }
+    if (!Number.isFinite(lo) ||
+        !Number.isFinite(hi) ||
+        !Number.isFinite(hi - lo) ||
+        hi <= lo) {
+        throw new Error("E_CHART_DOMAIN");
+    }
+    return [lo, hi];
+}
+export function legendKey(chart, index) {
+    const point = chart.points[index];
+    return chart.type === "pie" || chart.type === "donut"
+        ? JSON.stringify(point.x)
+        : chart.series[point.seriesIndex].id;
+}
+export function chartPresentation(chart, hidden = new Set()) {
+    const sector = chart.type === "pie" || chart.type === "donut";
+    const points = chart.points.filter((_, i) => !hidden.has(legendKey(chart, i)));
+    const total = sector ? points.reduce((sum, point) => sum + point.y, 0) : 0;
+    if (!Number.isFinite(total))
+        throw new Error("E_CHART_DOMAIN");
+    const message = chart.empty
+        ? "No data matches the current choices."
+        : !points.length && chart.type !== "histogram"
+            ? sector
+                ? "All categories are hidden."
+                : "All series are hidden."
+            : sector && total === 0
+                ? "All visible values are zero."
+                : "";
+    const numeric = typeof chart.points[0]?.x === "number";
+    const xDomain = chart.bins.length
+        ? [chart.bins[0].lower, chart.bins[chart.bins.length - 1].upper]
+        : !sector && numeric && chart.type !== "bar" && chart.points.length
+            ? numericDomain(chart.points.map((point) => point.x))
+            : undefined;
+    const yDomain = chart.bins.length
+        ? numericDomain(chart.bins.map((bin) => bin.count), true)
+        : !sector && points.length
+            ? numericDomain(points.map((point) => point.y), chart.type === "bar" || chart.type === "area")
+            : undefined;
+    return {
+        points,
+        total,
+        message,
+        xDomain,
+        yDomain,
+    };
+}

package/dist/charts.d.ts

@@ -0,0 +1,3 @@
+import type { ChartSpec, ControlDefinition, PreparedChart, TableValue } from "@tinta-lang/types";
+import { type Environment } from "./expression.js";
+export declare function prepare(chart: ChartSpec, table: TableValue, env: Environment, controls: ReadonlyMap<string, ControlDefinition>): PreparedChart;

package/dist/charts.js

@@ -0,0 +1,139 @@
+import { fail, label } from "./common.js";
+import { evaluate } from "./expression.js";
+import { inDomain } from "./grid.js";
+import { numericDomain } from "./chart-presentation.js";
+function domain(values, zero, chart) {
+    if (!values.length)
+        return;
+    try {
+        numericDomain(values, zero);
+    }
+    catch {
+        fail("E_CHART_DOMAIN", chart.span, "evaluate");
+    }
+}
+export function prepare(chart, table, env, controls) {
+    const budget = env.budget;
+    budget.limit("chartRows", table.rows.length, chart.span);
+    const xIndex = table.columns.findIndex((c) => c.name === chart.x);
+    const numericX = table.columns[xIndex].type === "number";
+    const sector = chart.kind === "pie" || chart.kind === "donut";
+    if (sector)
+        budget.limit("chartSectors", table.rows.length, chart.span);
+    if (chart.kind === "bar" ||
+        (!numericX && (chart.kind === "line" || chart.kind === "area")))
+        budget.limit("chartCategories", table.rows.length, chart.span);
+    const rows = [...table.rows];
+    if (numericX && (chart.kind === "line" || chart.kind === "area"))
+        rows.sort((a, b) => {
+            budget.charge(chart.span);
+            return a.cells[xIndex] - b.cells[xIndex];
+        });
+    const xs = rows.map((row) => row.cells[xIndex]);
+    if (chart.kind !== "scatter" &&
+        chart.kind !== "histogram" &&
+        new Set(xs).size !== xs.length)
+        fail("E_CHART_DUPLICATE_X", chart.span, "evaluate");
+    if (chart.select)
+        for (const x of xs)
+            if (!inDomain(controls.get(chart.select), x))
+                fail("E_SELECTION_DOMAIN", chart.span, "evaluate");
+    const series = chart.y?.kind === "columns"
+        ? chart.y.columns.map((name) => ({ id: name, label: label(name) }))
+        : chart.y
+            ? [{ id: "value", label: chart.yLabel }]
+            : [];
+    const points = [];
+    const bins = [];
+    if (chart.kind === "histogram" && rows.length) {
+        const values = xs;
+        let lo = Math.min(...values), hi = Math.max(...values);
+        if (lo === hi) {
+            const delta = Math.max(0.5, Math.abs(lo) * 0.05);
+            lo -= delta;
+            hi += delta;
+        }
+        if (!Number.isFinite(lo) ||
+            !Number.isFinite(hi) ||
+            !Number.isFinite(hi - lo) ||
+            hi <= lo)
+            fail("E_CHART_DOMAIN", chart.span, "evaluate");
+        const count = chart.bins;
+        const edges = Array.from({ length: count + 1 }, (_, i) => i === 0 ? lo : i === count ? hi : lo + (i * (hi - lo)) / count);
+        for (let i = 0; i < count; i++) {
+            budget.charge(chart.span);
+            if (!Number.isFinite(edges[i + 1]) || edges[i + 1] <= edges[i])
+                fail("E_CHART_DOMAIN", chart.span, "evaluate");
+            bins.push({
+                id: `${chart.id}:bin:${i}`,
+                lower: edges[i],
+                upper: edges[i + 1],
+                upperInclusive: i === count - 1,
+                count: 0,
+            });
+        }
+        const counts = bins.map(() => 0);
+        for (const x of values) {
+            budget.charge(chart.span);
+            const index = bins.findIndex((bin) => x >= bin.lower &&
+                (x < bin.upper || (bin.upperInclusive && x === bin.upper)));
+            counts[index]++;
+        }
+        bins.forEach((bin, i) => {
+            bins[i] = { ...bin, count: counts[i] };
+        });
+    }
+    else if (chart.y) {
+        let total = 0;
+        for (const row of rows) {
+            budget.charge(chart.span);
+            const fields = new Map(table.columns.map((c, i) => [c.name, row.cells[i]]));
+            const ys = chart.y.kind === "columns"
+                ? chart.y.columns.map((name) => row.cells[table.columns.findIndex((c) => c.name === name)])
+                : [evaluate(chart.y.expression, { ...env, row: fields })];
+            ys.forEach((y, i) => {
+                budget.charge(chart.span);
+                if (!Number.isFinite(y) || (sector && y < 0))
+                    fail("E_CHART_VALUE", chart.span, "evaluate");
+                if (sector) {
+                    total += y;
+                    if (!Number.isFinite(total))
+                        fail("E_CHART_DOMAIN", chart.span, "evaluate");
+                }
+                points.push({
+                    id: `${chart.id}:${row.id}:${i}`,
+                    rowId: row.id,
+                    seriesIndex: i,
+                    x: row.cells[xIndex],
+                    y,
+                });
+            });
+        }
+        if (!sector) {
+            if (numericX && chart.kind !== "bar")
+                domain(xs, false, chart);
+            domain(points.map((p) => p.y), chart.kind === "bar" || chart.kind === "area", chart);
+            // Any series can remain visible alone after a presentation-only toggle.
+            for (let index = 0; index < series.length; index++) {
+                domain(points
+                    .filter((point) => point.seriesIndex === index)
+                    .map((point) => point.y), chart.kind === "bar" || chart.kind === "area", chart);
+            }
+        }
+    }
+    budget.limit("chartMarks", points.length + bins.length, chart.span);
+    return {
+        id: chart.id,
+        type: chart.kind,
+        title: chart.title,
+        xLabel: chart.xLabel,
+        yLabel: chart.yLabel,
+        source: chart.source,
+        ...(chart.select ? { select: chart.select } : {}),
+        series,
+        points,
+        bins,
+        table: { columns: table.columns, rows },
+        empty: rows.length === 0,
+    };
+}

package/dist/codec.d.ts

@@ -0,0 +1,3 @@
+import type { CompilerOptions, Program, ProgramIR, Result } from "@tinta-lang/types";
+export declare function decodeProgram(payload: unknown, options?: CompilerOptions): Result<Program>;
+export declare function encodeProgram(program: Program): ProgramIR;

package/dist/codec.js

@@ -0,0 +1,52 @@
+import { attempt, Budget, fail } from "./common.js";
+import { compile, programs } from "./compiler.js";
+import validate from "./program-validator.js";
+import { inspect } from "./inspect.js";
+function same(a, b, budget) {
+    budget.charge();
+    if (a === b)
+        return true;
+    if (!a || !b || typeof a !== "object" || typeof b !== "object")
+        return false;
+    const x = a, y = b;
+    return (Array.isArray(a) === Array.isArray(b) &&
+        Object.keys(x).length === Object.keys(y).length &&
+        Object.keys(x).every((key) => Object.hasOwn(y, key) && same(x[key], y[key], budget)));
+}
+export function decodeProgram(payload, options) {
+    const span = {
+        uri: "tinta:program",
+        start: { offset: 0, line: 1, column: 1 },
+        end: { offset: 0, line: 1, column: 1 },
+    };
+    const checked = attempt(() => {
+        const budget = new Budget(span, "decode", options);
+        inspect(payload, budget);
+        if (!validate(payload))
+            fail("E_PROTOCOL", span, "decode");
+        return { ir: payload, budget };
+    });
+    if (!checked.ok)
+        return checked;
+    const { ir, budget } = checked.value;
+    const compiled = compile({
+        uri: ir.sourceUri,
+        profile: ir.profile,
+        text: ir.source,
+    }, options);
+    if (!compiled.ok)
+        return compiled;
+    return attempt(() => {
+        budget.charge(span, programs.get(compiled.value).compileOperations);
+        if (ir.sourceSha256 !== compiled.value.sourceSha256)
+            fail("E_HASH_MISMATCH", span, "decode");
+        if (!same(ir, compiled.value, budget))
+            fail("E_PROTOCOL", span, "decode");
+        return compiled.value;
+    }, compiled.diagnostics);
+}
+export function encodeProgram(program) {
+    if (!programs.has(program))
+        throw new TypeError("Only validated programs can be encoded.");
+    return program;
+}

package/dist/common.d.ts

@@ -0,0 +1,24 @@
+import type { CompilerOptions, Diagnostic, Phase, Result, Span } from "@tinta-lang/types";
+import { registry } from "./registry.js";
+export declare class Failure extends Error {
+    readonly diagnostic: Diagnostic;
+    readonly diagnostics: readonly Diagnostic[];
+    constructor(input: Diagnostic | readonly Diagnostic[]);
+}
+export declare function fail(code: keyof typeof registry.errors, span: Span, phase?: Phase): never;
+export declare function orderedDiagnostics(diagnostics: readonly Diagnostic[], maximum?: number): readonly Diagnostic[];
+export declare function attempt<T>(run: () => T, diagnostics?: readonly Diagnostic[], maximumDiagnostics?: number): Result<T>;
+export declare function freeze<T>(value: T): T;
+export declare function record<T>(): Record<string, T>;
+export declare class Budget {
+    readonly span: Span;
+    readonly phase: Phase;
+    readonly limits: Record<string, number>;
+    private operations;
+    get used(): number;
+    constructor(span: Span, phase: Phase, options?: CompilerOptions);
+    limit(name: string, observed: number, span?: Span): void;
+    charge(span?: Span, amount?: number): void;
+}
+export declare const label: (name: string) => string;
+export declare const scalarType: (value: string | number | boolean) => "text" | "number" | "boolean";