@texuli/core 0.7.0 → 0.8.0

package/dist/expression/text.js

@@ -0,0 +1,489 @@
+import { parseExpression } from "./parse.js";
+import { EXPRESSION_LIMITS, } from "./types.js";
+class TextSyntaxError extends Error {
+    code;
+    at;
+    constructor(code, at, message) {
+        super(message);
+        this.code = code;
+        this.at = at;
+    }
+}
+const OPERATORS = [
+    '==',
+    '!=',
+    '<>',
+    '<=',
+    '>=',
+    '&&',
+    '||',
+    '<',
+    '>',
+    '=',
+    '!',
+    '+',
+    '-',
+    '*',
+    '/',
+    '%',
+    '^',
+    '&',
+    '(',
+    ')',
+    ',',
+];
+const ESCAPES = { n: '\n', t: '\t', r: '\r' };
+function isDigit(code) {
+    return code >= 48 && code <= 57;
+}
+function isNameStart(code) {
+    return (code >= 65 && code <= 90) || (code >= 97 && code <= 122) || code === 95;
+}
+function tokenize(source) {
+    const tokens = [];
+    let i = 0;
+    while (i < source.length) {
+        const code = source.charCodeAt(i);
+        if (code === 32 || code === 9 || code === 10 || code === 13) {
+            i += 1;
+            continue;
+        }
+        const start = i;
+        if (isDigit(code) || (code === 46 && isDigit(source.charCodeAt(i + 1)))) {
+            while (isDigit(source.charCodeAt(i)))
+                i += 1;
+            if (source[i] === '.') {
+                i += 1;
+                while (isDigit(source.charCodeAt(i)))
+                    i += 1;
+            }
+            if (source[i] === 'e' || source[i] === 'E') {
+                let j = i + 1;
+                if (source[j] === '+' || source[j] === '-')
+                    j += 1;
+                if (isDigit(source.charCodeAt(j))) {
+                    i = j;
+                    while (isDigit(source.charCodeAt(i)))
+                        i += 1;
+                }
+            }
+            const text = source.slice(start, i);
+            const value = Number(text);
+            if (!Number.isFinite(value))
+                throw new TextSyntaxError('syntax', start, 'Number out of range.');
+            tokens.push({ kind: 'num', text, value, at: start });
+            continue;
+        }
+        if (code === 34 || code === 39) {
+            const quote = source[i];
+            i += 1;
+            let out = '';
+            let closed = false;
+            while (i < source.length) {
+                const ch = source[i];
+                if (ch === quote) {
+                    closed = true;
+                    i += 1;
+                    break;
+                }
+                if (ch === '\\') {
+                    const next = source[i + 1];
+                    if (next === undefined)
+                        break;
+                    out += ESCAPES[next] ?? next;
+                    i += 2;
+                    continue;
+                }
+                out += ch;
+                i += 1;
+            }
+            if (!closed)
+                throw new TextSyntaxError('syntax', start, 'Unterminated string.');
+            if (out.length > EXPRESSION_LIMITS.stringLength) {
+                throw new TextSyntaxError('too-long', start, 'String too long.');
+            }
+            tokens.push({ kind: 'str', text: source.slice(start, i), value: out, at: start });
+            continue;
+        }
+        if (isNameStart(code)) {
+            while (i < source.length) {
+                const c = source.charCodeAt(i);
+                if (!isNameStart(c) && !isDigit(c))
+                    break;
+                i += 1;
+            }
+            tokens.push({ kind: 'name', text: source.slice(start, i), at: start });
+            continue;
+        }
+        const op = OPERATORS.find((candidate) => source.startsWith(candidate, i));
+        if (!op) {
+            throw new TextSyntaxError('syntax', start, `Unexpected character "${source[i]}".`);
+        }
+        tokens.push({ kind: 'op', text: op, at: start });
+        i += op.length;
+    }
+    tokens.push({ kind: 'end', text: '', at: source.length });
+    return tokens;
+}
+const COMPARE = {
+    '==': 'eq',
+    '=': 'eq',
+    '!=': 'neq',
+    '<>': 'neq',
+    '<': 'lt',
+    '<=': 'lte',
+    '>': 'gt',
+    '>=': 'gte',
+};
+/** Names that are syntax, not fields. */
+const KEYWORDS = new Set(['and', 'or', 'not', 'true', 'false', 'null']);
+function build(tokens) {
+    let index = 0;
+    let level = 0;
+    let nodes = 0;
+    const peek = () => tokens[index];
+    const take = () => tokens[index++];
+    const isOp = (text) => peek().kind === 'op' && peek().text === text;
+    const isWord = (text) => peek().kind === 'name' && peek().text === text;
+    const expect = (text) => {
+        if (!isOp(text))
+            throw new TextSyntaxError('syntax', peek().at, `Expected "${text}".`);
+        take();
+    };
+    const node = (value) => {
+        nodes += 1;
+        if (nodes > EXPRESSION_LIMITS.nodes) {
+            throw new TextSyntaxError('too-many-nodes', peek().at, `An expression has at most ${EXPRESSION_LIMITS.nodes} nodes.`);
+        }
+        return value;
+    };
+    const enter = () => {
+        level += 1;
+        if (level > EXPRESSION_LIMITS.depth) {
+            throw new TextSyntaxError('too-deep', peek().at, `Expressions nest at most ${EXPRESSION_LIMITS.depth} levels.`);
+        }
+    };
+    const leave = () => {
+        level -= 1;
+    };
+    // A chain of the same associative op becomes one list node.
+    const chain = (op, first, next, more) => {
+        const args = [first];
+        while (more()) {
+            take();
+            args.push(next());
+        }
+        if (args.length === 1)
+            return first;
+        // Past the argument cap, nest: (a, …, b) → op(op(a, …), …).
+        let current = args.slice(0, EXPRESSION_LIMITS.args);
+        let rest = args.slice(EXPRESSION_LIMITS.args);
+        let out = node({ op, args: current });
+        while (rest.length > 0) {
+            current = [out, ...rest.slice(0, EXPRESSION_LIMITS.args - 1)];
+            rest = rest.slice(EXPRESSION_LIMITS.args - 1);
+            out = node({ op, args: current });
+        }
+        return out;
+    };
+    const parseOr = () => chain('or', parseAnd(), parseAnd, () => isWord('or') || isOp('||'));
+    const parseAnd = () => chain('and', parseNot(), parseNot, () => isWord('and') || isOp('&&'));
+    const parseNot = () => {
+        if (isWord('not') || isOp('!')) {
+            take();
+            enter();
+            const value = parseNot();
+            leave();
+            return node({ op: 'not', value });
+        }
+        return parseCompare();
+    };
+    const parseCompare = () => {
+        const left = parseConcat();
+        const token = peek();
+        const op = token.kind === 'op' ? COMPARE[token.text] : undefined;
+        if (!op)
+            return left;
+        take();
+        const right = parseConcat();
+        const after = peek();
+        if (after.kind === 'op' && COMPARE[after.text]) {
+            throw new TextSyntaxError('syntax', after.at, 'Comparisons do not chain; use "and".');
+        }
+        return node({ op, left, right });
+    };
+    const parseConcat = () => chain('concat', parseSum(), parseSum, () => isOp('&'));
+    const parseSum = () => {
+        let left = parseProduct();
+        while (isOp('+') || isOp('-')) {
+            const op = take().text === '+' ? 'add' : 'sub';
+            left = node({ op, left, right: parseProduct() });
+        }
+        return left;
+    };
+    const parseProduct = () => {
+        let left = parseUnary();
+        while (isOp('*') || isOp('/') || isOp('%')) {
+            const text = take().text;
+            const op = text === '*' ? 'mul' : text === '/' ? 'div' : 'mod';
+            left = node({ op, left, right: parseUnary() });
+        }
+        return left;
+    };
+    const parseUnary = () => {
+        if (isOp('-')) {
+            take();
+            enter();
+            const value = parseUnary();
+            leave();
+            return node({ op: 'neg', value });
+        }
+        if (isOp('+')) {
+            take();
+            enter();
+            const value = parseUnary();
+            leave();
+            return value;
+        }
+        return parsePower();
+    };
+    const parsePower = () => {
+        const base = parsePrimary();
+        if (!isOp('^'))
+            return base;
+        take();
+        enter();
+        const exponent = parseUnary();
+        leave();
+        return node({ op: 'pow', base, exponent });
+    };
+    const parseArgs = () => {
+        expect('(');
+        const args = [];
+        if (isOp(')')) {
+            take();
+            return args;
+        }
+        enter();
+        for (;;) {
+            args.push(parseOr());
+            if (args.length > EXPRESSION_LIMITS.args) {
+                throw new TextSyntaxError('syntax', peek().at, `At most ${EXPRESSION_LIMITS.args} arguments.`);
+            }
+            if (isOp(',')) {
+                take();
+                continue;
+            }
+            break;
+        }
+        leave();
+        expect(')');
+        return args;
+    };
+    const parsePrimary = () => {
+        const token = take();
+        if (token.kind === 'num')
+            return node({ op: 'num', value: token.value });
+        if (token.kind === 'str')
+            return node({ op: 'str', value: token.value });
+        if (token.kind === 'op' && token.text === '(') {
+            enter();
+            const inner = parseOr();
+            leave();
+            expect(')');
+            return inner;
+        }
+        if (token.kind === 'name') {
+            if (token.text === 'true' || token.text === 'false') {
+                return node({ op: 'bool', value: token.text === 'true' });
+            }
+            if (token.text === 'null')
+                return node({ op: 'null' });
+            if (KEYWORDS.has(token.text)) {
+                throw new TextSyntaxError('syntax', token.at, `Unexpected "${token.text}".`);
+            }
+            if (!isOp('('))
+                return node({ op: 'field', name: token.text });
+            const args = parseArgs();
+            return call(token, args);
+        }
+        throw new TextSyntaxError('syntax', token.at, token.kind === 'end' ? 'Unexpected end of expression.' : `Unexpected "${token.text}".`);
+    };
+    const call = (token, args) => {
+        const name = token.text;
+        const arity = (min, max) => {
+            if (args.length < min || args.length > max) {
+                throw new TextSyntaxError('arity', token.at, min === max
+                    ? `"${name}" takes ${min} arguments.`
+                    : `"${name}" takes ${min} to ${max} arguments.`);
+            }
+        };
+        switch (name) {
+            case 'if': {
+                arity(3, 3);
+                const [test, ifTrue, ifFalse] = args;
+                return node({ op: 'if', test, ifTrue, ifFalse });
+            }
+            case 'min':
+            case 'max':
+            case 'concat':
+                arity(1, EXPRESSION_LIMITS.args);
+                return node({ op: name, args });
+            case 'clamp': {
+                arity(3, 3);
+                const [value, min, max] = args;
+                return node({ op: 'clamp', value, min, max });
+            }
+            case 'round': {
+                arity(1, 2);
+                const [value, digits] = args;
+                if (!digits)
+                    return node({ op: 'round', value });
+                const literal = digits.op === 'num'
+                    ? digits.value
+                    : digits.op === 'neg' && digits.value.op === 'num'
+                        ? -digits.value.value
+                        : undefined;
+                if (literal === undefined) {
+                    throw new TextSyntaxError('syntax', token.at, '"round" digits must be a number literal.');
+                }
+                return node({ op: 'round', value, digits: literal });
+            }
+            default:
+                return node({ op: 'call', fn: name, args });
+        }
+    };
+    const tree = parseOr();
+    const rest = peek();
+    if (rest.kind !== 'end')
+        throw new TextSyntaxError('syntax', rest.at, `Unexpected "${rest.text}".`);
+    return tree;
+}
+/**
+ * Parse expression text (`age >= 18 and country == "CO"`) into a validated
+ * expression. Names read fields (`{ op: "field" }`); `if`, `min`, `max`,
+ * `concat`, `round` and `clamp` map to their AST ops, and other calls must
+ * be in the function table. Never throws.
+ */
+export function parseExpressionText(source, options = {}) {
+    const fail = (code, at, message) => Object.freeze({
+        ok: false,
+        expression: null,
+        diagnostics: Object.freeze([Object.freeze({ code, path: `@${at}`, message })]),
+    });
+    if (typeof source !== 'string')
+        return fail('syntax', 0, 'Expression text is a string.');
+    if (source.length > EXPRESSION_LIMITS.sourceLength) {
+        return fail('too-long', 0, `Expression text is at most ${EXPRESSION_LIMITS.sourceLength} characters.`);
+    }
+    let tree;
+    try {
+        tree = build(tokenize(source));
+    }
+    catch (error) {
+        if (error instanceof TextSyntaxError)
+            return fail(error.code, error.at, error.message);
+        return fail('syntax', 0, 'Unreadable expression.');
+    }
+    return parseExpression(tree, options);
+}
+const PRECEDENCE = {
+    or: 1,
+    and: 2,
+    not: 3,
+    lt: 4,
+    lte: 4,
+    gt: 4,
+    gte: 4,
+    eq: 4,
+    neq: 4,
+    concat: 5,
+    add: 6,
+    sub: 6,
+    mul: 7,
+    div: 7,
+    mod: 7,
+    neg: 8,
+    pow: 9,
+};
+const SYMBOL = {
+    lt: '<',
+    lte: '<=',
+    gt: '>',
+    gte: '>=',
+    eq: '==',
+    neq: '!=',
+    add: '+',
+    sub: '-',
+    mul: '*',
+    div: '/',
+    mod: '%',
+    pow: '^',
+};
+function quote(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\t/g, '\\t').replace(/\r/g, '\\r')}"`;
+}
+/**
+ * Print an AST as expression text that parses back to an equivalent
+ * expression (`var` prints as a plain name, which reads back as `field`;
+ * `ref` and `range` print their dialect text).
+ */
+export function formatExpression(ast) {
+    const wrap = (child, parent, right = false) => {
+        const own = PRECEDENCE[child.op] ?? 10;
+        const text = formatExpression(child);
+        return own < parent || (right && own === parent) ? `(${text})` : text;
+    };
+    switch (ast.op) {
+        case 'num':
+            return ast.value < 0 ? `(${String(ast.value)})` : String(ast.value);
+        case 'str':
+            return quote(ast.value);
+        case 'bool':
+            return String(ast.value);
+        case 'null':
+            return 'null';
+        case 'var':
+        case 'field':
+            return ast.name;
+        case 'ref':
+            return ast.ref;
+        case 'range':
+            return `${ast.from}:${ast.to}`;
+        case 'and':
+        case 'or':
+            return ast.args
+                .map((arg) => wrap(arg, PRECEDENCE[ast.op] + 1))
+                .join(` ${ast.op} `);
+        case 'concat':
+            return ast.args.length === 1
+                ? `concat(${formatExpression(ast.args[0])})`
+                : ast.args.map((arg) => wrap(arg, 6)).join(' & ');
+        case 'not':
+            return `not ${wrap(ast.value, 3)}`;
+        case 'neg':
+            return `-${wrap(ast.value, 8)}`;
+        case 'pow':
+            return `${wrap(ast.base, 10)} ^ ${wrap(ast.exponent, 8)}`;
+        case 'if':
+            return `if(${formatExpression(ast.test)}, ${formatExpression(ast.ifTrue)}, ${formatExpression(ast.ifFalse)})`;
+        case 'min':
+        case 'max':
+            return `${ast.op}(${ast.args.map(formatExpression).join(', ')})`;
+        case 'round':
+            return ast.digits === undefined
+                ? `round(${formatExpression(ast.value)})`
+                : `round(${formatExpression(ast.value)}, ${ast.digits})`;
+        case 'clamp':
+            return `clamp(${formatExpression(ast.value)}, ${formatExpression(ast.min)}, ${formatExpression(ast.max)})`;
+        case 'call':
+            return `${ast.fn}(${ast.args.map(formatExpression).join(', ')})`;
+        default: {
+            const own = PRECEDENCE[ast.op];
+            const symbol = SYMBOL[ast.op];
+            const node = ast;
+            const comparison = own === 4;
+            return `${wrap(node.left, comparison ? 5 : own)} ${symbol} ${wrap(node.right, comparison ? 5 : own, true)}`;
+        }
+    }
+}

package/dist/expression/types.d.ts

@@ -0,0 +1,197 @@
+/**
+ * The closed expression language of ADR-015: one JSON AST, one bounded
+ * evaluator. Every node names its operation in `op`. The base is the
+ * blueprint spec's `numberFormula` and `condition` shapes (ADR-008), which
+ * stay valid expressions; the extensions add strings, booleans, null,
+ * field references, calls to a closed function table, and the `ref` and
+ * `range` reference nodes a dialect (the planned sheets formula layer) can
+ * enable. There is no loop, no closure, no dynamic reference and no way to
+ * reach host objects.
+ */
+/** Binary arithmetic. */
+export type ExpressionArithmeticOp = 'add' | 'sub' | 'mul' | 'div' | 'mod';
+/** Comparisons; numbers compare numerically, strings by code unit (so ISO dates sort). */
+export type ExpressionComparisonOp = 'lt' | 'lte' | 'gt' | 'gte' | 'eq' | 'neq';
+/** One node of the closed expression AST. */
+export type ExpressionNode = {
+    readonly op: 'num';
+    readonly value: number;
+} | {
+    readonly op: 'str';
+    readonly value: string;
+} | {
+    readonly op: 'bool';
+    readonly value: boolean;
+} | {
+    readonly op: 'null';
+} | {
+    readonly op: 'var';
+    readonly name: string;
+} | {
+    readonly op: 'field';
+    readonly name: string;
+} | {
+    readonly op: 'ref';
+    readonly ref: string;
+} | {
+    readonly op: 'range';
+    readonly from: string;
+    readonly to: string;
+} | {
+    readonly op: ExpressionArithmeticOp;
+    readonly left: ExpressionNode;
+    readonly right: ExpressionNode;
+} | {
+    readonly op: 'pow';
+    readonly base: ExpressionNode;
+    readonly exponent: ExpressionNode;
+} | {
+    readonly op: 'neg';
+    readonly value: ExpressionNode;
+} | {
+    readonly op: ExpressionComparisonOp;
+    readonly left: ExpressionNode;
+    readonly right: ExpressionNode;
+} | {
+    readonly op: 'and' | 'or';
+    readonly args: readonly ExpressionNode[];
+} | {
+    readonly op: 'not';
+    readonly value: ExpressionNode;
+} | {
+    readonly op: 'if';
+    readonly test: ExpressionNode;
+    readonly ifTrue: ExpressionNode;
+    readonly ifFalse: ExpressionNode;
+} | {
+    readonly op: 'min' | 'max' | 'concat';
+    readonly args: readonly ExpressionNode[];
+} | {
+    readonly op: 'round';
+    readonly value: ExpressionNode;
+    readonly digits?: number;
+} | {
+    readonly op: 'clamp';
+    readonly value: ExpressionNode;
+    readonly min: ExpressionNode;
+    readonly max: ExpressionNode;
+} | {
+    readonly op: 'call';
+    readonly fn: string;
+    readonly args: readonly ExpressionNode[];
+};
+/** Every `op` the AST knows. */
+export type ExpressionOp = ExpressionNode['op'];
+/** The error codes an evaluation can produce (spreadsheet-style values, never exceptions). */
+export type ExpressionErrorCode = '#DIV/0!' | '#VALUE!' | '#REF!' | '#NAME?' | '#NUM!' | '#N/A' | '#CYCLE!' | '#LIMIT!';
+/** An error value. Errors propagate through operators and calls. */
+export interface ExpressionError {
+    readonly error: ExpressionErrorCode;
+}
+/** A scalar value. Dates are ISO `YYYY-MM-DD` strings. */
+export type ExpressionScalar = number | string | boolean | null;
+/**
+ * A value an expression reads or produces: a scalar, a flat list of scalars
+ * (multiple-choice answers, a sheet range) or an error.
+ */
+export type ExpressionValue = ExpressionScalar | readonly ExpressionScalar[] | ExpressionError;
+/** The static types the analyzer knows. `any` accepts everything. */
+export type ExpressionType = 'number' | 'string' | 'boolean' | 'date' | 'list' | 'null' | 'any';
+/** What a function receives besides its arguments. */
+export interface ExpressionFunctionContext {
+    /**
+     * Charge `steps` evaluation steps (for work proportional to input size).
+     * Returns `false` once the budget is spent; return `#LIMIT!` then.
+     */
+    charge(steps: number): boolean;
+    /** The host clock in milliseconds, or `undefined` when the host gave none. */
+    now(): number | undefined;
+}
+/**
+ * One entry of a closed function table. Arguments arrive evaluated; an error
+ * argument short-circuits the call unless `acceptsErrors` is set. `call`
+ * must be pure, bounded and total: a thrown exception becomes `#VALUE!`.
+ */
+export interface ExpressionFunction {
+    readonly minArgs: number;
+    readonly maxArgs: number;
+    /** Parameter types by position; the last one repeats for variadic functions. */
+    readonly params: readonly ExpressionType[];
+    readonly returns: ExpressionType;
+    /** Pass error arguments through instead of short-circuiting (for an `IFERROR`). */
+    readonly acceptsErrors?: boolean;
+    readonly description?: string;
+    call(args: readonly ExpressionValue[], context: ExpressionFunctionContext): ExpressionValue;
+}
+/** A closed function table: names to functions. Expressions can only name these. */
+export type ExpressionFunctionTable = Readonly<Record<string, ExpressionFunction>>;
+/** A problem with an expression, addressed like authoring diagnostics. */
+export interface ExpressionDiagnostic {
+    readonly code: ExpressionDiagnosticCode;
+    /** A JSON path into the AST (`$.args[0].left`) or a text offset (`@12`). */
+    readonly path: string;
+    readonly message: string;
+}
+export type ExpressionDiagnosticCode = 'not-a-node' | 'unknown-op' | 'unknown-member' | 'missing-member' | 'bad-member' | 'bad-name' | 'unknown-function' | 'arity' | 'refs-disabled' | 'bad-ref' | 'too-many-nodes' | 'too-deep' | 'too-long' | 'syntax' | 'unknown-field' | 'type';
+/**
+ * Lets a dialect enable `ref` and `range` nodes. The forms dialect leaves it
+ * out (references are refused); the planned sheets formula layer passes a
+ * checker for its reference syntax.
+ */
+export interface ExpressionReferenceDialect {
+    /** Whether `ref` is a reference this dialect accepts (for example `A1` or `Sheet2!B3`). */
+    isRef(ref: string): boolean;
+}
+/** A validated, frozen expression: the AST plus what it depends on. */
+export interface Expression {
+    readonly ast: ExpressionNode;
+    /** Node count (at most `EXPRESSION_LIMITS.nodes`). */
+    readonly nodes: number;
+    /** Nesting depth (at most `EXPRESSION_LIMITS.depth`). */
+    readonly depth: number;
+    /** Field and var names read, sorted and unique. */
+    readonly fields: readonly string[];
+    /** Function names called, sorted and unique. */
+    readonly functions: readonly string[];
+    /** `ref` nodes, sorted and unique (empty unless a dialect enabled them). */
+    readonly refs: readonly string[];
+    /** `range` nodes in source order (an interval each, never expanded). */
+    readonly ranges: readonly {
+        readonly from: string;
+        readonly to: string;
+    }[];
+}
+export type ExpressionParseResult = {
+    readonly ok: true;
+    readonly expression: Expression;
+    readonly diagnostics: readonly [];
+} | {
+    readonly ok: false;
+    readonly expression: null;
+    readonly diagnostics: readonly ExpressionDiagnostic[];
+};
+/** The limits of ADR-015. Exceeding one is a diagnostic at parse time or `#LIMIT!` at run time. */
+export declare const EXPRESSION_LIMITS: Readonly<{
+    /** AST nodes per expression. */
+    nodes: 1000;
+    /** Nesting depth per expression. */
+    depth: 32;
+    /** Evaluation steps per expression. */
+    steps: 100000;
+    /** Evaluation steps per recalculation pass (an `ExpressionBudget`). */
+    passSteps: 10000000;
+    /** UTF-16 code units in any string value. */
+    stringLength: 32768;
+    /** Items in any list value. */
+    listItems: 10000;
+    /** Characters of expression text the text parser reads. */
+    sourceLength: 16384;
+    /** Arguments of one `and`, `or`, `min`, `max`, `concat` or `call`. */
+    args: 64;
+    /** Largest absolute `pow` exponent. */
+    exponent: 64;
+    /** `round` digits range (±). */
+    roundDigits: 12;
+}>;
+/** Field, var and function names: a letter or underscore, then letters, digits or underscores. */
+export declare const EXPRESSION_NAME: RegExp;