@flexiberry/berrycore 0.1.0

package/dist/parser/ast/ast.engine.js

@@ -0,0 +1,526 @@
+/**
+ * AST Engine — Recursive Descent Parser
+ *
+ * Consumes Token[] from the LexerEngine and produces a ProgramNode AST.
+ * Each parse* method corresponds to one grammar rule from reader_v2.
+ *
+ * Architecture rules enforced:
+ *   - Parser ONLY produces AST — no runtime execution
+ *   - Deterministic recursive descent
+ *   - Throws syntax errors with line/column info
+ */
+import { LexerEngine } from "../tokenizer/reader/lexer.engine.js";
+import { TokenType } from "../tokenizer/tokenType.js";
+import { NodeType, } from "./ast.types.js";
+// ─── Parser Errors ──────────────────────────────────────────────────────────
+export class ParserError extends Error {
+    line;
+    column;
+    constructor(message, line, column) {
+        super(`[ParserError at ${line}:${column}] ${message}`);
+        this.line = line;
+        this.column = column;
+        this.name = "ParserError";
+    }
+}
+export class Ast {
+    static parse(code) {
+        const lexer = new LexerEngine(code);
+        const tokens = lexer.tokenize();
+        const engine = new AstEngine(tokens);
+        return engine.build();
+    }
+}
+// ─── Parser Engine ──────────────────────────────────────────────────────────
+export class AstEngine {
+    tokens;
+    cursor = 0;
+    constructor(tokens) {
+        this.tokens = tokens;
+    }
+    // ── Public API ──────────────────────────────────────────────────────────
+    /** Entry point: parse entire token stream into ProgramNode */
+    build() {
+        const body = [];
+        while (!this.isEof()) {
+            // Skip comments at top-level but collect them as nodes
+            if (this.check(TokenType.Comment)) {
+                body.push(this.parseComment());
+                continue;
+            }
+            const statement = this.parseStatement();
+            if (statement) {
+                body.push(statement);
+            }
+        }
+        return {
+            type: NodeType.Program,
+            position: { line: 0, column: 0 },
+            body,
+        };
+    }
+    // ── Statement Dispatch ──────────────────────────────────────────────────
+    parseStatement() {
+        if (this.check(TokenType.Var))
+            return this.parseVarDeclaration();
+        if (this.check(TokenType.Link))
+            return this.parseLinkStatement();
+        if (this.check(TokenType.Input))
+            return this.parseInputStatement();
+        if (this.check(TokenType.Api))
+            return this.parseApiBlock();
+        if (this.check(TokenType.Task))
+            return this.parseTaskBlock();
+        if (this.check(TokenType.Step))
+            return this.parseStepBlock();
+        if (this.check(TokenType.Params))
+            return this.parseParamsBlock();
+        if (this.check(TokenType.Capture))
+            return this.parseCaptureBlock();
+        if (this.check(TokenType.Check))
+            return this.parseCheckBlock();
+        if (this.check(TokenType.Comment))
+            return this.parseComment();
+        // Skip unrecognized tokens to avoid infinite loop
+        this.advance();
+        return null;
+    }
+    // ── Var Declaration ─────────────────────────────────────────────────────
+    /**
+     * Grammar: Var ((@)(pointed) (title))? keyValueLoop
+     * Tokens:  Var, optional Pointer+Pointed+Title, then key-value pairs
+     */
+    parseVarDeclaration() {
+        const varToken = this.expect(TokenType.Var, "Expected 'Var' keyword");
+        const position = this.positionOf(varToken);
+        let pointer = null;
+        let title = null;
+        // Check for pointer reference: @ followed by pointed name
+        if (this.check(TokenType.Pointer)) {
+            pointer = this.parsePointerReference();
+        }
+        // Check for title
+        if (this.check(TokenType.Title)) {
+            title = this.advance().value;
+        }
+        // Parse key-value entries
+        const entries = this.parseKeyValuePairs();
+        return {
+            type: NodeType.VarDeclaration,
+            position,
+            title,
+            pointer,
+            entries,
+        };
+    }
+    parsePointerReference() {
+        const pointerToken = this.expect(TokenType.Pointer, "Expected '@' pointer");
+        const position = this.positionOf(pointerToken);
+        const pointedToken = this.expect(TokenType.Pointed, "Expected pointed name after '@'");
+        return {
+            type: NodeType.PointerReference,
+            position,
+            symbol: pointerToken.value,
+            target: pointedToken.value,
+        };
+    }
+    // ── Link Statement ──────────────────────────────────────────────────────
+    /**
+     * Grammar: Link <path>
+     * Tokens:  Link, LinkPath
+     */
+    parseLinkStatement() {
+        const linkToken = this.expect(TokenType.Link, "Expected 'Link' keyword");
+        const position = this.positionOf(linkToken);
+        const pathToken = this.expect(TokenType.LinkPath, "Expected path after 'Link'");
+        return {
+            type: NodeType.LinkStatement,
+            position,
+            path: pathToken.value,
+        };
+    }
+    // ── Input Statement ──────────────────────────────────────────────────────
+    /**
+     * Grammar: Input <path>
+     * Tokens:  Input, InputPath
+     */
+    parseInputStatement() {
+        const inputToken = this.expect(TokenType.Input, "Expected 'Input' keyword");
+        const position = this.positionOf(inputToken);
+        const pathToken = this.expect(TokenType.InputPath, "Expected path after 'Input'");
+        return {
+            type: NodeType.InputStatement,
+            position,
+            path: pathToken.value,
+        };
+    }
+    // ── API Block ───────────────────────────────────────────────────────────
+    /**
+     * Grammar: Api (GET|POST|..)? #identifier title?
+     *          Url value
+     *          Header keyValueLoop
+     *          Body type `content`
+     */
+    parseApiBlock() {
+        const apiToken = this.expect(TokenType.Api, "Expected 'Api' keyword");
+        const position = this.positionOf(apiToken);
+        // Optional method
+        let method = null;
+        if (this.check(TokenType.ApiMethod)) {
+            method = this.advance().value;
+        }
+        // Hash + Identifier (API name)
+        if (this.check(TokenType.Hash)) {
+            this.advance(); // consume '#'
+        }
+        const nameToken = this.expect(TokenType.Identifier, "Expected API identifier after '#'");
+        const name = nameToken.value;
+        // Optional title
+        let title = null;
+        if (this.check(TokenType.Title)) {
+            title = this.advance().value;
+        }
+        // Parse sub-blocks: Url, Header, Body (in any order)
+        let url = null;
+        let headers = null;
+        let body = null;
+        while (this.check(TokenType.Url) ||
+            this.check(TokenType.Header) ||
+            this.check(TokenType.Body)) {
+            if (this.check(TokenType.Url)) {
+                url = this.parseUrlStatement();
+            }
+            else if (this.check(TokenType.Header)) {
+                headers = this.parseHeaderBlock();
+            }
+            else if (this.check(TokenType.Body)) {
+                body = this.parseBodyBlock();
+            }
+        }
+        return {
+            type: NodeType.ApiBlock,
+            position,
+            method,
+            name,
+            title,
+            url,
+            headers,
+            body,
+        };
+    }
+    parseUrlStatement() {
+        const urlToken = this.expect(TokenType.Url, "Expected 'Url' keyword");
+        const position = this.positionOf(urlToken);
+        const valueToken = this.expect(TokenType.Value, "Expected URL value after 'Url'");
+        return {
+            type: NodeType.UrlStatement,
+            position,
+            value: valueToken.value,
+        };
+    }
+    parseHeaderBlock() {
+        const headerToken = this.expect(TokenType.Header, "Expected 'Header' keyword");
+        const position = this.positionOf(headerToken);
+        const entries = this.parseKeyValuePairs();
+        return {
+            type: NodeType.HeaderBlock,
+            position,
+            entries,
+        };
+    }
+    parseBodyBlock() {
+        const bodyToken = this.expect(TokenType.Body, "Expected 'Body' keyword");
+        const position = this.positionOf(bodyToken);
+        const bodyTypeToken = this.expect(TokenType.BodyType, "Expected body type (e.g. 'json') after 'Body'");
+        // Expect backtick-wrapped content
+        let content = "";
+        if (this.check(TokenType.Backtick)) {
+            this.advance(); // opening backtick
+            if (this.check(TokenType.Scalar)) {
+                content = this.advance().value;
+            }
+            if (this.check(TokenType.Backtick)) {
+                this.advance(); // closing backtick
+            }
+        }
+        return {
+            type: NodeType.BodyBlock,
+            position,
+            bodyType: bodyTypeToken.value,
+            content,
+        };
+    }
+    // ── Task Block ──────────────────────────────────────────────────────────
+    /**
+     * Grammar: Task title?
+     * Tokens:  Task, Title
+     */
+    parseTaskBlock() {
+        const taskToken = this.expect(TokenType.Task, "Expected 'Task' keyword");
+        const position = this.positionOf(taskToken);
+        let title = null;
+        if (this.check(TokenType.Title)) {
+            title = this.advance().value;
+        }
+        // Collect Step blocks that follow this Task
+        const steps = [];
+        while (this.check(TokenType.Step)) {
+            steps.push(this.parseStepBlock());
+        }
+        return {
+            type: NodeType.TaskBlock,
+            position,
+            title,
+            steps,
+        };
+    }
+    // ── Step Block ──────────────────────────────────────────────────────────
+    /**
+     * Grammar: Step Call Api identifier
+     * Tokens:  Step, Call, Api, Identifier
+     */
+    parseStepBlock() {
+        const stepToken = this.expect(TokenType.Step, "Expected 'Step' keyword");
+        const position = this.positionOf(stepToken);
+        const callToken = this.expect(TokenType.Call, "Expected 'Call' after 'Step'");
+        const apiToken = this.expect(TokenType.Api, "Expected 'Api' after 'Call'");
+        const nameToken = this.expect(TokenType.Identifier, "Expected API name after 'Api'");
+        // Parse optional sub-blocks: Params, Capture, Check
+        let params = null;
+        let capture = null;
+        let check = null;
+        while (this.check(TokenType.Params) ||
+            this.check(TokenType.Capture) ||
+            this.check(TokenType.Check)) {
+            if (this.check(TokenType.Params)) {
+                params = this.parseParamsBlock();
+            }
+            else if (this.check(TokenType.Capture)) {
+                capture = this.parseCaptureBlock();
+            }
+            else if (this.check(TokenType.Check)) {
+                check = this.parseCheckBlock();
+            }
+        }
+        return {
+            type: NodeType.StepBlock,
+            position,
+            callType: callToken.value,
+            targetType: apiToken.value,
+            targetName: nameToken.value,
+            params,
+            capture,
+            check,
+        };
+    }
+    // ── Params Block ────────────────────────────────────────────────────────
+    /**
+     * Grammar: Params keyValueLoop
+     * Tokens:  Params, then key-value pairs
+     */
+    parseParamsBlock() {
+        const paramsToken = this.expect(TokenType.Params, "Expected 'Params' keyword");
+        const position = this.positionOf(paramsToken);
+        const entries = this.parseKeyValuePairs();
+        return {
+            type: NodeType.ParamsBlock,
+            position,
+            entries,
+        };
+    }
+    // ── Capture Block ───────────────────────────────────────────────────────
+    /**
+     * Grammar: Capture keyValueLoop
+     * Tokens:  Capture, then key-value pairs
+     */
+    parseCaptureBlock() {
+        const captureToken = this.expect(TokenType.Capture, "Expected 'Capture' keyword");
+        const position = this.positionOf(captureToken);
+        const entries = this.parseKeyValuePairs();
+        return {
+            type: NodeType.CaptureBlock,
+            position,
+            entries,
+        };
+    }
+    // ── Check Block ─────────────────────────────────────────────────────────
+    /**
+     * Grammar: Check conditionLoop
+     * Tokens:  Check, then condition list
+     */
+    parseCheckBlock() {
+        const checkToken = this.expect(TokenType.Check, "Expected 'Check' keyword");
+        const position = this.positionOf(checkToken);
+        const conditions = this.parseConditions();
+        return {
+            type: NodeType.CheckBlock,
+            position,
+            conditions,
+        };
+    }
+    // ── Key-Value Pairs ─────────────────────────────────────────────────────
+    /**
+     * Grammar: (- key: value)*
+     * Loops while Hyphen tokens appear
+     */
+    parseKeyValuePairs() {
+        const entries = [];
+        while (this.check(TokenType.Hyphen)) {
+            const hyphenToken = this.advance(); // consume '-'
+            const position = this.positionOf(hyphenToken);
+            let key = "";
+            let isKeyQuoted = false;
+            let value = "";
+            let isValueQuoted = false;
+            let isMultiline = false;
+            // Key: quoted or unquoted
+            if (this.check(TokenType.Quote)) {
+                isKeyQuoted = true;
+                this.advance(); // opening quote
+                if (this.check(TokenType.Identifier)) {
+                    key = this.advance().value;
+                }
+                if (this.check(TokenType.Quote)) {
+                    this.advance(); // closing quote
+                }
+            }
+            else if (this.check(TokenType.Identifier)) {
+                key = this.advance().value;
+            }
+            // Colon separator
+            if (this.check(TokenType.Colon)) {
+                this.advance();
+            }
+            // Value: quoted string, multiline backtick, or unquoted identifier
+            if (this.check(TokenType.Quote)) {
+                isValueQuoted = true;
+                this.advance(); // opening quote
+                if (this.check(TokenType.Scalar)) {
+                    value = this.advance().value;
+                }
+                if (this.check(TokenType.Quote)) {
+                    this.advance(); // closing quote
+                }
+            }
+            else if (this.check(TokenType.Backtick)) {
+                isMultiline = true;
+                this.advance(); // opening backtick
+                if (this.check(TokenType.Scalar)) {
+                    value = this.advance().value;
+                }
+                if (this.check(TokenType.Backtick)) {
+                    this.advance(); // closing backtick
+                }
+            }
+            else if (this.check(TokenType.Identifier)) {
+                value = this.advance().value;
+            }
+            let isEncrypted = false;
+            if (this.check(TokenType.Decrypt)) {
+                this.advance(); // consume 'Decrypt'
+                isEncrypted = true;
+            }
+            entries.push({
+                type: NodeType.KeyValuePair,
+                position,
+                key,
+                value,
+                isKeyQuoted,
+                isValueQuoted,
+                isMultiline,
+                isEncrypted,
+            });
+        }
+        return entries;
+    }
+    // ── Conditions ──────────────────────────────────────────────────────────
+    /**
+     * Grammar: (- lhs operator rhs (OR lhs operator rhs)*)*
+     * Loops while Hyphen tokens appear
+     */
+    parseConditions() {
+        const conditions = [];
+        while (this.check(TokenType.Hyphen)) {
+            const hyphenToken = this.advance(); // consume '-'
+            const position = this.positionOf(hyphenToken);
+            const lhs = this.expect(TokenType.Lhs, "Expected LHS in condition").value;
+            const operator = this.expect(TokenType.Operator, "Expected operator in condition").value;
+            const rhs = this.expect(TokenType.Rhs, "Expected RHS in condition").value;
+            // Parse OR chains
+            const orConditions = [];
+            while (this.check(TokenType.Or)) {
+                const orToken = this.advance(); // consume 'OR'
+                const orPos = this.positionOf(orToken);
+                const orLhs = this.expect(TokenType.Lhs, "Expected LHS after 'OR'").value;
+                const orOperator = this.expect(TokenType.Operator, "Expected operator after OR LHS").value;
+                const orRhs = this.expect(TokenType.Rhs, "Expected RHS after OR operator").value;
+                orConditions.push({
+                    type: NodeType.BinaryExpression,
+                    position: orPos,
+                    lhs: orLhs,
+                    operator: orOperator,
+                    rhs: orRhs,
+                });
+            }
+            conditions.push({
+                type: NodeType.Condition,
+                position,
+                lhs,
+                operator,
+                rhs,
+                orConditions,
+            });
+        }
+        return conditions;
+    }
+    // ── Comment ─────────────────────────────────────────────────────────────
+    parseComment() {
+        const commentToken = this.expect(TokenType.Comment, "Expected comment text");
+        return {
+            type: NodeType.Comment,
+            position: this.positionOf(commentToken),
+            text: commentToken.value,
+        };
+    }
+    // ── Token Helpers ─────────────────────────────────────────────────────
+    /** Check if we've reached EOF */
+    isEof() {
+        return (this.cursor >= this.tokens.length ||
+            this.tokens[this.cursor].type === TokenType.Eof);
+    }
+    /** Peek at current token without consuming */
+    peek() {
+        return this.tokens[this.cursor];
+    }
+    /** Check if current token matches expected type */
+    check(type) {
+        if (this.isEof())
+            return false;
+        return this.peek().type === type;
+    }
+    /** Consume current token and return it */
+    advance() {
+        const token = this.tokens[this.cursor];
+        this.cursor++;
+        return token;
+    }
+    /** Expect a specific token type or throw a ParserError */
+    expect(type, errorMessage) {
+        if (this.isEof()) {
+            const lastToken = this.tokens[this.tokens.length - 1];
+            throw new ParserError(`${errorMessage} — unexpected end of input`, lastToken?.position.line ?? 0, lastToken?.position.start ?? 0);
+        }
+        const token = this.peek();
+        if (token.type !== type) {
+            throw new ParserError(`${errorMessage} — got '${TokenType[token.type]}' (${token.value})`, token.position.line ?? 0, token.position.start);
+        }
+        return this.advance();
+    }
+    /** Extract NodePosition from a Token */
+    positionOf(token) {
+        return {
+            line: token.position.line ?? 0,
+            column: token.position.start,
+        };
+    }
+}