@oxygen-agent/cli 1.377.3 → 1.575.19

package/node_modules/@oxygen/formula/dist/expression.js

@@ -0,0 +1,428 @@
+import { FORMULA_FUNCTION_REGISTRY, checkFormulaFunctionArity, formulaExpressionError, } from "./formula-functions.js";
+/**
+ * Functions evaluated against the whole column rather than the current scope.
+ * They are intercepted before registry dispatch (the registry entry carries
+ * metadata only) because they need a corpus the scope supplies.
+ */
+export const CROSS_ROW_FUNCTIONS = new Set(["novelty_score"]);
+export function parseFormulaExpression(expression, options = {}) {
+    const parser = new FormulaParser(tokenize(expression, options), expression);
+    return parser.parse();
+}
+/** Validate supported functions and arity on an already-parsed tree. */
+export function validateFormulaAst(ast) {
+    walkExpression(ast, (node) => {
+        if (node.type !== "call")
+            return;
+        const normalized = node.name.toLowerCase();
+        if (normalized === "novelty_score") {
+            const firstArg = node.args[0];
+            if (node.args.length !== 1
+                || !firstArg
+                || (firstArg.type !== "identifier"
+                    && !(firstArg.type === "literal" && typeof firstArg.value === "string"))) {
+                throw formulaExpressionError("novelty_score requires exactly one column argument.", {
+                    function: node.name,
+                    received: node.args.length,
+                });
+            }
+            return;
+        }
+        const spec = FORMULA_FUNCTION_REGISTRY.get(normalized);
+        if (!spec) {
+            throw formulaExpressionError("Unsupported formula function.", {
+                function: node.name,
+            });
+        }
+        checkFormulaFunctionArity(spec, node.args.length);
+    });
+}
+/** Validate syntax, supported functions, and arity without evaluating any data. */
+export function validateFormulaExpression(expression, options = {}) {
+    validateFormulaAst(parseFormulaExpression(expression, options));
+}
+export function walkExpression(node, visit) {
+    visit(node);
+    switch (node.type) {
+        case "unary":
+            walkExpression(node.argument, visit);
+            return;
+        case "binary":
+            walkExpression(node.left, visit);
+            walkExpression(node.right, visit);
+            return;
+        case "call":
+            for (const arg of node.args)
+                walkExpression(arg, visit);
+            return;
+        default:
+            return;
+    }
+}
+export function analyzeCrossRowDependencies(node) {
+    const functions = new Set();
+    const columnKeys = new Set();
+    walkExpression(node, (entry) => {
+        if (entry.type !== "call")
+            return;
+        const normalized = entry.name.toLowerCase();
+        if (!CROSS_ROW_FUNCTIONS.has(normalized))
+            return;
+        functions.add(normalized);
+        for (const arg of entry.args) {
+            if (arg.type === "identifier") {
+                columnKeys.add(arg.name);
+            }
+            else if (arg.type === "literal" && typeof arg.value === "string") {
+                columnKeys.add(arg.value);
+            }
+        }
+    });
+    return { functions: [...functions], columnKeys: [...columnKeys] };
+}
+export function analyzeFormulaCrossRowDependencies(expression) {
+    const ast = parseFormulaExpression(expression);
+    validateFormulaAst(ast);
+    return analyzeCrossRowDependencies(ast);
+}
+/**
+ * Every identifier the expression reads, plus its cross-row dependencies.
+ * Identifiers are bare names — the host decides what they bind to (a table
+ * column key today, a workflow node output tomorrow).
+ */
+export function analyzeFormulaDependencies(expression, options = {}) {
+    const ast = parseFormulaExpression(expression, options);
+    validateFormulaAst(ast);
+    const identifiers = new Set();
+    walkExpression(ast, (entry) => {
+        if (entry.type === "identifier")
+            identifiers.add(entry.name);
+    });
+    const crossRow = analyzeCrossRowDependencies(ast);
+    return {
+        identifiers: [...identifiers],
+        crossRowFunctions: [...crossRow.functions],
+        crossRowColumnKeys: [...crossRow.columnKeys],
+    };
+}
+class FormulaParser {
+    tokens;
+    expression;
+    index = 0;
+    constructor(tokens, expression) {
+        this.tokens = tokens;
+        this.expression = expression;
+    }
+    parse() {
+        const node = this.parseOr();
+        if (this.current().type !== "eof") {
+            throw this.error("Unexpected token.", this.current());
+        }
+        return node;
+    }
+    parseOr() {
+        let node = this.parseAnd();
+        while (this.matchWord("or") || this.matchOperator("||")) {
+            const operator = this.previousValue();
+            node = { type: "binary", operator: operator === "||" ? "or" : operator, left: node, right: this.parseAnd() };
+        }
+        return node;
+    }
+    parseAnd() {
+        let node = this.parseEquality();
+        while (this.matchWord("and") || this.matchOperator("&&")) {
+            const operator = this.previousValue();
+            node = { type: "binary", operator: operator === "&&" ? "and" : operator, left: node, right: this.parseEquality() };
+        }
+        return node;
+    }
+    parseEquality() {
+        let node = this.parseComparison();
+        while (this.matchOperator("=")
+            || this.matchOperator("==")
+            || this.matchOperator("!=")
+            || this.matchOperator("<>")) {
+            const operator = this.previousValue();
+            node = { type: "binary", operator, left: node, right: this.parseComparison() };
+        }
+        return node;
+    }
+    parseComparison() {
+        let node = this.parseAdditive();
+        while (this.matchOperator("<")
+            || this.matchOperator("<=")
+            || this.matchOperator(">")
+            || this.matchOperator(">=")) {
+            const operator = this.previousValue();
+            node = { type: "binary", operator, left: node, right: this.parseAdditive() };
+        }
+        return node;
+    }
+    parseAdditive() {
+        let node = this.parseMultiplicative();
+        while (this.matchOperator("+") || this.matchOperator("-")) {
+            const operator = this.previousValue();
+            node = { type: "binary", operator, left: node, right: this.parseMultiplicative() };
+        }
+        return node;
+    }
+    parseMultiplicative() {
+        let node = this.parseUnary();
+        while (this.matchOperator("*")
+            || this.matchOperator("/")
+            || this.matchOperator("%")) {
+            const operator = this.previousValue();
+            node = { type: "binary", operator, left: node, right: this.parseUnary() };
+        }
+        return node;
+    }
+    parseUnary() {
+        if (this.matchOperator("-") || this.matchOperator("+") || this.matchOperator("!") || this.matchWord("not")) {
+            const operator = this.previousValue();
+            return {
+                type: "unary",
+                operator: operator === "!" ? "not" : operator,
+                argument: this.parseUnary(),
+            };
+        }
+        return this.parsePrimary();
+    }
+    parsePrimary() {
+        const token = this.current();
+        if (token.type === "number") {
+            this.advance();
+            return { type: "literal", value: token.value };
+        }
+        if (token.type === "string") {
+            this.advance();
+            return { type: "literal", value: token.value };
+        }
+        if (token.type === "identifier") {
+            this.advance();
+            const normalized = token.value.toLowerCase();
+            if (normalized === "true")
+                return { type: "literal", value: true };
+            if (normalized === "false")
+                return { type: "literal", value: false };
+            if (normalized === "null")
+                return { type: "literal", value: null };
+            if (this.match("left_paren")) {
+                const args = [];
+                if (!this.check("right_paren")) {
+                    do {
+                        args.push(this.parseOr());
+                    } while (this.match("comma"));
+                }
+                this.consume("right_paren", "Expected ')' after function arguments.");
+                return { type: "call", name: token.value, args };
+            }
+            return { type: "identifier", name: token.value };
+        }
+        if (this.match("left_paren")) {
+            const node = this.parseOr();
+            this.consume("right_paren", "Expected ')' after expression.");
+            return node;
+        }
+        throw this.error("Expected expression.", token);
+    }
+    match(type) {
+        if (!this.check(type))
+            return false;
+        this.advance();
+        return true;
+    }
+    matchOperator(value) {
+        const token = this.current();
+        if (token.type !== "operator" || token.value !== value)
+            return false;
+        this.advance();
+        return true;
+    }
+    matchWord(value) {
+        const token = this.current();
+        if (token.type !== "identifier" || token.value.toLowerCase() !== value)
+            return false;
+        this.advance();
+        return true;
+    }
+    consume(type, message) {
+        if (this.match(type))
+            return;
+        throw this.error(message, this.current());
+    }
+    check(type) {
+        return this.current().type === type;
+    }
+    current() {
+        return this.tokens[this.index] ?? { type: "eof", position: this.expression.length };
+    }
+    advance() {
+        const token = this.current();
+        this.index += 1;
+        return token;
+    }
+    previousValue() {
+        const token = this.tokens[this.index - 1];
+        return token && "value" in token ? String(token.value) : "";
+    }
+    error(message, token) {
+        return formulaExpressionError(message, {
+            position: token.position,
+            expression: this.expression,
+        });
+    }
+}
+/**
+ * Consume `.field` and `[0]` segments after an identifier.
+ *
+ * A trailing dot is NOT consumed: `sum(a.)` should fail on the dot rather than
+ * producing an identifier `a.` that no scope can resolve, which would turn a typo
+ * into an unknown-identifier error pointing at the wrong thing.
+ */
+function readPathSuffix(expression, from) {
+    let index = from;
+    for (;;) {
+        const char = expression[index];
+        if (char === "." && /[A-Za-z0-9_]/.test(expression[index + 1] ?? "")) {
+            index += 2;
+            while (/[A-Za-z0-9_]/.test(expression[index] ?? ""))
+                index += 1;
+            continue;
+        }
+        if (char === "[") {
+            const close = expression.indexOf("]", index);
+            if (close === -1)
+                return index;
+            index = close + 1;
+            continue;
+        }
+        return index;
+    }
+}
+function tokenize(expression, options = {}) {
+    const tokens = [];
+    let index = 0;
+    while (index < expression.length) {
+        const char = expression[index] ?? "";
+        if (/\s/.test(char)) {
+            index += 1;
+            continue;
+        }
+        if (char === "(") {
+            tokens.push({ type: "left_paren", position: index });
+            index += 1;
+            continue;
+        }
+        if (char === ")") {
+            tokens.push({ type: "right_paren", position: index });
+            index += 1;
+            continue;
+        }
+        if (char === ",") {
+            tokens.push({ type: "comma", position: index });
+            index += 1;
+            continue;
+        }
+        if (char === "\"" || char === "'") {
+            const parsed = readStringLiteral(expression, index, char);
+            tokens.push({ type: "string", value: parsed.value, position: index });
+            index = parsed.nextIndex;
+            continue;
+        }
+        if (/\d/.test(char) || (char === "." && /\d/.test(expression[index + 1] ?? ""))) {
+            const parsed = readNumberLiteral(expression, index);
+            tokens.push({ type: "number", value: parsed.value, position: index });
+            index = parsed.nextIndex;
+            continue;
+        }
+        if (/[A-Za-z_]/.test(char)) {
+            const start = index;
+            index += 1;
+            while (/[A-Za-z0-9_]/.test(expression[index] ?? ""))
+                index += 1;
+            // Opt-in dotted paths. A table formula must tokenize BYTE-IDENTICALLY to
+            // before, so this is off by default: `a.b` there is still a syntax error, not
+            // a silently-different identifier. Workflow expressions turn it on so a
+            // formula can spell the same `steps.<id>.output.x` the ref and template
+            // bindings already use — without it the three binding kinds disagreed about
+            // how to name the same value.
+            if (options.paths === true)
+                index = readPathSuffix(expression, index);
+            tokens.push({ type: "identifier", value: expression.slice(start, index), position: start });
+            continue;
+        }
+        const twoChar = expression.slice(index, index + 2);
+        if (["<=", ">=", "==", "!=", "<>", "&&", "||"].includes(twoChar)) {
+            tokens.push({ type: "operator", value: twoChar, position: index });
+            index += 2;
+            continue;
+        }
+        if (["+", "-", "*", "/", "%", "<", ">", "=", "!"].includes(char)) {
+            tokens.push({ type: "operator", value: char, position: index });
+            index += 1;
+            continue;
+        }
+        throw formulaExpressionError("Unexpected character in formula expression.", {
+            position: index,
+            character: char,
+            expression,
+        });
+    }
+    tokens.push({ type: "eof", position: expression.length });
+    return tokens;
+}
+function readStringLiteral(expression, start, quote) {
+    let value = "";
+    let index = start + 1;
+    while (index < expression.length) {
+        const char = expression[index] ?? "";
+        if (char === quote)
+            return { value, nextIndex: index + 1 };
+        if (char === "\\") {
+            const escaped = expression[index + 1];
+            if (escaped === undefined)
+                break;
+            value += decodeEscapedCharacter(escaped);
+            index += 2;
+            continue;
+        }
+        value += char;
+        index += 1;
+    }
+    throw formulaExpressionError("Unterminated string literal.", {
+        position: start,
+        expression,
+    });
+}
+function decodeEscapedCharacter(char) {
+    switch (char) {
+        case "n":
+            return "\n";
+        case "r":
+            return "\r";
+        case "t":
+            return "\t";
+        default:
+            return char;
+    }
+}
+function readNumberLiteral(expression, start) {
+    let index = start;
+    while (/\d/.test(expression[index] ?? ""))
+        index += 1;
+    if (expression[index] === ".") {
+        index += 1;
+        while (/\d/.test(expression[index] ?? ""))
+            index += 1;
+    }
+    const raw = expression.slice(start, index);
+    const value = Number(raw);
+    if (!Number.isFinite(value)) {
+        throw formulaExpressionError("Invalid number literal.", {
+            position: start,
+            value: raw,
+            expression,
+        });
+    }
+    return { value, nextIndex: index };
+}

package/node_modules/@oxygen/formula/dist/formula-functions.d.ts

@@ -0,0 +1,71 @@
+import { OxygenError } from "@oxygen/shared/cli-result";
+/**
+ * Table-driven formula function registry. The tokenizer/parser/AST live in
+ * expression.ts and the evaluator in evaluate.ts; this module owns every
+ * callable function plus the value-coercion helpers the operators share.
+ * Adding a function is one registry entry + one test row — the discoverability surfaces
+ * (`/api/cli/tables/formulas/functions`, `oxygen formulas functions`,
+ * `oxygen_formulas_list`) all render from this metadata. Run conditions
+ * (`only run if`) evaluate through the same registry, so every function here
+ * is usable as a per-row execution gate too.
+ *
+ * Value semantics, kept uniform on purpose:
+ * - blank in (null/undefined/""/[]), null out for scalar transforms;
+ *   boolean predicates return false, `count`/`sum` return 0.
+ * - numeric functions coerce strings ("42") and throw on non-numeric input.
+ * - dates are UTC-only ISO-8601 strings; unparseable input yields null so
+ *   dirty enrichment data flows instead of failing a whole run.
+ */
+export type FormulaFunctionCategory = "logic" | "string" | "number" | "date" | "url_email" | "array" | "json" | "null_handling" | "cross_row";
+export type FormulaFunctionExample = {
+    expression: string;
+    result: unknown;
+};
+export type FormulaFunctionMeta = {
+    name: string;
+    category: FormulaFunctionCategory;
+    signature: string;
+    description: string;
+    minArgs: number;
+    /** null = variadic (no upper bound). */
+    maxArgs: number | null;
+    examples: FormulaFunctionExample[];
+};
+export type FormulaFunctionSpec = FormulaFunctionMeta & {
+    /** Lazy functions receive argument thunks so untaken branches never evaluate. */
+    lazy?: boolean;
+    evaluate?: (args: unknown[]) => unknown;
+    evaluateLazy?: (thunks: Array<() => unknown>) => unknown;
+};
+export declare const MAX_FORMULA_REGEX_PATTERN_LENGTH = 256;
+export declare const MAX_FORMULA_REGEX_INPUT_LENGTH = 20000;
+export declare function formulaExpressionError(message: string, details: Record<string, unknown>): OxygenError;
+export declare function isBlankFormulaValue(value: unknown): boolean;
+export declare function stringifyFormulaValue(value: unknown): string;
+export declare function readFormulaNumber(value: unknown, operator: string): number;
+export declare function toFormulaBoolean(value: unknown): boolean;
+export declare function compareFormulaValues(left: unknown, right: unknown): number;
+export declare function formulaValuesEqual(left: unknown, right: unknown): boolean;
+export declare function readFormulaJsonPath(value: unknown, rawPath: string): unknown;
+export declare function checkFormulaFunctionArity(spec: FormulaFunctionMeta, received: number): void;
+export declare const FORMULA_DATE_UNITS: readonly ["seconds", "minutes", "hours", "days", "weeks", "months", "years"];
+export declare const FORMULA_FUNCTION_REGISTRY: ReadonlyMap<string, FormulaFunctionSpec>;
+export declare const FORMULA_FUNCTION_CATEGORIES: readonly FormulaFunctionCategory[];
+export declare function listFormulaFunctions(category?: FormulaFunctionCategory): FormulaFunctionMeta[];
+/** Operators the expression language supports, for the discovery surfaces. */
+export declare const FORMULA_OPERATORS: readonly [{
+    readonly operator: "+ - * / %";
+    readonly description: "Arithmetic (numbers or numeric strings).";
+}, {
+    readonly operator: "= == != <>";
+    readonly description: "Equality (numbers compare numerically).";
+}, {
+    readonly operator: "< <= > >=";
+    readonly description: "Comparison (numbers numerically, text lexicographically).";
+}, {
+    readonly operator: "and or not (&& || !)";
+    readonly description: "Boolean logic with short-circuit evaluation.";
+}, {
+    readonly operator: "( )";
+    readonly description: "Grouping and function calls.";
+}];